initiative/specs/014-inline-hp-delta/spec.md

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.