dostulata/initiative
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement the 008-persist-encounter feature that saves encounter state to localStorage so it survives page reloads

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Lukas
2026-03-05 16:24:00 +01:00
parent c4a90c9982
commit a9c280a6d6
12 changed files with 818 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
specs/008-persist-encounter/plan.md Normal file
View File

@@ -0,0 +1,74 @@
# Implementation Plan: Persist Encounter
**Branch**: `008-persist-encounter` | **Date**: 2026-03-05 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/008-persist-encounter/spec.md`
## Summary
Persist the current encounter state to browser localStorage so it survives page reloads. The web adapter layer will serialize encounter state on every change and deserialize on load, falling back to the demo encounter when no valid data exists. The domain and application layers remain unchanged -- persistence is purely an adapter concern.
## Technical Context
**Language/Version**: TypeScript 5.x (strict mode, verbatimModuleSyntax)
**Primary Dependencies**: React 19, Vite 6, Biome 2.0, existing domain/application packages
**Storage**: Browser localStorage (adapter layer only)
**Testing**: Vitest (unit tests for serialization/deserialization logic)
**Target Platform**: Modern browsers (Chrome, Firefox, Safari, Edge)
**Project Type**: Web application (monorepo with domain/application/web layers)
**Performance Goals**: Encounter restore under 1 second (negligible for small JSON payloads)
**Constraints**: No domain or application layer changes; persistence is adapter-only
**Scale/Scope**: Single encounter, single user, single tab (MVP baseline)
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
| Principle | Status | Notes |
|-----------|--------|-------|
| I. Deterministic Domain Core | PASS | No domain changes. localStorage access is confined to the adapter layer. |
| II. Layered Architecture | PASS | Persistence logic lives in the web adapter (apps/web). Domain and application layers are untouched. The existing `EncounterStore` port is already implemented by the `useEncounter` hook; persistence wraps around this. |
| III. Agent Boundary | N/A | No agent features involved. |
| IV. Clarification-First | PASS | Feature is well-scoped; no non-trivial assumptions. Storage key name and serialization format are implementation details within adapter scope. |
| V. Escalation Gates | PASS | Implementation stays within spec scope. |
| VI. MVP Baseline Language | PASS | Cross-tab sync and multi-encounter support noted as "MVP baseline does not include." |
| VII. No Gameplay Rules | PASS | No gameplay mechanics involved. |
**Gate result**: PASS -- no violations.
## Project Structure
### Documentation (this feature)
```text
specs/008-persist-encounter/
├── plan.md # This file
├── research.md # Phase 0 output
├── data-model.md # Phase 1 output
├── quickstart.md # Phase 1 output
└── tasks.md # Phase 2 output (via /speckit.tasks)
```
### Source Code (repository root)
```text
packages/domain/src/
├── types.ts # Encounter, Combatant, CombatantId (unchanged)
└── index.ts # Exports (unchanged)
packages/application/src/
├── ports.ts # EncounterStore interface (unchanged)
└── index.ts # Exports (unchanged)
apps/web/src/
├── hooks/
│ └── use-encounter.ts # Modified: initialize from localStorage, persist on change
├── persistence/
│ └── encounter-storage.ts # New: localStorage read/write/validate logic
└── main.tsx # Unchanged
```
**Structure Decision**: All new code goes into `apps/web/src/persistence/` as a new adapter module. The `useEncounter` hook is modified to use this module for initialization and persistence. No new packages or layers are introduced.
## Complexity Tracking
No constitution violations to justify.