Merge pull request 'feat(#58): trade & embargoes — economy layer (v0.35.0)' (#69) from feat/58-trade-embargo into master

Promote the bare 'war' relation to a named War entity in GameState.wars:
- War: { id, sides[], declaredTurn, declaredDate?, aims?, status, front? }
- TurnResult.wars: { declare: WarDeclareOp[], end: WarEndOp[] }
- syncWarRelations: derive 'war' from active wars, fallback to 'hostile' on end
- Mutual-defense drag-in: belligerent allies added to sides (one level)
- Bare 'war' back-compat: never downgraded, never force-created
- Stub: empty wars (e2e unaffected); ~30 new unit tests

v0.33.0

AGENTS.md

@@ -28,13 +28,17 @@ renders territorial ownership; the whole thing persists to SQLite and streams ov
 - Backend: Node 22 + Express — one process serving the built client, `/api` (REST), and `/sse`
 - Persistence: `better-sqlite3` (one row per game, full `GameState` as JSON)
 - Map: MapLibre GL (`maplibre-gl`) — remote OpenFreeMap `dark` basemap + a **sub-national**
-  choropleth from `public/regions.geo.json` (1,796 sub-regions; feature `id` = `<ISO_A3>-<nn>`,
+  choropleth from `public/regions.geo.json` (1,800 sub-regions; feature `id` = `<ISO_A3>-<nn>`,
   `properties.parent` = the country's ISO_A3). Ownership is at **region-key** granularity
   (v0.19, #16 P1): every sub-region is addressed by a stable key from
   `public/region-keys.json`, `Nation.territory` holds those keys, and each sub-region is
   colored by its own owner. Since v0.21 (#16 P2) the LLM moves *individual* sub-regions
   across shared land borders (frontier-biased transfers, verified with the `getNeighbours`
-  function-calling tool) instead of whole countries.
+  function-calling tool) instead of whole countries. Since v0.25 (#31) the old RU-ARK
+  mega-region is split into the mainland (`RU-ARK`, key unchanged) plus the New Earth
+  (`RU-ARK-NE`) and Severnaya Zemlya (`RU-ARK-SZ`) island groups; since v0.26 (#41) the
+  mainland's 28-part Arctic-coast band is further re-partitioned into Pechora (`RU-PEO`)
+  and Yamal (`RU-YAM`) (the 5-part lat < 68 core stays `RU-ARK`/`arkhangel-sk-lhbk`).
 - The LLM client is a thin OpenAI chat-completions wrapper over native `fetch` with an
   **injectable transport** (mirrors `mesh-bot/src/llm`), with two entry points: plain
   `chat()` and `chatWithTools()` — a bounded OpenAI function-calling loop (max 6 tool
@@ -52,31 +56,44 @@ history/
 ├── eslint.config.js        # flat config (ESLint 9)
 ├── tsconfig.json           # strict; aliases @/ → src/, @shared/ → shared/
 ├── vite.config.ts          # dev server + proxy /api,/sse → :4321; @ / @shared aliases
-├── vitest.config.ts        # unit tests (server/**/*.test.ts + scripts/**/*.test.ts; 127 tests)
+├── vitest.config.ts        # unit tests (server/**/*.test.ts + scripts/**/*.test.ts; 407 tests)
 ├── playwright.config.ts    # deterministic e2e (webServer runs npm run dev, LLM_STUB=1)
 ├── index.html
 ├── presets/                # 5 scenario JSON files + index.json (manifest)
 ├── public/
 │   ├── countries.geo.json  # 177 countries, id=ISO_A3 (input to the region generator)
-│   ├── regions.geo.json    # 1,796 sub-regions, id=<ISO_A3>-<nn>, parent=ISO_A3 (the choropleth)
-│   ├── region-keys.json    # feature id -> region key, 1,796 entries (the ownership/LLM address space, #16 P1)
-│   └── region-adjacency.json # region key -> bordering region keys, 1,796 entries (the getNeighbours data, #16 P2)
+│   ├── regions.geo.json    # 1,800 sub-regions, id=<ISO_A3>-<nn>, parent=ISO_A3 (the choropleth)
+│   ├── region-keys.json    # feature id -> region key, 1,800 entries (the ownership/LLM address space, #16 P1)
+│   ├── region-adjacency.json # region key -> bordering region keys, 1,800 entries (the getNeighbours data, #16 P2)
+│   ├── region-centroids.json # region key -> {lat,lon,spread} anchor for map markers, 1,800 entries (#44)
+│   ├── region-geo.json     # region key -> {area (km²), population}, 1,800 entries (the area×population weighting for per-region stats, #46)
+│   └── ne-admin0-pop.json  # ISO_A3 -> admin-0 POP_EST, 249 codes (the committed population SOURCE for region-geo.json — a small derived table, the 13 MB Natural Earth source is NOT committed, #46)
 ├── scripts/                # the geo/manifest data pipeline — .mjs (turf allowed HERE only;
 │   │                       #   never imported by .ts): generate → coarsen → cleanup → smooth →
-│   │                       #   fill-gaps → build-region-keys → build-region-adjacency
-│   └── *.test.ts           # turf-free vitest tests pinning the dataset + both manifests
+│   │                       #   fill-gaps → split-arkhangel → split-arkhangel-band → build-region-keys
+│   │                       #   → build-region-adjacency → build-region-centroids → build-region-geo
+│   │                       #   (build-region-geo reads the COMMITTED ne-admin0-pop.json; that small
+│   │                       #   table is distilled once from the 13 MB Natural Earth admin-0 source by
+│   │                       #   extract-admin0-pop.mjs — the raw source is never committed, #46)
+│   └── *.test.ts           # turf-free vitest tests pinning the dataset + the manifests
 ├── shared/                 # NO runtime deps — the single source of truth
 │   ├── types.ts            #   domain types (Nation, GameState, RoundItem, Preset, …)
-│   └── protocol.ts         #   LLM TurnResult schema (incl. `unowned`, v0.22 #16 P3) + AddAction/AddDiplomacy/RemoveQueueItem/Jump request types + pure helpers (incl. the no-man's-land map-presentation contract)
+│   └── protocol.ts         #   LLM TurnResult schema (incl. `unowned`, v0.22 #16 P3, and
+│                           #     `nationOps`, v0.23 #16 P4a; v0.24 #16 P4b) + AddAction/AddDiplomacy/RemoveQueueItem/
+│                           #     Jump + NationOp confirm/reject request types + pure helpers
+│                           #     (incl. per-region stats, v0.28 #46: weightedMedian / deriveNationStats /
+│                           #     seedRegionStats / migrateRegionStats)
 ├── server/
-│   ├── index.ts            # Express: /api/* (health|action|diplomacy|queue/remove|jump|advisor|games|map|presets), /sse/:id; reads PORT/LLM_*/DATA_DIR
-│   ├── engine.ts           # pure: prompts / parse+validate / applyTurnResult (sole-ownership + no-man's-land releases, v0.22 #16 P3) / runTurn (tool path + plain fallback) / getNeighbours tool + executor / playerFrontier / queue ops / advisor
+│   ├── index.ts            # Express: /api/* (health|action|diplomacy|queue/remove|jump|advisor|
+│   │                       #   nation-op/confirm|nation-op/reject|games|map|presets), /sse/:id; reads
+│   │                       #   PORT/LLM_*/DATA_DIR
+│   ├── engine.ts           # pure: prompts / parse+validate / applyTurnResult (sole-ownership + no-man's-land releases, v0.22 #16 P3; per-region stats maintenance + derived recompute, v0.28 #46) / runTurn (tool path + plain fallback) / getNeighbours tool + executor / playerFrontier / queue ops / advisor / nation-op ops (resolveNationRef / freshNationId / NEW_NATION_STATS / applyNationOp rename+split+merge / confirmNationOp / rejectNationOp, v0.23 #16 P4a; v0.24 #16 P4b)
 │   ├── llm.ts              # LlmClient: chat() + chatWithTools() (bounded function-calling loop), injectable transport, retry+backoff, logging + env config
-│   ├── regions.ts          # turf-free region-key data access: load manifest/geo/adjacency (public/ then dist/), country→keys expansion, reference table, neighboursOf/hasAdjacency
+│   ├── regions.ts          # turf-free region-key data access: load manifest/geo/adjacency/centroids/geo-manifest (public/ then dist/), country→keys expansion, reference table, neighboursOf/hasAdjacency, centroidOf/hasCentroids, geoOf/hasGeo (#46)
 │   ├── stub.ts             # deterministic LLM transport (tests/e2e): one frontier conquest per turn + ADVISOR_MARKER
 │   ├── map.ts              # GameState → RegionMap (region key → owner + stable color)
 │   ├── presets.ts          # load preset JSON files from disk
-│   ├── db.ts               # SQLite open/save/load
+│   ├── db.ts               # SQLite open/save/load (+ legacy regionStats migration on load, v0.28 #46)
 │   └── *.test.ts           # unit tests (vitest)
 └── src/
     ├── App.tsx             # screen router (home → pick → game) + manual hash router (#/game/<id>); owns game/regions/advisors/busy
@@ -91,7 +108,8 @@ history/
         ├── PresetPicker.tsx / NationSelect.tsx   # home + nation pick screens
         ├── WorldMap.tsx     # MapLibre basemap + choropleth + click→dossier + hover tooltip + player highlight
         ├── NationPanel.tsx  # a nation's stats/territory/diplomacy dossier
-        ├── ActionPanel.tsx  # tabs: Action / Diplomacy / Advisor + pending-queue list (per-item trash button + confirm dialog) + "Jump forward"
+        ├── ActionPanel.tsx  # tabs: Action / Diplomacy / Advisor + pending-queue list (per-item trash button + confirm dialog) + "Jump forward" + "Nation proposals" trigger (v0.23 #16 P4a)
+        ├── NationOpDialog.tsx # review LLM-proposed nation ops (rename/split/merge) — confirm (editable rename/merge name, split successor radio) or reject (v0.24 #16 P4b)
         ├── EventFeed.tsx    # scrolling event log (newest first)
         ├── FloatingWindow.tsx # the HUD window primitive — free-floating (draggable, position persisted), or `pinned` (fixed top-center bar), or `dock`ed (full-height left/right column); renders dock controls when `onDockChange` is set
         ├── StatBar.tsx
@@ -105,11 +123,15 @@ history/
 | `npm run dev` | Express on :4321 (tsx watch) + Vite on :5173 (proxies `/api`,`/sse`) concurrently |
 | `npm run build` | `vite build` (client → `dist/`) then `tsup server/index.ts` → `server/dist/index.js` |
 | `npm start` | run the compiled server (`node server/dist/index.js`) on :4321 |
-| `npm test` | vitest unit tests (`server/` + `scripts/`; 127 tests) |
+| `npm test` | vitest unit tests (`server/` + `scripts/`; 225 tests) |
 | `npm run typecheck` | `tsc --noEmit` (strict) across src/server/shared/e2e/configs |
 | `npm run lint` | ESLint flat config |
 | `npm run e2e` | Playwright, fully deterministic (`LLM_STUB=1`); **runs in CI on every PR** (see below) |
-| `npm run build:region-keys` / `build:region-adjacency` | (re)generate the `public/region-keys.json` / `region-adjacency.json` manifests — deterministic + idempotent (byte-identical re-run) |
+| `npm run split:regions` | (re)apply the #31 Arkhangel'sk split (`RU-ARK` → mainland + `RU-ARK-NE` + `RU-ARK-SZ`) — idempotent no-op once applied |
+| `npm run split:regions:band` | (re)apply the #41 Arctic-coast-band split (`RU-ARK` mainland's 28-part lat ≥ 68 band → `RU-PEO` + `RU-YAM`) — idempotent no-op once applied |
+| `npm run build:region-keys` / `build:region-adjacency` / `build:region-centroids` | (re)generate the `public/region-keys.json` / `region-adjacency.json` / `region-centroids.json` manifests — deterministic + idempotent (byte-identical re-run) |
+| `npm run build:region-geo` | (re)generate `public/region-geo.json` (region key → area km² + population) from `regions.geo.json` + `region-keys.json` + the committed `ne-admin0-pop.json` — deterministic + idempotent (byte-identical re-run; #46) |
+| `npm run extract:admin0-pop` | one-time distillation of the 13 MB Natural Earth admin-0 source → the committed `public/ne-admin0-pop.json` (ISO_A3 → `POP_EST`, 249 codes); the raw source is never committed (#46) |
 | `docker compose up -d --build` | prod image on :4321, routed via Traefik at `history.dev.kkhost.pl` |
 
 **Local verification (before every PR):** `npm run typecheck` + `npm run lint` + `npm test` (unit) + `npm run build`. The full **e2e** suite (`npm run e2e`) is verified by **CI on every PR** (the Playwright config boots its own dev webServer with `LLM_STUB=1`) — locally you only need the four checks above; e2e is the CI source of truth.
@@ -183,7 +205,208 @@ history/
   "No man's land" tooltip sub-line) while a preset-unassigned key keeps the faint look ("No owner")
   — the distinction is decided by the client from `GameState.unowned` (via `regionFillStyle` /
   `unownedTooltipLabel`), never by the `RegionMap`, which only knows "owned" vs "absent". A fresh
-  game always starts with `unowned: []` (legacy SQLite rows load with it defaulted).
+  game always starts with `unowned: []` (legacy SQLite rows load with it defaulted). Since v0.25
+  (#31) the 78-part RU-ARK mega-region is split into three features — mainland `RU-ARK` (its key
+  `arkhangel-sk-lhbk` is **unchanged**, so existing ownership is safe), `RU-ARK-NE` (New Earth /
+  Franz Josef Land, `new-earth-eikt`) and `RU-ARK-SZ` (Severnaya Zemlya,
+  `severnaya-zemlya-awqp`) — by the idempotent `scripts/split-arkhangel.mjs` stage (run between
+  `fill:regions` and `build:region-keys`, no-op once applied); the two island groups get their own
+  region keys and adjacency entries (New Earth is genuinely isolated → empty adjacency; Severnaya
+  Zemlya's islet rings touch the coarsened mainland ring, so it records one SZ↔mainland pair).
+  Since v0.26 (#41) the mainland's 28-part Arctic-coast band (centroid lat ≥ 68) is further
+  re-partitioned by the idempotent `scripts/split-arkhangel-band.mjs` stage (run between
+  `split:regions` and `build:region-keys`, no-op once applied) into Pechora (`RU-PEO`,
+  `pechora-qwhs`, 13 parts) and Yamal (`RU-YAM`, `yamal-gosw`, 15 parts) — a pure re-partition
+  (no geometry moved → the union is byte-identical) that keeps `RU-ARK`'s id/name/key
+  `arkhangel-sk-lhbk` stable and inserts the two new features immediately after `RU-ARK-SZ`; the
+  5-part lat < 68 core stays `RU-ARK` (a single ~305k km² polygon — splitting it needs turf
+  clipping, not a pure re-partition).
+- **Nation ops — “LLM proposes, player confirms” (v0.23, #16 P4a; v0.24, #16 P4b).**
+  `TurnResult.nationOps` (required in the schema) carries the LLM’s proposed **`NationOp`s** — a
+  discriminated union of `rename` / `split` / `merge`, all three of which are now applied on confirm
+  (P4b implemented split/merge). Each op names its target via `nationRef` — the LLM may use a
+  nation’s **id or name**; `resolveNationRef` resolves id-first, then a case-insensitive
+  unique-name match, and returns `null` for an unknown or ambiguous ref (such ops are dropped
+  defensively in `validateNationOps`, never thrown). A turn’s ops are appended to
+  `GameState.pendingNationOps`, which is **never cleared on a turn commit** — pending proposals
+  persist across turns until resolved (like the action queue). The player then decides per op via
+  `POST /api/games/:id/nation-op/confirm` (`{index, edits?{name?, playerPart?}}`) or
+  `.../nation-op/reject` (`{index}`): `confirmNationOp` applies the op to a clone — **rename** sets
+  `Nation.name` to the edited value or, failing that, the proposed `to` (id / territory / relations /
+  `playerNationId` stay valid, so a renamed player is re-named in place); **split** (the parent
+  must resolve and have ≥2 named parts, else a no-op) partitions the parent’s region-key territory
+  into new nations in parts order — each new nation gets a fresh id (`freshNationId`: first free of
+  `n1`, `n2`, …) and the baseline `NEW_NATION_STATS` (not a copy of the parent’s), plus a copy of
+  the parent’s relations; a key named by several parts goes to the first, and the parent’s
+  unclaimed keys go to part 0 (in territory order), so sole ownership holds and nothing is
+  orphaned; if the parent was the player’s nation, `playerNationId` moves to the part chosen by
+  `edits.playerPart` (clamped into range, default 0), which also receives `edits.name`; **merge**
+  (every ref must resolve, ≥2 DISTINCT inputs, and the survivor must be one of them, else a
+  no-op) folds the inputs into the survivor, which keeps its id and its own stats, gains the
+  union of the inputs’ territories (the survivor’s keys first) and a union of their relations
+  (the survivor’s own view of a third party wins, else the first input’s), is renamed
+  `edits.name` → `into` → its own name, while the other inputs are removed and their ids dropped
+  from every remaining nation’s relations maps; if the player led a removed input,
+  `playerNationId` moves to the survivor. An op that is invalid at confirm time (an ambiguous ref,
+  …) is a no-op on the world but is still removed — and `rejectNationOp` just drops it; both
+  splice by index and bump `version` once (an invalid index → `null` → HTTP 400). The response is
+  `{ game }` and the server broadcasts a version-bumped SSE `state`, so every tab’s
+  version-guarded `applyState` stays in sync. The client lists the pending ops in a “Nation
+  proposals” dialog (in the “Your move” panel): a rename and a merge show an editable name field
+  (the merge also highlights the survivor among the input chips); a split lists each part (name +
+  proposed region count) with a successor radio that appears only when the parent is the player’s
+  own nation (preselected part 0 — the choice is always valid). The system prompt documents all
+  three op shapes as a proposal queue (at most 1–2 per turn, each narrated in events). The stub
+  never proposes a nation op (`nationOps: []`), so this path is covered by unit tests only
+  (`server/engine.test.ts`).
+- **Map markers (v0.27, #44) — LLM-placed named points, region-anchored, canvas-icon rendered.**
+  The LLM can place named **point markers** on the map each turn: eight `MarkerType`s
+  (`city, factory, army, port, capital, fleet, rocket, gathering`; a **capital** is at most one
+  per nation, a **gathering** a political/social mass event that can enable a non-military
+  takeover). `TurnResult.markers = { add: MarkerSpec[]; remove: string[] }` (both required,
+  default `[]`; `MarkerSpec = { type, name, regionKey }`). A marker's stable `id` is the FNV-1a
+  32-bit hash of `` `${type}\u0000${name}\u0000${regionKey}` `` rendered as four lowercase
+  base-26 characters (mirroring the region-key scheme) — so a **re-add is idempotent** and a
+  **remove is unambiguous** (by id). `GameState.markers: MapMarker[]` is required (`[]` at game
+  creation; a legacy SQLite row without the field loads as `[]` — additive, never wipes).
+  `applyTurnResult` handles markers **after** territory claims: (1) remove by id (absent id →
+  no-op); (2) **recompute every surviving marker's `ownerNationId` from the final post-claim
+  ownership** — a marker always follows its region (a captured region follows its new owner; a
+  region released to no man's land, or a key with 0 or 2+ owners, becomes `null`); (3) add — each
+  new spec is placed at its region's centroid (from `public/region-centroids.json`, injected via
+  the optional `centroidOf` param on `applyTurnResult`) plus a deterministic per-axis jitter
+  (`spread ≈ 0.1 × the largest part's smallest bbox dimension`, so multiple markers of one region
+  scatter instead of stacking), owned by the region's post-turn owner, stamped with the acting
+  turn. Adds are **dropped, never thrown**, when the region key is unknown or has no centroid,
+  when the id already exists, or beyond the hard cap `MAX_MARKERS = 400`. The system prompt
+  documents the field + types + placement rules; `buildUserPrompt` carries the current markers
+  (as `MarkerInfo[]`) so the model can reference their ids in `remove`; a marker add/remove makes
+  a turn "meaningful". **Rendering is canvas-generated per-type ICON images, NOT text labels**
+  (`src/components/WorldMap.tsx`): every external glyph/font endpoint is a dead 404 (OpenFreeMap's
+  `fonts/{stack}/{range}.pbf` and `demotiles.maplibre.org/font/…`) and the OFM dark basemap only
+  renders because it is **raster** (labels baked into the tiles) — there is no working vector
+  font, so markers are drawn as self-contained, offline, deterministic per-type icons
+  (`drawMarkerIcon`: distinct shape per type, filled with the type color, outlined for legibility),
+  registered as named `ImageData` images that survive `styledata`. The marker **name shows in the
+  hover tooltip** (not a persistent on-map label), and **clicking a marker focuses its owning
+  nation's dossier**. There are **no separate marker event handlers** — MapLibre's per-layer event
+  delegates fire independently (no `stopPropagation`), so the region hover/click handlers instead
+  `queryRenderedFeatures` the marker layer under the cursor and act on the marker when present.
+  The **stub is marker-free** (`markers: { add: [], remove: [] }`) — e2e (CI, `LLM_STUB=1`) is
+  unaffected and the marker path is unit-tested only (`server/engine.test.ts`,
+  `scripts/region-centroids.test.ts`, `server/regions.test.ts`, `server/db.test.ts`).
+- **Per-region stats — `GameState.regionStats`, derived `Nation.stats` (v0.28, #46; PR 1 of 2 — the LLM lever is PR 2).**
+  Since v0.28 the four 0–100 stats live at **region-key** granularity: `GameState.regionStats`
+  (required; `{}` at game creation) maps each owned region key to its own `RegionStats`, and
+  `Nation.stats` is **derived** — the **area×population-weighted median** of the stats of the
+  regions the nation owns (`deriveNationStats`, pure in `shared/protocol.ts`). A region's weight
+  is `(area>0?area:1)×(population>0?population:1)` from the committed `public/region-geo.json`
+  manifest (1,800 entries; area in km² at 2dp, integer population) — which is built by
+  `scripts/build-region-geo.mjs` from `regions.geo.json` + `region-keys.json` + the committed
+  `public/ne-admin0-pop.json` (Natural Earth admin-0 `POP_EST`, 249 codes, one-time distilled by
+  `scripts/extract-admin0-pop.mjs`; each country's `POP_EST` is spread over its sub-regions
+  proportional to area by largest-remainder, so per-country totals are preserved exactly). A
+  released / 0-owner / 2+-owner key has **no** entry. A fresh game is seeded by
+  `seedRegionStats` (every owned region gets a **copy** of its owner's stats — identical values,
+  so the derived median equals the original and fresh-game numbers are unchanged). Legacy SQLite
+  rows are migrated once on load by `migrateRegionStats` (`db.load`, called without `geoOf` —
+  weight-invariant for the identical-value seed): a row that already has `regionStats` (v0.28+)
+  is returned **unchanged** (never recomputed on load → no drift), a legacy row is seeded +
+  recomputed (0-region guard keeps its stats). `applyTurnResult` takes an optional `geoOf`
+  (passed through `runTurn`; the jump route wires it via `hasGeo() ? (key) => geoOf(key) :
+  undefined`) and maintains the table inside the **load-bearing order events → relations →
+  territory → stateChanges → recompute → markers → nationOps**: a release deletes the key's
+  entry; a (re-)claim re-inits an absent entry as a copy of the gainer's current `stats`;
+  nation-level `stateChanges` (the only LLM lever for now — the prompt is **unchanged** in this
+  PR) write to `n.stats` **and** to every region the nation owns; then every nation with ≥1
+  entered region gets `stats` recomputed as its regions' weighted median (a 0-region — or no-
+  entered-region — nation keeps its directly-maintained `stats`, which is why the existing unit
+  and e2e assertions pass unchanged; without the geo manifest the recompute degrades to an
+  unweighted median, never throwing). The stub never touches per-region stats (`LLM_STUB=1`
+  e2e unaffected), and the path is unit-tested (`server/engine.test.ts`,
+  `server/protocol.test.ts`, `server/db.test.ts`, `server/regions.test.ts`,
+  `scripts/region-geo.test.ts`). **PR 1 of 2 — deliberately NOT deployed** (the user deploys
+  when PR 2, the per-region LLM lever, ships).
+- **Wars — `GameState.wars`, a first-class conflict entity (v0.33, #56).**
+  Since v0.33 the `war` relation is no longer a bare boolean flag but a named `War` entity in
+  `GameState.wars` (required, `[]` at creation; a legacy SQLite row without the field loads as
+  `[]` — additive, never wipes). Each `War` has a stable id (`w1`, `w2`, …), a `sides` list
+  (≥2 distinct nation ids — any two distinct members are at war with each other), `declaredTurn`,
+  `declaredDate`, optional `aims`, a `status` (`active` / `armistice` / `capitulation`), and an
+  optional `front` (region keys). `TurnResult.wars = { declare: WarDeclareOp[]; end: WarEndOp[] }`
+  (both required, default `[]`): a **declare** creates a new active `War` (sides resolved via
+  `resolveNationRef` — id first, then case-insensitive unique name; a declare with <2 resolved
+  distinct sides is dropped); an **end** finds a war by id (unknown → no-op, never throw) and sets
+  its `status` to the outcome (`armistice` or `capitulation`). After declare/end,
+  `syncWarRelations(prev, next)` enforces the derived `war` relation: any two nations on opposite
+  sides of ≥1 **active** war get `war` in both directions (overriding lesser statuses — you
+  cannot "make peace" without ending the war); when a war ends, the pairs it caused that are not
+  covered by another active war fall back to `hostile`. A **bare** `war` relation with no matching
+  active war (legacy/back-compat) is never downgraded and never force-created. **Mutual-defense
+  drag-in**: when a war is declared, each belligerent's `ally`-relation partners are added to the
+  war's `sides` (one level, no cascade; deterministic — sides in declared order, allies in sorted
+  id order). The system prompt documents the field + declare/end ops (at most 1–2 declarations
+  per turn, each narrated in `events`); `buildUserPrompt` carries the current **active** wars
+  (as `WarInfo[]`: id + sides + aims) so the model can `end` by id. The **stub never declares or
+  ends** a war (`wars: { declare: [], end: [] }`) — e2e (CI, `LLM_STUB=1`) is unaffected and the
+  path is unit-tested only (`server/engine.test.ts`).
+- **Hybrid war — `TurnResult.hybrid`, a deterministic non-kinetic operations spectrum (v0.34, #57).**
+  `TurnResult.hybrid = { ops: HybridOp[] }` (required; default `{ ops: [] }`) adds a covert /
+  hybrid-warfare spectrum alongside the kinetic `regionChanges` lever: `HybridOp =
+  { type, from, target, detail?, outcome? }` with `type ∈ spy | sabotage | assassinate |
+  cyber | economic | information | proxy` and `outcome ∈ success | exposed` (the LLM
+  declares its *intended* outcome; the engine applies the deterministic effect).
+  `from`/`target` are refs resolved by the shared `resolveNationRef` (id first, then
+  case-insensitive unique name); a `target` that is not a resolvable nation is treated
+  as a region key — it hits that region's SOLE owner (a key with 0 or 2+ owners — or the
+  acting nation itself — is dropped, never thrown). Per type: `sabotage` dips `economy`
+  (−3), `economic` dips `economy` (−5), `cyber` dips `military` (−3), `assassinate` dips
+  `stability` (−5); `information` nudges the from↔target relation one step apart (capped
+  at `hostile`), `proxy` likewise but capped at `rival`; `spy` is informational only.
+  A region-target dip lands on the single `regionStats[regionKey]` entry (hybrid ops
+  never move territory — `regionChanges` is the only lever that does); a nation-target
+  dip lands on every region the nation owns; afterwards the target's derived `stats` is
+  re-derived (0-region / no-entry guards), so the effect persists and the sole-ownership
+  invariant is untouched. **Exposed** (`outcome: "exposed"`) is a backfire: the intended
+  effect is NOT applied; instead the from↔target relation moves one step *toward*
+  `hostile` (capped; `war` is never created or escalated by an exposed op) and a
+  diplomatic/failed event is auto-appended to the turn's `events`.
+  **Additive only — no `GameState.hybrid` field, no `db.ts` change** (the ops are
+  consumed inside `applyTurnResult` after territory + wars and before markers).
+  `isMeaningful` counts hybrid ops; the system prompt documents the field + per-type
+  effects (the "unclear" fallback and the stub both return `hybrid: { ops: [] }`), and the
+  user payload carries the player's `relations` map so the model can reason about the
+  relation caps. The **stub never** proposes a hybrid op, so e2e (CI, `LLM_STUB=1`) is
+  unaffected and the path is unit-tested only (`server/engine.test.ts`).
+- **Trade & embargo economy layer — `GameState.trades` / `GameState.embargoes`, `TurnResult.economy` (v0.35, #58).**
+  `TurnResult.economy = { trade: EconomyTradeOp[]; embargo: EconomyEmbargoOp[] }` (required;
+  default `{ trade: [], embargo: [] }`) is the model's lever for the economic layer: a
+  bilateral **trade** (`{ a, b, lift? }` — symmetric, stored **sorted** `a < b`) and a
+  unilateral **embargo** (`{ from, target, lift? }` — ordered). No `lift` declares/imposes,
+  `lift: true` ends/lifts (a no-op when absent). Refs are resolved at apply time by the
+  shared `resolveNationRef` (id first, then case-insensitive unique name); an unknown /
+  ambiguous / self-pairing op is dropped (never thrown). The lists live in `GameState`
+  (`trades`/`embargoes`, required, `[]` at creation; a legacy SQLite row without them loads
+  as `[]` — additive, never wiped, like `wars`/`markers`). **Deterministic, no hidden
+  randomness.** Every committed turn, in `applyTurnResult` (after hybrid, before markers):
+  (1) `applyEconomyOps` applies this turn's declares/lifts to the active lists (idempotent
+  declares — an already-active pair/ordered pair is not duplicated); (2)
+  `suspendEconomyOnWar` **auto-suspends** any trade or embargo whose two nations are on
+  opposite sides of an **active** `War` (#56) — a war severs the economic link, so the
+  suspended pair stops producing its effect (this also drops a trade declared this turn
+  between two nations that just went to war); (3) `applyEconomyEffects` applies the per-turn
+  effect to the **full** active lists: each active trade gives **both** parties a small,
+  deterministic `economy` gain (`TRADE_ECONOMY_BONUS`), each active embargo dips the
+  **target's** `economy` only (`EMBARGO_ECONOMY_PENALTY`) — clamped to 0–100, mirrored to
+  every region the nation owns (`regionStats`), and each affected nation's derived `stats`
+  re-derived afterwards (same 0-region / no-entry guards as the hybrid dip). Sole ownership
+  is untouched (the layer moves stats, never territory). `isMeaningful` counts non-empty
+  `economy.trade` / `economy.embargo`; the system prompt documents the field + constraints
+  (at most 1–2 ops per turn, narrated in `events`; warring pairs auto-suspended), and the
+  user payload carries the active `trades`/`embargoes` so the model can `lift` them. The
+  **stub never** declares or lifts a trade/embargo (`economy: { trade: [], embargo: [] }`),
+  so e2e (CI, `LLM_STUB=1`) is unaffected and the path is unit-tested only
+  (`server/engine.test.ts`).
 - **Map click → dossier target (owner resolved from the RegionMap, by region key).**
   Clicking a sub-region does NOT open a popup — it switches the dossier to that sub-region's
   owning nation (`focusNation(ownerId, {name})` in `App.tsx`, which also records which region was
@@ -209,9 +432,12 @@ history/
   in `wwii-1939`) transfers nothing. Since v0.22 (#16 P3) the stub **never releases** a region to
   no man's land (it always returns `unowned: []` and ignores the payload's `unowned` field) — its
   one-conquest behavior is what the e2e assertions rely on, so the release/re-claim path is
-  covered by unit tests only (`server/engine.test.ts`, `server/map.test.ts`). The stub answers
-  plain `content` (never tool calls), so it naturally bypasses the tool loop in a single round.
-  Unit + e2e assertions rely on these exact values, so keep the stub deterministic.
+  covered by unit tests only (`server/engine.test.ts`, `server/map.test.ts`). Since v0.23 (#16 P4a)
+  the stub also returns `nationOps: []` — it **never proposes** a nation op (rename/split/merge;
+  still true since P4b implemented split/merge), so the confirm/reject path is covered by unit
+  tests only, mirroring the P3 approach; all e2e assertions are unaffected. The stub answers plain `content` (never tool calls), so it naturally
+  bypasses the tool loop in a single round. Unit + e2e assertions rely on these exact values, so
+  keep the stub deterministic.
 - **HUD layout.** The game screen is a full-viewport map (z-0) with `FloatingWindow` overlays. The
   top bar is **pinned** — a fixed, non-movable bar centered at the top a few px down (it re-centers
   on resize and always floats above the other windows). The **dossier / event-feed / action**
@@ -301,7 +527,8 @@ history/
   (works on `node:22-slim`/glibc). It's the sole `--external` in the tsup server bundle.
 - The `dist/` client is committed to the build output only; the `public/` data files
   (`regions.geo.json` — the choropleth — `region-keys.json` + `region-adjacency.json` — the
-  ownership/adjacency manifests — and `countries.geo.json`) are copied into `dist/` by Vite at
+  ownership/adjacency manifests — `region-centroids.json` — the marker anchors (#44) — and
+   `countries.geo.json`) are copied into `dist/` by Vite at
   build time, so the prod image serves them from `dist/` (no separate copy). The server's region
   loader (`server/regions.ts`) probes `public/` then `dist/` for the manifest pair, because the
   Docker image keeps only `dist/` (the v0.20 fix — before it, region-level ownership silently

CHANGELOG.md

@@ -2,6 +2,205 @@
 
 All notable changes to **History** are listed here, newest first.
 
+## v0.35.0 — 2026-10-15 17:22
+- **#58: Trade & Embargoes — a bilateral trade + embargo economy layer with a deterministic per-turn effect and war auto-suspension.** Every prior turn lever moved borders, dipped stats one-shot, or proposed a player-confirmed change. This version adds `TurnResult.economy = { trade: EconomyTradeOp[]; embargo: EconomyEmbargoOp[] }` (required, default `{ trade: [], embargo: [] }`) so the model can declare/lift **bilateral trade agreements** and **unilateral embargoes**, which persist in `GameState` and apply a small, deterministic economic effect **every committed turn**. The engine is **fully deterministic (no hidden randomness)** and **additive** — declares add to the lists, lifts remove, and nothing else (not even a war, beyond the suspension below) mutates them.
+  - **Types (`shared/types.ts`).** New `TradeAgreement` (`{ a; b }` — a symmetric pair, stored sorted `a < b`) and `Embargo` (`{ from; target }` — an ordered unilateral pair) interfaces, plus the required `GameState.trades` and `GameState.embargoes` fields (placed after `wars`). Both are `[]` on a fresh game; rows saved before v0.35 load with them defaulted to `[]` (additive, never wiped).
+  - **Protocol (`shared/protocol.ts`).** New `EconomyTradeOp` (`{ a; b; lift? }`), `EconomyEmbargoOp` (`{ from; target; lift? }`), and `EconomyOps` (`{ trade; embargo }`) types. `TurnResult.economy` is required, placed between `hybrid` and `markers`; a no-`lift` op declares/imposes, `lift: true` ends/lifts.
+  - **Engine (`server/engine.ts`).**
+    - `validateEconomyOps(raw)` — new exported, defensive validator (never throws): a missing/malformed object yields `{ trade: [], embargo: [] }`; each op needs non-empty `a`/`b` (or `from`/`target`) refs (trimmed, ≤200 chars) and a boolean `lift` (default false). Raw refs are kept — resolution happens at apply time against the real state (like wars/hybrid ops).
+    - `applyEconomyOps(next, ops)` — internal; resolves each op's refs via `resolveNationRef` (id first, then unique case-insensitive name). An unresolvable / ambiguous / self-pairing op is dropped (never thrown). A no-`lift` trade **declares** the agreement idempotently (stored sorted, so `{a,b}` and `{b,a}` are the same pair); `lift: true` ends it (a no-op when absent). A no-`lift` embargo **imposes** the ordered from→target pair idempotently; `lift: true` lifts it.
+    - `suspendEconomyOnWar(next)` — internal; any active trade or embargo whose two nations are on **opposite sides of an active war** (v0.33, #56) is removed — a war severs the economic link, so the suspended agreement stops producing its per-turn effect from now on. Runs **after** the turn's war declare/end ops (so it sees the final `next.wars`, including a war declared this turn) and **before** the per-turn effect.
+    - `applyEconomyEffects(next, geoOf?)` — internal; the per-turn effect, applied **every committed turn** to the **full** active lists (not just this turn's declares): each active trade grants **both** parties a small, deterministic economy gain (`TRADE_ECONOMY_BONUS`); each active embargo applies a small, deterministic economy dip to the **target only** (`EMBARGO_ECONOMY_PENALTY`). Clamped to 0–100, mirrored to every region the nation owns (`regionStats`), and each affected nation's derived `stats` re-derived afterwards (same 0-region/no-entry guards as the hybrid dip). No-op when there are no active trades or embargoes; never throws.
+    - `applyTurnResult` — new **economy block** (after the hybrid block, before markers): `applyEconomyOps` → `suspendEconomyOnWar` → `applyEconomyEffects`, in that order (ops first, so a same-turn trade declared between two nations that just went to war is suspended; effects then run on the surviving full lists). Sole ownership is untouched (the economy layer moves stats, never territory).
+    - `isMeaningful` — a non-empty `economy.trade` or `economy.embargo` makes a turn meaningful.
+    - `validateTurnResult` — initializes and validates `economy` (default `{ trade: [], embargo: [] }`).
+    - `buildSystemPrompt` — documents the `economy` field and a constraint bullet (bilateral trade gains both parties; a unilateral embargo hits the target only; omit `lift` to declare/impose, `lift: true` to end/lift; at most 1–2 ops per turn, narrated in `events`; trades/embargoes between warring nations are auto-suspended) in both tool and plain modes.
+    - `buildUserPrompt` — new optional `trades` and `embargoes` params (the currently active agreements/embargoes) so the model knows what is active and can `lift` it; emitted only when provided.
+    - `runTurn` — passes `state.trades` and `state.embargoes` to `buildUserPrompt`; the "unclear" fallback carries `economy: { trade: [], embargo: [] }`.
+  - **Stub (`server/stub.ts`).** The deterministic stub returns `economy: { trade: [], embargo: [] }` — it **never** declares or lifts a trade or embargo, so the e2e (CI, `LLM_STUB=1`) assertions are unaffected and the path is covered by unit tests only (`server/engine.test.ts`).
+  - **Persistence (`server/db.ts`).** `load()` defaults `trades`/`embargoes` to `[]` on rows saved before v0.35 (additive migration, alongside `unowned`/`pendingNationOps`/`markers`/`wars`) — legacy games are never wiped and never gain phantom trades/embargoes.
+  - **Game creation (`server/index.ts`, `shared/scenario.ts`).** Fresh games (preset and dynamic) are created with `trades: []` and `embargoes: []`.
+
+## v0.34.0 — 2026-10-15 16:35
+- **#57: Espionage & Hybrid War — a non-kinetic operations spectrum with a deterministic per-type effect and an exposure backfire.** Every prior turn lever was kinetic (conquest, state-change, region-change, wars, takeovers) or a player-confirmed proposal (nation ops). This version adds `TurnResult.hybrid = { ops: HybridOp[] }` (required, default `{ ops: [] }`) so the model can run **covert, non-kinetic** operations: spies, sabotage, assassination attempts, cyberattacks, economic pressure, disinformation, and proxy support. Unlike territory these **never move borders** — they dip a target's stats or sour a relation. The engine is **fully deterministic (no hidden randomness)**: the LLM declares an intended `outcome` (`success` by default, or `exposed`); a successful op applies its small per-type effect, an `exposed` op **backfires** (no effect, the actor's relation with the target sours one step toward hostile, and an auto `diplomatic`/`failure` event is emitted).
+  - **Protocol (`shared/protocol.ts`).** New `HybridOpType` (the seven types) + `HYBRID_OP_TYPES` const, and the `HybridOp` interface (`{ type; from; target; detail?; outcome? }`). `from` is the acting nation (id or unique name — resolved at apply time); `target` is **either** a nation (id/name) **or** a region key (hits that region's sole owner). `TurnResult.hybrid = { ops: HybridOp[] }` is required, placed between `wars` and `markers`.
+  - **Engine (`server/engine.ts`).**
+    - `isHybridOpType(t)` — exported guard over the seven types.
+    - `validateHybridOps(raw)` — new exported, defensive validator (never throws): accepts the `{ ops: […] }` object **or** a bare array; each op needs a known `type`, a non-empty `from` (≤200) and non-empty `target` (≤200); `outcome:'exposed'` is kept (success/missing is omitted to keep the shape minimal); `detail` capped at 300.
+    - `HYBRID_STAT_EFFECT` — exported table of the deterministic per-type stat dip: `sabotage`→economy −3, `assassinate`→stability −5, `cyber`→military −3, `economic`→economy −5; `spy`/`information`/`proxy` have no stat effect.
+    - `shiftRelationTowardHostile(state, a, b, cap)` — exported; nudges the bilateral relation **one** rung up the hostile ladder (`ally→neutral→rival→hostile`), symmetrically, capped at `cap`; a missing relation starts at `neutral`; a `war` relation is never touched (a covert op neither fabricates nor downgrades a war). Used for the `information`/`proxy` nudge and the `exposed` backfire.
+    - `resolveHybridTarget(state, target, validKeys?)` — internal; resolves a target to the concrete nation it affects: a nation ref via `resolveNationRef`, else a region key's **sole** owner (0 or 2+ owners → not targetable); `validKeys` (when supplied) gates the region path.
+    - `applyHybridOp(next, op, geoOf?, validKeys?, regionNameOf?, actingTurn?)` — internal; resolves `from`/`target` (unknown/ambiguous actor, unresolvable target, and self-targets are dropped — never throw), then applies the per-type effect: an `exposed` op backfires (relation sours one step, cap hostile, auto `diplomatic`/`failure` event); a successful stat op dips the target's `regionStats` (the single named region for a region target, otherwise **every** region the target owns) and re-derives the target nation's aggregate stats (same 0-region/no-entry guards as the main recompute) so the effect persists; `information`/`proxy` nudge the relation (caps `hostile`/`rival`); `spy` is informational only.
+    - `applyTurnResult` — new **hybrid block** (after the wars block, before markers): applies each validated op against the post-wars state. Sole ownership is preserved (a hybrid op affects stats, never ownership).
+    - `isMeaningful` — a non-empty `hybrid.ops` makes a turn meaningful.
+    - `validateTurnResult` — initializes and validates `hybrid` (default `{ ops: [] }`).
+    - `buildSystemPrompt` — documents the `hybrid` field and a HARD CONSTRAINTS bullet (non-kinetic, never moves borders, the per-type effects, the `exposed` backfire, region-key targets hit the sole owner, at most a few per turn, narrate each in `events`) in both tool and plain modes.
+    - `buildUserPrompt` — new optional `relations` param (the player's `nationId → RelationStatus` map) so the model sees the ladder its ops nudge and the starting point before a backfire; emitted only when provided.
+    - `runTurn` — computes the player's `relations` from state and passes them as the last `buildUserPrompt` arg; the "unclear" fallback carries `hybrid: { ops: [] }`.
+  - **Additive only.** No `GameState` field, **no** DB migration, **no** `db.ts` change — `hybrid` lives entirely in the `TurnResult` and is consumed by `applyTurnResult`.
+  - **Stub (`server/stub.ts`).** `deterministicTurn` returns `hybrid: { ops: [] }` — the stub **never** runs a covert op (mirrors `nationOps: []`, `takeovers: []`, `wars`). `StubPayload` gains an optional `relations` field (ignored). E2E (CI, `LLM_STUB=1`) is fully unaffected; the path is unit-tested only.
+  - **Unit tests (`server/engine.test.ts`).** ~30 new tests: `isHybridOpType`; `validateHybridOps` (both raw shapes, trim/cap, exposed-vs-success, drop rules); `validateTurnResult` — hybrid; `isMeaningful` — hybrid; `shiftRelationTowardHostile` (ladder, caps, war-untouched, missing=neutral); `applyTurnResult` — hybrid (each stat type's dip, nation-vs-region target, the per-type relation nudge & caps, `exposed` backfire + auto event, exposed-on-war, drop rules for unknown actor / self-target / unknown region / double-owned region, the `validKeys` gate, borders-untouched invariant, `HYBRID_STAT_EFFECT` magnitudes); `buildSystemPrompt` — hybrid contract (both modes); `buildUserPrompt` — relations; stub — hybrid.
+  - **Client.** No change — hybrid ops are an engine/LLM concern; their effects surface through the existing stats, relations, and event feed.
+  - **AGENTS.md.** New convention entry documenting the `hybrid` field, the deterministic per-type effects, the `exposed` backfire, the region-vs-nation targeting, and the stub/test coverage.
+
+## v0.33.0 — 2026-10-15 15:45
+- **#56: War as a first-class state — the `war` relation becomes a named `War` entity.** The v0.22+ `war` relation was a bare boolean flag on the `Relation` type with no lifecycle, no identity, and no way to distinguish "at war since 1939" from "at war since 1941" or to narrate the end of a conflict. This version promotes it to a first-class `War` entity in `GameState.wars` with a stable id, sides, declaration date/turn, optional aims, a lifecycle status (`active` / `armistice` / `capitulation`), and an optional front (region keys). The LLM declares and ends wars via `TurnResult.wars = { declare, end }` (both required, default `[]`); the engine creates/updates the entity and **derives** the `war` relation from active wars (any two nations on opposite sides of ≥1 active war get `war` in both directions, overriding lesser statuses — you cannot "make peace" without ending the war). When a war ends, the pairs it caused that are not covered by another active war fall back to `hostile`. A **bare** `war` relation with no matching active war (legacy/back-compat) is never downgraded and never force-created. **Mutual-defense drag-in**: when a war is declared, each belligerent's `ally`-relation partners are added to the war's `sides` (one level, no cascade; deterministic — sides in declared order, allies in sorted id order), so the dragged-in ally becomes `war` with all belligerents including its former ally.
+  - **Types (`shared/types.ts`).** New `War` interface (`id`, `sides: string[]` ≥2 distinct, `declaredTurn: number`, `declaredDate?: string`, `aims?: string[]`, `status: 'active'|'armistice'|'capitulation'`, `front?: string[]`); `GameState.wars: War[]` (required, `[]` at creation; a legacy SQLite row without the field loads as `[]` — additive, never wipes).
+  - **Protocol (`shared/protocol.ts`).** New `WarDeclareOp` (`{ sides: string[]; aims?: string[] }`) and `WarEndOp` (`{ id: string; outcome: 'armistice'|'capitulation'; terms?: string }`); `TurnResult.wars = { declare: WarDeclareOp[]; end: WarEndOp[] }` (both required, default `[]`). New `WarInfo` interface (`{ id; sides; aims? }`) for the user-prompt payload.
+  - **Engine (`server/engine.ts`).**
+    - `validateWarOps(raw)` — new exported, defensive validator (never throws): non-object → empty; `declare` — sides trimmed/capped 200/deduped, ≥2; aims ≤5×200; `end` — id ≤200, outcome exactly `armistice`|`capitulation`, terms ≤400.
+    - `activeWarPairs(wars): Set<string>` — NUL-joined sorted pair keys for active-only wars.
+    - `atWar(wars, a, b)` — convenience check.
+    - `syncWarRelations(prev, next)` — exported; enforces the derived `war` relation (active pairs → `war` both directions; ended pairs not covered by another active war → `hostile`; bare `war` never downgraded, never force-created).
+    - `freshWarId(taken)` — first free of `w1`, `w2`, … (next to `freshNationId`).
+    - `applyTurnResult` — new **wars block** (after takeovers, before markers): declare → create `War` (sides resolved via `resolveNationRef`; <2 distinct → dropped); end → find by id (unknown → no-op); then `syncWarRelations(state, next)`.
+    - `isMeaningful` — a non-empty `declare` or `end` makes a turn meaningful.
+    - `buildSystemPrompt` — documents the `wars` field (declare/end, at most 1–2 per turn, each narrated in `events`; the `war` relation is derived — do not emit it directly for active-war pairs).
+    - `buildUserPrompt` — carries current **active** wars as `WarInfo[]` so the model can `end` by id.
+    - `runTurn` — computes active-only `wars` from `state.wars`, passes as last arg; the "unclear" fallback carries `wars: { declare: [], end: [] }`.
+  - **DB (`server/db.ts`).** `load` defaults `state.wars` to `[]` when absent (after the markers default, before `migrateRegionStats`).
+  - **Stub (`server/stub.ts`).** `deterministicTurn` returns `wars: { declare: [], end: [] }` — the stub never declares or ends a war (mirrors `nationOps: []`, `takeovers: []`). E2E (CI, `LLM_STUB=1`) is unaffected; the path is unit-tested only.
+  - **Unit tests (`server/engine.test.ts`).** ~30 new tests: `freshWarId`, `validateWarOps`, `validateTurnResult` (wars), `activeWarPairs` / `atWar`, `syncWarRelations`, `applyTurnResult` — wars (declare creates war + derives relations; end removes active status + un-derives relations; mutual-defense drag-in; unknown-id end no-op; duplicate declare skip; unresolvable-ref drop; bare-war back-compat; relations-override-forced-back; same-turn declare+end leaves prior relation untouched), `isMeaningful` — wars, `buildSystemPrompt` — wars contract, `buildUserPrompt` — wars, stub — wars.
+  - **Client.** No change — wars are an engine/LLM concern; the UI already renders the `war` relation from the `Relation` type (which the engine now keeps in sync).
+  - **AGENTS.md.** New convention entry documenting the `War` entity, the `syncWarRelations` algorithm, the mutual-defense drag-in, and the stub/test coverage.
+
+## v0.32.0 — 2026-10-15 10:56
+- **#54: non-military takeovers become a visible regime change — a `Takeover` in the turn renames the nation.** The v0.30.0 stats work made stability a *soft* lever: the system prompt told the model that a low-stability nation (`stability < 30`) hosting a `gathering` marker "can suffer a non-military takeover — a coup, revolution or faction seizure of power", narrated with an event and a stat shock — but the model had no actual *field* to express the regime change itself, so the nation's name never changed and the takeover was invisible in the world. This version closes that gap with a new `TurnResult.takeovers` field: `Takeover = { nationRef, newRegimeName }`. Each entry is an **automatic, in-world** regime change applied directly by `applyTurnResult` (unlike `nationOps`, which are player-confirmed proposals) — the target nation's display `name` becomes `newRegimeName`, while its stable `id`, territory, relations (keyed by id), stats, and `playerNationId` are all preserved, so a player whose nation is overthrown keeps leading it under the new regime.
+  - **Protocol (`shared/protocol.ts`).** New `Takeover` interface (`nationRef` + `newRegimeName`, both strings). `TurnResult.takeovers: Takeover[]` is **required** (default `[]`), placed between `nationOps` and `markers`.
+  - **Engine (`server/engine.ts`).**
+    - `validateTakeovers(raw)` — new exported, defensive validator (same style as `validateNationOps`, never throws): non-array → `[]`; each entry must be an object with a non-empty (whitespace-trimmed) `nationRef` **and** a non-empty `newRegimeName`, each capped at 200 chars; anything else is dropped. Resolution of `nationRef` (id first, then a case-insensitive unique name) happens at apply time via the existing `resolveNationRef` — an unknown or ambiguous ref is a no-op at apply, never a throw.
+    - `validateTurnResult` populates `takeovers` from the validated array (and the generic "unclear" fallback in `runTurn` carries `takeovers: []`).
+    - `applyTurnResult` applies takeovers **after** the per-region stats recompute and **before** the markers block (the rename is order-independent of territory/stats; marker owners are nation **ids**, not names, so the rename never disturbs the owner recompute).
+    - `isMeaningful` — a turn that only performs a takeover is meaningful (it survives the retry/nudge path).
+    - `buildSystemPrompt` — the JSON shape gains `"takeovers": [{…}]` and a new HARD CONSTRAINTS bullet documents the field: **automatic, NOT player-confirmed**; fire it when a low-stability nation hosting a `gathering` marker is overthrown (the v0.30 stability/gathering mechanic now has a concrete consequence), narrate it with a political/social success event plus a stability/economy shock, and use `nationOps` rename only for the player-confirmed kind of name change.
+  - **Stub (`server/stub.ts`).** `deterministicTurn` returns `takeovers: []` (the stub never performs a takeover) — its one-conquest behavior and every e2e assertion are untouched; the regime-rename path is covered by unit tests only.
+  - **Client.** No change — a takeover is just a nation `name` change, which the existing dossier / event feed / map rendering already show (the nation keeps its stable color, since that is keyed by id).
+  - **Unit tests (`server/engine.test.ts`).** 15 new tests: the apply suite (a takeover renames the target with id/territory/relations/stats preserved; a takeover of the player's own nation preserves `playerNationId`; unknown ref → no-op; ambiguous ref → no-op; empty/whitespace `newRegimeName` dropped at validation; multiple takeovers in one turn all apply; a takeover turn bumps the version exactly once; case-insensitive name resolution); `isMeaningful` with takeovers; the system-prompt contract (both modes document the field + the automatic/not-player-confirmed rule + the stability/gathering tie-in + the distinction from `nationOps` rename); `validateTakeovers` (valid entries trimmed/capped, invalid dropped, non-array → `[]`, `validateTurnResult` carry-through + default); the stub returns `takeovers: []`. All existing `TurnResult` literals in the suite gained the new required field. Totals: **322 unit tests (14 files)**; typecheck, lint, and build green.
+
+## v0.31.0 — 2026-10-15 10:22
+- **#52: dynamic scenario generation — the "Create scenario" path.** An additive second way to start a game alongside the 5 static presets: the user picks one of **3 light era templates** (`ww2` 1939, `present` 2026, `near-future` 2035) and writes a free-text **description** (plus an editable start year), and the LLM **generates** a draft world + an advisor **checkpoint list** (step 1). The player reviews the checkpoints (approve/remove) and picks a nation to lead, and a second LLM call **finalizes** the world — constrained to the *approved* checkpoints — into a saved, playable `GameState` (step 2): a normal game at `#/game/<id>` that plays with the existing turn engine, map, and panels untouched. The 5 static presets and the turn stub (`server/stub.ts`) are 100% unchanged; a new deterministic **scenario stub** (a distinct transport discriminating the two calls by marker) makes the whole path reproducible under `LLM_STUB=1`.
+  - **Era templates (`presets/templates/`).** Three small JSON seeds + an `index.json` manifest — each `{ id, name, year, eraDescription, suggestedPowers: [{ name, region (ISO_A3), note }], tensions: [] }` (e.g. near-future suggests a North American Union/USA, a Chinese Federation/CHN, a European Confederation/FRA, a Russian Union/RUS, with tensions like "autonomous weapons and the new arms race"). `server/templates.ts` is a tiny store mirroring `createPresetStore` (manifest + per-file load; a missing/broken file degrades to absent).
+  - **Shared contract (`shared/scenario.ts`, dependency-free).** `EraTemplate` / `TemplateMeta` / `SuggestedPower`; `WorldDraft = { nations: WorldNation[]; events? }` where `WorldNation.territory` holds **ISO_A3 country codes** (not region keys) and `relations` are numeric sentiments (−100..100); `Checkpoint = string`; the four message shapes (`ScenarioDraftRequest/Response`, `ScenarioCommitRequest/Response`). Pure transforms: `validateWorldDraft(raw, { validCountryCodes })` — defensive parse/clamp/normalize that never throws (name-required, id kept-or-slug fallback, duplicate ids suffixed, territory upper-cased/deduped and filtered to known ISO_A3 codes when a valid set is given, relations re-keyed to assigned ids via id or case-insensitive name match with self/unknown refs dropped, optional backstory events kept only when they name a known nation; returns `null` when the result is unusable — no nations, or no valid territory to render); `relationFromScore` (≥60 ally · 0..59 neutral · −40..−1 rival · −80..−41 hostile · ≤−81 war); `worldDraftToGameState(draft, expand, playerNationId, opts)` — expands ISO_A3 territory to region keys via the injected `expand` (`expandCountriesToKeys` in production), seeds `regionStats` (so each owned region starts with its owner's stats and the derived aggregate equals them on turn 1), a clean turn-1 state (`version:1`, `turn:1`, empty `unowned`/`markers`/`pendingNationOps`/`pending`), `presetId: 'dynamic'`, and a guard that re-points a dangling `playerNationId` to the first nation so the game is always playable.
+  - **Scenario LLM steps (`server/scenario.ts`).** Two plain `chat()` calls (no tools, no separate advisor endpoint — the advisor is embodied in step 1's checkpoint list): `generateDraft({ template, description, year })` → `{ world, checkpoints }` (the prompt carries the era description, suggested powers, tensions, the user's description, the year, and the valid ISO_A3 reference), and `finalizeWorld({ …, approvedCheckpoints, draft, playerNationId })` → final `GameState` (re-asked to produce the final world constrained to the approved checkpoints, based on the step-1 draft the client re-sends so the chosen nation survives; falls back to the draft itself when the model returns nothing usable). Same defensive parsing as the engine (strip fences → first balanced object → `JSON.parse` → `validateWorldDraft`), one nudge-retry when the answer is unusable; a transport failure (model down) throws → HTTP 502, a bad *answer* degrades to the fallback and never crashes.
+  - **Scenario stub (`server/stubScenario.ts`).** Deterministic transport for the two scenario calls only (discriminated by `SCENARIO_GENERATE_MARKER` / `SCENARIO_REGENERATE_MARKER` in the system message, mirroring how the turn stub keys off `ADVISOR_MARKER`): a fixed 3-nation world (Alba/FRA 70·60·65·55, Boreas/RUS 55·70·50·60, Gamma/ESP 30·45·70·40) + one backstory event ("The new order takes shape") + a fixed 3-checkpoint list; the finalize step refines the world deterministically from the approved checkpoints (each naming a nation by its 4-letter name prefix raises that nation's stability +5, clamped) — so "finalize respects the approved checkpoints" is observable end-to-end. The turn stub stays 100% unchanged.
+  - **Routes (`server/index.ts`).** `GET /api/scenarios/templates` (the 3 manifest entries), `POST /api/scenarios/draft` (`{ templateId, description, year? }` → `{ world, checkpoints }`), `POST /api/scenarios/commit` (`{ templateId, description, year?, draft?, approvedCheckpoints, playerNationId }` → `{ id }` — the finalized world is saved to SQLite with `startDate = <year>-01-01` and title = the template name). A separate `scenarioLlm` client (the scenario stub under `LLM_STUB=1`, the same live `qwen3.8-27b` client otherwise) — the turn `llm` is untouched. `POST /api/games/:id/jump` synthesizes a minimal `Preset` (`dynamicPresetFromGame`) for a saved dynamic game (`presetId: 'dynamic'` has no static file on disk — `runTurn` only consumes title/startDate/worldBackground/rules) so a created scenario plays with the normal turn engine; a genuinely-missing static preset still 404s.
+  - **Client.** New `ScenarioForm` (3 template cards, a pre-filled editable year, a description textarea, Generate → `/draft`; a 502 toasts and stays on the form) and `CheckpointReview` (the draft world as nation cards with stats, the checkpoint checklist with per-item approve/remove, a pick-a-nation-to-lead step, Finalize → `/commit` → navigates to `#/game/<id>`; a 502 toasts and stays on review). `PresetPicker` gains a "Create scenario" card, and `App.tsx` wires the `home → form → review → navigate` flow (a distinct `scenarioBusy` flag that never gates "Jump forward" or the turn flow).
+  - **Tests.** Unit: the template store (manifest + all 3 files' shape); `validateWorldDraft` / `relationFromScore` / `worldDraftToGameState` (valid → clean, stat/score clamping, bad country codes dropped, garbage → null without throwing, id dedup, territory expansion, `regionStats` seeding, player fallback, turn-1 invariants); `generateDraft` / `finalizeWorld` against the scenario stub (deterministic output, finalize respecting the approved checkpoints, a saved playable game). E2E: a new `e2e/scenario.spec.ts` (2 tests — the templates manifest over the API, and the full deterministic flow under `LLM_STUB=1`: near-future (2035) + description → draft → remove one checkpoint → lead Boreas → finalize (checkpoints shift stats) → a playable game at the `#/game/<id>` deep link with turn 1, correct date, dossier stats, map legend, and the backstory event; plus an empty jump proving the dynamic game runs the normal turn loop). The existing `e2e/sim.spec.ts` is unchanged. Totals: **307 unit tests (14 files)**, **16 e2e tests (2 scenario + 14 sim)**; typecheck, lint, and build green.
+
+## v0.30.0 — 2026-10-15 08:22
+- **#50: make the four 0–100 stats consequential — a hard military conquest gate, soft stability takeovers, and economy growth/decay.** The four stats now actually drive outcomes instead of being decorative. **Military is a hard gate:** a contested invasion (a region's sole owner changing hands) is repelled whenever the attacker's military is **more than `CONQUEST_MILITARY_MARGIN = 15`** below the defender's — equal or within 15 still wins. The engine enforces this in `applyTurnResult` and emits a new `repelled` event when it fires; **re-claims of unowned (no man's land) regions are not gated** (there is no defender). **Stability is a soft lever:** the system prompt documents that a nation whose stability is below 30 *and* that hosts a `gathering` marker can suffer a **non-military takeover** (coup / revolution / faction seizure) — narrated by the LLM with a political/social success event, a gathering marker, and a downward stability/economy shock. **Economy is a soft lever:** a strong (rising) economy trends the other stats up (growth) and a collapsing economy drags them down (decay), reflected via `stateChanges` / `regionChanges`. A **frontier military-balance hint** and a **takeover-risks** hint are emitted in the user payload (each only when present) so the model — and the player, via the same data — sees the levers before acting. The stub stays 100% deterministic and untouched; e2e is unaffected (the UK/wwii-1939 e2e has an empty frontier, so the gate is vacuous there).
+  - **Protocol (`shared/protocol.ts`).** New `CONQUEST_MILITARY_MARGIN = 15` and a pure `canConquer(attackerMil, defenderMil, margin = CONQUEST_MILITARY_MARGIN)` — `!(attackerMil < defenderMil - margin)` (proceeds unless the attacker is strictly more than the margin below the defender).
+  - **Types (`shared/types.ts`).** `EventOutcome` gains `'repelled'` (engine-only; the LLM never produces it).
+  - **Colors (`src/lib/colors.ts`).** `OUTCOME_COLORS.repelled = '#9f1239'` — a muted rose-800, distinct from `failure` (`#ef4444`) and `neutral` (`#94a3b8`).
+  - **Engine (`server/engine.ts`).**
+    - `applyTurnResult` gains an optional `regionNameOf` (5th optional param, after `geoOf`) and the **military hard gate** inside the snapshot-first claims loop: for each contested key (a gainer's `gain` whose current sole owner is a *different* nation), it compares the gainer's start-of-turn military to the owner's via `canConquer`; on a fail it keeps the key with the owner, leaves both nations' military untouched, and pushes one `repelled` military event (`"<Attacker>'s invasion of <region name> was repelled by <Defender>."`, using the region's geo display name when known). Re-claims (`owner === undefined`) bypass the gate.
+    - `buildSystemPrompt` gains a **"HOW THE FOUR 0–100 STATS DRIVE OUTCOMES"** section: the enforced military gate (incl. the no-man's-land carve-out), the soft stability takeover, and the economy growth/decay lever — present in both tool and plain modes.
+    - `buildUserPrompt` computes and emits two new, bounded payload fields (each only when non-empty, the rest of the payload untouched): `frontierMilitary` (one line per frontier neighbour: `[Your military: X] vs [Name: Y] — a direct invasion could succeed | would be repelled`, decided by `canConquer`) and `takeoverRisks` (one line per nation with stability < 30 *and* a `gathering` marker: `Name (stability N, a gathering is in progress)`).
+    - `runTurn` threads `regionNameOf` through to `applyTurnResult`.
+  - **Server route (`server/index.ts`).** The `/jump` route wires `regionNameOf: (k) => regionName(k)` so repelled invasions name the region properly.
+  - **Stub (`server/stub.ts`).** Unchanged (100%) — it never releases, never proposes a nation op, and its one-conquest behavior is what e2e relies on; the new gate / takeover / economy paths are covered by unit tests only.
+  - **Unit tests.** `server/protocol.test.ts`: `canConquer` edges (equal, within margin, over margin, gap == margin, gap == margin + 1, margin = 0). `server/engine.test.ts`: the hard gate (proceed within margin / proceed when stronger / **repel when over margin** with a correct `repelled` event + region display name + attacker untouched / **re-claim ungated** / boundary at exactly the margin and one past it); the system prompt documents all three mechanics in both modes; the user prompt emits `frontierMilitary` (could-succeed vs repelled per neighbour) and `takeoverRisks` (and omits both fields when no frontier / no markers).
+
+## v0.29.0 — 2026-10-15 01:05
+- **#46 (PR 2 of 2): per-region stat lever — the LLM can now target individual regions' stats, and the map hover shows them.** The LLM gains a fine-grained `TurnResult.regionChanges` field (alongside the existing nation-wide `stateChanges`): each entry targets **one** region's own stats by its region key (preferred) or case-insensitive name. A `set` replaces the value; an `add` increments it (both clamped 0–100 at apply time). Region-level changes are applied **after** nation-wide `stateChanges` (so they override the nation-level value for that one region) and **before** the weighted-median recompute, which propagates every region's final value into its owning nation's derived `stats`. A region with no stats entry (unowned / no man's land) is a no-op. The map hover tooltip now shows each region's own four stats (military / economy / stability / population) alongside the region name and owner chip; the `NationPanel` keeps showing the nation-level derived aggregate. The stub stays fully deterministic (`regionChanges: []`) — e2e assertions are untouched.
+  - **Protocol (`shared/protocol.ts`).** New `RegionStatChange = { region: string; stat: StatKey; op: 'set'|'add'; value: number }`. `TurnResult.regionChanges: RegionStatChange[]` is **required** (default `[]`); sits right after `stateChanges`.
+  - **Engine (`server/engine.ts`).**
+    - `resolveRegionKey(ref, validKeys, nameOf)` — pure resolver: exact key first; then a case-insensitive unique-name match; ambiguous / unknown / empty → `null`.
+    - `validateRegionChanges(raw, regionKeyResolver?)` — validates and resolves each entry; drops unknown / ambiguous refs (never throws); clamps `set` values at validation; `add` values are clamped at apply time.
+    - `parseTurnResult` / `validateTurnResult` / `runTurn` all accept an **optional** `regionKeyResolver` (2nd arg / opts) threaded to `validateRegionChanges`; the generic "unclear" fallback carries `regionChanges: []`.
+    - `applyTurnResult` applies `regionChanges` after `stateChanges` and before the weighted-median recompute (the load-bearing order is: events → relations → territory → stateChanges → **regionChanges** → recompute → markers → nationOps).
+    - `isMeaningful` — a turn with only `regionChanges` is meaningful (survives the retry/nudge path).
+    - `buildSystemPrompt` — documents the `regionChanges` JSON field and a constraint bullet (target one region, use keys from the "regions" table, "playerRegionStats" lists the player's current per-region stats).
+    - `buildUserPrompt` — computes and emits `playerRegionStats` (the player's owned regions' current stats; bounded to the player's territory to keep the prompt small; `{}` when none).
+  - **Server route (`server/index.ts`).** The `/jump` route wires the `regionKeyResolver` (always on; degrades to key-only matching when the adjacency manifest is absent).
+  - **Stub (`server/stub.ts`).** `deterministicTurn` returns `regionChanges: []` — the per-region lever is covered by unit tests only, keeping the e2e assertions untouched.
+  - **Client (`src/components/WorldMap.tsx`).** The hover tooltip gains a `regionStats` prop and shows the region's own four stats (`Mil / Eco / Stab / Pop`); a region with no entry shows a `–` placeholder. The name and owner chip are kept; marker rendering and the click→dossier path are unchanged. `src/App.tsx` passes `game.regionStats ?? {}`.
+  - **Unit tests (`server/engine.test.ts`).** New suites: `resolveRegionKey` (key match, case-insensitive name match, unknown / ambiguous → null, key-over-name priority); `validateRegionChanges` (key / name resolution, unknown / invalid stat / non-numeric / invalid op dropped, `set` clamped, `add` not clamped at validation, non-array → [], no-resolver path); `applyTurnResult` with `regionChanges` (set changes only that region, add clamps 0/100, unowned no-op, applied after stateChanges, non-mutation); prompt contract (system prompt documents the field + constraint, user prompt emits bounded `playerRegionStats`); `isMeaningful` with `regionChanges`; stub returns `regionChanges: []`.
+
+## v0.28.0 — 2026-10-15 00:12
+- **#46 (PR 1 of 2): per-region stats — a nation's four 0–100 stats become a *derived* aggregate.** Instead of storing `Nation.stats` as four independent per-nation numbers, they are now **derived** as the **area×population-weighted median** of the stats of the regions the nation owns. Each sub-region carries its own `RegionStats` in a new `GameState.regionStats: Record<regionKey, RegionStats>` table; a nation's displayed stats are the weighted median over its owned regions. This is the data foundation for the per-region LLM levers that land in **PR 2** — in this PR the LLM still only emits nation-level `stateChanges`, which are re-interpreted as applying to *all* of a nation's owned regions. A new `public/region-geo.json` manifest (area km² + population per region key) supplies the weighting. **Not deployed in this PR** — the production site updates when PR 2 ships (the change is additive and backward-compatible, so deferring the deploy is safe).
+  - **Data build (`scripts/`, turf-`.mjs` only; never imported by `.ts`).**
+    - `scripts/extract-admin0-pop.mjs` (`npm run extract:admin0-pop`) — **one-time** distillation of the 13 MB Natural Earth 1:10m admin-0 GeoJSON (a *source* file we do **not** commit) into the small committed `public/ne-admin0-pop.json` = `{ ADM0_A3 → max POP_EST }` (249 country codes, total 7,677,059,722). The 1:10m **admin-1** file the region generator uses carries no population, so the source is the **admin-0** `POP_EST` (a deliberate deviation, recorded here).
+    - `scripts/build-region-geo.mjs` (`npm run build:region-geo`) — builds `public/region-geo.json` = `{ regionKey → { area, population } }`: `area` = `@turf/area(finalFeature)/1e6` km² (2 dp); `population` = the parent country's `POP_EST` spread across its sub-regions **proportional to area via largest-remainder**, so every country's sub-regions sum **exactly** to its total (no rounding drift). Reads the committed `ne-admin0-pop.json` → fully reproducible in CI. **Deterministic + idempotent** (sorted keys; byte-identical re-run, pinned by the test). 1,800 entries; **total population 7,654,092,021** (the sum over the 177 repo countries).
+  - **Types (`shared/types.ts`, no runtime deps).** New `RegionStats = { military, economy, stability, population }` (0–100). `GameState.regionStats: Record<string, RegionStats>` is **required** (`{}` at game creation; a released / 0-owner / 2+owner region has **no** entry; a legacy SQLite row without the field is migrated on load, never wiped).
+  - **Pure helpers (`shared/protocol.ts`, no deps).**
+    - `weightedMedian(values, weights)` — sorts by value and returns the value at the first point the cumulative weight reaches half the total; non-finite/non-positive weights are excluded; empty / zero-total → 0. **Translation-invariant** (the median of identical values is that value — the invariant seeding and migration rely on).
+    - `deriveNationStats(regionKeys, regionStats, geoOf?)` — each stat is the weighted median over the nation's owned region keys; a region's weight is `(area>0?area:1)×(population>0?population:1)` (both fall back to 1 when the key has no geo entry, so missing geo degrades to a uniform median); a key with no `regionStats` entry is skipped; returns zero stats when no owned region has an entry (the caller's 0-region guard keeps `n.stats` in that case).
+    - `seedRegionStats(nations)` — seeds the table from nations: every owned key gets a **copy** of its owner's stats (first owner wins on a corrupt double-ownership), so a fresh nation's regions start identical (derived = seeded).
+    - `migrateRegionStats(state, geoOf?)` — **one-time** legacy migration: a row that already has `regionStats` is returned **unchanged** (no recompute on load → no drift); a legacy row (field absent) is seeded per region and each nation's stats recomputed (0-region guard). Never throws.
+  - **Server (`server/regions.ts`, turf-free).** Loads `region-geo.json` (probes `public/` then `dist/`) **optionally** — a missing/broken file degrades weighting to uniform (every region weight 1) while everything else keeps working. New `hasGeo()` and `geoOf(key)` accessors mirror the existing `hasCentroids`/`centroidOf`.
+  - **Server (`server/engine.ts`).** `applyTurnResult` gains an optional `geoOf` param and is reordered to: events → relations → **territory** → **stateChanges** → **recompute** → markers → nationOps.
+    - **Territory:** a **transferred** region **keeps its own** per-region stats (the conquest is what makes a nation's regions diverge); a **released** region's entry is **deleted** (no man's land carries none); a **re-claimed** region with no entry is **re-inited** to the gainer's current stats.
+    - **StateChanges (re-interpreted):** a nation-level `set`/`add` applies to `n.stats` **and** to every region the nation owns (clamped 0–100).
+    - **Recompute:** every nation's `stats` is re-derived via `deriveNationStats` (weighted by area×population when `geoOf` is present). Two guards: a **0-region** nation keeps its directly-maintained stats, and a nation **none of whose regions has an entry** keeps its stats too (avoids clobbering with zeros).
+    - `runTurn` threads the optional `geoOf` through to `applyTurnResult`.
+  - **Server (`server/index.ts`).** Game creation seeds `regionStats` via `seedRegionStats` **after** `expandCountriesToKeys` (so regions hold real keys) — a new game's derived stats equal its nation-level stats on turn 1. The `jump` route passes `geoOf: hasGeo() ? geoOf : undefined`.
+  - **Server (`server/db.ts`).** `load()` migrates a legacy row (regionStats absent) via `migrateRegionStats(state)` **without** `geoOf` (uniform weights — weight-invariant for the equal-value seeding, and avoids a `db`→`regions` import). v0.28+ rows load unchanged.
+  - **Prompt / client / stub unchanged.** `nationForPrompt`/`buildUserPrompt` still surface the (now derived) four stats; there is no per-region LLM lever yet (PR 2). The deterministic stub is unaffected (nation-level `stateChanges` flow through the re-interpretation; the median of identical values is that value, so e2e stat assertions hold).
+  - **Tests (189 → 225).** New `server/protocol.test.ts` (weightedMedian incl. translation-invariance / identical / zero / empty; deriveNationStats weighted vs uniform / skip-missing / zero / single / fallback-weight; seedRegionStats; migrateRegionStats v0.28+ no-op vs legacy / 0-region); `server/engine.test.ts` (transfer keeps region stats + aggregate blends, release deletes entry, re-claim re-inits, 0-region keeps stats, geoOf-weighted vs uniform recompute, nation-level change re-applies to regions, original not mutated); `server/db.test.ts` (legacy row → seeded + preserved stats; v0.28+ row loads unchanged); `server/regions.test.ts` (`hasGeo`/`geoOf` in dev + prod-`dist/` layouts, graceful degradation when absent); new `scripts/region-geo.test.ts` (1,800-entry key-set match, sorted, finite / ≤2dp area / integer population, total 7,654,092,021, per-country totals preserved vs admin-0, spot-checked values, byte-identical re-run).
+  - **Verification.** Typecheck, lint, **225 unit tests**, and the production build all pass (the build copies `region-geo.json` + `ne-admin0-pop.json` into `dist/` like the other manifests, so the prod container layout is covered). e2e is verified by CI on the PR (no local run).
+  - **Deploy:** **none** in this PR — the production site (`https://history.dev.kkhost.pl`) updates when **PR 2** ships. The change is additive + backward-compatible, so existing games migrate on load and no data wipe is needed.
+
+## v0.27.0 — 2026-10-14 22:34
+- **#44: the LLM can place named point markers on the map.** The model may now place up to a handful of named *point markers* per turn (a capital, city, factory complex, army deployment, port, fleet concentration, rocket launch site, or a political **gathering**), each anchored to a region key, persisted per game, and rendered on the choropleth as a MapLibre symbol layer.
+  - **Types (`shared/types.ts` + `shared/protocol.ts`).** Eight `MarkerType`s — `city, factory, army, port, capital, fleet, rocket, gathering` — with a shared `MARKER_TYPE_INFO` map (display label + color + glyph). A `MapMarker = { id, type, name, regionKey, lat, lon, ownerNationId, placedTurn }`; `GameState.markers: MapMarker[]` is **required** (`[]` at game creation, and a legacy SQLite row without the field loads as `[]` — additive, never wipes existing markers). `TurnResult.markers = { add: MarkerSpec[]; remove: string[] }` (both required, default `[]`); `MarkerSpec = { type, name, regionKey }`.
+  - **Stable ids (`shared/protocol.ts`).** A marker's `id` is the FNV-1a 32-bit hash of `` `${type}\u0000${name}\u0000${regionKey}` `` rendered as four lowercase base-26 characters (mirroring the region-key scheme). This makes a **re-add idempotent** (the same type+name+region never creates a second marker) and a **remove unambiguous** (by id).
+  - **Centroid data (`public/region-centroids.json`, new).** ~1,800 entries keyed identically to `region-keys.json`, each `{ lat, lon, spread }`: the anchor is the **centroid of the region's largest-area part** (a single representative point, not an average across disjoint parts), and `spread` ≈ **0.1 × that part's smallest bbox dimension** (in degrees). A new idempotent pipeline stage `scripts/build-region-centroids.mjs` (`npm run build:region-centroids`) regenerates it deterministically (byte-identical re-run, sha256-pinned by the test). The engine uses the centroid as the marker's base position and the `spread` to jitter multiple markers of one region around it (a deterministic per-axis FNV-1a-derived offset, so markers scatter instead of stacking).
+  - **Engine (`server/engine.ts`).** `applyTurnResult` processes markers **after** territory claims, in three steps: (1) remove by id (a listed-but-absent id is a no-op); (2) **recompute every surviving marker's `ownerNationId` from the final post-claim ownership** — a captured region follows its new owner, a region released to no man's land (or a key with 0 or 2+ owners) becomes `null` (a marker always follows its region); (3) add — each new spec is placed at its region's centroid (injected via a new optional `centroidOf` param) plus the per-axis jitter, owned by the region's post-turn owner, stamped with the acting turn. Adds are dropped (never thrown) when their region key is unknown / has no centroid, when the id already exists (idempotent re-add), or beyond the hard cap `MAX_MARKERS = 400` (later adds dropped). The system prompt documents the field, the eight types, and the placement rules; `buildUserPrompt` carries the current markers (as `MarkerInfo[]`) so the model can reference their stable ids in `remove`; `isMeaningful` treats a marker add/remove as a real world change.
+  - **Client (`src/components/WorldMap.tsx`).** A second GeoJSON source + a symbol layer sits above the choropleth. **Deliberate deviation from the original "name as a text label" design:** every external glyph endpoint is a dead 404 (OpenFreeMap's `fonts/{stack}/{range}.pbf` and `demotiles.maplibre.org/font/…`), and the OFM dark basemap only renders at all because it is **raster** (labels baked into the PNG tiles) — there is no working vector font. So markers are drawn as **self-contained, offline, canvas-generated per-type icons** (`drawMarkerIcon`: a distinct shape per type — circle / rounded-square / triangle / diamond / star / center-dotted circles / up-arrow — filled with the type color, outlined for legibility on the dark basemap), registered as named `ImageData` images that survive `styledata`. The marker **name is shown in the hover tooltip** (region name + owner chip + marker name) instead of a persistent on-map label, and **clicking a marker focuses its owning nation's dossier** (a marker's owner is its region's owner). There are no separate marker event handlers: MapLibre's per-layer event delegates fire independently (no `stopPropagation`), so the region hover/click handlers instead `queryRenderedFeatures` the marker layer under the cursor and act on the marker when present.
+  - **Stub (`server/stub.ts`) stays marker-free** — it returns `markers: { add: [], remove: [] }` — so the e2e suite (CI, `LLM_STUB=1`) is unaffected and fully deterministic; the full marker path is covered by unit tests only.
+- **Tests (168 → 189).** New `scripts/region-centroids.test.ts` (1,800 entries, key-set match, finite/world-bounds, each centroid inside its feature's bbox via turf-free coordinate iteration, spot-checked anchors, byte-identical re-run determinism); `server/regions.test.ts` (`hasCentroids`/`centroidOf` in dev + prod-`dist/` layouts, graceful degradation when absent); `server/db.test.ts` (legacy row → `markers: []`); and an `engine.test.ts` marker suite (valid add → id/position/owner/placedTurn, idempotent re-add, region-validity/centroid drops, the 400 cap, remove by id / no-op, owner-follows-region incl. release→null and re-claim, `buildUserPrompt`/system-prompt contract, `validateMarkerOps` raw cleaner, and the `runTurn` centroid wiring).
+- **Verification.** Typecheck, lint, **189 unit tests**, and the production build all pass (the build copies `region-centroids.json` into `dist/` like the other manifests, so it works in the prod container layout).
+- **Deploy:** manual `docker compose up -d --build` on the host — **no `down -v`** (markers are additive; legacy games load with `markers: []`).
+
+## v0.26.0 — 2026-10-14 19:24
+- **#41: the `RU-ARK` mainland's Arctic-coast band is re-coarsened into two new regions** — a pure re-partition of the existing polygon parts: no new geometry, no coordinate change (the feature union stays byte-identical). After #31 the mainland `RU-ARK` was a 33-part MultiPolygon; its 28-part band (parts whose centroid lat ≥ 68 — the Arctic-coast strip) is now split into:
+  - `RU-PEO` — Pechora (13 parts, ~37,678 km²) → new region key `pechora-qwhs`. The southwestern band (around the Pechora delta / Nenets border).
+  - `RU-YAM` — Yamal (15 parts, ~51,722 km²) → new region key `yamal-gosw`. The northeastern band (Yamal peninsula).
+  - The 5 remaining lat < 68 parts (the ~305,229 km² inland core) **stay `RU-ARK` and keep its id, name, and region key `arkhangel-sk-lhbk`** — ownership-safe, mirroring the #31 precedent. Splitting that core further requires geometry clipping (a turf-op), not a pure re-partition, and is left as a follow-up issue.
+  - **New pipeline stage** `scripts/split-arkhangel-band.mjs` (`npm run split:regions:band`), run between `split:regions` and `build:region-keys`: deterministic and **idempotent** (a second run is a no-op that writes nothing). It asserts the mainland is a 33-part MultiPolygon, selects the band as the 28 parts with centroid lat ≥ 68 (exactly 28, or it fails loudly), picks the two largest-area band parts as Voronoi anchors (the smaller-longitude one, `idx 1`, anchors the Pechora side), and assigns each band part to the nearer anchor by km-weighted centroid distance `hypot(Δlon·111.32·cos(midLat), Δlat·110.574)` (ties go west). The resulting partition is exactly PEO={1,4,5,9,11,12,13,14,16,17,18,20,22}, YAM={2,6,15,19,21,23,24,25,26,27,28,29,30,31,32}, core={0,3,7,8,10}. The two new features are inserted **immediately after `RU-ARK-SZ`** (stable file order: `RU-ARK` | `RU-ARK-NE` | `RU-ARK-SZ` | `RU-PEO` | `RU-YAM` | `RU-AST` | …).
+  - **Manifests regenerated** with the real scripts and remain deterministic/idempotent (byte-identical re-run): `public/region-keys.json` and `public/region-adjacency.json` are now **1,800 entries each** (was 1,798); adjacency pairs 4,471 → 4,473. The new pairs are `pechora-qwhs ↔ yamal-gosw`, `pechora-qwhs ↔ nenets-qyga`, and `yamal-gosw ↔ severnaya-zemlya-awqp`, while the mainland `arkhangel-sk-lhbk` **loses** its `severnaya-zemlya-awqp` pair (the islets now touch the Yamal band, not the inland core) and keeps its six real neighbours (`karelia-ohem`, `kirov-gfvm`, `komi-eoeh`, `murmansk-etas`, `nenets-qyga`, `vologda-ynvr`). `new-earth-eikt` stays isolated (empty adjacency).
+  - **Fixed-point dataset unchanged except feature count** (1,798 → 1,800): the part/ring/vertex totals (11,794 / 11,795 / 164,801) and the single hole (KZ-KZY) are identical before and after — only the feature grouping changes. The RU-ARK family total stays 78 parts (mainland 5 / NE 42 / SZ 3 / PEO 13 / YAM 15).
+  - **Tests (168, count unchanged — existing cases updated, none added).** `scripts/regions.test.ts` (dataset is now 1,800 features; the Arkhangel feature-pin test now covers all five family members), `scripts/region-keys.test.ts` (1,800 keys; pins the unchanged `arkhangel-sk-lhbk` plus the two new keys), `scripts/region-adjacency.test.ts` (1,800 entries; pins the new PEO/YAM/SZ adjacency and the mainland's loss of the SZ pair), `server/regions.test.ts` (1,800; the RUS country expansion is now **84** sub-regions including all five keys — was 82 after #31). No e2e assertion references the region counts, so the CI e2e suite is unaffected.
+  - **LLM/engine/stub unchanged.** At game creation RUS simply auto-owns the two extra band regions (82 → 84 sub-regions); the LLM's reference table and the player's frontier now include `pechora-qwhs` and `yamal-gosw`.
+  - Deployed to `https://history.dev.kkhost.pl` with the authorized **clean data wipe** (`docker compose down -v` → `up -d --build`; the alpha `history-data` volume was destroyed, resetting all saved games).
+
+## v0.25.0 — 2026-10-14 17:53
+- **#31: the `RU-ARK` mega-region is split into a mainland region plus two island groups** — a pure re-grouping of the existing polygon parts: no new geometry, no coordinate changes. The old single feature (Arkhangel'sk Oblast + the Arctic archipelagos, 78 parts, ~410,187 km²) becomes three features inserted immediately after `RU-ARK` (stable file order: `RU-ARK` | `RU-ARK-NE` | `RU-ARK-SZ` | `RU-AST`):
+  - `RU-ARK` — the mainland (33 parts, ~393,256 km²); it **keeps its existing id and region key `arkhangel-sk-lhbk`**, so existing `Nation.territory` lists and SQLite ownership are untouched (ownership-safe).
+  - `RU-ARK-NE` — New Earth / Franz Josef Land (42 parts, ~15,721 km²) → new region key `new-earth-eikt`. Genuinely isolated (≥100 km from any land), so its adjacency list is **empty**.
+  - `RU-ARK-SZ` — Severnaya Zemlya (3 parts, ~1,210 km²) → new region key `severnaya-zemlya-awqp`. Its islet rings share boundary vertices with the coarsened mainland ring (a contact that pre-existed inside the single pre-split feature — no coordinate change), so it records **one** adjacency pair (SZ ↔ `arkhangel-sk-lhbk`). This deviates from the original "both islands isolated" expectation and is recorded as-is by the manifest's "shares at least one point" definition.
+  - **New pipeline stage** `scripts/split-arkhangel.mjs` (`npm run split:regions`), run between `fill:regions` and `build:region-keys`: deterministic and **idempotent** (a second run is a no-op that writes nothing). It classifies each part by centroid (turf — allowed in `.mjs` only): main = lat < 76 (plus any 76–79.5° band parts west of 55°E — none exist), Severnaya Zemlya = 76 ≤ lat < 79.5 AND lon ≥ 55, New Earth = lat ≥ 79.5. It fails loudly on a mis-split, a missing feature, or a non-MultiPolygon geometry.
+  - **Manifests regenerated** with the real scripts and remain deterministic/idempotent (byte-identical re-run): `public/region-keys.json` and `public/region-adjacency.json` are now **1,798 entries each** (was 1,796); adjacency pairs 4,470 → 4,471 (the one new pair is the SZ ↔ mainland contact; the mainland keeps its 6 real neighbours).
+  - **Fixed-point dataset unchanged except feature count** (1,796 → 1,798): the part/ring/vertex totals (11,794 / 11,795 / 164,801) and the single hole (KZ-KZY) are identical before and after the split.
+  - **Tests (164 → 168).** `scripts/regions.test.ts` (dataset is now 1,798 features; a new test pins the three Arkhangel features and their part counts), `scripts/region-keys.test.ts` (1,798 keys; a new test pins the unchanged main key plus the two new keys), `scripts/region-adjacency.test.ts` (1,798 entries; a new island-adjacency test: New Earth empty, Severnaya Zemlya = [mainland], mainland's neighbour list extended by exactly the SZ pair), `server/regions.test.ts` (1,798; the RUS country expansion is now **82** sub-regions including all three keys — was 80). No e2e assertion references the old counts, so the CI e2e suite is unaffected.
+  - **LLM/engine/stub unchanged.** At game creation RUS simply auto-owns the two extra island regions (80 → 82 sub-regions).
+  - Deployed to `https://history.dev.kkhost.pl` with the authorized **clean data wipe** (`docker compose down -v` → `up -d --build`; the alpha `history-data` volume was destroyed, resetting all saved games).
+
+## v0.24.0 — 2026-10-14 13:41
+- **Part 4b of #16: nation splits and merges — "LLM proposes, player confirms" is now complete.** P4a let the LLM propose a *rename* (a safe, single-field change). Now the same confirm/reject flow actually applies the two destructive ops: a **split** (one nation dissolves into several) and a **merge** (several nations fold into one). This is the last piece of #16 — all three `NationOp` kinds are now applied on player confirm.
+  - **Split (`server/engine.ts`).** `applyNationOp` now handles `kind: "split"`: it resolves the parent `nationRef` and requires **≥2** named parts (fewer → a safe no-op, the op is still resolved and removed). It partitions the parent's **region-key** territory across the parts **in order** — each part gets the keys of its `territory` that the parent actually owns and that no earlier part claimed (the **first part to name a key wins**, so a key is never held twice); any of the parent's keys no part claimed go to **part 0** (in the parent's territory order), so nothing is orphaned. Each new nation gets a **fresh id** (`freshNationId`: first free of `n1`, `n2`, …, tracked in a running `taken` set so ids never collide within the op), the baseline `NEW_NATION_STATS` (a neutral 50/50/50/50 profile — *not* a copy of the parent's, since a small rump state is not the parent's power), a copy of the parent's relations, and the parent's `type`; the parent is then removed and its id dropped from every other nation's relations map (`dropRelationsTo`). If the **parent was the player's nation**, `playerNationId` moves to the chosen part (`edits.playerPart`, clamped into range, default 0) — that same part also receives an `edits.name` override.
+  - **Merge (`server/engine.ts`).** `kind: "merge"`: every input ref and the survivor ref must resolve, at least **two distinct** inputs are required, and the **survivor must be one of the inputs** — any failure is a safe no-op. The survivor keeps its **id** and its **own stats**; it gains the **union of all inputs' territories** (the survivor's keys first, then each other input's unclaimed keys in its own order) and a **union of the inputs' relations** (the survivor's own view of a third party wins, else the first input's); it is renamed to `edits.name` → `into` → its own name (in that precedence). The other inputs are removed and their ids dropped from every remaining nation's relations maps; if the **player led a removed input**, `playerNationId` moves to the survivor.
+  - **Confirm contract extended (`shared/protocol.ts`).** `ConfirmNationOpRequest.edits` is now `{ name?: string; playerPart?: number }` — `name` overrides a rename's target or a merge's merged name; `playerPart` picks which new part the player's nation becomes in a split (default 0). The `SplitOp` / `MergeOp` / `NationOp` doc comments and the `TurnResult.nationOps` doc now describe the *applied* semantics (no longer "a no-op until P4b").
+  - **Prompt (`server/engine.ts`).** The system prompt's JSON contract now shows all three `nationOps` shapes (rename / split / merge), and the HARD CONSTRAINTS gain one line per op explaining when to use it and the "≥2 parts" / "survivor must be an input" rules — so the model knows what it may propose and that each is a player-confirmed PROPOSAL.
+  - **Client (`src/components/NationOpDialog.tsx`).** The dialog now renders all three kinds with a Confirm button (no more "dismiss-only" split/merge rows): a **split** lists each part (name + the number of regions it was assigned) and, when the split's parent is the **player's own nation**, shows a **radio group** to pick which new part the player leads (preselected 0, so the choice is always valid); a **merge** shows the input nations as chips (the **survivor** highlighted) and an **editable name** for the merged state (defaulting to `into`). Rename keeps its editable-name behavior. The new `onConfirm(index, edits?)` signature threads `playerPart` through `ActionPanel` and `App.tsx` (`runConfirmNationOp`) to the API helper.
+  - **Defensive invariants.** All ops are **pure and never throw**: an unresolvable or ambiguous ref, too few parts, or a survivor that isn't an input makes the op a no-op on the world (the proposal is still resolved and removed on confirm, mirroring P4a's ambiguous-ref behavior). **Sole ownership** is preserved by construction (a key lands in at most one new part / one survivor), and `playerNationId` is always re-pointed to a still-existing nation. The **stub is unchanged** — it still never proposes a nation op (`nationOps: []`) — so, like P4a/P4b before it, the new paths are covered by **unit tests only** and the e2e suite (CI, `LLM_STUB=1`) is unaffected.
+- **Tests (`server/engine.test.ts`).** New `freshNationId`, `applyNationOp (split)`, and `applyNationOp (merge)` suites: the partition (first-wins, leftovers-to-part-0, sole ownership, fresh ids/stats/relations, parent removed, relations cleanup, player-pointer move, clamped `playerPart`, `edits.name` on the chosen part), the merge (union territory, survivor stats, relations union with survivor-wins, removed ids dropped from everyone else, into-name, player-pointer move, and the four no-op guards), plus an updated prompt-contract test asserting all three op shapes. The old "split/merge is a no-op" P4a test is retargeted to a 1-part split. The unit suite grows **151 → 164**.
+- **Verification.** Typecheck, lint, **164 unit tests**, and the production build all pass. The e2e suite (CI, `LLM_STUB=1`) carries no nation-op assertions, so it stays green with the unchanged stub.
+- **Deploy:** manual `docker compose up -d --build` on the host (no `down -v`).
+- Part of #16 — major nation changes (P4b, the final part of the epic). #16 was already closed (2026-10-12, after P3 shipped); the PR references it for traceability the same way P4a's PR #38 did ("Part of #16" / "Related: #16") — no auto-close.
+
+## v0.23.0 — 2026-10-14 12:58
+- **Part 4a of #16: nation renames — "LLM proposes, player confirms."** The LLM can now propose that a nation be renamed during a turn. Unlike stat/relation/territory changes (applied automatically), a rename is stored as a **pending proposal** (`GameState.pendingNationOps`) and only takes effect when the player **confirms** it (optionally editing the new name) or is dropped on **reject**. This is the first of the "major nation changes" the LLM may propose — the `NationOp` contract is stable now; **split** and **merge** are declared in the same union but are *accepted-and-stored, not applied* until P4b.
+  - **New `NationOp` union (`shared/protocol.ts`).** `rename` / `split` / `merge`, discriminated by `kind`. Each names its target via a `nationRef` the LLM may give as either a nation **id** or **name**. `TurnResult.nationOps` is a **required** `NationOp[]` (the model's proposals this turn); the confirm/reject request types (`NationOpConfirmRequest` `{index, edits?{name?}}`, `NationOpRejectRequest` `{index}`, response `{game}`) live here too.
+  - **`GameState.pendingNationOps` (`shared/types.ts`, type-only import of `NationOp`)** — the proposals awaiting the player's decision. A turn **appends** to it (never clears it on commit), so a proposal persists across turns until confirmed or rejected. Legacy SQLite rows and new games default it to `[]` (`server/db.ts`).
+  - **Engine (`server/engine.ts`), all pure.** `resolveNationRef` resolves a `nationRef` id-first, then a case-insensitive unique-name match (returns `null` for unknown/ambiguous — never throws). `validateNationOps` drops invalid ops defensively. `applyTurnResult` keeps existing pending ops and appends the turn's valid ones (a rename-only turn is `isMeaningful`, so it survives the retry/nudge path). `applyNationOp` mutates a clone (rename → `Nation.name` = edited value or the proposed `to`; split/merge are no-ops for now). `confirmNationOp`/`rejectNationOp` splice by index and bump `version` once (invalid index → `null`). The system prompt (both tool-mode and plain-mode) gains the `nationOps` JSON field and the rename-proposal rule.
+  - **Routes + client.** `POST /api/games/:id/nation-op/confirm` and `.../reject` (404 unknown game, 400 bad index), each returning `{ game }` and broadcasting a version-bumped SSE `state` — mirroring the existing queue add/remove routes. The "Your move" panel shows a "Nation proposals (N)" trigger that opens a dialog listing each pending op; a rename has an editable name field plus **Confirm**/**Reject**, and split/merge offer **Dismiss** (they aren't applied yet).
+  - **Stub + tests.** The deterministic stub **never** proposes a nation op (`nationOps: []`), so this path is covered by **unit tests only** (mirroring the P3 no-man's-land approach) — `server/engine.test.ts` gains suites for `resolveNationRef`, `validateNationOps`, `applyNationOp`/confirm/reject (incl. an invalid-index 400 and the version-bump), and the prompt contract. The unit suite grows **127 → 151**; the e2e suite is unaffected.
+- **Verification.** Typecheck, lint, **151 unit tests**, and the production build all pass. The e2e suite (CI, `LLM_STUB=1`) has no nation-op assertions, so it stays green with the unchanged stub.
+- **Deploy:** manual `docker compose up -d --build` on the host (no `down -v`).
+- Part of #16 — major nation changes (P4a); #16 stays open (P4b: split/merge).
+
 ## v0.22.0 — 2026-10-14 12:02
 - **Part 3 of #16: no man's land — a region can be left unowned mid-game and re-claimed later.** After a war or cataclysm the LLM can leave a region without an owner: it lists the key in the new `TurnResult.unowned` field (and narrates the cause in `events`); the engine removes the key from its sole owner, and the region ends the turn ownerless. A later ordinary `gain` on that key is a **re-claim** — the key is granted to the (sole) gainer and removed from the no-man's-land list. A fresh game always starts fully owned (no man's land can only arise mid-game).
   - **Engine (`server/engine.ts`).** `applyTurnResult` applies **releases first**: a key is released only when it has exactly one current owner (0 owners — a preset never assigned it — is a no-op, so no man's land can never be fabricated from an ordinary unowned region; 2+ owners — corruption — is a no-op; already-unowned is a no-op). Claims are then resolved against the post-release ownership snapshot: sole gainer + sole owner ≠ gainer = a transfer (the v0.21 rules, unchanged); sole gainer + no owner = a re-claim; a double claim is still rejected. Invariants after every turn: no key sits in two or more territories, a released key sits in none, and `GameState.unowned` holds exactly the keys released mid-game. A lone release counts as `isMeaningful` (it survives the retry/nudge path instead of being replaced by the generic "unclear" result). The system prompt gains the JSON field, the no-man's-land rule (in both tool-mode and plain-mode), and the hard constraint that `unowned` may contain only region keys a nation currently owns. The user payload always carries the current `GameState.unowned` as `unowned` (even when empty), and the jump route's `regions` reference table now includes the released keys so the model can name them when re-claiming.

e2e/scenario.spec.ts

@@ -0,0 +1,253 @@
+import { test, expect, type Page } from '@playwright/test';
+
+/**
+ * Dynamic scenario generation — end to end (v0.31, #52). Fully deterministic
+ * under the SCENARIO stub (the Playwright webServer boots with LLM_STUB=1, so
+ * the two generation calls ride the deterministic transport in
+ * server/stubScenario.ts — the turn stub in server/stub.ts is untouched).
+ *
+ * The stub returns a FIXED 3-nation world and a FIXED 3-checkpoint list for
+ * the generate step, and — on the finalize step — refines that world in a
+ * deterministic way that depends on which checkpoints the player approved
+ * (each approved checkpoint naming one of the fixed nations, by its first 4
+ * letters, raises that nation's stability by 5). So the whole two-step
+ * "Create scenario" path plus the resulting game is reproducible:
+ *
+ *   home → "Create scenario" → pick the Near Future era (2035) + a description
+ *   → generate (draft: alba/boreas/gamma + 3 checkpoints) → review (remove the
+ *   3rd checkpoint, keep the first two) → lead Boreas → finalize → a saved,
+ *   playable game (turn 1, date 2035-01-01, player Boreas) → one empty jump
+ *   (turn 2, date 2035-01-03, Boreas military 55→60, allied with Alba, and no
+ *   territory change — Russia shares no land border with France or Spain).
+ *
+ * The e2e webServer shares one SQLite (data/e2e) across tests, so the test
+ * captures the *specific* id of the game it creates (from the POST
+ * /api/scenarios/commit response) rather than assuming "the only game".
+ */
+
+/** The saved-game shape the assertions read back from GET /api/games/<id>. */
+interface SavedGame {
+  id: string;
+  presetId: string;
+  presetTitle: string;
+  playerNationId: string;
+  turn: number;
+  date: string;
+  version: number;
+  pending: unknown[];
+  unowned: string[];
+  pendingNationOps: unknown[];
+  markers: unknown[];
+  events: Array<{ type: string; outcome: string; title: string }>;
+  nations: Record<
+    string,
+    {
+      name: string;
+      stats: { military: number; economy: number; stability: number; population: number };
+      territory: string[];
+      relations: Record<string, string>;
+    }
+  >;
+  regionStats: Record<
+    string,
+    { military: number; economy: number; stability: number; population: number }
+  >;
+}
+
+/** Poll until `location.hash` equals `expected` (hash writes happen in effects). */
+async function waitHash(page: Page, expected: string): Promise<void> {
+  await page.waitForFunction(
+    (exp) => window.location.hash === exp,
+    expected,
+    { timeout: 15000 },
+  );
+}
+
+/** Open the "Create scenario" form from the home screen. */
+async function openScenarioForm(page: Page): Promise<void> {
+  await page.goto('/');
+  // Home: the create-scenario card is additive (first in the grid); the five
+  // static presets are still all present alongside it.
+  await expect(page.getByTestId('create-scenario-card')).toBeVisible({ timeout: 15000 });
+  await expect(page.getByTestId('preset-card')).toHaveCount(5);
+  await page.getByTestId('create-scenario').click();
+  await expect(page.getByTestId('scenario-form')).toBeVisible({ timeout: 15000 });
+}
+
+test.describe('History — dynamic scenario generation (LLM_STUB=1)', () => {
+  test('the era template manifest renders three light templates', async ({ page }) => {
+    test.setTimeout(60000);
+    await openScenarioForm(page);
+
+    // Exactly three era-template cards, each carrying its id and default year.
+    const cards = page.getByTestId('template-card');
+    await expect(cards).toHaveCount(3, { timeout: 15000 });
+    await expect(page.locator('[data-template-id="ww2"]')).toContainText('1939');
+    await expect(page.locator('[data-template-id="present"]')).toContainText('2026');
+    await expect(page.locator('[data-template-id="near-future"]')).toContainText('2035');
+  });
+
+  test('full create → review → finalize → play flow is deterministic', async ({ page }) => {
+    test.setTimeout(120000);
+    await openScenarioForm(page);
+
+    // --- 1 · Pick the Near Future era (its default year pre-fills the field).
+    const nf = page.locator('[data-template-id="near-future"]');
+    await nf.click();
+    await expect(nf).toHaveAttribute('data-selected', 'true');
+    // The year field is pre-filled from the era (editable, a real value).
+    await expect(page.getByTestId('scenario-year')).toHaveValue('2035');
+
+    // --- 2 · Describe the world.
+    const description =
+      'A cold space race decides the new cold war: two orbital blocs hold the arctic shipping lanes at knife-edge.';
+    await page.getByTestId('scenario-description').fill(description);
+
+    // --- Step 1 · Generate the draft world + the advisor's checkpoint list.
+    const generate = page.getByTestId('generate-scenario');
+    await expect(generate).toBeEnabled();
+    const [draftResp] = await Promise.all([
+      page.waitForResponse(
+        (r) => r.request().method() === 'POST' && new URL(r.url()).pathname === '/api/scenarios/draft',
+      ),
+      generate.click(),
+    ]);
+    expect(draftResp.status()).toBe(200);
+    const draft = (await draftResp.json()) as {
+      world: {
+        nations: Array<{ id: string; name: string; territory: string[] }>;
+      };
+      checkpoints: string[];
+    };
+    // The stub's fixed 3-nation world (FRA / RUS / ESP) and 3 checkpoints.
+    expect(draft.world.nations.map((n) => n.id).sort()).toEqual(['alba', 'boreas', 'gamma']);
+    expect(draft.world.nations.find((n) => n.id === 'boreas')?.territory).toEqual(['RUS']);
+    expect(draft.checkpoints).toHaveLength(3);
+
+    // --- Review screen: the generated world + the checkpoint checklist.
+    await expect(page.getByTestId('scenario-review')).toBeVisible({ timeout: 15000 });
+    // Header shows the era's name + year and the description.
+    await expect(page.getByRole('heading', { name: 'Near Future' })).toBeVisible();
+    await expect(page.getByTestId('scenario-review')).toContainText('2035');
+    await expect(page.getByTestId('scenario-review')).toContainText(description);
+    // The three draft nations (with their ISO_A3 territory) and the backstory.
+    // Scope to the draft-nation cards (the nation-pick cards share the
+    // data-nation-id attribute but carry a different testid).
+    await expect(page.getByTestId('draft-nation')).toHaveCount(3);
+    await expect(page.locator('[data-testid="draft-nation"][data-nation-id="alba"]')).toContainText('FRA');
+    await expect(page.locator('[data-testid="draft-nation"][data-nation-id="boreas"]')).toContainText('RUS');
+    await expect(page.locator('[data-testid="draft-nation"][data-nation-id="gamma"]')).toContainText('ESP');
+    await expect(page.getByTestId('draft-event')).toHaveCount(1);
+    // Three checkpoints, all approved by default, in the stub's fixed order.
+    const cps = page.getByTestId('checkpoint-item');
+    await expect(cps).toHaveCount(3);
+    await expect(cps.nth(0)).toHaveAttribute('data-approved', 'true');
+    await expect(cps.nth(1)).toHaveAttribute('data-approved', 'true');
+    await expect(cps.nth(2)).toHaveAttribute('data-approved', 'true');
+    await expect(cps.nth(0)).toContainText('Alba dominates');
+    await expect(cps.nth(1)).toContainText('Boreas fortifies');
+    await expect(cps.nth(2)).toContainText('Gamma brokers');
+    // Three nation-pick cards; finalize is disabled until a nation is chosen.
+    await expect(page.getByTestId('scenario-nation-card')).toHaveCount(3);
+    await expect(page.getByTestId('finalize-scenario')).toBeDisabled();
+
+    // --- Review: remove checkpoint 3, keep 1 + 2.
+    await cps.nth(2).getByTestId('checkpoint-toggle').click();
+    await expect(cps.nth(2)).toHaveAttribute('data-approved', 'false');
+    await expect(cps.nth(0)).toHaveAttribute('data-approved', 'true');
+    await expect(cps.nth(1)).toHaveAttribute('data-approved', 'true');
+    await expect(page.getByTestId('scenario-review')).toContainText('2 of 3 approved');
+
+    // --- Review: choose Boreas (Russia) to lead.
+    const boreasCard = page.locator('[data-testid="scenario-nation-card"][data-nation-id="boreas"]');
+    await boreasCard.getByTestId('scenario-lead-nation').click();
+    await expect(boreasCard).toHaveAttribute('data-selected', 'true');
+    await expect(page.getByTestId('finalize-scenario')).toBeEnabled();
+
+    // --- Step 2 · Finalize: commit the approved draft into a saved game.
+    const [commitResp] = await Promise.all([
+      page.waitForResponse(
+        (r) => r.request().method() === 'POST' && new URL(r.url()).pathname === '/api/scenarios/commit',
+      ),
+      page.getByTestId('finalize-scenario').click(),
+    ]);
+    expect(commitResp.status()).toBe(200);
+    const { id } = (await commitResp.json()) as { id: string };
+    expect(id).toBeTruthy();
+
+    // --- The new game mounts at turn 1, leading Boreas, dated 2035-01-01.
+    await expect(page.getByTestId('world-map')).toBeVisible({ timeout: 20000 });
+    await expect(page.getByTestId('turn-count')).toHaveText('1');
+    await expect(page.getByTestId('game-date')).toHaveText('2035-01-01');
+    await expect(page.getByTestId('player-nation')).toHaveText('Boreas');
+    // The scenario title (the era name) is shown in the top bar.
+    await expect(page.getByTestId('top-bar')).toContainText('Near Future');
+    // Boreas's stats: the finalized world (its approved checkpoint raised
+    // stability 50→55); per-region stats are seeded to equal the derived.
+    await expect(page.getByTestId('stat-military')).toHaveText('55');
+    await expect(page.getByTestId('stat-economy')).toHaveText('70');
+    await expect(page.getByTestId('stat-stability')).toHaveText('55');
+    await expect(page.getByTestId('stat-population')).toHaveText('60');
+    // One backstory event; three nations on the legend.
+    await expect(page.getByTestId('event-item')).toHaveCount(1);
+    await expect(page.getByTestId('map-legend-item')).toHaveCount(3, { timeout: 15000 });
+    await expect(page.getByTestId('map-legend-item').filter({ hasText: 'Boreas' })).toBeVisible();
+    // The deep link lands on this exact game.
+    await waitHash(page, `#/game/${id}`);
+
+    // --- One empty jump: the world advances on its own (the turn stub).
+    // The button sits at the bottom of a scrollable window body and may be
+    // outside the viewport; a native DOM click bypasses the viewport check.
+    await page.getByTestId('jump-forward').evaluate((el) => (el as HTMLElement).click());
+
+    // Turn 2, date +2 days, Boreas military 55→60.
+    await expect(page.getByTestId('turn-count')).toHaveText('2', { timeout: 20000 });
+    await expect(page.getByTestId('stat-military')).toHaveText('60', { timeout: 20000 });
+    await expect(page.getByTestId('game-date')).toHaveText('2035-01-03', { timeout: 20000 });
+    // Two events now (the empty-round "world moves on" on top, then the
+    // backstory); both political/neutral.
+    await expect(page.getByTestId('event-item')).toHaveCount(2);
+    await expect(page.getByTestId('event-item').first()).toContainText('The world moves on');
+    await expect(page.getByTestId('event-item').first().getByTestId('event-type')).toHaveText('political');
+    await expect(page.getByTestId('event-item').first().getByTestId('event-outcome')).toHaveText('neutral');
+    await expect(page.getByTestId('event-item').nth(1)).toContainText('The new order takes shape');
+    // No territory change: Russia shares no land border with France or Spain,
+    // so the frontier is empty and no conquest is emitted.
+    await expect(page.getByTestId('map-legend-item')).toHaveCount(3, { timeout: 15000 });
+
+    // --- The saved game is a coherent dynamic GameState on the server.
+    const saved = await page.evaluate(async (gid) => {
+      const r = await fetch(`/api/games/${gid}`);
+      return { status: r.status, body: (await r.json()) as { game: SavedGame } };
+    }, id);
+    expect(saved.status).toBe(200);
+    const g = saved.body.game;
+    expect(g.presetId).toBe('dynamic');
+    expect(g.presetTitle).toBe('Near Future');
+    expect(g.playerNationId).toBe('boreas');
+    expect(g.turn).toBe(2);
+    expect(g.date).toBe('2035-01-03');
+    expect(g.version).toBe(2); // created at 1, bumped to 2 by the jump
+    expect(g.pending).toEqual([]);
+    expect(g.unowned).toEqual([]);
+    expect(g.pendingNationOps).toEqual([]);
+    expect(g.markers).toEqual([]);
+    expect(g.events).toHaveLength(2);
+    // Boreas after the jump: military bumped to 60, the rest untouched.
+    expect(g.nations.boreas.stats).toEqual({
+      military: 60,
+      economy: 70,
+      stability: 55,
+      population: 60,
+    });
+    // The stub allies the player with the first other nation (Alba).
+    expect(g.nations.boreas.relations.alba).toBe('ally');
+    // Every owned region key carries a seeded per-region stats entry.
+    const allKeys = new Set<string>();
+    for (const n of Object.values(g.nations)) for (const k of n.territory) allKeys.add(k);
+    expect(allKeys.size).toBeGreaterThan(0);
+    for (const k of allKeys) {
+      expect(g.regionStats[k]).toBeDefined();
+    }
+  });
+});

package.json

@@ -1,6 +1,6 @@
 {
   "name": "history",
-  "version": "0.22.0",
+  "version": "0.35.0",
   "private": true,
   "type": "module",
   "description": "AI-driven alternate-history simulator — the LLM is the world engine (Pax Historia style).",
@@ -14,8 +14,13 @@
     "cleanup:regions": "node scripts/cleanup-regions.mjs",
     "smooth:regions": "node scripts/smooth-regions.mjs",
     "fill:regions": "node scripts/fill-gaps.mjs",
+    "split:regions": "node scripts/split-arkhangel.mjs",
+    "split:regions:band": "node scripts/split-arkhangel-band.mjs",
     "build:region-keys": "node scripts/build-region-keys.mjs",
     "build:region-adjacency": "node scripts/build-region-adjacency.mjs",
+    "build:region-centroids": "node scripts/build-region-centroids.mjs",
+    "build:region-geo": "node scripts/build-region-geo.mjs",
+    "extract:admin0-pop": "node scripts/extract-admin0-pop.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "e2e": "playwright test"

presets/templates/index.json

@@ -0,0 +1,20 @@
+[
+  {
+    "id": "ww2",
+    "name": "World War II",
+    "year": 1939,
+    "eraDescription": "Europe teeters on the brink of total war. Fascist powers press their advantage across the continent while the democracies marshal their strength."
+  },
+  {
+    "id": "present",
+    "name": "Present Day",
+    "year": 2026,
+    "eraDescription": "A multipolar world of blocs, sanctions, and tech supremacy. Climate strain, AI, and great-power rivalry shape every decision."
+  },
+  {
+    "id": "near-future",
+    "name": "Near Future",
+    "year": 2035,
+    "eraDescription": "Autonomous fleets, orbital assets, and climate-hamstrung coastlines. Old alliances strain under new technologies and old grievances."
+  }
+]

presets/templates/near-future.json

@@ -0,0 +1,17 @@
+{
+  "id": "near-future",
+  "name": "Near Future",
+  "year": 2035,
+  "eraDescription": "A near-future world: autonomous fleets, orbital assets, and climate-hamstrung coastlines. Old alliances strain under new technologies and old grievances as the great powers reach for the next horizon.",
+  "suggestedPowers": [
+    { "name": "North American Union", "region": "USA", "note": "The industrial-technological core of the West." },
+    { "name": "Chinese Federation", "region": "CHN", "note": "The integrated superpower of the Pacific." },
+    { "name": "European Confederation", "region": "FRA", "note": "The united European bloc." },
+    { "name": "Russian Union", "region": "RUS", "note": "The resource frontier state." }
+  ],
+  "tensions": [
+    "Autonomous weapons and the new arms race",
+    "Climate migration and resource wars",
+    "The contest for space and orbital dominance"
+  ]
+}

presets/templates/present.json

@@ -0,0 +1,17 @@
+{
+  "id": "present",
+  "name": "Present Day",
+  "year": 2026,
+  "eraDescription": "A multipolar world of blocs, sanctions, and tech supremacy. Climate strain, artificial intelligence, and great-power rivalry shape every decision the leaders of the age must make.",
+  "suggestedPowers": [
+    { "name": "United States", "region": "USA", "note": "The military-technological leader of the Western bloc." },
+    { "name": "People's Republic of China", "region": "CHN", "note": "The industrial giant pressing on the Western Pacific." },
+    { "name": "Russian Federation", "region": "RUS", "note": "A resource-rich power testing its neighbors' resolve." },
+    { "name": "European Union", "region": "FRA", "note": "A large, internally divided economic bloc." }
+  ],
+  "tensions": [
+    "US–China tech and trade rivalry",
+    "The war in Europe and the eastern flank",
+    "AI and cyber dominance"
+  ]
+}

presets/templates/ww2.json

@@ -0,0 +1,17 @@
+{
+  "id": "ww2",
+  "name": "World War II",
+  "year": 1939,
+  "eraDescription": "Europe teeters on the brink of total war. Fascist powers press their advantage across the continent while the democracies marshal their strength, and the great powers watch — and arm — from across the oceans.",
+  "suggestedPowers": [
+    { "name": "German Reich", "region": "DEU", "note": "A militarized Reich at the heart of the continent, its army the most battle-hardened in Europe." },
+    { "name": "United Kingdom", "region": "GBR", "note": "An island power that commands the seas but is cut off from the continent." },
+    { "name": "Soviet Union", "region": "RUS", "note": "A vast, fragile industrial giant on the eastern frontier." },
+    { "name": "United States", "region": "USA", "note": "An industrial colossus, still politically divided over entry into the war." }
+  ],
+  "tensions": [
+    "The Axis versus the Allies",
+    "The race for continental resources and sea lanes",
+    "The uneasy balance before the bomb"
+  ]
+}

public/ne-admin0-pop.json

@@ -0,0 +1,251 @@
+{
+  "ABW": 106314,
+  "AFG": 38041754,
+  "AGO": 31825295,
+  "AIA": 14731,
+  "ALB": 2854191,
+  "ALD": 29884,
+  "AND": 77142,
+  "ARE": 9770529,
+  "ARG": 44938712,
+  "ARM": 2957731,
+  "ASM": 55312,
+  "ATA": 4490,
+  "ATF": 140,
+  "ATG": 97118,
+  "AUS": 25364307,
+  "AUT": 8877067,
+  "AZE": 10023318,
+  "BDI": 11530580,
+  "BEL": 11484055,
+  "BEN": 11801151,
+  "BFA": 20321378,
+  "BGD": 163046161,
+  "BGR": 6975761,
+  "BHR": 1641172,
+  "BHS": 389482,
+  "BIH": 3301000,
+  "BLM": 9961,
+  "BLR": 9466856,
+  "BLZ": 390353,
+  "BMU": 63918,
+  "BOL": 11513100,
+  "BRA": 211049527,
+  "BRB": 287025,
+  "BRN": 433285,
+  "BTN": 763092,
+  "BWA": 2303697,
+  "CAF": 4745185,
+  "CAN": 37589262,
+  "CHE": 8574832,
+  "CHL": 18952038,
+  "CHN": 1397715000,
+  "CIV": 25716544,
+  "CMR": 25876380,
+  "CNM": 10000,
+  "COD": 86790567,
+  "COG": 5380508,
+  "COK": 17459,
+  "COL": 50339443,
+  "COM": 850886,
+  "CPV": 549935,
+  "CRI": 5047561,
+  "CSI": 4,
+  "CUB": 11333483,
+  "CUW": 157538,
+  "CYM": 64948,
+  "CYN": 326000,
+  "CYP": 1198575,
+  "CZE": 10669709,
+  "DEU": 83132799,
+  "DJI": 973560,
+  "DMA": 71808,
+  "DNK": 5818553,
+  "DOM": 10738958,
+  "DZA": 43053054,
+  "ECU": 17373662,
+  "EGY": 100388073,
+  "ERI": 6081196,
+  "ESB": 7850,
+  "ESP": 47076781,
+  "EST": 1326590,
+  "ETH": 112078730,
+  "FIN": 5520314,
+  "FJI": 889953,
+  "FLK": 3398,
+  "FRA": 67059887,
+  "FRO": 48678,
+  "FSM": 113815,
+  "GAB": 2172579,
+  "GBR": 66834405,
+  "GEO": 3720382,
+  "GGY": 62792,
+  "GHA": 30417856,
+  "GIB": 33701,
+  "GIN": 12771246,
+  "GMB": 2347706,
+  "GNB": 1920922,
+  "GNQ": 1355986,
+  "GRC": 10716322,
+  "GRD": 112003,
+  "GRL": 56225,
+  "GTM": 16604026,
+  "GUM": 167294,
+  "GUY": 782766,
+  "HKG": 7507400,
+  "HND": 9746117,
+  "HRV": 4067500,
+  "HTI": 11263077,
+  "HUN": 9769949,
+  "IDN": 270625568,
+  "IMN": 84584,
+  "IND": 1366417754,
+  "IOA": 2387,
+  "IOT": 3000,
+  "IRL": 4941444,
+  "IRN": 82913906,
+  "IRQ": 39309783,
+  "ISL": 361313,
+  "ISR": 9053300,
+  "ITA": 60297396,
+  "JAM": 2948279,
+  "JEY": 107800,
+  "JOR": 10101694,
+  "JPN": 126264931,
+  "KAB": 36175,
+  "KAS": 6000,
+  "KAZ": 18513930,
+  "KEN": 52573973,
+  "KGZ": 6456900,
+  "KHM": 16486542,
+  "KIR": 117606,
+  "KNA": 52834,
+  "KOR": 51709098,
+  "KOS": 1794248,
+  "KWT": 4207083,
+  "LAO": 7169455,
+  "LBN": 6855713,
+  "LBR": 4937374,
+  "LBY": 6777452,
+  "LCA": 182790,
+  "LIE": 38019,
+  "LKA": 21803000,
+  "LSO": 2125268,
+  "LTU": 2786844,
+  "LUX": 619896,
+  "LVA": 1912789,
+  "MAC": 640445,
+  "MAF": 38002,
+  "MAR": 36471769,
+  "MCO": 38964,
+  "MDA": 2657637,
+  "MDG": 26969307,
+  "MDV": 530953,
+  "MEX": 127575529,
+  "MHL": 58791,
+  "MKD": 2083459,
+  "MLI": 19658031,
+  "MLT": 502653,
+  "MMR": 54045420,
+  "MNE": 622137,
+  "MNG": 3225167,
+  "MNP": 57216,
+  "MOZ": 30366036,
+  "MRT": 4525696,
+  "MSR": 4649,
+  "MUS": 1265711,
+  "MWI": 18628747,
+  "MYS": 31949777,
+  "NAM": 2494530,
+  "NCL": 287800,
+  "NER": 23310715,
+  "NFK": 2169,
+  "NGA": 200963599,
+  "NIC": 6545502,
+  "NIU": 1620,
+  "NLD": 17332850,
+  "NOR": 5347896,
+  "NPL": 28608710,
+  "NRU": 12581,
+  "NZL": 4917000,
+  "OMN": 4974986,
+  "PAK": 216565318,
+  "PAN": 4246439,
+  "PCN": 54,
+  "PER": 32510453,
+  "PGA": 100,
+  "PHL": 108116615,
+  "PLW": 18008,
+  "PNG": 8776109,
+  "POL": 37970874,
+  "PRI": 3193694,
+  "PRK": 25666161,
+  "PRT": 10269417,
+  "PRY": 7044636,
+  "PSX": 4685306,
+  "PYF": 279287,
+  "QAT": 2832067,
+  "ROU": 19356544,
+  "RUS": 144373535,
+  "RWA": 12626950,
+  "SAH": 603253,
+  "SAU": 34268528,
+  "SDN": 42813238,
+  "SDS": 11062113,
+  "SEN": 16296364,
+  "SGP": 5703569,
+  "SGS": 30,
+  "SHN": 4534,
+  "SLB": 669823,
+  "SLE": 7813215,
+  "SLV": 6453553,
+  "SMR": 33860,
+  "SOL": 5096159,
+  "SOM": 10192317,
+  "SPM": 5997,
+  "SRB": 6944975,
+  "STP": 215056,
+  "SUR": 581363,
+  "SVK": 5454073,
+  "SVN": 2087946,
+  "SWE": 10285453,
+  "SWZ": 1148130,
+  "SXM": 40733,
+  "SYC": 97625,
+  "SYR": 17070135,
+  "TCA": 38191,
+  "TCD": 15946876,
+  "TGO": 8082366,
+  "THA": 69625582,
+  "TJK": 9321018,
+  "TKM": 5942089,
+  "TLS": 1293119,
+  "TON": 104494,
+  "TTO": 1394973,
+  "TUN": 11694719,
+  "TUR": 83429615,
+  "TUV": 11646,
+  "TWN": 23568378,
+  "TZA": 58005463,
+  "UGA": 44269594,
+  "UKR": 44385155,
+  "UMI": 300,
+  "URY": 3461734,
+  "USA": 328239523,
+  "USG": 6000,
+  "UZB": 33580650,
+  "VAT": 825,
+  "VCT": 110589,
+  "VEN": 28515829,
+  "VGB": 30030,
+  "VIR": 106631,
+  "VNM": 96462106,
+  "VUT": 299882,
+  "WLF": 11558,
+  "WSB": 7850,
+  "WSM": 197097,
+  "YEM": 29161922,
+  "ZAF": 58558270,
+  "ZMB": 17861030,
+  "ZWE": 14645468
+}

public/region-adjacency.json

@@ -7587,6 +7587,7 @@
   "nenets-qyga": [
     "arkhangel-sk-lhbk",
     "komi-eoeh",
+    "pechora-qwhs",
     "yamal-nenets-aqsx"
   ],
   "neuquen-yvne": [
@@ -7614,6 +7615,7 @@
     "ontario-bzqu",
     "quebec-yegk"
   ],
+  "new-earth-eikt": [],
   "new-hampshire-koki": [
     "maine-maiz",
     "massachusetts-ggid",
@@ -8748,6 +8750,10 @@
     "soriano-ixbv",
     "tacuarembo-yekg"
   ],
+  "pechora-qwhs": [
+    "nenets-qyga",
+    "yamal-gosw"
+  ],
   "peloponnisos-wqyw": [
     "dytiki-ellada-mlyj",
     "sterea-ellada-inyu"
@@ -10010,6 +10016,9 @@
     "medea-elbf",
     "skikda-odba"
   ],
+  "severnaya-zemlya-awqp": [
+    "yamal-gosw"
+  ],
   "sevilla-oxma": [
     "badajoz-ciwt",
     "cadiz-aazc",
@@ -12160,6 +12169,10 @@
     "iwate-uvfz",
     "niigata-idhx"
   ],
+  "yamal-gosw": [
+    "pechora-qwhs",
+    "severnaya-zemlya-awqp"
+  ],
   "yamal-nenets-aqsx": [
     "khanty-mansiy-tkto",
     "komi-eoeh",

public/region-keys.json

@@ -1305,6 +1305,10 @@
   "RU-ALT": "altay-mfuq",
   "RU-AMU": "amur-clbp",
   "RU-ARK": "arkhangel-sk-lhbk",
+  "RU-ARK-NE": "new-earth-eikt",
+  "RU-ARK-SZ": "severnaya-zemlya-awqp",
+  "RU-PEO": "pechora-qwhs",
+  "RU-YAM": "yamal-gosw",
   "RU-AST": "astrakhan-anec",
   "RU-BA": "bashkortostan-uovk",
   "RU-BEL": "belgorod-wxjk",

scripts/build-region-centroids.mjs

@@ -0,0 +1,132 @@
+/**
+ * scripts/build-region-centroids.mjs — build the precomputed region-centroid
+ * manifest: `public/region-centroids.json` = `{ "<regionKey>": { "lat": <number>, "lon": <number>, "spread": <number> }, ... }`.
+ *
+ * For every sub-region (region key, see `public/region-keys.json`) this records
+ * the point the LLM's map markers (v0.27, #44) will be anchored to: the
+ * **centroid of the region's largest-area part** (a MultiPolygon's biggest
+ * island/lake-piece rather than an area-weighted average of all parts), plus
+ * a `spread` value ≈ 0.1 × the smallest bbox dimension of that part (in
+ * degrees) — the engine scatters markers of one region within ±(spread/2)
+ * around the centroid using a deterministic per-marker offset, so several
+ * markers of the same region do not stack on one pixel.
+ *
+ * Method — plain turf on the pre-generated geo file (turf is allowed in .mjs
+ * scripts; it is deliberately kept OUT of the TS typecheck program, see the
+ * v0.17 note). For each feature we (1) split a MultiPolygon into its parts
+ * (a plain Polygon is its own single part), (2) pick the part with the
+ * greatest `@turf/area`, (3) take `@turf/centroid` of that part and
+ * `@turf/bbox` of that part, and (4) round everything to 6 decimal places
+ * (≈ 0.1 m at this scale — far below the map's visual precision).
+ *
+ * Output contract (asserted by scripts/region-centroids.test.ts):
+ *   - one entry for **every** region key, keyed identically to
+ *     `public/region-keys.json` (same key set, 1,800 entries);
+ *   - each centroid lies inside its region's (largest part's) bbox;
+ *   - `spread` is a non-negative number of degrees (0 for degenerate parts);
+ *   - values are rounded to at most 6 decimal places.
+ *
+ * Deterministic + idempotent: the input files are fixed, turf is a pure
+ * geometric computation, the output keeps the geo file's (stable) feature
+ * order and rounds to fixed precision — so a re-run rewrites a byte-identical
+ * file (the test re-runs this script and compares bytes).
+ *
+ * Usage: `node scripts/build-region-centroids.mjs`  (or `npm run build:region-centroids`).
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import area from '@turf/area';
+import bbox from '@turf/bbox';
+import centroid from '@turf/centroid';
+import { feature } from '@turf/helpers';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+
+const round6 = (v) => Math.round(v * 1e6) / 1e6;
+
+// --- load the geo + region-key manifest (plain parse; keys join feature->key) --
+const geo = JSON.parse(readFileSync(path.join(root, 'public', 'regions.geo.json'), 'utf8'));
+const idToKey = JSON.parse(readFileSync(path.join(root, 'public', 'region-keys.json'), 'utf8'));
+
+/**
+ * The polygon parts of a geometry: a MultiPolygon's individual polygons, a
+ * plain Polygon as its own single part, anything else as an empty list (the
+ * caller falls back to the whole-feature centroid).
+ */
+function partsOf(geometry) {
+  if (geometry?.type === 'MultiPolygon') return geometry.coordinates ?? [];
+  if (geometry?.type === 'Polygon') return [geometry.coordinates];
+  return [];
+}
+
+const manifest = {};
+let skipped = 0;
+for (const f of geo.features ?? []) {
+  const id = f.id == null ? '' : String(f.id);
+  const key = idToKey[id];
+  if (!key) continue; // a geo feature with no manifest entry is skipped
+  const parts = partsOf(f.geometry);
+  if (parts.length === 0) {
+    // Degenerate geometry (a point/line region): anchor at the feature's own
+    // centroid. Can't happen with the current 1,800-polygon dataset, but the
+    // fallback keeps the manifest complete if the generator ever changes.
+    skipped += 1;
+    const c = centroid(feature(f.geometry));
+    const b = bbox(feature(f.geometry));
+    manifest[key] = {
+      lat: round6(c.geometry.coordinates[1]),
+      lon: round6(c.geometry.coordinates[0]),
+      spread: round6(Math.min(b[2] - b[0], b[3] - b[1]) * 0.1),
+    };
+    continue;
+  }
+  // Pick the part with the greatest area (km²) and anchor to IT, so a
+  // multi-part region's markers cluster on its main mass, not between parts.
+  let best = 0;
+  let bestArea = -1;
+  for (let i = 0; i < parts.length; i++) {
+    const a = area(feature({ type: 'Polygon', coordinates: parts[i] }));
+    if (a > bestArea) {
+      bestArea = a;
+      best = i;
+    }
+  }
+  const part = feature({ type: 'Polygon', coordinates: parts[best] });
+  const c = centroid(part);
+  const b = bbox(part);
+  manifest[key] = {
+    lat: round6(c.geometry.coordinates[1]),
+    lon: round6(c.geometry.coordinates[0]),
+    spread: round6(Math.min(b[2] - b[0], b[3] - b[1]) * 0.1),
+  };
+}
+
+// --- hard assertions (the test re-checks these against the committed file) ---
+const expectedKeys = Object.values(idToKey);
+if (Object.keys(manifest).length !== expectedKeys.length) {
+  throw new Error(
+    `expected ${expectedKeys.length} centroid entries (one per region key), got ${Object.keys(manifest).length}`,
+  );
+}
+for (const k of expectedKeys) {
+  if (!(k in manifest)) throw new Error(`missing centroid for region key ${JSON.stringify(k)}`);
+}
+for (const [k, v] of Object.entries(manifest)) {
+  if (!Number.isFinite(v.lat) || !Number.isFinite(v.lon) || !Number.isFinite(v.spread)) {
+    throw new Error(`non-finite centroid for ${k}: ${JSON.stringify(v)}`);
+  }
+  if (v.spread < 0) throw new Error(`negative spread for ${k}: ${v.spread}`);
+}
+
+// --- write idempotently (stable order = insertion order = geo file order) ---
+writeFileSync(path.join(root, 'public', 'region-centroids.json'), JSON.stringify(manifest, null, 2) + '\n');
+
+// --- summary ------------------------------------------------------------------
+const spreads = Object.values(manifest).map((v) => v.spread);
+console.log(
+  `[build-region-centroids] wrote public/region-centroids.json — ${Object.keys(manifest).length} region keys` +
+    (skipped ? ` (${skipped} non-polygon fallbacks)` : '') +
+    `, spread min/max ${Math.min(...spreads)} / ${Math.max(...spreads)} deg`,
+);

scripts/build-region-geo.mjs

@@ -0,0 +1,165 @@
+/**
+ * scripts/build-region-geo.mjs — build the region **geo** manifest:
+ * `public/region-geo.json` = `{ "<regionKey>": { "area": <number>, "population": <number> }, ... }`.
+ *
+ * For every sub-region (region key, see `public/region-keys.json`) this records
+ * two facts the v0.28 per-region stats model (and its area×population weighting)
+ * needs:
+ *   - `area`       — the region's **total** surface area in km², from
+ *                    `@turf/area` on the FINAL generated feature
+ *                    (`public/regions.geo.json`) — turf reports square metres,
+ *                    so the raw value is divided by 1e6 — rounded to 2 decimals.
+ *   - `population` — the region's share of its **parent country's** real
+ *                    population (Natural Earth 1:10m admin-0 `POP_EST`, from the
+ *                    committed `public/ne-admin0-pop.json`), distributed across
+ *                    the country's sub-regions **proportional to each region's
+ *                    area** (a first-order "uniform population density within a
+ *                    country" approximation — Natural Earth admin-1, which the
+ *                    region generator uses, carries no per-unit population).
+ *
+ * Population distribution uses **largest remainder** per country, so the sum of
+ * a country's sub-region populations is EXACTLY the country's POP_EST, and the
+ * sum over all 1,800 regions is EXACTLY the sum of the 177 repo countries'
+ * POP_EST (7,654,092,021) — no rounding drift.
+ *
+ * Method — plain turf on the pre-generated geo file (turf is allowed in .mjs
+ * scripts; it is deliberately kept OUT of the TS typecheck program, see the
+ * v0.17 note). The population source is the COMMITTED `public/ne-admin0-pop.json`
+ * (a small derived table produced once by `scripts/extract-admin0-pop.mjs` from
+ * the 13 MB Natural Earth admin-0 file, which we do NOT commit) — so this build
+ * is fully reproducible in CI.
+ *
+ * Output contract (asserted by scripts/region-geo.test.ts):
+ *   - one entry for **every** region key, keyed identically to
+ *     `public/region-keys.json` (same key set, 1,800 entries);
+ *   - `area` is a finite number >= 0 (km², <= 2 decimals);
+ *   - `population` is a non-negative integer;
+ *   - the total population across all entries is a non-negative integer.
+ *
+ * Deterministic + idempotent: fixed inputs (the geo file, the key manifest, and
+ * the committed population table), pure turf, largest-remainder with a
+ * (remainder desc, key asc) tie-break, and stable sorted key order → a re-run
+ * rewrites a byte-identical file (the test re-runs this script and compares
+ * bytes).
+ *
+ * Usage: `node scripts/build-region-geo.mjs`  (or `npm run build:region-geo`).
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import area from '@turf/area';
+import { feature } from '@turf/helpers';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+
+const round2 = (v) => Math.round(v * 100) / 100;
+
+// --- load the inputs (plain parse) ------------------------------------------
+const geoPath = path.join(root, 'public', 'regions.geo.json');
+const keysPath = path.join(root, 'public', 'region-keys.json');
+const popPath = path.join(root, 'public', 'ne-admin0-pop.json');
+
+let geo, idToKey, popByCountry;
+try {
+  geo = JSON.parse(readFileSync(geoPath, 'utf8'));
+  idToKey = JSON.parse(readFileSync(keysPath, 'utf8'));
+  popByCountry = JSON.parse(readFileSync(popPath, 'utf8'));
+} catch (err) {
+  console.error(
+    `[build-region-geo] could not load the inputs (${geoPath}, ${keysPath}, ${popPath}). ` +
+      `Is public/ne-admin0-pop.json present? Regenerate it with scripts/extract-admin0-pop.mjs.`,
+  );
+  throw err;
+}
+
+/**
+ * One pass over the geo features: for each region key record its (unrounded)
+ * turf area and its parent ISO_A3, then group the keys by parent so the
+ * population can be distributed per country.
+ */
+const regionArea = new Map(); // key -> unrounded area (km²)
+const regionParent = new Map(); // key -> parent ISO_A3
+for (const f of geo.features ?? []) {
+  const id = f.id == null ? '' : String(f.id);
+  const key = idToKey[id];
+  if (!key) continue; // a geo feature with no manifest entry is skipped
+  // @turf/area reports square METRES; the manifest stores km².
+  const a = area(feature(f.geometry)) / 1e6;
+  regionArea.set(key, a);
+  regionParent.set(key, typeof f.properties?.parent === 'string' ? f.properties.parent : '');
+}
+
+// Group region keys by parent country (file order is stable, but we sort for
+// deterministic population distribution).
+const keysByCountry = new Map(); // parent -> string[] of keys
+for (const [key, parent] of regionParent) {
+  if (!parent) continue; // a region with no parent has no population source
+  const list = keysByCountry.get(parent);
+  if (list) list.push(key);
+  else keysByCountry.set(parent, [key]);
+}
+
+const population = new Map(); // key -> integer population
+for (const [parent, keys] of keysByCountry) {
+  keys.sort(); // deterministic ordering for the tie-break
+  const P = Number.isFinite(popByCountry[parent]) ? Math.max(0, popByCountry[parent]) : 0;
+  const totalArea = keys.reduce((s, k) => s + (regionArea.get(k) || 0), 0);
+  if (P <= 0 || totalArea <= 0) {
+    for (const k of keys) population.set(k, 0);
+    continue;
+  }
+  // Largest remainder: floor each share, then hand out the leftover 1s to the
+  // regions with the largest fractional remainders (ties broken by key asc).
+  const shares = keys.map((k) => {
+    const a = regionArea.get(k) || 0;
+    const ideal = (P * a) / totalArea;
+    return { k, floor: Math.floor(ideal), rem: ideal - Math.floor(ideal) };
+  });
+  const distributed = shares.reduce((s, x) => s + x.floor, 0);
+  let deficit = P - distributed; // 0 <= deficit < keys.length
+  const order = shares
+    .map((x, i) => ({ i, rem: x.rem, k: x.k }))
+    .sort((a, b) => (b.rem - a.rem) || (a.k < b.k ? -1 : a.k > b.k ? 1 : 0));
+  for (let i = 0; i < order.length && deficit > 0; i++) {
+    shares[order[i].i].floor += 1;
+    deficit -= 1;
+  }
+  for (const x of shares) population.set(x.k, x.floor);
+}
+
+// --- assemble the manifest (sorted keys) -------------------------------------
+const expectedKeys = Object.values(idToKey);
+const manifest = {};
+for (const k of [...expectedKeys].sort()) {
+  const a = regionArea.get(k);
+  const p = population.get(k);
+  if (a === undefined || p === undefined) {
+    throw new Error(`region key ${JSON.stringify(k)} has no computed area/population`);
+  }
+  manifest[k] = { area: round2(a), population: p };
+}
+
+// --- hard assertions (the test re-checks these against the committed file) ----
+if (Object.keys(manifest).length !== expectedKeys.length) {
+  throw new Error(
+    `expected ${expectedKeys.length} region-geo entries (one per region key), got ${Object.keys(manifest).length}`,
+  );
+}
+let totalPop = 0;
+let zeros = 0;
+for (const [k, v] of Object.entries(manifest)) {
+  if (!Number.isFinite(v.area) || v.area < 0) throw new Error(`bad area for ${k}: ${JSON.stringify(v)}`);
+  if (!Number.isInteger(v.population) || v.population < 0) throw new Error(`bad population for ${k}: ${JSON.stringify(v)}`);
+  if (v.area === 0) zeros += 1;
+  totalPop += v.population;
+}
+
+// --- write idempotently (sorted keys, 2-space indent, trailing newline) ------
+writeFileSync(path.join(root, 'public', 'region-geo.json'), JSON.stringify(manifest, null, 2) + '\n');
+
+// --- summary ------------------------------------------------------------------
+console.log(
+  `[build-region-geo] wrote public/region-geo.json — ${Object.keys(manifest).length} region keys` +
+    `${zeros ? ` (${zeros} zero-area regions)` : ''}, total population ${totalPop.toLocaleString('en-US')}`,
+);

scripts/build-region-keys.mjs

@@ -21,7 +21,7 @@
  *     SQLite and shown to the LLM. Within any name-slug group (e.g. the six
  *     regions all named "Western") the 4-char codes are made distinct by
  *     re-deriving with a deterministic salt on collision, which guarantees the
- *     full key is unique across all 1,796 regions.
+ *     full key is unique across all 1,800 regions.
  *
  * Output: `public/region-keys.json` — a `{ [stableFeatureId]: regionKey }`
  * object, e.g. `{ "FR-57": "brittany-xk2a" }`, in file (stable) order. The map
@@ -107,8 +107,8 @@ const geoFile = path.join(root, 'public', 'regions.geo.json');
 const geo = JSON.parse(readFileSync(geoFile, 'utf8'));
 const features = Array.isArray(geo?.features) ? geo.features : [];
 
-if (features.length !== 1796) {
-  throw new Error(`expected 1,796 regions, got ${features.length} — regions.geo.json changed; re-verify the region-key contract`);
+if (features.length !== 1800) {
+  throw new Error(`expected 1,800 regions, got ${features.length} — regions.geo.json changed; re-verify the region-key contract`);
 }
 
 // Group features by their (computed) name-slug, preserving file order, so the
@@ -154,5 +154,5 @@ writeFileSync(path.join(root, 'public', 'region-keys.json'), out);
 const western = Object.entries(manifest)
   .filter(([, k]) => k.startsWith('western-'))
   .sort((a, b) => a[0] < b[0] ? -1 : 1);
-console.log(`[build-region-keys] wrote public/region-keys.json — ${keys.length} unique region keys (1,796 expected)`);
+console.log(`[build-region-keys] wrote public/region-keys.json — ${keys.length} unique region keys (1,800 expected)`);
 console.log(`  western group: ${western.map(([id, k]) => `${id}=${k}`).join(', ')}`);

scripts/extract-admin0-pop.mjs

@@ -0,0 +1,78 @@
+/**
+ * scripts/extract-admin0-pop.mjs — one-time extraction of the population
+ * SOURCE for the region-geo manifest: `public/ne-admin0-pop.json`.
+ *
+ * Output = `{ "<ADM0_A3>": <POP_EST>, ... }` — the estimated population
+ * (POP_EST) of every Natural Earth 1:10m **admin-0 country** code, keeping
+ * the **maximum** POP_EST seen for each code (Natural Earth ships a few
+ * duplicated / broken-out features per code, e.g. the `TLC` stubs, whose
+ * POP_EST is 0; the real country always wins by having the larger value).
+ * Only codes with a finite, positive POP_EST are recorded (a 0/null POP_EST
+ * has nothing to distribute). Keys are sorted; the file is written with
+ * 2-space indent + trailing newline (deterministic, committed).
+ *
+ * Why a separate committed file: `public/region-geo.json` (built by
+ * `build-region-geo.mjs`) needs a per-country population, but the raw
+ * Natural Earth GeoJSON (13 MB) is a *source* file we deliberately do NOT
+ * commit (see the AGENTS.md data-pipeline note). This script distils it
+ * into a tiny (a few KB) derived table that IS committed, so the region-geo
+ * builder stays fully reproducible in CI without the source present.
+ * Re-run only when the underlying Natural Earth data changes.
+ *
+ * The 1:10m admin-1 file (the one the region generator uses) carries NO
+ * population; the 1:10m admin-0 file does (uppercase `POP_EST` / `ADM0_A3`).
+ *
+ * Usage:
+ *   NE_ADMIN0=/path/to/ne_10m_admin_0_countries.geojson node scripts/extract-admin0-pop.mjs
+ * (default source: /tmp/ne10m_admin0.geojson)
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+
+const src = process.env.NE_ADMIN0 || '/tmp/ne10m_admin0.geojson';
+let raw;
+try {
+  raw = readFileSync(src, 'utf8');
+} catch (err) {
+  console.error(
+    `[extract-admin0-pop] could not read the Natural Earth admin-0 source at ${src}. ` +
+      `Download it (ne_10m_admin_0_countries.geojson) and re-run with NE_ADMIN0 pointing at it.`,
+  );
+  throw err;
+}
+
+const geo = JSON.parse(raw);
+
+/** ADM0_A3 -> max finite, positive POP_EST. */
+const byCode = new Map();
+for (const f of geo.features ?? []) {
+  const p = f.properties ?? {};
+  const code = typeof p.ADM0_A3 === 'string' ? p.ADM0_A3 : '';
+  const pop = typeof p.POP_EST === 'number' ? p.POP_EST : NaN;
+  if (!code || !Number.isFinite(pop) || pop <= 0) continue;
+  const prev = byCode.get(code);
+  if (prev === undefined || pop > prev) byCode.set(code, Math.round(pop));
+}
+
+if (byCode.size === 0) {
+  throw new Error('[extract-admin0-pop] no finite positive POP_EST found in the source — wrong file?');
+}
+
+// Deterministic: sorted keys, 2-space indent, trailing newline.
+const keys = [...byCode.keys()].sort();
+const manifest = {};
+for (const k of keys) manifest[k] = byCode.get(k);
+
+const out = path.join(root, 'public', 'ne-admin0-pop.json');
+writeFileSync(out, JSON.stringify(manifest, null, 2) + '\n');
+
+let sum = 0;
+for (const v of byCode.values()) sum += v;
+console.log(
+  `[extract-admin0-pop] wrote public/ne-admin0-pop.json — ${byCode.size} country codes, ` +
+    `total population ${sum.toLocaleString('en-US')} (Natural Earth 1:10m admin-0, max POP_EST per code)`,
+);

scripts/region-adjacency.test.ts

@@ -34,7 +34,7 @@ describe('region-adjacency.json', () => {
     const adjacencyKeys = new Set(Object.keys(adjacency));
     expect(adjacencyKeys).toEqual(manifestKeys);
     expect(Object.keys(adjacency)).toHaveLength(keys.size);
-    expect(adjacencyKeys.size).toBe(1796);
+    expect(adjacencyKeys.size).toBe(1800);
   });
 
   it('every neighbour is itself a valid region key (referential integrity)', () => {
@@ -84,4 +84,32 @@ describe('region-adjacency.json', () => {
     expect(adjacency['moselle-rygy']?.includes('baden-wurttemberg-oyje')).toBe(true);
     expect(adjacency['baden-wurttemberg-oyje']?.includes('moselle-rygy')).toBe(true);
   });
+
+  it("the #31 + #41 Arctic splits: New Earth isolated; Severnaya Zemlya, Pechora and Yamal adjacency", () => {
+    // v0.25 (#31) split RU-ARK into the mainland (arkhangel-sk-lhbk), the
+    // Franz Josef Land islets (new-earth-eikt) and the Severnaya Zemlya
+    // islets (severnaya-zemlya-awqp). New Earth sits ~100+ km from any land
+    // → a genuinely isolated island (empty list).
+    // v0.26 (#41) repartitioned the mainland: the 5 lat < 68 parts stay
+    // arkhangel-sk-lhbk, and the 28 lat ≥ 68 band parts became pechora-qwhs
+    // (the SW cell) and yamal-gosw (the NE cell). The Severnaya Zemlya
+    // islets' digitized rings touch the NE band part (now yamal-gosw), not
+    // the trimmed core, so SZ now borders Yamal (its former mainland contact
+    // moved to Yamal). The trimmed core keeps its real mainland neighbours
+    // but loses the SZ contact. Pechora (SW) borders the existing Nenets
+    // region to the south and Yamal to the north.
+    expect(adjacency['new-earth-eikt']).toEqual([]);
+    expect(adjacency['severnaya-zemlya-awqp']).toEqual(['yamal-gosw']);
+    expect(adjacency['pechora-qwhs']).toEqual(['nenets-qyga', 'yamal-gosw']);
+    expect(adjacency['yamal-gosw']).toEqual(['pechora-qwhs', 'severnaya-zemlya-awqp']);
+    // the trimmed core keeps its real neighbours (the band's SZ contact moved to Yamal)
+    expect(adjacency['arkhangel-sk-lhbk']).toEqual([
+      'karelia-ohem',
+      'kirov-gfvm',
+      'komi-eoeh',
+      'murmansk-etas',
+      'nenets-qyga',
+      'vologda-ynvr',
+    ]);
+  });
 });

scripts/region-centroids.test.ts

@@ -0,0 +1,158 @@
+/**
+ * scripts/region-centroids.test.ts — validation for the committed
+ * `public/region-centroids.json` (built by `scripts/build-region-centroids.mjs`).
+ *
+ * The manifest maps each region key to the anchor point a map marker (v0.27,
+ * #44) is placed at: the centroid of the region's largest-area part, plus a
+ * `spread` (≈ 0.1 × that part's smallest bbox dimension, in degrees) that the
+ * engine uses to scatter multiple markers of one region around the centroid.
+ * It is a load-bearing data artifact for the marker placement path — this test
+ * pins its contract.
+ *
+ * Deliberately dependency-free: it reads the JSON with plain `fs`/`JSON.parse`
+ * and computes bbox checks by iterating coordinates directly (no `@turf`/
+ * geojson types, which would pull `@types/geojson` into the tsc program and
+ * break `WorldMap.tsx` — see the v0.17 note). Mirrors the style of
+ * `scripts/region-adjacency.test.ts`; the determinism test re-runs the (turf
+ * `.mjs`) builder and compares bytes, matching that the builder is idempotent.
+ */
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+
+function readJson(rel: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(path.join(root, rel), 'utf8'));
+}
+
+interface CentroidEntry {
+  lat: number;
+  lon: number;
+  spread: number;
+}
+
+/** All [lon, lat] coordinate pairs of a Polygon / MultiPolygon geometry. */
+function allCoords(geometry: { type?: string; coordinates?: unknown }): Array<[number, number]> {
+  const c = geometry?.coordinates as
+    | Array<Array<[number, number]>>
+    | Array<Array<Array<[number, number]>>>
+    | undefined;
+  if (!c) return [];
+  if (geometry?.type === 'Polygon') {
+    const rings = c as Array<Array<[number, number]>>;
+    const out: Array<[number, number]> = [];
+    for (const ring of rings) for (const p of ring) out.push(p);
+    return out;
+  }
+  if (geometry?.type === 'MultiPolygon') {
+    const polys = c as Array<Array<Array<[number, number]>>>;
+    const out: Array<[number, number]> = [];
+    for (const poly of polys) for (const ring of poly) for (const p of ring) out.push(p);
+    return out;
+  }
+  return [];
+}
+
+/** The bounding box [minLon, minLat, maxLon, maxLat] of a geometry. */
+function bboxOf(geometry: { type?: string; coordinates?: unknown }): [number, number, number, number] {
+  let minLon = Infinity;
+  let minLat = Infinity;
+  let maxLon = -Infinity;
+  let maxLat = -Infinity;
+  for (const [x, y] of allCoords(geometry)) {
+    if (x < minLon) minLon = x;
+    if (y < minLat) minLat = y;
+    if (x > maxLon) maxLon = x;
+    if (y > maxLat) maxLat = y;
+  }
+  return [minLon, minLat, maxLon, maxLat];
+}
+
+describe('region-centroids.json', () => {
+  const centroids = readJson('public/region-centroids.json') as Record<string, CentroidEntry>;
+  const manifest = readJson('public/region-keys.json') as Record<string, string>;
+  const geo = readJson('public/regions.geo.json') as {
+    features?: Array<{ id?: string | number; geometry?: { type?: string; coordinates?: unknown } }>;
+  };
+  const keys = Object.values(manifest);
+
+  // featureId -> feature, then regionKey -> feature (via the key manifest).
+  const featureByKey = new Map<string, { geometry?: { type?: string; coordinates?: unknown } }>();
+  for (const f of geo.features ?? []) {
+    const key = manifest[String(f.id)];
+    if (key) featureByKey.set(key, f);
+  }
+
+  it('has exactly one entry per region key (same key set as region-keys.json)', () => {
+    expect(new Set(Object.keys(centroids))).toEqual(new Set(keys));
+    expect(Object.keys(centroids)).toHaveLength(1800);
+  });
+
+  it('every entry is a finite { lat, lon, spread } with a non-negative spread, in world bounds', () => {
+    for (const [k, v] of Object.entries(centroids)) {
+      expect(Number.isFinite(v.lat), `non-finite lat for ${k}`).toBe(true);
+      expect(Number.isFinite(v.lon), `non-finite lon for ${k}`).toBe(true);
+      expect(Number.isFinite(v.spread), `non-finite spread for ${k}`).toBe(true);
+      expect(v.spread >= 0, `negative spread for ${k}`).toBe(true);
+      expect(v.lat >= -90 && v.lat <= 90, `lat out of range for ${k}: ${v.lat}`).toBe(true);
+      expect(v.lon >= -180 && v.lon <= 180, `lon out of range for ${k}: ${v.lon}`).toBe(true);
+    }
+  });
+
+  it('each centroid lies inside its region feature bounding box', () => {
+    // The recorded point is the centroid of the LARGEST part, which is a subset
+    // of the whole feature, so it must fall inside the feature's overall bbox.
+    let checked = 0;
+    for (const [key, c] of Object.entries(centroids)) {
+      const feat = featureByKey.get(key);
+      if (!feat?.geometry) continue;
+      const [minLon, minLat, maxLon, maxLat] = bboxOf(feat.geometry);
+      const eps = 1e-4; // allow for the 6-dp rounding in the builder
+      expect(
+        c.lat >= minLat - eps && c.lat <= maxLat + eps,
+        `lat ${c.lat} outside bbox [${minLat}, ${maxLat}] for ${key}`,
+      ).toBe(true);
+      expect(
+        c.lon >= minLon - eps && c.lon <= maxLon + eps,
+        `lon ${c.lon} outside bbox [${minLon}, ${maxLon}] for ${key}`,
+      ).toBe(true);
+      checked++;
+    }
+    expect(checked).toBe(1800);
+  });
+
+  it('spot-checks a couple of well-known anchors land in the right place', () => {
+    // Region keys are sub-national (states/provinces), so we spot-check a few
+    // whose geography is unambiguous. A gross error in the centroid method
+    // (e.g. averaging across all parts of a large multi-part region, or a
+    // lon/lat swap) would land one of these far off.
+    const near = (k: string, lat: number, lon: number, tol: number) => {
+      const c = centroids[k];
+      expect(c, `missing centroid for ${k}`).toBeDefined();
+      expect(Math.abs(c!.lat - lat)).toBeLessThan(tol);
+      expect(Math.abs(c!.lon - lon)).toBeLessThan(tol);
+    };
+    near('ain-lqtt', 46.16, 4.8, 0.5); // FR-01 — eastern France
+    near('california-kikh', 36.87, -120.67, 0.7); // US-CA — central California
+    near('alberta-zopq', 52.09, -116.94, 1.5); // CA-AB — Alberta (large province)
+    near('acre-ekzw', -9.49, -71.11, 0.5); // BR-AC — western Brazil
+  });
+
+  it('is deterministic: re-running the builder rewrites a byte-identical file', () => {
+    const file = path.join(root, 'public', 'region-centroids.json');
+    const before = readFileSync(file, 'utf8');
+    // The builder is cwd-independent (it resolves the repo root from its own
+    // location) and idempotent: same input files + pure turf + fixed rounding
+    // + stable insertion order → identical bytes.
+    execFileSync(process.execPath, [path.join(root, 'scripts', 'build-region-centroids.mjs')], {
+      cwd: root,
+      stdio: 'pipe',
+    });
+    const after = readFileSync(file, 'utf8');
+    expect(after).toBe(before);
+  });
+});

scripts/region-geo.test.ts

@@ -0,0 +1,139 @@
+/**
+ * scripts/region-geo.test.ts — validation for the committed
+ * `public/region-geo.json` (built by `scripts/build-region-geo.mjs`).
+ *
+ * The manifest maps each region key to its { area (km²), population } — the
+ * weighting source for the per-region stats model (v0.28, #46): a nation's
+ * four 0–100 stats are derived as the area×population-weighted median of the
+ * stats of the regions it owns. It is a load-bearing data artifact — this
+ * test pins its contract.
+ *
+ * The `area` is the turf area of the region's final geometry (km², 2 dp); the
+ * `population` is the country's Natural-Earth admin-0 `POP_EST` (from the
+ * committed `public/ne-admin0-pop.json`) distributed across its sub-regions
+ * proportional to area via largest-remainder, so every country's sub-regions
+ * sum EXACTLY to the country's total (and the global total is the sum over the
+ * 177 repo countries). This is a dependency-free test: it reads the JSON with
+ * plain `fs`/`JSON.parse` (no `@turf`/geojson types, which would pull
+ * `@types/geojson` into the tsc program and break `WorldMap.tsx` — see the
+ * v0.17 note). The determinism test re-runs the (turf `.mjs`) builder and
+ * compares bytes, matching that the builder is idempotent.
+ */
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+
+function readJson(rel: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(path.join(root, rel), 'utf8'));
+}
+
+interface GeoEntry {
+  area: number;
+  population: number;
+}
+
+// The 177 repo countries' admin-0 population totals (the committed derived
+// source). Only the countries actually present in the region dataset appear.
+const admin0 = readJson('public/ne-admin0-pop.json') as Record<string, number>;
+// feature id -> region key
+const manifest = readJson('public/region-keys.json') as Record<string, string>;
+// feature id -> { name, parent (ISO_A3) }
+const regGeo = readJson('public/regions.geo.json') as {
+  features?: Array<{ id?: string | number; properties?: { name?: string; parent?: string } }>;
+};
+
+// region key -> parent ISO_A3 (via the key manifest + the geo feature parent).
+const keyToParent: Record<string, string> = {};
+for (const f of regGeo.features ?? []) {
+  const key = manifest[String(f.id)];
+  const parent = f.properties?.parent;
+  if (key && parent) keyToParent[key] = parent;
+}
+
+const geo = readJson('public/region-geo.json') as Record<string, GeoEntry>;
+const keys = Object.values(manifest);
+
+describe('region-geo.json', () => {
+  it('has exactly one entry per region key (same key set as region-keys.json)', () => {
+    expect(new Set(Object.keys(geo))).toEqual(new Set(keys));
+    expect(Object.keys(geo)).toHaveLength(1800);
+  });
+
+  it('is keyed in sorted (deterministic) order', () => {
+    const ks = Object.keys(geo);
+    expect(ks).toEqual([...ks].sort());
+  });
+
+  it('every entry is a finite { area ≥ 0 with ≤ 2 dp, integer population ≥ 0 }', () => {
+    for (const [k, v] of Object.entries(geo)) {
+      expect(Number.isFinite(v.area), `non-finite area for ${k}`).toBe(true);
+      expect(Number.isFinite(v.population), `non-finite population for ${k}`).toBe(true);
+      expect(v.area >= 0, `negative area for ${k}: ${v.area}`).toBe(true);
+      // area is recorded to at most 2 decimal places (km²)
+      expect(Math.round(v.area * 100) / 100 === v.area, `area over 2dp for ${k}: ${v.area}`).toBe(true);
+      expect(Number.isInteger(v.population), `non-integer population for ${k}: ${v.population}`).toBe(true);
+      expect(v.population >= 0, `negative population for ${k}: ${v.population}`).toBe(true);
+    }
+  });
+
+  it('the global population total equals the sum of the 177 repo countries\' admin-0 totals', () => {
+    // The distribution preserved each country's total exactly, so the grand
+    // total over all sub-regions is the sum over the repo countries only.
+    const total = Object.values(geo).reduce((s, v) => s + v.population, 0);
+    expect(total).toBe(7654092021);
+  });
+
+  it('preserves each country\'s population total across its sub-regions (largest-remainder)', () => {
+    // For every parent country present in the region dataset, the sum of its
+    // sub-regions' populations must equal that country's admin-0 POP_EST
+    // EXACTLY — this is the invariant the largest-remainder distribution
+    // guarantees (no population is created or lost by the split).
+    const byParent: Record<string, number> = {};
+    for (const [k, v] of Object.entries(geo)) {
+      const p = keyToParent[k];
+      if (!p) throw new Error(`no parent for region key ${k}`);
+      byParent[p] = (byParent[p] ?? 0) + v.population;
+    }
+    expect(Object.keys(byParent).length).toBe(177); // the 177 repo countries
+    for (const [p, sum] of Object.entries(byParent)) {
+      expect(admin0[p], `missing admin-0 population for ${p}`).toBeDefined();
+      expect(sum, `population drift for ${p}: sub-regions ${sum} vs admin-0 ${admin0[p]}`).toBe(admin0[p]);
+    }
+  });
+
+  it('spot-checks well-known regions for exact area + population', () => {
+    const is = (k: string, area: number, population: number) => {
+      const v = geo[k];
+      expect(v, `missing geo for ${k}`).toBeDefined();
+      expect(v!.area, `area for ${k}`).toBe(area);
+      expect(v!.population, `population for ${k}`).toBe(population);
+    };
+    is('california-kikh', 413329.21, 14184195); // US-CA
+    is('arkhangel-sk-lhbk', 305257.7, 2579108); // RU-ARK mainland core
+    is('pechora-qwhs', 37399.76, 315989); // RU-PEO (Arctic-coast band, #41)
+    is('yamal-gosw', 50598.25, 427502); // RU-YAM (Arctic-coast band, #41)
+    is('new-earth-eikt', 15721.27, 132828); // RU-ARK-NE (island group, #31)
+    is('severnaya-zemlya-awqp', 1209.93, 10223); // RU-ARK-SZ (island group, #31)
+    is('ain-lqtt', 22557.77, 2304126); // FR-01 (Ain)
+  });
+
+  it('is deterministic: re-running the builder rewrites a byte-identical file', () => {
+    const file = path.join(root, 'public', 'region-geo.json');
+    const before = readFileSync(file, 'utf8');
+    // The builder is cwd-independent (it resolves the repo root from its own
+    // location) and idempotent: same input files (regions.geo.json +
+    // region-keys.json + ne-admin0-pop.json) + pure turf + fixed 2-dp rounding
+    // + stable (sorted) key order → identical bytes.
+    execFileSync(process.execPath, [path.join(root, 'scripts', 'build-region-geo.mjs')], {
+      cwd: root,
+      stdio: 'pipe',
+    });
+    const after = readFileSync(file, 'utf8');
+    expect(after).toBe(before);
+  });
+});

scripts/region-keys.test.ts

@@ -33,13 +33,13 @@ describe('region-keys.json', () => {
   const keys = Object.values(manifest);
   const featureIds = (geo.features ?? []).map((f) => String(f.id));
 
-  it('has exactly 1,796 entries (one per region)', () => {
-    expect(Object.keys(manifest)).toHaveLength(1796);
+  it('has exactly 1,800 entries (one per region)', () => {
+    expect(Object.keys(manifest)).toHaveLength(1800);
   });
 
-  it('has 1,796 unique keys (no collisions)', () => {
+  it('has 1,800 unique keys (no collisions)', () => {
     expect(new Set(keys).size).toBe(keys.length);
-    expect(new Set(keys).size).toBe(1796);
+    expect(new Set(keys).size).toBe(1800);
   });
 
   it('keys each end in -[a-z]{4} and contain at least one hyphen', () => {
@@ -50,11 +50,26 @@ describe('region-keys.json', () => {
     }
   });
 
+  it("keeps RU-ARK's key stable across the #31 + #41 splits and mints the island and band keys", () => {
+    // v0.25 (#31) split RU-ARK into main + RU-ARK-NE + RU-ARK-SZ, and v0.26
+    // (#41) repartitioned the mainland into the core (RU-ARK) + RU-PEO +
+    // RU-YAM. The MAIN feature keeps its id (and therefore its key — FNV-1a
+    // of the id), which is what keeps existing Nation.territory / SQLite
+    // ownership valid; the new features get fresh keys derived the same way
+    // from their ids (no within-country name-collision salt needed — the
+    // slugs are unique).
+    expect(manifest['RU-ARK']).toBe('arkhangel-sk-lhbk'); // unchanged since v0.19
+    expect(manifest['RU-ARK-NE']).toBe('new-earth-eikt');
+    expect(manifest['RU-ARK-SZ']).toBe('severnaya-zemlya-awqp');
+    expect(manifest['RU-PEO']).toBe('pechora-qwhs');
+    expect(manifest['RU-YAM']).toBe('yamal-gosw');
+  });
+
   it('is a stable join: its keys are exactly the regions.geo.json feature ids', () => {
     // The manifest is looked up by feature id, so its key set must line up
     // 1:1 with the geo file (catches drift if the geo is regenerated without
     // rebuilding the keys).
-    expect(featureIds).toHaveLength(1796);
+    expect(featureIds).toHaveLength(1800);
     const manifestIds = Object.keys(manifest);
     expect(new Set(manifestIds)).toEqual(new Set(featureIds));
   });

scripts/regions.test.ts

@@ -530,16 +530,22 @@ describe('regions.geo.json', () => {
     );
   });
 
-  it('is at the v0.17 fixed point: 1,796 regions, 11,794 parts, 11,795 rings, 164,801 vertices, 1 hole (KZ-KZY)', () => {
+  it('is at the v0.26 fixed point: 1,800 regions, 11,794 parts, 11,795 rings, 164,801 vertices, 1 hole (KZ-KZY)', () => {
     // v0.17 (scripts/fill-gaps.mjs) APPENDED cleaned gap pieces to the v0.16
     // fixed point: it never moves an existing border, merges a part, or
     // removes a ring — it only adds new parts (+6,768: 5,026 → 11,794) and
-    // keeps the single KZ-KZY hole. The region count (1,796), the
-    // per-feature ids/names/parents and their order are unchanged; only the
-    // part/ring/vertex totals and the hole's part structure moved. Pinning
-    // the signature guards against a non-idempotent or destructive re-run.
-    // The fill is byte-deterministic per input and idempotent (a second run
-    // on the filled file changes nothing).
+    // keeps the single KZ-KZY hole. The v0.25 Arkhangel'sk split (#31,
+    // scripts/split-arkhangel.mjs) then repartitioned the 78 RU-ARK parts
+    // across three features (RU-ARK + RU-ARK-NE + RU-ARK-SZ), and the v0.26
+    // band split (#41, scripts/split-arkhangel-band.mjs) repartitioned the
+    // 33-part mainland again into RU-ARK + RU-PEO + RU-YAM. Both are pure
+    // re-groupings: no part/ring/vertex moves, so only the region count
+    // changed (1,796 → 1,798 → 1,800); the part/ring/vertex totals, the
+    // per-feature ids/names/parents, and the feature order (the new features
+    // sit immediately after RU-ARK-SZ) are as pinned below. Pinning the
+    // signature guards against a non-idempotent or destructive re-run; both
+    // stages are byte-deterministic per input and idempotent (a second run
+    // changes nothing).
     const polysOf = (g: Geometry) => (g.type === 'Polygon' ? [g.coordinates] : g.coordinates);
     let verts = 0,
       rings = 0,
@@ -556,15 +562,67 @@ describe('regions.geo.json', () => {
         for (const ring of poly) verts += ring.length;
       }
     }
-    expect(regions.features.length, 'region count').toBe(1796); // unchanged by the fill
-    expect(parts, 'parts').toBe(11_794); // v0.16: 5,026 → +6,768 appended gap pieces
+    expect(regions.features.length, 'region count').toBe(1800); // 1,796 + the #31 islands (+2) + the #41 band regions (+2)
+    expect(parts, 'parts').toBe(11_794); // v0.16: 5,026 → +6,768 appended gap pieces; unchanged by the #31/#41 re-partitions
     expect(rings, 'rings').toBe(11_795); // every appended part is a single-ring polygon (+1 hole = KZ-KZY, pre-existing)
     expect(holes, 'holes').toBe(1); // the single KZ-KZY hole, unchanged
     expect(holeIds, 'the one remaining hole is KZ-KZY').toEqual(['KZ-KZY']);
-    expect(verts, 'total vertices (incl. ring closure)').toBe(164_801); // v0.16: 111,175
+    expect(verts, 'total vertices (incl. ring closure)').toBe(164_801); // v0.16: 111,175; unchanged by the #31/#41 re-partitions
     console.log(
-      `\n  v0.17 gap fill: ${regions.features.length} regions, ${parts} parts, ${rings} rings, ` +
-        `${holes} hole (KZ-KZY), ${verts} vertices — v0.16 topology preserved, 6,768 gap pieces appended`,
+      `\n  v0.26 fixed point: ${regions.features.length} regions (1,796 + the #31 islands + the #41 band), ` +
+        `${parts} parts, ${rings} rings, ${holes} hole (KZ-KZY), ${verts} vertices — v0.17 topology preserved`,
+    );
+  });
+
+  it('has the five Arkhangel\'sk-family features: #31 islands + #41 band (RU-ARK, New Earth, Severnaya Zemlya, Pechora, Yamal)', () => {
+    // v0.25 (#31): the ~411,500 km² RU-ARK mega-region (a 78-part MultiPolygon
+    // mixing mainland and far-north islands) was repartitioned by part
+    // centroid into the mainland (RU-ARK, keeps its id/name/key), the Franz
+    // Josef Land islets (RU-ARK-NE "New Earth", centroid lat ≥ 79.5) and the
+    // Severnaya Zemlya islets (RU-ARK-SZ, centroid 76–79.5° N, lon ≥ 55°E).
+    // v0.26 (#41): the 33-part mainland (post-#31) was repartitioned again —
+    // the 5 lat < 68 parts stay RU-ARK (id/name/key unchanged), and the 28
+    // lat ≥ 68 "Arctic-coast band" parts split into RU-PEO "Pechora" (the SW
+    // Voronoi cell, 13 parts) and RU-YAM "Yamal" (the NE Voronoi cell, 15
+    // parts). Pure re-grouping: all five keep parent RUS and all 78 original
+    // parts of the pre-#31 feature are accounted for, verbatim.
+    const byId = new Map(regions.features.map((f) => [f.id, f]));
+    const ark = byId.get('RU-ARK');
+    const ne = byId.get('RU-ARK-NE');
+    const sz = byId.get('RU-ARK-SZ');
+    const peo = byId.get('RU-PEO');
+    const yam = byId.get('RU-YAM');
+    for (const f of [ark, ne, sz, peo, yam]) {
+      expect(f, `${f?.id ?? '?'} exists`).toBeDefined();
+      expect(f!.properties.parent, `${f!.id} parent`).toBe('RUS');
+      expect(f!.geometry.type, `${f!.id} geometry`).toBe('MultiPolygon');
+    }
+    expect(ark!.properties.name, 'RU-ARK keeps its name').toBe("Arkhangel'sk");
+    expect(ne!.properties.name, 'RU-ARK-NE name').toBe('New Earth');
+    expect(sz!.properties.name, 'RU-ARK-SZ name').toBe('Severnaya Zemlya');
+    expect(peo!.properties.name, 'RU-PEO name').toBe('Pechora');
+    expect(yam!.properties.name, 'RU-YAM name').toBe('Yamal');
+    // the 78 parts of the pre-split feature are all accounted for, verbatim
+    const countParts = (f: (typeof regions.features)[number]) =>
+      f.geometry.type === 'MultiPolygon' ? f.geometry.coordinates.length : 1;
+    expect(
+      countParts(ark!) + countParts(ne!) + countParts(sz!) + countParts(peo!) + countParts(yam!),
+      'total parts across the five features',
+    ).toBe(78);
+    // the #41 split: the mainland core keeps its 5 lat < 68 parts; the band's
+    // 28 parts split 13 (Pechora) / 15 (Yamal)
+    expect(countParts(ark!), 'RU-ARK core part count').toBe(5);
+    expect(countParts(peo!), 'RU-PEO part count').toBe(13);
+    expect(countParts(yam!), 'RU-YAM part count').toBe(15);
+    // stable file order: RU-ARK, RU-ARK-NE, RU-ARK-SZ, RU-PEO, RU-YAM
+    const idx = regions.features.findIndex((f) => f.id === 'RU-ARK');
+    expect(regions.features[idx + 1]?.id).toBe('RU-ARK-NE');
+    expect(regions.features[idx + 2]?.id).toBe('RU-ARK-SZ');
+    expect(regions.features[idx + 3]?.id).toBe('RU-PEO');
+    expect(regions.features[idx + 4]?.id).toBe('RU-YAM');
+    console.log(
+      `\n  #31 + #41: RU-ARK ${countParts(ark!)} parts (core), RU-ARK-NE ${countParts(ne!)} (New Earth), ` +
+        `RU-ARK-SZ ${countParts(sz!)} (Severnaya Zemlya), RU-PEO ${countParts(peo!)} (Pechora), RU-YAM ${countParts(yam!)} (Yamal)`,
     );
   });
 });

scripts/split-arkhangel-band.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * scripts/split-arkhangel-band.mjs — split the RU-ARK Arctic-coast band into
+ * two new regions, RU-PEO ("Pechora", the SW group) and RU-YAM ("Yamal", the
+ * NE group) (issue #41, a follow-up to #31).
+ *
+ * The #31 split (`scripts/split-arkhangel.mjs`) left `RU-ARK` as a 33-part
+ * MultiPolygon (~393,256 km²). Measured on that feature (centroid latitude /
+ * planar area), the parts divide cleanly by centroid latitude:
+ *
+ *   lat < 68            4 parts  ~305,000 km²  (Arkhangel'sk proper + 3 slivers)
+ *   66 ≤ lat < 68       1 part   ~47 km²
+ *   lat ≥ 68            28 parts ~88,000 km²   (the "Arctic-coast band")
+ *
+ * The band is really *other* Arctic oblasts (Nenets / Pechora / Yamal / Taimyr
+ * side) mis-lumped into Arkhangel'sk during the v0.14 coarsening. This stage
+ * re-coarsens it: the 28 band parts are split into two new regions by a
+ * Voronoi of the two band parts with the largest planar area (the SW anchor
+ * vs the NE anchor), while the 5 lat < 68 parts stay in `RU-ARK`.
+ *
+ *   RU-ARK   (keeps its id and name)  — the 5 lat < 68 parts (original order)
+ *                                          → still the `arkhangel-sk-lhbk` key
+ *   RU-PEO   "Pechora"                — the band's SW Voronoi cell (13 parts)
+ *   RU-YAM   "Yamal"                  — the band's NE Voronoi cell (15 parts)
+ *
+ * Deterministic, turf-free threshold spec (all data-derived — no magic
+ * coordinates; the same planar model the tests/adjacency build use):
+ *   1. centroid of a part = the mean of its outer-ring vertices (verified to
+ *      give the same band assignment as turf's area-weighted centroid, 0 flips).
+ *   2. band = the parts whose centroid lat ≥ 68 (asserted to be exactly 28).
+ *   3. anchors = the 2 band parts with the largest planar area (≈ 47,223 and
+ *      ≈ 32,907 km², indices 2 and 1 in the 33-part feature); anchorW = the
+ *      anchor with the smaller centroid longitude.
+ *   4. each non-anchor band part → the nearer anchor by km-weighted centroid
+ *      distance, `dist(a,b) = hypot(Δlon·111.32·cos(midLat), Δlat·110.574)`;
+ *      a tie → west (anchorW). Each anchor → its own group. This yields
+ *      PEO = {1,4,5,9,11,12,13,14,16,17,18,20,22} and
+ *      YAM = {2,6,15,19,21,23,24,25,26,27,28,29,30,31,32} (0-based indices).
+ *
+ * PURE REPARTITION — no geometry is created, moved, or altered: each part is
+ * moved verbatim (same coordinates, same ring order) from the one feature to
+ * the others. The union of the three output geometries is byte-identical to
+ * the input feature's parts, so no border moves and no new overlap is
+ * possible (the same guarantee as #31). `RU-ARK` keeps its stable feature id,
+ * so its region key (`arkhangel-sk-lhbk`, FNV-1a of the id) and every existing
+ * `Nation.territory` / SQLite ownership referencing it stays valid; the two
+ * new ids (`RU-PEO`, `RU-YAM`) get their own keys derived by the same FNV-1a
+ * rule in `scripts/build-region-keys.mjs` (`pechora-qwhs`, `yamal-gosw` —
+ * run it after this stage).
+ *
+ * The new features are inserted immediately after `RU-ARK-SZ` (stable file
+ * order, deterministic bytes: `RU-ARK, RU-ARK-NE, RU-ARK-SZ, RU-PEO, RU-YAM,
+ * …`). Each new feature's `properties` copies `RU-ARK`'s (only `name` and
+ * `parent` exist in this dataset) with `name` overridden; `parent` stays RUS.
+ * Each feature's geometry is a MultiPolygon of its assigned parts (in
+ * original order), or a single Polygon if it ended up with one part (it won't
+ * here, but the builder handles it).
+ *
+ * Pipeline position: AFTER `split-arkhangel` and BEFORE `build-region-keys`
+ * (the manifests must be rebuilt after any geo change):
+ *
+ *   generate → coarsen → cleanup → smooth → fill-gaps → split-arkhangel
+ *   → **split-arkhangel-band** → build-region-keys → build-region-adjacency
+ *
+ * Idempotent: when RU-PEO and RU-YAM already exist the file is left untouched
+ * (no write at all), so a full re-run of the pipeline reproduces byte-identical
+ * output.
+ *
+ * Usage:  node scripts/split-arkhangel-band.mjs [inFile [outFile]]
+ *          (or `npm run split:regions:band`)
+ *   inFile  default: public/regions.geo.json
+ *   outFile default: inFile (edit in place)
+ *
+ * Deliberately turf-free: no `@turf/*` import (turf is only ever imported by
+ * the geo-generator `.mjs` stages, never by this re-partition or by any `.ts`).
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+const inFile = process.argv[2] ?? path.join(root, 'public', 'regions.geo.json');
+const outFile = process.argv[3] ?? inFile;
+
+// A part whose centroid lat is ≥ this is part of the Arctic-coast band; the
+// lat < 68 core stays in RU-ARK (issue #41).
+const BAND_MIN_LAT = 68;
+
+// The post-#31 mainland feature is a 33-part MultiPolygon; any other shape
+// means the file is not the state this stage expects → fail loud.
+const EXPECTED_PARTS = 33;
+// The Arctic-coast band is exactly 28 of those parts (lat ≥ 68).
+const EXPECTED_BAND = 28;
+
+// Planar km model (matches the test's area model and the adjacency build):
+// x = lon · 111.32 · cos(midLat), y = lat · 110.574.
+const KM_LON = 111.32;
+const KM_LAT = 110.574;
+const rad = (deg) => (deg * Math.PI) / 180;
+
+/**
+ * Mean of a part's outer-ring vertices — a turf-free centroid. Verified to give
+ * the same band assignment as turf's area-weighted centroid (0 flips).
+ */
+function centroidOf(part) {
+  const ring = part[0];
+  let lon = 0;
+  let lat = 0;
+  for (const [lo, la] of ring) {
+    lon += lo;
+    lat += la;
+  }
+  return [lon / ring.length, lat / ring.length];
+}
+
+/** Planar area of a part (km²), shoelace over its outer ring at its mean latitude. */
+function areaKm2(part) {
+  const ring = part[0];
+  let lat = 0;
+  for (const [, la] of ring) lat += la;
+  const midLat = lat / ring.length;
+  const kx = KM_LON * Math.cos(rad(midLat));
+  let a = 0;
+  for (let i = 0; i < ring.length; i++) {
+    const [lon1, lat1] = ring[i];
+    const [lon2, lat2] = ring[(i + 1) % ring.length];
+    a += lon1 * kx * (lat2 * KM_LAT) - lon2 * kx * (lat1 * KM_LAT);
+  }
+  return Math.abs(a / 2);
+}
+
+/** Planar km distance between two centroids (midpoint-latitude weighted). */
+function kmDist(a, b) {
+  const dLon = b[0] - a[0];
+  const dLat = b[1] - a[1];
+  const midLat = (a[1] + b[1]) / 2;
+  return Math.hypot(dLon * KM_LON * Math.cos(rad(midLat)), dLat * KM_LAT);
+}
+
+// --- load --------------------------------------------------------------------
+const geo = JSON.parse(readFileSync(inFile, 'utf8'));
+if (geo?.type !== 'FeatureCollection' || !Array.isArray(geo.features)) {
+  throw new Error(`${inFile} is not a FeatureCollection`);
+}
+const features = geo.features;
+
+// --- idempotency: already split? ----------------------------------------------
+const ids = new Set(features.map((f) => String(f.id ?? '')));
+if (ids.has('RU-PEO') && ids.has('RU-YAM')) {
+  console.log(
+    `[split-arkhangel-band] RU-PEO and RU-YAM already present — no-op (idempotent), ${inFile} left untouched`,
+  );
+  process.exit(0);
+}
+
+// --- load + validate RU-ARK ---------------------------------------------------
+const idx = features.findIndex((f) => f.id === 'RU-ARK');
+if (idx < 0) throw new Error('RU-ARK not found in ' + inFile);
+const ark = features[idx];
+if (ark.geometry?.type !== 'MultiPolygon') {
+  throw new Error(
+    `RU-ARK geometry is ${ark.geometry?.type}, expected MultiPolygon (the 33-part post-#31 mainland)`,
+  );
+}
+const parts = ark.geometry.coordinates;
+if (parts.length !== EXPECTED_PARTS) {
+  throw new Error(`RU-ARK has ${parts.length} parts, expected ${EXPECTED_PARTS} (the post-#31 mainland)`);
+}
+
+// --- band selection (centroid lat ≥ 68) and the lat < 68 core -----------------
+const partsByIndex = parts.map((p, i) => ({ i, c: centroidOf(p) }));
+const band = partsByIndex.filter((o) => o.c[1] >= BAND_MIN_LAT);
+if (band.length !== EXPECTED_BAND) {
+  throw new Error(`expected exactly ${EXPECTED_BAND} Arctic-coast band parts (lat ≥ ${BAND_MIN_LAT}), found ${band.length}`);
+}
+const core = partsByIndex.filter((o) => o.c[1] < BAND_MIN_LAT);
+
+// --- anchors: the two band parts with the largest planar area -----------------
+// (≈ 47,223 and ≈ 32,907 km², indices 2 and 1 in the 33-part feature).
+const byArea = [...band].sort((a, b) => areaKm2(parts[b.i]) - areaKm2(parts[a.i]));
+const big = byArea[0];
+const small = byArea[1];
+const anchorW = big.c[0] <= small.c[0] ? big : small; // the west (SW) anchor
+const anchorE = big.c[0] <= small.c[0] ? small : big; // the east (NE) anchor
+
+// --- assignment (Voronoi by km-weighted centroid distance; tie → west) --------
+const peo = new Set([anchorW.i]);
+const yam = new Set([anchorE.i]);
+for (const o of band) {
+  if (o.i === anchorW.i || o.i === anchorE.i) continue;
+  const dW = kmDist(o.c, anchorW.c);
+  const dE = kmDist(o.c, anchorE.c);
+  (dW <= dE ? peo : yam).add(o.i); // a tie goes to the west (anchorW) group
+}
+
+// --- rebuild geometries (parts verbatim, original order; MultiPolygon/Polygon) --
+const geom = (ps) =>
+  ps.length > 1 ? { type: 'MultiPolygon', coordinates: ps } : { type: 'Polygon', coordinates: ps[0] };
+
+const coreParts = [...core].sort((a, b) => a.i - b.i).map((o) => parts[o.i]);
+const peoParts = [...peo].sort((a, b) => a - b).map((i) => parts[i]);
+const yamParts = [...yam].sort((a, b) => a - b).map((i) => parts[i]);
+
+ark.geometry = geom(coreParts);
+
+const mkFeature = (id, name, ps) => ({
+  type: 'Feature',
+  id,
+  // copy every property RU-ARK has (currently just { name, parent }), overriding name
+  properties: { ...ark.properties, name },
+  geometry: geom(ps),
+});
+const peoF = mkFeature('RU-PEO', 'Pechora', peoParts);
+const yamF = mkFeature('RU-YAM', 'Yamal', yamParts);
+
+// --- report -------------------------------------------------------------------
+const km2 = (ps) => ps.reduce((s, p) => s + areaKm2(p), 0);
+console.log(`[split-arkhangel-band] input: ${inFile}`);
+console.log(
+  `  RU-ARK  (core, lat < 68)   ${coreParts.length} parts (of ${parts.length}), ≈ ${Math.round(km2(coreParts)).toLocaleString('en-US')} km²`,
+);
+console.log(
+  `  RU-PEO  (Pechora, SW)      ${peoParts.length} parts, ≈ ${Math.round(km2(peoParts)).toLocaleString('en-US')} km²  [${[...peo].sort((a, b) => a - b).join(',')}]`,
+);
+console.log(
+  `  RU-YAM  (Yamal, NE)        ${yamParts.length} parts, ≈ ${Math.round(km2(yamParts)).toLocaleString('en-US')} km²  [${[...yam].sort((a, b) => a - b).join(',')}]`,
+);
+if (peoParts.length === 0 || yamParts.length === 0) {
+  throw new Error(
+    `threshold mis-split: Pechora=${peoParts.length} parts, Yamal=${yamParts.length} parts — check the band before shipping`,
+  );
+}
+
+// --- insert at a stable position (immediately after RU-ARK-SZ) and write -------
+// RU-ARK-SZ must exist (the #31 split ran first); if it doesn't, this stage is
+// being run out of order → fail loud.
+const szIdx = features.findIndex((f) => f.id === 'RU-ARK-SZ');
+if (szIdx < 0) {
+  throw new Error('RU-ARK-SZ not found — the #31 split (scripts/split-arkhangel.mjs) must run before this stage');
+}
+features.splice(szIdx + 1, 0, peoF, yamF);
+writeFileSync(outFile, JSON.stringify(geo));
+console.log(
+  `[split-arkhangel-band] wrote ${outFile} — features ${features.length - 2} → ${features.length}` +
+    ` (order …, RU-ARK, RU-ARK-NE, RU-ARK-SZ, RU-PEO, RU-YAM, …)`,
+);

scripts/split-arkhangel.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * scripts/split-arkhangel.mjs — split the RU-ARK ("Arkhangel'sk") mega-region
+ * into main + two detached island archipelagos (issue #31).
+ *
+ * `RU-ARK` is a 78-part MultiPolygon of ~411,500 km²: the Arkhangel'sk
+ * mainland plus Arctic-coast mainland parts, tiny islets, AND two far-north
+ * island groups that belong nowhere near the mainland — the Franz Josef Land
+ * islets (New Earth, centroid lat ≥ 79.5) and the Severnaya Zemlya islets
+ * (centroid lat 76–79.5, lon ≥ 55). This stage repartitions the existing
+ * polygon parts between three features so each island group is its own
+ * addressable sub-region:
+ *
+ *   RU-ARK     (keeps its id and name)  — every part whose centroid has
+ *                                         lat < 76 (the mainland, Arctic-coast
+ *                                         mainland parts, islets, one south dot)
+ *   RU-ARK-NE  "New Earth"              — every part whose centroid has
+ *                                         lat ≥ 79.5 (the 42 Franz Josef Land
+ *                                         islets, ~15,700 km²)
+ *   RU-ARK-SZ  "Severnaya Zemlya"       — every part whose centroid has
+ *                                         76 ≤ lat < 79.5 AND lon ≥ 55 (the 3
+ *                                         Severnaya Zemlya islets, ~1,200 km²)
+ *
+ * (Parts in the 76–79.5° band with lon < 55 would stay in RU-ARK; none exist
+ * in the current dataset — the split is verified clean before it is written.)
+ *
+ * PURE REPARTITION — no geometry is created, moved, or altered: each part is
+ * moved verbatim (same coordinates, same ring order) from the one feature to
+ * the other. The union of the three output geometries is byte-identical to
+ * the input feature's parts, so no border moves and no new overlap is
+ * possible. RU-ARK keeps its stable feature id, so its region key
+ * (`arkhangel-sk-lhbk`, FNV-1a of the id) and every existing
+ * `Nation.territory` / SQLite ownership referencing it stays valid; the two
+ * new ids (`RU-ARK-NE`, `RU-ARK-SZ`) get their own keys derived by the same
+ * FNV-1a rule in `scripts/build-region-keys.mjs` (run it after this stage).
+ *
+ * The new features are inserted immediately after RU-ARK (stable file order,
+ * deterministic bytes). Each new feature's `properties` copies RU-ARK's
+ * (only `name` and `parent` exist in this dataset) with `name` overridden;
+ * `parent` stays RUS. Each feature's geometry is a MultiPolygon of its
+ * assigned parts, or a single Polygon if it ends up with one part.
+ *
+ * Pipeline position: between `fill-gaps` and `build-region-keys` (the
+ * manifests must be rebuilt after any geo change):
+ *
+ *   generate → coarsen → cleanup → smooth → fill-gaps → **split-arkhangel**
+ *   → build-region-keys → build-region-adjacency
+ *
+ * Idempotent: when RU-ARK-NE and RU-ARK-SZ already exist the file is left
+ * untouched (no write at all), so a full re-run of the pipeline reproduces
+ * byte-identical output.
+ *
+ * Usage:  node scripts/split-arkhangel.mjs [inFile [outFile]]
+ *          (or `npm run split:regions`)
+ *   inFile  default: public/regions.geo.json
+ *   outFile default: inFile (edit in place)
+ *
+ * `@turf/centroid` + `@turf/helpers` are used only to classify each part by
+ * its centroid — the same measurement the split thresholds are defined in.
+ * (Turf is allowed in .mjs scripts only; never imported by any .ts file.)
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import centroid from '@turf/centroid';
+import area from '@turf/area';
+import { polygon } from '@turf/helpers';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+const inFile = process.argv[2] ?? path.join(root, 'public', 'regions.geo.json');
+const outFile = process.argv[3] ?? inFile;
+
+// The split thresholds (degrees), per issue #31.
+const NEW_EARTH_MIN_LAT = 79.5; // centroid lat ≥ this → New Earth (Franz Josef Land)
+const SZ_BAND_MIN_LAT = 76; // centroid lat ≥ this (and < NEW_EARTH_MIN_LAT)…
+const SZ_MIN_LON = 55; // …and centroid lon ≥ this → Severnaya Zemlya
+// (anything else — including the 76–79.5° band west of 55°E, of which the
+// current dataset has none — stays in the main Arkhangel'sk feature)
+
+/** A GeoJSON polygon part as a turf Feature (for centroid/area only). */
+const partFeature = (part) => polygon(part);
+
+/**
+ * A part's centroid [lon, lat]. Strict by design: a centroid that cannot be
+ * computed is a data error, not something to silently route to the mainland.
+ */
+function centroidOf(part) {
+  try {
+    return centroid(partFeature(part)).geometry.coordinates;
+  } catch (err) {
+    throw new Error(`cannot compute centroid for a RU-ARK part: ${err.message}`);
+  }
+}
+
+/** Classify a centroid [lon, lat] into one of the three output buckets. */
+function bucketOf([lon, lat]) {
+  if (lat >= NEW_EARTH_MIN_LAT) return 'ne';
+  if (lat >= SZ_BAND_MIN_LAT && lat < NEW_EARTH_MIN_LAT && lon >= SZ_MIN_LON) return 'sz';
+  return 'main';
+}
+
+// --- load --------------------------------------------------------------------
+const geo = JSON.parse(readFileSync(inFile, 'utf8'));
+if (geo?.type !== 'FeatureCollection' || !Array.isArray(geo.features)) {
+  throw new Error(`${inFile} is not a FeatureCollection`);
+}
+const features = geo.features;
+
+// --- idempotency: already split? ----------------------------------------------
+const ids = new Set(features.map((f) => String(f.id ?? '')));
+if (ids.has('RU-ARK-NE') && ids.has('RU-ARK-SZ')) {
+  console.log(
+    `[split-arkhangel] RU-ARK-NE and RU-ARK-SZ already present — no-op (idempotent), ${inFile} left untouched`,
+  );
+  process.exit(0);
+}
+
+const idx = features.findIndex((f) => f.id === 'RU-ARK');
+if (idx < 0) {
+  throw new Error('RU-ARK not found in ' + inFile);
+}
+const ark = features[idx];
+if (ark.geometry?.type !== 'MultiPolygon') {
+  throw new Error(
+    `RU-ARK geometry is ${ark.geometry?.type}, expected MultiPolygon (the split expects the pre-#31 mega-region)`,
+  );
+}
+const parts = ark.geometry.coordinates;
+
+// --- partition (stable: original part order is kept inside each bucket) -------
+const buckets = { main: [], ne: [], sz: [] };
+let bandWest = 0; // 76–79.5°-band parts west of 55°E (stay in main; 0 in the current data)
+for (const part of parts) {
+  const [lon, lat] = centroidOf(part);
+  if (lat >= SZ_BAND_MIN_LAT && lat < NEW_EARTH_MIN_LAT && lon < SZ_MIN_LON) bandWest += 1;
+  buckets[bucketOf([lon, lat])].push(part);
+}
+
+// --- rebuild geometries (parts verbatim; MultiPolygon, or Polygon if 1 part) --
+const geom = (ps) =>
+  ps.length > 1
+    ? { type: 'MultiPolygon', coordinates: ps }
+    : { type: 'Polygon', coordinates: ps[0] };
+
+ark.geometry = geom(buckets.main);
+
+const mkFeature = (id, name, ps) => ({
+  type: 'Feature',
+  id,
+  // copy every property RU-ARK has (currently just { name, parent }), overriding name
+  properties: { ...ark.properties, name },
+  geometry: geom(ps),
+});
+const ne = mkFeature('RU-ARK-NE', 'New Earth', buckets.ne);
+const sz = mkFeature('RU-ARK-SZ', 'Severnaya Zemlya', buckets.sz);
+
+// --- report -------------------------------------------------------------------
+const km2 = (ps) => ps.reduce((s, p) => s + area(partFeature(p)) * 1e-6, 0);
+console.log(`[split-arkhangel] input: ${inFile}`);
+console.log(
+  `  RU-ARK    (main)  ${buckets.main.length} parts (of ${parts.length}), ≈ ${Math.round(km2(buckets.main)).toLocaleString('en-US')} km²` +
+    (bandWest ? ` — incl. ${bandWest} part(s) in the 76–79.5° band west of 55°E (kept in main)` : ''),
+);
+console.log(
+  `  RU-ARK-NE (New Earth)         ${buckets.ne.length} parts, ≈ ${Math.round(km2(buckets.ne)).toLocaleString('en-US')} km²`,
+);
+console.log(
+  `  RU-ARK-SZ (Severnaya Zemlya)  ${buckets.sz.length} parts, ≈ ${Math.round(km2(buckets.sz)).toLocaleString('en-US')} km²`,
+);
+if (buckets.ne.length === 0 || buckets.sz.length === 0) {
+  throw new Error(
+    `threshold mis-split: New Earth=${buckets.ne.length} parts, Severnaya Zemlya=${buckets.sz.length} parts — check the centroids before shipping`,
+  );
+}
+
+// --- insert at a stable position (immediately after RU-ARK) and write ---------
+features.splice(idx + 1, 0, ne, sz);
+writeFileSync(outFile, JSON.stringify(geo));
+console.log(`[split-arkhangel] wrote ${outFile} — features ${features.length - 2} → ${features.length}`);

server/db.test.ts

@@ -24,6 +24,18 @@ function makeState(id: string): GameState {
     pending: [],
     version: 1,
     unowned: [],
+    pendingNationOps: [],
+    markers: [],
+    // (v0.28, #46) a v0.28+ save carries per-region stats; the fake 'GBR'
+    // region here holds a copy of the uk's (single-region) stats.
+    regionStats: {
+      GBR: { military: 80, economy: 70, stability: 60, population: 50 },
+    },
+    // (v0.33.0, #56) no wars.
+    wars: [],
+    // (v0.35.0, #58) no active trades or embargoes.
+    trades: [],
+    embargoes: [],
   };
 }
 
@@ -85,6 +97,74 @@ describe('openDb', () => {
     db.close();
   });
 
+  it('(v0.23 #16 P4a) a legacy row saved before the pendingNationOps field existed loads with it defaulted to []', () => {
+    const db = openDb(':memory:');
+    const legacy = makeState('legacy');
+    delete (legacy as { pendingNationOps?: unknown[] }).pendingNationOps; // a pre-v0.23 save (field absent)
+    db.save(legacy);
+    const loaded = db.load('legacy');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.pendingNationOps).toEqual([]);
+    db.close();
+  });
+
+  it('(v0.27 #44) a legacy row saved before the markers field existed loads with it defaulted to []', () => {
+    const db = openDb(':memory:');
+    const legacy = makeState('legacy');
+    delete (legacy as { markers?: unknown[] }).markers; // a pre-v0.27 save (field absent)
+    db.save(legacy);
+    const loaded = db.load('legacy');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.markers).toEqual([]);
+    db.close();
+  });
+
+  it('(v0.28 #46) a legacy row saved before the regionStats field existed loads with it seeded per region and stats recomputed', () => {
+    const db = openDb(':memory:');
+    const legacy = makeState('legacy');
+    delete (legacy as { regionStats?: Record<string, unknown> }).regionStats; // a pre-v0.28 save (field absent)
+    db.save(legacy);
+    const loaded = db.load('legacy');
+    expect(loaded).not.toBeNull();
+    // each owned region is seeded with a copy of its owner's stats…
+    expect(loaded!.regionStats).toEqual({
+      GBR: { military: 80, economy: 70, stability: 60, population: 50 },
+    });
+    // …and a single-region nation's derived stats equal the seeded ones
+    // (the weighted median of identical values is that value).
+    expect(loaded!.nations.uk.stats).toEqual({ military: 80, economy: 70, stability: 60, population: 50 });
+    db.close();
+  });
+
+  it('(v0.28 #46) a v0.28+ row (regionStats present) loads UNCHANGED — no recompute on load', () => {
+    const db = openDb(':memory:');
+    const s = makeState('current');
+    // Diverge one region's stats from the nation level to prove load does not
+    // recompute (a v0.28+ save keeps its stored derived stats exactly).
+    s.regionStats = { GBR: { military: 99, economy: 70, stability: 60, population: 50 } };
+    s.nations = { uk: { ...s.nations.uk, stats: { military: 42, economy: 70, stability: 60, population: 50 } } };
+    db.save(s);
+    const loaded = db.load('current');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.regionStats).toEqual({ GBR: { military: 99, economy: 70, stability: 60, population: 50 } });
+    // the nation's stats are NOT recomputed from the region on load (they stay 42)
+    expect(loaded!.nations.uk.stats.military).toBe(42);
+    db.close();
+  });
+
+  it('(v0.35.0 #58) a legacy row saved before the trades/embargoes fields existed loads with them defaulted to []', () => {
+    const db = openDb(':memory:');
+    const legacy = makeState('legacy');
+    delete (legacy as { trades?: unknown[] }).trades; // a pre-v0.35 save (fields absent)
+    delete (legacy as { embargoes?: unknown[] }).embargoes;
+    db.save(legacy);
+    const loaded = db.load('legacy');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.trades).toEqual([]);
+    expect(loaded!.embargoes).toEqual([]);
+    db.close();
+  });
+
   it('delete removes a game by id and reports absence otherwise', () => {
     const db = openDb(':memory:');
     db.save(makeState('a'));

server/db.ts

@@ -2,6 +2,7 @@
 import { mkdirSync } from 'node:fs';
 import path from 'node:path';
 import Database from 'better-sqlite3';
+import { migrateRegionStats } from '../shared/protocol';
 import type { GameState } from '../shared/types';
 
 export interface Db {
@@ -39,10 +40,30 @@ export function openDb(filePath: string): Db {
       const row = byId.get(id) as { data: string } | undefined;
       if (!row) return null;
       try {
-        const state = JSON.parse(row.data) as GameState;
+        let state = JSON.parse(row.data) as GameState;
         // (v0.22, #16 P3) Rows saved before `GameState.unowned` existed load
         // with it defaulted: a legacy game has no no-man's-land regions.
         if (state.unowned === undefined) state.unowned = [];
+        // (v0.23, #16 P4a) Same for pending nation-op proposals: a legacy game
+        // has none awaiting confirm/reject.
+        if (state.pendingNationOps === undefined) state.pendingNationOps = [];
+        // (v0.27, #44) Same for map markers: a legacy game has none placed.
+        if (state.markers === undefined) state.markers = [];
+        // (v0.33.0, #56) Same for named wars: a legacy game has none declared
+        // (any pre-v0.33 `war` relation stays a bare/implicit relation — see
+        // syncWarRelations, which never force-creates a War entity).
+        if (state.wars === undefined) state.wars = [];
+        // (v0.35.0, #58) Same for the trade & embargo economy layer: a
+        // legacy game has no active trades or embargoes.
+        if (state.trades === undefined) state.trades = [];
+        if (state.embargoes === undefined) state.embargoes = [];
+        // (v0.28, #46) Rows saved before per-region stats existed are migrated
+        // ONCE at load time (and never re-migrated afterwards — the field is
+        // then present): each owned region is seeded with a copy of its owner's
+        // nation-level stats and the nations' stats are recomputed as the
+        // (uniform-weight) area×population-weighted median, so no data is lost
+        // and a single-region nation keeps exactly its old stats.
+        state = migrateRegionStats(state);
         return state;
       } catch {
         return null;

server/index.ts

@@ -8,20 +8,26 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { deepClone } from '../shared/protocol';
+import { deepClone, seedRegionStats } from '../shared/protocol';
 import type {
   AddActionRequest,
   AddDiplomacyRequest,
+  ConfirmNationOpRequest,
   CreateGameRequest,
+  RejectNationOpRequest,
   RemoveQueueItemRequest,
 } from '../shared/protocol';
-import type { GameState } from '../shared/types';
+import type { GameState, Preset } from '../shared/types';
+import type { WorldDraft } from '../shared/scenario';
 import { createLlmClient } from './llm';
 import { makeStubLlmClient } from './stub';
-import { askAdvisor, queueRoundItem, removeRoundItem, runTurn } from './engine';
+import { makeScenarioStubLlmClient } from './stubScenario';
+import { finalizeWorld, generateDraft } from './scenario';
+import { askAdvisor, confirmNationOp, queueRoundItem, rejectNationOp, removeRoundItem, resolveRegionKey, runTurn } from './engine';
 import { buildRegionMap } from './map';
-import { allTerritoryKeys, expandCountriesToKeys, hasAdjacency, loadRegions, neighboursOf, referenceForKeys, validKeys } from './regions';
+import { allTerritoryKeys, centroidOf, expandCountriesToKeys, geoOf, hasAdjacency, hasCentroids, hasGeo, loadRegions, neighboursOf, referenceForKeys, regionName, validCountryCodes, validKeys } from './regions';
 import { createPresetStore } from './presets';
+import { createTemplateStore } from './templates';
 import { openDb, type Db } from './db';
 
 const here = fileURLToPath(new URL('.', import.meta.url));
@@ -50,6 +56,8 @@ const dataDir = process.env.DATA_DIR ?? path.join(root, 'data');
 // the e2e config, so honor it as a fallback to keep all three in agreement.
 const PORT = parseInt(process.env.PORT ?? process.env.HISTORY_API_PORT ?? '4321', 10);
 const presetStore = createPresetStore(presetsDir);
+// (v0.31, #52) Era templates for the "Create scenario" path (presets/templates/).
+const templateStore = createTemplateStore(path.join(root, 'presets', 'templates'));
 // Load the region-key manifest + geo once at boot (v0.19 #16 P1). A missing file
 // just means region expansion/reference degrade to the raw keys (server still boots).
 loadRegions(root);
@@ -57,6 +65,10 @@ const db: Db = openDb(path.join(dataDir, 'history.db'));
 // LLM_STUB=1 → deterministic stub (tests/e2e/dev without a live model).
 const useStub = process.env.LLM_STUB === '1';
 const llm = useStub ? makeStubLlmClient() : createLlmClient();
+// (v0.31, #52) The scenario-generation LLM client: the deterministic scenario
+// stub under LLM_STUB=1 (a distinct transport from the turn stub, which stays
+// untouched), and the live client otherwise.
+const scenarioLlm = useStub ? makeScenarioStubLlmClient() : llm;
 
 const app = express();
 app.use(express.json());
@@ -93,6 +105,34 @@ function broadcast(id: string, event: string, data: unknown): void {
 
 // --- Routes ---
 
+/**
+ * (v0.31, #52) Synthesize the minimal `Preset` the turn engine needs for a
+ * dynamically generated game (`presetId: 'dynamic'` — there is no static preset
+ * file on disk). `runTurn` only consumes `title` / `startDate` /
+ * `worldBackground` / `simulationRules` (never `preset.nations`), so a generic
+ * alternate-history background plus the standard rules is sufficient; `nations`
+ * is carried from the saved world so the type is complete. `startDate` uses the
+ * game's current date (GameState stores no separate start date) — it only feeds
+ * the static "WORLD: <title> — <date>" header of the system prompt.
+ */
+function dynamicPresetFromGame(game: GameState): Preset {
+  return {
+    id: game.presetId,
+    title: game.presetTitle,
+    startDate: game.date,
+    summary: game.presetTitle,
+    worldBackground: `${game.presetTitle} is a dynamically generated alternate-history world. Keep every nation's stats, borders and relations internally consistent as the world evolves.`,
+    simulationRules: [
+      "Advance the shared world for ALL nations, not only the player's.",
+      'Keep every stat value between 0 and 100.',
+      'Only change borders when war or a decisive political shift justifies it.',
+      'Prefer 1-4 events per turn; keep each narrative to 1-3 sentences.',
+      'Use only nation ids and region keys that exist in the provided state.',
+    ],
+    nations: Object.values(game.nations),
+  };
+}
+
 app.get('/api/health', (_req, res) => {
   res.json({ ok: true, stub: useStub, port: PORT });
 });
@@ -128,11 +168,32 @@ app.post('/api/games', (req: Request, res) => {
     // starts with nothing released; this list grows as the LLM releases
     // regions and shrinks as they get re-claimed.
     unowned: [],
+    // (v0.23, #16 P4a) No pending nation-op proposals on a fresh game; the
+    // list grows as the LLM proposes renames (and, later, splits/merges) and
+    // shrinks as the player confirms or rejects them.
+    pendingNationOps: [],
+    // (v0.27, #44) No markers on a fresh game; the LLM places them over time.
+    markers: [],
+    // (v0.28, #46) Per-region stats are seeded below, once territories hold
+    // real region keys — each region starts as a copy of its owner's initial
+    // stats, so the derived aggregate equals the nation's stats on turn 1.
+    regionStats: {},
+    // (v0.33.0, #56) No wars on a fresh game; the LLM declares them over time
+    // (any preset-level `war` relation stays a bare/implicit one, not an
+    // entity — see syncWarRelations).
+    wars: [],
+    // (v0.35.0, #58) No active trades or embargoes on a fresh game; the LLM
+    // declares (and lifts) them over time via TurnResult.economy.
+    trades: [],
+    embargoes: [],
   };
   // v0.19 (#16 P1): expand each nation's ISO_A3 country list to the region keys
   // of all its sub-regions, so ownership (and the choropleth) is at region
   // granularity from the very first turn. Preset JSONs stay country-level.
   for (const n of Object.values(state.nations)) n.territory = expandCountriesToKeys(n.territory);
+  // (v0.28, #46): seed per-region stats AFTER the expansion so each owned
+  // region key gets its owner's initial stats (see seedRegionStats).
+  state.regionStats = seedRegionStats(state.nations);
   db.save(state);
   res.json({ game: state });
 });
@@ -224,6 +285,38 @@ app.post('/api/games/:id/queue/remove', (req, res) => {
   res.json({ game: next });
 });
 
+// (v0.23, #16 P4a; v0.24, #16 P4b) Resolve a pending nation-op proposal
+// waiting in game.pendingNationOps: a rename takes effect (body.edits.name
+// may override the proposed name), a split partitions the nation's territory
+// into the proposed parts (body.edits.playerPart picks which part the player
+// leads, default 0), and a merge folds its inputs into the survivor
+// (body.edits.name may override the merged name). No LLM call, no turn
+// advance — same fast save → broadcast → respond order as /queue/remove.
+// The version bump lets "never go backwards" clients reconcile.
+app.post('/api/games/:id/nation-op/confirm', (req, res) => {
+  const id = req.params.id;
+  const game = db.load(id);
+  if (!game) return res.status(404).json({ error: 'game not found' });
+  const body = (req.body ?? {}) as ConfirmNationOpRequest;
+  const next = confirmNationOp(game, body.index, body.edits);
+  if (!next) return res.status(400).json({ error: 'invalid proposal index' });
+  db.save(next);
+  broadcast(id, 'state', { state: next });
+  res.json({ game: next });
+});
+
+app.post('/api/games/:id/nation-op/reject', (req, res) => {
+  const id = req.params.id;
+  const game = db.load(id);
+  if (!game) return res.status(404).json({ error: 'game not found' });
+  const body = (req.body ?? {}) as RejectNationOpRequest;
+  const next = rejectNationOp(game, body.index);
+  if (!next) return res.status(400).json({ error: 'invalid proposal index' });
+  db.save(next);
+  broadcast(id, 'state', { state: next });
+  res.json({ game: next });
+});
+
 // Jump forward: commit the whole pending round (or an empty one) to the model
 // in a single turn. applyTurnResult clears the pending queue on the returned
 // state. 404 for not-found/preset-missing; 502 for LLM/model (transport) errors.
@@ -231,8 +324,14 @@ app.post('/api/games/:id/jump', async (req, res) => {
   const id = req.params.id;
   const game = db.load(id);
   if (!game) return res.status(404).json({ error: 'game not found' });
-  const preset = presetStore.get(game.presetId);
-  if (!preset) return res.status(404).json({ error: 'preset_missing' });
+  let preset = presetStore.get(game.presetId);
+  if (!preset) {
+    // (v0.31, #52) A dynamically generated game has no static preset file:
+    // synthesize one from the saved world so the turn engine can run. A
+    // genuinely-missing static preset still 404s.
+    if (game.presetId !== 'dynamic') return res.status(404).json({ error: 'preset_missing' });
+    preset = dynamicPresetFromGame(game);
+  }
   try {
     const { state, result } = await runTurn({
       llm,
@@ -250,6 +349,27 @@ app.post('/api/games/:id/jump', async (req, res) => {
       // engine the resolver — the turn then runs with the LLM's getNeighbours
       // tool and the player-frontier prompt field (both switch off without it).
       getNeighbours: hasAdjacency() ? (keys) => neighboursOf(keys) : undefined,
+      // (v0.27, #44) when the centroid manifest loaded, hand the engine the
+      // resolver so a turn can place new map markers at their region's
+      // centroid (without it, marker adds are dropped; existing markers are
+      // still maintained).
+      centroidOf: hasCentroids() ? (key) => centroidOf(key) : undefined,
+      // (v0.28, #46) when the region-geo manifest (area + population) loaded,
+      // hand the engine the resolver so the end-of-turn recompute weights each
+      // owned region by area×population (without it the aggregate degrades to
+      // an unweighted median — still region-consistent, just unweighted).
+      geoOf: hasGeo() ? (key) => geoOf(key) : undefined,
+      // (v0.29, #46 PR 2) region ref resolver: lets the model name a
+      // regionChanges target by its human-readable name (resolved
+      // case-insensitively against the region-key manifest) or its key;
+      // unknown / ambiguous refs are dropped. Always on — the resolver is
+      // pure (validKeys + regionName) and degrades to a key-only match when
+      // the manifest is absent.
+      regionKeyResolver: (ref) => resolveRegionKey(ref, validKeys(), (k) => regionName(k)),
+      // (v0.30, #50) region display name for the engine's "invasion repelled"
+      // event (geo properties.name, else the raw key). Always on — the
+      // resolver is pure and degrades to the key when the manifest is absent.
+      regionNameOf: (k) => regionName(k),
     });
     db.save(state);
     broadcast(id, 'turn', { state, result });
@@ -279,6 +399,86 @@ app.post('/api/games/:id/advisor', async (req, res) => {
   }
 });
 
+// --- Dynamic scenario generation (v0.31, #52) ---
+//
+// The additive "Create scenario" path. Step 1 (POST /draft) designs a draft
+// world + an advisor checkpoint list; the client shows both, the player
+// approves/removes checkpoints and picks a nation; step 2 (POST /commit)
+// finalizes the world (constrained to the approved checkpoints) into a saved,
+// playable game. Both steps ride the scenario LLM client (the deterministic
+// scenario stub under LLM_STUB=1, the live model otherwise). All existing
+// routes are untouched.
+
+app.get('/api/scenarios/templates', (_req, res) => {
+  res.json({ templates: templateStore.listMeta() });
+});
+
+app.post('/api/scenarios/draft', async (req, res) => {
+  const body = (req.body ?? {}) as { templateId?: string; description?: string; year?: number };
+  const template = templateStore.get(body.templateId ?? '');
+  if (!template) return res.status(400).json({ error: 'unknown template' });
+  const description = typeof body.description === 'string' ? body.description.trim() : '';
+  const year = Number.isFinite(body.year as number) ? (body.year as number) : template.year;
+  const codes = validCountryCodes();
+  try {
+    const { world, checkpoints } = await generateDraft({
+      llm: scenarioLlm,
+      template,
+      description,
+      year,
+      // No region data → no code filtering (the draft keeps whatever codes the
+      // model emitted; expansion degrades to the raw keys, like presets do).
+      validCountryCodes: codes.size > 0 ? codes : undefined,
+    });
+    if (!world) return res.status(502).json({ error: 'generate: the model returned no usable world' });
+    res.json({ world, checkpoints });
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    res.status(502).json({ error: `generate failed: ${msg}` });
+  }
+});
+
+app.post('/api/scenarios/commit', async (req, res) => {
+  const body = (req.body ?? {}) as {
+    templateId?: string;
+    description?: string;
+    year?: number;
+    draft?: WorldDraft;
+    approvedCheckpoints?: string[];
+    playerNationId?: string;
+  };
+  const template = templateStore.get(body.templateId ?? '');
+  if (!template) return res.status(400).json({ error: 'unknown template' });
+  const description = typeof body.description === 'string' ? body.description.trim() : '';
+  const year = Number.isFinite(body.year as number) ? (body.year as number) : template.year;
+  const approvedCheckpoints = Array.isArray(body.approvedCheckpoints)
+    ? body.approvedCheckpoints.filter((c): c is string => typeof c === 'string' && c.trim() !== '')
+    : [];
+  const playerNationId = typeof body.playerNationId === 'string' ? body.playerNationId : '';
+  const codes = validCountryCodes();
+  try {
+    const state = await finalizeWorld({
+      llm: scenarioLlm,
+      template,
+      description,
+      year,
+      approvedCheckpoints,
+      draft: body.draft,
+      playerNationId,
+      validCountryCodes: codes.size > 0 ? codes : undefined,
+      expand: (cs) => expandCountriesToKeys(cs),
+      id: randomUUID(),
+      title: template.name,
+      startDate: `${year}-01-01`,
+    });
+    db.save(state);
+    res.json({ id: state.id });
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    res.status(502).json({ error: `commit failed: ${msg}` });
+  }
+});
+
 // --- SSE stream ---
 app.get('/sse/:id', (req, res) => {
   const id = req.params.id;
@@ -316,4 +516,4 @@ app.listen(PORT, () => {
 });
 
 // Exported for tests (createApp is implicit via app; here we just expose handles).
-export { app, db, llm };
+export { app, db, llm, scenarioLlm, templateStore };

server/map.test.ts

@@ -48,6 +48,15 @@ const state: GameState = {
   pending: [],
   version: 1,
   unowned: [],
+  pendingNationOps: [],
+  markers: [],
+  // (v0.28, #46) the map is ownership-only; the region-stats table is unused here.
+  regionStats: {},
+  // (v0.33.0, #56) the map is ownership-only; wars are unused here.
+  wars: [],
+  // (v0.35.0, #58) the map is ownership-only; trades/embargoes are unused here.
+  trades: [],
+  embargoes: [],
 };
 
 // The RegionMap built from the fixture: the authoritative region key → owner source.

server/protocol.test.ts

@@ -0,0 +1,262 @@
+import { describe, expect, it } from 'vitest';
+import {
+  canConquer,
+  CONQUEST_MILITARY_MARGIN,
+  deriveNationStats,
+  migrateRegionStats,
+  seedRegionStats,
+  weightedMedian,
+} from '../shared/protocol';
+import type { GameState, Nation, NationStats } from '../shared/types';
+
+// --- Test fixtures -----------------------------------------------------------
+
+const S = (military: number, economy: number, stability: number, population: number): NationStats => ({
+  military,
+  economy,
+  stability,
+  population,
+});
+
+function nation(id: string, name: string, stats: NationStats, territory: string[]): Nation {
+  return { id, name, type: 'major', stats, territory, relations: {} };
+}
+
+function mkState(
+  nations: Record<string, Nation>,
+  regionStats?: Record<string, unknown>,
+): GameState {
+  const base: GameState = {
+    id: 'g',
+    presetId: 'p',
+    presetTitle: 'P',
+    playerNationId: Object.keys(nations)[0] ?? '',
+    turn: 1,
+    date: '1939-09-01',
+    nations,
+    events: [],
+    pending: [],
+    version: 1,
+    unowned: [],
+    pendingNationOps: [],
+    markers: [],
+    regionStats: {} as GameState['regionStats'],
+    wars: [],
+    trades: [],
+    embargoes: [],
+  };
+  if (regionStats !== undefined) base.regionStats = regionStats as GameState['regionStats'];
+  else delete (base as { regionStats?: unknown }).regionStats; // simulate a legacy row
+  return base;
+}
+
+// --- weightedMedian ----------------------------------------------------------
+
+describe('weightedMedian', () => {
+  it('returns 0 for an empty input or zero total weight', () => {
+    expect(weightedMedian([], [])).toBe(0);
+    expect(weightedMedian([5, 6], [0, 0])).toBe(0); // zero weights
+    expect(weightedMedian([5, 6], [NaN, -1])).toBe(0); // non-finite / non-positive → 0
+  });
+
+  it('returns the single value when it is the only weighted input', () => {
+    expect(weightedMedian([42], [7])).toBe(42);
+  });
+
+  it('the median of a set of IDENTICAL values is that value (translation-invariant)', () => {
+    // The invariant seeding + legacy migration rely on: equal values → that value,
+    // regardless of the (arbitrary) weights.
+    expect(weightedMedian([7, 7, 7], [1, 5, 9])).toBe(7);
+    expect(weightedMedian([0, 0], [10, 20])).toBe(0);
+    expect(weightedMedian([100, 100, 100], [1, 1, 1000])).toBe(100);
+    // and a constant shift shifts the result by the same constant
+    expect(weightedMedian([107, 107, 107], [1, 5, 9])).toBe(weightedMedian([7, 7, 7], [1, 5, 9]) + 100);
+  });
+
+  it('picks the value at the first point the cumulative weight reaches half the total', () => {
+    // two equal weights: the lower value is reached first (cum 1 of 2 ≥ 1)
+    expect(weightedMedian([10, 20], [1, 1])).toBe(10);
+    // an odd middle: the true middle value
+    expect(weightedMedian([10, 20, 30], [1, 1, 1])).toBe(20);
+    // the heavier value dominates
+    expect(weightedMedian([10, 20], [1, 3])).toBe(20);
+    expect(weightedMedian([10, 20], [3, 1])).toBe(10);
+  });
+
+  it('treats non-finite or non-positive weights as excluded (0)', () => {
+    // NaN weight on 10, positive on 20 → only 20 counts
+    expect(weightedMedian([10, 20], [NaN, 1])).toBe(20);
+    // negative weight on 20, positive on 10 → only 10 counts
+    expect(weightedMedian([10, 20], [1, -5])).toBe(10);
+  });
+});
+
+// --- deriveNationStats -------------------------------------------------------
+
+describe('deriveNationStats', () => {
+  const regionStats = {
+    a: S(50, 50, 50, 50),
+    b: S(90, 90, 90, 90),
+  };
+  const geo: Record<string, { area: number; population: number }> = { a: { area: 100, population: 1000 }, b: { area: 1000, population: 1000 } };
+
+  it('weights by area×population: the larger region dominates the aggregate', () => {
+    // a: weight 100×1000=100000, b: weight 1000×1000=1000000 → b (90) dominates
+    const out = deriveNationStats(['a', 'b'], regionStats, (k) => geo[k]);
+    expect(out).toEqual(S(90, 90, 90, 90));
+  });
+
+  it('degrades to a uniform (unweighted) median without geo: the lower value is reached first', () => {
+    // equal weights 1,1 → the lower (a=50) is reached at half-total first
+    const out = deriveNationStats(['a', 'b'], regionStats);
+    expect(out).toEqual(S(50, 50, 50, 50));
+    // same when geoOf is provided but returns undefined for the keys (missing geo)
+    const out2 = deriveNationStats(['a', 'b'], regionStats, () => undefined);
+    expect(out2).toEqual(S(50, 50, 50, 50));
+  });
+
+  it('skips a region key that has no stats entry', () => {
+    // b has no entry → only a is counted → a's (50) values
+    const out = deriveNationStats(['a', 'b'], { a: S(50, 50, 50, 50) }, (k) => geo[k]);
+    expect(out).toEqual(S(50, 50, 50, 50));
+  });
+
+  it('returns zero stats when none of the owned regions has a stats entry', () => {
+    const out = deriveNationStats(['a', 'b'], {}, (k) => geo[k]);
+    expect(out).toEqual(S(0, 0, 0, 0));
+  });
+
+  it('a single region yields exactly that region\'s stats (the seeding invariant)', () => {
+    expect(deriveNationStats(['a'], regionStats, (k) => geo[k])).toEqual(S(50, 50, 50, 50));
+    expect(deriveNationStats(['a'], regionStats)).toEqual(S(50, 50, 50, 50));
+  });
+
+  it('treats zero/negative area or population as a fallback weight of 1', () => {
+    // a has area 0 (weight falls back to 1×pop), b has full weight → b dominates
+    const g: Record<string, { area: number; population: number }> = { a: { area: 0, population: 1000 }, b: { area: 1000, population: 1000 } };
+    const out = deriveNationStats(['a', 'b'], regionStats, (k) => g[k]);
+    expect(out).toEqual(S(90, 90, 90, 90));
+  });
+});
+
+// --- seedRegionStats ---------------------------------------------------------
+
+describe('seedRegionStats', () => {
+  it('copies each owner\'s stats to every region it owns', () => {
+    const nations = {
+      uk: nation('uk', 'UK', S(80, 70, 60, 50), ['k1', 'k2']),
+      de: nation('de', 'DE', S(95, 70, 75, 90), ['k3']),
+    };
+    expect(seedRegionStats(nations)).toEqual({
+      k1: S(80, 70, 60, 50),
+      k2: S(80, 70, 60, 50),
+      k3: S(95, 70, 75, 90),
+    });
+  });
+
+  it('gives the first owner\'s stats a key owned by two or more nations (corrupt)', () => {
+    const nations = {
+      a: nation('a', 'A', S(10, 10, 10, 10), ['k1']),
+      b: nation('b', 'B', S(90, 90, 90, 90), ['k1']),
+    };
+    expect(seedRegionStats(nations)).toEqual({ k1: S(10, 10, 10, 10) });
+  });
+
+  it('returns an empty table for nations with no territory', () => {
+    const nations = { a: nation('a', 'A', S(10, 10, 10, 10), []) };
+    expect(seedRegionStats(nations)).toEqual({});
+  });
+});
+
+// --- migrateRegionStats ------------------------------------------------------
+
+describe('migrateRegionStats', () => {
+  it('returns a v0.28+ row (regionStats present) UNCHANGED — same reference, no recompute', () => {
+    const state = mkState(
+      { uk: nation('uk', 'UK', S(42, 70, 60, 50), ['k1']) },
+      { k1: S(99, 70, 60, 50) }, // deliberately divergent from the nation stats
+    );
+    const out = migrateRegionStats(state);
+    expect(out).toBe(state); // same reference: untouched
+    expect(out.regionStats).toEqual({ k1: S(99, 70, 60, 50) });
+    expect(out.nations.uk.stats).toEqual(S(42, 70, 60, 50)); // NOT recomputed from the region
+  });
+
+  it('migrates a legacy row (regionStats absent): seeds each owned region and preserves stats', () => {
+    const state = mkState({
+      uk: nation('uk', 'UK', S(80, 70, 60, 50), ['k1', 'k2', 'k3']),
+      de: nation('de', 'DE', S(95, 70, 75, 90), ['k4']),
+    });
+    // sanity: we built a legacy row
+    expect((state as { regionStats?: unknown }).regionStats).toBeUndefined();
+
+    const out = migrateRegionStats(state, (k) =>
+      k === 'k1' ? { area: 100, population: 1000 }
+      : k === 'k2' ? { area: 1, population: 1 }
+      : k === 'k3' ? { area: 9, population: 9 }
+      : { area: 50, population: 500 });
+    // each owned region is seeded with a copy of its owner's stats…
+    expect(out.regionStats).toEqual({
+      k1: S(80, 70, 60, 50),
+      k2: S(80, 70, 60, 50),
+      k3: S(80, 70, 60, 50),
+      k4: S(95, 70, 75, 90),
+    });
+    // …and the (multi-region) nation's stats are PRESERVED: the weighted median of
+    // identical values is that value, regardless of the (uneven) weights.
+    expect(out.nations.uk.stats).toEqual(S(80, 70, 60, 50));
+    expect(out.nations.de.stats).toEqual(S(95, 70, 75, 90));
+    // the original row is NOT mutated
+    expect((state as { regionStats?: unknown }).regionStats).toBeUndefined();
+    expect(state.nations.uk.stats).toEqual(S(80, 70, 60, 50));
+  });
+
+  it('a legacy 0-region nation keeps its stats (no recompute, no entries)', () => {
+    const state = mkState({
+      uk: nation('uk', 'UK', S(80, 70, 60, 50), []),
+      de: nation('de', 'DE', S(95, 70, 75, 90), ['k1']),
+    });
+    const out = migrateRegionStats(state);
+    expect(out.nations.uk.stats).toEqual(S(80, 70, 60, 50)); // unchanged
+    expect(out.nations.de.stats).toEqual(S(95, 70, 75, 90)); // single region → preserved
+    expect(out.regionStats).toEqual({ k1: S(95, 70, 75, 90) });
+    expect('uk' in (out.regionStats ?? {})).toBe(false);
+  });
+});
+
+// --- canConquer (v0.30, #50: the military hard gate) -------------------------
+
+describe('canConquer', () => {
+  it('the default margin constant is 15', () => {
+    expect(CONQUEST_MILITARY_MARGIN).toBe(15);
+  });
+
+  it('an attacker within the margin of the defender proceeds (gap == margin)', () => {
+    // attacker 10, defender 25 → gap of 15 == margin → win (not more than 15 below)
+    expect(canConquer(10, 25)).toBe(true);
+  });
+
+  it('an attacker more than the margin below the defender is repelled (gap == margin+1)', () => {
+    // attacker 9, defender 25 → gap of 16 > margin → repel
+    expect(canConquer(9, 25)).toBe(false);
+  });
+
+  it('an equal attacker proceeds', () => {
+    expect(canConquer(50, 50)).toBe(true);
+  });
+
+  it('an attacker within the margin (gap < margin) proceeds', () => {
+    expect(canConquer(30, 40)).toBe(true); // gap 10
+    expect(canConquer(14, 25)).toBe(true); // gap 11
+  });
+
+  it('an attacker ahead of the defender always proceeds', () => {
+    expect(canConquer(90, 10)).toBe(true);
+  });
+
+  it('a margin of 0 means only an equal-or-ahead attacker proceeds', () => {
+    expect(canConquer(50, 50, 0)).toBe(true); // equal
+    expect(canConquer(51, 50, 0)).toBe(true); // ahead
+    expect(canConquer(49, 50, 0)).toBe(false); // one below → repel
+  });
+});

server/regions.test.ts

@@ -5,8 +5,12 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 import {
   allTerritoryKeys,
+  centroidOf,
   expandCountriesToKeys,
+  geoOf,
   hasAdjacency,
+  hasCentroids,
+  hasGeo,
   hasRegionData,
   loadRegions,
   neighboursOf,
@@ -27,9 +31,9 @@ describe('regions (region-key loader, v0.19 #16 P1)', () => {
     expect(loadRegions(root)).toBe(true);
   });
 
-  it('loads the full manifest: 1,796 unique valid region keys', () => {
+  it('loads the full manifest: 1,800 unique valid region keys', () => {
     expect(hasRegionData()).toBe(true);
-    expect(validKeys().size).toBe(1796);
+    expect(validKeys().size).toBe(1800);
   });
 
   it('expands an ISO_A3 country to the region keys of all its sub-regions', () => {
@@ -51,6 +55,21 @@ describe('regions (region-key loader, v0.19 #16 P1)', () => {
     expect(ref['aisne-gstu']).toBe('Aisne (FRA)');
   });
 
+  it('expands RUS to all 84 sub-regions after the #31 + #41 Arkhangel splits (no ownership gap at game init)', () => {
+    // #31 split RU-ARK into the mainland + New Earth + Severnaya Zemlya; #41
+    // repartitioned the mainland into the core (unchanged key) + Pechora +
+    // Yamal. A fresh game's RUS territory (expanded from the preset's
+    // country list) must contain all five sub-region keys — the main one
+    // (ownership-safe, unchanged key) plus the island and band ones.
+    const rus = expandCountriesToKeys(['RUS']);
+    expect(rus).toHaveLength(84);
+    expect(rus).toContain('arkhangel-sk-lhbk');
+    expect(rus).toContain('new-earth-eikt');
+    expect(rus).toContain('severnaya-zemlya-awqp');
+    expect(rus).toContain('pechora-qwhs');
+    expect(rus).toContain('yamal-gosw');
+  });
+
   it('referenceForKeys labels only known keys and omits unknown ones', () => {
     const ref = referenceForKeys(['ain-lqtt', 'not-a-real-key-xyz']);
     expect(ref['ain-lqtt']).toBe('Ain (FRA)');
@@ -87,6 +106,14 @@ describe('regions (region-key loader, v0.19 #16 P1)', () => {
       pending: [],
       version: 1,
       unowned: [],
+      pendingNationOps: [],
+      markers: [],
+      // (v0.28, #46) unused here (allTerritoryKeys is ownership-only).
+      regionStats: {},
+      wars: [],
+      // (v0.35.0, #58) unused here (allTerritoryKeys is ownership-only).
+      trades: [],
+      embargoes: [],
     };
     // 16 GBR sub-regions + 42 FRA sub-regions, no overlap between the two.
     expect(allTerritoryKeys(state).size).toBe(58);
@@ -117,6 +144,34 @@ describe('regions (region-key loader, v0.19 #16 P1)', () => {
     expect(neighboursOf([])).toEqual([]);
   });
 
+  it('(v0.27 #44) hasCentroids() is true and centroidOf resolves a real key to a plausible location', () => {
+    expect(hasCentroids()).toBe(true);
+    const ain = centroidOf('ain-lqtt');
+    expect(ain).toBeDefined();
+    expect(ain!.lat).toBeCloseTo(46.16, 1);
+    expect(ain!.lon).toBeCloseTo(4.8, 1);
+    expect(ain!.spread).toBeGreaterThan(0);
+  });
+
+  it('(v0.27 #44) centroidOf returns undefined for an unknown key', () => {
+    expect(centroidOf('not-a-real-key-xyz')).toBeUndefined();
+  });
+
+  it('(v0.28 #46) hasGeo() is true and geoOf resolves a real key to area + population', () => {
+    expect(hasGeo()).toBe(true);
+    const ain = geoOf('ain-lqtt');
+    expect(ain).toBeDefined();
+    expect(ain!.area).toBeGreaterThanOrEqual(0); // km²
+    expect(ain!.population).toBeGreaterThanOrEqual(0);
+    // exact spot-check values pinned from the committed manifest (Ain, FRA)
+    expect(ain!.area).toBeCloseTo(22557.77, 1); // km²
+    expect(ain!.population).toBe(2304126);
+  });
+
+  it('(v0.28 #46) geoOf returns undefined for an unknown key', () => {
+    expect(geoOf('not-a-real-key-xyz')).toBeUndefined();
+  });
+
   describe('graceful degradation with no region data', () => {
     beforeEach(() => resetRegions());
 
@@ -130,6 +185,12 @@ describe('regions (region-key loader, v0.19 #16 P1)', () => {
       // and no adjacency: the LLM tool / frontier field switch off
       expect(hasAdjacency()).toBe(false);
       expect(neighboursOf(['moselle-rygy'])).toEqual([]);
+      // and no centroids: the marker-placement path degrades to a no-op
+      expect(hasCentroids()).toBe(false);
+      expect(centroidOf('ain-lqtt')).toBeUndefined();
+      // and no region-geo: the per-region stats weighting degrades to uniform
+      expect(hasGeo()).toBe(false);
+      expect(geoOf('ain-lqtt')).toBeUndefined();
     });
   });
 
@@ -165,13 +226,13 @@ describe('loadRegions resolves the manifest per environment (dev public/ vs prod
   it('loads from dist/ when public/ is absent (the prod container layout)', () => {
     expect(loadRegions(prodRoot)).toBe(true);
     expect(hasRegionData()).toBe(true);
-    expect(validKeys().size).toBe(1796);
+    expect(validKeys().size).toBe(1800);
     expect(expandCountriesToKeys(['FRA'])).toHaveLength(42);
   });
 
   it('still loads from public/ (the dev layout, the first candidate)', () => {
     expect(loadRegions(realRoot)).toBe(true);
-    expect(validKeys().size).toBe(1796);
+    expect(validKeys().size).toBe(1800);
   });
 
   it('a dist/ WITHOUT the adjacency manifest degrades: hasAdjacency() false, neighboursOf []', () => {
@@ -181,6 +242,37 @@ describe('loadRegions resolves the manifest per environment (dev public/ vs prod
     expect(loadRegions(prodRoot)).toBe(true);
     expect(hasAdjacency()).toBe(false);
     expect(neighboursOf(['moselle-rygy'])).toEqual([]);
+    // and no centroids (not copied into this dist/) -> marker placement degrades
+    expect(hasCentroids()).toBe(false);
+    expect(centroidOf('ain-lqtt')).toBeUndefined();
+    // and no region-geo (not copied into this dist/) -> stats weighting is uniform
+    expect(hasGeo()).toBe(false);
+    expect(geoOf('ain-lqtt')).toBeUndefined();
+  });
+
+  it('(v0.27 #44) a dist/ WITH the centroids manifest loads them (prod layout)', () => {
+    copyFileSync(
+      path.join(realRoot, 'public', 'region-centroids.json'),
+      path.join(prodRoot, 'dist', 'region-centroids.json'),
+    );
+    expect(loadRegions(prodRoot)).toBe(true);
+    expect(hasCentroids()).toBe(true);
+    const ain = centroidOf('ain-lqtt');
+    expect(ain).toBeDefined();
+    expect(ain!.lat).toBeCloseTo(46.16, 1);
+  });
+
+  it('(v0.28 #46) a dist/ WITH the region-geo manifest loads it (prod layout)', () => {
+    copyFileSync(
+      path.join(realRoot, 'public', 'region-geo.json'),
+      path.join(prodRoot, 'dist', 'region-geo.json'),
+    );
+    expect(loadRegions(prodRoot)).toBe(true);
+    expect(hasGeo()).toBe(true);
+    const ain = geoOf('ain-lqtt');
+    expect(ain).toBeDefined();
+    expect(ain!.area).toBeCloseTo(22557.77, 1);
+    expect(ain!.population).toBe(2304126);
   });
 
   it('returns false and no data when neither public/ nor dist/ holds the files', () => {

server/regions.ts

@@ -2,7 +2,9 @@
 // (region-keys.json: stable feature id -> region key), the sub-national geo
 // (regions.geo.json: feature id -> { name, parent }), and — optionally — the
 // precomputed region-adjacency manifest (region-adjacency.json: region key ->
-// bordering region keys, built by scripts/build-region-adjacency.mjs) — all
+// bordering region keys, built by scripts/build-region-adjacency.mjs) and the
+// precomputed region-centroid manifest (region-centroids.json: region key ->
+// { lat, lon, spread }, built by scripts/build-region-centroids.mjs) — all
 // from public/ in dev (Vite serves it) or dist/ in prod (Vite copies
 // public/* -> dist/ at build, and the Docker image keeps only dist/) — and
 // joins them into the lookups the region-level ownership model needs:
@@ -13,6 +15,10 @@
 //   - neighboursOf(): the union of the bordering keys for a set of keys — the
 //     data behind the LLM's getNeighbours tool and the player-frontier prompt
 //     field (v0.21, #16 P2)
+//   - centroidOf(): a region key's precomputed anchor point ({ lat, lon, spread })
+//     — the data behind LLM-placed map markers (v0.27, #44)
+//   - geoOf(): a region key's area (km²) + population (from region-geo.json)
+//     — the weighting source for the per-region stats model (v0.28, #46)
 //
 // Deliberately turf-free: it reads the JSON files with plain JSON.parse and
 // never imports @turf/@types/geojson (importing one pulls @types/geojson into
@@ -39,12 +45,17 @@ interface RegionData {
   validKeys: Set<string>;
   /** region key -> bordering region keys (from public/region-adjacency.json). */
   adjacency: Record<string, string[]>;
+  /** region key -> anchor point (from public/region-centroids.json). */
+  centroids: Record<string, { lat: number; lon: number; spread: number }>;
+  /** region key -> { area (km²), population } (from public/region-geo.json, v0.28 #46). */
+  geo: Record<string, { area: number; population: number }>;
 }
 
 let data: RegionData | null = null;
 
 /**
- * Load (or reload) the region-key manifest, geo, and adjacency. Idempotent.
+ * Load (or reload) the region-key manifest, geo, adjacency, and centroids.
+ * Idempotent.
  * The files are served to the client from `public/` in dev (Vite serves it
  * directly) and from `dist/` in prod (Vite copies `public/*` → `dist/` at build
  * and the Docker image keeps only `dist/`), so probe `public/` then `dist/`
@@ -52,7 +63,10 @@ let data: RegionData | null = null;
  * key manifest + geo. The adjacency manifest is OPTIONAL: when it is missing
  * or broken, `adjacency` stays empty and `neighboursOf`/`hasAdjacency` simply
  * report "no adjacency" (the LLM tool and the frontier prompt field switch
- * off; everything else keeps working). Returns true when the core pair loaded
+ * off; everything else keeps working). The centroid manifest is likewise
+ * OPTIONAL (v0.27, #44): when missing or broken, `centroids` stays empty and
+ * `centroidOf`/`hasCentroids` report "no centroids" (new map markers can't be
+ * placed, but everything else keeps working). Returns true when the core pair loaded
  * cleanly; a missing/broken pair clears the data and returns false so the
  * server still boots and degrades gracefully (expansion becomes a no-op,
  * ownership falls back to the raw input keys).
@@ -61,6 +75,8 @@ export function loadRegions(root: string): boolean {
   const keyFile = 'region-keys.json';
   const geoFile = 'regions.geo.json';
   const adjacencyFile = 'region-adjacency.json';
+  const centroidsFile = 'region-centroids.json';
+  const regionGeoFile = 'region-geo.json';
   const base = [
     path.join(root, 'public'), // dev: Vite serves public/ at /
     path.join(root, 'dist'), // prod: Vite copies public/* -> dist/ (== clientDir)
@@ -74,13 +90,13 @@ export function loadRegions(root: string): boolean {
   const geoPath = path.join(base, geoFile);
   try {
     const idToKey = JSON.parse(readFileSync(keyPath, 'utf8')) as Record<string, string>;
-    const geo = JSON.parse(readFileSync(geoPath, 'utf8')) as {
+    const geoJson = JSON.parse(readFileSync(geoPath, 'utf8')) as {
       features?: Array<{ id?: string | number; properties?: { name?: string; parent?: string } }>;
     };
     const keyToInfo: Record<string, RegionInfo> = {};
     const keysByCountry: Record<string, string[]> = {};
     const validKeys = new Set<string>();
-    for (const f of geo.features ?? []) {
+    for (const f of geoJson.features ?? []) {
       const id = f.id == null ? '' : String(f.id);
       const key = idToKey[id];
       if (!key) continue; // a geo feature with no manifest entry is skipped
@@ -105,7 +121,71 @@ export function loadRegions(root: string): boolean {
       }
     }
 
-    data = { idToKey, keyToInfo, keysByCountry, validKeys, adjacency };
+    // Centroids are optional too (v0.27, #44): a missing/broken file means
+    // "no centroid data" — new markers can't be placed (their adds are
+    // dropped), but everything else keeps working.
+    let centroids: Record<string, { lat: number; lon: number; spread: number }> = {};
+    const centroidsPath = path.join(base, centroidsFile);
+    if (existsSync(centroidsPath)) {
+      try {
+        const raw = JSON.parse(readFileSync(centroidsPath, 'utf8')) as Record<
+          string,
+          { lat?: unknown; lon?: unknown; spread?: unknown }
+        >;
+        // Keep only well-formed entries; a corrupt file degrades to "none".
+        for (const [k, v] of Object.entries(raw)) {
+          if (
+            v &&
+            typeof v.lat === 'number' &&
+            typeof v.lon === 'number' &&
+            typeof v.spread === 'number' &&
+            Number.isFinite(v.lat) &&
+            Number.isFinite(v.lon) &&
+            Number.isFinite(v.spread)
+          ) {
+            centroids[k] = { lat: v.lat, lon: v.lon, spread: v.spread };
+          }
+        }
+      } catch (err) {
+        console.error('[regions] failed to load region-centroids.json, continuing without it', err);
+        centroids = {};
+      }
+    }
+
+    // The region-geo manifest (v0.28, #46): area (km²) + population per region
+    // key — the weighting source for the per-region stats model. OPTIONAL like
+    // the others: a missing/broken file means "no geo data", and weighting
+    // degrades to uniform (every region weight 1) while everything else keeps
+    // working.
+    let geo: Record<string, { area: number; population: number }> = {};
+    const geoDataPath = path.join(base, regionGeoFile);
+    if (existsSync(geoDataPath)) {
+      try {
+        const raw = JSON.parse(readFileSync(geoDataPath, 'utf8')) as Record<
+          string,
+          { area?: unknown; population?: unknown }
+        >;
+        // Keep only well-formed entries; a corrupt file degrades to "none".
+        for (const [k, v] of Object.entries(raw)) {
+          if (
+            v &&
+            typeof v.area === 'number' &&
+            Number.isFinite(v.area) &&
+            v.area >= 0 &&
+            typeof v.population === 'number' &&
+            Number.isFinite(v.population) &&
+            v.population >= 0
+          ) {
+            geo[k] = { area: v.area, population: v.population };
+          }
+        }
+      } catch (err) {
+        console.error('[regions] failed to load region-geo.json, continuing without it', err);
+        geo = {};
+      }
+    }
+
+    data = { idToKey, keyToInfo, keysByCountry, validKeys, adjacency, centroids, geo };
     return validKeys.size > 0;
   } catch (err) {
     console.error('[regions] failed to load region data', err);
@@ -179,6 +259,18 @@ export function validKeys(): ReadonlySet<string> {
   return data ? data.validKeys : new Set<string>();
 }
 
+/**
+ * The set of ISO_A3 country codes that own at least one sub-region in the
+ * manifest (the valid `territory` codes for a world draft, v0.31 #52). These
+ * are the keys of `keysByCountry` — i.e. the distinct `properties.parent`
+ * values in regions.geo.json. Empty when no region data is loaded; callers
+ * pass it (or `undefined` to skip filtering) to `validateWorldDraft` so a
+ * draft's territory is checked against real countries.
+ */
+export function validCountryCodes(): ReadonlySet<string> {
+  return data ? new Set(Object.keys(data.keysByCountry)) : new Set<string>();
+}
+
 /**
  * True when the region-adjacency manifest loaded with at least one entry.
  * Callers (the server's jump route) use this to decide whether to hand the
@@ -189,6 +281,47 @@ export function hasAdjacency(): boolean {
   return data !== null && Object.keys(data.adjacency).length > 0;
 }
 
+/**
+ * True when the region-centroid manifest loaded with at least one entry
+ * (v0.27, #44). The server's jump route uses this to decide whether to hand
+ * the engine a centroid resolver (which lets a turn place new map markers)
+ * or skip marker placement (existing markers are still maintained).
+ */
+export function hasCentroids(): boolean {
+  return data !== null && Object.keys(data.centroids).length > 0;
+}
+
+/**
+ * True when the region-geo manifest loaded with at least one entry (v0.28,
+ * #46). The server's jump route uses this to decide whether to hand the
+ * engine a geo resolver (which weights the per-region stats derivation by
+ * area×population) or fall back to a uniform (unweighted) median.
+ */
+export function hasGeo(): boolean {
+  return data !== null && Object.keys(data.geo).length > 0;
+}
+
+/**
+ * The precomputed anchor point for a region key: the centroid of its
+ * largest-area part, plus a `spread` (≈ 0.1 × that part's smallest bbox
+ * dimension, in degrees) the engine scatters markers within
+ * ±(spread/2) of the centroid. `undefined` for an unknown key or when no
+ * centroid data is loaded (v0.27, #44).
+ */
+export function centroidOf(key: string): { lat: number; lon: number; spread: number } | undefined {
+  return data?.centroids[key];
+}
+
+/**
+ * The precomputed area (km²) + population for a region key (v0.28, #46) — the
+ * weighting source for the per-region stats model. `undefined` for an unknown
+ * key or when no geo data is loaded (the derivation then falls back to a
+ * uniform weight of 1 for that region).
+ */
+export function geoOf(key: string): { area: number; population: number } | undefined {
+  return data?.geo[key];
+}
+
 /**
  * The union of the region keys that share a land border with any of the given
  * keys — deduplicated, the queried keys themselves excluded, and sorted for

server/scenario-shared.test.ts

@@ -0,0 +1,235 @@
+import { describe, expect, it } from 'vitest';
+import {
+  relationFromScore,
+  validateWorldDraft,
+  worldDraftToGameState,
+  type WorldDraft,
+} from '../shared/scenario';
+import type { NationStats } from '../shared/types';
+
+// A deterministic fake ISO_A3 -> region-key expander (two sub-regions per
+// country), standing in for server/regions.expandCountriesToKeys in these
+// pure-function tests.
+const fakeExpand = (countries: string[]): string[] =>
+  countries.flatMap((c) => [`${c}-a`, `${c}-b`]);
+
+const S = (m: number, e: number, s: number, p: number): NationStats => ({
+  military: m,
+  economy: e,
+  stability: s,
+  population: p,
+});
+
+describe('relationFromScore (v0.31.0, #52)', () => {
+  it('maps the five sentiment bands to RelationStatus', () => {
+    expect(relationFromScore(100)).toBe('ally');
+    expect(relationFromScore(60)).toBe('ally');
+    expect(relationFromScore(0)).toBe('neutral');
+    expect(relationFromScore(30)).toBe('neutral');
+    expect(relationFromScore(-1)).toBe('rival');
+    expect(relationFromScore(-40)).toBe('rival');
+    expect(relationFromScore(-41)).toBe('hostile');
+    expect(relationFromScore(-80)).toBe('hostile');
+    expect(relationFromScore(-81)).toBe('war');
+    expect(relationFromScore(-100)).toBe('war');
+  });
+
+  it('clamps out-of-range scores before banding', () => {
+    expect(relationFromScore(250)).toBe('ally');
+    expect(relationFromScore(-250)).toBe('war');
+  });
+});
+
+describe('validateWorldDraft (v0.31.0, #52)', () => {
+  it('returns a clean draft from a valid payload', () => {
+    const raw = {
+      nations: [
+        { id: 'de', name: 'German Reich', type: 'major', stats: S(95, 70, 75, 90), territory: ['DEU'], relations: { uk: 80 } },
+        { id: 'uk', name: 'United Kingdom', type: 'major', stats: S(80, 75, 60, 48), territory: ['GBR', 'IRL'], relations: { de: 80 } },
+      ],
+    };
+    const d = validateWorldDraft(raw);
+    expect(d).not.toBeNull();
+    const draft = d as WorldDraft;
+    expect(draft.nations).toHaveLength(2);
+    expect(draft.nations[0]).toMatchObject({ id: 'de', name: 'German Reich', type: 'major' });
+    expect(draft.nations[0].stats).toEqual(S(95, 70, 75, 90));
+    expect(draft.nations[0].territory).toEqual(['DEU']);
+    expect(draft.nations[0].relations).toEqual({ uk: 80 });
+    expect(draft.events).toBeUndefined();
+  });
+
+  it('clamps out-of-range stat values to 0-100 and defaults missing to 50', () => {
+    const raw = {
+      nations: [
+        { name: 'Over', stats: { military: 150, economy: -20, stability: 7 }, territory: ['DEU'] },
+      ],
+    };
+    const d = validateWorldDraft(raw) as WorldDraft;
+    expect(d.nations[0].stats).toEqual(S(100, 0, 7, 50)); // population missing -> 50
+  });
+
+  it('upper-cases, de-dupes, and (given valid codes) filters territory to known ISO_A3', () => {
+    const codes = new Set(['DEU', 'GBR', 'FRA']);
+    const raw = {
+      nations: [
+        {
+          name: 'Mixed',
+          // lower-case, duplicated, and one unknown code (USA) to be dropped.
+          territory: ['deu', 'DEU', 'usa', 'gbr'],
+        },
+      ],
+    };
+    const d = validateWorldDraft(raw, { validCountryCodes: codes }) as WorldDraft;
+    expect(d.nations[0].territory).toEqual(['DEU', 'GBR']);
+  });
+
+  it('keeps unknown codes when no validCountryCodes set is supplied', () => {
+    const raw = { nations: [{ name: 'X', territory: ['AAA', 'BBB'] }] };
+    const d = validateWorldDraft(raw) as WorldDraft;
+    expect(d.nations[0].territory).toEqual(['AAA', 'BBB']);
+  });
+
+  it('resolves relation keys by id or (case-insensitive) name and drops self/unknown refs', () => {
+    const raw = {
+      nations: [
+        { id: 'de', name: 'Germany', territory: ['DEU'], relations: { 'United Kingdom': 55, de: 99, ghost: 10 } },
+        { id: 'uk', name: 'United Kingdom', territory: ['GBR'], relations: { de: -70 } },
+      ],
+    };
+    const d = validateWorldDraft(raw) as WorldDraft;
+    // de: the name-keyed ref resolves to uk, self (de) and unknown (ghost) dropped.
+    expect(d.nations[0].relations).toEqual({ uk: 55 });
+    // uk: the id-keyed ref to de is kept, clamped (already in range).
+    expect(d.nations[1].relations).toEqual({ de: -70 });
+  });
+
+  it('clamps relation scores to -100..100', () => {
+    const raw = {
+      nations: [
+        { id: 'a', name: 'A', territory: ['AAA'], relations: { b: 500 } },
+        { id: 'b', name: 'B', territory: ['BBB'], relations: { a: -500 } },
+      ],
+    };
+    const d = validateWorldDraft(raw) as WorldDraft;
+    expect(d.nations[0].relations).toEqual({ b: 100 });
+    expect(d.nations[1].relations).toEqual({ a: -100 });
+  });
+
+  it('suffices duplicate ids until unique and derives ids from names', () => {
+    const raw = {
+      nations: [
+        { id: 'x', name: 'First', territory: ['AAA'] },
+        { id: 'x', name: 'Second', territory: ['BBB'] },
+        { name: 'United Kingdom', territory: ['GBR'] }, // no id -> slug
+      ],
+    };
+    const d = validateWorldDraft(raw) as WorldDraft;
+    const ids = d.nations.map((n) => n.id);
+    expect(ids).toEqual(['x', 'x-2', 'united-kingdom']);
+  });
+
+  it('keeps backstory events that name a known nation and drops the rest', () => {
+    const raw = {
+      nations: [
+        { id: 'de', name: 'Germany', territory: ['DEU'] },
+        { id: 'uk', name: 'United Kingdom', territory: ['GBR'] },
+      ],
+      events: [
+        { nation: 'de', type: 'military', title: 'Remilitarization', text: 't', outcome: 'success' },
+        { nation: 'United Kingdom', type: 'political', title: 'By-elections', text: 't', outcome: 'neutral' },
+        { nation: 'ghost', type: 'political', title: 'No owner', text: 't', outcome: 'neutral' },
+        { nation: 'de', type: 'political' }, // no title -> dropped
+      ],
+    };
+    const d = validateWorldDraft(raw) as WorldDraft;
+    expect(d.events).toHaveLength(2);
+    expect(d.events?.[0]).toMatchObject({ nation: 'de', type: 'military', title: 'Remilitarization', outcome: 'success' });
+    expect(d.events?.[1]).toMatchObject({ nation: 'uk', type: 'political', title: 'By-elections', outcome: 'neutral' });
+  });
+
+  it('returns null (never throws) for unusable / garbage payloads', () => {
+    expect(validateWorldDraft(null)).toBeNull();
+    expect(validateWorldDraft('nope')).toBeNull();
+    expect(validateWorldDraft([])).toBeNull();
+    expect(validateWorldDraft({})).toBeNull();
+    expect(validateWorldDraft({ nations: [] })).toBeNull();
+    expect(validateWorldDraft({ nations: [{ name: 'No territory' }] })).toBeNull();
+    expect(validateWorldDraft({ nations: [{}] })).toBeNull(); // no name
+    expect(validateWorldDraft({ nations: [42] })).toBeNull(); // not an object
+    // no nation owns a *valid* territory -> unusable.
+    expect(
+      validateWorldDraft(
+        { nations: [{ name: 'X', territory: ['ZZZ'] }] },
+        { validCountryCodes: new Set(['DEU']) },
+      ),
+    ).toBeNull();
+  });
+});
+
+describe('worldDraftToGameState (v0.31.0, #52)', () => {
+  function draft(): WorldDraft {
+    return {
+      nations: [
+        { id: 'de', name: 'Germany', type: 'major', stats: S(90, 70, 75, 90), territory: ['DEU'], relations: { uk: 70 } },
+        { id: 'uk', name: 'United Kingdom', type: 'major', stats: S(80, 75, 60, 48), territory: ['GBR', 'IRL'], relations: { de: -90 } },
+      ],
+      events: [{ nation: 'de', type: 'political', title: 'The new order', text: 'A fresh map is drawn.', outcome: 'neutral' }],
+    };
+  }
+
+  it('expands ISO_A3 territory to region keys and seeds per-region stats', () => {
+    const g = worldDraftToGameState(draft(), fakeExpand, 'uk', {
+      id: 'g1',
+      title: 'Custom World',
+      startDate: '1939-09-01',
+    });
+    expect(g.id).toBe('g1');
+    expect(g.presetTitle).toBe('Custom World');
+    expect(g.date).toBe('1939-09-01');
+    expect(g.turn).toBe(1);
+    expect(g.version).toBe(1);
+    expect(g.playerNationId).toBe('uk');
+    expect(g.unowned).toEqual([]);
+    expect(g.markers).toEqual([]);
+    expect(g.pendingNationOps).toEqual([]);
+    expect(g.pending).toEqual([]);
+
+    // de owns DEU -> two region keys; uk owns GBR+IRL -> four.
+    expect(g.nations.de.territory).toEqual(['DEU-a', 'DEU-b']);
+    expect(g.nations.uk.territory).toEqual(['GBR-a', 'GBR-b', 'IRL-a', 'IRL-b']);
+
+    // Every owned region is seeded with a copy of its owner's stats.
+    expect(g.regionStats['DEU-a']).toEqual(g.nations.de.stats);
+    expect(g.regionStats['IRL-b']).toEqual(g.nations.uk.stats);
+    // No entry for unowned regions.
+    expect(g.regionStats['ZZZ-a']).toBeUndefined();
+  });
+
+  it('maps numeric relations to RelationStatus', () => {
+    const g = worldDraftToGameState(draft(), fakeExpand, 'de');
+    expect(g.nations.de.relations).toEqual({ uk: 'ally' }); // 70 -> ally
+    expect(g.nations.uk.relations).toEqual({ de: 'war' }); // -90 -> war
+  });
+
+  it('seeds the event feed from backstory events at turn 1 / startDate', () => {
+    const g = worldDraftToGameState(draft(), fakeExpand, 'de', { startDate: '2035-01-01' });
+    expect(g.events).toHaveLength(1);
+    expect(g.events[0]).toMatchObject({
+      turn: 1,
+      date: '2035-01-01',
+      nation: 'de',
+      type: 'political',
+      title: 'The new order',
+      outcome: 'neutral',
+    });
+  });
+
+  it('uses the defaults (empty id, Custom World, 1970-01-01) when options are omitted', () => {
+    const g = worldDraftToGameState(draft(), fakeExpand, 'de');
+    expect(g.id).toBe('');
+    expect(g.presetTitle).toBe('Custom World');
+    expect(g.date).toBe('1970-01-01');
+    expect(g.presetId).toBe('dynamic');
+  });
+});

server/scenario.test.ts

@@ -0,0 +1,335 @@
+// Unit tests for the dynamic scenario-generation LLM steps (v0.31, #52):
+// the prompt builders, the defensive parsers, generateDraft / finalizeWorld
+// over an injected LlmClient, and the deterministic scenario stub.
+import { describe, expect, it } from 'vitest';
+import {
+  buildGeneratePrompt,
+  buildRegeneratePrompt,
+  finalizeWorld,
+  generateDraft,
+  parseGenerate,
+  parseRegenerate,
+  SCENARIO_GENERATE_MARKER,
+  SCENARIO_REGENERATE_MARKER,
+} from './scenario';
+import { makeScenarioStubLlmClient, stubWorldFor } from './stubScenario';
+import type { EraTemplate, WorldDraft } from '../shared/scenario';
+import type { ChatMessage, LlmClient } from './llm';
+
+const TEMPLATE: EraTemplate = {
+  id: 'near-future',
+  name: 'Near Future',
+  year: 2035,
+  eraDescription: 'A fractured, multipolar 2035.',
+  suggestedPowers: [
+    { name: 'United States', region: 'USA', note: 'declining hegemon' },
+    { name: 'China', region: 'CHN', note: 'rising industrial power' },
+  ],
+  tensions: ['Indo-Pacific standoff', 'Climate migration'],
+};
+
+const VALID_CODES = new Set(['FRA', 'RUS', 'ESP', 'USA', 'CHN']);
+
+/** A minimal LlmClient double whose chat() returns a canned string (or calls a handler). */
+function fakeClient(canned?: string | ((messages: ChatMessage[]) => string)): LlmClient {
+  return {
+    async chat(messages) {
+      if (typeof canned === 'function') return canned(messages);
+      return canned ?? '{"world":{"nations":[]},"checkpoints":[]}';
+    },
+    async listModels() {
+      return [];
+    },
+  };
+}
+
+const GOOD_GENERATE = JSON.stringify({
+  world: {
+    nations: [
+      {
+        id: 'alba',
+        name: 'Alba',
+        type: 'major',
+        stats: { military: 70, economy: 60, stability: 65, population: 55 },
+        territory: ['FRA'],
+        relations: { boreas: -60 },
+      },
+      {
+        id: 'boreas',
+        name: 'Boreas',
+        type: 'major',
+        stats: { military: 55, economy: 70, stability: 50, population: 60 },
+        territory: ['RUS'],
+        relations: { alba: -60 },
+      },
+    ],
+  },
+  checkpoints: ['Alba presses its advantage.', 'Boreas fortifies the north.'],
+});
+
+const GOOD_REGENERATE = JSON.stringify({
+  world: {
+    nations: [
+      {
+        id: 'alba',
+        name: 'Alba',
+        type: 'major',
+        stats: { military: 70, economy: 60, stability: 70, population: 55 },
+        territory: ['FRA'],
+        relations: { boreas: -70 },
+      },
+      {
+        id: 'boreas',
+        name: 'Boreas',
+        type: 'major',
+        stats: { military: 55, economy: 70, stability: 55, population: 60 },
+        territory: ['RUS'],
+        relations: { alba: -70 },
+      },
+    ],
+  },
+});
+
+describe('buildGeneratePrompt', () => {
+  it('embeds the era, description, year and the valid country codes', () => {
+    const { system, user } = buildGeneratePrompt(TEMPLATE, 'a cold war in space', 2041, VALID_CODES);
+    expect(system).toContain(SCENARIO_GENERATE_MARKER);
+    expect(system).toContain('"checkpoints"');
+    expect(user).toContain('near-future');
+    expect(user).toContain('a cold war in space');
+    expect(user).toContain('2041');
+    expect(user).toContain('CHN');
+    expect(user).toContain('validCountryCodes');
+  });
+
+  it('omits the code list when no valid codes are supplied', () => {
+    const { system, user } = buildGeneratePrompt(TEMPLATE, 'desc', 2035, undefined);
+    expect(system).toContain('standard ISO 3166-1 alpha-3');
+    expect(user).not.toContain('validCountryCodes');
+  });
+});
+
+describe('buildRegeneratePrompt', () => {
+  it('embeds the approved checkpoints and the draft when present', () => {
+    const draft: WorldDraft = {
+      nations: [
+        {
+          id: 'alba',
+          name: 'Alba',
+          stats: { military: 70, economy: 60, stability: 65, population: 55 },
+          territory: ['FRA'],
+          relations: {},
+        },
+      ],
+    };
+    const { system, user } = buildRegeneratePrompt(
+      TEMPLATE,
+      'desc',
+      2035,
+      ['Alba presses its advantage.'],
+      VALID_CODES,
+      draft,
+    );
+    expect(system).toContain(SCENARIO_REGENERATE_MARKER);
+    expect(user).toContain('approvedCheckpoints');
+    expect(user).toContain('Alba presses its advantage.');
+    expect(user).toContain('draft');
+    expect(user).toContain('alba');
+  });
+
+  it('omits the draft field when none is supplied', () => {
+    const { user } = buildRegeneratePrompt(TEMPLATE, 'desc', 2035, [], VALID_CODES, undefined);
+    expect(user).not.toContain('draft');
+  });
+});
+
+describe('parseGenerate / parseRegenerate (defensive)', () => {
+  it('parses a valid generate answer into a world + checkpoints', () => {
+    const { world, checkpoints } = parseGenerate(GOOD_GENERATE, VALID_CODES);
+    expect(world).not.toBeNull();
+    expect(world!.nations).toHaveLength(2);
+    expect(world!.nations[0].id).toBe('alba');
+    expect(world!.nations[0].territory).toEqual(['FRA']);
+    expect(checkpoints).toEqual(['Alba presses its advantage.', 'Boreas fortifies the north.']);
+  });
+
+  it('strips code fences and drops unknown country codes', () => {
+    const raw = '```json\n' + GOOD_GENERATE + '\n```';
+    const { world } = parseGenerate(raw, new Set(['FRA'])); // RUS not in the set
+    expect(world).not.toBeNull();
+    expect(world!.nations.find((n) => n.id === 'boreas')?.territory).toEqual([]);
+  });
+
+  it('returns null world + empty checkpoints for garbage', () => {
+    const { world, checkpoints } = parseGenerate('not json at all', VALID_CODES);
+    expect(world).toBeNull();
+    expect(checkpoints).toEqual([]);
+  });
+
+  it('parses a valid regenerate answer (no checkpoints echoed)', () => {
+    const world = parseRegenerate(GOOD_REGENERATE, VALID_CODES);
+    expect(world).not.toBeNull();
+    expect(world!.nations[0].stats.stability).toBe(70);
+  });
+});
+
+describe('generateDraft (injected client)', () => {
+  it('returns a validated world + checkpoints from the model', async () => {
+    const { world, checkpoints } = await generateDraft({
+      llm: fakeClient(GOOD_GENERATE),
+      template: TEMPLATE,
+      description: 'a cold war in space',
+      year: 2041,
+      validCountryCodes: VALID_CODES,
+    });
+    expect(world).not.toBeNull();
+    expect(world!.nations).toHaveLength(2);
+    expect(checkpoints).toHaveLength(2);
+  });
+
+  it('nudges once when the first answer is unusable', async () => {
+    let call = 0;
+    const client: LlmClient = {
+      async chat() {
+        call += 1;
+        return call === 1 ? 'total garbage' : GOOD_GENERATE;
+      },
+      async listModels() {
+        return [];
+      },
+    };
+    const { world, checkpoints } = await generateDraft({
+      llm: client,
+      template: TEMPLATE,
+      description: 'x',
+      year: 2035,
+      validCountryCodes: VALID_CODES,
+    });
+    expect(call).toBe(2);
+    expect(world).not.toBeNull();
+    expect(checkpoints).toHaveLength(2);
+  });
+
+  it('returns null world when even the nudge fails', async () => {
+    const { world } = await generateDraft({
+      llm: fakeClient('still no json'),
+      template: TEMPLATE,
+      description: 'x',
+      year: 2035,
+      validCountryCodes: VALID_CODES,
+    });
+    expect(world).toBeNull();
+  });
+});
+
+describe('finalizeWorld (injected client)', () => {
+  const expand = (countries: string[]) => countries.flatMap((c) => [`${c}-a`, `${c}-b`]);
+
+  it('converts the finalized world to a playable GameState', async () => {
+    const state = await finalizeWorld({
+      llm: fakeClient(GOOD_REGENERATE),
+      template: TEMPLATE,
+      description: 'x',
+      year: 2035,
+      approvedCheckpoints: ['Alba presses its advantage.'],
+      playerNationId: 'alba',
+      validCountryCodes: VALID_CODES,
+      expand,
+      id: 'g-1',
+      title: 'Custom World',
+      startDate: '2035-01-01',
+    });
+    expect(state.id).toBe('g-1');
+    expect(state.presetId).toBe('dynamic');
+    expect(state.playerNationId).toBe('alba');
+    expect(state.turn).toBe(1);
+    expect(state.date).toBe('2035-01-01');
+    // FRA expands to two region keys; the per-region stats are seeded.
+    expect(state.nations.alba.territory).toEqual(['FRA-a', 'FRA-b']);
+    expect(state.regionStats['FRA-a']).toEqual(state.nations.alba.stats);
+  });
+
+  it('falls back to the first nation when the model drops the player nation', async () => {
+    // The regenerated world has no 'alba' — only 'boreas'.
+    const dropped = JSON.stringify({
+      world: {
+        nations: [
+          {
+            id: 'boreas',
+            name: 'Boreas',
+            stats: { military: 55, economy: 70, stability: 55, population: 60 },
+            territory: ['RUS'],
+            relations: {},
+          },
+        ],
+      },
+    });
+    const state = await finalizeWorld({
+      llm: fakeClient(dropped),
+      template: TEMPLATE,
+      description: 'x',
+      year: 2035,
+      approvedCheckpoints: [],
+      playerNationId: 'alba', // not in the world
+      validCountryCodes: VALID_CODES,
+      expand,
+    });
+    expect(state.playerNationId).toBe('boreas');
+  });
+});
+
+describe('scenario stub (deterministic, LLM_STUB=1)', () => {
+  it('is deterministic: same input → same generate output', async () => {
+    const llm = makeScenarioStubLlmClient();
+    const a = await generateDraft({
+      llm,
+      template: TEMPLATE,
+      description: 'd',
+      year: 2035,
+      validCountryCodes: VALID_CODES,
+    });
+    const b = await generateDraft({
+      llm,
+      template: TEMPLATE,
+      description: 'completely different description',
+      year: 1999,
+      validCountryCodes: VALID_CODES,
+    });
+    expect(a.world).toEqual(b.world);
+    expect(a.checkpoints).toEqual(b.checkpoints);
+    expect(a.world!.nations).toHaveLength(3);
+    expect(a.checkpoints).toHaveLength(3);
+  });
+
+  it('finalize respects the approved checkpoints (deterministically)', async () => {
+    const baseline = stubWorldFor([]);
+    const withAlba = stubWorldFor(['Alba dominates the western sea lanes.']);
+    const albaBase = baseline.nations.find((n) => n.id === 'alba')?.stats.stability ?? 0;
+    const boreasBase = baseline.nations.find((n) => n.id === 'boreas')?.stats.stability ?? 0;
+    const albaWith = withAlba.nations.find((n) => n.id === 'alba')?.stats.stability ?? 0;
+    const boreasWith = withAlba.nations.find((n) => n.id === 'boreas')?.stats.stability ?? 0;
+    // Approving a checkpoint that names Alba raises Alba's stability only.
+    expect(albaWith).toBe(albaBase + 5);
+    expect(boreasWith).toBe(boreasBase);
+  });
+
+  it('finalizeWorld over the stub returns a playable game honoring approvals', async () => {
+    const llm = makeScenarioStubLlmClient();
+    const state = await finalizeWorld({
+      llm,
+      template: TEMPLATE,
+      description: 'd',
+      year: 2035,
+      approvedCheckpoints: ['Boreas fortifies its northern frontier.'],
+      playerNationId: 'boreas',
+      validCountryCodes: VALID_CODES,
+      expand: (cs) => cs.flatMap((c) => [`${c}-a`]),
+      id: 'stub-1',
+    });
+    expect(state.id).toBe('stub-1');
+    expect(state.playerNationId).toBe('boreas');
+    expect(state.nations.boreas.territory).toEqual(['RUS-a']);
+    // The approved Boreas checkpoint raised its stability by 5 (50 → 55).
+    expect(state.nations.boreas.stats.stability).toBe(55);
+  });
+});

server/scenario.ts

@@ -0,0 +1,390 @@
+// Dynamic scenario generation — the two LLM steps (v0.31, #52).
+//
+// This is the additive "Create scenario" path. Two plain `chat()` calls (no
+// tools, no separate advisor endpoint — the advisor is embodied in step 1's
+// checkpoint list):
+//
+//   1. `generateDraft` — from an era template + a free-text description + a
+//      year, the model designs a draft {@link WorldDraft} (nations with ISO_A3
+//      territory, stats, relations, optional backstory) AND an opening
+//      checkpoint list (the advisor's briefing of the world's live tensions).
+//
+//   2. `finalizeWorld` — on commit, the model is re-asked to produce the
+//      final world, constrained to the player's APPROVED checkpoints (and,
+//      when the client re-sends the step-1 draft, based on it so the player's
+//      chosen nation survives). The result is converted to a playable
+//      {@link GameState} (region-key territory via the injected `expand`
+//      resolver, per-region stats seeded) and returned for the caller to
+//      persist — a normal game at `#/game/<id>`.
+//
+// Both steps are defensive like the rest of the engine: raw model output is
+// fence-stripped, the first balanced object is extracted, JSON.parsed, and
+// validated via the pure `validateWorldDraft` (which never throws and returns
+// `null` for unusable input). A transport-level failure (the model being down)
+// throws and is mapped to an HTTP 502 by the route; a bad *answer* degrades to
+// a null world, never a crash. The `LlmClient` is injected so unit tests and
+// the deterministic scenario stub (server/stubScenario.ts) can replace the
+// network call exactly like the turn path does.
+import type { LlmClient } from './llm';
+import { DEFAULT_MAX_TOKENS } from './llm';
+import type { EraTemplate, WorldDraft } from '../shared/scenario';
+import { validateWorldDraft } from '../shared/scenario';
+import type { GameState } from '../shared/types';
+import { worldDraftToGameState } from '../shared/scenario';
+
+// --- Defensive parsing (shared with the engine's approach) --------------------
+
+/** The system-prompt markers the deterministic scenario stub keys off. */
+export const SCENARIO_GENERATE_MARKER = '<<SCENARIO_GENERATE>>';
+export const SCENARIO_REGENERATE_MARKER = '<<SCENARIO_REGENERATE>>';
+
+/** Strip a leading/trailing ``` code fence (mirrors engine.stripFence). */
+function stripFence(text: string): string {
+  let t = text.trim();
+  const lead = t.match(/^```[a-zA-Z]*\s*\n?/);
+  if (lead) t = t.slice(lead[0].length);
+  const tail = t.match(/\n?\s*```\s*$/);
+  if (tail) t = t.slice(0, t.length - tail[0].length);
+  return t.trim();
+}
+
+/** Extract the first balanced `{ ... }` substring (string-aware). */
+function extractBalancedObject(text: string): string | null {
+  const start = text.indexOf('{');
+  if (start === -1) return null;
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = start; i < text.length; i++) {
+    const c = text[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (c === '\\') esc = true;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') inStr = true;
+    else if (c === '{') depth++;
+    else if (c === '}' && --depth === 0) return text.slice(start, i + 1);
+  }
+  return null;
+}
+
+/** Parse a raw top-level JSON object, or `null` when none is recoverable. */
+function parseObject(raw: string): Record<string, unknown> | null {
+  const jsonText = extractBalancedObject(stripFence(raw));
+  if (!jsonText) return null;
+  try {
+    const obj: unknown = JSON.parse(jsonText);
+    return obj && typeof obj === 'object' && !Array.isArray(obj)
+      ? (obj as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+// --- Prompt building ------------------------------------------------------------
+
+/**
+ * The shared nation JSON contract text, embedded in both system prompts so the
+ * model sees the exact shape it must emit. Mirrors the engine's strict "ONLY a
+ * valid JSON object" style.
+ */
+const WORLD_SHAPE = [
+  '{',
+  '  "world": {',
+  '    "nations": [',
+  '      {',
+  '        "id": "short-stable-id",',
+  '        "name": "Human readable name",',
+  '        "type": "major|minor|power|alliance|faction",',
+  '        "stats": {"military":0-100,"economy":0-100,"stability":0-100,"population":0-100},',
+  '        "territory": ["ISO_A3","ISO_A3"],',
+  '        "relations": {"<other nation id or name>": -100..100}',
+  '      }',
+  '    ],',
+  '    "events": [',
+  '      {"nation":"<id or name>","type":"<military|diplomatic|economic|political|social|disaster|scientific|cultural>","title":"short headline","text":"1-3 sentences","outcome":"<success|failure|partial|neutral>"}',
+  '    ]',
+  '  },',
+  '  "checkpoints": ["short advisor checkpoint", "..."]',
+  '}',
+].join('\n');
+
+/**
+ * The system prompt for step 1 (generate). Tells the model to design a fresh
+ * world for the era AND to emit an opening advisor checkpoint list.
+ */
+export function buildGeneratePrompt(
+  template: EraTemplate,
+  description: string,
+  year: number,
+  validCountryCodes: ReadonlySet<string> | undefined,
+): { system: string; user: string } {
+  const codes = validCountryCodes ? [...validCountryCodes].sort() : null;
+  const system = [
+    `${SCENARIO_GENERATE_MARKER} You are a world-builder for an alternate-history strategy game.`,
+    'Given an era, a starting year, and the designer\'s description, create a plausible, self-consistent world of 3 to 8 nations for that moment in (or diverged from) history.',
+    'Respond with ONLY a valid JSON object of exactly this shape. No prose, no commentary, no markdown fences, no trailing commas:',
+    WORLD_SHAPE,
+    '',
+    'RULES',
+    '- "nations": 3 to 8 nations, each with a short stable id, a human name, a type, and four 0-100 stats (military, economy, stability, population).',
+    codes
+      ? '- Each nation\'s "territory" MUST use ONLY ISO 3166-1 alpha-3 country codes from this list: ' +
+        codes.join(', ') +
+        '. A nation may control several codes; together the nations should cover a plausible portion of the world.'
+      : '- Each nation\'s "territory" uses standard ISO 3166-1 alpha-3 country codes (e.g. FRA, RUS, USA).',
+    '- "relations": a nation\'s sentiment toward each other nation, an integer from -100 (warring) to +100 (allied). Omit or set 0 for neutrality.',
+    '- "events" (optional): 1 to 4 short backstory events that already happened and set up the current tensions; each names one of the nations above.',
+    '- "checkpoints": 3 to 6 short strings — the advisor\'s opening briefing of the world\'s live strategic questions (the pressures, rivalries, and opportunities the player should know before leading a nation). Keep each under 20 words.',
+    '- Keep every stat value between 0 and 100. Do not invent nations outside the "nations" array.',
+  ].join('\n');
+  const user = JSON.stringify(
+    {
+      era: {
+        id: template.id,
+        name: template.name,
+        year,
+        description: template.eraDescription,
+      },
+      suggestedPowers: template.suggestedPowers,
+      tensions: template.tensions,
+      description,
+      year,
+      ...(codes ? { validCountryCodes: codes } : {}),
+    },
+    null,
+    2,
+  );
+  return { system, user };
+}
+
+/**
+ * The system prompt for step 2 (regenerate/finalize). Same world contract, but
+ * the model must now respect the player's APPROVED checkpoints (and, when a
+ * draft is supplied, stay close to it so the player's chosen nation survives).
+ */
+export function buildRegeneratePrompt(
+  template: EraTemplate,
+  description: string,
+  year: number,
+  approvedCheckpoints: string[],
+  validCountryCodes: ReadonlySet<string> | undefined,
+  draft?: WorldDraft,
+): { system: string; user: string } {
+  const codes = validCountryCodes ? [...validCountryCodes].sort() : null;
+  const system = [
+    `${SCENARIO_REGENERATE_MARKER} You are finalizing a world for an alternate-history strategy game.`,
+    'A draft world was generated and the player has APPROVED a set of checkpoints that the final world MUST respect. Produce the final, playable world.',
+    'Respond with ONLY a valid JSON object of exactly this shape (same as the draft, but the "checkpoints" field is NOT repeated — omit it). No prose, no commentary, no markdown fences, no trailing commas:',
+    [
+      '{',
+      '  "world": {',
+      '    "nations": [',
+      '      {',
+      '        "id": "short-stable-id",',
+      '        "name": "Human readable name",',
+      '        "type": "major|minor|power|alliance|faction",',
+      '        "stats": {"military":0-100,"economy":0-100,"stability":0-100,"population":0-100},',
+      '        "territory": ["ISO_A3","ISO_A3"],',
+      '        "relations": {"<other nation id or name>": -100..100}',
+      '      }',
+      '    ],',
+      '    "events": [',
+      '      {"nation":"<id or name>","type":"<military|diplomatic|economic|political|social|disaster|scientific|cultural>","title":"short headline","text":"1-3 sentences","outcome":"<success|failure|partial|neutral>"}',
+      '    ]',
+      '  }',
+      '}',
+    ].join('\n'),
+    '',
+    'RULES',
+    '- Base the final world on the provided draft (the "draft" field of the user message) and keep the same nations — do not rename, drop, or invent nations beyond what the draft established, UNLESS an approved checkpoint demands it.',
+    '- You MUST respect EVERY approved checkpoint (the "approvedCheckpoints" field of the user message): reflect each one in the nations\' stats, borders, relations, or backstory events.',
+    codes
+      ? '- Each nation\'s "territory" MUST use ONLY ISO 3166-1 alpha-3 country codes from this list: ' +
+        codes.join(', ') +
+        '.'
+      : '- Each nation\'s "territory" uses standard ISO 3166-1 alpha-3 country codes (e.g. FRA, RUS, USA).',
+    '- Keep every stat value between 0 and 100.',
+  ].join('\n');
+  const user = JSON.stringify(
+    {
+      era: {
+        id: template.id,
+        name: template.name,
+        year,
+        description: template.eraDescription,
+      },
+      description,
+      year,
+      approvedCheckpoints,
+      ...(draft ? { draft } : {}),
+      ...(codes ? { validCountryCodes: codes } : {}),
+    },
+    null,
+    2,
+  );
+  return { system, user };
+}
+
+// --- Parsing the model's answers ----------------------------------------------
+
+/** Parse the step-1 (generate) answer into a validated world + checkpoint list. */
+export function parseGenerate(
+  raw: string,
+  validCountryCodes?: ReadonlySet<string>,
+): { world: WorldDraft | null; checkpoints: string[] } {
+  const obj = parseObject(raw);
+  if (!obj) return { world: null, checkpoints: [] };
+  const world = validateWorldDraft(obj.world, { validCountryCodes });
+  const checkpoints: string[] = [];
+  if (Array.isArray(obj.checkpoints)) {
+    const seen = new Set<string>();
+    for (const c of obj.checkpoints) {
+      if (typeof c !== 'string') continue;
+      const t = c.trim();
+      if (t.length > 2 && !seen.has(t)) {
+        seen.add(t);
+        checkpoints.push(t);
+      }
+    }
+  }
+  return { world, checkpoints: checkpoints.slice(0, 12) };
+}
+
+/** Parse the step-2 (finalize) answer into a validated world (or null). */
+export function parseRegenerate(
+  raw: string,
+  validCountryCodes?: ReadonlySet<string>,
+): WorldDraft | null {
+  const obj = parseObject(raw);
+  if (!obj) return null;
+  return validateWorldDraft(obj.world, { validCountryCodes });
+}
+
+// --- Orchestration -------------------------------------------------------------
+
+export interface GenerateDraftOptions {
+  llm: LlmClient;
+  template: EraTemplate;
+  description: string;
+  year: number;
+  /** ISO_A3 codes to accept (undefined = no filtering). */
+  validCountryCodes?: ReadonlySet<string>;
+}
+
+/**
+ * Step 1: ask the model to design a draft world + an advisor checkpoint list.
+ * Throws only on a transport-level failure (the model is down) — a bad answer
+ * yields `{ world: null, checkpoints: [] }` and is the caller's to surface as
+ * an error, never a crash.
+ */
+export async function generateDraft(
+  opts: GenerateDraftOptions,
+): Promise<{ world: WorldDraft | null; checkpoints: string[] }> {
+  const { llm, template, description, year, validCountryCodes } = opts;
+  const { system, user } = buildGeneratePrompt(template, description, year, validCountryCodes);
+  const nudge =
+    'Your previous output was invalid. Respond with ONLY the JSON object described above — no prose, no fences.';
+  const out = await llm.chat(
+    [{ role: 'system', content: system }, { role: 'user', content: user }],
+    { temperature: 0.7, maxTokens: DEFAULT_MAX_TOKENS },
+  );
+  const parsed = parseGenerate(out, validCountryCodes);
+  if (parsed.world) return parsed;
+  // One nudge re-send with a fresh history, mirroring the engine's retry.
+  const retry = await llm.chat(
+    [
+      { role: 'system', content: system },
+      { role: 'user', content: user },
+      { role: 'assistant', content: '' },
+      { role: 'user', content: nudge },
+    ],
+    { temperature: 0.7, maxTokens: DEFAULT_MAX_TOKENS },
+  );
+  return parseGenerate(retry, validCountryCodes);
+}
+
+export interface FinalizeWorldOptions {
+  llm: LlmClient;
+  template: EraTemplate;
+  description: string;
+  year: number;
+  approvedCheckpoints: string[];
+  /** The step-1 draft (re-sent by the client) — the base the final world refines. */
+  draft?: WorldDraft;
+  /** The nation id the player will lead (kept in the final world when present). */
+  playerNationId: string;
+  /** ISO_A3 codes to accept (undefined = no filtering). */
+  validCountryCodes?: ReadonlySet<string>;
+  /** Expand ISO_A3 territory to sub-region keys (injected from server/regions). */
+  expand: (countries: string[]) => string[];
+  /** The new game's id (the route sets randomUUID()). */
+  id?: string;
+  /** The scenario title (becomes presetTitle; default 'Custom World'). */
+  title?: string;
+  /** The game's start date (YYYY-MM-DD, from the chosen year). */
+  startDate?: string;
+}
+
+/**
+ * Step 2: ask the model to produce the final world constrained to the approved
+ * checkpoints, convert it to a playable {@link GameState}, and return it for the
+ * caller to persist. Throws only on a transport-level failure; a bad answer
+ * that still yields a usable world is committed, and if the final world drops
+ * the player's chosen nation the conversion falls back to the first nation so
+ * the game is always playable.
+ */
+export async function finalizeWorld(opts: FinalizeWorldOptions): Promise<GameState> {
+  const {
+    llm,
+    template,
+    description,
+    year,
+    approvedCheckpoints,
+    draft,
+    playerNationId,
+    validCountryCodes,
+    expand,
+    id,
+    title,
+    startDate,
+  } = opts;
+  const { system, user } = buildRegeneratePrompt(
+    template,
+    description,
+    year,
+    approvedCheckpoints,
+    validCountryCodes,
+    draft,
+  );
+  const nudge =
+    'Your previous output was invalid. Respond with ONLY the JSON object described above — no prose, no fences.';
+  const out = await llm.chat(
+    [{ role: 'system', content: system }, { role: 'user', content: user }],
+    { temperature: 0.4, maxTokens: DEFAULT_MAX_TOKENS },
+  );
+  let world = parseRegenerate(out, validCountryCodes);
+  if (!world) {
+    const retry = await llm.chat(
+      [
+        { role: 'system', content: system },
+        { role: 'user', content: user },
+        { role: 'assistant', content: '' },
+        { role: 'user', content: nudge },
+      ],
+      { temperature: 0.4, maxTokens: DEFAULT_MAX_TOKENS },
+    );
+    world = parseRegenerate(retry, validCountryCodes);
+  }
+  if (!world) {
+    // The model could not produce a usable final world. Rather than fail the
+    // whole commit, fall back to the draft the player already approved (if any)
+    // so the commit still yields a playable game.
+    if (draft) world = draft;
+    else throw new Error('finalize: the model returned no usable world');
+  }
+  return worldDraftToGameState(world, expand, playerNationId, { id, title, startDate });
+}

server/stub.ts

@@ -3,7 +3,7 @@
 // speaks the OpenAI chat-completions wire shape, so it plugs in as a Transport.
 import { createLlmClient, type ChatMessage, type Transport } from './llm';
 import { addDays, clampStat, type TerritoryChange, type TurnEventSpec, type TurnResult } from '../shared/protocol';
-import type { RoundItem } from '../shared/types';
+import type { RelationStatus, RoundItem } from '../shared/types';
 
 export const ADVISOR_MARKER = '<<ADVISOR>>';
 
@@ -31,6 +31,42 @@ export interface StubPayload {
    * is covered by unit tests against applyTurnResult, not by the stub.
    */
   unowned?: string[];
+  /**
+   * (v0.27, #44) Current map markers (`{ id, type, name, regionKey, owner }`),
+   * emitted by the engine's user prompt. The stub ignores this field — it
+   * never places or removes a marker (see deterministicTurn), so the marker
+   * path is covered by unit tests against applyTurnResult, not by the stub.
+   */
+  markers?: Array<{ id: string; type: string; name: string; regionKey: string; owner: string | null }>;
+  /**
+   * (v0.33.0, #56) Currently ACTIVE wars (`{ id, sides, aims? }`), emitted by
+   * the engine's user prompt. The stub ignores this field — it never declares
+   * or ends a war (see deterministicTurn), so the war path is covered by unit
+   * tests against applyTurnResult, not by the stub.
+   */
+  wars?: Array<{ id: string; sides: string[]; aims?: string[] }>;
+  /**
+   * (v0.34.0, #57) The player's current relations to every other nation
+   * (`nationId -> RelationStatus`), emitted by the engine's user prompt. The
+   * stub ignores this field — it never runs a hybrid op (see
+   * deterministicTurn), so the hybrid path is covered by unit tests only.
+   */
+  relations?: Record<string, RelationStatus>;
+  /**
+   * (v0.35.0, #58) The currently active bilateral trade agreements
+   * (`{ a, b }` nation-id pairs), emitted by the engine's user prompt. The
+   * stub ignores this field — it never declares, lifts or suspends a trade
+   * (see deterministicTurn), so the trade path is covered by unit tests only.
+   */
+  trades?: Array<{ a: string; b: string }>;
+  /**
+   * (v0.35.0, #58) The currently active unilateral embargoes
+   * (`{ from, target }` nation-id pairs), emitted by the engine's user
+   * prompt. The stub ignores this field — it never imposes, lifts or
+   * suspends an embargo (see deterministicTurn), so the embargo path is
+   * covered by unit tests only.
+   */
+  embargoes?: Array<{ from: string; target: string }>;
 }
 
 function truncate(s: string, n: number): string {
@@ -57,6 +93,36 @@ function truncate(s: string, n: number): string {
  * always returns `unowned: []`) — e2e assertions rely on its fully-deterministic
  * one-conquest behavior, so the release/re-claim path is exercised by unit
  * tests only (see server/engine.test.ts).
+ *
+ * (v0.23, #16 P4a) The stub likewise NEVER proposes nation-management ops (it
+ * always returns `nationOps: []`) — the propose→confirm/reject flow is
+ * covered by unit tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.27, #44) The stub likewise NEVER places or removes a map marker (it
+ * always returns `markers: { add: [], remove: [] }`) — the marker path is
+ * covered by unit tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.29, #46 PR 2) The stub likewise NEVER changes per-region stats (it
+ * always returns `regionChanges: []`) — the per-region lever is covered by
+ * unit tests only (see server/engine.test.ts), keeping the e2e assertions
+ * untouched.
+ *
+ * (v0.32.0, #54) The stub likewise NEVER performs a non-military takeover
+ * (it always returns `takeovers: []`) — the regime-rename path is covered by
+ * unit tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.33.0, #56) The stub likewise NEVER declares or ends a war (it always
+ * returns `wars: { declare: [], end: [] }`) — the war path is covered by unit
+ * tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.34.0, #57) The stub likewise NEVER runs a hybrid / covert op (it always
+ * returns `hybrid: { ops: [] }`) — the hybrid-war path is covered by unit
+ * tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.35.0, #58) The stub likewise NEVER declares, lifts or suspends a trade
+ * or an embargo (it always returns `economy: { trade: [], embargo: [] }`) —
+ * the trade & embargo economy path is covered by unit tests only, keeping
+ * the e2e assertions untouched.
  */
 export function deterministicTurn(p: StubPayload): TurnResult {
   const state = p.state;
@@ -118,9 +184,16 @@ export function deterministicTurn(p: StubPayload): TurnResult {
     date: addDays(state?.date ?? '1939-09-01', 2),
     events,
     stateChanges: [{ nation: pid, stat: 'military', op: 'set', value: mil }],
+    regionChanges: [], // the stub never changes per-region stats (see doc comment)
     relations: otherId ? [{ a: pid, b: otherId, set: 'ally' }] : [],
     territoryChanges,
     unowned: [], // the stub never creates no man's land (see doc comment)
+    nationOps: [], // the stub never proposes nation ops (see doc comment)
+    takeovers: [], // the stub never performs a takeover (see doc comment)
+    wars: { declare: [], end: [] }, // the stub never declares/ends wars (see doc comment)
+    hybrid: { ops: [] }, // the stub never runs hybrid/covert ops (see doc comment)
+    economy: { trade: [], embargo: [] }, // the stub never touches trades/embargoes (see doc comment)
+    markers: { add: [], remove: [] }, // the stub never touches markers (see doc comment)
   };
 }
 

server/stubScenario.ts

@@ -0,0 +1,122 @@
+// Deterministic SCENARIO-generation stub (v0.31, #52).
+//
+// Distinct from the turn stub (server/stub.ts, which stays untouched): this one
+// answers the two scenario-generation LLM calls (see server/scenario.ts) so the
+// whole "Create scenario" path is reproducible under LLM_STUB=1 (unit tests and
+// the Playwright e2e). It speaks the OpenAI chat-completions wire shape, so it
+// plugs in as a Transport, and it discriminates the two calls by the markers
+// scenario.ts embeds in each system message (SCENARIO_GENERATE_MARKER for the
+// draft step, SCENARIO_REGENERATE_MARKER for the finalize step) — mirroring how
+// the turn stub discriminates the advisor call via ADVISOR_MARKER.
+//
+// The stub returns a fixed 3-nation world and a fixed checkpoint list for the
+// generate step, and — for the finalize step — the same world refined in a
+// simple, deterministic way that depends on the approved checkpoints, so the
+// "finalize respects approved checkpoints" behavior is observable end to end.
+import { createLlmClient, type ChatMessage, type LlmClient, type Transport } from './llm';
+import { SCENARIO_REGENERATE_MARKER } from './scenario';
+import type { WorldDraft } from '../shared/scenario';
+
+/** A small fixed 3-nation world (ISO_A3 territory — FRA / RUS / ESP). */
+const WORLD: WorldDraft = {
+  nations: [
+    {
+      id: 'alba',
+      name: 'Alba',
+      type: 'major',
+      stats: { military: 70, economy: 60, stability: 65, population: 55 },
+      territory: ['FRA'],
+      relations: { boreas: -60, gamma: 20 },
+    },
+    {
+      id: 'boreas',
+      name: 'Boreas',
+      type: 'major',
+      stats: { military: 55, economy: 70, stability: 50, population: 60 },
+      territory: ['RUS'],
+      relations: { alba: -60, gamma: 10 },
+    },
+    {
+      id: 'gamma',
+      name: 'Gamma',
+      type: 'minor',
+      stats: { military: 30, economy: 45, stability: 70, population: 40 },
+      territory: ['ESP'],
+      relations: { alba: 20, boreas: 10 },
+    },
+  ],
+  events: [
+    {
+      nation: 'alba',
+      type: 'political',
+      title: 'The new order takes shape',
+      text: 'The three powers settle their borders after the great realignment.',
+      outcome: 'neutral',
+    },
+  ],
+};
+
+/** The advisor's opening checkpoint list (fixed, in order). */
+const CHECKPOINTS: string[] = [
+  'Alba dominates the western sea lanes and presses its advantage.',
+  'Boreas fortifies its northern frontier against a long winter.',
+  'Gamma brokers a neutral corridor between the two rivals.',
+];
+
+/**
+ * Deterministically refine the fixed world to "respect" the approved
+ * checkpoints: each approved checkpoint that names one of the fixed nations (by
+ * the first 4 letters of the nation's name, case-insensitive) raises that
+ * nation's stability by 5 (clamped at 100). Same input → same output, and the
+ * result visibly depends on which checkpoints were approved.
+ */
+export function stubWorldFor(approved: string[]): WorldDraft {
+  const nations = WORLD.nations.map((n) => ({
+    ...n,
+    stats: { ...n.stats },
+    relations: { ...n.relations },
+  }));
+  const lower = approved.map((c) => c.toLowerCase());
+  for (const n of nations) {
+    const key = n.name.toLowerCase().slice(0, 4);
+    if (lower.some((c) => c.includes(key))) {
+      n.stats.stability = Math.min(100, n.stats.stability + 5);
+    }
+  }
+  return { nations, events: WORLD.events };
+}
+
+export function makeScenarioStubTransport(): Transport {
+  return async (_url, init) => {
+    let content: string;
+    try {
+      const req = JSON.parse(String(init?.body ?? '{}')) as { messages?: ChatMessage[] };
+      const sys = req.messages?.find((m) => m.role === 'system')?.content ?? '';
+      const user = req.messages?.find((m) => m.role === 'user');
+      if (sys.includes(SCENARIO_REGENERATE_MARKER)) {
+        // Finalize step: read the approved checkpoints out of the user payload
+        // and refine the fixed world accordingly (no checkpoints field echoed).
+        const payload = JSON.parse(user?.content ?? '{}') as {
+          approvedCheckpoints?: string[];
+        };
+        content = JSON.stringify({ world: stubWorldFor(payload.approvedCheckpoints ?? []) });
+      } else {
+        // Generate step (and any unrecognized prompt): the fixed world + list.
+        content = JSON.stringify({ world: WORLD, checkpoints: CHECKPOINTS });
+      }
+    } catch {
+      content = JSON.stringify({ world: WORLD, checkpoints: CHECKPOINTS });
+    }
+    return {
+      ok: true,
+      status: 200,
+      json: async () => ({ choices: [{ message: { content } }] }),
+      text: async () => content,
+    } as unknown as Response;
+  };
+}
+
+/** A ready-made LlmClient backed by the deterministic scenario transport. */
+export function makeScenarioStubLlmClient(): LlmClient {
+  return createLlmClient({ transport: makeScenarioStubTransport() });
+}

server/templates.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createTemplateStore } from './templates';
+
+// The project root is the parent of server/ (mirrors how server/index.ts and
+// server/regions.test.ts locate it via import.meta.url).
+const root = fileURLToPath(new URL('..', import.meta.url));
+const templatesDir = path.join(root, 'presets', 'templates');
+
+const store = createTemplateStore(templatesDir);
+
+/** A well-formed ISO_A3 country code: exactly three uppercase letters. */
+function isIsoA3(code: string): boolean {
+  return /^[A-Z]{3}$/.test(code);
+}
+
+describe('era templates store (v0.31.0, #52)', () => {
+  it('the manifest lists exactly the three era templates', () => {
+    const meta = store.listMeta();
+    expect(meta).toHaveLength(3);
+    const ids = meta.map((m) => m.id);
+    expect(ids).toEqual(['ww2', 'present', 'near-future']);
+    for (const m of meta) {
+      expect(m.id).toBeTruthy();
+      expect(m.name).toBeTruthy();
+      expect(typeof m.year).toBe('number');
+      expect(m.eraDescription).toBeTruthy();
+    }
+  });
+
+  it('each template file loads and is well-formed', () => {
+    for (const m of store.listMeta()) {
+      const t = store.get(m.id);
+      expect(t, `template ${m.id} should load`).not.toBeNull();
+      const tpl = t as NonNullable<typeof t>;
+      expect(tpl.id).toBe(m.id);
+      expect(tpl.name).toBe(m.name);
+      expect(tpl.year).toBe(m.year);
+      expect(tpl.eraDescription).toBeTruthy();
+      // suggested powers: non-empty, each a named power with an ISO_A3 core region + note.
+      expect(tpl.suggestedPowers.length).toBeGreaterThan(0);
+      for (const p of tpl.suggestedPowers) {
+        expect(p.name).toBeTruthy();
+        expect(isIsoA3(p.region)).toBe(true);
+        expect(p.note).toBeTruthy();
+      }
+      // tensions: a non-empty list of non-empty strings.
+      expect(tpl.tensions.length).toBeGreaterThan(0);
+      for (const s of tpl.tensions) expect(typeof s).toBe('string');
+      for (const s of tpl.tensions) expect(s.trim()).not.toBe('');
+    }
+  });
+
+  it('get returns null for an unknown id', () => {
+    expect(store.get('does-not-exist')).toBeNull();
+    expect(store.get('')).toBeNull();
+  });
+});

server/templates.ts

@@ -0,0 +1,28 @@
+// Load era templates for the "Create scenario" path from disk (v0.31.0, #52).
+// Mirrors the preset store (server/presets.ts): each template is a JSON file
+// (presets/templates/<id>.json) and index.json is the lightweight manifest used
+// to render the picker cards. The store is created with the resolved templates
+// directory so it works from repo root (dev) and /app (Docker) alike.
+import { readFileSync } from 'node:fs';
+import type { EraTemplate, TemplateMeta } from '../shared/scenario';
+
+export interface TemplateStore {
+  listMeta(): TemplateMeta[];
+  get(id: string): EraTemplate | null;
+}
+
+export function createTemplateStore(dir: string): TemplateStore {
+  const manifest = JSON.parse(readFileSync(`${dir}/index.json`, 'utf8')) as TemplateMeta[];
+  return {
+    listMeta() {
+      return manifest;
+    },
+    get(id: string) {
+      try {
+        return JSON.parse(readFileSync(`${dir}/${id}.json`, 'utf8')) as EraTemplate;
+      } catch {
+        return null;
+      }
+    },
+  };
+}

shared/protocol.ts

@@ -6,16 +6,37 @@ import type {
   EventOutcome,
   EventType,
   GameState,
+  MarkerType,
   Nation,
+  NationStats,
   RelationStatus,
+  RegionStats,
   StatKey,
 } from './types';
+import { MARKER_TYPES, STAT_KEYS } from './types';
 
 /** A numeric change to one of a nation's 0–100 stats. */
 export type StateChange =
   | { nation: string; stat: StatKey; op: 'set'; value: number }
   | { nation: string; stat: StatKey; op: 'add'; value: number };
 
+/**
+ * (v0.29, #46 PR 2) A numeric change to one of **one region's** 0–100 stats —
+ * the fine-grained, per-region lever that complements the nation-wide
+ * {@link StateChange}. `region` names the target by its **region key**
+ * (preferred) or its human-readable **name** (the engine resolves it
+ * case-insensitively, mirroring `resolveNationRef`); after validation it holds
+ * the resolved **region key**. `op` is `set` (replace the value) or `add`
+ * (delta, clamped to 0–100 by the engine).
+ */
+export type RegionStatChange = {
+  /** The target region's key (preferred) or name (resolved by the engine). */
+  region: string;
+  stat: StatKey;
+  op: 'set' | 'add';
+  value: number;
+};
+
 /** Set the bilateral relation between nations `a` and `b` to `set` (symmetric). */
 export interface RelationChange {
   a: string;
@@ -30,6 +51,144 @@ export interface TerritoryChange {
   lose: string[];
 }
 
+// --- Wars (v0.33.0, #56): first-class war entities --------------------------
+//
+// A war is an explicit world entity (see types.War), not just a boolean
+// relation: the LLM DECLARES one (it becomes an active War with an engine-
+// assigned stable id) and later ENDS one by id. The engine derives the
+// symmetric `war` relation from the set of ACTIVE wars on every turn (two
+// nations are in a `war` relation iff they are both belligerents of at least
+// one active war) and downgrades it to `hostile` when the war ends — so the
+// relation can never drift apart from the war state.
+
+/**
+ * (v0.33.0, #56) Declare a new war this turn. `sides` names every
+ * belligerent (≥2 distinct nation ids — each resolved by `resolveNationRef`,
+ * so a unique name also works); any two distinct sides end the turn in a
+ * `war` relation. `aims` are optional short war aims for the narrative. The
+ * engine assigns the stable id, the declared turn/date, drags in the
+ * mutual-defense allies of each belligerent, and drops the op when fewer than
+ * two sides resolve (never throws).
+ */
+export interface WarDeclareOp {
+  /** The belligerent nations (≥2 distinct ids or unique names). */
+  sides: string[];
+  /** Optional short war aims (narrative only). */
+  aims?: string[];
+}
+
+/**
+ * (v0.33.0, #56) End an existing ACTIVE war this turn, by its stable id
+ * (the model sees the current active wars in the user payload's `wars`
+ * field). `outcome` is `armistice` (a negotiated stop) or `capitulation`
+ * (one side surrenders); the war keeps its id/sides and stays in
+ * `GameState.wars` as history with that final status. `terms` are optional
+ * short peace terms (narrative only — the model narrates the details in
+ * `events`). An unknown id, or a war that is already ended, is a no-op
+ * (never throws).
+ */
+export interface WarEndOp {
+  /** The stable id of the active war to end (from the user payload). */
+  id: string;
+  outcome: 'armistice' | 'capitulation';
+  /** Optional short peace terms (narrative only). */
+  terms?: string;
+}
+
+// --- Nation-management ops (v0.23 P4a / v0.24 P4b, #16: the hybrid "LLM
+// proposes, player confirms" model) ------------------------------------------
+//
+// Unlike stat / relation / territory deltas, a NationOp proposed in a turn is
+// NOT applied by that turn. It is stored as a *pending proposal* in
+// `GameState.pendingNationOps` and only takes effect when the player confirms
+// it (optionally editing it) or is dropped when the player rejects it. All
+// three kinds are implemented: rename (v0.23 P4a), split and merge (v0.24 P4b).
+
+/**
+ * The identity reference a nation is addressed by inside a {@link NationOp}.
+ * The LLM may use either the nation's stable `id` (the `nations` record key,
+ * e.g. `f`) or its human-readable `name` (e.g. `France`); the engine resolves
+ * it to a concrete `nationId` (id first, then a unique name match — see the
+ * engine's `resolveNationRef`).
+ */
+
+/**
+ * (v0.32.0, #54) A **non-military regime change** — a coup or revolution that
+ * renames a nation to the name of the new regime. Unlike a {@link RenameOp}
+ * (a player-confirmed diplomatic/political name change), a takeover is
+ * **automatic and in-world**: `applyTurnResult` applies it directly (no
+ * pending queue, no player confirm). Only `Nation.name` changes — the stable
+ * `id`, territory, relations (keyed by id), stats, and `playerNationId`
+ * (which references the id) all stay intact, so the player keeps leading the
+ * nation under its new regime. `nationRef` is resolved exactly like the
+ * `nationRef` of a NationOp (id first, then a case-insensitive unique name
+ * match — see `resolveNationRef`).
+ */
+export interface Takeover {
+  /** The target nation's id or current name (resolved by `resolveNationRef`). */
+  nationRef: string;
+  /** The name of the new regime to set as the nation's display name. */
+  newRegimeName: string;
+}
+
+/**
+ * A **rename** proposal: change a nation's human-readable `name`. Only the
+ * `name` changes — the stable `id`, its territory keys, its relations (keyed
+ * by id), and the player pointer are all left untouched, so nothing downstream
+ * breaks. `to` is the new display name.
+ */
+export interface RenameOp {
+  kind: 'rename';
+  /** The target nation's id or current name (see the note above). */
+  nationRef: string;
+  /** The new display name to apply when the player confirms. */
+  to: string;
+}
+
+/**
+ * A **split** proposal (v0.24, #16 P4b). Describes the new nations a source
+ * nation is divided into. On confirm the source is dissolved: each part gets a
+ * fresh id, the region keys it was given (restricted to keys the source
+ * actually owns — first claim wins), fresh baseline stats, and a copy of the
+ * source's relations; any of the source's unclaimed keys go to `parts[0]`.
+ * When the source is the player's own nation the player chooses which part
+ * they lead (the confirm request's `edits.playerPart`, default `parts[0]`).
+ */
+export interface SplitOp {
+  kind: 'split';
+  /** The id/name of the nation being split. */
+  nationRef: string;
+  /** The new nations created from the split. */
+  parts: Array<{ name: string; territory?: string[] }>;
+}
+
+/**
+ * A **merge** proposal (v0.24, #16 P4b). Folds several nations into a single
+ * surviving nation. On confirm the survivor keeps its id (renamed to `into`,
+ * or to the confirm request's `edits.name`), its territory becomes the union
+ * of all inputs' territories, it keeps its own stats, and it inherits the
+ * union of all inputs' relations (its own winning per third party, else the
+ * first input's); every non-survivor input is removed. If the player's nation
+ * was a non-survivor input the player pointer is re-pointed to the survivor.
+ */
+export interface MergeOp {
+  kind: 'merge';
+  /** The id/name of every nation folded into the result. */
+  nationRefs: string[];
+  /** The id/name of the nation that survives and keeps its identity. */
+  survivingRef: string;
+  /** The name to give the merged nation. */
+  into: string;
+}
+
+/**
+ * A structural operation on the set of nations that the LLM may propose in a
+ * turn (`TurnResult.nationOps`). See the section comment above for the hybrid
+ * propose→confirm semantics. All three kinds are implemented: rename (P4a),
+ * and split / merge (P4b, v0.24).
+ */
+export type NationOp = RenameOp | SplitOp | MergeOp;
+
 /** One narrative event the LLM proposes for this turn. */
 export interface TurnEventSpec {
   nation: string;
@@ -39,11 +198,240 @@ export interface TurnEventSpec {
   outcome: EventOutcome;
 }
 
+// --- Map markers (v0.27, #44) -------------------------------------------------
+//
+// The LLM places named point markers (cities, factories, armies, ports,
+// capitals, fleets, rocket launch sites, gatherings) anchored to a region
+// key. It never sees or sets coordinates: the engine derives the position
+// from the region's precomputed centroid (public/region-centroids.json) plus a
+// small deterministic offset, and it recomputes each marker's owner from the
+// region's current owner on every turn (a released region → null).
+//
+// The marker id is a STABLE, deterministic 4-letter code (FNV-1a 32-bit →
+// base 26, the same scheme as the region keys' 4-char suffix) derived from
+// (type, name, regionKey) — so re-adding an identical marker is idempotent
+// (same id, skipped) and removing by id is unambiguous.
+
+/** The spec the LLM emits to place a marker: type, name and the region it sits in. */
+export interface MarkerSpec {
+  type: MarkerType;
+  name: string;
+  regionKey: string;
+}
+
+/**
+ * One existing marker as the user prompt presents it to the model (v0.27,
+ * #44): its stable `id` (the model may echo it in `TurnResult.markers.remove`),
+ * type, name, region key, and the id of the nation currently owning its
+ * region (`null` when the region is unowned / no man's land).
+ */
+export interface MarkerInfo {
+  id: string;
+  type: MarkerType;
+  name: string;
+  regionKey: string;
+  owner: string | null;
+}
+
+/**
+ * (v0.33.0, #56) One ACTIVE war as the user prompt presents it to the model
+ * (the `wars` field): its stable `id` (the model echoes it in
+ * `TurnResult.wars.end` to end it), its belligerent `sides`, and optional
+ * short `aims`. Ended wars are NOT included — they stay in `GameState.wars`
+ * as history, but the model only needs to address the active ones.
+ */
+export interface WarInfo {
+  id: string;
+  sides: string[];
+  aims?: string[];
+}
+
+/**
+ * The per-type presentation of a marker: its display label (tooltip /
+ * dossier), its color, and its glyph character (a symbol-layer text label —
+ * a small, font-safe character in front of the name). Pure + shared so the
+ * client's marker layer and any server-side consumers agree on the look.
+ */
+export const MARKER_TYPE_INFO: Record<MarkerType, { label: string; color: string; glyph: string }> = {
+  city: { label: 'City', color: '#cbd5e1', glyph: '●' },
+  factory: { label: 'Factory', color: '#fb923c', glyph: '■' },
+  army: { label: 'Army', color: '#ef4444', glyph: '▲' },
+  port: { label: 'Port', color: '#38bdf8', glyph: '◆' },
+  capital: { label: 'Capital', color: '#fbbf24', glyph: '★' },
+  fleet: { label: 'Fleet', color: '#22d3ee', glyph: '◗' },
+  rocket: { label: 'Rocket site', color: '#a78bfa', glyph: '↥' },
+  gathering: { label: 'Gathering', color: '#4ade80', glyph: '◉' },
+};
+
+/** Hard cap on a game's total markers (new adds beyond the cap are dropped, v0.27 #44). */
+export const MAX_MARKERS = 400;
+
+/**
+ * FNV-1a 32-bit — the same tiny, stable, pure string hash the region keys use
+ * (see scripts/build-region-keys.mjs). Exported so the engine can derive
+ * deterministic per-axis jitter fractions from it (marker placement, v0.27 #44).
+ */
+export function fnv1a32(str: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h >>> 0;
+}
+
+/** Spread a 32-bit hash across four lowercase letters (base 26 per byte). */
+function code4(h: number): string {
+  let out = '';
+  for (let i = 0; i < 4; i++) {
+    out += String.fromCharCode(97 + (((h >>> (i * 8)) & 0xff) % 26));
+  }
+  return out;
+}
+
+/**
+ * The stable id for a marker: 4 base-26 lowercase chars from the FNV-1a hash
+ * of `(type, name, regionKey)` (NUL-separated so no field boundary is
+ * ambiguous). Deterministic across runs and platforms (pure string math), so
+ * the same (type, name, regionKey) always maps to the same id — re-adding is
+ * idempotent, removing by id is unambiguous.
+ */
+export function markerId(type: MarkerType, name: string, regionKey: string): string {
+  return code4(fnv1a32(`${type}\u0000${name}\u0000${regionKey}`));
+}
+
+/** True when `t` is one of the eight known marker types (v0.27, #44). */
+export function isMarkerType(t: unknown): t is MarkerType {
+  return typeof t === 'string' && (MARKER_TYPES as string[]).includes(t);
+}
+
+// --- Hybrid war (v0.34.0, #57): non-kinetic operations ---------------------
+//
+// The LLM can run covert, non-kinetic operations each turn: spies, sabotage,
+// assassination attempts, cyberattacks, economic pressure, disinformation, and
+// proxy support. Unlike kinetic conquest (territory), these never move borders
+// — they dip a target's stats or sour a relation. The LLM declares an intended
+// outcome (`success` or `exposed`); the engine is fully deterministic (no
+// hidden randomness) and acts only on that declaration: a successful op applies
+// its small, per-type effect, and an "exposed" op backfires (no effect, the
+// actor's relation with the target sours by one step, and an auto
+// diplomatic/failure event is emitted).
+
+/** The seven covert operation types a hybrid op can be (v0.34.0, #57). */
+export type HybridOpType =
+  | 'spy'
+  | 'sabotage'
+  | 'assassinate'
+  | 'cyber'
+  | 'economic'
+  | 'information'
+  | 'proxy';
+
+/** All hybrid op types, in canonical order (the LLM contract + validator). */
+export const HYBRID_OP_TYPES: HybridOpType[] = [
+  'spy',
+  'sabotage',
+  'assassinate',
+  'cyber',
+  'economic',
+  'information',
+  'proxy',
+];
+
+/**
+ * (v0.34.0, #57) One covert (non-kinetic) operation the LLM may run in a turn
+ * (`TurnResult.hybrid.ops`). `from` is the acting nation (its id or a unique
+ * name — resolved by the engine's `resolveNationRef`). `target` is EITHER a
+ * nation (id or unique name) or a specific region key; a region target hits
+ * that region's sole owner (a region with zero or 2+ owners can't be
+ * targeted). `detail` is a short narrative (the LLM may also narrate the op in
+ * `events`). `outcome` is the LLM's *intended* result: `success` (the default)
+ * applies the op's deterministic effect, while `exposed` backfires it — the
+ * effect is NOT applied, the actor's relation with the target sours by one
+ * step, and an auto diplomatic/failure event is emitted.
+ */
+export interface HybridOp {
+  /** The operation type (see {@link HybridOpType}). */
+  type: HybridOpType;
+  /** The acting nation's id or current name (resolved by `resolveNationRef`). */
+  from: string;
+  /** The target: a nation's id/name, or a region key (hits that region's owner). */
+  target: string;
+  /** Short narrative detail (optional). */
+  detail?: string;
+  /** The LLM's intended result; `exposed` backfires the op. Defaults to success. */
+  outcome?: 'success' | 'exposed';
+}
+
+// --- Trade & embargo ops (v0.35.0, #58) --------------------------------------
+
+/**
+ * (v0.35.0, #58) A bilateral TRADE op in `TurnResult.economy.trade`: `a` and
+ * `b` are the two parties (each a nation's id or unique name — resolved by
+ * the engine's `resolveNationRef`; a pair that resolves to the same nation,
+ * or contains an unknown/ambiguous ref, is dropped defensively). Without
+ * `lift` the op DECLARES the agreement (idempotent — an already-active
+ * agreement is not duplicated); `lift: true` ENDS it.
+ */
+export interface EconomyTradeOp {
+  /** First party's id or unique name. */
+  a: string;
+  /** Second party's id or unique name (distinct from `a` after resolution). */
+  b: string;
+  /** `true` → end this bilateral trade; default `false` = declare it. */
+  lift?: boolean;
+}
+
+/**
+ * (v0.35.0, #58) A unilateral EMBARGO op in `TurnResult.economy.embargo`:
+ * `from` blocks trade with `target` (each a nation's id or unique name —
+ * resolved by `resolveNationRef`; an unknown/ambiguous ref or
+ * `from === target` is dropped defensively). Without `lift` the op imposes
+ * the embargo (idempotent — an already-active one is not duplicated);
+ * `lift: true` LIFTS it.
+ */
+export interface EconomyEmbargoOp {
+  /** The imposing nation's id or unique name. */
+  from: string;
+  /** The embargoed nation's id or unique name (distinct from `from`). */
+  target: string;
+  /** `true` → lift this embargo; default `false` = impose it. */
+  lift?: boolean;
+}
+
+/**
+ * (v0.35.0, #58) The turn's trade-and-embargo operations, nested under
+ * `TurnResult.economy`. Both arrays are required and default to `[]`. The
+ * engine applies the ops to `GameState.trades` / `GameState.embargoes`
+ * (add = declare/impose, remove = lift) and, on every committed turn, applies
+ * the per-turn economic effect of the FULL active lists (trade: both
+ * parties' economy up a little; embargo: the target's economy down a
+ * little). Active trades/embargoes between nations on opposite sides of an
+ * active war (v0.33, #56) are suspended (removed) automatically.
+ */
+export interface EconomyOps {
+  /** Bilateral trades (declare or lift). */
+  trade: EconomyTradeOp[];
+  /** Unilateral embargoes (impose or lift). */
+  embargo: EconomyEmbargoOp[];
+}
+
 /** The exact JSON object the world-simulator LLM must return for a turn. */
 export interface TurnResult {
   date: string;
   events: TurnEventSpec[];
   stateChanges: StateChange[];
+  /**
+   * (v0.29, #46 PR 2) Fine-grained, **per-region** stat changes: each targets a
+   * single region's 0–100 stats (by region key or name) and complements the
+   * nation-wide `stateChanges` (which apply to *all* of a nation's regions).
+   * The engine resolves each `region` to a key (key first, then a
+   * case-insensitive unique name match) and applies it to
+   * `GameState.regionStats` only for regions that have an entry (owned); an
+   * unowned / no-man's-land region is a no-op. Empty on turns where the model
+   * changes no individual region. Required (default `[]`).
+   */
+  regionChanges: RegionStatChange[];
   relations: RelationChange[];
   territoryChanges: TerritoryChange[];
   /**
@@ -56,6 +444,78 @@ export interface TurnResult {
    * empty on normal turns.
    */
   unowned: string[];
+  /**
+   * (v0.23 P4a / v0.24 P4b, #16) Nation-management ops the LLM proposes this
+   * turn. These are NOT applied by the turn: each is appended to
+   * `GameState.pendingNationOps` as a proposal awaiting the player's
+   * confirm/reject. All three kinds (rename, split, merge) are implemented —
+   * a confirmed rename changes `Nation.name`; a confirmed split dissolves the
+   * source into its parts; a confirmed merge folds its inputs into the
+   * survivor. Empty on turns where the model proposes none.
+   */
+  nationOps: NationOp[];
+  /**
+   * (v0.32.0, #54) Non-military regime changes (coups / revolutions) that take
+   * effect **this turn** — each renames the target nation to `newRegimeName`.
+   * Unlike `nationOps` (player-confirmed proposals), a takeover is **automatic
+   * and in-world**: it is applied directly by `applyTurnResult` (like territory
+   * / state changes), not queued to `pendingNationOps`. Only the nation's
+   * `name` changes; the id, territory, relations, stats, and `playerNationId`
+   * are all preserved. Empty on turns where no takeover occurs. Required
+   * (default `[]`).
+   */
+  takeovers: Takeover[];
+  /**
+   * (v0.33.0, #56) First-class war ops this turn. `declare` starts new wars
+   * (≥2 distinct belligerents; the engine assigns the stable id / declared
+   * turn / date, drags in the mutual-defense allies of each belligerent, and
+   * derives the `war` relation between every pair of sides); `end` closes an
+   * existing ACTIVE war by id (`armistice` = a negotiated stop,
+   * `capitulation` = one side surrenders), which downgrades the relation the
+   * war had derived back to `hostile`. Both sub-fields are required and
+   * default `[]`; a turn with war activity is meaningful (it survives the
+   * retry/nudge path). The model sees the current active wars (id + sides +
+   * aims) in the user payload's `wars` field, so it can `end` by id.
+   */
+  wars: { declare: WarDeclareOp[]; end: WarEndOp[] };
+  /**
+   * (v0.34.0, #57) Covert, non-kinetic ("hybrid") operations this turn — spies,
+   * sabotage, assassination attempts, cyberattacks, economic pressure,
+   * disinformation, and proxy support. Unlike `nationOps` (player-confirmed
+   * proposals) these are applied directly by the turn, like territory / state
+   * changes: each op's deterministic per-type effect is applied by
+   * `applyTurnResult` (a small stat dip on the target's regions, or a
+   * relation nudge toward hostile for `information` / `proxy`); an `exposed`
+   * op backfires (no effect, the actor's relation with the target sours by
+   * one step, and an auto diplomatic/failure event is emitted). They never
+   * move borders — sole ownership is untouched. Required (default
+   * `{ ops: [] }`).
+   */
+  hybrid: { ops: HybridOp[] };
+  /**
+   * (v0.35.0, #58) Trade and embargo ops — the economy layer. `trade`
+   * declares (or, with `lift: true`, ends) bilateral trade agreements
+   * between two nations; `embargo` imposes (or, with `lift: true`, lifts)
+   * a unilateral embargo on a target. Both arrays are required and default
+   * to `[]`. Applied directly by `applyTurnResult` (add to / remove from
+   * `GameState.trades` / `GameState.embargoes`), and the per-turn economic
+   * effect of the FULL active lists is applied on every committed turn (a
+   * trade lifts both parties' economy a little; an embargo lowers the
+   * target's economy a little — clamped, deterministic). Active
+   * trades/embargoes between nations on opposite sides of an active war are
+   * suspended automatically.
+   */
+  economy: EconomyOps;
+  /**
+   * (v0.27, #44) Map-marker ops this turn. `add` places new named markers
+   * (the engine positions each at its region's centroid + a small
+   * deterministic offset, sets the owner to the region's post-turn owner,
+   * derives the stable id, and drops unknown types/region keys, duplicates,
+   * and adds beyond MAX_MARKERS); `remove` drops markers by their stable id
+   * (a no-op for an id that is not present). Both required, `[]` on turns
+   * with no marker activity.
+   */
+  markers: { add: MarkerSpec[]; remove: string[] };
 }
 
 /** Per-region map payload: region key -> owning nation + its stable color. */
@@ -162,6 +622,39 @@ export interface RemoveQueueItemResponse {
   game: GameState;
 }
 
+/**
+ * (v0.23 P4a / v0.24 P4b, #16) Confirm a pending nation-op proposal by its
+ * index in `game.pendingNationOps`. A rename takes effect (the player may
+ * override the proposed name via `edits.name`); a split and a merge are fully
+ * applied (v0.24 P4b). No LLM call, no turn advance.
+ */
+export interface ConfirmNationOpRequest {
+  index: number;
+  /**
+   * Optional player edits applied on confirm.
+   * - `name`: the final display name — overrides a rename's `to`, a merge's
+   *   `into`, or (for a split) the name of the part the player leads.
+   * - `playerPart`: for a split of the player's own nation, which part (index
+   *   into the op's `parts`) the player will lead (default `0` when missing or
+   *   out of range, so the player is never orphaned).
+   */
+  edits?: { name?: string; playerPart?: number };
+}
+export interface ConfirmNationOpResponse {
+  game: GameState;
+}
+
+/**
+ * (v0.23, #16 P4a) Reject (drop) a pending nation-op proposal by its index
+ * in `game.pendingNationOps` without applying it. No LLM call, no turn advance.
+ */
+export interface RejectNationOpRequest {
+  index: number;
+}
+export interface RejectNationOpResponse {
+  game: GameState;
+}
+
 export interface AdvisorRequest {
   /** Optional prompt to steer the brainstorm. */
   prompt?: string;
@@ -198,6 +691,42 @@ export function nationColor(id: string): string {
   return `hsl(${hue} 58% 46%)`;
 }
 
+// --- Combat: the military hard gate (v0.30, #50) ------------------------------
+//
+// The one rule the engine enforces on the player's behalf instead of trusting
+// the LLM: a contested conquest only succeeds when the attacker is not MORE
+// than `CONQUEST_MILITARY_MARGIN` below the defender. The LLM still proposes
+// the transfer; the engine decides whether it holds (see `applyTurnResult`).
+// Re-claims of unowned / no-man's-land regions are never gated.
+
+/**
+ * (v0.30, #50) The margin of military superiority an attacker must NOT be more
+ * than below the defender for a contested conquest to succeed. A gap of exactly
+ * this many points is still enough to win; a gap one larger is repelled.
+ */
+export const CONQUEST_MILITARY_MARGIN = 15;
+
+/**
+ * (v0.30, #50) Hard military gate for a **contested** conquest (a region
+ * currently owned by a different nation). Returns `true` — the invasion
+ * proceeds — unless the attacker's military is MORE than `margin` below the
+ * defender's: equal, or within `margin` (default {@link CONQUEST_MILITARY_MARGIN}),
+ * is enough to win, while a gap larger than `margin` is repelled.
+ *
+ * The comparison is intentionally one-sided (it only protects the *defender*
+ * from an overwhelming odds gap, not the attacker from a small disadvantage):
+ * `attacker < defender - margin` → repel; everything else (equal, within the
+ * margin, or ahead) → proceed. Pure + shared so the engine, the tests, and the
+ * prompt's frontier-balance hint all agree on the outcome.
+ */
+export function canConquer(
+  attackerMil: number,
+  defenderMil: number,
+  margin: number = CONQUEST_MILITARY_MARGIN,
+): boolean {
+  return !(attackerMil < defenderMil - margin);
+}
+
 // --- No man's land (v0.22, #16 P3) — the map presentation contract ---
 //
 // An unowned region has two distinct looks, and the difference is NOT in the
@@ -291,3 +820,137 @@ export function nationForPrompt(n: Nation) {
     relations: n.relations,
   };
 }
+
+// --- Per-region stats (v0.28, #46) ------------------------------------------
+//
+// A nation's 0–100 `NationStats` are no longer stored as independent per-nation
+// values: they are DERIVED as the area×population-weighted median of the stats
+// of the regions the nation owns (`GameState.regionStats`, keyed by region key).
+// These pure helpers implement that derivation, the fresh-game / legacy seeding,
+// and the one-time migration of a pre-v0.28 row. They have no runtime deps.
+
+/**
+ * The weighted median of `values` with per-value `weights` (paired by index).
+ * The pairs are sorted by value ascending and the result is the value at the
+ * first point where the cumulative weight reaches at least half the total
+ * weight. An empty input, or a total weight of zero, yields 0. Non-finite or
+ * non-positive weights are treated as 0 (excluded from the median).
+ * Translation-invariant: adding a constant to every value shifts the result by
+ * that constant — so the median of a set of **identical** values is that value
+ * (the invariant the equal-value seeding and legacy migration rely on).
+ * Pure + shared.
+ */
+export function weightedMedian(values: number[], weights: number[]): number {
+  if (values.length === 0) return 0;
+  const pairs = values
+    .map((v, i) => {
+      const w =
+        typeof weights[i] === 'number' && Number.isFinite(weights[i]) && weights[i] > 0
+          ? weights[i]
+          : 0;
+      return { v: Number.isFinite(v) ? v : 0, w };
+    })
+    .filter((p) => p.w > 0);
+  if (pairs.length === 0) return 0;
+  const total = pairs.reduce((s, p) => s + p.w, 0);
+  if (total <= 0) return 0;
+  pairs.sort((a, b) => a.v - b.v);
+  let cum = 0;
+  for (const p of pairs) {
+    cum += p.w;
+    if (cum >= total / 2) return p.v;
+  }
+  return pairs[pairs.length - 1]!.v;
+}
+
+/**
+ * Derive a nation's aggregate {@link NationStats} from the stats of the regions
+ * it owns: each of the four stats is the **area×population-weighted median**
+ * (see {@link weightedMedian}) over the nation's owned region keys. A region's
+ * weight is `(area > 0 ? area : 1) × (population > 0 ? population : 1)` — both
+ * factors fall back to 1 when the region has no geo entry (`geoOf` returns
+ * `undefined` for it), so every region carries weight ≥ 1 and a missing geo
+ * degrades gracefully to a uniform (unweighted) median. A region key with no
+ * `regionStats` entry is skipped. Returns the zero stats when the nation owns
+ * no region with a stats entry (the caller's 0-region guard keeps the nation's
+ * directly-maintained `n.stats` in that case). Pure + shared.
+ */
+export function deriveNationStats(
+  regionKeys: string[],
+  regionStats: Record<string, RegionStats>,
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+): NationStats {
+  const zero: NationStats = { military: 0, economy: 0, stability: 0, population: 0 };
+  const byStat: Record<StatKey, number[]> = {
+    military: [],
+    economy: [],
+    stability: [],
+    population: [],
+  };
+  const weights: number[] = [];
+  for (const key of regionKeys) {
+    const rs = regionStats[key];
+    if (!rs) continue; // a key with no per-region stats is skipped
+    const g = geoOf?.(key);
+    const a = g && g.area > 0 ? g.area : 1;
+    const p = g && g.population > 0 ? g.population : 1;
+    weights.push(a * p);
+    for (const k of STAT_KEYS) byStat[k].push(rs[k]);
+  }
+  if (weights.length === 0) return zero;
+  const out: NationStats = { military: 0, economy: 0, stability: 0, population: 0 };
+  for (const k of STAT_KEYS) out[k] = clampStat(weightedMedian(byStat[k], weights));
+  return out;
+}
+
+/**
+ * Seed a per-region stats table from a set of nations (used both at game
+ * creation and by the legacy migration): every owned region key gets a **copy**
+ * of its owner's current `NationStats`, so a fresh nation's regions all start
+ * identical (the weighted median of identical values is that value, so the
+ * derived `n.stats` equals the seeded one). A region with two or more owners
+ * (corrupt) is seeded by the first owner encountered; a key owned by nobody gets
+ * no entry. Pure + shared.
+ */
+export function seedRegionStats(nations: Record<string, Nation>): Record<string, RegionStats> {
+  const out: Record<string, RegionStats> = {};
+  for (const n of Object.values(nations)) {
+    for (const key of n.territory) {
+      if (!(key in out)) out[key] = { ...n.stats }; // first owner wins (sole ownership holds normally)
+    }
+  }
+  return out;
+}
+
+/**
+ * (v0.28, #46) One-time migration of a **legacy** (pre-v0.28) `GameState` row
+ * into the per-region-stats model, returning a new state (the input is never
+ * mutated):
+ *  - a row that already has `regionStats` (a v0.28+ save) is returned
+ *    **UNCHANGED** — its `Nation.stats` are already the correct derived medians
+ *    and must not be recomputed on load (that would drift them);
+ *  - a legacy row (`regionStats` absent at runtime) seeds every owned region key
+ *    with a copy of its owner's current stats (so each nation's regions start
+ *    identical), then recomputes each nation's stats as the weighted median of
+ *    its regions (a 0-region nation keeps its stats). Without `geoOf` the
+ *    weighting is uniform, which is weight-invariant for the identical-value
+ *    case, so the recomputed stats equal the originals — the migration is a
+ *    no-op on the visible numbers and only materializes the (previously
+ *    implicit) per-region values. Never throws.
+ */
+export function migrateRegionStats(
+  state: GameState,
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+): GameState {
+  // A v0.28+ row already carries per-region stats: leave it exactly as saved.
+  if (state.regionStats !== undefined) return state;
+  // Legacy row: materialize per-region stats from each nation's (uniform) stats.
+  const next: GameState = { ...state, regionStats: seedRegionStats(state.nations) };
+  for (const n of Object.values(next.nations)) {
+    if (n.territory.length === 0) continue; // 0-region guard: keep its stats
+    if (n.territory.some((k) => next.regionStats[k])) {
+      n.stats = deriveNationStats(n.territory, next.regionStats, geoOf);
+    }
+  }
+  return next;
+}

shared/scenario.ts

@@ -0,0 +1,464 @@
+// Dynamic scenario generation — the shared (dependency-free) contract.
+//
+// This is the additive "Create scenario" path: instead of picking one of the
+// static presets, the user picks a light **era template**, writes a free-text
+// description, and lets the LLM generate a fresh world (a {@link WorldDraft})
+// plus an advisor **checkpoint** list. The player reviews the checkpoints,
+// approves/removes some, and picks a nation to lead; a second LLM call then
+// finalizes the draft into a playable {@link GameState} (a normal game).
+//
+// Everything here is pure and has no runtime dependencies beyond the other
+// shared modules: it may import types from `./types` and helpers from
+// `./protocol`, but it never imports the engine, the LLM client, or any
+// external package. The two LLM calls (`generateDraft` / `finalizeWorld`)
+// live in `server/scenario.ts`; only the *shapes* and the pure transforms
+// live here.
+
+import type {
+  EventEntry,
+  EventOutcome,
+  EventType,
+  GameState,
+  Nation,
+  NationStats,
+  NationType,
+  RelationStatus,
+} from './types';
+import { clampStat, makeEvent, seedRegionStats, type TurnEventSpec } from './protocol';
+
+// --- Era templates -----------------------------------------------------------
+
+/**
+ * A suggested starting power for an era template: a display `name`, an ISO_A3
+ * core `region` (the country the power is rooted in), and a short `note` the
+ * LLM is shown when it designs the world.
+ */
+export interface SuggestedPower {
+  name: string;
+  /** ISO_A3 country code the power's core territory sits in. */
+  region: string;
+  note: string;
+}
+
+/**
+ * A light **era template** the user can start from on the "Create scenario"
+ * path (one JSON file per template in `presets/templates/`, plus an
+ * `index.json` manifest). It is deliberately small: a name, a default `year`,
+ * a short `eraDescription`, a few `suggestedPowers`, and a few `tensions` —
+ * a seed the LLM generator expands into a full {@link WorldDraft}.
+ */
+export interface EraTemplate {
+  id: string;
+  name: string;
+  /** Default starting year (the user may override it in the form). */
+  year: number;
+  /** A short description of the era, shown on the card and fed to the LLM. */
+  eraDescription: string;
+  /** A few suggested starting powers (name + ISO_A3 core region + a note). */
+  suggestedPowers: SuggestedPower[];
+  /** A few suggested tensions / conflicts to seed the world. */
+  tensions: string[];
+}
+
+/** The lightweight manifest entry for an era template (the picker card). */
+export interface TemplateMeta {
+  id: string;
+  name: string;
+  year: number;
+  eraDescription: string;
+}
+
+// --- World draft -------------------------------------------------------------
+
+/**
+ * A single nation in a generated world **draft** (before it is committed to a
+ * playable {@link GameState}). Its `territory` holds **ISO_A3 country codes**
+ * (not region keys) — the engine expands them to sub-region keys at commit
+ * time via the injected `expand` resolver. `relations` are the LLM's
+ * numeric sentiment toward other nations (−100..100); the engine maps them to
+ * a {@link RelationStatus} on commit.
+ */
+export interface WorldNation {
+  id: string;
+  name: string;
+  type?: NationType;
+  stats: NationStats;
+  /** ISO_A3 country codes the nation controls. */
+  territory: string[];
+  /** Bilateral sentiment: other nation id -> −100..100. */
+  relations: Record<string, number>;
+}
+
+/** An optional narrative backstory event carried by a world draft (turn 0). */
+export interface ScenarioEvent {
+  nation: string;
+  type: EventType;
+  title: string;
+  text: string;
+  outcome: EventOutcome;
+}
+
+/**
+ * A draft world the LLM generator returns before the player confirms it.
+ * `nations` is required and non-empty; `events` is optional backstory that
+ * seeds the new game's event feed on commit.
+ */
+export interface WorldDraft {
+  nations: WorldNation[];
+  events?: ScenarioEvent[];
+}
+
+/**
+ * A single **advisor checkpoint** — a short string the generator proposes for
+ * the player to approve (or remove) before the world is finalized. The
+ * approved checkpoints are handed to the finalize call as constraints.
+ */
+export type Checkpoint = string;
+
+// --- Client ↔ server message shapes (the two LLM steps) -----------------------
+
+/** The body of `POST /api/scenarios/draft` (step 1: design the world). */
+export interface ScenarioDraftRequest {
+  templateId: string;
+  description: string;
+  /** The chosen start year (the server falls back to the template's year). */
+  year?: number;
+}
+
+/** The response of `POST /api/scenarios/draft` — the draft world + checkpoints. */
+export interface ScenarioDraftResponse {
+  world: WorldDraft;
+  checkpoints: string[];
+}
+
+/** The body of `POST /api/scenarios/commit` (step 2: finalize + save the game). */
+export interface ScenarioCommitRequest {
+  templateId: string;
+  description: string;
+  /** The chosen start year (the server falls back to the template's year). */
+  year?: number;
+  /** The step-1 draft, re-sent so the final world stays close to it. */
+  draft?: WorldDraft;
+  /** The checkpoints the player approved (the finalize step's constraints). */
+  approvedCheckpoints: string[];
+  /** The nation id the player will lead (kept in the final world when present). */
+  playerNationId: string;
+}
+
+/** The response of `POST /api/scenarios/commit` — the saved game's id. */
+export interface ScenarioCommitResponse {
+  id: string;
+}
+
+// --- Validation + transforms (pure) ------------------------------------------
+
+/** The 8 known event types (a local copy so this module needs no runtime import). */
+const EVENT_TYPES: readonly string[] = [
+  'military',
+  'diplomatic',
+  'economic',
+  'political',
+  'social',
+  'disaster',
+  'scientific',
+  'cultural',
+];
+
+/** The 5 known nation types. */
+const NATION_TYPES: readonly string[] = ['major', 'minor', 'power', 'alliance', 'faction'];
+
+/** True when `t` is one of the eight known event types. */
+function isEventType(t: unknown): t is EventType {
+  return typeof t === 'string' && (EVENT_TYPES as string[]).includes(t);
+}
+
+/** True when `t` is one of the five known event outcomes. */
+function isEventOutcome(o: unknown): o is EventOutcome {
+  return o === 'success' || o === 'failure' || o === 'partial' || o === 'neutral';
+}
+
+/** True when `t` is one of the five known nation types. */
+function isNationType(t: unknown): t is NationType {
+  return typeof t === 'string' && (NATION_TYPES as string[]).includes(t);
+}
+
+/** Clamp a number to [lo, hi] and round (non-finite → lo). */
+function clampRange(v: number, lo: number, hi: number): number {
+  if (!Number.isFinite(v)) return lo;
+  return Math.max(lo, Math.min(hi, Math.round(v)));
+}
+
+/** Parse a raw (unknown) stats object into a clamped NationStats (missing → 50). */
+function parseStats(raw: unknown): NationStats {
+  const o =
+    raw && typeof raw === 'object' && !Array.isArray(raw)
+      ? (raw as Record<string, unknown>)
+      : {};
+  const get = (k: keyof NationStats): number => {
+    const v = o[k];
+    return typeof v === 'number' && Number.isFinite(v) ? clampStat(v) : 50;
+  };
+  return {
+    military: get('military'),
+    economy: get('economy'),
+    stability: get('stability'),
+    population: get('population'),
+  };
+}
+
+/**
+ * A short, stable, lowercase slug for a nation name (used as a fallback id):
+ * "United Kingdom" → "united-kingdom". Diacritics stripped, runs of
+ * non-alphanumerics collapsed to a single dash, length capped at 20.
+ */
+function slugFromName(name: string): string {
+  const s = name
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (!s) return '';
+  return s.length > 20 ? s.slice(0, 20).replace(/-+$/, '') : s;
+}
+
+/**
+ * Map a numeric sentiment score (−100..100) to a {@link RelationStatus}.
+ * Five bands: ally (≥60), neutral (0..59), rival (−40..−1), hostile (−80..−41),
+ * war (≤−81). Pure.
+ */
+export function relationFromScore(v: number): RelationStatus {
+  const c = clampRange(v, -100, 100);
+  if (c >= 60) return 'ally';
+  if (c >= 0) return 'neutral';
+  if (c >= -40) return 'rival';
+  if (c >= -80) return 'hostile';
+  return 'war';
+}
+
+/**
+ * Validate + normalize a raw LLM world-draft payload into a clean
+ * {@link WorldDraft} (or `null` when it is unusable). Never throws:
+ *   - the top level must be an object with a non-empty `nations` array;
+ *   - each nation needs a non-empty `name`; its `id` is kept when a valid
+ *     non-empty string, else derived from a name slug (else `n<index>`);
+ *     duplicate ids are suffixed until unique;
+ *   - each nation's `type`/stats are clamped (missing stats → 50);
+ *   - each nation's `territory` is upper-cased, deduped, and (when
+ *     `validCountryCodes` is given) filtered to only known ISO_A3 codes;
+ *   - a nation's `relations` are clamped to −100..100 and re-keyed to the
+ *     assigned ids (a key that is a known id, or a case-insensitive name
+ *     match, is kept; unknown / self references are dropped);
+ *   - optional `events` are kept when they name a known nation (by id or
+ *     name) and have a non-empty title;
+ *   - the result is `null` when there are no nations, or no nation ends up
+ *     owning a valid territory (nothing to render on the map).
+ */
+export function validateWorldDraft(
+  raw: unknown,
+  opts: { validCountryCodes?: ReadonlySet<string> } = {},
+): WorldDraft | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const obj = raw as Record<string, unknown>;
+  const rawNations = Array.isArray(obj.nations) ? obj.nations : null;
+  if (!rawNations || rawNations.length === 0) return null;
+
+  const validCodes = opts.validCountryCodes;
+  const usedIds = new Set<string>();
+  const nameToId = new Map<string, string>();
+
+  interface Tmp {
+    id: string;
+    name: string;
+    type: NationType;
+    stats: NationStats;
+    territory: string[];
+    rawRelations: Record<string, number>;
+  }
+  const tmp: Tmp[] = [];
+
+  for (const rn of rawNations) {
+    if (!rn || typeof rn !== 'object') continue;
+    const o = rn as Record<string, unknown>;
+    const name = typeof o.name === 'string' ? o.name.trim() : '';
+    if (name === '') continue; // a nation needs a name
+
+    // id: keep a valid non-empty string, else derive from the name slug, else n<index>.
+    let id = typeof o.id === 'string' && o.id.trim() !== '' ? o.id.trim() : '';
+    if (id === '') id = slugFromName(name) || `n${tmp.length + 1}`;
+    let candidate = id;
+    let k = 2;
+    while (usedIds.has(candidate)) {
+      candidate = `${id}-${k}`;
+      k += 1;
+    }
+    id = candidate;
+    usedIds.add(id);
+    const lowerName = name.toLowerCase();
+    if (!nameToId.has(lowerName)) nameToId.set(lowerName, id);
+
+    const type = isNationType(o.type) ? o.type : 'major';
+    const stats = parseStats(o.stats);
+
+    // territory: upper-case, de-duped, and (optionally) filtered to known codes.
+    const territory: string[] = [];
+    if (Array.isArray(o.territory)) {
+      for (const t of o.territory) {
+        if (typeof t !== 'string') continue;
+        const code = t.trim().toUpperCase();
+        if (code === '') continue;
+        if (validCodes && !validCodes.has(code)) continue; // drop unknown country codes
+        if (!territory.includes(code)) territory.push(code);
+      }
+    }
+
+    // relations: keep only finite numeric values (clamped later on re-key).
+    const rawRelations: Record<string, number> = {};
+    if (o.relations && typeof o.relations === 'object' && !Array.isArray(o.relations)) {
+      for (const [key, v] of Object.entries(o.relations as Record<string, unknown>)) {
+        if (typeof v === 'number' && Number.isFinite(v)) rawRelations[key] = v;
+      }
+    }
+
+    tmp.push({ id, name, type, stats, territory, rawRelations });
+  }
+
+  if (tmp.length === 0) return null;
+  // Unusable when no nation owns a valid territory (there is nothing to render).
+  if (!tmp.some((t) => t.territory.length > 0)) return null;
+
+  const idSet = new Set(tmp.map((t) => t.id));
+  const nations: WorldNation[] = tmp.map((t) => {
+    const relations: Record<string, number> = {};
+    for (const [key, val] of Object.entries(t.rawRelations)) {
+      // Resolve the key: a known id, else a case-insensitive name match.
+      let target = key;
+      if (!idSet.has(target)) {
+        const mapped = nameToId.get(key.toLowerCase());
+        if (mapped) target = mapped;
+      }
+      if (target === t.id) continue; // drop self-references
+      if (!idSet.has(target)) continue; // drop references to unknown nations
+      relations[target] = clampRange(val, -100, 100);
+    }
+    return { id: t.id, name: t.name, type: t.type, stats: t.stats, territory: t.territory, relations };
+  });
+
+  // Optional backstory events (kept when they name a known nation).
+  let events: ScenarioEvent[] | undefined;
+  if (Array.isArray(obj.events)) {
+    const evs: ScenarioEvent[] = [];
+    for (const re of obj.events) {
+      if (!re || typeof re !== 'object') continue;
+      const e = re as Record<string, unknown>;
+      const title = typeof e.title === 'string' ? e.title.trim() : '';
+      if (title === '') continue;
+      const text = typeof e.text === 'string' ? e.text : '';
+      const type = isEventType(e.type) ? e.type : 'political';
+      const outcome = isEventOutcome(e.outcome) ? e.outcome : 'neutral';
+      let nation = typeof e.nation === 'string' ? e.nation : '';
+      if (nation !== '' && !idSet.has(nation)) {
+        nation = nameToId.get(nation.toLowerCase()) ?? '';
+      }
+      if (nation === '' || !idSet.has(nation)) continue; // drop events with no known owner
+      evs.push({ nation, type, title, text, outcome });
+    }
+    events = evs;
+  }
+
+  return { nations, events };
+}
+
+/** Options for {@link worldDraftToGameState} (all optional, sensible defaults). */
+export interface WorldDraftToGameOptions {
+  /** The new game's id (the server sets `randomUUID()`; default `''`). */
+  id?: string;
+  /** The scenario title (becomes `GameState.presetTitle`; default 'Custom World'). */
+  title?: string;
+  /** The game's start date (`YYYY-MM-DD`, from the chosen year; default '1970-01-01'). */
+  startDate?: string;
+}
+
+/**
+ * Convert a validated {@link WorldDraft} into a fresh, playable {@link
+ * GameState} (a normal game at `#/game/<id>`). Mirrors `POST /api/games`
+ * exactly, except the draft's nations carry **ISO_A3** territory which is
+ * expanded to sub-region keys by the injected `expand` resolver, and
+ * `regionStats` is seeded from the expanded territories via
+ * {@link seedRegionStats} (so every owned region starts with its owner's
+ * stats and the derived aggregate equals them on turn 1).
+ *
+ * The result is a clean turn-1 state: `version: 1`, `turn: 1`, `unowned: []`,
+ * `markers: []`, `pendingNationOps: []`, `pending: []`, the given
+ * `playerNationId`, and a `startDate` from the chosen year. Backstory events
+ * (if any) seed the event feed at turn 1. Pure — no side effects, no I/O.
+ */
+export function worldDraftToGameState(
+  draft: WorldDraft,
+  expand: (countries: string[]) => string[],
+  playerNationId: string,
+  opts: WorldDraftToGameOptions = {},
+): GameState {
+  const id = opts.id ?? '';
+  const title = opts.title ?? 'Custom World';
+  const startDate = opts.startDate ?? '1970-01-01';
+
+  const nations: Record<string, Nation> = {};
+  for (const wn of draft.nations) {
+    const relations: Record<string, RelationStatus> = {};
+    for (const [otherId, score] of Object.entries(wn.relations)) {
+      if (otherId === wn.id) continue; // no self-relations
+      relations[otherId] = relationFromScore(score);
+    }
+    nations[wn.id] = {
+      id: wn.id,
+      name: wn.name,
+      type: wn.type ?? 'major',
+      stats: wn.stats,
+      territory: expand(wn.territory),
+      relations,
+    };
+  }
+
+  // Guard: a finalize step (or a bad model answer) might drop the nation the
+  // player chose to lead. Rather than produce a game with a dangling
+  // playerNationId, fall back to the first nation (deterministic insertion
+  // order) so the resulting game is always playable.
+  const effectivePlayer =
+    nations[playerNationId] !== undefined
+      ? playerNationId
+      : draft.nations.length > 0
+        ? draft.nations[0].id
+        : '';
+
+  // Seed the event feed from the draft's optional backstory (turn 1, startDate).
+  const events: EventEntry[] = (draft.events ?? []).map((e) =>
+    makeEvent(e as unknown as TurnEventSpec, 1, startDate),
+  );
+
+  const state: GameState = {
+    id,
+    presetId: 'dynamic',
+    presetTitle: title,
+    playerNationId: effectivePlayer,
+    turn: 1,
+    date: startDate,
+    nations,
+    events,
+    pending: [],
+    version: 1,
+    unowned: [],
+    pendingNationOps: [],
+    markers: [],
+    // Seed AFTER the territories hold real region keys: each owned region gets
+    // a copy of its owner's stats, so the derived aggregate equals them.
+    regionStats: seedRegionStats(nations),
+    // (v0.33.0, #56) No wars on a fresh (dynamic) game; any preset-level `war`
+    // relation stays a bare/implicit one, not an entity (see syncWarRelations).
+    wars: [],
+    // (v0.35.0, #58) No trades/embargoes on a fresh (dynamic) game.
+    trades: [],
+    embargoes: [],
+  };
+  return state;
+}

shared/types.ts

@@ -1,5 +1,9 @@
 // Domain types — the single source of truth shared by the frontend (src/), the
 // backend (server/), and the LLM prompt contract. No runtime dependencies here.
+// (The single `import type` below erases at compile time, so no runtime
+// dependency on protocol.ts is introduced — see the GameState.pendingNationOps
+// doc comment.)
+import type { NationOp } from './protocol';
 
 /** A nation's 0–100 status indices. Every value is clamped to 0–100 by the engine. */
 export interface NationStats {
@@ -9,6 +13,19 @@ export interface NationStats {
   population: number;
 }
 
+/**
+ * (v0.28, #46) The 0–100 status indices of a **single region**. Per-region stats
+ * are the unit of record: a nation's aggregate {@link NationStats} is derived as
+ * the area×population-weighted median of the stats of the regions it owns (see
+ * `protocol.deriveNationStats`). Every value is clamped to 0–100 by the engine.
+ */
+export interface RegionStats {
+  military: number;
+  economy: number;
+  stability: number;
+  population: number;
+}
+
 export const STAT_KEYS = ['military', 'economy', 'stability', 'population'] as const;
 export type StatKey = (typeof STAT_KEYS)[number];
 
@@ -62,7 +79,138 @@ export const EVENT_TYPES: EventType[] = [
   'cultural',
 ];
 
-export type EventOutcome = 'success' | 'failure' | 'partial' | 'neutral';
+/**
+ * The outcome of a narrative event. `success` / `failure` / `partial` /
+ * `neutral` are the four the LLM is asked to emit. `repelled` (v0.30, #50) is
+ * reserved for the engine: it is emitted automatically when the military hard
+ * gate rejects a contested conquest (an invasion whose attacker was more than
+ * `CONQUEST_MILITARY_MARGIN` below the defender) — the LLM never produces it,
+ * and the client renders it in a distinct muted-red failure tone.
+ */
+export type EventOutcome = 'success' | 'failure' | 'partial' | 'neutral' | 'repelled';
+
+// --- Map markers (v0.27, #44) -------------------------------------------------
+//
+// Named point markers the LLM can place on the map (cities, factories, armies,
+// ports, capitals, fleets, rocket launch sites, political/social gatherings).
+// A marker is anchored to a **region key** (see `public/region-keys.json`): the
+// engine positions it at that region's precomputed centroid (with a small
+// deterministic offset) and its `ownerNationId` follows the region's current
+// owner (recomputed on every turn; `null` when the region is unowned / no
+// man's land). See protocol.ts for the LLM-facing `TurnResult.markers`
+// contract and the `markerId` derivation.
+
+/** The eight marker categories the model may place (v0.27, #44). */
+export type MarkerType =
+  | 'city'
+  | 'factory'
+  | 'army'
+  | 'port'
+  | 'capital'
+  | 'fleet'
+  | 'rocket'
+  | 'gathering';
+
+/** All marker types, in canonical order (used by the LLM contract + map layer). */
+export const MARKER_TYPES: MarkerType[] = [
+  'city',
+  'factory',
+  'army',
+  'port',
+  'capital',
+  'fleet',
+  'rocket',
+  'gathering',
+];
+
+/**
+ * A named point marker on the map (v0.27, #44). `id` is a stable,
+ * deterministic 4-character code derived from `type + name + regionKey`
+ * (see protocol.markerId) — re-adding the same marker is idempotent and
+ * removing by id is unambiguous. `lat`/`lon` are filled in by the engine from
+ * the region's centroid manifest (never by the model); `ownerNationId` is the
+ * marker's region's current owner (`null` when unowned) and is recomputed by
+ * the engine on every committed turn, so a marker always follows its region.
+ */
+export interface MapMarker {
+  id: string;
+  type: MarkerType;
+  name: string;
+  regionKey: string;
+  lat: number;
+  lon: number;
+  ownerNationId: string | null;
+  placedTurn: number;
+}
+
+/**
+ * (v0.35.0, #58) An active BILATERAL TRADE agreement between two distinct
+ * nations. Declared by the LLM via `TurnResult.economy.trade` (a no-`lift`
+ * op) and ended by a `lift: true` op; while active it yields a small,
+ * deterministic economy gain to BOTH parties every committed turn. The
+ * engine suspends (removes) the trade automatically when the two parties end
+ * up on opposite sides of an active war (v0.33, #56).
+ */
+export interface TradeAgreement {
+  /** First party's nation id. */
+  a: string;
+  /** Second party's nation id (distinct from `a`; the pair is symmetric). */
+  b: string;
+}
+
+/**
+ * (v0.35.0, #58) An active UNILATERAL EMBARGO: `from` blocks trade with
+ * `target` (which must differ from `from`). Declared by the LLM via
+ * `TurnResult.economy.embargo` (a no-`lift` op) and lifted by a `lift: true`
+ * op; while active it applies a small, deterministic economy dip to the
+ * TARGET only, every committed turn. The engine suspends (removes) the
+ * embargo automatically when the two nations end up on opposite sides of an
+ * active war (v0.33, #56).
+ */
+export interface Embargo {
+  /** The imposing nation's id. */
+  from: string;
+  /** The embargoed nation's id (distinct from `from`). */
+  target: string;
+}
+
+/**
+ * (v0.33.0, #56) A first-class **war** — a named, ongoing armed conflict
+ * between two or more nations. Unlike the boolean `war` relation (which a
+ * preset or a bare `relations` entry can carry without any structure behind
+ * it), a `War` is an explicit world entity the engine tracks: the LLM
+ * declares it (a turn's `wars.declare`), the engine assigns it a stable id
+ * (`w1`, `w2`, …), the turn and in-game date it was declared, and it stays in
+ * `GameState.wars` for the rest of the game as history after it ends.
+ *
+ * **Semantics of `sides`:** the flat list of every belligerent in the war
+ * (≥2 distinct nation ids). Any two distinct members of an active war's
+ * sides are at war with each other — the engine derives the symmetric `war`
+ * relation for every such pair on every turn (see the engine's
+ * `syncWarRelations`), and downgrades the relation to `hostile` when the war
+ * ends. A mutual-defense ally of a belligerent is dragged into the same list
+ * on declaration (the engine does this automatically).
+ */
+export interface War {
+  /** Stable id (`w1`, `w2`, …) assigned by the engine on declaration. */
+  id: string;
+  /** The belligerent nations (≥2 distinct ids; see the note above). */
+  sides: string[];
+  /** The turn number the war was declared on. */
+  declaredTurn: number;
+  /** The in-game date the war took effect on (`YYYY-MM-DD`). */
+  declaredDate?: string;
+  /** Optional short war aims the LLM names at declaration. */
+  aims?: string[];
+  /**
+   * Lifecycle: `active` until a turn ends the war, then the end outcome —
+   * `armistice` (a negotiated stop) or `capitulation` (one side surrenders) —
+   * or the generic `ended`. Ended wars stay in `GameState.wars` as history.
+   */
+  status: 'active' | 'armistice' | 'capitulation' | 'ended';
+  /** Optional region keys the war's front line runs through (reserved). */
+  front?: string[];
+}
 
 /** A narrative event the simulation emitted on some turn. */
 export interface EventEntry {
@@ -133,6 +281,81 @@ export interface GameState {
    * this defaulted to `[]` (see server/db.ts).
    */
   unowned: string[];
+  /**
+   * (v0.23, #16 P4a; v0.24, #16 P4b) Nation-management ops the LLM has
+   * proposed but the player has not yet resolved: a *pending proposal* list,
+   * as opposed to `pending` (the current round's queued player actions). A
+   * turn NEVER applies one — `applyTurnResult` appends the turn's
+   * `nationOps` to this list, and each proposal survives across turns until
+   * the player resolves it: confirming applies it (a rename changes
+   * `Nation.name` only; a split partitions the nation's region-key territory
+   * into the new nations' territories; a merge folds the inputs' territory
+   * into the survivor) and removes it; rejecting removes it without
+   * applying. Always `[]` on a fresh game; rows saved before v0.23 load with
+   * this defaulted to `[]` (see server/db.ts). (The `NationOp` type lives in
+   * protocol.ts; the import there is type-only, so this file still has no
+   * runtime dependencies.)
+   */
+  pendingNationOps: NationOp[];
+  /**
+   * (v0.27, #44) Named point markers on the map: the LLM places them (via a
+   * turn's `markers.add`) and removes them (`markers.remove`, by id). The
+   * engine positions each at its region's centroid (deterministic small
+   * offset) and recomputes `ownerNationId` from the region's current owner on
+   * EVERY committed turn (a released region → `null`). Always `[]` on a fresh
+   * game; rows saved before v0.27 load with this defaulted to `[]` (see
+   * server/db.ts) — additive, no data wipe. Capped at protocol.MAX_MARKERS.
+   */
+  markers: MapMarker[];
+  /**
+   * (v0.28, #46) Per-region stats, keyed by **region key** (see
+   * `public/region-keys.json`): each owned region carries its own four 0–100
+   * stats, and a nation's aggregate `Nation.stats` is the area×population-
+   * weighted median of the regions it owns (see `protocol.deriveNationStats`).
+   * A region that ends a turn **unowned** (released to no man's land) has NO
+   * entry, and a preset-unassigned region (never owned) has none until first
+   * claimed (re-claiming re-inits it to the gainer's stats). Always present on a
+   * fresh game (every owned region seeded with its owner's initial stats); a
+   * legacy SQLite row without the field is migrated at load (see server/db.ts)
+   * — additive, no data wipe.
+   */
+  regionStats: Record<string, RegionStats>;
+  /**
+   * (v0.33.0, #56) First-class war entities (see {@link War}): declared by a
+   * turn's `wars.declare` (the engine assigns the id, declared turn/date, and
+   * drags in mutual-defense allies) and closed by `wars.end` (armistice /
+   * capitulation). The engine DERIVES the `war` relation from the ACTIVE
+   * wars on every turn (two nations are in a `war` relation iff they are both
+   * belligerents of ≥1 active war), so the boolean relation and the war
+   * entities can never drift apart. A bare preset `war` relation with no
+   * active war behind it stays as-is (an implicit, unnamed war — never
+   * force-created into an entity). Always `[]` on a fresh game; rows saved
+   * before v0.33 load with this defaulted to `[]` (see server/db.ts) —
+   * additive, no data wipe.
+   */
+  wars: War[];
+  /**
+   * (v0.35.0, #58) Active bilateral trade agreements (see {@link TradeAgreement}):
+   * declared/ended by a turn's `economy.trade` ops (a no-`lift` op declares,
+   * `lift: true` ends). Every committed turn the engine applies a small,
+   * deterministic economy gain to BOTH parties of each active agreement, and
+   * suspends (removes) any agreement whose two parties are on opposite sides
+   * of an active war (v0.33, #56). Always `[]` on a fresh game; rows saved
+   * before v0.35 load with this defaulted to `[]` (see server/db.ts) —
+   * additive, no data wipe.
+   */
+  trades: TradeAgreement[];
+  /**
+   * (v0.35.0, #58) Active unilateral embargoes (see {@link Embargo}):
+   * imposed/lifted by a turn's `economy.embargo` ops (a no-`lift` op imposes,
+   * `lift: true` lifts). Every committed turn the engine applies a small,
+   * deterministic economy dip to each embargo's TARGET only, and suspends
+   * (removes) any embargo whose two nations are on opposite sides of an
+   * active war (v0.33, #56). Always `[]` on a fresh game; rows saved before
+   * v0.35 load with this defaulted to `[]` (see server/db.ts) — additive,
+   * no data wipe.
+   */
+  embargoes: Embargo[];
 }
 
 /**

src/App.tsx

@@ -16,6 +16,8 @@ import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '.
 import { cn } from './lib/utils';
 import PresetPicker from './components/PresetPicker';
 import NationSelect from './components/NationSelect';
+import ScenarioForm from './components/ScenarioForm';
+import CheckpointReview from './components/CheckpointReview';
 import WorldMap from './components/WorldMap';
 import FloatingWindow from './components/FloatingWindow';
 import MapLegend from './components/MapLegend';
@@ -26,9 +28,27 @@ import { api } from './lib/api';
 import { useSse } from './lib/sse';
 import { nationColor, type GameSummary, type RegionMap } from '@shared/protocol';
 import type { GameState, Preset, PresetMeta } from '@shared/types';
+import type { TemplateMeta, WorldDraft } from '@shared/scenario';
 
-/** Which top-level screen the app is showing. */
-type Screen = { name: 'home' } | { name: 'pick'; preset: Preset } | { name: 'game' };
+/**
+ * Which top-level screen the app is showing. The dynamic path (v0.31, #52) adds
+ * two: 'scenario-form' (era + description + year) and 'scenario-review' (the
+ * generated world + checkpoint checklist + nation pick), the latter carrying
+ * the step-1 draft + chosen template so the finalize step can re-send them.
+ */
+type Screen =
+  | { name: 'home' }
+  | { name: 'pick'; preset: Preset }
+  | { name: 'game' }
+  | { name: 'scenario-form' }
+  | {
+      name: 'scenario-review';
+      template: TemplateMeta;
+      description: string;
+      year: number;
+      world: WorldDraft;
+      checkpoints: string[];
+    };
 
 /**
  * Surface a turn failure. A 502 (live model down / timeout) gets a friendly,
@@ -177,6 +197,14 @@ export default function App() {
   // gate the turn flow ("Jump forward" stays enabled while the advisor thinks) —
   // it only gates the advisor UI (the "Ask advisor" button + its hint).
   const [advisorBusy, setAdvisorBusy] = useState(false);
+  // Separate again: a pending nation-op confirm/reject is its own (fast,
+  // non-LLM) request. It gates only the nation-op dialog controls, never the
+  // turn flow — "Jump forward" stays usable while it is in flight.
+  const [opBusy, setOpBusy] = useState(false);
+  // (v0.31, #52) A scenario-generation LLM call (generate or finalize) is
+  // in flight. Distinct from `busy`/`advisorBusy` — it only gates the
+  // scenario-form/review screens (those screens never coexist with a game).
+  const [scenarioBusy, setScenarioBusy] = useState(false);
   // The id of the game the user is/was last in (mirrors localStorage) and the
   // list of saved games (newest first) shown on the home screen.
   const [activeGameId, setActiveGameId] = useState<string | null>(() => readActiveGameId());
@@ -355,6 +383,77 @@ export default function App() {
     [screen],
   );
 
+  // --- (v0.31, #52) Dynamic scenario generation: form → generate → review →
+  // finalize → game. Both LLM steps run on the server (the scenario stub under
+  // LLM_STUB=1, the live model otherwise); on failure we toast and stay on the
+  // current screen (the form's / review's local selections are preserved).
+
+  // Home screen's "Create scenario" card → the scenario form.
+  const openScenarioForm = useCallback(() => {
+    setScreen({ name: 'scenario-form' });
+  }, []);
+
+  // Step 1 (generate): design the draft world + checkpoint list. On success
+  // the app moves to the review screen (carrying the draft, template, year,
+  // and description so the finalize step can re-send them).
+  const generateScenarioDraft = useCallback(
+    async (template: TemplateMeta, description: string, year: number) => {
+      setScenarioBusy(true);
+      try {
+        const { world, checkpoints } = await api.draftScenario({
+          templateId: template.id,
+          description,
+          year,
+        });
+        setScreen({ name: 'scenario-review', template, description, year, world, checkpoints });
+      } catch (e) {
+        toastError(e);
+      } finally {
+        setScenarioBusy(false);
+      }
+    },
+    [],
+  );
+
+  // Step 2 (finalize): commit the approved draft into a saved, playable game
+  // and enter it. The step-1 draft is re-sent so the final world stays close
+  // to it (and the chosen nation survives); the new game's id is then fetched
+  // and adopted exactly like a normal created game (active-game persistence,
+  // applyState, screen → game — the URL-sync effect writes the deep link).
+  const finalizeScenario = useCallback(
+    async (
+      template: TemplateMeta,
+      description: string,
+      year: number,
+      world: WorldDraft,
+      approvedCheckpoints: string[],
+      playerNationId: string,
+    ) => {
+      setScenarioBusy(true);
+      try {
+        const { id } = await api.commitScenario({
+          templateId: template.id,
+          description,
+          year,
+          draft: world,
+          approvedCheckpoints,
+          playerNationId,
+        });
+        const { game } = await api.getGame(id);
+        persistActiveGameId(id);
+        setActiveGameId(id);
+        applyState(game);
+        setAdvisors([]);
+        setScreen({ name: 'game' });
+      } catch (e) {
+        toastError(e);
+      } finally {
+        setScenarioBusy(false);
+      }
+    },
+    [applyState],
+  );
+
   // Add an action to the pending round. Fast, non-LLM — no `busy`; the pending
   // list updates from the response and the SSE `state` event. Both are
   // version-gated via applyState, so the item can never be clobbered by a
@@ -401,6 +500,44 @@ export default function App() {
     [game, applyState],
   );
 
+  // Apply a pending nation op the model proposed (confirm; `edits.name`
+  // overrides a rename/merge name, `edits.playerPart` picks the player's
+  // successor part in a split). Fast, non-LLM — gated by `opBusy`, not `busy`.
+  // The version-bumped state comes back in the response and the SSE `state` event.
+  const runConfirmNationOp = useCallback(
+    async (index: number, edits?: { name?: string; playerPart?: number }) => {
+      if (!game) return;
+      setOpBusy(true);
+      try {
+        const { game: g } = await api.confirmNationOp(game.id, index, edits);
+        applyState(g);
+        toast.success('Nation change applied');
+      } catch (e) {
+        toastError(e);
+      } finally {
+        setOpBusy(false);
+      }
+    },
+    [game, applyState],
+  );
+
+  // Drop a pending nation op (reject / dismiss). Fast, non-LLM — `opBusy`.
+  const runRejectNationOp = useCallback(
+    async (index: number) => {
+      if (!game) return;
+      setOpBusy(true);
+      try {
+        const { game: g } = await api.rejectNationOp(game.id, index);
+        applyState(g);
+      } catch (e) {
+        toastError(e);
+      } finally {
+        setOpBusy(false);
+      }
+    },
+    [game, applyState],
+  );
+
   // Jump forward: the single LLM call that commits the pending round. Only this
   // sets `busy` (the adds above are fast and non-LLM).
   const runJump = useCallback(async () => {
@@ -507,12 +644,15 @@ export default function App() {
           regions={regions}
           busy={busy}
           advisorBusy={advisorBusy}
+          opBusy={opBusy}
           advisors={advisors}
           onAddAction={runAddAction}
           onAddDiplomacy={runAddDiplomacy}
           onRemoveQueueItem={runRemoveQueueItem}
           onAdvisor={askAdvisor}
           onJump={runJump}
+          onConfirmNationOp={runConfirmNationOp}
+          onRejectNationOp={runRejectNationOp}
           onHome={goHome}
         />
       </>
@@ -528,6 +668,36 @@ export default function App() {
     );
   }
 
+  if (screen.name === 'scenario-form') {
+    return (
+      <>
+        <Toaster richColors position="top-right" />
+        <ScenarioForm busy={scenarioBusy} onBack={goHome} onGenerate={generateScenarioDraft} />
+      </>
+    );
+  }
+
+  if (screen.name === 'scenario-review') {
+    const { template, description, year, world, checkpoints } = screen;
+    return (
+      <>
+        <Toaster richColors position="top-right" />
+        <CheckpointReview
+          template={template}
+          description={description}
+          year={year}
+          world={world}
+          checkpoints={checkpoints}
+          busy={scenarioBusy}
+          onBack={openScenarioForm}
+          onFinalize={(approved, nationId) =>
+            void finalizeScenario(template, description, year, world, approved, nationId)
+          }
+        />
+      </>
+    );
+  }
+
   return (
     <>
       <Toaster richColors position="top-right" />
@@ -539,6 +709,7 @@ export default function App() {
         activeGameId={activeGameId}
         onResume={resumeGame}
         onDelete={runDeleteGame}
+        onCreateScenario={openScenarioForm}
       />
     </>
   );
@@ -551,12 +722,16 @@ interface GameScreenProps {
   busy: boolean;
   /** An advisor fetch is in flight — drives the advisor UI only (never the turn). */
   advisorBusy: boolean;
+  /** A nation-op confirm/reject is in flight — drives the dialog controls only. */
+  opBusy: boolean;
   advisors: string[];
   onAddAction: (a: string) => void;
   onAddDiplomacy: (to: string, m: string) => void;
   onRemoveQueueItem: (index: number) => void;
   onAdvisor: (p?: string) => void;
   onJump: () => void;
+  onConfirmNationOp: (index: number, edits?: { name?: string; playerPart?: number }) => void;
+  onRejectNationOp: (index: number) => void;
   onHome: () => void;
 }
 
@@ -579,12 +754,15 @@ function GameScreen({
   regions,
   busy,
   advisorBusy,
+  opBusy,
   advisors,
   onAddAction,
   onAddDiplomacy,
   onRemoveQueueItem,
   onAdvisor,
   onJump,
+  onConfirmNationOp,
+  onRejectNationOp,
   onHome,
 }: GameScreenProps) {
   // Which nation's dossier to show. Defaults to the player; remounts per game.
@@ -654,6 +832,8 @@ function GameScreen({
         nations={game.nations}
         presetId={game.presetId}
         unowned={game.unowned ?? []}
+        markers={game.markers ?? []}
+        regionStats={game.regionStats ?? {}}
         onFocusNation={focusNation}
       />
 
@@ -835,12 +1015,15 @@ function GameScreen({
           game={game}
           busy={busy}
           advisorBusy={advisorBusy}
+          opBusy={opBusy}
           advisors={advisors}
           onAddAction={onAddAction}
           onAddDiplomacy={onAddDiplomacy}
           onRemoveQueueItem={onRemoveQueueItem}
           onAdvisor={onAdvisor}
           onJump={onJump}
+          onConfirmNationOp={onConfirmNationOp}
+          onRejectNationOp={onRejectNationOp}
           inWindow
         />
       </FloatingWindow>

src/components/ActionPanel.tsx

@@ -1,5 +1,5 @@
 import { useState } from 'react';
-import { Loader2, MessageSquare, Radar, Trash2, Zap } from 'lucide-react';
+import { Loader2, MessageSquare, PenLine, Radar, Trash2, Zap } from 'lucide-react';
 import { Badge } from './ui/badge';
 import { Button } from './ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from './ui/card';
@@ -15,6 +15,7 @@ import { Input } from './ui/input';
 import { Textarea } from './ui/textarea';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from './ui/tabs';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from './ui/select';
+import NationOpDialog from './NationOpDialog';
 import type { GameState, RoundItem } from '@shared/types';
 
 interface Props {
@@ -27,6 +28,11 @@ interface Props {
    * never disable "Jump forward" or the rest of the turn flow.
    */
   advisorBusy: boolean;
+  /**
+   * A pending nation-op confirm/reject request is in flight. Distinct from
+   * `busy`: it gates only the nation-op dialog controls, never the turn flow.
+   */
+  opBusy: boolean;
   /** Advisor brainstorm suggestions from the last request. */
   advisors: string[];
   /** Queue a free-text action onto the pending round (no turn advance). */
@@ -38,6 +44,14 @@ interface Props {
   onAdvisor: (prompt?: string) => void;
   /** Commit the whole pending round in a single LLM turn. */
   onJump: () => void;
+  /**
+   * Apply a pending nation op: `edits.name` overrides a rename's target name
+   * (or a merge's name); `edits.playerPart` picks the player's successor part
+   * in a split (default 0).
+   */
+  onConfirmNationOp: (index: number, edits?: { name?: string; playerPart?: number }) => void;
+  /** Drop (reject) a pending nation op by its index. */
+  onRejectNationOp: (index: number) => void;
   /**
    * Render without the outer card chrome (the surrounding floating window
    * provides the border and the "Your move" title). Same content, same testids.
@@ -66,12 +80,15 @@ export default function ActionPanel({
   game,
   busy,
   advisorBusy,
+  opBusy,
   advisors,
   onAddAction,
   onAddDiplomacy,
   onRemoveQueueItem,
   onAdvisor,
   onJump,
+  onConfirmNationOp,
+  onRejectNationOp,
   inWindow = false,
 }: Props) {
   const [tab, setTab] = useState('action');
@@ -81,6 +98,8 @@ export default function ActionPanel({
   const [prompt, setPrompt] = useState('');
   // Index of the queued item the user is about to remove, or null (dialog closed).
   const [confirmRemoveIndex, setConfirmRemoveIndex] = useState<number | null>(null);
+  // Whether the nation-op review dialog is open.
+  const [opDialogOpen, setOpDialogOpen] = useState(false);
 
   const others = Object.entries(game.nations)
     .filter(([id]) => id !== game.playerNationId)
@@ -108,6 +127,7 @@ export default function ActionPanel({
   };
 
   const pending = game.pending;
+  const ops = game.pendingNationOps;
   // The item the confirmation dialog is about (re-derived from the live list,
   // so if the queue changes while the dialog is open it tracks the current
   // item at that index — or the dialog closes if the index went out of range).
@@ -325,6 +345,31 @@ export default function ActionPanel({
           </DialogContent>
         </Dialog>
 
+        {/* Pending nation ops proposed by the model — open to confirm or reject. */}
+        {ops.length > 0 && (
+          <button
+            type="button"
+            onClick={() => setOpDialogOpen(true)}
+            disabled={busy}
+            data-testid="nation-op-trigger"
+            className="flex w-full items-center justify-between gap-2 rounded-lg border border-amber-500/30 bg-amber-500/10 p-2.5 text-sm hover:bg-amber-500/15"
+          >
+            <span className="flex items-center gap-2 font-medium text-amber-300">
+              <PenLine className="size-4" />
+              {ops.length} nation {ops.length === 1 ? 'proposal' : 'proposals'} — review
+            </span>
+            <span className="text-xs text-amber-300/70">confirm or reject</span>
+          </button>
+        )}
+        <NationOpDialog
+          game={game}
+          open={opDialogOpen}
+          onOpenChange={setOpDialogOpen}
+          opBusy={opBusy}
+          onConfirm={onConfirmNationOp}
+          onReject={onRejectNationOp}
+        />
+
         <Button className="h-11 w-full" onClick={onJump} disabled={busy} data-testid="jump-forward">
           {busy ? <Loader2 className="size-4 animate-spin" /> : <Radar className="size-4" />}
           {queuedLabel}

src/components/CheckpointReview.tsx

@@ -0,0 +1,278 @@
+import { useState } from 'react';
+import { Check, ListChecks, Loader2, Sparkles } from 'lucide-react';
+import { Badge } from './ui/badge';
+import { Button } from './ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from './ui/card';
+import StatBar from './StatBar';
+import { cn } from '@/lib/utils';
+import { EVENT_COLORS, RELATION_COLORS } from '@/lib/colors';
+import { relationFromScore, type TemplateMeta, type WorldDraft, type WorldNation } from '@shared/scenario';
+
+interface Props {
+  /** The era template the draft was generated from (name/year for the header). */
+  template: TemplateMeta;
+  /** The free-text description the user wrote (shown as the world's context). */
+  description: string;
+  /** The effective start year (template default or the user's override). */
+  year: number;
+  /** The step-1 draft world to review and finalize. */
+  world: WorldDraft;
+  /** The advisor's proposed checkpoints (all approved by default). */
+  checkpoints: string[];
+  /** A finalize (LLM) call is in flight — disables the controls. */
+  busy?: boolean;
+  /** Back to the scenario form (a fresh attempt — the form's state resets). */
+  onBack: () => void;
+  /** Step 2: finalize with the approved checkpoints + the chosen nation to lead. */
+  onFinalize: (approvedCheckpoints: string[], playerNationId: string) => void;
+}
+
+const STAT_BARS: Array<{ key: keyof WorldNation['stats']; label: string }> = [
+  { key: 'military', label: 'Military' },
+  { key: 'economy', label: 'Economy' },
+  { key: 'stability', label: 'Stability' },
+  { key: 'population', label: 'Population' },
+];
+
+/**
+ * "Create scenario" — step 2 of the dynamic path (v0.31, #52). Shows the
+ * generated world (each nation's stats, territory country codes, and
+ * relations; plus any backstory events) and the advisor's proposed
+ * checkpoints as an approve/remove checklist (approved by default — the
+ * approved ones bind the finalize step). The player then picks which nation
+ * to lead (the nation cards mirror NationSelect's pick screen; the draft's
+ * nations are not a static Preset, so they are rendered here directly) and
+ * finalizes. On success the app navigates into the new game; on failure it
+ * toasts and stays here with the current selections intact.
+ */
+export default function CheckpointReview({
+  template,
+  description,
+  year,
+  world,
+  checkpoints,
+  busy = false,
+  onBack,
+  onFinalize,
+}: Props) {
+  // Approve/remove per checkpoint (approved by default — the advisor's list is
+  // a starting point the player prunes, not a form they fill in).
+  const [approved, setApproved] = useState<boolean[]>(() => checkpoints.map(() => true));
+  // The nation the player will lead (none until explicitly picked).
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  const nameOf = (id: string) => world.nations.find((n) => n.id === id)?.name ?? id;
+  const approvedCount = approved.filter(Boolean).length;
+  const selected = selectedId ? world.nations.find((n) => n.id === selectedId) : undefined;
+
+  const toggle = (i: number) =>
+    setApproved((prev) => prev.map((v, j) => (j === i ? !v : v)));
+
+  const finalize = () => {
+    if (!selectedId) return;
+    onFinalize(
+      checkpoints.filter((_, i) => approved[i]),
+      selectedId,
+    );
+  };
+
+  return (
+    <div className="mx-auto max-w-4xl px-6 py-8" data-testid="scenario-review">
+      <Button variant="ghost" size="sm" onClick={onBack} className="mb-4">
+        ← Back to form
+      </Button>
+      <div className="flex items-center gap-3">
+        <h1 className="text-3xl font-bold tracking-tight">{template.name}</h1>
+        <Badge variant="secondary" className="text-sm">
+          {year}
+        </Badge>
+      </div>
+      {description && (
+        <p className="mt-2 max-w-3xl whitespace-pre-line text-sm leading-relaxed text-muted-foreground">
+          {description}
+        </p>
+      )}
+
+      {/* --- The generated world --- */}
+      <h2 className="mb-3 mt-8 text-lg font-semibold">The generated world</h2>
+      <div className="space-y-3">
+        {world.nations.map((n) => (
+          <div
+            key={n.id}
+            className="rounded-lg border border-border/60 bg-card/40 p-3"
+            data-testid="draft-nation"
+            data-nation-id={n.id}
+          >
+            <div className="flex flex-wrap items-center gap-2">
+              <span className="font-medium">{n.name}</span>
+              <Badge variant="secondary" className="text-xs capitalize">
+                {n.type ?? 'major'}
+              </Badge>
+              {n.territory.length > 0 && (
+                <span className="ml-auto text-xs text-muted-foreground">
+                  {n.territory.join(' · ')}
+                </span>
+              )}
+            </div>
+            <div className="mt-2 grid gap-x-6 gap-y-1 sm:grid-cols-2">
+              {STAT_BARS.map(({ key, label }) => (
+                <StatBar key={key} label={label} value={n.stats[key]} />
+              ))}
+            </div>
+            {Object.keys(n.relations).length > 0 && (
+              <div className="mt-2 flex flex-wrap gap-1.5">
+                {Object.entries(n.relations).map(([otherId, score]) => {
+                  const status = relationFromScore(score);
+                  return (
+                    <span
+                      key={otherId}
+                      className="rounded-full border px-2 py-0.5 text-[11px] font-medium"
+                      style={{
+                        color: RELATION_COLORS[status],
+                        borderColor: `${RELATION_COLORS[status]}55`,
+                      }}
+                    >
+                      {nameOf(otherId)} {score > 0 ? `+${score}` : score}
+                    </span>
+                  );
+                })}
+              </div>
+            )}
+          </div>
+        ))}
+
+        {(world.events ?? []).length > 0 && (
+          <div className="rounded-lg border border-border/60 bg-card/40 p-3">
+            <div className="mb-2 text-[11px] font-medium uppercase tracking-wide text-muted-foreground">
+              Backstory
+            </div>
+            <ul className="space-y-2">
+              {(world.events ?? []).map((e, i) => (
+                <li key={i} className="flex items-start gap-2 text-sm" data-testid="draft-event">
+                  <span
+                    className="mt-1.5 inline-block size-2 shrink-0 rounded-full"
+                    style={{ background: EVENT_COLORS[e.type] }}
+                    aria-hidden
+                  />
+                  <span className="min-w-0 flex-1">
+                    <span className="font-medium">{nameOf(e.nation)}:</span>{' '}
+                    {e.title} — {e.text}
+                  </span>
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+      </div>
+
+      {/* --- Advisor checkpoints (approve / remove) --- */}
+      <div className="mt-8 flex items-center gap-2">
+        <ListChecks className="size-4 text-primary" />
+        <h2 className="text-lg font-semibold">Advisor checkpoints</h2>
+        <Badge variant="secondary" className="ml-auto text-xs tabular-nums">
+          {approvedCount} of {checkpoints.length} approved
+        </Badge>
+      </div>
+      <p className="mb-3 mt-1 text-sm leading-relaxed text-muted-foreground">
+        The advisor’s opening read of this world’s live strategic threads. Keep the ones the final
+        world should respect — removed checkpoints are dropped.
+      </p>
+      <ul className="space-y-1.5">
+        {checkpoints.map((c, i) => (
+          <li
+            key={`${i}-${c}`}
+            className={cn(
+              'flex items-center gap-2 rounded-lg border p-2.5 text-sm',
+              approved[i]
+                ? 'border-amber-500/30 bg-amber-500/10'
+                : 'border-border/60 bg-card/30 text-muted-foreground',
+            )}
+            data-testid="checkpoint-item"
+            data-approved={approved[i] ? 'true' : 'false'}
+          >
+            <span
+              className={cn(
+                'inline-flex size-4 shrink-0 items-center justify-center rounded-full border',
+                approved[i] ? 'border-amber-500/50 bg-amber-500/20' : 'border-border',
+              )}
+              aria-hidden
+            >
+              {approved[i] && <Check className="size-3 text-amber-400" />}
+            </span>
+            <span className="min-w-0 flex-1 leading-snug">{c}</span>
+            <Button
+              variant={approved[i] ? 'ghost' : 'secondary'}
+              size="sm"
+              onClick={() => toggle(i)}
+              disabled={busy}
+              data-testid="checkpoint-toggle"
+            >
+              {approved[i] ? 'Remove' : 'Keep'}
+            </Button>
+          </li>
+        ))}
+      </ul>
+
+      {/* --- Choose your nation (cards mirror NationSelect's pick screen) --- */}
+      <h2 className="mb-3 mt-8 text-lg font-semibold">Choose your nation</h2>
+      <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+        {world.nations.map((n) => {
+          const isSel = n.id === selectedId;
+          return (
+            <Card
+              key={n.id}
+              className={cn(
+                'flex flex-col transition',
+                isSel ? 'ring-2 ring-primary/60' : 'hover:ring-1 hover:ring-primary/40',
+              )}
+              data-testid="scenario-nation-card"
+              data-nation-id={n.id}
+              data-selected={isSel ? 'true' : 'false'}
+            >
+              <CardHeader>
+                <CardTitle className="flex items-center gap-2 text-base">
+                  {n.name}
+                  {isSel && <Check className="size-4 shrink-0 text-primary" />}
+                </CardTitle>
+                <CardDescription>
+                  {n.type ?? 'major'} · {n.territory.length} territory unit
+                  {n.territory.length === 1 ? '' : 's'} ({n.territory.join(', ')})
+                </CardDescription>
+              </CardHeader>
+              <CardContent className="mt-auto space-y-1.5">
+                {STAT_BARS.map(({ key, label }) => (
+                  <StatBar key={key} label={label} value={n.stats[key]} />
+                ))}
+                <Button
+                  className="mt-3 w-full"
+                  variant={isSel ? 'default' : 'secondary'}
+                  onClick={() => setSelectedId(n.id)}
+                  disabled={busy}
+                  data-testid="scenario-lead-nation"
+                >
+                  {isSel ? 'Leading' : `Play as ${n.name}`}
+                </Button>
+              </CardContent>
+            </Card>
+          );
+        })}
+      </div>
+
+      {/* --- Finalize --- */}
+      <div
+        className="mt-8 flex flex-wrap items-center justify-between gap-3 rounded-xl border border-primary/30 bg-primary/5 p-3"
+        data-testid="finalize-bar"
+      >
+        <span className="min-w-0 flex-1 text-sm text-muted-foreground">
+          {selected
+            ? `Finalizing as ${selected.name} with ${approvedCount} of ${checkpoints.length} checkpoints approved.`
+            : 'Pick the nation you will lead, then finalize the scenario.'}
+        </span>
+        <Button className="shrink-0" onClick={finalize} disabled={busy || !selected} data-testid="finalize-scenario">
+          {busy ? <Loader2 className="size-4 animate-spin" /> : <Sparkles className="size-4" />}
+          {busy ? 'Finalizing…' : 'Finalize scenario'}
+        </Button>
+      </div>
+    </div>
+  );
+}

src/components/NationOpDialog.tsx

@@ -0,0 +1,307 @@
+import { useState } from 'react';
+import { Check, Loader2, PenLine, X } from 'lucide-react';
+import { Button } from './ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from './ui/dialog';
+import { Input } from './ui/input';
+import { Badge } from './ui/badge';
+import type { GameState } from '@shared/types';
+import type { NationOp, RenameOp } from '@shared/protocol';
+
+interface Props {
+  game: GameState;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** A confirm/reject request is in flight — disable the per-op controls. */
+  opBusy: boolean;
+  /**
+   * Apply a pending op: `edits.name` overrides a rename's target name (or the
+   * merged name for a merge); `edits.playerPart` picks which new part the
+   * player's nation becomes in a split (default 0).
+   */
+  onConfirm: (index: number, edits?: { name?: string; playerPart?: number }) => void;
+  /** Drop a pending op (reject / dismiss). */
+  onReject: (index: number) => void;
+}
+
+/** A short, display-safe description of a pending nation op. */
+function describeOp(op: NationOp, name: (ref: string) => string): string {
+  if (op.kind === 'rename') return `Rename ${name(op.nationRef)} to “${op.to}”`;
+  if (op.kind === 'split')
+    return `Split ${name(op.nationRef)} into ${op.parts.length} nations (${op.parts
+      .map((p) => p.name)
+      .join(', ')})`;
+  return `Merge ${op.nationRefs.map(name).join(' + ')} into “${op.into}”`;
+}
+
+/**
+ * Reviews the nation ops the LLM has proposed (stored in `pendingNationOps`)
+ * and lets the player apply ("LLM proposes, player confirms") or drop each one:
+ * a rename shows the proposed name in an editable field; a split lists the
+ * proposed parts (with the number of regions each is assigned) and, when the
+ * split parent is the player's own nation, radio buttons to pick which new
+ * part the player leads; a merge shows the input nations (the survivor
+ * highlighted) and an editable name for the merged state (default `into`).
+ */
+export default function NationOpDialog({
+  game,
+  open,
+  onOpenChange,
+  opBusy,
+  onConfirm,
+  onReject,
+}: Props) {
+  const ops = game.pendingNationOps;
+  const name = (ref: string) => game.nations[ref]?.name ?? ref;
+  // Resolve a nation ref the way the server does (id first, then a unique
+  // case-insensitive name; null when unknown/ambiguous) — UI hints only, the
+  // server stays authoritative.
+  const resolveRef = (ref: string): string | null => {
+    const r = (ref ?? '').trim();
+    if (!r) return null;
+    if (game.nations[r]) return r;
+    const matches = Object.values(game.nations).filter(
+      (n) => n.name.trim().toLowerCase() === r.toLowerCase(),
+    );
+    return matches.length === 1 ? matches[0].id : null;
+  };
+  // The player's edits, keyed by pending-op index: the rename/merge target
+  // name (an unset entry means "use the model's proposed name"), and which
+  // split part the player succeeds to (preselected 0 — the radio is
+  // "required" and always has a valid answer).
+  const [edits, setEdits] = useState<Record<number, string>>({});
+  const [playerParts, setPlayerParts] = useState<Record<number, number>>({});
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-lg" data-testid="nation-op-dialog">
+        <DialogHeader>
+          <DialogTitle>
+            <span className="flex items-center gap-2">
+              <PenLine className="size-4 text-primary" />
+              Nation proposals
+            </span>
+          </DialogTitle>
+          <DialogDescription>
+            The model proposed changes to nations. Confirm to apply them (you can edit a
+            name and choose your successor state in a split) or reject to leave the world
+            as it is.
+          </DialogDescription>
+        </DialogHeader>
+
+        {ops.length === 0 ? (
+          <p className="py-2 text-sm text-muted-foreground" data-testid="nation-op-empty">
+            Nothing pending — the model hasn’t proposed any nation changes.
+          </p>
+        ) : (
+          <ul className="max-h-[50vh] space-y-2.5 overflow-y-auto pr-1" data-testid="nation-op-list">
+            {ops.map((op, i) => {
+              const isRename = op.kind === 'rename';
+              const isSplit = op.kind === 'split';
+              const isMerge = op.kind === 'merge';
+              const finalName = isRename ? (edits[i] ?? (op as RenameOp).to).trim() : '';
+              // Split: is the parent the player's own nation? (the successor radio
+              // is offered only in that case — the engine ignores playerPart otherwise)
+              const splitParentIsPlayer =
+                isSplit && resolveRef((op as { nationRef: string }).nationRef) === game.playerNationId;
+              const playerPart = playerParts[i] ?? 0;
+              // Merge: the survivor (highlighted) and whether the proposal is
+              // even valid (2+ distinct inputs; the survivor among them).
+              const survivorId = isMerge ? resolveRef((op as { survivingRef: string }).survivingRef) : null;
+              const inputIds = isMerge
+                ? new Set(
+                    (op as { nationRefs: string[] }).nationRefs
+                      .map(resolveRef)
+                      .filter((x): x is string => x !== null),
+                  )
+                : new Set<string>();
+              const mergeValid =
+                !isMerge || (inputIds.size >= 2 && (survivorId !== null && inputIds.has(survivorId)));
+              const mergeName = isMerge ? (edits[i] ?? (op as { into: string }).into).trim() : '';
+
+              const confirm = () => {
+                if (isRename) onConfirm(i, finalName ? { name: finalName } : undefined);
+                else if (isMerge) onConfirm(i, mergeName ? { name: mergeName } : undefined);
+                else onConfirm(i, splitParentIsPlayer ? { playerPart } : undefined);
+              };
+
+              return (
+                <li
+                  key={`${i}-${op.kind}`}
+                  className="rounded-lg border border-border/70 bg-card/50 p-3"
+                  data-testid="nation-op-item"
+                  data-kind={op.kind}
+                >
+                  <div className="mb-2 flex items-start gap-2">
+                    <Badge variant="secondary" className="shrink-0 text-[11px] capitalize">
+                      {op.kind}
+                    </Badge>
+                    <span className="min-w-0 flex-1 text-sm leading-snug">
+                      {describeOp(op, name)}
+                    </span>
+                  </div>
+
+                  {isRename ? (
+                    <div className="space-y-2.5">
+                      <Input
+                        value={edits[i] ?? (op as RenameOp).to}
+                        onChange={(e) => setEdits((p) => ({ ...p, [i]: e.target.value }))}
+                        placeholder="New name…"
+                        data-testid="nation-op-name-input"
+                      />
+                      <div className="flex justify-end gap-2">
+                        <Button
+                          variant="ghost"
+                          size="sm"
+                          onClick={() => onReject(i)}
+                          disabled={opBusy}
+                          className="text-muted-foreground hover:text-destructive"
+                          data-testid="nation-op-reject"
+                        >
+                          <X className="size-3.5" />
+                          Reject
+                        </Button>
+                        <Button
+                          size="sm"
+                          onClick={confirm}
+                          disabled={opBusy}
+                          data-testid="nation-op-confirm"
+                        >
+                          {opBusy ? <Loader2 className="size-3.5 animate-spin" /> : <Check className="size-3.5" />}
+                          Confirm
+                        </Button>
+                      </div>
+                    </div>
+                  ) : isSplit ? (
+                    <div className="space-y-2.5">
+                      <div className="space-y-1">
+                        {(op as { parts: { name: string; territory?: string[] }[] }).parts.map((p, pi) => (
+                          <div
+                            key={pi}
+                            className="flex items-center gap-2 text-sm"
+                            data-testid="nation-op-part"
+                            data-part={pi}
+                          >
+                            {splitParentIsPlayer ? (
+                              <input
+                                type="radio"
+                                name={`player-part-${i}`}
+                                checked={playerPart === pi}
+                                onChange={() => setPlayerParts((prev) => ({ ...prev, [i]: pi }))}
+                                disabled={opBusy}
+                                className="size-3.5 shrink-0 accent-amber-400"
+                                aria-label={`Make ${p.name} the player's successor state`}
+                                data-testid="nation-op-player-part"
+                              />
+                            ) : (
+                              <span className="size-3.5 shrink-0" aria-hidden />
+                            )}
+                            <span className="min-w-0 flex-1 truncate">{p.name}</span>
+                            <span className="shrink-0 text-[11px] tabular-nums text-muted-foreground">
+                              {p.territory?.length ?? 0} region{(p.territory?.length ?? 0) === 1 ? '' : 's'}
+                            </span>
+                          </div>
+                        ))}
+                      </div>
+                      {splitParentIsPlayer && (
+                        <p className="text-[11px] text-muted-foreground" data-testid="nation-op-split-hint">
+                          Choose which new state you will lead after the split.
+                        </p>
+                      )}
+                      {(op as { parts: unknown[] }).parts.length < 2 && (
+                        <p className="text-[11px] text-muted-foreground">
+                          This split names fewer than two parts — confirming will dismiss it
+                          without changing the world.
+                        </p>
+                      )}
+                      <div className="flex justify-end gap-2">
+                        <Button
+                          variant="ghost"
+                          size="sm"
+                          onClick={() => onReject(i)}
+                          disabled={opBusy}
+                          className="text-muted-foreground hover:text-destructive"
+                          data-testid="nation-op-reject"
+                        >
+                          <X className="size-3.5" />
+                          Reject
+                        </Button>
+                        <Button
+                          size="sm"
+                          onClick={confirm}
+                          disabled={opBusy}
+                          data-testid="nation-op-confirm"
+                        >
+                          {opBusy ? <Loader2 className="size-3.5 animate-spin" /> : <Check className="size-3.5" />}
+                          Confirm
+                        </Button>
+                      </div>
+                    </div>
+                  ) : (
+                    <div className="space-y-2.5">
+                      <div className="flex flex-wrap gap-1.5">
+                        {(op as { nationRefs: string[] }).nationRefs.map((ref, ri) => {
+                          const isSurvivor = resolveRef(ref) === survivorId;
+                          return (
+                            <Badge
+                              key={ri}
+                              variant={isSurvivor ? 'default' : 'secondary'}
+                              className="text-[11px]"
+                              data-testid="nation-op-input"
+                            >
+                              {name(ref)}
+                              {isSurvivor ? ' (survivor)' : ''}
+                            </Badge>
+                          );
+                        })}
+                      </div>
+                      <Input
+                        value={edits[i] ?? (op as { into: string }).into}
+                        onChange={(e) => setEdits((p) => ({ ...p, [i]: e.target.value }))}
+                        placeholder="New name…"
+                        data-testid="nation-op-name-input"
+                      />
+                      {!mergeValid && (
+                        <p className="text-[11px] text-muted-foreground">
+                          This merge is not valid as proposed — confirming will dismiss it
+                          without changing the world.
+                        </p>
+                      )}
+                      <div className="flex justify-end gap-2">
+                        <Button
+                          variant="ghost"
+                          size="sm"
+                          onClick={() => onReject(i)}
+                          disabled={opBusy}
+                          className="text-muted-foreground hover:text-destructive"
+                          data-testid="nation-op-reject"
+                        >
+                          <X className="size-3.5" />
+                          Reject
+                        </Button>
+                        <Button
+                          size="sm"
+                          onClick={confirm}
+                          disabled={opBusy}
+                          data-testid="nation-op-confirm"
+                        >
+                          {opBusy ? <Loader2 className="size-3.5 animate-spin" /> : <Check className="size-3.5" />}
+                          Confirm
+                        </Button>
+                      </div>
+                    </div>
+                  )}
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}

src/components/PresetPicker.tsx

@@ -1,5 +1,5 @@
 import { useState } from 'react';
-import { Play, Trash2 } from 'lucide-react';
+import { Play, Sparkles, Trash2 } from 'lucide-react';
 import { Badge } from './ui/badge';
 import { Button } from './ui/button';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from './ui/card';
@@ -26,6 +26,12 @@ interface Props {
   onResume?: (id: string) => void;
   /** Delete a saved game by id (confirmed by a dialog in this component). */
   onDelete?: (id: string) => void;
+  /**
+   * (v0.31, #52) Open the "Create scenario" path (era template + description →
+   * AI-generated world → checkpoint review → a normal game). Omitted = the
+   * create-scenario card is hidden.
+   */
+  onCreateScenario?: () => void;
 }
 
 /**
@@ -41,6 +47,7 @@ export default function PresetPicker({
   activeGameId,
   onResume,
   onDelete,
+  onCreateScenario,
 }: Props) {
   const activeGame = activeGameId ? savedGames.find((g) => g.id === activeGameId) : undefined;
   // The game awaiting a delete confirmation (null = dialog closed).
@@ -83,6 +90,51 @@ export default function PresetPicker({
       )}
 
       <div className="grid gap-5 sm:grid-cols-2 lg:grid-cols-3">
+        {(
+          onCreateScenario
+            ? [
+                {
+                  // (v0.31, #52) The dynamic path, first in the grid: it is the
+                  // "any world you can describe" card, distinct from the static presets.
+                  id: 'create',
+                  title: 'Create scenario',
+                  summary:
+                    'Design your own world — pick an era, describe it, and the AI drafts the world and the advisor’s opening checkpoints for your review before you pick a nation to lead.',
+                  badge: 'custom world',
+                },
+              ]
+            : []
+        ).map((c) => (
+          <Card
+            key={c.id}
+            className="flex flex-col border-primary/40 bg-primary/5 transition hover:ring-1 hover:ring-primary/50"
+            data-testid="create-scenario-card"
+          >
+            <CardHeader>
+              <div className="flex items-start justify-between gap-2">
+                <CardTitle className="flex items-center gap-2 text-lg">
+                  <Sparkles className="size-4 shrink-0 text-primary" />
+                  {c.title}
+                </CardTitle>
+                <Badge variant="secondary" className="shrink-0 text-xs">
+                  {c.badge}
+                </Badge>
+              </div>
+              <CardDescription className="text-sm leading-relaxed">{c.summary}</CardDescription>
+            </CardHeader>
+            <CardContent className="mt-auto">
+              <Button
+                variant="secondary"
+                className="w-full"
+                onClick={() => onCreateScenario?.()}
+                disabled={loading}
+                data-testid="create-scenario"
+              >
+                Create scenario
+              </Button>
+            </CardContent>
+          </Card>
+        ))}
         {presets.map((p) => (
           <Card
             key={p.id}

src/components/ScenarioForm.tsx

@@ -0,0 +1,197 @@
+import { useEffect, useState } from 'react';
+import { Loader2, Sparkles } from 'lucide-react';
+import { Badge } from './ui/badge';
+import { Button } from './ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from './ui/card';
+import { Input } from './ui/input';
+import { Label } from './ui/label';
+import { Textarea } from './ui/textarea';
+import { cn } from '@/lib/utils';
+import { api } from '@/lib/api';
+import type { TemplateMeta } from '@shared/scenario';
+
+interface Props {
+  /** A generate (LLM) call is in flight — disables the form's controls. */
+  busy?: boolean;
+  onBack: () => void;
+  /**
+   * Step 1: design the draft world + checkpoint list. The form hands over the
+   * selected template's full metadata (the review screen shows its name/year)
+   * plus the description and the effective start year.
+   */
+  onGenerate: (template: TemplateMeta, description: string, year: number) => void;
+}
+
+/** The year input is an empty string ("use the template's default") or a number. */
+const YEAR_MIN = 1000;
+const YEAR_MAX = 3000;
+
+/**
+ * "Create scenario" — step 1 of the dynamic path (v0.31, #52). The user picks
+ * one of the light era templates (a card each: name, default year, blurb),
+ * writes a free-text description of the world they want, and may override the
+ * start year (the field is pre-filled from the selected template; leaving it
+ * empty keeps the template's default). "Generate world" posts the draft
+ * request; on success the app moves to the checkpoint review screen, on
+ * failure it toasts and stays here (the form's local state is preserved).
+ */
+export default function ScenarioForm({ busy = false, onBack, onGenerate }: Props) {
+  const [templates, setTemplates] = useState<TemplateMeta[]>([]);
+  const [templatesError, setTemplatesError] = useState<string | null>(null);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [description, setDescription] = useState('');
+  // Pre-filled from the selected template's default year (the user can edit).
+  const [yearText, setYearText] = useState('');
+
+  // Load the era-template manifest on mount (the form is the only consumer).
+  useEffect(() => {
+    let alive = true;
+    api
+      .listScenarioTemplates()
+      .then((r) => alive && setTemplates(r.templates))
+      .catch((e: unknown) => alive && setTemplatesError(e instanceof Error ? e.message : String(e)));
+    return () => {
+      alive = false;
+    };
+  }, []);
+
+  const selected = templates.find((t) => t.id === selectedId) ?? null;
+  const effectiveYear =
+    yearText.trim() === '' ? NaN : Number.parseInt(yearText.trim(), 10);
+  const yearValid =
+    Number.isInteger(effectiveYear) && effectiveYear >= YEAR_MIN && effectiveYear <= YEAR_MAX;
+
+  const canGenerate = !busy && selected !== null && description.trim() !== '' && yearValid;
+
+  const selectTemplate = (t: TemplateMeta) => {
+    setSelectedId(t.id);
+    // Selecting an era pre-fills the year with that era's default (the user
+    // can still edit it afterwards).
+    setYearText(String(t.year));
+  };
+
+  const generate = () => {
+    if (!canGenerate || !selected) return;
+    onGenerate(selected, description.trim(), effectiveYear);
+  };
+
+  return (
+    <div className="mx-auto max-w-4xl px-6 py-8" data-testid="scenario-form">
+      <Button variant="ghost" size="sm" onClick={onBack} className="mb-4">
+        ← Back to scenarios
+      </Button>
+      <h1 className="text-3xl font-bold tracking-tight">Create a scenario</h1>
+      <p className="mt-2 max-w-2xl text-sm leading-relaxed text-muted-foreground">
+        Design your own world: pick an era, describe what should be true, and the AI will draft the
+        world and an opening set of advisor checkpoints for your review. Nothing is saved until you
+        finalize.
+      </p>
+
+      {/* 1 — the era template (a card each). */}
+      <h2 className="mb-3 mt-8 text-lg font-semibold">
+        1 · Pick an era <span className="font-normal text-muted-foreground">(required)</span>
+      </h2>
+      {templatesError ? (
+        <p className="rounded-lg border border-destructive/40 bg-destructive/10 p-3 text-sm text-destructive">
+          Could not load the era templates: {templatesError}
+        </p>
+      ) : templates.length === 0 ? (
+        <p className="rounded-lg border border-border/60 bg-card/40 p-3 text-sm text-muted-foreground">
+          Loading era templates…
+        </p>
+      ) : (
+        <div className="grid gap-4 sm:grid-cols-3">
+          {templates.map((t) => {
+            const isSel = t.id === selectedId;
+            return (
+              <Card
+                key={t.id}
+                className={cn(
+                  'flex cursor-pointer flex-col transition',
+                  isSel ? 'ring-2 ring-primary/60' : 'hover:ring-1 hover:ring-primary/40',
+                )}
+                data-testid="template-card"
+                data-template-id={t.id}
+                data-selected={isSel ? 'true' : 'false'}
+                onClick={() => selectTemplate(t)}
+              >
+                <CardHeader>
+                  <div className="flex items-start justify-between gap-2">
+                    <CardTitle className="text-base">{t.name}</CardTitle>
+                    <Badge variant="secondary" className="shrink-0 text-xs">
+                      {t.year}
+                    </Badge>
+                  </div>
+                  <CardDescription className="text-sm leading-relaxed">
+                    {t.eraDescription}
+                  </CardDescription>
+                </CardHeader>
+                <CardContent className="mt-auto">
+                  <div
+                    className={cn(
+                      'flex items-center gap-2 text-xs',
+                      isSel ? 'font-medium text-primary' : 'text-muted-foreground',
+                    )}
+                  >
+                    <Sparkles className="size-3.5" />
+                    {isSel ? 'Selected' : 'Start from this era'}
+                  </div>
+                </CardContent>
+              </Card>
+            );
+          })}
+        </div>
+      )}
+
+      {/* 2 — the description (+ optional year override). */}
+      <h2 className="mb-3 mt-8 text-lg font-semibold">
+        2 · Describe your world <span className="font-normal text-muted-foreground">(required)</span>
+      </h2>
+      <div className="space-y-4 rounded-lg border border-border/60 bg-card/40 p-4">
+        <Textarea
+          value={description}
+          onChange={(e) => setDescription(e.target.value)}
+          placeholder="e.g. “A cold-war world where the space race decided the Cold War — two blocs orbit, and the arctic shipping lanes are the new flashpoint.”"
+          rows={4}
+          disabled={busy}
+          data-testid="scenario-description"
+        />
+        <div className="flex items-center gap-3">
+          <Label htmlFor="scenario-year-input" className="shrink-0 text-sm">
+            Start year
+          </Label>
+          <Input
+            id="scenario-year-input"
+            type="number"
+            inputMode="numeric"
+            value={yearText}
+            onChange={(e) => setYearText(e.target.value)}
+            placeholder={selected ? `default ${selected.year}` : 'pick an era first'}
+            min={YEAR_MIN}
+            max={YEAR_MAX}
+            disabled={busy || !selected}
+            className="w-32"
+            data-testid="scenario-year"
+          />
+          <span className="text-xs text-muted-foreground">
+            {yearValid ? `The game begins on ${effectiveYear}-01-01.` : 'Leave empty for the era default, or use a year between 1000 and 3000.'}
+          </span>
+        </div>
+      </div>
+
+      {/* Generate. */}
+      <div className="mt-8">
+        <Button className="h-11 w-full" onClick={generate} disabled={!canGenerate} data-testid="generate-scenario">
+          {busy ? <Loader2 className="size-4 animate-spin" /> : <Sparkles className="size-4" />}
+          {busy ? 'Generating world…' : 'Generate world'}
+        </Button>
+        {busy && (
+          <p className="mt-2 flex items-center justify-center gap-1.5 text-xs text-muted-foreground">
+            <span className="sim-pulse inline-block size-1.5 rounded-full bg-primary" />
+            The world-builder is thinking — this can take a few seconds.
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}

src/components/WorldMap.tsx

@@ -10,12 +10,14 @@ import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?url';
 maplibregl.setWorkerUrl(workerUrl);
 import {
   mapFeatureOwner,
+  MARKER_TYPE_INFO,
+  nationColor,
   regionFillStyle,
   unownedTooltipLabel,
   type RegionMap,
   type RegionOwner,
 } from '@shared/protocol';
-import type { Nation } from '@shared/types';
+import { MARKER_TYPES, type MapMarker, type Nation, type RegionStats } from '@shared/types';
 import { cn } from '@/lib/utils';
 import { idToKey } from '@/lib/regions';
 
@@ -45,8 +47,16 @@ type GeoSource = maplibregl.GeoJSONSource;
 // looked black, and `styledata` was gated on fetching a remote document. An
 // inline object loads instantly, so `isStyleLoaded()` / `styledata` fire
 // immediately and the choropleth is guaranteed to paint. (The OFM `ne2sr`
-// raster has no vector tiles, so no glyphs endpoint is needed — we don't add
-// label layers; the choropleth provides the borders.)
+// raster has no vector tiles, so the basemap itself needs no label layers —
+// the choropleth provides the borders.)
+//
+// No `glyphs` URL: the map needs no MapLibre *text* rendering. The basemap is
+// raster (its labels are baked into the PNG tiles), and the LLM-placed map
+// markers (v0.27, #44) are drawn as canvas-generated icon images in a symbol
+// layer — fully self-contained, so they render offline and deterministically
+// without depending on any external font/glyph endpoint (the OpenFreeMap
+// `fonts/` path is a dead nginx 404, and the basemap's apparent labels come
+// from the raster, not from glyphs).
 const NE2SR_TILES = ['https://tiles.openfreemap.org/natural_earth/ne2sr/{z}/{x}/{y}.png'];
 
 const INLINE_STYLE: maplibregl.StyleSpecification = {
@@ -88,6 +98,8 @@ const PLAYER_LINE = 'player-line';
 const FLASH_LINE = 'flash-line';
 const HOVER_FILL = 'hover-fill';
 const HOVER_LINE = 'hover-line';
+const MARKERS_SOURCE = 'markers';
+const MARKER_SYMBOL = 'markers-symbol';
 
 /** Sensible per-scenario initial camera: Europe for the WWII scenarios, wider for the global ones. */
 function cameraForPreset(presetId: string): { center: [number, number]; zoom: number } {
@@ -195,6 +207,186 @@ function featuresByRegionKeys(
   return { type: 'FeatureCollection', features: JSON.parse(JSON.stringify(features)) };
 }
 
+// --- Map markers (v0.27, #44) ------------------------------------------------
+//
+// The LLM places named point markers (cities, factories, armies, ports,
+// capitals, fleets, rocket sites, gatherings) anchored to a region key. The
+// engine positions each at its region's centroid (deterministic small offset)
+// and recomputes its owner from the region's current owner every turn. The
+// map renders them as a single top-most symbol layer: a per-type glyph
+// character in front of the name, per-type color, dark-theme halo.
+
+/**
+ * The GeoJSON behind the marker symbol layer: one Point per marker at
+ * `[lon, lat]`, carrying the stable id, type, name, its type's glyph, and the
+ * current owner's name + stable color (empty when the region is unowned).
+ * Pure; the caller passes the current marker list + nations record, so a
+ * renamed/removed owner is picked up on the next paint.
+ */
+function buildMarkersFC(markers: MapMarker[], nations: Record<string, Nation>): FeatureCollection {
+  const features = markers.map((m) => {
+    const owner = m.ownerNationId ? nations[m.ownerNationId] : undefined;
+    return {
+      type: 'Feature' as const,
+      geometry: { type: 'Point' as const, coordinates: [m.lon, m.lat] as [number, number] },
+      properties: {
+        id: m.id,
+        type: m.type,
+        name: m.name,
+        glyph: MARKER_TYPE_INFO[m.type]?.glyph ?? '',
+        owner: owner?.name ?? '',
+        ownerId: owner?.id ?? '',
+        ownerColor: owner ? nationColor(owner.id) : '',
+      },
+    };
+  });
+  return { type: 'FeatureCollection', features };
+}
+
+// Small canvas-path helpers for the marker icons (self-contained shapes — no
+// unicode/font dependency, so they render identically in any environment).
+function roundRectPath(
+  ctx: CanvasRenderingContext2D,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+  r: number,
+): void {
+  ctx.beginPath();
+  ctx.moveTo(x + r, y);
+  ctx.lineTo(x + w - r, y);
+  ctx.quadraticCurveTo(x + w, y, x + w, y + r);
+  ctx.lineTo(x + w, y + h - r);
+  ctx.quadraticCurveTo(x + w, y + h, x + w - r, y + h);
+  ctx.lineTo(x + r, y + h);
+  ctx.quadraticCurveTo(x, y + h, x, y + h - r);
+  ctx.lineTo(x, y + r);
+  ctx.quadraticCurveTo(x, y, x + r, y);
+  ctx.closePath();
+}
+
+function starPath(
+  ctx: CanvasRenderingContext2D,
+  cx: number,
+  cy: number,
+  spikes: number,
+  outer: number,
+  inner: number,
+): void {
+  let rot = (Math.PI / 2) * -1;
+  const step = Math.PI / spikes;
+  ctx.beginPath();
+  ctx.moveTo(cx + Math.cos(rot) * outer, cy + Math.sin(rot) * outer);
+  for (let i = 0; i < spikes; i++) {
+    rot += step;
+    ctx.lineTo(cx + Math.cos(rot) * inner, cy + Math.sin(rot) * inner);
+    rot += step;
+    ctx.lineTo(cx + Math.cos(rot) * outer, cy + Math.sin(rot) * outer);
+  }
+  ctx.closePath();
+}
+
+/**
+ * (v0.27, #44) Draw one marker-type icon into an offscreen canvas: a distinct
+ * shape per type, filled with the type's color from the shared
+ * `MARKER_TYPE_INFO` contract, with a dark outline for legibility on any
+ * choropleth fill. Added to the map as a named image and referenced by the
+ * symbol layer's `icon-image` — a real symbol layer, per-type color + form,
+ * with zero external font/glyph dependency.
+ */
+function drawMarkerIcon(type: MapMarker['type']): ImageData {
+  const S = 44;
+  const c = document.createElement('canvas');
+  c.width = S;
+  c.height = S;
+  const ctx = c.getContext('2d')!;
+  const cx = S / 2;
+  const cy = S / 2;
+  ctx.fillStyle = MARKER_TYPE_INFO[type]?.color ?? '#cbd5e1';
+  ctx.strokeStyle = '#0b1220';
+  ctx.lineWidth = 2.5;
+  ctx.lineJoin = 'round';
+  switch (type) {
+    case 'city':
+      ctx.beginPath();
+      ctx.arc(cx, cy, S * 0.3, 0, Math.PI * 2);
+      break;
+    case 'factory': {
+      const h = S * 0.5;
+      roundRectPath(ctx, cx - h / 2, cy - h / 2, h, h, 5);
+      break;
+    }
+    case 'army': {
+      const r = S * 0.34;
+      ctx.beginPath();
+      ctx.moveTo(cx, cy - r);
+      ctx.lineTo(cx + r, cy + r * 0.8);
+      ctx.lineTo(cx - r, cy + r * 0.8);
+      ctx.closePath();
+      break;
+    }
+    case 'port': {
+      const r = S * 0.36;
+      ctx.beginPath();
+      ctx.moveTo(cx, cy - r);
+      ctx.lineTo(cx + r, cy);
+      ctx.lineTo(cx, cy + r);
+      ctx.lineTo(cx - r, cy);
+      ctx.closePath();
+      break;
+    }
+    case 'capital':
+      starPath(ctx, cx, cy, 5, S * 0.36, S * 0.15);
+      break;
+    case 'fleet':
+    case 'gathering':
+      ctx.beginPath();
+      ctx.arc(cx, cy, S * 0.32, 0, Math.PI * 2);
+      break;
+    case 'rocket': {
+      const w = S * 0.14;
+      ctx.beginPath();
+      ctx.moveTo(cx, cy - S * 0.36);
+      ctx.lineTo(cx + S * 0.22, cy - S * 0.04);
+      ctx.lineTo(cx + w, cy - S * 0.04);
+      ctx.lineTo(cx + w, cy + S * 0.34);
+      ctx.lineTo(cx - w, cy + S * 0.34);
+      ctx.lineTo(cx - w, cy - S * 0.04);
+      ctx.lineTo(cx - S * 0.22, cy - S * 0.04);
+      ctx.closePath();
+      break;
+    }
+  }
+  ctx.fill();
+  ctx.stroke();
+  // fleet and gathering share a circle base; an inner mark tells them apart
+  // (fleet = a dark porthole dot, gathering = a white bullseye dot).
+  if (type === 'fleet' || type === 'gathering') {
+    ctx.beginPath();
+    ctx.arc(cx, cy, S * 0.13, 0, Math.PI * 2);
+    ctx.fillStyle = type === 'fleet' ? '#0b1220' : '#ffffff';
+    ctx.fill();
+  }
+  // Hand MapLibre the raw pixels (an untainted canvas, so getImageData is safe)
+  // rather than the canvas element — `addImage` accepts ImageData directly.
+  return ctx.getImageData(0, 0, S, S);
+}
+
+/** The hover tooltip for a marker: its type label + name, then the owner chip. */
+function markerTooltipHtml(
+  type: string,
+  name: string,
+  owner: string,
+  ownerColor: string,
+): string {
+  const label = MARKER_TYPE_INFO[type as MapMarker['type']]?.label ?? 'Marker';
+  const ownerLine = owner
+    ? `<div class="hm-popup-owner"><span class="hm-chip" style="background:${ownerColor}"></span>${esc(owner)}</div>`
+    : '<div class="hm-popup-sub">No owner</div>';
+  return `<div class="hm-popup"><div class="hm-popup-title">${esc(label)}: ${esc(name)}</div>${ownerLine}</div>`;
+}
+
 const esc = (s: string) =>
   s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c] as string));
 
@@ -218,11 +410,29 @@ function hoverHtml(
   region?: RegionOwner,
   nation?: Nation,
   noMansLand = false,
+  regionKey?: string,
+  regionStats?: Record<string, RegionStats>,
 ): string {
   if (!region || !nation) {
     return `<div class="hm-popup"><div class="hm-popup-title">${esc(subRegionName || 'Unclaimed')}</div><div class="hm-popup-sub">${unownedTooltipLabel(noMansLand)}</div></div>`;
   }
-  const stats = [statRow('Mil', nation.stats.military), statRow('Eco', nation.stats.economy)].join('');
+  // (v0.29, #46 PR 2) The region's OWN per-region stats (not the nation's
+  // derived aggregate), looked up by region key. When the region has no stats
+  // entry (defensive — an owned region should always have one) every stat
+  // shows a placeholder dash. The dossier (NationPanel) still shows the
+  // nation's derived stats, so this tooltip is the one place a single region's
+  // numbers are visible on the map.
+  const rs = regionKey ? regionStats?.[regionKey] : undefined;
+  const row = (label: string, v?: number): string =>
+    rs == null
+      ? `<div class="hm-stat"><span class="hm-stat-k">${label}</span><span class="hm-stat-v">–</span></div>`
+      : statRow(label, v);
+  const stats = [
+    row('Mil', rs?.military),
+    row('Eco', rs?.economy),
+    row('Stab', rs?.stability),
+    row('Pop', rs?.population),
+  ].join('');
   return `<div class="hm-popup">
     <div class="hm-popup-title">${esc(subRegionName || region.owner)}</div>
     <div class="hm-popup-owner"><span class="hm-chip" style="background:${region.color}"></span>${esc(region.owner)}</div>
@@ -254,6 +464,21 @@ interface Props {
    * component doc for the full behavior.
    */
   onFocusNation?: (id: string, info?: { name?: string }) => void;
+  /**
+   * (v0.27, #44) The game's named map markers (`GameState.markers`): the LLM
+   * places/removes them over time, the engine positions each at its region's
+   * centroid and keeps its owner in sync with the region's owner. Rendered as
+   * a top-most symbol layer (per-type glyph + name, per-type color).
+   */
+  markers?: MapMarker[];
+  /**
+   * (v0.29, #46 PR 2) The game's per-region stats (`GameState.regionStats`,
+   * keyed by region key). Used only by the hover tooltip to show a single
+   * region's own four 0–100 stats (a region with no entry shows placeholders).
+   * The dossier (NationPanel) is unaffected — it keeps the nation's derived
+   * stats.
+   */
+  regionStats?: Record<string, RegionStats>;
 }
 
 /**
@@ -286,6 +511,18 @@ interface Props {
  * a plain "No owner" sub-line. The colors/labels come from the shared
  * `regionFillStyle` / `unownedTooltipLabel` contract in @shared/protocol.
  *
+ * (v0.27, #44) LLM-placed **map markers** (`markers` prop = `GameState.markers`)
+ * render on a top-most symbol layer: each is its type's canvas-generated icon
+ * (a distinct shape, per-type color from the shared `MARKER_TYPE_INFO`
+ * contract, dark-outlined) at the engine-derived position (region centroid +
+ * small deterministic offset). The icons are drawn into named map images
+ * (`marker-<type>`), so there is no external font/glyph dependency and markers
+ * render offline and deterministically. Hovering a marker shows a tooltip
+ * (type label + name + owner chip); clicking one switches the dossier to the
+ * owning nation (no-op when the marker's region is unowned). The region
+ * hover/click handlers detect a marker under the cursor (MapLibre layer events
+ * have no propagation) and act on the marker's data.
+ *
  * Zoom and pan are driven directly by the user (MapLibre wheel/trackpad + drag)
  * — no floating control and no external API.
  */
@@ -297,6 +534,8 @@ export default function WorldMap({
   className,
   unowned,
   onFocusNation,
+  markers,
+  regionStats,
 }: Props) {
   const containerRef = useRef<HTMLDivElement>(null);
   const mapRef = useRef<maplibregl.Map | null>(null);
@@ -311,12 +550,17 @@ export default function WorldMap({
   const presetRef = useRef(presetId);
   const unownedRef = useRef<Set<string>>(new Set(unowned ?? []));
   const onFocusNationRef = useRef(onFocusNation);
+  const markersRef = useRef<MapMarker[]>(markers ?? []);
+  // (v0.29, #46 PR 2) latest per-region stats, for the hover tooltip.
+  const regionStatsRef = useRef<Record<string, RegionStats>>(regionStats ?? {});
   regionsRef.current = regions;
   nationsRef.current = nations;
   playerRef.current = playerNationId;
   presetRef.current = presetId;
   unownedRef.current = new Set(unowned ?? []);
   onFocusNationRef.current = onFocusNation;
+  markersRef.current = markers ?? [];
+  regionStatsRef.current = regionStats ?? {};
 
   // Diffing state for the transient territory-change flash (owned by this component
   // so a resync with identical data never re-flashes).
@@ -424,6 +668,39 @@ export default function WorldMap({
     const onHover = (e: maplibregl.MapLayerMouseEvent) => {
       const f = e.features?.[0];
       if (!f) return;
+      // (v0.27, #44) A marker rendered on top of this region wins the hover.
+      // The region polygon is always beneath a marker, so this FILL_LAYER
+      // delegate fires in both cases; if a marker icon is under the cursor,
+      // show the marker's tooltip (name + type + owner) instead of the
+      // region's. `e.point` is the cursor's pixel position, so querying the
+      // marker layer there tests the icon's (small) hit area, not the whole
+      // region.
+      const markerHits = map.queryRenderedFeatures(e.point, { layers: [MARKER_SYMBOL] });
+      if (markerHits.length > 0) {
+        const mp = (markerHits[0].properties ?? {}) as {
+          type?: string;
+          name?: string;
+          owner?: string;
+          ownerColor?: string;
+        };
+        hoverPopup
+          .setLngLat(e.lngLat)
+          .setHTML(
+            markerTooltipHtml(
+              typeof mp.type === 'string' ? mp.type : '',
+              typeof mp.name === 'string' ? mp.name : '',
+              typeof mp.owner === 'string' ? mp.owner : '',
+              typeof mp.ownerColor === 'string' ? mp.ownerColor : '',
+            ),
+          )
+          .addTo(map);
+        map.getCanvas().style.cursor = 'pointer';
+        // A marker has no region outline to highlight; clear the previous one
+        // (and reset lastHoverId so moving back onto a region re-triggers it).
+        lastHoverId = null;
+        (map.getSource(HOVER_SOURCE) as GeoSource | undefined)?.setData(emptyFC());
+        return;
+      }
       const p = f.properties as { name?: string; regionId?: string };
       const subId = typeof p?.regionId === 'string' ? p.regionId : '';
       if (subId && subId !== lastHoverId) {
@@ -442,11 +719,11 @@ export default function WorldMap({
       // (v0.22, #16 P3) whether this region is no man's land (released
       // mid-game), so the ownerless tooltip can say so.
       const pKey = f.properties?.regionKey;
-      const noMansLand =
-        !region && typeof pKey === 'string' && pKey !== '' && unownedRef.current.has(pKey);
+      const keyStr = typeof pKey === 'string' && pKey !== '' ? pKey : undefined;
+      const noMansLand = !region && keyStr !== undefined && unownedRef.current.has(keyStr);
       hoverPopup
         .setLngLat(e.lngLat)
-        .setHTML(hoverHtml(p?.name ?? subId, region, nation, noMansLand))
+        .setHTML(hoverHtml(p?.name ?? subId, region, nation, noMansLand, keyStr, regionStatsRef.current))
         .addTo(map);
       map.getCanvas().style.cursor = 'pointer';
     };
@@ -466,6 +743,19 @@ export default function WorldMap({
     const onClick = (e: maplibregl.MapLayerMouseEvent) => {
       const f = e.features?.[0];
       if (!f) return;
+      // (v0.27, #44) A marker under the cursor: focus its owning nation
+      // (identical to its region's owner — the engine keeps a marker's owner in
+      // sync with the region) and carry the marker's name into the dossier.
+      const markerHits = map.queryRenderedFeatures(e.point, { layers: [MARKER_SYMBOL] });
+      if (markerHits.length > 0) {
+        const mp = (markerHits[0].properties ?? {}) as { ownerId?: string; name?: string };
+        const owner = typeof mp.ownerId === 'string' ? mp.ownerId : '';
+        if (owner) {
+          const info = typeof mp.name === 'string' ? { name: mp.name } : undefined;
+          onFocusNationRef.current?.(owner, info);
+        }
+        return;
+      }
       const region = mapFeatureOwner(regionsRef.current, f);
       if (!region?.ownerId) return;
       // Carry the clicked sub-region's name so the dossier can show which region
@@ -497,6 +787,9 @@ export default function WorldMap({
       if (!map.getSource(FLASH_SOURCE)) {
         map.addSource(FLASH_SOURCE, { type: 'geojson', data: emptyFC() });
       }
+      if (!map.getSource(MARKERS_SOURCE)) {
+        map.addSource(MARKERS_SOURCE, { type: 'geojson', data: emptyFC() });
+      }
     };
 
     // Stamp ownership + colors onto the regions source (no-op until both the
@@ -509,6 +802,26 @@ export default function WorldMap({
       src.setData(applyRegions(geo, regionsRef.current, playerRef.current, idKey, unownedRef.current));
     };
 
+    // Stamp the current markers onto the marker source (v0.27, #44).
+    const paintMarkers = () => {
+      const src = map.getSource(MARKERS_SOURCE) as GeoSource | undefined;
+      if (!src) return;
+      src.setData(buildMarkersFC(markersRef.current, nationsRef.current));
+    };
+
+    // Register the eight canvas-generated marker-type icon images (v0.27, #44).
+    // Images are cleared on a style (re)load, so this is (re)run from
+    // `ensureLayers` (which fires on every `styledata`). Self-contained — no
+    // external font/glyph endpoint — so markers render offline and
+    // deterministically.
+    const ensureMarkerImages = async () => {
+      for (const type of MARKER_TYPES) {
+        const id = `marker-${type}`;
+        if (map.getImage(id)) continue;
+        await map.addImage(id, drawMarkerIcon(type));
+      }
+    };
+
     const ensureLayers = async () => {
       if (cancelled) return;
       ensureSources();
@@ -528,6 +841,7 @@ export default function WorldMap({
       }
       if (cancelled) return;
       paintRegions();
+      paintMarkers();
       if (!map.getLayer(FILL_LAYER)) {
         // The choropleth is the star: a high opacity so the vivid per-nation
         // colors read clearly even on the dark background / over the terrain.
@@ -554,8 +868,9 @@ export default function WorldMap({
       }
       // NOTE: layers are added in bottom→top order (each appends on top). The
       // stack is: fill, base borders, player border, territory-change flash,
-      // hover brighten, hover outline. Do not use a `beforeId` here — it throws
-      // if that layer does not exist yet on a fresh style load.
+      // hover brighten, hover outline, and (top-most) the LLM-placed map
+      // markers' symbol layer (v0.27, #44). Do not use a `beforeId` here — it
+      // throws if that layer does not exist yet on a fresh style load.
       if (!map.getLayer(PLAYER_LINE)) {
         map.addLayer({
           id: PLAYER_LINE,
@@ -589,6 +904,36 @@ export default function WorldMap({
           paint: { 'line-color': '#ffffff', 'line-width': 1.6, 'line-opacity': 0.9 },
         });
       }
+      // (v0.27, #44) The LLM-placed map markers: a top-most symbol layer.
+      // Each marker renders its type's canvas-generated icon (a distinct shape,
+      // per-type color from the shared MARKER_TYPE_INFO contract) with a dark
+      // outline for legibility on any choropleth fill. The icon images are
+      // self-contained (no external font/glyph endpoint), so markers render
+      // offline and deterministically. `icon-image` is `marker-<type>`, the
+      // named canvas images registered by `ensureMarkerImages` above.
+      await ensureMarkerImages();
+      if (!map.getLayer(MARKER_SYMBOL)) {
+        map.addLayer({
+          id: MARKER_SYMBOL,
+          type: 'symbol',
+          source: MARKERS_SOURCE,
+          layout: {
+            'icon-image': ['concat', 'marker-', ['get', 'type']],
+            'icon-size': 0.8,
+            'icon-allow-overlap': true,
+            'icon-ignore-placement': true,
+          },
+        });
+      }
+      // Marker interactions: the markers sit above the choropleth, but they
+      // deliberately share the region (FILL_LAYER) handlers registered below.
+      // MapLibre layer-scoped events are independent per-layer delegates (no
+      // propagation, no stopPropagation), so a marker-on-region would fire
+      // both a marker and a region handler. Instead the region handlers detect
+      // a marker under the cursor (see onHover/onClick) and act on the
+      // marker's data; clicking a marker focuses its owning nation via the
+      // same path as clicking its region (the marker's owner == its region's
+      // owner).
       map.off('mousemove', FILL_LAYER, onHover);
       map.off('mouseout', FILL_LAYER, onHoverOut);
       map.off('click', FILL_LAYER, onClick);
@@ -646,6 +991,19 @@ export default function WorldMap({
     }
   }, [regions, playerNationId, unowned]);
 
+  // (v0.27, #44) Repaint the marker symbol layer whenever the marker list
+  // changes (a turn placed/removed markers) or the nations record changes
+  // (a confirmed rename/merge changes an owner's display name). No-op until
+  // the map + source exist (the mount effect's ensureLayers applies the
+  // current data once the layer structure is in place).
+  useEffect(() => {
+    const map = mapRef.current;
+    if (!map) return;
+    const src = map.getSource(MARKERS_SOURCE) as GeoSource | undefined;
+    if (!src) return;
+    src.setData(buildMarkersFC(markers ?? [], nations));
+  }, [markers, nations]);
+
   // Full-viewport, edge-to-edge background layer. `position: fixed` is set
   // inline because MapLibre's own stylesheet sets `.maplibregl-map` to
   // `position: relative`, which would otherwise win over a Tailwind class.

src/lib/api.ts

@@ -6,12 +6,21 @@ import type {
   AddActionResponse,
   AddDiplomacyResponse,
   AdvisorResponse,
+  ConfirmNationOpResponse,
   CreateGameResponse,
   DeleteGameResponse,
   GameSummary,
+  RejectNationOpResponse,
   RemoveQueueItemResponse,
   TurnResponse,
 } from '@shared/protocol';
+import type {
+  ScenarioCommitRequest,
+  ScenarioCommitResponse,
+  ScenarioDraftRequest,
+  ScenarioDraftResponse,
+  TemplateMeta,
+} from '@shared/scenario';
 
 async function req<T>(path: string, init?: RequestInit): Promise<T> {
   const res = await fetch(path, {
@@ -60,6 +69,24 @@ export const api = {
       method: 'POST',
       body: JSON.stringify({ index }),
     }),
+  // (v0.23, #16 P4a; v0.24, #16 P4b) Confirm a pending nation-op proposal by
+  // its index in `game.pendingNationOps`: a rename takes effect (`edits.name`
+  // overrides the proposed name), a split partitions the nation's territory
+  // (`edits.playerPart` picks which part the player leads, default 0), and a
+  // merge folds its inputs into the survivor (`edits.name` overrides the
+  // merged name). Fast, non-LLM — no turn advance. Returns the updated game.
+  confirmNationOp: (id: string, index: number, edits?: { name?: string; playerPart?: number }) =>
+    req<ConfirmNationOpResponse>(`/api/games/${id}/nation-op/confirm`, {
+      method: 'POST',
+      body: JSON.stringify({ index, ...(edits ? { edits } : {}) }),
+    }),
+  // (v0.23, #16 P4a) Reject (drop) a pending nation-op proposal by index,
+  // without applying it. Fast, non-LLM — no turn advance. Returns the updated game.
+  rejectNationOp: (id: string, index: number) =>
+    req<RejectNationOpResponse>(`/api/games/${id}/nation-op/reject`, {
+      method: 'POST',
+      body: JSON.stringify({ index }),
+    }),
   // Commit the whole pending round (or an empty one) in a single LLM turn.
   jump: (id: string) =>
     req<TurnResponse>(`/api/games/${id}/jump`, {
@@ -75,4 +102,24 @@ export const api = {
     req<{ regions: Record<string, { color: string; owner: string; ownerId: string }> }>(
       `/api/games/${id}/map`,
     ),
+  // --- Dynamic scenario generation (v0.31, #52) ---------------------------
+  // The additive "Create scenario" path: a two-step LLM flow (design a draft
+  // world + checkpoint list, then finalize it into a saved, playable game).
+  // The era-template manifest for the form's cards (id / name / year / blurb).
+  listScenarioTemplates: () => req<{ templates: TemplateMeta[] }>('/api/scenarios/templates'),
+  // Step 1: design a draft world + an advisor checkpoint list from an era
+  // template + a free-text description. An LLM call — can be slow; a 502
+  // means the model is down or returned nothing usable (the caller toasts).
+  draftScenario: (body: ScenarioDraftRequest) =>
+    req<ScenarioDraftResponse>('/api/scenarios/draft', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    }),
+  // Step 2: finalize the approved draft (constrained to the approved
+  // checkpoints) into a new, playable game and save it. Returns the id.
+  commitScenario: (body: ScenarioCommitRequest) =>
+    req<ScenarioCommitResponse>('/api/scenarios/commit', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    }),
 };

src/lib/colors.ts

@@ -26,6 +26,9 @@ export const OUTCOME_COLORS: Record<EventOutcome, string> = {
   failure: '#ef4444',
   partial: '#f59e0b',
   neutral: '#94a3b8',
+  // (v0.30, #50) engine-emitted "invasion repelled" — a muted, darker red so it
+  // reads as a defensive failure distinct from a bright outright `failure`.
+  repelled: '#9f1239',
 };
 
 /**