initiative/specs/008-persist-encounter/spec.md

Feature Specification: Persist Encounter

Feature Branch: 008-persist-encounter Created: 2026-03-05 Status: Draft Input: User description: "Persist the encounter in browser localStorage so the current encounter survives page reloads."

User Scenarios & Testing (mandatory)

User Story 1 - Encounter Survives Page Reload (Priority: P1)

A user is managing a combat encounter (combatants added, initiative set, turns advanced). They accidentally refresh the page or their browser restarts. When the page reloads, the encounter is restored exactly as it was -- same combatants, same initiative values, same active turn, same round number.

Why this priority: This is the core value of the feature. Without persistence, all encounter progress is lost on any page navigation or reload, which is the primary pain point.

Independent Test: Can be fully tested by setting up an encounter, refreshing the page, and verifying all encounter state is preserved.

Acceptance Scenarios:

1. Given an encounter with combatants, initiative values, active turn, and round number, When the user reloads the page, Then the encounter is restored with all state intact (combatants, initiative, active index, round number).
2. Given an encounter that has been modified (combatant added, removed, renamed, or initiative changed), When the user reloads the page, Then the latest state is reflected.
3. Given the user advances the turn multiple times, When the user reloads the page, Then the active turn and round number are preserved.

---

User Story 2 - Fresh Start with No Saved Data (Priority: P2)

A first-time user opens the application with no previously saved encounter. The application shows the default demo encounter so the user can immediately start exploring.

Why this priority: Ensures backward compatibility and a smooth first-use experience.

Independent Test: Can be tested by clearing browser storage and loading the application, verifying the demo encounter appears.

Acceptance Scenarios:

1. Given no saved encounter exists in the browser, When the user opens the application, Then the default demo encounter is displayed.
2. Given saved encounter data has been manually cleared from the browser, When the user opens the application, Then the default demo encounter is displayed.

---

User Story 3 - Graceful Handling of Corrupt Data (Priority: P3)

Saved data may become invalid (e.g., manually edited in dev tools, schema changes between versions). The application handles this gracefully rather than crashing.

Why this priority: Protects the user experience from edge cases that would otherwise render the app unusable without manual intervention.

Independent Test: Can be tested by writing malformed data to the storage key and loading the application.

Acceptance Scenarios:

1. Given the saved encounter data is malformed or unparseable, When the user opens the application, Then the default demo encounter is displayed and the corrupt data is discarded.
2. Given the saved data is missing required fields, When the user opens the application, Then the default demo encounter is displayed.

---

Edge Cases

• What happens when browser storage quota is exceeded? The application continues to function normally; persistence silently fails without disrupting the user's current session.
• What happens when browser storage is unavailable (e.g., private browsing in some browsers)? The application falls back to in-memory-only behavior, functioning identically to the current experience.
• What happens when the user has multiple browser tabs open? MVP baseline does not include cross-tab synchronization. Each tab operates independently; the last tab to save wins.

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST save the full encounter state (combatants, activeIndex, roundNumber) to browser storage after every state change.
• FR-002: System MUST restore the saved encounter state when the application loads, if valid saved data exists.
• FR-003: System MUST fall back to the default demo encounter when no saved data exists or saved data is invalid.
• FR-004: System MUST NOT crash or show an error to the user when storage is unavailable or data is corrupt.
• FR-005: System MUST preserve combatant identity (IDs, names, initiative values) across reloads.
• FR-006: System MUST preserve the active turn position and round number across reloads.

Key Entities

• Persisted Encounter: A serialized representation of the Encounter (combatants with IDs, names, and initiative values; activeIndex; roundNumber) stored in the browser.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Users can reload the page and see their encounter fully restored within 1 second, with zero data loss.
• SC-002: First-time users see the demo encounter immediately on first visit with no extra steps.
• SC-003: 100% of corrupt or missing data scenarios result in a usable application (demo encounter displayed), never a crash or blank screen.

Assumptions

• The encounter state is small enough that serialization/deserialization has negligible performance impact.
• A single browser storage key is sufficient for the MVP (one encounter at a time).
• Cross-tab synchronization is not required for the MVP baseline.
• The ID counter for new combatants must also be persisted or derived from existing state so that new combatants added after a reload do not collide with existing IDs.