Implement the 023-clear-encounter feature that adds a clear encounter button with confirmation dialog to remove all combatants and reset round/turn counters, with the cleared state persisting across page refreshes

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

specs/023-clear-encounter/spec.md

@@ -0,0 +1,74 @@
+# Feature Specification: Clear Encounter
+
+**Feature Branch**: `023-clear-encounter`
+**Created**: 2026-03-09
+**Status**: Draft
+**Input**: User description: "I want to have a button to clear the whole encounter and start over. This is helpful because when I end a combat and want to start a new one, I don't want to manually delete every single combatant. Also the round and turn counters should reset."
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Clear Encounter to Start Fresh (Priority: P1)
+
+As a DM who has just finished a combat encounter, I want to clear the entire encounter with a single action so that I can quickly set up a new combat without manually removing each combatant one by one.
+
+**Why this priority**: This is the core value of the feature. Without it, DMs must tediously remove combatants individually between encounters, which slows down gameplay.
+
+**Independent Test**: Can be fully tested by adding several combatants, advancing through some rounds, then clearing the encounter and verifying all combatants are removed and counters reset.
+
+**Acceptance Scenarios**:
+
+1. **Given** an encounter with multiple combatants at round 3, **When** the user activates the clear encounter action, **Then** all combatants are removed, the round number resets to its initial state, and the active turn index resets.
+2. **Given** an encounter with a single combatant, **When** the user activates the clear encounter action, **Then** the encounter is fully cleared.
+3. **Given** an encounter with combatants that have HP values, conditions, concentration, and AC set, **When** the user clears the encounter, **Then** all combatant data is removed completely.
+
+---
+
+### User Story 2 - Confirmation Before Clearing (Priority: P1)
+
+As a DM, I want to be asked for confirmation before the encounter is cleared so that I don't accidentally lose my current combat state.
+
+**Why this priority**: Accidental data loss would be extremely frustrating during an active combat. This is critical for usability and trust.
+
+**Independent Test**: Can be tested by clicking the clear button and verifying a confirmation prompt appears, then cancelling and verifying nothing changed.
+
+**Acceptance Scenarios**:
+
+1. **Given** an encounter with combatants, **When** the user activates the clear encounter action, **Then** a confirmation prompt is displayed before any data is removed.
+2. **Given** a confirmation prompt is displayed, **When** the user confirms, **Then** the encounter is cleared.
+3. **Given** a confirmation prompt is displayed, **When** the user cancels, **Then** the encounter remains unchanged.
+
+---
+
+### Edge Cases
+
+- What happens when the encounter is already empty (no combatants)? The clear action should either be disabled or be a no-op.
+- What happens to persisted data after clearing? The persisted encounter state should also be cleared so that refreshing the page does not restore the old encounter.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST provide a clear encounter action accessible from the encounter tracker interface.
+- **FR-002**: Activating the clear action MUST remove all combatants from the encounter.
+- **FR-003**: Activating the clear action MUST reset the round number to its initial value (1).
+- **FR-004**: Activating the clear action MUST reset the active turn index to its initial value (0).
+- **FR-005**: System MUST display a confirmation prompt before executing the clear action to prevent accidental data loss.
+- **FR-006**: Cancelling the confirmation MUST leave the encounter completely unchanged.
+- **FR-007**: The cleared state MUST be persisted so that a page refresh does not restore the previous encounter.
+- **FR-008**: The clear action SHOULD be disabled or hidden when the encounter has no combatants.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: Users can clear a full encounter (any number of combatants) and start fresh with a single confirmed action, compared to N individual remove actions previously required.
+- **SC-002**: After clearing, the encounter tracker displays an empty state with round and turn counters at their initial values.
+- **SC-003**: Accidental clears are prevented by requiring explicit user confirmation before any data is removed.
+- **SC-004**: Cleared state persists across page refreshes — no stale encounter data is restored.
+
+## Assumptions
+
+- The clear action results in an empty encounter state (no combatants, round 1, active index 0). The user will then add new combatants for the next encounter using the existing add-combatant flow.
+- The confirmation mechanism will be a simple modal dialog or equivalent inline confirmation pattern consistent with the existing UI style.
+- MVP baseline does not include undo/restore functionality after clearing. Once confirmed, the clear is final.
+- MVP baseline does not include encounter history or the ability to save/archive encounters before clearing.