initiative/specs/017-combat-conditions/quickstart.md

Quickstart: Combat Conditions

Prerequisites

pnpm install          # install dependencies (no new packages needed)
pnpm --filter web dev # start dev server at localhost:5173

Implementation Order

1. Domain: Condition types & registry (packages/domain/src/conditions.ts)

   • Define ConditionId union type and ConditionDefinition interface
   • Create CONDITION_DEFINITIONS static array with all 15 entries
   • Export VALID_CONDITION_IDS set for validation

2. Domain: Extend Combatant (packages/domain/src/types.ts)

   • Add readonly conditions?: readonly ConditionId[] to Combatant

3. Domain: Events (packages/domain/src/events.ts)

   • Add ConditionAdded and ConditionRemoved event types
   • Add to DomainEvent union

4. Domain: Operations (packages/domain/src/toggle-condition.ts)

   • toggleCondition(encounter, combatantId, conditionId) — add if absent, remove if present
   • Maintains sorted order and emits ConditionAdded or ConditionRemoved event

5. Domain: Tests (packages/domain/src/__tests__/)

   • Test toggle on/off, ordering, duplicate prevention, unknown condition rejection, immutability

6. Application: Use case (packages/application/src/)

   • toggleConditionUseCase following setAcUseCase pattern

7. Web: Persistence (apps/web/src/persistence/encounter-storage.ts)

   • Add conditions rehydration with validation against VALID_CONDITION_IDS

8. Web: Components (apps/web/src/components/)

   • condition-tags.tsx — renders icon tags + "+" button
   • condition-picker.tsx — popover with all 15 conditions for toggling
   • Update combatant-row.tsx to include condition area below name

9. Web: Hook (apps/web/src/hooks/use-encounter.ts)

   • Add toggleCondition callback

Verification

pnpm check   # must pass: knip + format + lint + typecheck + test

Key Patterns to Follow

• Domain operations: See packages/domain/src/set-ac.ts for the exact pattern
• Use cases: See packages/application/src/set-ac-use-case.ts
• UI components: See combatant-row.tsx AcInput for inline editing pattern
• Persistence: See encounter-storage.ts AC validation for rehydration pattern
• Hook integration: See use-encounter.ts setAc callback for wiring pattern