Files

Lukas 46b444caba Refactor combatant row: single-click rename, book icon for stat blocks

Replace 250ms click timer and double-click detection with immediate
single-click rename for all combatant types. Add a BookOpen icon before
the name on bestiary rows as the dedicated stat block trigger. Remove
auto-show stat block on turn advance. Update specs to match: consistent
collapse/expand terminology, book icon requirements, no row-click stat
block behavior.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-16 11:14:28 +01:00

39 KiB

Raw Permalink Blame History

Feature Specification: Combatant State

Feature Branch: 003-combatant-state Created: 2026-03-03 Status: Implemented

Overview

Combatant State covers all per-combatant data tracked during an encounter: hit points, armor class, conditions, concentration, and initiative.

Structure: This spec is organized by topic area. Each topic section contains its own user scenarios, requirements, and edge cases. The Combatant Row Layout section covers cross-cutting UI concerns.

Domain Model Reference

interface Combatant {
  readonly id: CombatantId;          // branded string
  readonly name: string;
  readonly initiative?: number;       // integer, undefined = unset
  readonly maxHp?: number;            // positive integer
  readonly currentHp?: number;        // 0..maxHp
  readonly ac?: number;               // non-negative integer
  readonly conditions?: readonly ConditionId[];
  readonly isConcentrating?: boolean;
  readonly creatureId?: CreatureId;   // link to bestiary entry
}

Hit Points

User Stories

Story HP-1 — Set Max HP (P1) As a game master, I want to assign a maximum HP value to a combatant so that I can track their health during the encounter.

Acceptance scenarios:

Given a combatant exists, When the user sets max HP to a positive integer, Then the combatant's max HP is stored and current HP defaults to that value.
Given a combatant has max HP 20 and current HP 20, When the user lowers max HP to 15, Then current HP is clamped to 15.
Given a combatant has max HP 20 and current HP 20 (full health), When the user increases max HP to 30, Then current HP increases to 30 (stays at full).
Given a combatant has max HP 20 and current HP 12 (not full), When the user increases max HP to 30, Then current HP remains at 12.
Given the max HP inline edit is active, When the user clears the field and confirms, Then max HP is unset and HP tracking is removed entirely.

Story HP-2 — Apply HP Delta (P1) As a game master in the heat of combat, I want to type a damage or healing number and immediately apply it to a combatant's HP so that I can keep up with fast-paced encounters without mental arithmetic.

Acceptance scenarios:

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.
Given a combatant has 10/20 HP, When the user types 15 and presses Enter, Then current HP is clamped to 0.
Given a combatant has 10/20 HP and types 5 then clicks the heal button, Then current HP increases to 15.
Given a combatant has 18/20 HP and types 10 then clicks the heal button, Then current HP is clamped to 20.
Given any confirmed delta, Then the input field clears automatically and is ready for the next entry.
Given the user types 0 and presses Enter, Then the input is rejected and HP remains unchanged.
Given the delta input is focused and the user presses Escape, Then the input clears without applying any change.

Story HP-3 — Click-to-Adjust Popover (P1) As a DM running combat, I want to click on a combatant's current HP value to open a small adjustment popover so that the combatant row is visually clean and I can still quickly apply damage or healing when needed.

Acceptance scenarios:

Given a combatant with max HP set, When viewing the row at rest, Then only the current HP number and max HP are visible — no delta input or action buttons.
Given a combatant with max HP set, When the user clicks the current HP number, Then a small popover opens with an auto-focused numeric input and Damage/Heal buttons.
Given the HP popover is open with a valid number, When the user presses Enter, Then damage is applied and the popover closes.
Given the HP popover is open with a valid number, When the user presses Shift+Enter, Then healing is applied and the popover closes.
Given the HP popover is open, When the user presses Escape, Then the popover closes without changes.
Given the HP popover is open, When the user clicks outside, Then the popover closes without changes.
Given a combatant with no max HP set, When viewing the row, Then the HP area shows only the max HP clickable placeholder — no current HP value.

Story HP-4 — Direct HP Entry (P2) As a game master, I want to type a specific absolute current HP value directly so I can apply large corrections in one action.

Acceptance scenarios:

Given a combatant has max HP 50, When the user types 35 into the current HP field, Then current HP is set to 35.
Given a combatant has max HP 50, When the user types 60, Then current HP is clamped to 50.
Given a combatant has max HP 50, When the user types -5, Then current HP is clamped to 0.

Story HP-5 — HP Status Indicators (P1) As a game master, I want to see at a glance which combatants are bloodied or unconscious so I can narrate the battle and make tactical decisions without mental math.

Acceptance scenarios:

Given a combatant has max HP 20 and current HP 10 (at half), Then no bloodied indicator is shown (10 is not less than 20/2 = 10).
Given a combatant has max HP 20 and current HP 9 (below half), Then the bloodied indicator is visible (amber color treatment on HP value).
Given a combatant has max HP 21 and current HP 10 (below 10.5), Then the bloodied indicator is shown.
Given a combatant has max HP 20 and current HP 0, Then the unconscious/dead indicator is shown (red color; row visually muted).
Given a combatant at 0 HP is healed above 0, Then the unconscious indicator is removed and the correct status is applied.
Given a combatant has no max HP set, Then no status indicator is shown.
Given a combatant at full HP 20/20, When 11 damage is dealt (-> 9/20), Then the indicator transitions to bloodied.
Given a bloodied combatant 5/20, When 5 damage is dealt (-> 0/20), Then the indicator transitions to unconscious/dead.
Given an unconscious combatant 0/20, When 15 HP is healed (-> 15/20), Then the indicator transitions directly to healthy (skips bloodied since 15 > 10).

Story HP-6 — HP Persists Across Reloads (P2) As a game master, I want HP values to survive page reloads so that I do not lose health tracking mid-session.

Acceptance scenarios:

Given a combatant has max HP 30 and current HP 18, When the page is reloaded, Then both values are restored exactly.

Requirements

FR-001: Each combatant MAY have an optional maxHp value (positive integer >= 1). HP tracking is optional per combatant.
FR-002: When maxHp is first set, currentHp MUST default to maxHp.
FR-003: currentHp MUST be clamped to [0, maxHp] at all times.
FR-004: The system MUST provide an inline HP delta input per combatant (hidden behind a click-to-open popover on the current HP value).
FR-005: The HP popover MUST contain a single auto-focused numeric input and Damage and Heal action buttons.
FR-006: Pressing Enter in the popover MUST apply the entered value as damage; Shift+Enter MUST apply it as healing; Escape MUST dismiss without change; clicking outside MUST dismiss without change.
FR-007: When a damage value is confirmed, the system MUST subtract the entered amount from currentHp, clamping to 0.
FR-008: When a healing value is confirmed, the system MUST add the entered amount to currentHp, clamping to maxHp.
FR-009: After any delta is applied, the input MUST clear automatically.
FR-010: The delta input MUST only accept positive integers. Zero, negative, and non-numeric values MUST be rejected.
FR-011: Direct editing of the absolute currentHp value MUST remain available alongside the delta input.
FR-012: maxHp MUST display as compact static text with click-to-edit. The value is committed on Enter or blur; Escape cancels. Intermediate editing (clearing the field to retype) MUST NOT affect currentHp until committed.
FR-013: When maxHp is reduced below currentHp, currentHp MUST be clamped to the new maxHp.
FR-014: When maxHp increases and the combatant was at full health, currentHp MUST increase to match the new maxHp.
FR-015: When maxHp increases and the combatant was NOT at full health, currentHp MUST remain unchanged (unless clamped by FR-013).
FR-016: maxHp MUST reject zero, negative, and non-integer values.
FR-017: HP values MUST persist across page reloads via the existing persistence mechanism.
FR-018: The HP status MUST be derived as a pure domain computation: healthy (currentHp >= maxHp / 2), bloodied (0 < currentHp < maxHp / 2), unconscious (currentHp <= 0). The status is not stored — computed on demand.
FR-019: The HP area MUST display the bloodied color treatment (amber) on the current HP value when status is bloodied.
FR-020: The HP area MUST display the unconscious color treatment (red) and the combatant row MUST appear visually muted when status is unconscious.
FR-021: Status indicators MUST NOT be shown when maxHp is not set.
FR-022: Visual status indicators MUST update within the same interaction frame as the HP change — no perceptible delay.

Edge Cases

maxHp of 1: at 1/1 the combatant is healthy; at 0/1 unconscious. No bloodied state is possible.
maxHp of 2: at 1/2 the combatant is healthy (1 is not strictly less than 1); at 0/2 unconscious.
When maxHp is cleared, currentHp is also cleared; the combatant returns to the no-HP state.
Entering a non-numeric value in any HP field is rejected; the previous value is preserved.
Entering a very large number (e.g., 99999) is applied normally; clamping prevents invalid state.
Submitting an empty delta input applies no change; the input remains ready.
When the user rapidly applies multiple deltas, each is applied sequentially; none are lost.
HP tracking is entirely absent for combatants with no maxHp set — no HP controls are shown.
There is no temporary HP in the MVP baseline.
There is no death/unconscious game mechanic triggered at 0 HP; the system displays the state only.
There is no damage type tracking, resistance/vulnerability calculation, or hit log in the MVP baseline.
There is no undo/redo for HP changes in the MVP baseline.

Armor Class

User Stories

Story AC-1 — Set and Display AC (P1) As a game master, I want to assign an Armor Class value to a combatant and see it displayed as a shield shape so I can reference it at a glance during combat.

Acceptance scenarios:

Given a combatant exists, When the user clicks the AC shield area and enters 17, Then the combatant's AC is stored and the shield shape displays "17".
Given a combatant with AC 15, When viewing the row, Then the AC number is displayed inside a shield-shaped outline (not a separate icon + number).
Given a combatant with no AC set, When viewing the row, Then the shield shape is shown in an empty/placeholder state.
Given multiple combatants with different AC values, When viewing the encounter list, Then each displays its own correct AC.

Story AC-2 — Edit AC (P2) As a game master, I want to edit an existing combatant's AC inline so I can correct or update it without navigating away.

Acceptance scenarios:

Given a combatant with AC 15, When the user clicks the shield, Then an inline input appears pre-filled with 15 and selected.
Given the inline AC edit is active, When the user types 18 and presses Enter, Then AC updates to 18 and the display returns to static mode.
Given the inline AC edit is active, When the user blurs, Then AC is committed and the display returns to static mode.
Given the inline AC edit is active, When the user presses Escape, Then the edit is cancelled and the original value is preserved.
Given the inline AC edit is active, When the user clears the field and presses Enter, Then AC is unset and the shield shows an empty state.

Requirements

FR-023: Each combatant MAY have an optional ac value, a non-negative integer (>= 0).
FR-024: AC MUST be displayed inside a shield-shaped visual element. The separate shield icon is replaced by the shield shape itself.
FR-025: The shield shape MUST be shown in all cases (set, unset/empty state). No AC value means an empty-state shield, not hidden.
FR-026: Clicking the shield MUST open an inline edit input with the current value pre-filled and selected.
FR-027: The inline AC edit MUST commit on Enter or blur and cancel on Escape.
FR-028: Clearing the AC field and confirming MUST unset AC.
FR-029: AC MUST reject negative values. Zero is a valid AC.
FR-030: AC values MUST persist via the existing persistence mechanism.
FR-031: The AC shield MUST scale appropriately for single-digit, double-digit, and any valid AC values.

Edge Cases

AC 0 is valid and MUST be displayed.
Negative AC is not accepted; the input is rejected.
MVP baseline does not include AC-based calculations (to-hit comparisons, conditional formatting based on AC thresholds).

Conditions & Concentration

User Stories

Story CC-1 — Add a Condition (P1) As a DM running an encounter, I want to quickly apply a condition to a combatant so I can track status effects during combat.

Acceptance scenarios:

Given a combatant row is not hovered and has no conditions, Then no condition UI is visible.
Given a combatant row is hovered, When no conditions are active, Then a "+" button appears inline after the creature name.
Given the "+" button is visible, When the user clicks it, Then a compact condition picker opens showing all 15 conditions as icon + label pairs.
Given the picker is open, When the user clicks a condition, Then it is toggled on and its icon appears inline after the creature name.
Given the picker is open with active conditions already marked, When viewing the picker, Then active conditions are visually distinguished from inactive ones.

Story CC-2 — Remove a Condition (P1) As a DM, I want to remove a condition from a combatant when the effect ends so the tracker stays accurate.

Acceptance scenarios:

Given a combatant has active conditions, When the user clicks an active condition icon tag inline, Then the condition is removed and the icon disappears.
Given the condition picker is open, When the user clicks an active condition, Then it is toggled off and removed from the row.
Given a combatant with one condition and it is removed, Then only the hover-revealed "+" button remains.

Story CC-3 — View Condition Name via Tooltip (P2) As a DM, I want to hover over a condition icon to see its name so I can identify conditions without memorizing icons.

Acceptance scenarios:

Given a combatant has an active condition, When the user hovers over its icon, Then a tooltip shows the condition name (e.g., "Blinded").
Given the user moves the cursor away from the icon, Then the tooltip disappears.

Story CC-4 — Multiple Conditions (P2) As a DM, I want to apply multiple conditions to a single combatant so I can track complex combat situations.

Acceptance scenarios:

Given a combatant with one condition, When another is added, Then both icons appear inline.
Given a combatant with many conditions, When viewing the row, Then icons wrap within the name column without increasing row width; row height may increase.
Given "poisoned" was applied first and "blinded" second, When viewing the row, Then "blinded" appears before "poisoned" (fixed definition order, not insertion order).

Story CC-5 — Toggle Concentration (P1) As a DM, I want to mark a combatant as concentrating on a spell by clicking a Brain icon in the row gutter so I can track spells requiring concentration.

Acceptance scenarios:

Given a combatant row is not hovered and concentration is inactive, Then the Brain icon is hidden.
Given a combatant row is hovered and concentration is inactive, Then the Brain icon appears in a muted/faded style.
Given the Brain icon is visible, When the user clicks it, Then concentration activates and the icon remains visible with an active style.
Given concentration is active and the row is not hovered, Then the Brain icon remains visible.
Given concentration is active, When the user clicks the Brain icon again, Then concentration deactivates and the icon hides (unless the row is still hovered).
Given the Brain icon is visible, When the user hovers over it, Then a tooltip reading "Concentrating" appears.

Story CC-6 — Visual Feedback for Concentration (P2) As a DM, I want concentrating combatants to have a visible row accent so I can identify them at a glance without interacting.

Acceptance scenarios:

Given concentration is active, When viewing the encounter tracker, Then the combatant row shows a colored left border accent (border-l-purple-400).
Given concentration is inactive, Then no concentration accent is shown.
Given concentration is toggled off, Then the left border accent disappears immediately.

Story CC-7 — Damage Pulse Alert (P3) As a DM, I want a visual alert when a concentrating combatant takes damage so I remember to call for a concentration check.

Acceptance scenarios:

Given a combatant is concentrating, When the combatant takes damage (HP reduced), Then the Brain icon and row accent briefly pulse/flash for 700 ms.
Given a combatant is concentrating, When the combatant is healed, Then no pulse/flash occurs.
Given a combatant is NOT concentrating, When damage is taken, Then no pulse/flash occurs.
Given a concentrating combatant takes damage, When the animation completes, Then the row returns to its normal concentration-active appearance.

Requirements

FR-032: The MVP MUST support the following 15 standard D&D 5e conditions: blinded, charmed, deafened, exhaustion, frightened, grappled, incapacitated, invisible, paralyzed, petrified, poisoned, prone, restrained, stunned, unconscious.

FR-033: Each condition MUST have a fixed icon and color mapping (Lucide icons; no emoji):

Condition	Icon	Color
Blinded	EyeOff	neutral
Charmed	Heart	pink
Deafened	EarOff	neutral
Exhaustion	BatteryLow	amber
Frightened	Siren	orange
Grappled	Hand	neutral
Incapacitated	Ban	gray
Invisible	Ghost	violet
Paralyzed	ZapOff	yellow
Petrified	Gem	slate
Poisoned	Droplet	green
Prone	ArrowDown	neutral
Restrained	Link	neutral
Stunned	Sparkles	yellow
Unconscious	Moon	indigo

FR-034: Active condition icons MUST appear inline after the creature name within the same row, not on a separate line.
FR-035: Conditions MUST be displayed in the fixed definition order (blinded -> unconscious), regardless of application order.
FR-036: The "+" condition button MUST be hidden by default and appear only on row hover (or touch/focus on touch devices).
FR-037: Clicking "+" MUST open the compact condition picker showing all conditions as icon + label pairs.
FR-038: Clicking a condition in the picker MUST toggle it on or off.
FR-039: Clicking an active condition icon tag in the row MUST remove that condition.
FR-040: Hovering an active condition icon MUST show a tooltip with the condition name.
FR-041: Condition icons MUST NOT increase the row's width; row height MAY increase to accommodate wrapping.
FR-042: The condition picker MUST close when the user clicks outside of it.
FR-043: Conditions MUST persist as part of combatant state (surviving page reload).
FR-044: The condition data model MUST be extensible for future additions (e.g., mechanical effects, descriptions).
FR-045: isConcentrating MUST be stored as an optional boolean on the combatant, separate from the conditions array.
FR-046: Concentration MUST NOT appear in or interact with the condition tag system.
FR-047: The Brain icon toggle MUST be hidden at row rest and revealed on hover (same hover pattern as the "+" button).
FR-048: The Brain icon MUST remain visible whenever concentration is active, regardless of hover state.
FR-049: A tooltip reading "Concentrating" MUST appear when hovering the Brain icon.
FR-050: The active Brain icon MUST use text-purple-400; the inactive (hover-revealed) Brain icon MUST use a muted style (text-muted-foreground opacity-50).
FR-051: The concentration left border accent MUST use border-l-purple-400.
FR-052: The concentration toggle's clickable area MUST extend to fill the full gutter between the left border and the initiative column.
FR-053: When a concentrating combatant takes damage, the Brain icon and row accent MUST briefly pulse/flash for 700 ms.
FR-054: The pulse animation MUST NOT trigger on healing or when concentration is inactive.
FR-055: Concentration MUST persist across page reloads via existing storage.

Edge Cases

When all 15 conditions are applied, icons wrap within the row; row height increases but width does not.
When a combatant is removed, all its conditions and concentration state are discarded.
When the picker is open and the user clicks outside, it closes.
When a condition is toggled on then immediately off in the picker, it does not appear in the row.
When concentration is toggled during an active pulse animation, the animation cancels and the new state applies immediately.
Multiple combatants may concentrate simultaneously; concentration is independent per combatant.
Conditions have no mechanical effects in the MVP baseline (no auto-disadvantage, no automation).

Initiative

User Stories

Story INI-1 — Set Initiative Value (P1) As a game master running an encounter, I want to assign an initiative value to a combatant so that the encounter's turn order reflects each combatant's rolled initiative.

Acceptance scenarios:

Given a combatant with no initiative set, When the user sets initiative to 15, Then the combatant has initiative value 15.
Given a combatant with initiative 15, When the user changes initiative to 8, Then the combatant has initiative value 8.
Given a combatant with no initiative set, When the user attempts to set a non-integer value, Then the system rejects the input and initiative remains unset.
Given a combatant with initiative 15, When the user clears initiative, Then the initiative is unset and the combatant moves to the end of the turn order.
Given a combatant has an initiative value displayed as plain text, When the user clicks it, Then an inline editor opens to change or clear it.

Story INI-2 — Roll Initiative for a Single Combatant (P1) As a DM, I want to click a d20 icon next to a combatant's initiative slot to randomly roll initiative (1d20 + initiative modifier) so the result is immediately placed into the initiative field and the tracker re-sorts.

Acceptance scenarios:

Given a combatant linked to a bestiary creature (e.g., Aboleth, initiative modifier +7) with no initiative, When the user clicks the d20 icon, Then a random value in the range [8, 27] is stored as initiative and the list re-sorts descending.
Given a combatant NOT linked to a bestiary creature, When viewing the row, Then the initiative slot shows "--" (clickable to type a value manually) — no d20 button.
Given a combatant whose initiative modifier is negative (e.g., -2), When the d20 button is clicked, Then the result ranges from -1 to 18.
Given a combatant already has an initiative value, Then the d20 button is replaced by the value as plain text; clicking it opens the inline editor.

Story INI-3 — Roll Initiative for All Eligible Combatants (P2) As a DM, I want a "Roll All Initiative" button in the top bar to roll for all bestiary combatants at once so I can set up the initiative order quickly at the start of combat.

Acceptance scenarios:

Given 3 bestiary combatants (no initiative) and 1 manual combatant, When the roll-all button is clicked, Then all 3 bestiary combatants receive rolled initiative values; the manual combatant is unchanged.
Given bestiary combatants that already have initiative values, When the roll-all button is clicked, Then those combatants are skipped; only bestiary combatants without initiative are rolled.
Given no bestiary combatants, When the roll-all button is clicked, Then no changes occur.

Story INI-4 — Display Initiative Modifier in Stat Block (P1) As a DM viewing a creature's stat block, I want to see the creature's initiative modifier and passive initiative so I can reference it when rolling.

Acceptance scenarios:

Given a creature with DEX 9, CR 10, initiative proficiency multiplier 2 (e.g., Aboleth), When the stat block is displayed, Then the initiative line shows "Initiative +7 (17)" (-1 + 2x4 = +7; passive = 17).
Given a creature with proficiency multiplier 1, Then the initiative modifier includes 1x the proficiency bonus.
Given a creature with no initiative field in bestiary data, Then only the DEX modifier is shown (e.g., DEX 14 -> "Initiative +2 (12)").
Given a creature with a negative initiative modifier (e.g., DEX 8, no proficiency), Then the line uses a minus sign (e.g., "Initiative -1 (9)").
Given a combatant without bestiary data, Then no initiative line is shown in the stat block.

Story INI-5 — Combatants Without Initiative (P2) As a game master, I want combatants without initiative set to appear at the end of the turn order so the encounter remains usable while I am still entering values.

Acceptance scenarios:

Given combatants A (initiative 15), B (no initiative), C (initiative 10), Then order is A, C, B.
Given A (no initiative) and B (no initiative), Then their relative order is preserved from when they were added.
Given combatant A (no initiative), When initiative is set to 12, Then A moves to its correct sorted position.

Requirements

FR-056: System MUST allow setting an integer initiative value for any combatant.
FR-057: System MUST allow changing an existing initiative value.
FR-058: System MUST allow clearing (unsetting) a combatant's initiative value.
FR-059: System MUST reject non-integer initiative values and return a domain error.
FR-060: System MUST accept zero and negative integers as valid initiative values.
FR-061: System MUST automatically reorder combatants highest-to-lowest initiative whenever a value is set, changed, or cleared.
FR-062: Combatants without initiative MUST be placed after all combatants with initiative values.
FR-063: System MUST use a stable sort so combatants with equal initiative (or multiple without initiative) retain their relative order.
FR-064: System MUST preserve the active combatant's turn through reorders — the active turn tracks combatant identity, not list position.
FR-065: System MUST emit a domain event when a combatant's initiative is set or changed.
FR-066: System MUST display a d20 icon button in the initiative slot for every combatant that has a linked bestiary creature and does not yet have an initiative value.
FR-067: System MUST NOT display the d20 button for combatants without a linked bestiary creature; they see a "--" placeholder that is clickable to type a value.
FR-068: When the d20 button is clicked, the system MUST generate a uniform random integer in [1, 20], add the creature's initiative modifier, and set the result as the initiative value.
FR-069: The initiative modifier MUST be calculated as: DEX modifier + (proficiency multiplier x proficiency bonus), where DEX modifier = floor((DEX - 10) / 2) and proficiency bonus is derived from challenge rating.
FR-070: The initiative proficiency multiplier MUST be read from initiative.proficiency in bestiary data (0 if absent, 1 for proficiency, 2 for expertise).
FR-071: System MUST provide a "Roll All Initiative" button in the top bar. Clicking it MUST roll for every bestiary-linked combatant that does not already have an initiative value; all others MUST be left unchanged.
FR-072: After any initiative roll (single or batch), the encounter list MUST re-sort descending per existing behavior.
FR-073: Once a combatant has an initiative value, the d20 button is replaced by the value as plain text using a click-to-edit pattern (consistent with AC and name editing).
FR-074: The stat block header MUST display initiative in the format "Initiative +X (Y)" where X is the modifier (with + or - sign) and Y = 10 + X.
FR-075: The initiative display in the stat block MUST be positioned adjacent to the AC value, matching Monster Manual 2024 layout.
FR-076: No initiative line MUST be shown in the stat block for combatants without bestiary data.
FR-077: The initiative display in the stat block is display-only. It MUST NOT modify encounter turn order or trigger rolling automatically.
FR-078: The d20 roll-initiative icon MUST be displayed larger than 20x20 px while remaining contained within the initiative column.
FR-079: The "Roll All Initiative" d20 in the top bar MUST be sized at 24 px; the clear-encounter (trash) icon MUST be sized at 20 px. Both are visually grouped together, separated from turn navigation controls by spacing.

Edge Cases

Setting initiative to zero is valid and treated normally in sorting.
Negative initiative values are valid (some game systems use them).
When a combatant is added without initiative during an ongoing encounter, it appears at the end of the order.
When all combatants have the same initiative value, their insertion order is preserved.
When the active combatant's own initiative changes causing a reorder, the active turn still points to that combatant.
When another combatant's initiative changes causing a reorder, the active turn still points to the current active combatant.
When a combatant's initiative modifier produces a roll result of 0 or negative, the value is stored as-is.
When multiple combatants roll the same initiative, ties are resolved by preserving relative insertion order.
A minus sign is used for negative modifiers in the stat block display, not a hyphen.
When a creature has DEX producing a modifier of exactly 0 and no initiative proficiency, display "Initiative +0 (10)".
For manually-added combatants: no initiative modifier is available, so no d20 button and no stat block initiative line.
The passive initiative value shown in the stat block is reference-only; only the active modifier (+X) is used for rolling.
Random number generation for dice rolls uses standard browser randomness; cryptographic randomness is not required.

Combatant Row Layout

User Stories

Story ROW-1 — Compact Resting State (P1) As a DM, I want each combatant row to display a minimal, uncluttered view at rest so I can scan the encounter list quickly during play.

Acceptance scenarios:

Given a combatant row is not hovered, Then no delta input, action buttons, "+" condition button, remove button, or Brain icon are visible.
Given a combatant has no conditions, Then the row occupies exactly one line height at rest.
Given a combatant has conditions applied, Then condition icons appear inline after the creature name on the same row (not a separate line).

Story ROW-2 — Hover Reveals Controls (P1) As a DM, I want secondary controls to appear when I hover over a row so they are accessible without cluttering the resting view.

Acceptance scenarios:

Given any combatant row, When hovered, Then the "+" condition button appears inline after the name/conditions.
Given any combatant row, When hovered, Then the remove (x) button becomes visible.
Given any combatant row, When hovered and concentration is inactive, Then the Brain icon becomes visible.
Given the remove button appears on hover, Then no layout shift occurs — space is reserved.

Story ROW-3 — Book Icon Opens Stat Block (P1) As a DM, I want a dedicated book icon on bestiary combatant rows so I can open the stat block with an explicit, discoverable control — while clicking the name always starts a rename.

Acceptance scenarios:

Given a combatant has a linked bestiary creature, When the user views the row, Then a small BookOpen icon is visible next to the name.
Given a combatant does NOT have a linked creature, When the user views the row, Then no BookOpen icon is displayed.
Given a bestiary combatant row, When the user clicks the BookOpen icon, Then the stat block panel opens for that creature.
Given the user clicks the combatant's name, Then inline rename mode is entered — the stat block does NOT open.
Given the stat block is already open for a creature, When the user clicks its BookOpen icon again, Then the panel closes (toggle behavior).

Requirements

FR-080: Condition icons MUST render inline after the creature name within the same row.
FR-081: The "+" condition button MUST be hidden at rest and appear on row hover (or touch/focus on touch devices).
FR-082: The remove (x) button MUST be hidden at rest and appear on row hover (or touch/focus on touch devices).
FR-083: Layout space for the remove button MUST be reserved so appearing/disappearing does not cause layout shifts.
FR-084: Bestiary-linked combatant rows MUST display a BookOpen icon as the dedicated stat block trigger (see also specs/004-bestiary/spec.md, FR-062).
FR-085: Clicking the combatant name MUST enter inline rename mode, not open the stat block.
FR-086: Non-bestiary combatant rows MUST NOT display the BookOpen icon.
FR-087: The BookOpen icon MUST have a tooltip ("View stat block") and aria-label="View stat block" for accessibility.
FR-088: All existing interactions (condition add/remove, HP adjustment, AC editing, initiative editing/rolling, concentration toggle, combatant removal) MUST continue to work.
FR-089: Browser scrollbars MUST be styled to match the dark UI theme (thin, dark-colored scrollbar thumbs).
FR-090: Turn navigation (Previous/Next) MUST use StepBack/StepForward icons in outline button style with foreground-colored borders. Utility actions (d20/trash) MUST use ghost button style to create clear visual hierarchy.
FR-091: Previous and Next turn buttons MUST be positioned at the far left and far right of the top bar respectively, with the round/combatant info centered between them.
FR-092: The "Initiative Tracker" heading MUST be removed to maximize vertical space for combatants.
FR-093: All interactive elements in the row MUST remain keyboard-accessible (focusable and operable via keyboard).
FR-094: On touch devices, hover-only controls ("+" button, "x" button) MUST remain accessible via tap or focus.

Edge Cases

When a combatant has so many conditions that they exceed the available inline space, they wrap within the name column; row height increases but width does not.
The condition picker dropdown positions relative to the "+" button, flipping vertically if near the viewport edge.
When the stat block panel is already open and the user clicks the same BookOpen icon again, the panel closes.
Clicking the combatant name starts inline rename; it does not open the stat block.
Tablet-width screens (>= 768 px / Tailwind md): popovers and inline edits MUST remain accessible and not overflow or clip.

Success Criteria (mandatory)

SC-001: Users can set max HP and adjust current HP for any combatant in under 5 seconds per action.
SC-002: currentHp never exceeds maxHp or drops below 0, regardless of input method.
SC-003: HP values survive a full page reload without data loss.
SC-004: A user can apply damage to a combatant in 2 interactions or fewer (click HP -> type number -> Enter).
SC-005: A user can apply healing in 3 interactions or fewer (click HP -> type number -> click Heal).
SC-006: Users can identify bloodied combatants at a glance without reading HP numbers — 100% of combatants below half HP display a distinct amber treatment.
SC-007: Users can identify unconscious/dead combatants at a glance — 100% of combatants at 0 HP or below display a distinct red treatment that differs from the bloodied indicator.
SC-008: Visual status indicators update within the same interaction frame as the HP change.
SC-009: Users can set an AC value for any combatant within the existing edit workflow with no additional steps.
SC-010: AC is visible at a glance in the encounter list without expanding or hovering.
SC-011: A condition can be added to a combatant in 2 clicks or fewer (click "+", click condition).
SC-012: A condition can be removed in 1 click (click the active icon tag).
SC-013: All 15 D&D 5e conditions are available and visually distinguishable by icon and color.
SC-014: Condition state survives a full page reload without data loss.
SC-015: Users can toggle concentration on/off for any combatant in a single click.
SC-016: Concentrating combatants are visually distinguishable from non-concentrating combatants at a glance.
SC-017: When a concentrating combatant takes damage, the visual pulse alert draws attention within the same interaction flow.
SC-018: Concentration state survives a full page reload.
SC-019: Users can set initiative for any combatant in a single action.
SC-020: After any initiative change, the encounter list immediately reflects the correct descending sort.
SC-021: A single combatant's initiative can be rolled with one click (the d20 button).
SC-022: All eligible combatants' initiative can be rolled with one click (roll-all button).
SC-023: Manual combatants (no stat block) are never affected by roll actions.
SC-024: Every bestiary creature displays an initiative value in its stat block matching D&D Beyond / Monster Manual 2024.
SC-025: The initiative line is visible without scrolling in the stat block header.
SC-026: Each combatant row without conditions takes up exactly one line height at rest.
SC-027: The DM can open a stat block by clicking anywhere on the combatant name area without needing a dedicated icon.
SC-028: The AC number is visually identifiable as armor class through the shield shape alone.
SC-029: No layout shift occurs when hovering/unhovering rows.
SC-030: All HP, AC, initiative, condition, and concentration interactions remain fully operable using only a keyboard.

39 KiB Raw Permalink Blame History

Feature Specification: Combatant State

Overview

Domain Model Reference

Hit Points

User Stories

Requirements

Edge Cases

Armor Class

User Stories

Requirements

Edge Cases

Conditions & Concentration

User Stories

Requirements

Edge Cases

Initiative

User Stories

Requirements

Edge Cases

Combatant Row Layout

User Stories

Requirements

Edge Cases

Success Criteria (mandatory)

39 KiB

Raw Permalink Blame History