initiative/specs/018-combatant-concentration/spec.md

Feature Specification: Combatant Concentration

Feature Branch: 018-combatant-concentration Created: 2026-03-06 Status: Draft Input: User description: "Add concentration as a separate per-combatant state, not as a normal condition."

User Scenarios & Testing (mandatory)

User Story 1 - Toggle Concentration (Priority: P1)

A DM wants to mark a combatant as concentrating on a spell. They hover over the combatant row to reveal a Brain icon button on the left side of the row, then click it to activate concentration. Clicking the icon again toggles concentration off.

Why this priority: Core interaction; without toggle, the feature has no function.

Independent Test: Can be fully tested by hovering a combatant row, clicking the Brain icon, and verifying concentration state toggles on/off.

Acceptance Scenarios:

1. Given a combatant row is not hovered, When the row is at rest, Then the Brain icon is hidden.
2. Given a combatant row is hovered, When concentration is inactive, Then the Brain icon appears (muted/faded).
3. Given the Brain icon is visible, When the user clicks it, Then concentration activates and the icon remains visible with an active style.
4. Given concentration is active, When the user clicks the Brain icon again, Then concentration deactivates and the icon hides (unless row is still hovered).
5. Given concentration is active, When the row is not hovered, Then the Brain icon remains visible (active state keeps it shown).
6. Given the Brain icon is visible, When the user hovers over it, Then a tooltip reading "Concentrating" appears.

---

User Story 2 - Visual Feedback for Concentration (Priority: P2)

A DM wants to see at a glance which combatants are concentrating. When concentration is active, the combatant row displays a subtle colored left border accent to visually distinguish it from normal conditions.

Why this priority: Provides passive visual awareness without requiring interaction; builds on toggle.

Independent Test: Can be tested by activating concentration on a combatant and verifying the row gains a colored left border accent.

Acceptance Scenarios:

1. Given a combatant has concentration active, When viewing the encounter tracker, Then the combatant row shows a colored left border accent.
2. Given a combatant has concentration inactive, When viewing the encounter tracker, Then the combatant row has no concentration accent.
3. Given concentration is active, When the user toggles concentration off, Then the left border accent disappears.

---

User Story 3 - Damage Pulse Alert (Priority: P3)

A DM deals damage to a concentrating combatant. The concentration icon and the row accent briefly pulse/flash to draw attention, reminding the DM that a concentration check may be needed.

Why this priority: Enhances situational awareness but depends on both toggle (P1) and visual feedback (P2) being in place.

Independent Test: Can be tested by activating concentration on a combatant, applying damage, and verifying the pulse animation triggers.

Acceptance Scenarios:

1. Given a combatant is concentrating, When the combatant takes damage (HP reduced), Then the Brain icon and row accent briefly pulse/flash.
2. Given a combatant is concentrating, When the combatant is healed (HP increased), Then no pulse/flash occurs.
3. Given a combatant is not concentrating, When the combatant takes damage, Then no pulse/flash occurs.
4. Given a concentrating combatant takes damage, When the pulse animation completes, Then the row returns to its normal concentration-active appearance.

---

Edge Cases

• What happens when a combatant with concentration active is removed from the encounter? Concentration state is discarded with the combatant.
• What happens when concentration is toggled during an active pulse animation? The animation cancels and the new state applies immediately.
• Can multiple combatants concentrate simultaneously? Yes, concentration is independent per combatant.
• Does concentration state persist across page reloads? Yes, it is part of the combatant state stored via existing persistence.

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST store concentration as a boolean property on each combatant, separate from the conditions list.
• FR-002: System MUST provide a toggle operation that flips concentration on/off for a given combatant.
• FR-003: The Brain icon MUST be hidden by default and appear on combatant row hover.
• FR-004: The Brain icon MUST remain visible whenever concentration is active, regardless of hover state.
• FR-005: Clicking the Brain icon MUST toggle the combatant's concentration state.
• FR-006: A tooltip reading "Concentrating" MUST appear when hovering the Brain icon.
• FR-007: When concentration is active, the combatant row MUST display a subtle colored left border accent.
• FR-008: When a concentrating combatant takes damage, the Brain icon and row accent MUST briefly pulse/flash.
• FR-009: The pulse/flash MUST NOT trigger on healing or when concentration is inactive.
• FR-010: Concentration MUST persist across page reloads via existing storage mechanisms.
• FR-011: Concentration MUST NOT appear in or interact with the condition tag system.
• FR-012: The concentration left border accent MUST use border-l-purple-400. The active Brain icon MUST use text-purple-400 to visually associate icon and border.
• FR-013: The inactive (hover-revealed) Brain icon MUST use a muted style (text-muted-foreground opacity-50).

Key Entities

• Combatant: Gains a new isConcentrating optional boolean property (default: undefined/falsy), independent of the existing conditions array.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Users can toggle concentration on/off for any combatant in a single click.
• SC-002: Concentrating combatants are visually distinguishable from non-concentrating combatants at a glance without hovering or interacting.
• SC-003: When a concentrating combatant takes damage, the visual alert draws attention within the same interaction flow (no separate notification needed).
• SC-004: Concentration state survives a full page reload without data loss.
• SC-005: The concentration UI does not increase the resting height of combatant rows (icon hidden by default keeps rows compact).

Assumptions

• The Lucide Brain icon is available in the project's existing Lucide React dependency.
• The colored left border accent will use a distinct color that does not conflict with existing condition tag colors.
• The pulse/flash animation duration MUST be 700ms. Both the CSS animation and the JS timeout MUST use this single value.
• "Takes damage" means any HP reduction (negative delta applied to current HP).