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/api.ts

@@ -0,0 +1,47 @@
+// Client-side API helper. All requests are same-origin relative paths (they are
+// proxied by Vite in dev and served by Express in prod), so no origin is ever
+// hardcoded — this works unchanged behind the Traefik proxy.
+import type { GameState, Preset, PresetMeta } from '@shared/types';
+import type { AdvisorResponse, CreateGameResponse, TurnResponse } from '@shared/protocol';
+
+async function req<T>(path: string, init?: RequestInit): Promise<T> {
+  const res = await fetch(path, {
+    headers: { 'content-type': 'application/json' },
+    ...init,
+  });
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as { error?: string };
+    throw new Error(body.error ?? `HTTP ${res.status}`);
+  }
+  return res.json() as Promise<T>;
+}
+
+export const api = {
+  listPresets: () => req<{ presets: PresetMeta[] }>('/api/presets'),
+  getPreset: (id: string) => req<{ preset: Preset }>(`/api/presets/${id}`),
+  createGame: (presetId: string, playerNationId: string) =>
+    req<CreateGameResponse>('/api/games', {
+      method: 'POST',
+      body: JSON.stringify({ presetId, playerNationId }),
+    }),
+  getGame: (id: string) => req<{ game: GameState }>(`/api/games/${id}`),
+  turn: (id: string, action?: string, chat?: { to: string; message: string }) =>
+    req<TurnResponse>(`/api/games/${id}/turn`, {
+      method: 'POST',
+      body: JSON.stringify({ action, chat }),
+    }),
+  jump: (id: string) =>
+    req<TurnResponse>(`/api/games/${id}/jump`, {
+      method: 'POST',
+      body: JSON.stringify({}),
+    }),
+  advisor: (id: string, prompt?: string) =>
+    req<AdvisorResponse>(`/api/games/${id}/advisor`, {
+      method: 'POST',
+      body: JSON.stringify({ prompt }),
+    }),
+  map: (id: string) =>
+    req<{ regions: Record<string, { color: string; owner: string; ownerId: string }> }>(
+      `/api/games/${id}/map`,
+    ),
+};

src/lib/colors.ts

@@ -0,0 +1,29 @@
+// Small color maps for the "command center" theme. Pure + shared so the event
+// feed, nation panel, and any future view all agree on a type/status → color.
+import type { EventOutcome, EventType, RelationStatus } from '@shared/types';
+
+export const EVENT_COLORS: Record<EventType, string> = {
+  military: '#ef4444',
+  diplomatic: '#3b82f6',
+  economic: '#22c55e',
+  political: '#f59e0b',
+  social: '#06b6d4',
+  disaster: '#f97316',
+  scientific: '#a855f7',
+  cultural: '#ec4899',
+};
+
+export const RELATION_COLORS: Record<RelationStatus, string> = {
+  ally: '#22c55e',
+  neutral: '#94a3b8',
+  rival: '#f59e0b',
+  hostile: '#f97316',
+  war: '#ef4444',
+};
+
+export const OUTCOME_COLORS: Record<EventOutcome, string> = {
+  success: '#22c55e',
+  failure: '#ef4444',
+  partial: '#f59e0b',
+  neutral: '#94a3b8',
+};

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]);
+}

src/lib/utils.ts

@@ -0,0 +1,7 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/** shadcn/ui class combiner. */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}