initiative/specs/009-combatant-hp/quickstart.md

Quickstart: Combatant HP Tracking

Feature: 009-combatant-hp | Date: 2026-03-05

Overview

This feature adds optional health point (HP) tracking to combatants. Each combatant can optionally have a max HP and current HP. Both HP fields are always visible per combatant row (current HP disabled until max HP is set). The current HP is adjusted via +/- controls or direct entry, always clamped to [0, maxHp]. When max HP changes and the combatant is at full health, current HP stays synced.

Implementation Order

1. Domain types — Extend Combatant interface with optional maxHp and currentHp. Add new event types to events.ts.

2. Domain functions — Implement setHp (set/clear max HP) and adjustHp (apply delta to current HP) as pure functions following the existing pattern in edit-combatant.ts.

3. Domain tests — Write tests for both domain functions covering acceptance scenarios, invariants, error cases, and edge cases.

4. Application use cases — Create setHpUseCase and adjustHpUseCase following the existing get-call-save pattern.

5. Persistence — Extend loadEncounter() validation to handle optional maxHp/currentHp fields on combatants.

6. Web hook — Add setHp and adjustHp callbacks to useEncounter.

7. UI components — Add HP controls to combatant rows in App.tsx: both Current HP and Max HP inputs always visible (Current HP disabled until Max HP is set), +/- buttons shown only when HP tracking is active, direct current HP entry.

Key Files to Modify

File	Change
packages/domain/src/types.ts	Add optional maxHp and currentHp to Combatant
packages/domain/src/events.ts	Add MaxHpSet and CurrentHpAdjusted event types
packages/domain/src/set-hp.ts	New file: pure function for setting max HP
packages/domain/src/adjust-hp.ts	New file: pure function for adjusting current HP
packages/domain/src/index.ts	Re-export new functions
packages/application/src/set-hp-use-case.ts	New file: set HP use case
packages/application/src/adjust-hp-use-case.ts	New file: adjust HP use case
packages/application/src/index.ts	Re-export new use cases
apps/web/src/hooks/use-encounter.ts	Add setHp/adjustHp callbacks
apps/web/src/persistence/encounter-storage.ts	Validate HP fields on load
apps/web/src/App.tsx	HP controls in combatant rows

Development Commands

pnpm test                          # Run all tests
pnpm vitest run packages/domain/src/__tests__/set-hp.test.ts   # Single test
pnpm check                         # Full quality gate
pnpm --filter web dev              # Dev server