Implement the 018-combatant-concentration feature that adds a per-combatant concentration toggle with Brain icon, purple border accent, and damage pulse animation in the encounter tracker

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

specs/018-combatant-concentration/spec.md

@@ -0,0 +1,106 @@
+# 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).