# 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).