History: AI-driven alternate-history simulator

Pax Historia-style sim where the LLM is the world engine.

- React 19 + Vite 6 + Tailwind v4 + shadcn/ui frontend
- Express single-port backend (/api + /sse + built client + SPA fallback)
- SQLite (better-sqlite3) persistence, one row per game
- MapLibre choropleth map (OpenFreeMap dark + ISO_A3 regions)
- Defensive turn loop: strip fences, balanced-{} extract, parse, clamp 0-100,
  retry-once nudge, generic 'unclear' fallback; never crashes on bad output
- 5 seed presets (wwii-1939, coldwar-1955, modern-2025, no-wwii-1940, aegis-2400)
- LLM client over native fetch w/ injectable transport (mesh-bot pattern);
  LLM_STUB=1 deterministic transport for tests/e2e
- Unit (vitest, 19) + deterministic Playwright e2e
- Multi-stage node:22-slim Docker + Traefik (history.dev.kkhost.pl:4321)

Co-Authored-By: OpenCode <opencode@users.noreply.github.com>

src/lib/sse.ts

@@ -0,0 +1,44 @@
+import { useEffect, useRef } from 'react';
+import type { GameState } from '@shared/types';
+import type { TurnResult } from '@shared/protocol';
+
+interface SseHandlers {
+  onState?: (state: GameState) => void;
+  onTurn?: (state: GameState, result: TurnResult) => void;
+}
+
+/**
+ * Subscribe to a game's SSE stream. The server sends a `state` event on connect
+ * and a `turn` event after every turn; EventSource auto-reconnects on drop, so a
+ * reload always resyncs to the persisted server state.
+ *
+ * Handlers are kept in a ref so the (id-keyed) effect always invokes the latest
+ * callbacks without re-subscribing on every render.
+ */
+export function useSse(id: string | null, handlers: SseHandlers): void {
+  const handlersRef = useRef(handlers);
+  handlersRef.current = handlers;
+
+  useEffect(() => {
+    if (!id) return;
+    const es = new EventSource(`/sse/${id}`);
+    const onState = (e: MessageEvent) => {
+      try {
+        handlersRef.current.onState?.(JSON.parse(e.data).state as GameState);
+      } catch {
+        /* ignore malformed */
+      }
+    };
+    const onTurn = (e: MessageEvent) => {
+      try {
+        const d = JSON.parse(e.data) as { state: GameState; result: TurnResult };
+        handlersRef.current.onTurn?.(d.state, d.result);
+      } catch {
+        /* ignore malformed */
+      }
+    };
+    es.addEventListener('state', onState);
+    es.addEventListener('turn', onTurn);
+    return () => es.close();
+  }, [id]);
+}