# Feature Specification: Inline HP Delta Input **Feature Branch**: `014-inline-hp-delta` **Created**: 2026-03-05 **Status**: Draft **Input**: User description: "change the quick hp input to be an inline HP delta input per combatant. Users type a number and press Enter to apply damage by default, or click small damage/heal buttons to apply the value explicitly. Clear the input after applying. No toggle for damage and heal anymore." ## User Scenarios & Testing ### User Story 1 - Apply Damage via Enter Key (Priority: P1) As a game master in the heat of combat, I want to type a damage number and press Enter to immediately subtract it from a combatant's HP, so that damage application is as fast as possible with minimal interaction. **Why this priority**: Damage is the most frequent HP change during combat. Enter-to-damage is the fastest possible workflow for the most common action. **Independent Test**: Can be fully tested by having a combatant with HP, typing a number, pressing Enter, and verifying HP decreases. **Acceptance Scenarios**: 1. **Given** a combatant has 20/20 HP, **When** the user types 7 into the delta input and presses Enter, **Then** current HP decreases to 13. 2. **Given** a combatant has 10/20 HP, **When** the user types 15 and presses Enter, **Then** current HP is clamped to 0 (not negative). 3. **Given** a combatant has 20/20 HP, **When** the user types a number and presses Enter, **Then** the input field clears and is ready for the next entry. 4. **Given** a combatant has 5/20 HP, **When** the user types 0 and presses Enter, **Then** the input is rejected and HP remains unchanged. --- ### User Story 2 - Apply Damage or Heal via Explicit Buttons (Priority: P1) As a game master, I want small damage and heal buttons next to the input so that I can explicitly choose whether to apply the entered value as damage or healing. **Why this priority**: While Enter defaults to damage, users still need a way to heal. Explicit buttons remove ambiguity and eliminate the need for a mode toggle. **Independent Test**: Can be fully tested by typing a number and clicking the heal button, verifying HP increases. **Acceptance Scenarios**: 1. **Given** a combatant has 10/20 HP and the user has typed 5, **When** the user clicks the heal button, **Then** current HP increases to 15 and the input clears. 2. **Given** a combatant has 18/20 HP and the user has typed 10, **When** the user clicks the heal button, **Then** current HP is clamped to 20 (max HP) and the input clears. 3. **Given** a combatant has 20/20 HP and the user has typed 7, **When** the user clicks the damage button, **Then** current HP decreases to 13 and the input clears. 4. **Given** a combatant has 0/20 HP and the user has typed 8, **When** the user clicks the heal button, **Then** current HP increases to 8 and the input clears. --- ### User Story 3 - Keyboard-Driven Workflow (Priority: P2) As a game master, I want to use only the keyboard to apply damage quickly so that I can keep up with fast-paced combat without reaching for the mouse. **Why this priority**: Speed is critical during combat encounters. The keyboard workflow should cover the most common action (damage) end-to-end. **Independent Test**: Can be fully tested by using only keyboard interactions to apply damage values. **Acceptance Scenarios**: 1. **Given** the delta input is focused, **When** the user types a number and presses Enter, **Then** damage is applied immediately and the input clears. 2. **Given** the delta input is focused, **When** the user presses Escape, **Then** the input value is cleared without applying any change. --- ### Edge Cases - What happens when the user enters a non-numeric value? The input only accepts digits; non-numeric characters are rejected. - What happens when the user enters a very large number (e.g., 99999)? The value is applied normally; clamping to 0 or max HP ensures no invalid state. - What happens when the combatant has no HP tracking (no max HP set)? The delta input is not shown for that combatant. - What happens when the user submits an empty input? No change is applied; the input remains ready for the next entry. - What happens when the user clicks a button with an empty input? No change is applied. - What happens when the user rapidly enters multiple values? Each entry is applied sequentially; no values are lost or merged. ## Requirements ### Functional Requirements - **FR-001**: The system MUST provide an inline numeric input per combatant for entering HP delta amounts. - **FR-002**: When the user types a number and presses Enter, the system MUST apply the value as damage (subtract from current HP), clamping to 0. - **FR-003**: The system MUST provide a small damage button that applies the entered value as damage (subtract from current HP), clamping to 0. - **FR-004**: The system MUST provide a small heal button that applies the entered value as healing (add to current HP), clamping to max HP. - **FR-005**: After any value is applied (via Enter or button click), the input MUST clear automatically. - **FR-006**: The input MUST only accept positive integers. Zero, negative numbers, and non-numeric input MUST be rejected. - **FR-007**: Pressing Escape while the input is focused MUST clear the input value without applying any change. - **FR-008**: The delta input MUST only be available for combatants that have HP tracking active (max HP is set). - **FR-009**: There MUST NOT be a toggle between damage and heal modes. The input is mode-free; the action is determined by which button is clicked or by pressing Enter (which defaults to damage). - **FR-010**: Direct editing of the current HP absolute value MUST remain available alongside the delta input. - **FR-011**: The damage and heal buttons MUST be visually distinct from each other (e.g., different colors or icons). ### Key Entities - **HP Delta**: A numeric value entered by the user, applied as either damage or healing to a combatant's current HP. ## Success Criteria ### Measurable Outcomes - **SC-001**: A user can apply damage to a combatant in 2 interactions or fewer (type number + press Enter). - **SC-002**: A user can apply healing to a combatant in 3 interactions or fewer (type number + click heal button). - **SC-003**: Current HP never exceeds max HP or drops below 0 after any delta input operation. - **SC-004**: No mode toggle exists in the interface -- damage and heal are always available as distinct actions. ## Assumptions - This feature replaces the existing quick HP input (011-quick-hp-input) which used a damage/heal mode toggle. The toggle is removed in favor of explicit actions. - Enter key defaults to damage because damage is the most frequent HP change during combat. - Direct HP entry (absolute value) remains available for overrides and corrections. - There is no undo/redo for HP changes in the MVP baseline. - There is no damage type tracking (fire, slashing, etc.) in the MVP baseline. - There is no hit log or damage history in the MVP baseline.