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

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

apps/web/src/hooks/use-encounter.ts

@@ -12,7 +12,11 @@ import {
 	createEncounter,
 	isDomainError,
 } from "@initiative/domain";
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+	loadEncounter,
+	saveEncounter,
+} from "../persistence/encounter-storage.js";
 
 function createDemoEncounter(): Encounter {
 	const result = createEncounter([
@@ -28,12 +32,34 @@ function createDemoEncounter(): Encounter {
 	return result;
 }
 
+function initializeEncounter(): Encounter {
+	const stored = loadEncounter();
+	if (stored !== null) return stored;
+	return createDemoEncounter();
+}
+
+function deriveNextId(encounter: Encounter): number {
+	let max = 0;
+	for (const c of encounter.combatants) {
+		const match = /^c-(\d+)$/.exec(c.id);
+		if (match) {
+			const n = Number.parseInt(match[1], 10);
+			if (n > max) max = n;
+		}
+	}
+	return max;
+}
+
 export function useEncounter() {
-	const [encounter, setEncounter] = useState<Encounter>(createDemoEncounter);
+	const [encounter, setEncounter] = useState<Encounter>(initializeEncounter);
 	const [events, setEvents] = useState<DomainEvent[]>([]);
 	const encounterRef = useRef(encounter);
 	encounterRef.current = encounter;
 
+	useEffect(() => {
+		saveEncounter(encounter);
+	}, [encounter]);
+
 	const makeStore = useCallback((): EncounterStore => {
 		return {
 			get: () => encounterRef.current,
@@ -51,7 +77,7 @@ export function useEncounter() {
 		setEvents((prev) => [...prev, ...result]);
 	}, [makeStore]);
 
-	const nextId = useRef(0);
+	const nextId = useRef(deriveNextId(encounter));
 
 	const addCombatant = useCallback(
 		(name: string) => {

apps/web/src/persistence/__tests__/encounter-storage.test.ts

@@ -0,0 +1,229 @@
+import {
+	combatantId,
+	createEncounter,
+	isDomainError,
+} from "@initiative/domain";
+import { beforeEach, describe, expect, it } from "vitest";
+import { loadEncounter, saveEncounter } from "../encounter-storage.js";
+
+const STORAGE_KEY = "initiative:encounter";
+
+function makeEncounter() {
+	const result = createEncounter(
+		[
+			{ id: combatantId("1"), name: "Aria", initiative: 18 },
+			{ id: combatantId("c-2"), name: "Brak", initiative: 12 },
+			{ id: combatantId("3"), name: "Cael" },
+		],
+		1,
+		3,
+	);
+	if (isDomainError(result)) throw new Error("Failed to create test encounter");
+	return result;
+}
+
+function createMockLocalStorage() {
+	const store = new Map<string, string>();
+	return {
+		getItem: (key: string) => store.get(key) ?? null,
+		setItem: (key: string, value: string) => store.set(key, value),
+		removeItem: (key: string) => store.delete(key),
+		clear: () => store.clear(),
+		get length() {
+			return store.size;
+		},
+		key: (_index: number) => null,
+	} as Storage;
+}
+
+beforeEach(() => {
+	Object.defineProperty(globalThis, "localStorage", {
+		value: createMockLocalStorage(),
+		writable: true,
+		configurable: true,
+	});
+});
+
+describe("saveEncounter", () => {
+	it("writes encounter to localStorage", () => {
+		const encounter = makeEncounter();
+		saveEncounter(encounter);
+		expect(localStorage.getItem(STORAGE_KEY)).not.toBeNull();
+	});
+});
+
+describe("loadEncounter", () => {
+	it("returns null when localStorage is empty", () => {
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("round-trip save/load preserves encounter state", () => {
+		const encounter = makeEncounter();
+		saveEncounter(encounter);
+		const loaded = loadEncounter();
+
+		expect(loaded).not.toBeNull();
+		expect(loaded?.combatants).toHaveLength(3);
+		expect(loaded?.activeIndex).toBe(1);
+		expect(loaded?.roundNumber).toBe(3);
+	});
+
+	it("round-trip preserves combatant IDs, names, and initiative values", () => {
+		const encounter = makeEncounter();
+		saveEncounter(encounter);
+		const loaded = loadEncounter();
+		expect(loaded).not.toBeNull();
+
+		expect(loaded?.combatants[0].id).toBe("1");
+		expect(loaded?.combatants[0].name).toBe("Aria");
+		expect(loaded?.combatants[0].initiative).toBe(18);
+
+		expect(loaded?.combatants[1].id).toBe("c-2");
+		expect(loaded?.combatants[1].name).toBe("Brak");
+		expect(loaded?.combatants[1].initiative).toBe(12);
+
+		expect(loaded?.combatants[2].id).toBe("3");
+		expect(loaded?.combatants[2].name).toBe("Cael");
+		expect(loaded?.combatants[2].initiative).toBeUndefined();
+	});
+
+	it("returns null for non-JSON strings", () => {
+		localStorage.setItem(STORAGE_KEY, "not json at all");
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null for JSON missing required fields", () => {
+		localStorage.setItem(STORAGE_KEY, JSON.stringify({ foo: "bar" }));
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null for invalid encounter data (empty combatants)", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({ combatants: [], activeIndex: 0, roundNumber: 1 }),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null for out-of-bounds activeIndex", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: [{ id: "1", name: "Aria" }],
+				activeIndex: 5,
+				roundNumber: 1,
+			}),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	// US3: Corrupt data scenarios
+	it("returns null for non-object JSON (string)", () => {
+		localStorage.setItem(STORAGE_KEY, JSON.stringify("hello"));
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null for non-object JSON (number)", () => {
+		localStorage.setItem(STORAGE_KEY, JSON.stringify(42));
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null for non-object JSON (array)", () => {
+		localStorage.setItem(STORAGE_KEY, JSON.stringify([1, 2, 3]));
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null for non-object JSON (null)", () => {
+		localStorage.setItem(STORAGE_KEY, "null");
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null when combatants is a string instead of array", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: "not-array",
+				activeIndex: 0,
+				roundNumber: 1,
+			}),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null when activeIndex is a string instead of number", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: [{ id: "1", name: "Aria" }],
+				activeIndex: "zero",
+				roundNumber: 1,
+			}),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null when combatant entry is missing id", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: [{ name: "Aria" }],
+				activeIndex: 0,
+				roundNumber: 1,
+			}),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null when combatant entry is missing name", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: [{ id: "1" }],
+				activeIndex: 0,
+				roundNumber: 1,
+			}),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null for negative roundNumber", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: [{ id: "1", name: "Aria" }],
+				activeIndex: 0,
+				roundNumber: -1,
+			}),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null for zero combatants (domain validation)", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({ combatants: [], activeIndex: 0, roundNumber: 1 }),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("saving after modifications persists the latest state", () => {
+		const encounter = makeEncounter();
+		saveEncounter(encounter);
+
+		const modified = createEncounter(
+			[
+				{ id: combatantId("1"), name: "Aria", initiative: 18 },
+				{ id: combatantId("c-2"), name: "Brak", initiative: 12 },
+			],
+			0,
+			5,
+		);
+		if (isDomainError(modified)) throw new Error("unreachable");
+
+		saveEncounter(modified);
+		const loaded = loadEncounter();
+
+		expect(loaded?.combatants).toHaveLength(2);
+		expect(loaded?.roundNumber).toBe(5);
+	});
+});

apps/web/src/persistence/encounter-storage.ts

@@ -0,0 +1,63 @@
+import {
+	combatantId,
+	createEncounter,
+	type Encounter,
+	isDomainError,
+} from "@initiative/domain";
+
+const STORAGE_KEY = "initiative:encounter";
+
+export function saveEncounter(encounter: Encounter): void {
+	try {
+		localStorage.setItem(STORAGE_KEY, JSON.stringify(encounter));
+	} catch {
+		// Silently swallow errors (quota exceeded, storage unavailable)
+	}
+}
+
+export function loadEncounter(): Encounter | null {
+	try {
+		const raw = localStorage.getItem(STORAGE_KEY);
+		if (raw === null) return null;
+
+		const parsed: unknown = JSON.parse(raw);
+
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+			return null;
+
+		const obj = parsed as Record<string, unknown>;
+
+		if (!Array.isArray(obj.combatants)) return null;
+		if (typeof obj.activeIndex !== "number") return null;
+		if (typeof obj.roundNumber !== "number") return null;
+
+		const combatants = obj.combatants as unknown[];
+		for (const c of combatants) {
+			if (typeof c !== "object" || c === null || Array.isArray(c)) return null;
+			const entry = c as Record<string, unknown>;
+			if (typeof entry.id !== "string") return null;
+			if (typeof entry.name !== "string") return null;
+		}
+
+		const rehydrated = combatants.map((c) => {
+			const entry = c as Record<string, unknown>;
+			return {
+				id: combatantId(entry.id as string),
+				name: entry.name as string,
+				initiative:
+					typeof entry.initiative === "number" ? entry.initiative : undefined,
+			};
+		});
+
+		const result = createEncounter(
+			rehydrated,
+			obj.activeIndex,
+			obj.roundNumber,
+		);
+		if (isDomainError(result)) return null;
+
+		return result;
+	} catch {
+		return null;
+	}
+}