initiative/specs/018-combatant-concentration/quickstart.md

Quickstart: Combatant Concentration

Feature: 018-combatant-concentration | Date: 2026-03-06

Overview

This feature adds a per-combatant boolean isConcentrating state with a Brain icon toggle, a colored left border accent for visual identification, and a pulse animation when a concentrating combatant takes damage.

Key Files to Modify

Domain Layer

1. packages/domain/src/types.ts — Add isConcentrating?: boolean to Combatant interface.
2. packages/domain/src/events.ts — Add ConcentrationStarted and ConcentrationEnded event types to the DomainEvent union.
3. packages/domain/src/toggle-concentration.ts (new) — Pure function mirroring toggle-condition.ts pattern.
4. packages/domain/src/index.ts — Re-export new function and event types.

Application Layer

5. packages/application/src/toggle-concentration-use-case.ts (new) — Thin orchestration following toggle-condition-use-case.ts pattern.
6. packages/application/src/index.ts — Re-export new use case.

Web Adapter

7. apps/web/src/persistence/encounter-storage.ts — Add isConcentrating to combatant rehydration.
8. apps/web/src/hooks/use-encounter.ts — Add toggleConcentration callback.
9. apps/web/src/components/combatant-row.tsx — Add Brain icon toggle, left border accent, and pulse animation.
10. apps/web/src/App.tsx — Wire onToggleConcentration prop through to CombatantRow.

Implementation Pattern

Follow the existing toggleCondition pattern end-to-end:

Domain:    toggleConcentration(encounter, combatantId) → { encounter, events } | DomainError
App:       toggleConcentrationUseCase(store, combatantId) → events | DomainError
Hook:      toggleConcentration = useCallback((id) => { ... toggleConcentrationUseCase(makeStore(), id) ... })
Component: <Brain onClick={() => onToggleConcentration(id)} />

Testing Strategy

• Domain tests: toggle-concentration.test.ts — toggle on/off, combatant not found, immutability, correct events emitted.
• UI behavior: Manual verification of hover show/hide, tooltip, left border accent, pulse animation on damage.

Key Decisions

• Concentration is not a condition — it has its own boolean field and separate UI treatment.
• Pulse animation uses CSS keyframes triggered by transient React state, not a domain event.
• Damage detection for pulse uses HP comparison in the component (prevHp vs currentHp), not domain events.
• No localStorage migration needed — optional boolean field is backward-compatible.