initiative/specs/011-quick-hp-input/quickstart.md

Quickstart: Quick HP Input

What this feature does

Adds an inline damage/heal numeric input to each combatant row. Instead of editing the absolute HP value, the game master types a number (e.g., "7") and the system applies it as damage (subtract) or healing (add) to the combatant's current HP.

Key files to modify

1. apps/web/src/components/quick-hp-input.tsx (NEW) -- The main component: numeric input + damage/heal mode toggle.
2. apps/web/src/components/combatant-row.tsx (MODIFY) -- Integrate QuickHpInput into the combatant row layout alongside existing HP display.

Key files to understand (read-only)

• packages/domain/src/adjust-hp.ts -- Domain function that applies signed deltas (negative = damage, positive = heal)
• packages/domain/src/types.ts -- Combatant type with optional maxHp/currentHp
• apps/web/src/hooks/use-encounter.ts -- adjustHp(id, delta) hook already exposed
• apps/web/src/components/ui/input.tsx -- Base input component for consistent styling
• apps/web/src/components/ui/button.tsx -- Base button component for toggle

How the pieces connect

QuickHpInput (new component)
  |-- User types "7" in damage mode, presses Enter
  |-- Calls onAdjustHp(combatantId, -7)
  |
CombatantRow
  |-- Passes onAdjustHp prop to QuickHpInput
  |
useEncounter hook
  |-- adjustHp(id, delta) -> adjustHpUseCase -> domain adjustHp()
  |-- Domain clamps result to [0, maxHp]
  |-- State updates, localStorage persists

Running the feature locally

pnpm --filter web dev    # Start Vite dev server at localhost:5173

Running tests

pnpm check               # Full quality gate (format + lint + typecheck + test)
pnpm test                # All tests

No new domain tests needed -- adjustHp is already fully tested. New tests (if any) would be component-level tests for QuickHpInput keyboard behavior and mode toggling.