4.0 KiB
Implementation Plan: Quick HP Input
Branch: 011-quick-hp-input | Date: 2026-03-05 | Spec: spec.md
Input: Feature specification from /specs/011-quick-hp-input/spec.md
Summary
Add an always-visible inline quick HP input per combatant that allows the game master to type a damage or healing number and immediately apply it as a delta to current HP. The domain layer already provides adjustHp(encounter, combatantId, delta) with full clamping logic, so no domain or application changes are needed. This is a UI-only feature: a new QuickHpInput component in the web adapter layer with damage/heal mode toggle, keyboard-driven workflow, and clear visual distinction between modes.
Technical Context
Language/Version: TypeScript 5.8 (strict mode, verbatimModuleSyntax)
Primary Dependencies: React 19, Vite 6, Tailwind CSS v4, shadcn/ui-style components, Lucide React (icons)
Storage: N/A (no storage changes -- existing localStorage persistence handles HP via adjustHpUseCase)
Testing: Vitest (domain pure-function tests); UI component tested via existing patterns
Target Platform: Browser (single-user, local-first)
Project Type: Web application (monorepo: packages/domain, packages/application, apps/web)
Performance Goals: N/A (single-user, instant local state updates)
Constraints: Must follow layered architecture (domain -> application -> adapters); UI-only changes in apps/web
Scale/Scope: Single combatant row component enhancement
Constitution Check
GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.
| Principle | Status | Notes |
|---|---|---|
| I. Deterministic Domain Core | PASS | No domain changes. Existing adjustHp is a pure function. |
| II. Layered Architecture | PASS | All changes are in the adapter layer (apps/web). Domain and application layers unchanged. |
| III. Agent Boundary | N/A | No agent features involved. |
| IV. Clarification-First | PASS | Clarifications completed in spec (visibility model, direct entry coexistence). |
| V. Escalation Gates | PASS | All requirements are in the spec. |
| VI. MVP Baseline Language | PASS | Exclusions use "MVP baseline does not include" phrasing. |
| VII. No Gameplay Rules | PASS | No gameplay mechanics in constitution. |
Project Structure
Documentation (this feature)
specs/011-quick-hp-input/
├── spec.md
├── plan.md # This file
├── research.md # Phase 0 output
├── data-model.md # Phase 1 output
├── quickstart.md # Phase 1 output
└── tasks.md # Phase 2 output (via /speckit.tasks)
Source Code (repository root)
apps/web/src/
├── components/
│ ├── combatant-row.tsx # Modified: integrate QuickHpInput
│ ├── quick-hp-input.tsx # NEW: inline damage/heal input component
│ └── ui/
│ ├── button.tsx # Existing (may use for toggle)
│ └── input.tsx # Existing (base input styling)
├── hooks/
│ └── use-encounter.ts # Unchanged (adjustHp already exposed)
└── App.tsx # Unchanged (props already passed through)
packages/domain/src/
├── adjust-hp.ts # Unchanged (already supports +/- deltas)
├── set-hp.ts # Unchanged
├── types.ts # Unchanged
└── __tests__/
└── adjust-hp.test.ts # Unchanged (domain logic covered)
packages/application/src/
├── adjust-hp-use-case.ts # Unchanged
└── ports.ts # Unchanged
Structure Decision: UI-only change. Single new component (quick-hp-input.tsx) added to the existing component directory. combatant-row.tsx modified to integrate it alongside the existing direct HP entry. No new directories needed.
Complexity Tracking
No violations to justify. All changes are within the existing adapter layer, using established patterns.