Merge pull request 'feat: nation-op rename — LLM proposes, player confirms (v0.23.0, #16 P4a)' (#38 ) from feat/16-p4a-rename into master

chore: bump to v0.23.0 (nation-op rename, #16 P4a) + CHANGELOG
feat: nation-op rename review — confirm/reject routes, client dialog, AGENTS.md (P4a, #16 )
2026-10-14 15:03:41 +02:00 · 2026-10-14 13:00:33 +00:00 · 2026-10-14 13:00:28 +00:00 · 2026-10-14 12:47:58 +00:00 · 2026-10-14 14:09:22 +02:00 · 2026-10-14 12:04:03 +00:00
41 changed files with 23004 additions and 273 deletions
@@ -27,11 +27,20 @@ renders territorial ownership; the whole thing persists to SQLite and streams ov
 - Frontend: React 19 + Vite 6 + Tailwind CSS v4 (`@tailwindcss/vite`, no config file) + shadcn/ui
 - 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 country choropleth
+- Map: MapLibre GL (`maplibre-gl`) — remote OpenFreeMap `dark` basemap + a **sub-national**
-  from `public/countries.geo.json` (`id` = ISO_A3)
+  choropleth from `public/regions.geo.json` (1,796 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.
 - The LLM client is a thin OpenAI chat-completions wrapper over native `fetch` with an
-  **injectable transport** (mirrors `mesh-bot/src/llm`). A deterministic **stub** transport
+  **injectable transport** (mirrors `mesh-bot/src/llm`), with two entry points: plain
-  (`LLM_STUB=1`) is used by all tests/e2e.
+  `chat()` and `chatWithTools()` — a bounded OpenAI function-calling loop (max 6 tool
  rounds, then one forced no-tools request) sharing the same retry/backoff/
  `reasoning_effort` machinery (see the LLM config note below). A deterministic **stub**
  transport (`LLM_STUB=1`) is used by all tests/e2e.
 ## Layout
@@ -43,21 +52,33 @@ 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)
+├── vitest.config.ts        # unit tests (server/**/*.test.ts + scripts/**/*.test.ts; 151 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 features, id=ISO_A3 (committed; Vite copies to dist/)
+│   ├── 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)
 ├── 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
 ├── shared/                 # NO runtime deps — the single source of truth
 │   ├── types.ts            #   domain types (Nation, GameState, RoundItem, Preset, …)
-│   └── protocol.ts         #   LLM TurnResult schema + AddAction/AddDiplomacy/RemoveQueueItem/Jump request types + pure helpers
+│   └── protocol.ts         #   LLM TurnResult schema (incl. `unowned`, v0.22 #16 P3, and
 │                           #     `nationOps`, v0.23 #16 P4a) + AddAction/AddDiplomacy/RemoveQueueItem/
 │                           #     Jump + NationOp confirm/reject request types + pure helpers
 ├── server/
-│   ├── index.ts            # Express: /api/* (action|diplomacy|queue/remove|jump|advisor|games|presets), /sse/:id; reads PORT/LLM_*/DATA_DIR
+│   ├── index.ts            # Express: /api/* (health|action|diplomacy|queue/remove|jump|advisor|
-│   ├── engine.ts           # pure: buildPrompt / parse+validate / applyTurnResult / runTurn / queueRoundItem / removeRoundItem / advisor
+│   │                       #   nation-op/confirm|nation-op/reject|games|map|presets), /sse/:id; reads
-│   ├── llm.ts              # LlmClient (injectable transport, retry+backoff, logging) + env config
+│   │                       #   PORT/LLM_*/DATA_DIR
-│   ├── stub.ts             # deterministic LLM transport (tests/e2e) + ADVISOR_MARKER
+│   ├── 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 / nation-op ops (resolveNationRef / applyNationOp / confirmNationOp / rejectNationOp, v0.23 #16 P4a)
-│   ├── map.ts              # GameState → RegionMap (ISO_A3 → owner + stable color)
+│   ├── 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
 │   ├── 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
 │   └── *.test.ts           # unit tests (vitest)
@@ -74,7 +95,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) or reject (v0.23 #16 P4a)
        ├── 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
@@ -88,10 +110,11 @@ 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 in `server/` (39 tests) |
+| `npm test` | vitest unit tests (`server/` + `scripts/`; 151 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) |
 | `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.
@@ -140,24 +163,81 @@ history/
  (model down) surfaces as an HTTP 502 to the client (shown as a toast).
 - **Stable per-nation colors.** `shared.nationColor(id)` hashes a nation id → hue, shared by the
  server's `RegionMap` and any client coloring so the choropleth always agrees.
- **Map click → dossier target (owner resolved from the RegionMap).** Clicking a map region does
+- **Region-level territory (v0.19/v0.21, #16 P1+P2).** Since v0.19 ownership lives at sub-region
-  NOT open a popup — it switches the dossier to that region's owning nation
+  granularity: `Nation.territory` holds **region keys** (`<name-slug>-<4char>`, e.g. `moselle-rygy`;
-  (`setViewingId(ownerId)` in `GameScreen`); the manual "Inspect" selector and a map click both set
+  the manifest is `public/region-keys.json`), `server/regions.ts` expands each preset's country list
-  the same target and stay in sync. The owning nation is resolved from the authoritative `RegionMap`
+  to all its sub-regions' keys at game creation, and `buildRegionMap` keys the choropleth `RegionMap`
-  by the feature's stable ISO_A3 code, which `applyRegions` stamps into `properties.regionId`
+  by region key. Since v0.21 transfers are **frontier-biased**: `applyTurnResult` is snapshot-first
-  (properties survive into the rendered features) and the shared `regionOwner()` helper looks up.
+  and enforces **sole ownership** (a key transfers only when exactly one nation claims it to gain,
-  It must **never** be read from the feature's top-level `id`: MapLibre repacks a GeoJSON source's
+  it has exactly one current owner, and the owner is not the gainer — a double claim is rejected and
-  `id` into a numeric index when it stores the source, so at click/hover time `feature.id` is a
+  a lone `lose` is a no-op, so a key can never be orphaned or duplicated), and the LLM can call the
-  number, never the ISO_A3 (that repacking was the "no owner" bug, #6). Unowned regions (no
+  `getNeighbours` tool (`GET_NEIGHBOURS_TOOL` + `makeNeighboursExecutor` in `engine.ts`, data from
-  `RegionMap` entry) leave the current dossier target unchanged — never a broken dossier. The
+  `public/region-adjacency.json` via `neighboursOf`) to verify land borders before proposing a
-  hover path (a non-closeable tooltip with owner + key stats) uses the same resolution.
+  transfer; the user payload carries the player's `frontier` (the sorted other-nation keys bordering
  the player's territory, via `playerFrontier`). The tool path degrades gracefully: without the
  adjacency manifest (or with a client lacking `chatWithTools`), a turn runs the legacy plain
  `chat()` path and the tool/frontier simply switch off. Since v0.22 (#16 P3) a key may also end
  a turn **unowned** — "no man's land": `TurnResult.unowned` lists keys released this turn;
  `applyTurnResult` applies releases FIRST (a key leaves its sole owner — only a key with exactly
  one current owner can be released; a never-assigned or corrupt key is a no-op), then claims
  against the post-release snapshot, so a `gain` on an ownerless key is a **re-claim** (granted to
  the sole gainer and removed from the cumulative `GameState.unowned` list). The user payload
  carries the current `GameState.unowned` as `unowned`, and the jump route's `regions` reference
  table includes those keys so the model can name them when re-claiming. The map renders a
  released key in the distinct visible grey (`NO_MANS_LAND_FILL` in `shared/protocol.ts`, with a
  "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).
 - **Nation ops — “LLM proposes, player confirms” (v0.23, #16 P4a).** `TurnResult.nationOps` (required
  in the schema) carries the LLM’s proposed **`NationOp`s** — a discriminated union of `rename` /
  `split` / `merge`. `rename` is fully applied; `split` and `merge` are **declared shapes only**
  (accepted and stored as pending, but a no-op until P4b implements them). 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?}}`) or `.../nation-op/reject`
  (`{index}`): `confirmNationOp` applies the op to a clone (a 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) 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) with
  an editable rename name plus Confirm / Reject. The stub never proposes a nation op (`nationOps: []`),
  so this path is covered by unit tests 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
  clicked for a small dossier label); the manual "Inspect" selector and a map click both set the
  same target and stay in sync (a manual pick clears the label). Ownership is resolved from the
  authoritative `RegionMap` (keyed by **region key**) via the feature's stamped
  `properties.regionKey`, using the shared `mapFeatureOwner()` helper (`shared/protocol.ts`) —
  `WorldMap` stamps each rendered feature with its key from `region-keys.json` when it builds the
  choropleth source. It must **never** be resolved from the feature's top-level `id` (MapLibre
  repacks it into a numeric index — the "no owner" bug, #6) nor from the raw sub-region `id` (not a
  `RegionMap` key). A sub-region whose key has no owner leaves the current dossier target
  unchanged — never a broken dossier. The hover path (a non-closeable tooltip showing the region
  name + owner chip + key stats) uses the same resolution. `properties.parent` is static
  geographic-origin data — never use it for ownership or display.
 - **Deterministic stub.** `server/stub.ts` answers the model contract deterministically per
  queued round item: each `action` item → one military/success event, each `diplomacy` item → one
  diplomatic/partial event, an empty round → one political "The world moves on" event. The player
  nation's `military` is set to `(current + 5)` (clamped) once per committed turn (not per item),
  the player is allied with the first other nation (by key order in the `nations` record), and the
-  date advances 2 days. Unit + e2e assertions rely on these exact values, so keep the stub
+  date advances 2 days. Since v0.21 the stub also makes **one contiguous conquest per turn**: the
-  deterministic.
+  player gains `frontier[0]` (the first of the sorted `frontier` list from the prompt payload —
  stable) and that region's owner loses it; an empty frontier (no controllable border, e.g. the UK
  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`). Since v0.23 (#16 P4a)
  the stub also returns `nationOps: []` — it **never proposes** a nation op (rename/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**
@@ -200,6 +280,12 @@ history/
 > ignoring `reasoning`. `chat()` retries transient failures (timeout/abort, 5xx, network
 > errors, null/empty `content`) up to 3 attempts with 2s→3s backoff and logs every call
 > (`[llm] chat ok` / `[llm] chat failed`). No auth header is sent — the endpoint requires no key.
 > The same machinery backs `chatWithTools()` (the function-calling loop used by turns when the
 > region-adjacency manifest is loaded): a `finish_reason: "tool_calls"` response is a *successful*
 > round (never a truncation error), each requested tool call is run through the injected executor,
 > the assistant tool-call message plus one `tool` result message per call are appended to the
 > history, and the loop re-sends until a final `content` — max `DEFAULT_MAX_TOOL_ROUNDS = 6`
 > tool rounds, after which one last *no-tools* request forces the answer.
 | `PORT` | `4321` | single server port |
 | `DATA_DIR` | `./data` | where `history.db` lives |
 | `CLIENT_DIST` | `./dist` | built client to serve (auto-found) |
@@ -239,5 +325,10 @@ history/
  caught.
 - **`better-sqlite3`** is the only native module; the Docker build relies on its prebuilt binary
  (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; `public/countries.geo.json` is copied
+- The `dist/` client is committed to the build output only; the `public/` data files
-  into `dist/` by Vite at build time, so the prod image serves it from `dist/` (no separate copy).
+  (`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
  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
  never activated in prod).
@@ -2,6 +2,114 @@
 All notable changes to **History** are listed here, newest first.
 ## 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.
  - **New required `GameState.unowned` field** (`shared/types.ts`): the cumulative list of keys released mid-game. A no-man's-land region is **distinct from a preset-unassigned region** — the presets assign only ~25–30% of the 1,796 sub-regions (e.g. `wwii-1939` starts with 411 owned / 1,385 unowned), so ~1,300 ownerless regions exist at init; those keep the existing faint look, and only `GameState.unowned` keys get the distinct one. Legacy SQLite rows saved before v0.22 load with the field defaulted to `[]` (`server/db.ts`), and game creation sets it to `[]`.
  - **Map presentation (a new contract in `shared/protocol.ts`).** `regionFillStyle(owner, isNoMansLand)` + `unownedTooltipLabel` decide the look: an owned region is unchanged (nation color + `OWNED_STROKE`); a released region gets the distinct visible grey `NO_MANS_LAND_FILL = '#3f3f46'` (hue-less by construction, so it can never collide with a nation's `hsl(h 58% 46%)` color) with a brighter border (`NO_MANS_LAND_STROKE`) and the tooltip sub-line "No man's land"; every other ownerless region keeps the faint `rgba(148,163,184,0.05)` fill and "No owner". The client (`WorldMap`, via a new `unowned` prop from `App.tsx`) is the sole consumer of the distinction — the `RegionMap` simply has no entry for an unowned key (`buildRegionMap` is unchanged). Clicking a no-man's-land region does not change the dossier (there is no owner to focus), and a release/re-claim flashes like any other ownership change.
  - **Stub + tests.** The deterministic stub is deliberately **unchanged** — it never releases a region (it always returns `unowned: []` and ignores the payload's `unowned` field), because its one-conquest behavior is what the e2e assertions rely on; the release/re-claim path is therefore covered by **unit tests only** (a new `applyTurnResult (no man's land)` suite: release, re-claim, release+claim of the same key, a double claim on a released key, the four no-op release cases, a legacy state without the field, and a `runTurn` end-to-end test with a narrated release; new `buildUserPrompt`/`buildSystemPrompt` contract tests; a presentation-contract suite in `server/map.test.ts`; a legacy-row normalization test in `server/db.test.ts`). The unit suite grows **105 → 127**.
  - **No data-format wipe.** The `GameState` shape only gains a field that legacy rows load with, so existing saves remain compatible: the deploy is a plain `up -d --build` (no `down -v`).
 - **Verification.** Typecheck, lint, **127 unit tests**, and the production build all pass. The e2e suite (CI, `LLM_STUB=1`) carries no map-color/no-man's-land 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 — no man's land (P3); #16 stays open.
 ## v0.21.0 — 2026-10-14 10:37
 - **Part 2 of #16: territory now moves region-by-region along real land borders, and the LLM can verify borders with a live tool.** v0.19 made ownership region-keyed, but the model's `territoryChanges` were still applied wholesale — any key could jump to any nation, effectively moving whole countries. Now:
  - **Region-adjacency manifest (Stage 1).** `scripts/build-region-adjacency.mjs` (`npm run build:region-adjacency`) computes which of the 1,796 sub-regions share a land border: per candidate pair, a cheap bbox-proximity prefilter (0.05° gap reject) then a `@turf/boolean-intersects` arbiter. The output `public/region-adjacency.json` is symmetric and deduped — **1,796 entries, 4,470 border pairs (8,940 directed), max degree 19; 1,727 regions have ≥1 neighbour, 69 don't** — and is deterministic/idempotent (sha256 `e9f1d475…`; re-running is byte-identical). Vite copies it into `dist/` for prod; `server/regions.ts` loads it (turf-free — plain `JSON.parse`, no `@turf` import in any `.ts`) and degrades gracefully when it is missing.
  - **`getNeighbours` LLM tool (Stage 2).** `server/llm.ts` gains `LlmClient.chatWithTools` — a bounded OpenAI function-calling loop: on a `finish_reason: "tool_calls"` response the client runs the injected executor for every call, appends the assistant tool-call message plus one `tool` result message per call, and re-sends until a final `content` (max **6** tool rounds, then one last *no-tools* request forces the answer). It shares the retry/backoff/`reasoning_effort: "low"` machinery with `chat()`; a tool-call round is a success (never treated as truncation); malformed tool arguments become an `{"error":"invalid tool arguments…"}` tool message, so a bad model reply can never throw. `tools` is included in the request body only when non-empty, so plain `chat()` bodies (and their tests) are unchanged.
  - **Engine wiring.** `runTurn` takes an optional `getNeighbours` resolver — the server's jump route passes one only when the manifest loaded (`hasAdjacency()`). With both the resolver and a `chatWithTools`-capable client, the turn runs the tool path: the system prompt gains the contiguity rules (a nation may only GAIN a key that borders its own territory; every key has exactly one owner) and advertises the tool; the user payload gains a `frontier` field — the player's `playerFrontier`, the sorted/deduped set of *other-nation* keys bordering the player's territory (the natural targets of a player-led conquest). Without the manifest, or with a minimal chat-only client, the turn falls back to the legacy plain `chat()` path — everything keeps working, the tool/frontier simply switch off.
  - **Sole-ownership enforcement.** `applyTurnResult` now applies territory snapshot-first: before mutating anything it computes each key's current owner, and a key transfers only when (a) exactly one nation claims to gain it (a double claim is rejected — the key stays), (b) it has exactly one current owner (pre-existing double ownership is never touched), and (c) the owner is not the gainer (self-gain is a no-op). A transfer removes the key from all nations first, then grants it to the gainer; lone `lose` entries are no-ops. Every key therefore ends the turn with exactly one owner — it can never be orphaned or duplicated, and a bad model answer degrades to "no transfer", never to a corrupt map.
  - **Deterministic stub.** The stub now makes one contiguous conquest per turn: the player gains `frontier[0]` (sorted → stable) and its owner loses it. It answers plain content (no tool calls), so it naturally bypasses the tool loop in a single round; with an empty frontier (no controllable border — e.g. the UK in `wwii-1939`, whose only external neighbour is Ireland) nothing transfers and every existing e2e assertion stays stable.
  - **No data-format change — no save wipe.** The `TerritoryChange` wire shape is unchanged and saved games load as-is, so the deploy is a plain rebuild (no `down -v`).
 - **Verification.** Typecheck, lint, **105 unit tests** (79 baseline + 26 new: tool-loop protocol — echo, parsed executor args, bounded rounds, malformed args, retry; engine tool-path wiring + fallback; `playerFrontier`; executor degradation; sole-ownership invariants; `neighboursOf`/`hasAdjacency`), the production build, and all **14 e2e** tests pass.
 - **Deploy:** manual `docker compose up -d --build` on the host (no `down -v`).
 - Part of #16 — P3 (region rename/split/merge) and P4 follow; #16 stays open.
 ## v0.20.0 — 2026-10-14 09:30
 - **Fixed: v0.19.0's region-level ownership did not activate in the production image.** The server-side region loader (`server/regions.ts`) only looked for the manifest + geo in `public/`, but in the Docker image Vite copies `public/*` → `dist/` and no `public/` directory is kept — so `loadRegions` found nothing, `expandCountriesToKeys` degraded to a no-op, and freshly-created games kept raw ISO_A3 codes (`DEU`, `GBR,IRL,IND`, …) instead of expanding to region keys. The choropleth therefore still rendered whole-country ownership and the model's region-key contract was inactive in prod (the client's own `/region-keys.json` fetch still worked, because the client is served from `dist/`). `loadRegions` now probes `public/` (dev) then `dist/` (prod, == `clientDir`) and uses the first directory holding both files, so one build works in both environments. A new test covers the prod-only (`dist/`), dev (`public/`), and empty-root (no data) layouts.
 - **Deploy:** `docker compose down -v` (drops the `history-data` volume — pre-v0.19 saves were already dropped by v0.19.0 and are dropped again here) then `up -d --build`.
 ## v0.19.0 — 2026-10-14 09:14
 - **Region-level ownership foundation (Part 1 of #16): internal territory ownership flips from whole countries to individual sub-regions.** Previously a nation owned *whole countries* (a `territory` list of ISO_A3 codes) and every sub-region of a country shared the parent's color, so a single region could never change owner independently. Now each owned sub-region is addressed by a stable **region key** — `<name-slug>-<4char>`, e.g. `moselle-rygy`, `ain-lqtt`, `western-alun` — generated deterministically by `scripts/build-region-keys.mjs` into `public/region-keys.json` (**1,796 unique keys** over the 1,796 sub-regions). A key is a slug of the region's name (NFKD, diacritics stripped, lowercased, non-alphanumerics → `-`) plus a 4-character hash of the feature's stable id, salted on within-country name collisions, so it is stable, human-readable, and globally unique (a "western" collision group yields `western-alun` / `western-qwvr` / `western-adsp` / …; an accented name like Shkodër becomes `shkoder-gmnr`).
 - **The map, the model, and the LLM all now reason in region keys.** `Nation.territory` and the `RegionMap` are keyed by region key; the choropleth resolves each sub-region's owner by its stamped `properties.regionKey` (never the repacked numeric feature `id`, never the raw sub-region id — the #6 guard, now region-keyed). A new `server/regions.ts` (turf-free) loads the manifest + geo once at boot and **expands each nation's country list to all its sub-regions' keys at game creation**, so a fresh game shows every sub-region in its owner's color — visually identical to the old whole-country choropleth, but each sub-region is now individually addressable. The LLM prompt gains a `regions` reference table (region key → "<name> (parent ISO_A3)"), and `applyTurnResult` ignores any territory key not in the valid set, so a hallucinated key can't corrupt ownership.
 - **The dossier shows region names.** NationPanel's territory chips display each sub-region's human name (e.g. "Ain", "Wales", "Moselle") with the raw key in the tooltip / data attribute, instead of bare codes.
 - **⚠ Breaking — pre-v0.19 saved games are dropped.** The `territory` field's meaning changed from ISO_A3 country codes to region keys, so a game saved before this version can't be read by it. Deploy runs `docker compose down -v` (dropping the `history-data` volume) then `up -d --build`; there is no migration — start fresh after deploying.
 - **Supersedes the abandoned `feat/sub-region-territory` branch**, which prototyped raw feature-id keys (`DEU-03`); this version uses the slugged, human-readable key scheme instead.
 - **Verification.** Typecheck, lint, and the unit suite (now **71 tests across 7 files**: +`server/regions.test.ts`, a rewritten `server/map.test.ts`, +2 in `engine.test.ts`) all pass; the production build is clean. The deterministic `LLM_STUB` and the format-agnostic e2e suite (legend/stats/dates) are unchanged. **#16 stays open** — P2 (LLM tools / function-calling for reliable region ops) and the no-man's-land rename/split/merge phases follow.
 ## v0.18.0 — 2026-10-13 18:54
 - **Fixed a stale-owner display bug: the region hover tooltip and the dossier "Selected" label no longer print the static parent-country code (e.g. "FRA").** The GeoJSON `properties.parent` is a *static geographic-origin* field that never updates when a country is taken, yet it was rendered in the hover tooltip (as a sub-line and as a title fallback) and in the dossier's `Selected:` label (as a `(FRA)` suffix) — so a sub-region of a transferred country still displayed the old country's code next to the (correct) new owner. The tooltip now shows only the region name + the live owner chip (from the RegionMap) + key stats, and the dossier label shows only the region name. Ownership resolution still keys on `properties.parent` (unchanged) — only the display of it was removed.
 ## v0.17.0 — 2026-10-13 15:13
 - **Filled the no-one's-land left between merged sub-regions (Part of #16).** The v0.14 coarsening's boolean dissolves left slivers of each country's landmass inside no region — measured at **≈ 3.90M km² globally** (the union of a country's regions covered only ~98% of its landmass). The new `scripts/fill-gaps.mjs` (`npm run fill:regions`) closes them: per country it computes the gap (`landmass − union(its regions)`, `@turf/difference`+`union`), drops slivers < **25 km²** (66,637 of them — sub-pixel on the map), and assigns each remaining piece to the **nearest region** (centroid distance) as an appended MultiPolygon part. **2,696,811 km²** of no-one's-land was filled into **1,575 regions** (+6,768 parts: 5,026 → 11,794), leaving **63,889 km²** residual (**98.4% reduction** — the rest is coastline digitization fuzz and 14 tiny border-band overlap artifacts, see below). The named "messy" regions absorb their surroundings: **SI-048 Kočevje (SVN) 16,692 → 19,816 km² (57 → 90 parts)**, **MK-36 Kavadarci (MKD) 21,297 → 25,190 km² (8 → 17)**, **AZ-AGC Ağcabədi (AZE) 18,657 → 32,065 km² (7 → 14)**; the biggest single fills are **AQ-X01~ (Antarctica) +195,351 km²**, **CA-NU (Nunavut) +143,447**, **AQ-X02~ +142,615**, **CL-MA (Magallanes) +81,806**, **US-AK (Alaska) +63,830**, **CA-NT (NWT) +46,333**, **GL-UO (Kommuneqarfiup) +41,971**, **RU-KAM (Kamchatka) +41,911**.
 - **Correct, not just greedy: clipping, hole policy, dedup.** Each gap piece is clipped sequentially against (a) all *other countries'* regions, (b) its own country's existing regions, and (c) pieces already appended (bbox-touching) — so a piece straddling a border is split, and no piece can double-cover another region's area (**1,149,841 km² of foreign overhang removed** this way; 0 clip failures). **FR-57 Moselle (FRA) gains nothing on purpose**: its apparent gap was a cross-border phantom consumed by the neighbor clip — correct behavior. Holes follow a keep-or-drop policy: a gap hole whose centroid matches a **pre-existing hole** (within 10 km) or lies inside another country's landmass is kept, otherwise it's a phantom and dropped — so the **KZ-KZY Aral hole survives** (5,858 km² planar, the file's only hole; 5,875 km² of water kept open). A global dedup set guarantees each cleaned piece is appended at most once.
 - **The dataset contract is untouched.** Still **1,796 regions** with identical `id` / `properties.name` / `properties.parent` and order — the fill only *appends* parts; all **177 countries** covered; the single KZ-KZY hole intact. **14 genuinely new overlap pairs** remain (13 same-country border bands + 1 cross CN-FJ×TW-KIN) — a known polychip artifact of filling right up to a shared boundary (the pre-fill file already carried 3,690 pre-existing pairs), and they are sub-pixel at map scale, so they're accepted. The file grows **2,289,528 → 3,399,806 bytes (2.29 → 3.40 MB)** — under the 5 MB guard, so no Douglas–Peucker pass is needed.
 - **Deterministic + idempotent.** Fixed 25 km² threshold, deterministic ordering (centroid → area → id), 4-dp rounding (same convention as the other scripts). A fresh run on the pristine v0.16 file reproduces the shipped byte-for-byte (sha256 `87f44198…`), and re-running on the filled file is a no-op (byte-identical output).
 - **Tests** — `scripts/regions.test.ts` (now 9 tests): the v0.16 fixed-point pin is updated to the v0.17 topology (1,796 regions, 11,794 parts, 11,795 rings, 164,801 vertices, 1 hole); a new test asserts the **only** hole in the file is KZ-KZY and sits in a realistic 5,000–7,000 km² band; a new **grid-sampled per-country coverage** test (25×25 grid per country, inline even-odd ray cast) asserts no significant no-one's-land remains — median 1.8% / p90 6.1% / max 26.4% (BRN, a coastline-denseness artifact, not a real gap), with thresholds at 5% / 15% / 40% and ≤3 countries above 20%. The planar sum band's upper bound widens 175% → **190%**: the fill only adds area *inside* each country, so it can't shrink the pre-existing admin-1 over-extension tail (Vanuatu 178.9%, Solomon Is. 133% — tiny island nations whose admin-1 polygons extend beyond their own country polygon), while the old under-fill tail is gone (minimum is now Brunei at 78.8%, was ~52%).
 - **Type-check gotcha (why the test stays turf-free):** the project keeps `@types/geojson` **out of the tsc program** (tsconfig `types: ["vite/client", "node"]`). maplibre-gl's d.ts references the `GeoJSON` UMD global *without importing it*, so under `skipLibCheck` the reference degrades to `any` and `WorldMap.tsx`'s deliberately-minimal `GeoFeature` (with `geometry: unknown`) passes. The moment anything (e.g. a test importing `@turf/turf`) pulls `@types/geojson` into the program, those references typecheck for real and `WorldMap.tsx` fails with 7 errors. The v0.14–0.16 scripts are `.mjs` (never typechecked) for exactly this reason; the new test uses an inline ray cast instead of a geometry library, and `@turf/*` (a new devDependency, 137 packages including the meta `@turf/turf`) is only ever *run* by the `.mjs` scripts.
 - Part of #16
 ## v0.16.0 — 2026-10-13 09:37
 - **Smoothed the jagged sub-national region boundaries with Douglas–Peucker vertex-thinning (Part of #16).** The v0.14 coarsening (boolean dissolve) and Natural Earth's 1:10m digitization left some boundaries overly jagged — the worst being regions the dissolve split into many small zig-zag fragments, e.g. **SI-048 Kocevje (Slovenia, 57 parts)** and **MK-36 Kavadartsi (N. Macedonia, 8 parts)**. The new `scripts/smooth-regions.mjs` (`npm run smooth:regions`) runs `@turf/simplify` (Ramer–Douglas–Peucker, tolerance ~**50 m**) over **every ring of every polygon**, dropping the redundant "in-between" vertices of a shallow zig-zag while keeping the overall shape.
 - **Vertex-thinning only — no topology change.** DP only removes points: it never moves a border, never merges/dissolves a part, and never creates or removes a ring. So the dataset contract is fully preserved — still **1,796 regions** with identical `id` / `properties.name` / `properties.parent`, all **177 countries** covered, the same **5,026 parts / 5,027 rings**, the single **KZ-KZY** hole, and all **83 islands**. The 18 degenerate 3-point "micro-dot" rings (Ragged Island, the Paracels, …) are kept verbatim (`@turf/simplify` requires ≥4 pts and would otherwise throw).
 - **A gentle pass, reported honestly.** At 50 m the dataset is already fairly smooth (the v0.14 dissolve produced low-vertex, widely-spaced boundaries — median consecutive-vertex spacing ~18 km), so this is a light cleanup: **111,891 → 111,175 vertices (716 removed, 0.64%)** across **542 of 1,796** regions. **Kocelje 612 → 599** and **Kavadartsi 169 → 163** verts; both keep their exact part count (the "mess" there is fragmentation, which thinning — under the no-topology-change constraint — does not fix). The file shrinks **2,302,473 → 2,289,528 bytes (2.29 MB)**. Bump `TOLERANCE_M` to 100 / 200 m and re-run for a stronger pass (100 m → 974 removed; 200 m → 1,312 removed) — the pass stays idempotent either way.
 - **The "messy" regions are really fragmentation artifacts, not fine jaggedness.** Ranking by **part density** (parts packed per unit area) rather than raw part count — which is dominated by legitimate *dispersed* archipelagos (Nunavut 213, Alaska 159, Antarctica 135, British Columbia 84) — surfaces the genuinely messy **coherent regions the dissolve left fragmented**: **SI-048 Kocevje (SVN, 57 parts in ~16,600 km²)**, **GR-H Stereá Elláda / Central Greece (GRC, 53 parts)**, **KR-46 South Jeolla (KOR, 28 parts)**, **SE-C Uppsala (SWE, 19 parts)**, **HR-13 Zadarska (HRV, 17 parts)**, plus the milder Balkan **MK-36 Kavadartsi (MKD, 8 parts)**. These real land regions (the Balkan ones in particular) ended up as many scattered fragments — the "similar shape problems".
 - **Deterministic + idempotent.** One `@turf/simplify` pass at a fixed tolerance, then 4-dp rounding (the same convention as the other scripts). The output already sits at the pass's fixed point, so re-running on the smoothed file is byte-identical (sha256 `70a43541…`, verified across repeated runs); `public/regions.geo.json` and the built `dist/regions.geo.json` are sha256-identical.
 - **Tests.** `scripts/regions.test.ts` gains an eighth test pinning the v0.16 fixed point: 1,796 regions, 5,026 parts, 5,027 rings, the single KZ-KZY hole, and exactly **111,175** vertices (8 tests total). All prior assertions (well-formed, unique ids, 177-country coverage, area floor, holes, coverage band) pass unchanged on the smoothed dataset.
 - Part of #16
 ## v0.15.0 — 2026-10-12 13:49
 - **Filled the small holes left by the v0.14 coarsening (Part of #16).** The coarsened `public/regions.geo.json` still carried **2,245 tiny enclosed holes** (all < 500 km² in practice) — unfilled patches left by the boolean dissolves and Natural Earth's own digitization, which showed up as "holes in regions". The new `scripts/cleanup-regions.mjs` (`npm run cleanup:regions`) drops every inner ring smaller than the 1,000 km² threshold so each region becomes solid: across **498 features, 56,484 km²** of artifact area was filled, removing the visible unfilled dots.
 - **Real water is kept, not erased.** Any enclosed hole ≥ 1,000 km² survives as a hole. In this dataset the genuinely large lakes (the Great Lakes, the Caspian, the Aral, Lake Superior) had already been dissolved by the v0.14 coarsening, so none remain to preserve; the only surviving hole is a single medium one — **KZ-KZY (Kyzylorda, Kazakhstan) at 5,858 km²**, a real water body in the Aral basin — which is kept. The 1,000 km² threshold sits comfortably between the tiny artifacts (all < 500) and any genuine lake, so it fills exactly the artifacts and nothing else.
 - **The dataset contract is untouched.** Still **1,796 regions** with identical `id`s / `properties.name` / `properties.parent` (0 mismatches), all **177 countries** still covered, the ~100 km floor and the island exemption intact — only inner rings were dropped, never a feature or its identity. The file shrinks 2,431 → **2,249 KB (2.20 MB)** (fewer inner rings).
 - **Deterministic + idempotent.** Fixed threshold, deterministic planar geometry, 4-dp rounding; re-running on the cleaned file rewrites a byte-identical file (sha256-verified). Bridging very-close MultiPolygon parts is available behind an opt-in `--bridge` flag but is **off by default**, because the union it performs can itself mint new medium-sized holes — counter to the fill-holes goal — so the shipped run is the clean hole-fill only.
 - **Tests.** `scripts/regions.test.ts` gains a seventh test asserting that no enclosed hole below the cleanup threshold remains and that only a handful of real water bodies survive (57 tests total). `public/regions.geo.json` and the built `dist/regions.geo.json` are sha256-identical.
 - Part of #16.
 ## v0.14.0 — 2026-10-12 09:51
 - **Coarsened the sub-national choropleth dataset to a ~100 km floor (Part of #16).** `public/regions.geo.json` shrinks from 4,138 real administrative regions to **1,796** (2,342 merges): every region smaller than ~100×100 km (10,000 km²) that has a same-country neighbor within 0.2° (≈22 km) of its bounding box is **dissolved into its nearest such neighbor** (nearest by centroid distance; ties → larger area, then id). Standalone cities and micro-districts collapse into the region around them: `US-DC` (191 km²) into Maryland, `FR-75` Paris (59 km²) into Hauts-de-Seine, the UK's 232 admin-1 districts down to **16** regions, and all of North Macedonia's 85 municipalities into one whole-country region.
 - **Islands are exempt.** A region with no same-country neighbor within 0.2° keeps its shape whatever its size — **83** such small islands survive in the final set (Corsica, the Kerguelen/Crozet archipelagos, the Bahamas districts, Lord Howe, …) and the coarsening's fixed point leaves **0** non-island regions below the floor.
 - **Real dissolve, not overlap.** Each merge is a real boolean union (`@turf/union`, polygon clipping) that removes the shared boundary between the merged region and its host, yielding one clean polygon — the final dataset has **0** fallback (non-dissolved) unions. Passes iterate smallest-area-first to a fixed point (2 passes on the v0.13 data, ~7 s); the output is sorted by (parent, id) at 4-dp precision and is byte-reproducible: re-running on the coarsened file reaches the fixed point immediately and rewrites an identical file (sha256-verified).
 - **Numbers.** Per-country region count: min 1 / median 7 / max 80 (Russia; was 1 / 15 / 232 — the UK). Region areas: median 23,933 km²; smallest ≈0 (degenerate micro-dots like Ragged Island and the Paracel Islands, kept as islands); largest is Antarctica itself (≈21.8M km² in the planar model, exempt — it wraps a full 360°). 158 of the 177 countries had at least one merge. The file is 2,431 KB (2.37 MB) — under the 5 MB guard, so no Douglas–Peucker pass was needed.
 - **Tooling + tests.** New `scripts/coarsen-regions.mjs` (`npm run coarsen:regions`) performs the merge in place; `scripts/regions.test.ts` gains a sixth test asserting that below-floor non-island regions stay under 1% of the dataset (currently 0) alongside the existing well-formed / unique-id / 177-country coverage / area / coverage-band checks (56 tests total). The map's data contract is unchanged (`properties.parent` → RegionMap), so `WorldMap.tsx`, `App.tsx`, `shared/protocol.ts`, and `server/map.ts` all keep working as-is.
 - Part of #16.
 ## v0.13.0 — 2026-10-12 08:30
 - **Replaced the geometric sub-region grid with real named sub-national administrative regions (#16, PR 2).** The choropleth source `public/regions.geo.json` now contains real named administrative regions — states, provinces, governorates, oblasts, … (Natural Earth admin-1, 1:10m) — instead of the abstract ~100–200 km geometric grid. Each region keeps a stable `id` and a `name`. The map's data contract is **unchanged** (`properties.parent` → the parent country's ISO_A3, `properties.name` → the region name), so no change to the map code or the LLM contract: `WorldMap.tsx`, `App.tsx`, `shared/protocol.ts`, and `server/map.ts` all keep working as-is.
 - **Generator rewritten** — `scripts/generate-regions.mjs` (same path, dependency-free, `npm run generate:regions`) now groups the admin-1 features by their `adm0_a3` (the parent's ISO_A3), keeps only parents in the 177-country set, and id's each region with its ISO 3166-2 code when present (e.g. `US-CA`, `FR-75`, `RU-MOW`) else `<ISO_A3>-<nn>`; within a country, ids are disambiguated with a `-2/-3/…` suffix on collision (ISO 3166-2 codes are not always unique within a country — e.g. all nine of Bosnia's entities report `BA-BIH`). A country with no admin-1 data would collapse to one whole-country region `<ISO_A3>-01` (0 are needed at 1:10m, which covers all 177). Coordinates are rounded to 4 decimal places, and the file is Douglas–Peucker-simplified only if it exceeds the ~8 MB guard. Output is sorted by (parent, id) and fully deterministic.
 - **The dataset is 4,138 regions covering all 177 countries**, 2,831 KB (2.76 MB) after Douglas–Peucker (the 4-dp base is ~23 MB). Per-country region count: min 1 / median 15 / max 232 (United Kingdom). There are **0 whole-country fallbacks** — 1:10m admin-1 covers every one of the 177 (the five single-region countries are SOL, SAH, CYN, PRI, FLK). Samples: `US-CA` California and `US-NY` New York (US); `FR-75` Paris and `FR-13` Bouches-du-Rhône (France); `RU-MOW` Moskovskaya (Russia).
 - **Validation test updated** — `scripts/regions.test.ts` was rewritten for the new dataset: well-formed features, globally unique ids, all 177 countries covered (≥1 region each), sane region areas (median ≥ 100 km², no non-Antarctica region ≥ 5,000,000 km² — Antarctica is exempt because its full-360° wrap ring breaks the planar area model), and each country's region area summing to within [40%, 175%] of its own area (median within [70%, 130%] — the band is wider than a naive [40%, 110%] because Natural Earth's admin-1 polygons are digitized independently of the admin-0 country polygons and are not clipped to them). Runs in O(total vertices).
 - Part of #16.
 ## v0.12.0 — 2026-10-12 01:03
 - **Map now renders the sub-national regional dataset (#16, PR 2).** The choropleth source switches from `public/countries.geo.json` (177 countries) to `public/regions.geo.json` (**2,597 sub-regions**): each country is subdivided into ~100–200 km regions, shown as a finer choropleth with thin internal border lines. The MapLibre source/layer ids are renamed `countries`/`countries-fill`/`countries-line` → `regions`/`regions-fill`/`regions-line`, and the border line is thinned to `0.75` (from `1.25`) so the subdivision reads within each country.
 - **Ownership stays at country granularity.** A nation still owns whole countries, so every sub-region of a country shares that country's owning-nation color (the fill is "same colors as the country map, but subdivided"). The owner of a sub-region is resolved from the RegionMap via the feature's `properties.parent` (the parent country's ISO_A3) — never the sub-region id (`FRA-03`) nor the repacked top-level `feature.id`. Clicking a sub-region switches the dossier to its parent country's owning nation (unchanged behavior); the hover tooltip now also shows the sub-region name + its parent country; a small "Selected …" label appears in the dossier after a map click.
 - **New shared helper `mapFeatureOwner(regions, feature)`** in `@shared/protocol` — the single source of truth for resolving a rendered map feature's owner via `properties.parent` → `RegionMap[parent]` (built on the existing `regionOwner` key lookup). The territory-change **flash** now expands a changed country to **all** of its sub-regions (via the new `featuresByParents`), so a whole-country transfer still pulses correctly at the finer resolution.
 - **No ownership-model or LLM change** — `buildRegionMap`/`RegionMap` remain ISO_A3-keyed and the engine still references whole countries; this PR only changes what the map draws. Sub-region-level ownership (individual regions changing hands) is PR 3.
 - **Tests** — new `mapFeatureOwner` unit tests and an updated #6 regression guard pinning the sub-region feature shape (numeric `id`, `regionId` = sub-region code, `parent` = ISO_A3) and proving resolution via `parent` while the sub-region id and repacked id do not resolve (55 unit tests). The e2e suite needed no changes: it asserts on the legend (derived from the ISO_A3 RegionMap) and screen structure, not on map geometry.
 - Part of #16.
 ## v0.11.0 — 2026-10-12 00:31
 - **Sub-national region dataset + generator (#16, foundation only — no app behavior change).** A new dependency-free `scripts/generate-regions.mjs` (run via `npm run generate:regions`) splits each of the 177 countries in `public/countries.geo.json` into adaptive ~100–200 km sub-national regions on a regular lat/lon grid clipped to the country (Sutherland–Hodgman), and writes the committed `public/regions.geo.json` (**2,597 regions**, ~755 KB). Each region is id'd `<ISO_A3>-<nn>` (nn = 1..k in row-major order, capped at 36 per country) with `properties = { name, parent }`, so downstream work can map any region back to its parent nation. Antimeridian countries are handled three ways: small island groups (Fiji) stay a single whole-country region; large ones (Russia) are tiled in shifted [0,360) longitude space with output rings split at ±180°; and the full-360° Antarctic wrap ring becomes two hemispheric wedges. The output is fully deterministic — the same input yields a byte-identical file (verified by sha256).
 - **Validation test** — new self-contained `scripts/regions.test.ts` (picked up by `npm test`) reads the two GeoJSON files once each and asserts: the file is a well-formed FeatureCollection; every region is a valid feature whose id matches `^[A-Z]{3}-\d+$` and whose `parent` is a real country id; every country has 1–36 regions (≥2 for any country larger than 50,000 km²); every region has a sane area (≥ 200 km², with a microstate exemption, and < 5,000,000 km²); and each country's regions sum to 45–108% of its own area (the measured range is ~[64%, 105%] — Antarctica's wedges under-fill, Norway's high-latitude fjord coast over-fills by 0.1%). No change to the running app, the LLM contract, or the map — this is purely the dataset + tooling that later PRs for #16 build on.
 - Fixes #16.
 ## v0.10.0 — 2026-10-11 21:25
 - **Fix world map style (#2)** — made the choropleth fill fully opaque (`fill-opacity` 0.85 → 1.0) and darkened the Natural Earth terrain raster (`raster-opacity` 0.5 → 0.15), so the raster's flat water tint and fine 1:10m coastline no longer bleed through countries and compete with the borders.
 - **Strengthened country border lines** — border width 0.7 → 1.25, and the per-region stroke alphas raised (owned 0.10 → 0.30, unowned 0.06 → 0.14) so the vector borders read clearly as the dominant edge, with owned regions still more prominent than unowned ones.
 - Fixes #2.
 ## v0.9.0 — 2026-10-11 20:57
 - **Reduced turn latency (prompt-level):** capped `recentEvents` in the turn prompt from the last 10 to the last 5 events, and added a HARD CONSTRAINT asking the reasoning model to keep its internal analysis brief before emitting the JSON. This shortens the chain-of-thought (the 170–223s turn driver) and lowers the risk of exhausting the 4000-token output budget before the answer (the original 502 failure mode). Reasoning stays enabled (`reasoning_effort: low`); the deterministic stub, the `TurnResult` contract, `max_tokens`, and `reasoning_effort` are all unchanged.
@@ -30,6 +30,7 @@ export default tseslint.config(
      'vitest.config.ts',
      'playwright.config.ts',
      'scripts/**/*.mjs',
      'scripts/**/*.ts',
    ],
    languageOptions: { globals: { ...globals.node, ...globals.es2022 } },
    rules: {
@@ -1,6 +1,6 @@
 {
  "name": "history",
-  "version": "0.9.0",
+  "version": "0.23.0",
  "private": true,
  "type": "module",
  "description": "AI-driven alternate-history simulator — the LLM is the world engine (Pax Historia style).",
@@ -9,6 +9,13 @@
    "build": "vite build && tsup server/index.ts --format esm --target node22 --out-dir server/dist --external better-sqlite3",
    "start": "node server/dist/index.js",
    "test": "vitest run",
    "generate:regions": "node scripts/generate-regions.mjs",
    "coarsen:regions": "node scripts/coarsen-regions.mjs",
    "cleanup:regions": "node scripts/cleanup-regions.mjs",
    "smooth:regions": "node scripts/smooth-regions.mjs",
    "fill:regions": "node scripts/fill-gaps.mjs",
    "build:region-keys": "node scripts/build-region-keys.mjs",
    "build:region-adjacency": "node scripts/build-region-adjacency.mjs",
    "typecheck": "tsc --noEmit",
    "lint": "eslint .",
    "e2e": "playwright test"
@@ -38,6 +45,15 @@
    "@eslint/js": "^9.20.0",
    "@playwright/test": "^1.62.1",
    "@tailwindcss/vite": "^4.1.4",
    "@turf/area": "^7.4.0",
    "@turf/bbox": "^7.4.0",
    "@turf/boolean-point-in-polygon": "^7.4.0",
    "@turf/centroid": "^7.4.0",
    "@turf/difference": "^7.4.0",
    "@turf/distance": "^7.4.0",
    "@turf/simplify": "^7.4.0",
    "@turf/turf": "^7.4.0",
    "@turf/union": "^7.4.0",
    "@types/better-sqlite3": "^7.6.13",
    "@types/express": "^4.17.25",
    "@types/node": "^22.13.0",
@@ -0,0 +1,133 @@
 /**
 * scripts/build-region-adjacency.mjs — build the precomputed region-adjacency
 * manifest: `public/region-adjacency.json` = `{ "<regionKey>": ["<neighbourKey>", ...], ... }`.
 *
 * For every sub-region (region key, see `public/region-keys.json`) this records
 * which *other* sub-regions it **borders** — i.e. shares an edge or a point with.
 * The result is the data behind the model's `getNeighbours` tool (P2 of #16):
 * given a set of region keys, the engine returns the union of their adjacency
 * entries (excluding the queried keys), so the LLM can plan *frontier-biased,
 * contiguous* territory transfers (a nation realistically gains/loses a region
 * it already abuts) instead of whole countries.
 *
 * Method — bounding-box-pruned polygon intersection (turf is allowed in .mjs
 * scripts; it is deliberately kept OUT of the TS typecheck program, see the
 * v0.17 note). For each unordered pair of regions (i < j) we first do a cheap
 * bbox-proximity reject with a small gap tolerance (adjacent regions' bboxes
 * touch, so their gap is ≈0), and only for the survivors do we run
 * `@turf/boolean-intersects`, which returns true exactly when the two
 * (Multi)Polygons share at least one point (edge or corner touch, or overlap).
 * A hit adds each key to the other's set — adjacency is recorded **symmetrically**
 * and **deduplicated** (a neighbour appears once even if the pair shares several
 * disjoint border segments).
 *
 * Output contract (asserted by scripts/region-adjacency.test.ts):
 *   - one entry for **every** region key (including regions with no bordering
 *     neighbours, e.g. isolated islands — their list is simply empty);
 *   - adjacency is symmetric (A ∈ B's list  ⟺  B ∈ A's list);
 *   - no key lists itself.
 *
 * Deterministic + idempotent: the input files are fixed, the intersection test
 * is a pure geometric computation, and the output is written with keys and
 * neighbour lists both sorted — so a re-run rewrites a byte-identical file.
 *
 * Usage: `node scripts/build-region-adjacency.mjs`  (or `npm run build:region-adjacency`).
 */
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import bbox from '@turf/bbox';
 import booleanIntersects from '@turf/boolean-intersects';
 import { feature } from '@turf/helpers';
 const here = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(here, '..');
 // "Close enough" bbox gap (degrees) for the cheap reject. Adjacent regions'
 // bboxes touch (gap ≈ 0); a small tolerance absorbs 4-dp coordinate rounding
 // and digitization fuzz. It only prunes work — it never affects correctness,
 // because `booleanIntersects` is the final arbiter (a pair is a neighbour only
 // if the polygons actually share a point).
 const GAP_DEG = 0.05; // ≈ 5.5 km
 // --- 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'));
 // Region records in stable file order, keyed by their region key.
 const regions = [];
 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
  regions.push({ key, feature: feature(f.geometry), bbox: bbox(f.geometry) });
 }
 if (regions.length === 0) {
  throw new Error('no regions with valid region keys — check regions.geo.json / region-keys.json');
 }
 // bboxes are flat [minX, minY, maxX, maxY] (turf's BBox type).
 function bboxesClose(a, b) {
  return (
    a[0] <= b[2] + GAP_DEG && // a.w <= b.e + gap
    b[0] <= a[2] + GAP_DEG && // b.w <= a.e + gap
    a[1] <= b[3] + GAP_DEG && // a.s <= b.n + gap
    b[1] <= a[3] + GAP_DEG // b.s <= a.n + gap
  );
 }
 // key -> set of neighbouring keys (deduped; a pair sharing several segments is
 // recorded once).
 const adj = new Map();
 for (const r of regions) adj.set(r.key, new Set());
 let pairChecks = 0;
 let intersections = 0;
 for (let i = 0; i < regions.length; i++) {
  for (let j = i + 1; j < regions.length; j++) {
    if (!bboxesClose(regions[i].bbox, regions[j].bbox)) continue; // cheap reject
    pairChecks++;
    let touches = false;
    try {
      touches = booleanIntersects(regions[i].feature, regions[j].feature);
    } catch {
      touches = false; // a degenerate geometry pair is treated as non-adjacent
    }
    if (touches) {
      intersections++;
      adj.get(regions[i].key).add(regions[j].key);
      adj.get(regions[j].key).add(regions[i].key);
    }
  }
 }
 // --- write idempotently: keys sorted, neighbour lists sorted ------------------
 // Every region key gets an entry (an isolated island's list is simply empty).
 const manifest = {};
 for (const key of [...adj.keys()].sort()) {
  manifest[key] = [...adj.get(key)].sort();
 }
 // Self-reference guard (can't happen — we only ever add the *other* region — but
 // assert it so a future regression is loud rather than silent).
 for (const [k, list] of Object.entries(manifest)) {
  if (list.includes(k)) throw new Error(`region ${k} lists itself as a neighbour`);
 }
 writeFileSync(path.join(root, 'public', 'region-adjacency.json'), JSON.stringify(manifest, null, 2) + '\n');
 // --- summary ------------------------------------------------------------------
 const totalEntries = Object.values(manifest).reduce((n, l) => n + l.length, 0);
 const withNeighbours = Object.values(manifest).filter((l) => l.length > 0).length;
 const maxDegree = Math.max(0, ...Object.values(manifest).map((l) => l.length));
 console.log(
  `[build-region-adjacency] wrote public/region-adjacency.json — ${Object.keys(manifest).length} region keys, ` +
    `${totalEntries / 2} border pairs (${totalEntries} directed entries), max degree ${maxDegree}, ` +
    `${withNeighbours} with ≥1 neighbour (${pairChecks} bbox-close pairs tested, ${intersections} intersect)`,
 );
 // A couple of human-checkable examples (highest-degree regions, stable order).
 const byDegree = Object.entries(manifest).sort((a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0]));
 for (const [k, list] of byDegree.slice(0, 3)) {
  console.log(`  e.g. ${k} (deg ${list.length}) → ${list.slice(0, 4).join(', ')}${list.length > 4 ? ', …' : ''}`);
 }
@@ -0,0 +1,158 @@
 /**
 * scripts/build-region-keys.mjs — build the deterministic region-key manifest.
 *
 * Region ownership flips from whole-country (ISO_A3) to individual sub-region
 * granularity, but the LLM and the persisted `Nation.territory` list need a
 * *stable, human-readable, globally unique* identifier per sub-region. Raw
 * feature ids (`FR-57`) are opaque to the model, so we mint a readable key of
 * the form:
 *
 *     <name-slug>-<4char>        e.g.  brittany-xk2a, western-alun
 *
 * where:
 *   - <name-slug> = properties.name → NFKD → strip combining marks → lowercase
 *     → a tiny fold table for the handful of letters NFKD does NOT decompose
 *     (ə ø ð đ œ ł, the only non-folding letters present in this dataset)
 *     → every non-alphanumeric run collapsed to a single '-' → leading/trailing
 *     '-' trimmed.
 *   - <4char>     = a deterministic 4-letter lowercase code derived from the
 *     feature's stable id (FNV-1a 32-bit → 4 base-26 chars). It is stable
 *     (same id → same code on every run) because the key is persisted in
 *     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.
 *
 * Output: `public/region-keys.json` — a `{ [stableFeatureId]: regionKey }`
 * object, e.g. `{ "FR-57": "brittany-xk2a" }`, in file (stable) order. The map
 * is looked up by the client (`WorldMap`) and the server (`map`/`presets`/
 * `engine`) to join a sub-region's stable id to its readable key.
 *
 * Builtins only — deliberately NO `@turf`/geojson import (importing one pulls
 * `@types/geojson` into the tsc program and breaks `WorldMap.tsx`; see the
 * v0.17 changelog note). Reads the geo file with plain `JSON.parse`.
 *
 * Idempotent: a re-run rewrites a byte-identical file (no timestamps, no
 * randomness, stable feature order, deterministic hash).
 *
 * Usage: `node scripts/build-region-keys.mjs`  (or `npm run build:region-keys`).
 */
 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, '..');
 /**
 * Letters present in the dataset that NFKD does NOT decompose, and their
 * single/multi-letter ASCII equivalents, so their slugs aren't hyphen-soup.
 * Kept deliberately tiny + deterministic (only the six that actually occur).
 */
 const FOLD = {
  'ə': 'a', // schwa
  'ø': 'o', // o-stroke
  'ð': 'd', // eth
  'đ': 'dj', // d-stroke
  'œ': 'oe', // oe ligature
  'ł': 'l', // l-stroke
 };
 /**
 * Readable slug from a region name. NFKD decomposes + we strip the combining
 * marks, lowercase, fold the non-decomposing letters, collapse every other
 * non-alphanumeric run to one hyphen, and trim leading/trailing hyphens.
 */
 function slug(name) {
  let s = name.normalize('NFKD').replace(/[\u0300-\u036f]/g, '');
  s = s.toLowerCase();
  s = [...s].map((ch) => FOLD[ch] ?? ch).join('');
  s = s.replace(/[^a-z0-9]+/g, '-');
  s = s.replace(/^-+|-+$/g, '');
  return s;
 }
 /** FNV-1a 32-bit — a tiny, stable, pure string hash. */
 function fnv1a32(str) {
  let h = 0x811c9dc5;
  for (let i = 0; i < str.length; i++) {
    h ^= str.charCodeAt(i);
    h = (h * 0x01000193) >>> 0;
  }
  return h >>> 0;
 }
 /** Spread a 32-bit hash across four lowercase letters (base 26 per byte). */
 function code4(h) {
  let out = '';
  for (let i = 0; i < 4; i++) {
    out += String.fromCharCode(97 + ((((h >>> (i * 8)) & 0xff) % 26)));
  }
  return out;
 }
 /** The 4-char code for an id, deterministically salted on within-group collision. */
 function codeFor(id, used) {
  let code = code4(fnv1a32(id));
  let attempt = 0;
  while (used.has(code)) {
    attempt += 1;
    code = code4(fnv1a32(`${id}#${attempt}`));
  }
  return code;
 }
 // --- load the region geo (plain parse; no geojson types) ---
 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`);
 }
 // Group features by their (computed) name-slug, preserving file order, so the
 // within-slug 4-char uniqueness resolution below is deterministic.
 const groups = new Map(); // slug -> array of { id }
 for (const f of features) {
  const id = f.id == null ? '' : String(f.id);
  const name = f.properties?.name;
  if (!id || typeof name !== 'string') {
    throw new Error(`region with id ${JSON.stringify(id)} has no usable name`);
  }
  const s = slug(name);
  if (!groups.has(s)) groups.set(s, []);
  groups.get(s).push({ id });
 }
 // Assign keys, resolving 4-char collisions within each slug group.
 const manifest = {};
 for (const [s, ids] of groups) {
  const used = new Set();
  for (const { id } of ids) {
    manifest[id] = `${s}-${codeFor(id, used)}`;
    used.add(manifest[id].slice(-4));
  }
 }
 // --- hard assertions (the test re-checks these against the committed file) ---
 const keys = Object.values(manifest);
 if (new Set(keys).size !== keys.length) {
  throw new Error(`region-key collision: ${keys.length} keys but only ${new Set(keys).size} unique`);
 }
 const KEY_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*-[a-z]{4}$/;
 for (const k of keys) {
  if (!KEY_RE.test(k) || !k.includes('-')) {
    throw new Error(`malformed region key: ${JSON.stringify(k)}`);
  }
 }
 // --- write idempotently (stable order = insertion order = file order) ---
 const out = JSON.stringify(manifest, null, 2) + '\n';
 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(`  western group: ${western.map(([id, k]) => `${id}=${k}`).join(', ')}`);
@@ -0,0 +1,323 @@
 #!/usr/bin/env node
 /**
 * scripts/cleanup-regions.mjs — removes the small holes left by coarsening.
 *
 * Run:   npm run cleanup:regions        (in place on public/regions.geo.json)
 *        node scripts/cleanup-regions.mjs [out] [src] [--bridge]
 *
 * The v0.14 coarsening produced a clean 1,796-region dataset, but small
 * unfilled patches ("holes") remain inside regions — artifacts of the boolean
 * dissolves and Natural Earth's own digitization. This fixes that in place,
 * WITHOUT touching the dataset's contract (the region count, the `id`s, the
 * `properties = { name, parent }`, the ~100 km floor and the island exemption
 * are all preserved — only inner rings are dropped).
 *
 *   ENCLOSED HOLES  — every hole (inner ring) whose area is < HOLE_AREA_MAX_KM2
 *   is dropped, so the region fills in to be solid. Any larger hole (a genuine
 *   water body) is kept. NOTE: the big real lakes (Great Lakes, Caspian, Aral,
 *   Lake Superior, …) were already dissolved by the v0.14 coarsening, so they
 *   are not present as holes here; the only hole above the threshold in this
 *   dataset is a single medium one (~5,858 km2, kept). A 1,000 km2 threshold
 *   is comfortably above the 2,252 tiny artifact holes (all < 500 km2) and
 *   comfortably below any large real lake, so it fills exactly the artifacts.
 *
 *   BRIDGING (opt-in, `--bridge`)  — a MultiPolygon whose separate parts sit
 *   only a short distance apart (a thin gap across a strait, a nearby island)
 *   leaves a visible crack of background. This joins each such close pair with
 *   a small connector polygon and a boolean union, closing the crack while
 *   genuinely far parts (islands, separated territories) stay separate. It is
 *   OFF by default: the union itself can mint new (medium) holes, which is
 *   counter to the primary "fill holes" goal, so the default run is the
 *   clean, deterministic hole-fill only.
 *
 * Deterministic + idempotent: fixed threshold, deterministic planar geometry,
 * 4-dp rounding. Re-running on an already-clean file rewrites the same file
 * (no small holes remain to fill; the kept holes are above the threshold).
 */
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { union } from '@turf/union';
 import { featureCollection } from '@turf/helpers';
 const here = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(here, '..');
 const DEFAULT_FILE = path.join(root, 'public', 'regions.geo.json');
 // positional args (out, src) plus named flags; keep the two orthogonal
 const args = process.argv.slice(2).filter((a) => !a.startsWith('-'));
 const flags = process.argv.slice(2).filter((a) => a.startsWith('-'));
 const BRIDGE = flags.includes('--bridge');
 const OUT = args[0] ? path.resolve(args[0]) : DEFAULT_FILE;
 const SRC = args[1] ? path.resolve(args[1]) : DEFAULT_FILE;
 // --- parameters ---------------------------------------------------------------
 const HOLE_AREA_MAX_KM2 = 1000; // fill enclosed holes smaller than this (keep real lakes)
 const BRIDGE_MAX_KM = 30; // bridge part-gaps smaller than this …
 const BRIDGE_MIN_KM = 0.3; // … but only real gaps (a pair in (BRIDGE_MIN, BRIDGE_MAX))
 const BRIDGE_EXT_KM = 2; // extend each bridge end into its part (ensures union overlap)
 const BRIDGE_HW_MIN_KM = 2; // minimum half-width of a connector
 const BRIDGE_HW_MAX_KM = 20; // cap so a connector never becomes a big blob
 const R4 = 4; // coordinate precision (decimal places)
 const SLIVER_EPS_KM2 = 1e-6; // drop only truly-degenerate (≈zero-area) parts
 // --- area model (identical to coarsen-regions.mjs / regions.test.ts) -----------
 const KM_LON = 111.32;
 const KM_LAT = 110.574;
 const rad = (deg) => (deg * Math.PI) / 180;
 function ringAreaKm2(ring) {
  let lat = 0;
  for (const [, la] of ring) lat += la;
  const kx = KM_LON * Math.cos(rad(ring.length ? lat / ring.length : 0));
  let a = 0;
  const n = ring.length;
  for (let i = 0; i < n; i++) {
    const [lon1, lat1] = ring[i];
    const [lon2, lat2] = ring[(i + 1) % n];
    a += lon1 * kx * (lat2 * KM_LAT) - lon2 * kx * (lat1 * KM_LAT);
  }
  return Math.abs(a / 2);
 }
 function geomAreaKm2(geom) {
  if (!geom) return 0;
  const polys = geom.type === 'Polygon' ? [geom.coordinates] : geom.coordinates;
  let total = 0;
  for (const poly of polys) total += ringAreaKm2(poly[0]);
  return total;
 }
 // --- rounding / normalization (same conventions as coarsen-regions.mjs) --------
 const rN = (v, N) => Math.round(v * 10 ** N) / 10 ** N;
 function roundRing(ring, N = R4) {
  const out = [];
  for (const [x, y] of ring) {
    const p = [rN(x, N), rN(y, N)];
    const last = out[out.length - 1];
    if (!last || last[0] !== p[0] || last[1] !== p[1]) out.push(p);
  }
  if (out.length > 1 && out[0][0] === out[out.length - 1][0] && out[0][1] === out[out.length - 1][1]) out.pop();
  if (out.length < 3) return out;
  return [...out, [...out[0]]];
 }
 function roundAll(geom) {
  if (!geom || (geom.type !== 'Polygon' && geom.type !== 'MultiPolygon')) return null;
  const polys = (geom.type === 'Polygon' ? [geom.coordinates] : geom.coordinates)
    .map((poly) => poly.map((ring) => roundRing(ring)))
    .filter((poly) => poly.length >= 1 && poly.every((r) => r.length >= 3));
  if (!polys.length) return null;
  if (polys.length === 1 && geom.type === 'Polygon') return { type: 'Polygon', coordinates: polys[0] };
  return { type: 'MultiPolygon', coordinates: polys };
 }
 function normalizeGeom(geom) {
  const rounded = roundAll(geom);
  if (!rounded) return null;
  const all = rounded.type === 'Polygon' ? [rounded.coordinates] : rounded.coordinates;
  const kept = all.filter((poly) => ringAreaKm2(poly[0]) >= SLIVER_EPS_KM2);
  const polys = kept.length ? kept : all;
  if (polys.length === 1 && rounded.type === 'Polygon') return { type: 'Polygon', coordinates: polys[0] };
  return { type: 'MultiPolygon', coordinates: polys };
 }
 // --- closest-point measurement (decimated planar point↔segment, ~km) ----------
 function toXY(ring) {
  let lat = 0;
  for (const [, la] of ring) lat += la;
  const kx = KM_LON * Math.cos(rad(ring.length ? lat / ring.length : 0));
  return ring.map(([lon, lat]) => [lon * kx, lat * KM_LAT]);
 }
 function dec(pts, maxN = 200) {
  if (pts.length <= maxN) return pts;
  const step = Math.ceil(pts.length / maxN);
  const out = [];
  for (let i = 0; i < pts.length; i += step) out.push(pts[i]);
  return out;
 }
 /**
 * Closest point-pair between two planar rings: returns { d, p, q } with p on A,
 * q on B and d = |p-q| in km (both on the decimated rings — a good-enough
 * approximation for bridging; a tiny offset is corrected by the extension).
 */
 function ringClosest(AX, BX) {
  const A = dec(AX), B = dec(BX);
  let best = Infinity, bestP = null, bestQ = null;
  for (const p of A) {
    for (let i = 0; i < B.length - 1; i++) {
      const a = B[i], b = B[i + 1];
      const dx = b[0] - a[0], dy = b[1] - a[1];
      const l2 = dx * dx + dy * dy;
      let t = l2 === 0 ? 0 : ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / l2;
      t = Math.max(0, Math.min(1, t));
      const c = [a[0] + t * dx, a[1] + t * dy];
      const dd = Math.hypot(p[0] - c[0], p[1] - c[1]);
      if (dd < best) { best = dd; bestP = p; bestQ = c; }
    }
  }
  for (const p of B) {
    for (let i = 0; i < A.length - 1; i++) {
      const a = A[i], b = A[i + 1];
      const dx = b[0] - a[0], dy = b[1] - a[1];
      const l2 = dx * dx + dy * dy;
      let t = l2 === 0 ? 0 : ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / l2;
      t = Math.max(0, Math.min(1, t));
      const c = [a[0] + t * dx, a[1] + t * dy];
      const dd = Math.hypot(p[0] - c[0], p[1] - c[1]);
      if (dd < best) { best = dd; bestP = c; bestQ = p; }
    }
  }
  return { d: best, p: bestP, q: bestQ };
 }
 /**
 * Build a thin connector (a quad in lon/lat) between two closest points p, q
 * (both in planar km). The connector is extended a little into each part so the
 * boolean union joins them, and its half-width is wide enough to span the local
 * gap (capped so it never becomes a big blob).
 */
 function makeBridgeRing(p, q) {
  const gap = Math.hypot(q[0] - p[0], q[1] - p[1]);
  if (gap < 1e-3) return null; // coincident → nothing to bridge
  const midLat = (p[1] / KM_LAT + q[1] / KM_LAT) / 2;
  const kx = KM_LON * Math.cos(rad(midLat));
  const ux = (q[0] - p[0]) / gap, uy = (q[1] - p[1]) / gap; // unit p→q
  const nx = -uy, ny = ux; // perpendicular
  const hw = Math.min(BRIDGE_HW_MAX_KM, Math.max(BRIDGE_HW_MIN_KM, gap / 2));
  const ext = BRIDGE_EXT_KM;
  const pExt = [p[0] - ux * ext, p[1] - uy * ext];
  const qExt = [q[0] + ux * ext, q[1] + uy * ext];
  const toLL = ([x, y]) => [rN(x / kx, R4), rN(y / KM_LAT, R4)];
  const c1 = toLL([pExt[0] + nx * hw, pExt[1] + ny * hw]);
  const c2 = toLL([qExt[0] + nx * hw, qExt[1] + ny * hw]);
  const c3 = toLL([qExt[0] - nx * hw, qExt[1] - ny * hw]);
  const c4 = toLL([pExt[0] - nx * hw, pExt[1] - ny * hw]);
  return [c1, c2, c3, c4, c1];
 }
 /** Bridge all close pairs of a MultiPolygon and union everything into one shape. */
 function bridgeParts(geom) {
  const parts = geom.coordinates;
  const partsXY = parts.map((p) => toXY(p[0]));
  const bridges = [];
  let bridgedPairs = 0;
  for (let i = 0; i < partsXY.length; i++) {
    for (let j = i + 1; j < partsXY.length; j++) {
      const { d, p, q } = ringClosest(partsXY[i], partsXY[j]);
      if (d > BRIDGE_MIN_KM && d < BRIDGE_MAX_KM) {
        const ring = makeBridgeRing(p, q);
        if (ring) { bridges.push(ring); bridgedPairs++; }
      }
    }
  }
  if (!bridges.length) return { geom, bridgedPairs: 0, changed: false };
  // union: original parts (as Polygons) + connector rings (as Polygons)
  const feats = parts.map((poly) => ({ type: 'Feature', geometry: { type: 'Polygon', coordinates: poly } }));
  for (const ring of bridges) feats.push({ type: 'Feature', geometry: { type: 'Polygon', coordinates: [ring] } });
  let u;
  try {
    u = union(featureCollection(feats));
  } catch (e) {
    console.error(`    [warn] bridge union failed: ${e.message}`);
    return { geom, bridgedPairs: 0, changed: false };
  }
  const norm = u ? normalizeGeom(u.geometry) : null;
  // Guard: a good bridge only adds a little area. Reject the union if it lost
  // area (< 0.8×, a bad union that ate parts) or over-filled (> 1.3×, e.g. many
  // overlapping bridges in a dense archipelago) — keep the original instead.
  if (norm) {
    const na = geomAreaKm2(norm);
    const oa = geomAreaKm2(geom);
    if (oa > 0 && (na < 0.8 * oa || na > 1.3 * oa)) {
      return { geom, bridgedPairs: 0, changed: false };
    }
  }
  return { geom: norm ?? geom, bridgedPairs, changed: true, bridgedParts: u ? (u.geometry.type === 'Polygon' ? 1 : u.geometry.coordinates.length) : parts.length };
 }
 // --- main ----------------------------------------------------------------------
 function main() {
  const t0 = Date.now();
  const fc = JSON.parse(readFileSync(SRC, 'utf8'));
  const inKB = (Buffer.byteLength(readFileSync(SRC)) / 1024).toFixed(0);
  console.log(`input: ${fc.features.length} regions (${inKB} KB) from ${SRC}`);
  console.log(`mode: holes <${HOLE_AREA_MAX_KM2} km2 filled, larger kept${BRIDGE ? `; + bridging part-gaps in (${BRIDGE_MIN_KM}, ${BRIDGE_MAX_KM}) km` : ''}`);
  // diagnostics
  let holesFilled = 0, holesFilledArea = 0, holesKept = 0, holesKeptArea = 0, featuresTouchedHole = 0;
  let bridgedFeatures = 0, bridgedPairs = 0, partsBefore = 0, partsAfter = 0, areaBefore = 0, areaAfter = 0;
  const bridgeSamples = [];
  const keptHoleSamples = [];
  const outFeatures = [];
  for (const f of fc.features) {
    let geom = f.geometry;
    // ---- Opt-in: bridge close parts (additive connector + union) ----
    if (BRIDGE && geom.type === 'MultiPolygon' && geom.coordinates.length >= 2) {
      const before = { parts: geom.coordinates.length, area: geomAreaKm2(geom) };
      const res = bridgeParts(geom);
      if (res.changed) {
        geom = res.geom;
        bridgedFeatures++;
        bridgedPairs += res.bridgedPairs;
        partsBefore += before.parts;
        partsAfter += geom.type === 'Polygon' ? 1 : geom.coordinates.length;
        areaBefore += before.area;
        areaAfter += geomAreaKm2(geom);
        if (bridgeSamples.length < 20)
          bridgeSamples.push(`${f.id} ${f.properties.name} (${f.properties.parent}): ${before.parts}p→${geom.type === 'Polygon' ? 1 : geom.coordinates.length}p, ${res.bridgedPairs} bridge(s), ${Math.round(before.area)}→${Math.round(geomAreaKm2(geom))} km2`);
      }
    }
    // ---- Fill small enclosed holes: drop inner rings < threshold, keep larger ----
    const isMulti = geom.type === 'MultiPolygon';
    const polys = isMulti ? geom.coordinates : [geom.coordinates];
    let touchedHole = false;
    const newPolys = polys.map((poly) => {
      const kept = [poly[0]]; // outer ring always kept
      for (let i = 1; i < poly.length; i++) {
        const area = ringAreaKm2(poly[i]);
        if (area < 1e-6) continue; // degenerate — drop
        if (area < HOLE_AREA_MAX_KM2) {
          holesFilled++; holesFilledArea += area; touchedHole = true; // fill (drop)
        } else {
          holesKept++; holesKeptArea += area;
          kept.push(poly[i]); // a genuine water body — keep the hole
          if (keptHoleSamples.length < 20) keptHoleSamples.push(`${f.id}(${f.properties.parent}) ${Math.round(area)} km2`);
        }
      }
      return kept;
    });
    if (touchedHole) featuresTouchedHole++;
    const rebuilt = isMulti
      ? { type: 'MultiPolygon', coordinates: newPolys }
      : { type: 'Polygon', coordinates: newPolys[0] };
    // normalize (round 4dp, drop degenerate). NEVER drop a feature: if nothing
    // usable survives (a degenerate 3-pt 0-area micro-dot), keep the
    // hole-filled (rebuilt) geometry, else the untouched original.
    const norm = normalizeGeom(rebuilt);
    outFeatures.push({ type: 'Feature', id: f.id, properties: { name: f.properties.name, parent: f.properties.parent }, geometry: norm ?? rebuilt ?? geom });
  }
  const out = { type: 'FeatureCollection', features: outFeatures };
  const json = JSON.stringify(out);
  const outKB = (Buffer.byteLength(json) / 1024).toFixed(0);
  writeFileSync(OUT, json + '\n');
  console.log(`\n--- RESULTS ---`);
  console.log(`regions: ${fc.features.length} → ${out.features.length} (should be unchanged)`);
  console.log(`file: ${inKB} KB → ${outKB} KB (${(outKB / 1024).toFixed(2)} MB)`);
  console.log(`\nENCLOSED HOLES:`);
  console.log(`  filled ${holesFilled} holes (${Math.round(holesFilledArea).toLocaleString('en-US')} km2) in ${featuresTouchedHole} features`);
  console.log(`  kept ${holesKept} hole(s) (${Math.round(holesKeptArea).toLocaleString('en-US')} km2) as real water`);
  if (keptHoleSamples.length) console.log(`  kept-hole list: ${keptHoleSamples.join(', ')}`);
  if (BRIDGE) {
    console.log(`\nBRIDGING (part-gaps):`);
    console.log(`  bridged ${bridgedFeatures} features (${bridgedPairs} close pairs): parts ${partsBefore} → ${partsAfter}, area ${Math.round(areaBefore).toLocaleString('en-US')} → ${Math.round(areaAfter).toLocaleString('en-US')} km2`);
    for (const s of bridgeSamples) console.log(`    ${s}`);
  } else {
    console.log(`\nbridging: skipped (pass --bridge to enable)`);
  }
  console.log(`\nwrote ${OUT}; elapsed ${((Date.now() - t0) / 1000).toFixed(1)}s`);
 }
 main();
@@ -0,0 +1,612 @@
 #!/usr/bin/env node
 /**
 * scripts/coarsen-regions.mjs — coarsens the committed `public/regions.geo.json`
 * in place, so the map is genuinely coarser, not just finer-grained.
 *
 * Rule (per user request: "focus on joining cities to the region around it.
 * Regions shouldn't be smaller than around 100x100km, excluding islands"):
 *
 *   FLOOR   — no region should be smaller than ~100×100 km = 10,000 km²,
 *             EXCEPT islands.
 *   ISLAND  — a region is an island if it has NO same-country neighbor: no
 *             other region with the same `properties.parent` whose bounding box
 *             is within CLOSE_DEG (≈≤22 km) of its own. Small islands stay
 *             as-is regardless of size (Corsica, the Hawaiian counties,
 *             Okinawa, the Faroes, island micro-states, …).
 *   MERGE   — a region that is small (area < FLOOR) AND not an island is
 *             merged into its NEAREST same-country neighbor (nearest by
 *             centroid distance; tie-break → larger area, then lexicographic
 *             id). Standalone cities (FR-75 Paris, the Latvian/Slovenian
 *             municipalities, the UK's 231 micro-districts) collapse into the
 *             region around them.
 *   DISSOLVE— the merge is a real boolean union (`@turf/union`, polygon-
 *             clipping): the shared boundary between the merged region and its
 *             host is removed, producing a single clean polygon — not two
 *             overlapping shapes. (Fallback if the union fails on a pair:
 *             combine the rings into a MultiPolygon without dissolving; the
 *             count of such fallbacks is reported.)
 *   ITERATE — passes run smallest-area-first (small regions merge into their
 *             neighbors, which grow and then absorb more). After each pass the
 *             area/neighbor/centroid metrics are recomputed; it stops at the
 *             fixed point (no small non-island region left) or at MAX_ITER.
 *   IDENTITY— the host (the region merged INTO) keeps its own `id` and
 *             `name`; the absorbed region's id is dropped. `properties.parent`
 *             is unchanged, so the map code (WorldMap/App/protocol/map.ts)
 *             keeps working untouched.
 *
 * Deterministic: fixed processing order (area, then id), deterministic
 * neighbor choice (distance, then -area, then id), deterministic boolean
 * union. Re-running on the coarsened file reaches the fixed point
 * immediately and rewrites a byte-identical file.
 *
 * Area model: the SAME planar approximation the validation test uses
 * (`scripts/regions.test.ts`) — `x = lon·111.32·cos(midLat)`,
 * `y = lat·110.574` km, shoelace per OUTER ring (holes ignored), each ring at
 * its own mean latitude — so the script's merge decisions and the test's
 * assertions measure the same quantity.
 *
 * Longitude handling: every ring is unwrapped to a continuous [0,360)-derived
 * space before its bbox/centroid is computed (the shortest-difference
 * "np.unwrap" scheme), which makes the one full-360° antimeridian-wrapping
 * feature (Antarctica's mainland ring) and any seam-straddling ring behave
 * correctly; cross-feature longitude gaps use the 360°-cyclic minimum.
 *
 * Output: features sorted by (parent, id) (the same comparator as
 * `scripts/generate-regions.mjs`), coordinates rounded to 4 decimal places,
 * single line of JSON + trailing newline. If the file would exceed the
 * ~5 MB guard, a light Douglas–Peucker pass (tolerances escalated through a
 * small table) brings it under ~4 MB before writing.
 *
 * Run: `npm run coarsen:regions`
 */
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { union } from '@turf/union';
 import { feature, featureCollection } from '@turf/helpers';
 const here = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(here, '..');
 const FILE = path.join(root, 'public', 'regions.geo.json');
 // --- parameters ---------------------------------------------------------------
 const AREA_FLOOR_KM2 = 10_000; // ~100×100 km floor for non-island regions
 const CLOSE_DEG = 0.2; // "spatially close" bbox gap (both lat and lon ≤ this; ≈≤22 km)
 const MAX_ITER = 20; // safety cap on fixed-point passes (spec: ~15)
 const SIZE_GUARD_KB = 5_120; // keep the committed file under ~5 MB
 const SIZE_TARGET_KB = 4_096; // …and land under ~4 MB once simplified
 const DP_STEPS = [0.05, 0.1, 0.2, 0.3, 0.5, 0.75, 1.0]; // Douglas–Peucker tolerances (degrees)
 const R4 = 4; // coordinate precision (decimal places, ≈11 m)
 const SLIVER_EPS_KM2 = 1e-6; // drop only truly-degenerate (≈zero-area) clipper slivers
 // --- area model (identical to scripts/regions.test.ts) -------------------------
 const KM_LON = 111.32;
 const KM_LAT = 110.574;
 const rad = (deg) => (deg * Math.PI) / 180;
 /** Shoelace area (km²) of one ring, measured at the ring's own mean latitude. */
 function ringAreaKm2(ring) {
  let lat = 0;
  for (const [, la] of ring) lat += la;
  const kx = KM_LON * Math.cos(rad(ring.length ? lat / ring.length : 0));
  let a = 0;
  const n = ring.length;
  for (let i = 0; i < n; i++) {
    const [lon1, lat1] = ring[i];
    const [lon2, lat2] = ring[(i + 1) % n];
    a += lon1 * kx * (lat2 * KM_LAT) - lon2 * kx * (lat1 * KM_LAT);
  }
  return Math.abs(a / 2);
 }
 /** Sum of a geometry's outer-ring areas (holes are lakes — ignored by design). */
 function geomAreaKm2(geom) {
  if (!geom) return 0;
  const polys = geom.type === 'Polygon' ? [geom.coordinates] : geom.coordinates;
  let total = 0;
  for (const poly of polys) total += ringAreaKm2(poly[0]);
  return total;
 }
 // --- longitude unwrapping (antimeridian-safe) ----------------------------------
 /**
 * Unwrap a ring's longitudes to a continuous real line (the "np.unwrap"
 * shortest-difference scheme, anchored at the first vertex's [0,360) value).
 * Returns { lons, full } — `full` when the unwrapped span is ≥ 300°, i.e. the
 * ring is a full-360° antimeridian band (Antarctica's mainland ring).
 */
 function unwrapRing(ring) {
  const n = ring.length;
  const norm = (x) => ((x % 360) + 360) % 360; // → [0,360)
  const u = new Array(n);
  u[0] = norm(ring[0][0]);
  for (let i = 1; i < n; i++) {
    // The PREVIOUS unwrapped value may lie outside [0,360) (it accumulates),
    // so normalize it back before measuring the difference; otherwise a bogus
    // ~180° jump is inserted and the ring's span balloons to ~180°.
    const a = norm(u[i - 1]);
    const b = norm(ring[i][0]);
    const d = (((b - a) % 360) + 540) % 360 - 180; // shortest signed diff in (-180, 180]
    u[i] = u[i - 1] + d;
  }
  let min = Infinity;
  let max = -Infinity;
  for (const v of u) {
    if (v < min) min = v;
    if (v > max) max = v;
  }
  return { lons: u, full: max - min >= 300 };
 }
 /**
 * Cyclic 1-D gap (degrees) between two tight longitude intervals in their own
 * unwrapped [0,360)-derived spaces. Tries the three 360° shifts of `b` so
 * different unwrap anchors reconcile; a `full` interval is close to everything.
 */
 function lonGap(intA, intB) {
  if (intA.full || intB.full) return 0;
  let best = Infinity;
  for (const k of [-1, 0, 1]) {
    const a2 = intB.a + 360 * k;
    const b2 = intB.b + 360 * k;
    const gap = intA.b < a2 ? a2 - intA.b : b2 < intA.a ? intA.a - b2 : 0;
    if (gap < best) best = gap;
  }
  return best;
 }
 // --- geometry helpers ----------------------------------------------------------
 const rN = (v, N) => Math.round(v * 10 ** N) / 10 ** N;
 /** Round a ring to 4 dp, drop consecutive duplicates, and (re-)close it. */
 function roundRing(ring, N = R4) {
  const out = [];
  for (const [x, y] of ring) {
    const p = [rN(x, N), rN(y, N)];
    const last = out[out.length - 1];
    if (!last || last[0] !== p[0] || last[1] !== p[1]) out.push(p);
  }
  if (
    out.length > 1 &&
    out[0][0] === out[out.length - 1][0] &&
    out[0][1] === out[out.length - 1][1]
  )
    out.pop();
  if (out.length < 3) return out; // degenerate; caller drops it
  return [...out, [...out[0]]];
 }
 /**
 * Round every ring of a geometry to 4 dp, drop degenerate rings (<3 pts) and
 * empty polygons, keep the Polygon/MultiPolygon type (a single-part
 * MultiPolygon collapses to Polygon). Returns null if nothing usable survived.
 */
 function roundAll(geom) {
  if (!geom || (geom.type !== 'Polygon' && geom.type !== 'MultiPolygon')) return null;
  const polys = (geom.type === 'Polygon' ? [geom.coordinates] : geom.coordinates)
    .map((poly) => poly.map((ring) => roundRing(ring)))
    .filter((poly) => poly.length >= 1 && poly.every((r) => r.length >= 3));
  if (!polys.length) return null;
  if (polys.length === 1 && geom.type === 'Polygon') return { type: 'Polygon', coordinates: polys[0] };
  return { type: 'MultiPolygon', coordinates: polys };
 }
 /**
 * Normalize a union output (or fallback MultiPolygon): roundAll, then drop
 * truly-degenerate (≈zero-area, < SLIVER_EPS_KM2) polygons the clipper can
 * leave behind at shared boundaries. It never drops *every* part — a merge of
 * two sub-resolution (zero-area) micro-regions must still collapse into one
 * (degenerate) region rather than vanish. Returns null only when the input
 * itself had no usable ring (e.g. `null`).
 */
 function normalizeGeom(geom) {
  const rounded = roundAll(geom);
  if (!rounded) return null;
  const all = rounded.type === 'Polygon' ? [rounded.coordinates] : rounded.coordinates;
  const kept = all.filter((poly) => ringAreaKm2(poly[0]) >= SLIVER_EPS_KM2);
  const polys = kept.length ? kept : all;
  if (polys.length === 1 && rounded.type === 'Polygon') return { type: 'Polygon', coordinates: polys[0] };
  return { type: 'MultiPolygon', coordinates: polys };
 }
 /** Douglas–Peucker of an OPEN point sequence (keeps endpoints). */
 function dpOpen(pts, tol) {
  if (pts.length < 3) return pts;
  let maxD = 0;
  let idx = 0;
  const a = pts[0];
  const b = pts[pts.length - 1];
  for (let i = 1; i < pts.length - 1; i++) {
    const dx = b[0] - a[0];
    const dy = b[1] - a[1];
    const l2 = dx * dx + dy * dy;
    let t = l2 === 0 ? 0 : ((pts[i][0] - a[0]) * dx + (pts[i][1] - a[1]) * dy) / l2;
    t = Math.max(0, Math.min(1, t));
    const d = Math.hypot(pts[i][0] - (a[0] + t * dx), pts[i][1] - (a[1] + t * dy));
    if (d > maxD) {
      maxD = d;
      idx = i;
    }
  }
  if (maxD > tol) {
    const left = dpOpen(pts.slice(0, idx + 1), tol);
    const right = dpOpen(pts.slice(idx), tol);
    return left.concat(right.slice(1));
  }
  return [a, b];
 }
 /** Douglas–Peucker a CLOSED ring at tolerance `tol` (0 = skip). */
 function dpRing(ring, tol) {
  if (tol <= 0 || ring.length < 4) return ring;
  let pts = ring;
  if (pts[0][0] === pts[pts.length - 1][0] && pts[0][1] === pts[pts.length - 1][1]) pts = pts.slice(0, -1);
  const s = dpOpen(pts, tol);
  if (s.length < 3) return ring;
  return [...s, [...s[0]]];
 }
 /** Round (and optionally DP-simplify) every ring of a geometry. */
 function transformGeom(geom, tol) {
  const polys = (geom.type === 'Polygon' ? [geom.coordinates] : geom.coordinates)
    .map((poly) => poly.map((ring) => roundRing(ring, R4)).map((ring) => (tol > 0 ? dpRing(ring, tol) : ring)))
    .filter((poly) => poly.length >= 1 && poly.every((r) => r.length >= 3));
  if (!polys.length) return null;
  if (polys.length === 1 && geom.type === 'Polygon') return { type: 'Polygon', coordinates: polys[0] };
  return { type: 'MultiPolygon', coordinates: polys };
 }
 // --- region record -------------------------------------------------------------
 /**
 * A region under management. `lonInt` is the tight longitude interval in
 * [0,360)-derived unwrapped space (or `full` for a 360° band); `(clat, clon)`
 * is the area-weighted centroid of the LARGEST outer ring (the region's
 * "location"), unwrapped for its ring then wrapped to [-180,180) for
 * cyclic-distance use.
 */
 class Region {
  constructor(f) {
    this.id = f.id;
    this.name = f.properties.name;
    this.parent = f.properties.parent;
    this.geom = f.geometry;
    this.rawGeom = null; // last pre-normalization union output (safety net for build())
    this.dead = false;
    this.metrics();
  }
  metrics() {
    this.area = geomAreaKm2(this.geom);
    const polys = this.geom.type === 'Polygon' ? [this.geom.coordinates] : this.geom.coordinates;
    let latMin = Infinity;
    let latMax = -Infinity;
    let lonA = Infinity;
    let lonB = -Infinity;
    let lonFull = false;
    let bestRing = null;
    let bestArea = -1;
    for (const poly of polys) {
      const outer = poly[0];
      for (const [, la] of outer) {
        if (la < latMin) latMin = la;
        if (la > latMax) latMax = la;
      }
      const { lons, full } = unwrapRing(outer);
      if (full) lonFull = true;
      let a = Infinity;
      let b = -Infinity;
      for (const v of lons) {
        if (v < a) a = v;
        if (v > b) b = v;
      }
      lonA = Math.min(lonA, a);
      lonB = Math.max(lonB, b);
      const ar = ringAreaKm2(outer);
      if (ar > bestArea) {
        bestArea = ar;
        bestRing = outer;
      }
    }
    this.lonInt = { a: lonA, b: lonB, full: lonFull };
    this.latMin = latMin;
    this.latMax = latMax;
    // area-weighted centroid of the largest outer ring, in unwrapped space
    const { lons } = unwrapRing(bestRing);
    const lats = bestRing.map((p) => p[1]);
    const n = bestRing.length;
    let A = 0;
    let cx = 0;
    let cy = 0;
    for (let i = 0; i < n; i++) {
      const x1 = lons[i];
      const y1 = lats[i];
      const x2 = lons[(i + 1) % n];
      const y2 = lats[(i + 1) % n];
      const f = x1 * y2 - x2 * y1;
      A += f;
      cx += (x1 + x2) * f;
      cy += (y1 + y2) * f;
    }
    A /= 2;
    if (Math.abs(A) > 1e-9) {
      cx /= 6 * A;
      cy /= 6 * A;
    } else {
      cx = (lonA + lonB) / 2;
      cy = (latMin + latMax) / 2;
    }
    this.clon = (((cx + 180) % 360) + 360) % 360 - 180;
    this.clat = cy;
  }
  /** Cyclic planar distance (km) to another region's centroid. */
  distKm(o) {
    let dlon = Math.abs(this.clon - o.clon) % 360;
    if (dlon > 180) dlon = 360 - dlon;
    const midLat = rad((this.clat + o.clat) / 2);
    return Math.hypot(dlon * KM_LON * Math.cos(midLat), (this.clat - o.clat) * KM_LAT);
  }
  /** Bounding-box closeness to another same-space region (see CLOSE_DEG). */
  closeTo(o) {
    const latGap = this.latMax < o.latMin ? o.latMin - this.latMax : o.latMax < this.latMin ? this.latMin - o.latMax : 0;
    if (latGap > CLOSE_DEG) return false;
    return lonGap(this.lonInt, o.lonInt) <= CLOSE_DEG;
  }
 }
 /**
 * A "degenerate" region is a zero-area artifact: after 4-dp rounding its only
 * ring has <3 distinct points (a line/point, e.g. a micro-municipality that
 * v0.13's Douglas–Peucker collapsed to `[A, B, A]`). It contributes no area,
 * so it can never be dissolved by the clipper (which returns null) nor kept
 * through ring-dropping (which loses the 2-point ring). Merging one is purely
 * an absorption: the host keeps its own geometry.
 */
 const isDegenerate = (r) => r.area < SLIVER_EPS_KM2;
 // --- main ----------------------------------------------------------------------
 function main() {
  const fc0 = JSON.parse(readFileSync(FILE, 'utf8'));
  const regions = fc0.features.map((f) => new Region(f));
  const byParent = new Map();
  for (const r of regions) {
    if (!byParent.has(r.parent)) byParent.set(r.parent, []);
    byParent.get(r.parent).push(r);
  }
  const t0 = Date.now();
  console.log(`input: ${fc0.features.length} regions across ${byParent.size} countries (${(Buffer.byteLength(readFileSync(FILE)) / 1024).toFixed(0)} KB)`);
  console.log(`parameters: floor ${AREA_FLOOR_KM2.toLocaleString('en-US')} km2, close ${CLOSE_DEG} deg, max ${MAX_ITER} passes`);
  const merges = []; // { from, fromName, fromArea, to, toName, toAreaAfter }
  let fallbackUnions = 0;
  // The fixed-point loop. Each pass: every region that is small AND has a
  // close same-country neighbor merges into the nearest such neighbor
  // (nearest by centroid distance; tie → larger area → lexicographic id).
  for (let pass = 0; pass < MAX_ITER; pass++) {
    let skippedIsland = 0;
    let skippedGrew = 0;
    const items = [];
    for (const r of regions) {
      if (r.dead || r.area >= AREA_FLOOR_KM2) continue;
      const siblings = byParent.get(r.parent);
      for (const s of siblings) {
        if (s !== r && !s.dead && r.closeTo(s)) {
          items.push(r);
          break;
        }
      }
    }
    if (!items.length) {
      console.log(`after pass ${pass}: fixed point reached (no small non-island regions left)`);
      break;
    }
    items.sort((a, b) => (a.area !== b.area ? a.area - b.area : a.id < b.id ? -1 : 1));
    let merged = 0;
    for (const r of items) {
      if (r.dead) continue;
      if (r.area >= AREA_FLOOR_KM2) {
        skippedGrew++;
        continue; // absorbed a smaller region earlier this pass and crossed the floor
      }
      const siblings = byParent.get(r.parent);
      // Close same-country neighbors as of NOW (mid-pass): some may have died
      // earlier in this pass.
      const close = [];
      for (const s of siblings) if (s !== r && !s.dead && r.closeTo(s)) close.push(s);
      if (!close.length) {
        skippedIsland++;
        continue; // lost its last close neighbor this pass → island now → exempt
      }
      // Prefer a REAL (non-degenerate) host so real regions dissolve cleanly;
      // fall back to any close neighbor only when no real one is nearby.
      const realCands = close.filter((s) => !isDegenerate(s));
      const pool = realCands.length ? realCands : close;
      let host = null;
      for (const s of pool) {
        if (
          !host ||
          r.distKm(s) < r.distKm(host) ||
          (r.distKm(s) === r.distKm(host) &&
            (s.area !== host.area ? s.area > host.area : s.id < host.id))
        )
          host = s;
      }
      if (isDegenerate(r)) {
        // r is a zero-area artifact (line/point): it contributes no area, so the
        // merge is a pure absorption — the host keeps its own geometry (a real
        // host is untouched; if the host is also degenerate a cluster of dots
        // collapses to one). Never route degenerate input through the clipper
        // (returns null) or ring-dropping (would lose the 2-point ring the map
        // already renders).
        r.dead = true;
        merged++;
        merges.push({ from: r.id, fromName: r.name, fromArea: r.area, to: host.id, toName: host.name, toAreaAfter: host.area });
        continue;
      }
      if (isDegenerate(host)) {
        // r is real but the chosen host is a zero-area artifact: the host takes
        // on r's geometry (keeping its own id/name). No clipper needed.
        host.geom = r.geom;
        host.rawGeom = r.geom;
        host.metrics();
        r.dead = true;
        merged++;
        merges.push({ from: r.id, fromName: r.name, fromArea: r.area, to: host.id, toName: host.name, toAreaAfter: host.area });
        continue;
      }
      // Both real: dissolve via a boolean union; the host keeps its id/name
      // and the item vanishes. @turf/union@7 dispatches through geomEach, which
      // only understands a FeatureCollection / single Feature / bare geometry —
      // a raw array of features has no `.type` and throws "Unknown Geometry
      // Type". Wrap it.
      let unionGeom = null;
      let rawUnion = null;
      try {
        const u = union(featureCollection([feature(r.geom), feature(host.geom)]));
        rawUnion = u ? u.geometry : null;
        unionGeom = normalizeGeom(rawUnion);
      } catch (err) {
        console.error(`  [warn] union failed for ${r.id} into ${host.id} (${err.message}); combining without dissolve`);
        fallbackUnions++;
      }
      if (!unionGeom) {
        // fallback: no dissolve — keep both shapes in one MultiPolygon
        const polys = [...(r.geom.type === 'Polygon' ? [r.geom.coordinates] : r.geom.coordinates), ...(host.geom.type === 'Polygon' ? [host.geom.coordinates] : host.geom.coordinates)];
        rawUnion = { type: 'MultiPolygon', coordinates: polys };
        unionGeom = normalizeGeom(rawUnion);
        if (!unionGeom) fallbackUnions++;
      }
      if (!unionGeom) {
        console.error(`  [error] could not merge ${r.id} into ${host.id}; leaving ${r.id} as-is`);
        continue;
      }
      host.geom = unionGeom;
      host.rawGeom = rawUnion;
      host.metrics();
      r.dead = true;
      merged++;
      merges.push({ from: r.id, fromName: r.name, fromArea: r.area, to: host.id, toName: host.name, toAreaAfter: host.area });
    }
    const alive = regions.filter((r) => !r.dead).length;
    console.log(
      `pass ${pass + 1}: ${items.length} small non-island region(s) → ${merged} merged` +
        ` (${skippedGrew} crossed the floor, ${skippedIsland} became island) → ${alive} regions remain`,
    );
    if (merged === 0) {
      // items exist but nothing could merge (all became islands this pass) → stable
      console.log(`pass ${pass + 1}: no merges possible — stable state`);
      break;
    }
  }
  // --- assemble output ----------------------------------------------------------
  const alive = regions.filter((r) => !r.dead);
  const sortById = (a, b) =>
    a.parent !== b.parent ? (a.parent < b.parent ? -1 : 1) : a.id.localeCompare(b.id, 'en', { numeric: true });
  alive.sort(sortById);
  const build = (tol) => {
    const feats = [];
    for (const r of alive) {
      // Never drop a region: if the simplified/normalized geometry degenerated,
      // fall back to the raw (pre-normalization) union output, then to the
      // untouched input geometry.
      const g =
        transformGeom(r.geom, tol) ??
        (r.rawGeom ? transformGeom(r.rawGeom, 0) ?? r.rawGeom : r.geom);
      feats.push({ type: 'Feature', id: r.id, properties: { name: r.name, parent: r.parent }, geometry: g });
    }
    return { type: 'FeatureCollection', features: feats };
  };
  let out = build(0);
  let json = JSON.stringify(out);
  let sizeKB = Buffer.byteLength(json) / 1024;
  console.log(`\ncoarsened: ${fc0.features.length} → ${out.features.length} regions (${fc0.features.length - out.features.length} merged away)`);
  let usedTol = 0;
  if (sizeKB > SIZE_GUARD_KB) {
    for (const t of DP_STEPS) {
      out = build(t);
      json = JSON.stringify(out);
      sizeKB = Buffer.byteLength(json) / 1024;
      usedTol = t;
      console.log(`DP ${t}: ${sizeKB.toFixed(1)} KB`);
      if (sizeKB < SIZE_TARGET_KB) break;
    }
  }
  writeFileSync(FILE, json + '\n');
  // --- summary -------------------------------------------------------------------
  const areaOf = new Map();
  const counts = new Map();
  let maxA = 0;
  let maxR = null;
  for (const f of out.features) {
    const a = geomAreaKm2(f.geometry);
    areaOf.set(f.id, a);
    counts.set(f.properties.parent, (counts.get(f.properties.parent) ?? 0) + 1);
    if (a > maxA) {
      maxA = a;
      maxR = f;
    }
  }
  const ccounts = [...counts.values()].sort((a, b) => a - b);
  const median =
    ccounts.length % 2 ? ccounts[(ccounts.length - 1) / 2] : (ccounts[ccounts.length / 2 - 1] + ccounts[ccounts.length / 2]) / 2;
  const maxCountry = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
  // islands = small regions with no close same-country neighbor in the FINAL set
  const finalByParent = new Map();
  for (const f of out.features) {
    if (!finalByParent.has(f.properties.parent)) finalByParent.set(f.properties.parent, []);
    finalByParent.get(f.properties.parent).push(f);
  }
  // rebuild final metrics (light: only need island flag on the < FLOOR set)
  const finalRegions = out.features.map((f) => new Region(f));
  const finalByParent2 = new Map();
  for (const r of finalRegions) {
    if (!finalByParent2.has(r.parent)) finalByParent2.set(r.parent, []);
    finalByParent2.get(r.parent).push(r);
  }
  let smallIslands = 0;
  let smallNonIslands = 0;
  const islandSamples = [];
  for (const r of finalRegions) {
    if (r.area >= AREA_FLOOR_KM2) continue;
    let hasNeighbor = false;
    for (const s of finalByParent2.get(r.parent)) {
      if (s !== r && r.closeTo(s)) {
        hasNeighbor = true;
        break;
      }
    }
    if (hasNeighbor) smallNonIslands++;
    else {
      smallIslands++;
      if (islandSamples.length < 12) islandSamples.push(`${r.id} ${r.name} (${Math.round(r.area)} km2)`);
    }
  }
  console.log(`wrote ${FILE} — ${sizeKB.toFixed(1)} KB (${(sizeKB / 1024).toFixed(2)} MB)` + (usedTol ? ` [DP @ ${usedTol}°]` : ''));
  console.log(`per-country count: min ${ccounts[0]} / median ${median} / max ${ccounts[ccounts.length - 1]} (max: ${maxCountry[0]})`);
  console.log(`max region: ${maxR.id} (${maxR.properties.name}) ≈ ${Math.round(maxA).toLocaleString('en-US')} km2`);
  console.log(`small (<${AREA_FLOOR_KM2.toLocaleString('en-US')} km2) in final set: ${smallIslands + smallNonIslands} — ${smallIslands} islands (exempt) / ${smallNonIslands} non-island residuals`);
  if (islandSamples.length) console.log(`island samples: ${islandSamples.join(', ')}`);
  console.log(`fallback (non-dissolved) unions: ${fallbackUnions}`);
  console.log(`merge log (${merges.length} merges): first 15:`);
  for (const m of merges.slice(0, 15)) {
    console.log(`  ${m.from} (${m.fromName}, ${Math.round(m.fromArea)} km2) → ${m.to} (${m.toName}, now ${Math.round(m.toAreaAfter)} km2)`);
  }
  const logPath = '/tmp/opencode/coarsen-log.txt';
  writeFileSync(logPath, merges.map((m) => `${m.from}\t${m.fromName}\t${Math.round(m.fromArea)}\t${m.to}\t${m.toName}\t${Math.round(m.toAreaAfter)}`).join('\n') + '\n');
  console.log(`full merge log → ${logPath}; elapsed ${((Date.now() - t0) / 1000).toFixed(1)}s`);
 }
 main();
@@ -0,0 +1,364 @@
 #!/usr/bin/env node
 /**
 * Fill "no-one's-land" gaps left in `public/regions.geo.json` by the v0.14 coarsening merge.
 *
 * For each country, the gap = (country landmass) − (union of the country's sub-regions):
 * area inside the country's authoritative landmass that no sub-region covers. Each gap
 * fragment is assigned to the **nearest** sub-region (centroid haversine distance) and
 * appended to it as extra polygon part(s). A fragment is only added if:
 *
 *   • it is not a sub-tiny sliver (≥ GAP_MIN_KM2),
 *   • it does not fall inside an existing region's *hole* (water) — this keeps the
 *     Aral-basin hole in KZ-KZY open,
 *   • it is not byte-identical to a part the file already contains (polyclip sometimes
 *     re-emits a region's own outer ring with a phantom sliver hole; once the hole is
 *     cleaned the piece equals the existing part, and appending it would only grow the
 *     file on every re-run),
 *   • it has been clipped against every region of *other* countries (and against pieces
 *     already appended this run) that touch its bbox, so it never overlaps an existing
 *     region — no new cross-border overlaps are introduced.
 *
 * Holes found in gap fragments are kept only when they are real: pre-existing region
 * holes (matched by centroid) or enclaves of another country (e.g. Lesotho inside ZAF,
 * so the ZAF fragment stays a ring and never covers the LSO region); every other hole
 * is a polyclip phantom and is dropped.
 *
 * Standard GeoJSON (`{type, coordinates}`) throughout — the same shape the file and
 * MapLibre already use, and what @turf v7 expects.
 *
 * Usage:   node scripts/fill-gaps.mjs [inFile [outFile]]
 *   inFile  default: public/regions.geo.json
 *   outFile default: inFile (edit in place)
 * Env:      GAP_MIN_KM2 (default 25) — gap fragments below this area are ignored slivers.
 *
 * Deterministic: same input → same output. Re-running on an already-filled file is a
 * no-op (every re-discovered fragment is either a sub-threshold sliver, a phantom that
 * byte-matches an existing part, or already covered by the enlarged union), so the
 * result is idempotent.
 */
 import fs from "node:fs";
 import difference from "@turf/difference";
 import union from "@turf/union";
 import centroid from "@turf/centroid";
 import bbox from "@turf/bbox";
 import area from "@turf/area";
 import booleanPointInPolygon from "@turf/boolean-point-in-polygon";
 import distance from "@turf/distance";
 import { feature, featureCollection, multiPolygon, polygon, point } from "@turf/helpers";
 const GAP_MIN_KM2 = Number(process.env.GAP_MIN_KM2 ?? 25);
 const RING_MIN_KM2 = 1e-4; // drop degenerate (numerical-noise) rings
 // --------------------------------------------------------------------------- helpers
 /**
 * Round coordinates in place to 6 decimals (file convention). Accepts either a single
 * ring (array of positions) or a polygon part (array of rings) and detects the depth.
 */
 function roundCoords(coords) {
  const isRing = Array.isArray(coords[0]) && Array.isArray(coords[0][0]) ? false : true;
  const rings = isRing ? [coords] : coords;
  for (const ring of rings) for (const c of ring) {
    c[0] = Number(c[0].toFixed(6));
    c[1] = Number(c[1].toFixed(6));
  }
  return coords;
 }
 /** Area (km²) of a closed ring, 0 when degenerate/NaN. */
 function ringKm2(ring) {
  if (!isValidRing(ring)) return 0;
  try { return area(polygon([ring])) * 1e-6; } catch { return 0; }
 }
 /** A valid GeoJSON ring: ≥4 closed positions, each [finiteNumber, finiteNumber]. */
 function isValidRing(ring) {
  if (!Array.isArray(ring) || ring.length < 4) return false;
  for (const c of ring) {
    if (!Array.isArray(c) || c.length < 2) return false;
    if (typeof c[0] !== "number" || !Number.isFinite(c[0])) return false;
    if (typeof c[1] !== "number" || !Number.isFinite(c[1])) return false;
  }
  return true;
 }
 // Module-level refs populated in main before use (see keepHole).
 let preHoleCentroids = []; // centroids of holes present in the input file (kept verbatim)
 let otherLandmasses = [];  // { iso, feature } for every country landmass
 /**
 * Is this hole a "real" one that must be preserved? Kept when it is a pre-existing
 * region hole (centroid match, e.g. the Aral) or lies inside another country's
 * landmass (enclave, e.g. Lesotho). Otherwise it is a polyclip phantom → dropped.
 */
 function keepHole(hole, currentIso) {
  const hKm2 = ringKm2(hole);
  if (!(hKm2 >= RING_MIN_KM2)) return false; // degenerate / NaN
  const cm = centroid(polygon([hole])).geometry.coordinates;
  if (preHoleCentroids.some((p) => distance(cm, p) < 10)) return true;
  if (otherLandmasses.some((l) => l.iso !== currentIso && booleanPointInPolygon(point(cm), l.feature))) return true;
  return false;
 }
 /**
 * Clean a GeoJSON polygon part (`[outerRing, ...holeRings]`): round coordinates, keep
 * only real holes (see keepHole). Returns the cleaned part, or null if the outer ring
 * is degenerate.
 */
 function cleanPolygonPart(part, currentIso) {
  if (!Array.isArray(part) || part.length === 0) return null;
  const outer = part[0];
  if (!isValidRing(outer)) return null;
  const outerKm2 = ringKm2(outer);
  if (!(outerKm2 >= RING_MIN_KM2)) return null; // covers NaN too
  const holes = part.slice(1).filter((h) => isValidRing(h) && keepHole(h, currentIso));
  roundCoords([outer, ...holes]);
  return [outer, ...holes];
 }
 /** Split a geometry (Polygon|MultiPolygon) into cleaned polygon parts. */
 function partsOf(geom, iso) {
  if (!geom) return [];
  const raw = geom.type === "MultiPolygon" ? geom.coordinates : [geom.coordinates];
  const out = [];
  for (const p of raw) { const c = cleanPolygonPart(p, iso); if (c) out.push(c); }
  return out;
 }
 /** Rebuild a geometry (NOT a feature) from cleaned parts. */
 function toGeometry(parts) {
  // turf helpers return Features; take their .geometry ({type, coordinates}).
  return parts.length > 1 ? multiPolygon(parts).geometry : polygon(parts[0]).geometry;
 }
 /** Bbox of a polygon part, as [west, south, east, north]. */
 function partBBox(part) { return bbox(polygon(part)); }
 function bBoxesOverlap(a, b) {
  return !(a[2] < b[0] || a[0] > b[2] || a[3] < b[1] || a[1] > b[3]);
 }
 /** Sample points along a part's outer ring (start + every ~max(1, n/16)th vertex). */
 function samplePoints(part, maxN = 16) {
  const ring = part[0];
  const n = ring.length;
  if (n <= maxN) return ring;
  const step = Math.ceil(n / maxN);
  const out = [ring[0]];
  for (let i = step; i < n; i += step) out.push(ring[i]);
  return out;
 }
 // Module-level list of pre-existing region holes (water guard), built in main.
 let holeRings = []; // { bbox, poly }
 /** Does a gap piece overlap any pre-existing region hole (water)? */
 function overlapsAnyHole(piece, pieceCm) {
  const pBBox = partBBox(piece);
  const candidates = holeRings.filter((h) => bBoxesOverlap(pBBox, h.bbox));
  if (candidates.length === 0) return false;
  const pts = [pieceCm, ...samplePoints(piece)];
  return candidates.some((h) => pts.some((p) => booleanPointInPolygon(point(p), h.poly)));
 }
 // --------------------------------------------------------------------------- main
 const inFile = process.argv[2] ?? "public/regions.geo.json";
 const outFile = process.argv[3] ?? inFile;
 const geo = JSON.parse(fs.readFileSync(inFile, "utf8"));
 const countries = JSON.parse(fs.readFileSync(new URL("../public/countries.geo.json", import.meta.url), "utf8"));
 otherLandmasses = countries.features.map((f) => ({ iso: f.id, feature: f }));
 const features = geo.features;
 const regionsByParent = new Map();
 for (const f of features) {
  const p = f.properties.parent;
  if (!regionsByParent.has(p)) regionsByParent.set(p, []);
  regionsByParent.get(p).push(f);
 }
 // Region inner-ring (hole) list for the water-hole guard; also the centroids of every
 // pre-existing hole (so the hole policy never destroys one, e.g. KZ-KZY's Aral hole).
 for (const f of features) {
  const parts = f.geometry.type === "MultiPolygon" ? f.geometry.coordinates : [f.geometry.coordinates];
  for (const p of parts) for (const h of p.slice(1)) {
    if (Array.isArray(h) && h.length >= 4 && ringKm2(h) >= RING_MIN_KM2) {
      const poly = polygon([h]);
      holeRings.push({ bbox: bbox(poly), poly });
      preHoleCentroids.push(centroid(poly).geometry.coordinates);
    }
  }
 }
 // Every part already in the input file (string key) — used to skip phantom pieces that
 // re-emiss an existing part byte-for-byte.
 const existingPartSet = new Set();
 for (const f of features) {
  const parts = f.geometry.type === "MultiPolygon" ? f.geometry.coordinates : [f.geometry.coordinates];
  for (const p of parts) existingPartSet.add(JSON.stringify(p));
 }
 // All regions with bboxes, for cross-border clipping.
 const allRegions = features.map((f) => ({
  feature: f,
  parent: f.properties.parent,
  bbox: bbox(feature(f.geometry)),
 }));
 console.log(`input: ${inFile}`);
 console.log(`regions: ${features.length}  countries(with regions): ${regionsByParent.size}  region holes: ${holeRings.length}`);
 // Per-region running totals for the report.
 const added = new Map(); // feature -> { km2, parts }
 let totalSliverKm2 = 0, totalWaterKm2 = 0, totalFilledKm2 = 0, totalDupN = 0, totalClippedKm2 = 0, totalClipFailN = 0;
 // Pieces already appended this run (any country) — later pieces clip against these so
 // appended pieces never overlap each other either.
 const appendedSoFar = []; // { parent, bbox, part }
 for (const [iso, countryRegions] of regionsByParent) {
  const landmass = countries.features.find((c) => c.id === iso);
  if (!landmass) continue; // no authoritative landmass → nothing to fill against
  const feats = countryRegions.map((r) => feature(r.geometry));
  let unionGeom, diffGeom;
  try {
    // A country with a single sub-region has no union to compute: it IS the union.
    unionGeom = countryRegions.length === 1
      ? countryRegions[0].geometry
      : union(featureCollection(feats)).geometry;
    diffGeom = difference(featureCollection([landmass, { ...landmass, geometry: unionGeom }])).geometry;
  } catch (e) {
    console.log(`${iso}\tSKIPPED (${unionGeom ? "difference" : "union"} failed: ${e.message})`);
    continue;
  }
  if (!diffGeom) continue;
  const rawPieces = partsOf(diffGeom, iso); // cleaned gap fragments inside the landmass
  // Pass 1: filter (sliver / water / duplicate) and clip against foreign territory.
  const fillable = [];
  let sliverKm2 = 0, waterKm2 = 0, dupN = 0, clippedKm2 = 0, sliverN = 0, waterN = 0, clipFailN = 0;
  for (const piece of rawPieces) {
    const piecePoly = polygon(piece);
    const aKm2 = area(piecePoly) * 1e-6;
    if (aKm2 < GAP_MIN_KM2) { sliverKm2 += aKm2; sliverN++; continue; }
    const pieceCm = centroid(piecePoly).geometry.coordinates;
    if (overlapsAnyHole(piece, pieceCm)) { waterKm2 += aKm2; waterN++; continue; }
    if (existingPartSet.has(JSON.stringify(piece))) { dupN++; continue; }
    // Clip: remove any part of this piece that ANY existing region (own or foreign
    // country) or an already-appended piece claims. Clipped *sequentially* against
    // each touching target (more robust than one big union-difference): a target that
    // fails to clip is skipped and counted, not allowed to abort the whole piece.
    // Clipping against the country's OWN regions as well as foreign ones is what kills
    // the same-country overlaps: the gap is `landmass − union(own regions)`, and
    // polychip's difference can leave thin slivers of an own region inside that "gap";
    // re-differencing each fragment against the individual regions (simpler operands
    // than the big union) strips them out. Both operands are built as proper Features
    // carrying a real geometry — never `feature()` on an already-Feature object (that
    // double-wraps the geometry into the Feature itself and breaks polychip).
    const pBBox = partBBox(piece);
    const targets = [
      ...allRegions.filter((r) => bBoxesOverlap(r.bbox, pBBox)).map((r) => ({ feature: r.feature, bbox: r.bbox })),
      ...appendedSoFar.filter((a) => bBoxesOverlap(a.bbox, pBBox)).map((a) => ({ feature: polygon(a.part), bbox: a.bbox })),
    ];
    if (targets.length === 0) {
      fillable.push({ piece, aKm2, cm: pieceCm });
      continue;
    }
    let cur = { type: "Feature", properties: {}, geometry: piecePoly.geometry };
    let curBBox = pBBox;
    let covered = false;
    for (const t of targets) {
      if (!bBoxesOverlap(curBBox, t.bbox)) continue;
      let d;
      try {
        d = difference(featureCollection([cur, t.feature]));
      } catch {
        clipFailN++; // clip against this target failed: keep current (safe fallback)
        continue;
      }
      if (!d || !d.geometry) { covered = true; break; } // piece fully covered by this target
      cur = { type: "Feature", properties: {}, geometry: d.geometry };
      curBBox = bbox(cur);
    }
    if (covered || !cur.geometry) { clippedKm2 += aKm2; continue; } // fully covered by foreign territory
    const kept = [];
    for (const cp of partsOf(cur.geometry, iso)) {
      const cpArea = area(polygon(cp)) * 1e-6;
      if (cpArea < GAP_MIN_KM2) { sliverKm2 += cpArea; sliverN++; continue; }
      if (existingPartSet.has(JSON.stringify(cp))) { dupN++; continue; }
      kept.push({ piece: cp, aKm2: cpArea, cm: centroid(polygon(cp)).geometry.coordinates });
    }
    clippedKm2 += Math.max(0, aKm2 - kept.reduce((s, k) => s + k.aKm2, 0));
    fillable.push(...kept);
  }
  // Pass 2: nearest-region assignment and append.
  const regionInfo = countryRegions.map((r) => {
    const f = feature(r.geometry);
    return { r, cm: centroid(f).geometry.coordinates, areaKm2: area(f) * 1e-6 };
  });
  let realKm2 = 0;
  for (const { piece, aKm2, cm } of fillable) {
    // Nearest region by centroid haversine distance; tie → larger area, then lexicographic id.
    let best = null;
    for (const info of regionInfo) {
      const d = distance(cm, info.cm);
      if (
        best === null ||
        d < best.d ||
        (d === best.d && (info.areaKm2 > best.areaKm2 || (info.areaKm2 === best.areaKm2 && info.r.id < best.id)))
      ) best = { info, d };
    }
    if (!best) continue; // no regions at all (should not happen)
    realKm2 += aKm2;
    const target = best.info.r;
    const parts = (target.geometry.type === "MultiPolygon" ? target.geometry.coordinates : [target.geometry.coordinates]).concat([piece]);
    target.geometry = toGeometry(parts);
    const a = added.get(target) ?? { km2: 0, parts: 0 };
    a.km2 += aKm2; a.parts += 1;
    added.set(target, a);
    appendedSoFar.push({ parent: iso, bbox: partBBox(piece), part: piece });
  }
  totalSliverKm2 += sliverKm2;
  totalWaterKm2 += waterKm2;
  totalFilledKm2 += realKm2;
  totalDupN += dupN;
  totalClippedKm2 += clippedKm2;
  totalClipFailN += clipFailN;
  // Verify the fill for countries we actually changed: recompute the residual gap.
  let afterKm2 = null;
  if (realKm2 > 0) {
    try {
      const u2 = countryRegions.length === 1
        ? countryRegions[0].geometry
        : union(featureCollection(countryRegions.map((r) => feature(r.geometry)))).geometry;
      afterKm2 = area(difference(featureCollection([landmass, { ...landmass, geometry: u2 }]))) * 1e-6;
    } catch { afterKm2 = null; }
  }
  console.log(
    `${iso}\tregions=${countryRegions.length}\tgap-before=${(area(diffGeom) * 1e-6).toFixed(0)}` +
    (afterKm2 === null ? "" : `\tgap-after=${afterKm2.toFixed(0)}`) +
    `\tfilled=${realKm2.toFixed(0)}\tslivers=${sliverN}(${sliverKm2.toFixed(0)})\twater-skipped=${waterN}(${waterKm2.toFixed(0)})` +
    `\tdup-skipped=${dupN}${clippedKm2 > 0 ? `\tforeign-overlap-removed=${clippedKm2.toFixed(0)}` : ""}${clipFailN > 0 ? `\tclip-failed=${clipFailN}` : ""}`,
  );
 }
 const totalAddedKm2 = [...added.values()].reduce((s, a) => s + a.km2, 0);
 const totalAddedParts = [...added.values()].reduce((s, a) => s + a.parts, 0);
 console.log(`\nfilled ${totalAddedKm2.toFixed(0)} km² into ${added.size} regions (+${totalAddedParts} parts)`);
 console.log(
  `totals: filled=${totalFilledKm2.toFixed(0)}  slivers-ignored=${totalSliverKm2.toFixed(0)}  water-kept-open=${totalWaterKm2.toFixed(0)}` +
  `  duplicate-phantoms-skipped=${totalDupN}  foreign-overlap-removed=${totalClippedKm2.toFixed(0)}  clip-failed=${totalClipFailN}`,
 );
 fs.writeFileSync(outFile, JSON.stringify(geo));
 console.log(`wrote ${outFile}`);
@@ -0,0 +1,252 @@
 #!/usr/bin/env node
 /**
 * scripts/generate-regions.mjs — dependency-free generator for `public/regions.geo.json`.
 *
 * Builds the sub-national region choropleth from REAL named administrative
 * regions (Natural Earth admin-1: states, provinces, governorates, oblasts, …)
 * instead of the old geometric grid the user rejected ("some stupid geometric
 * grid" — it looked abstract, not like recognizable territories).
 *
 * Sources (both GeoJSON):
 *   (a) the Natural Earth admin-1 file — real, named sub-national boundaries.
 *       It is read from a NON-committed temp path (default /tmp/ne10m_admin1.geojson,
 *       override with the NE_ADMIN1 env var) so the repo only stores the derived
 *       output, not the 40 MB source. Natural Earth is public domain (CC0).
 *   (b) the committed `public/countries.geo.json` (177 countries) — the
 *       authoritative ISO_A3 set, the country names, and the whole-country
 *       geometries used as the fallback for any country with no admin-1 data.
 *
 * Output contract (UNCHANGED from the old generator, so `WorldMap.tsx`,
 * `App.tsx`, `shared/protocol.ts` and `server/map.ts` all keep working —
 * ownership is resolved via `properties.parent`, the parent country's ISO_A3):
 *   - a GeoJSON FeatureCollection
 *   - each feature: a unique top-level `id`, `properties = { name, parent }`
 *     (`parent` = the country ISO_A3 = the RegionMap key; `name` = the region's
 *     human name), and a Polygon/MultiPolygon geometry.
 *
 * For each country in `countries.geo.json` (in file order, deterministic):
 *   - if it has admin-1 sub-regions -> emit each as a feature, in the source
 *     file's order. Region `id` = its ISO 3166-2 code (e.g. `US-CA`, `FR-75`,
 *     `RU-MOW`) when present, else `<ISO_A3>-<nn>` (1-based index in file
 *     order). Because ISO 3166-2 codes are not always unique WITHIN a country
 *     (e.g. all nine of Bosnia's entities report `BA-BIH`), ids are
 *     disambiguated with a `-2/-3/…` suffix on collision (BA-BIH, BA-BIH-2, …).
 *   - if it has none (tiny / not covered by admin-1) -> emit ONE whole-country
 *     region: `id = <ISO_A3>-01`, `name` = the country's name, geometry = the
 *     country's geometry.
 *
 * Every coordinate is rounded to 4 decimal places (0.0001° ≈ 11 m). If the
 * resulting file exceeds ~8 MB, a light Douglas–Peucker pass (0.05°, escalating
 * through a small table if still too big) trims it under the guard while keeping
 * shapes recognizable, and the before/after sizes are reported. Features are
 * sorted by (parent, id). Fully deterministic: same inputs -> same bytes.
 *
 * Run: `npm run generate:regions`
 */
 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, '..');
 // --- parameters ----------------------------------------------------------------
 const SIZE_GUARD_KB = 8192; // ~8 MB file-size guard (task spec)
 const SIZE_TARGET_KB = 6144; // land under ~6 MB once simplified (margin under the guard)
 const DP_STEPS = [0.05, 0.1, 0.2, 0.3, 0.5, 0.75, 1.0]; // Douglas–Peucker tolerances (degrees)
 const R4 = 4; // base coordinate precision (decimal places, ≈11 m)
 // Natural Earth admin-1 source (NON-committed temp file; override with NE_ADMIN1).
 const INPUT = process.env.NE_ADMIN1 || '/tmp/ne10m_admin1.geojson';
 // --- small geo helpers ---------------------------------------------------------
 const rN = (v, N) => Math.round(v * Math.pow(10, N)) / Math.pow(10, N);
 /** Round a ring to N decimals, drop consecutive duplicates, and close it. */
 function roundRing(ring, N) {
  const out = [];
  for (const [x, y] of ring) {
    const p = [rN(x, N), rN(y, N)];
    const last = out[out.length - 1];
    if (!last || last[0] !== p[0] || last[1] !== p[1]) out.push(p);
  }
  // drop a trailing point equal to the first (a redundant close), then re-close
  if (
    out.length > 1 &&
    out[0][0] === out[out.length - 1][0] &&
    out[0][1] === out[out.length - 1][1]
  )
    out.pop();
  if (out.length < 3) return out; // degenerate; caller drops it
  return [...out, [...out[0]]];
 }
 /** Perpendicular distance (degrees) from point p to the segment a→b. */
 function perpDist(p, a, b) {
  const dx = b[0] - a[0];
  const dy = b[1] - a[1];
  const l2 = dx * dx + dy * dy;
  if (l2 === 0) return Math.hypot(p[0] - a[0], p[1] - a[1]);
  let t = ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / l2;
  t = Math.max(0, Math.min(1, t));
  return Math.hypot(p[0] - (a[0] + t * dx), p[1] - (a[1] + t * dy));
 }
 /** Douglas–Peucker simplification of an OPEN point sequence (keeps endpoints). */
 function dpOpen(pts, tol) {
  if (pts.length < 3) return pts;
  let maxD = 0;
  let idx = 0;
  const a = pts[0];
  const b = pts[pts.length - 1];
  for (let i = 1; i < pts.length - 1; i++) {
    const d = perpDist(pts[i], a, b);
    if (d > maxD) {
      maxD = d;
      idx = i;
    }
  }
  if (maxD > tol) {
    const left = dpOpen(pts.slice(0, idx + 1), tol);
    const right = dpOpen(pts.slice(idx), tol);
    return left.concat(right.slice(1));
  }
  return [a, b];
 }
 /** Douglas–Peucker a CLOSED ring (first == last) at tolerance `tol` (0 = skip). */
 function dpRing(ring, tol) {
  if (tol <= 0 || ring.length < 3) return ring;
  let pts = ring;
  if (
    pts[0][0] === pts[pts.length - 1][0] &&
    pts[0][1] === pts[pts.length - 1][1]
  )
    pts = pts.slice(0, -1);
  const simplified = dpOpen(pts, tol);
  return [...simplified, [...simplified[0]]];
 }
 /** Round (and optionally simplify) every ring of a Polygon/MultiPolygon geometry. */
 function transformGeom(geom, tol) {
  const polys = geom.type === 'Polygon' ? [geom.coordinates] : geom.coordinates;
  const out = polys
    .map((poly) => poly.map((ring) => roundRing(ring, R4)).map((ring) => (tol > 0 ? dpRing(ring, tol) : ring)))
    .filter((poly) => poly.length >= 1 && poly.every((ring) => ring.length >= 3));
  if (!out.length) return geom; // nothing survived simplification — keep the rounded original
  if (geom.type === 'Polygon') return { type: 'Polygon', coordinates: out[0] };
  return { type: 'MultiPolygon', coordinates: out };
 }
 // --- main ----------------------------------------------------------------------
 function main() {
  const countries = JSON.parse(readFileSync(path.join(root, 'public', 'countries.geo.json'), 'utf8'));
  const admin1 = JSON.parse(readFileSync(INPUT, 'utf8'));
  const cset = new Set(countries.features.map((c) => c.id));
  // Group admin-1 features by parent ISO_A3 (their `adm0_a3`), in file order,
  // keeping only parents that are one of our 177 countries.
  const byParent = new Map();
  for (const f of admin1.features) {
    const p = f.properties.adm0_a3;
    if (typeof p === 'string' && cset.has(p)) {
      if (!byParent.has(p)) byParent.set(p, []);
      byParent.get(p).push(f);
    }
  }
  // Build the base specs (raw geometry + unique id + name + parent) in
  // countries.geo.json file order, then per-region source order — deterministic.
  const specs = [];
  const seenIds = new Set();
  const nextId = (base) => {
    let id = base;
    let k = 1;
    while (seenIds.has(id)) {
      k += 1;
      id = `${base}-${k}`;
    }
    seenIds.add(id);
    return id;
  };
  let fallbackCount = 0;
  const fallbackCountries = [];
  for (const c of countries.features) {
    const regs = byParent.get(c.id) ?? [];
    if (regs.length) {
      let nn = 0;
      for (const r of regs) {
        nn += 1;
        const iso = r.properties.iso_3166_2;
        const base = typeof iso === 'string' && iso ? iso : `${c.id}-${String(nn).padStart(2, '0')}`;
        const name = typeof r.properties.name === 'string' && r.properties.name ? r.properties.name : c.properties.name;
        specs.push({ id: nextId(base), name, parent: c.id, geom: r.geometry });
      }
    } else {
      fallbackCount += 1;
      fallbackCountries.push(c.id);
      specs.push({ id: nextId(`${c.id}-01`), name: c.properties.name, parent: c.id, geom: c.geometry });
    }
  }
  const sortById = (a, b) => (a.properties.parent !== b.properties.parent ? (a.properties.parent < b.properties.parent ? -1 : 1) : a.id.localeCompare(b.id, 'en', { numeric: true }));
  const build = (tol) => {
    const fc = {
      type: 'FeatureCollection',
      features: specs.map((s) => ({
        type: 'Feature',
        id: s.id,
        properties: { name: s.name, parent: s.parent },
        geometry: transformGeom(s.geom, tol),
      })),
    };
    fc.features.sort(sortById);
    return fc;
  };
  // Base: 4 decimal places, no simplification.
  let fc = build(0);
  let json = JSON.stringify(fc);
  let sizeKB = Buffer.byteLength(json) / 1024;
  console.log(`base (4dp, no DP): ${sizeKB.toFixed(1)} KB  (${fc.features.length} features)`);
  // File-size guard: if the base is over the guard, simplify until it is under
  // the target (or we exhaust the tolerance table).
  let usedTol = 0;
  if (sizeKB > SIZE_GUARD_KB) {
    for (const t of DP_STEPS) {
      fc = build(t);
      json = JSON.stringify(fc);
      sizeKB = Buffer.byteLength(json) / 1024;
      usedTol = t;
      console.log(`DP ${t}: ${sizeKB.toFixed(1)} KB`);
      if (sizeKB < SIZE_TARGET_KB) break;
    }
  }
  writeFileSync(path.join(root, 'public', 'regions.geo.json'), json + '\n');
  // --- summary ----------------------------------------------------------------
  const counts = new Map();
  for (const f of fc.features) counts.set(f.properties.parent, (counts.get(f.properties.parent) ?? 0) + 1);
  const sortedCounts = [...counts.values()].sort((a, b) => a - b);
  const median =
    sortedCounts.length % 2
      ? sortedCounts[Math.floor(sortedCounts.length / 2)]
      : (sortedCounts[sortedCounts.length / 2 - 1] + sortedCounts[sortedCounts.length / 2]) / 2;
  const maxCountry = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
  const maxCountryName = countries.features.find((c) => c.id === maxCountry[0])?.properties.name ?? '';
  const finalKB = Buffer.byteLength(json) / 1024;
  console.log(`\nwrote public/regions.geo.json — ${finalKB.toFixed(1)} KB (${(finalKB / 1024).toFixed(2)} MB)`);
  console.log(`features: ${fc.features.length} total across ${counts.size} of ${countries.features.length} countries`);
  console.log(`per-country count: min ${sortedCounts[0]} / median ${median} / max ${sortedCounts[sortedCounts.length - 1]}`);
  console.log(`max-count country: ${maxCountry[0]} (${maxCountryName}) with ${maxCountry[1]}`);
  if (usedTol) console.log(`simplification: Douglas–Peucker @ ${usedTol}° (base was ${SIZE_GUARD_KB}+ KB)`);
  console.log(`whole-country fallback: ${fallbackCount} ${fallbackCount ? `(${fallbackCountries.join(', ')})` : '(none)'}`);
 }
 main();
@@ -0,0 +1,87 @@
 /**
 * scripts/region-adjacency.test.ts — validation for the committed
 * `public/region-adjacency.json` (built by `scripts/build-region-adjacency.mjs`).
 *
 * The manifest maps each region key to the list of region keys it **borders**
 * (shares an edge/point with). It is the data behind the model's `getNeighbours`
 * tool (v0.21, #16 P2), so it is a load-bearing data artifact — this test pins
 * its contract.
 *
 * Deliberately dependency-free: it reads the JSON with plain `fs`/`JSON.parse`
 * and never imports `@turf`/geojson types (importing one pulls `@types/geojson`
 * into the tsc program and breaks `WorldMap.tsx`; see the v0.17 changelog note).
 * Mirrors the style of `scripts/region-keys.test.ts`.
 */
 import { readFileSync } from 'node:fs';
 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'));
 }
 describe('region-adjacency.json', () => {
  const adjacency = readJson('public/region-adjacency.json') as Record<string, string[]>;
  const manifest = readJson('public/region-keys.json') as Record<string, string>;
  const keys = new Set(Object.values(manifest));
  it('has exactly one entry per region key (same key set as region-keys.json)', () => {
    const manifestKeys = new Set(Object.values(manifest));
    const adjacencyKeys = new Set(Object.keys(adjacency));
    expect(adjacencyKeys).toEqual(manifestKeys);
    expect(Object.keys(adjacency)).toHaveLength(keys.size);
    expect(adjacencyKeys.size).toBe(1796);
  });
  it('every neighbour is itself a valid region key (referential integrity)', () => {
    for (const [key, neighbours] of Object.entries(adjacency)) {
      for (const n of neighbours) {
        expect(keys.has(n), `neighbour ${n} of ${key} is not a valid region key`).toBe(true);
      }
    }
  });
  it('no region lists itself as a neighbour', () => {
    for (const [key, neighbours] of Object.entries(adjacency)) {
      expect(neighbours.includes(key), `${key} lists itself`).toBe(false);
    }
  });
  it('adjacency is symmetric (A ∈ B  ⟺  B ∈ A)', () => {
    let checked = 0;
    for (const [a, aList] of Object.entries(adjacency)) {
      const aSet = new Set(aList);
      for (const b of aList) {
        const bList = adjacency[b];
        expect(Array.isArray(bList), `${b} has no adjacency entry`).toBe(true);
        // A lists B, so B must list A.
        expect(bList!.includes(a), `${a} → ${b} but ${b} does not list ${a}`).toBe(true);
        checked++;
      }
      // And the converse: every neighbour B of A must be a key (implied above) —
      // also assert no *missing* reverse entry by checking the full set equality.
      const bSet = new Set(aSet);
      for (const b of aList) bSet.add(b);
      // Symmetry means a's set equals the set of {b : a ∈ b}.
      const reverse = Object.entries(adjacency)
        .filter(([, list]) => list.includes(a))
        .map(([k]) => k);
      expect(new Set(reverse).size, `asymmetric degree for ${a}`).toBe(aList.length);
      expect(new Set(aList).size).toBe(aSet.size); // no duplicate neighbours
    }
    expect(checked).toBeGreaterThan(0);
  });
  it('spot-checks known real bordering pairs', () => {
    // Brazil ↔ Peru (Acre borders Loreto) — a real, unambiguous land border.
    expect(adjacency['acre-ekzw']?.includes('loreto-ipkx')).toBe(true);
    expect(adjacency['loreto-ipkx']?.includes('acre-ekzw')).toBe(true);
    // France ↔ Germany (Moselle borders Baden-Württemberg) — another real border.
    expect(adjacency['moselle-rygy']?.includes('baden-wurttemberg-oyje')).toBe(true);
    expect(adjacency['baden-wurttemberg-oyje']?.includes('moselle-rygy')).toBe(true);
  });
 });
@@ -0,0 +1,61 @@
 /**
 * scripts/region-keys.test.ts — validation for the committed `public/region-keys.json`.
 *
 * The manifest maps each sub-region's **stable feature id** (from
 * `public/regions.geo.json`) to a deterministic, human-readable, globally
 * unique region key of the form `<name-slug>-<4char>` (built by
 * `scripts/build-region-keys.mjs`). Region-level ownership (v0.19) keys both
 * `Nation.territory` and the `RegionMap` on these keys, so the manifest is a
 * load-bearing data artifact — this test pins its contract.
 *
 * Deliberately dependency-free: it reads both JSON files with plain
 * `fs`/`JSON.parse` and never imports `@turf`/geojson types (importing one
 * pulls `@types/geojson` into the tsc program and breaks `WorldMap.tsx`; see
 * the v0.17 changelog note). Mirrors the style of `scripts/regions.test.ts`.
 */
 import { readFileSync } from 'node:fs';
 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'));
 }
 describe('region-keys.json', () => {
  const manifest = readJson('public/region-keys.json') as Record<string, string>;
  const geo = readJson('public/regions.geo.json') as {
    features?: Array<{ id?: string | number }>;
  };
  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 1,796 unique keys (no collisions)', () => {
    expect(new Set(keys).size).toBe(keys.length);
    expect(new Set(keys).size).toBe(1796);
  });
  it('keys each end in -[a-z]{4} and contain at least one hyphen', () => {
    const ending = /-[a-z]{4}$/;
    for (const k of keys) {
      expect(k, `key does not end in -[a-z]{4}: ${k}`).toMatch(ending);
      expect(k, `key has no hyphen: ${k}`).toContain('-');
    }
  });
  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);
    const manifestIds = Object.keys(manifest);
    expect(new Set(manifestIds)).toEqual(new Set(featureIds));
  });
 });
@@ -0,0 +1,570 @@
 /**
 * scripts/regions.test.ts — validation for the committed `public/regions.geo.json`.
 *
 * The dataset is REAL named sub-national administrative regions (Natural
 * Earth admin-1: states, provinces, governorates, oblasts, …) that the
 * coarsening step (`scripts/coarsen-regions.mjs`, v0.14) has merged down to a
 * ~100×100 km (10,000 km²) floor: every small non-island region was dissolved
 * into its nearest same-country neighbor, so the only regions left below the
 * floor are islands (no same-country sibling nearby). One feature per named
 * region, each carrying `properties = { name, parent }` where `parent` is the
 * country's ISO_A3 (the RegionMap key the map resolves ownership through).
 * Tiny or uncovered countries collapse to a single whole-country region
 * (`<ISO_A3>-01`).
 *
 * v0.17 (`scripts/fill-gaps.mjs`) additionally fills the no-one's-land left
 * between merged sub-regions: per country, the uncovered slivers of the
 * country's landmass (≥ 25 km²) were added as extra parts of the nearest
 * region, so the regions now cover the landmass almost completely (the
 * sampling test below measures that per country).
 *
 * This test is self-contained (no import of the generator) and deliberately
 * dependency-free — it re-implements the same planar area model the
 * generator/analysis use, so the area-based assertions measure the same
 * quantity:
 *
 *   x = lon · 111.32 · cos(midLat),  y = lat · 110.574  (km)
 *
 * with a shoelace per OUTER ring, each ring measured at its own mean latitude.
 * Outer rings only — a region's inner rings (holes) are lakes and are ignored
 * by design, the same way the coverage band already absorbed them.
 *
 * No geojson/@turf types are imported: the project keeps `@types/geojson`
 * OUT of the tsc program (see tsconfig `types`) so maplibre-gl's d.ts stays
 * in its loose (skipLibCheck) mode; the one coverage test below uses an
 * inline even-odd ray cast instead of a geometry library.
 *
 * It reads each file exactly once and runs in O(total vertices).
 */
 import { readFileSync } from 'node:fs';
 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, '..');
 // --- area model (planar approximation; matches scripts/generate-regions.mjs) --
 const KM_LON = 111.32;
 const KM_LAT = 110.574;
 const rad = (deg: number) => (deg * Math.PI) / 180;
 type Ring = [number, number][];
 type Geometry =
  | { type: 'Polygon'; coordinates: Ring[] }
  | { type: 'MultiPolygon'; coordinates: Ring[][] };
 function ringAreaKm2(ring: Ring, midLat: number): number {
  const kx = KM_LON * Math.cos(rad(midLat));
  let a = 0;
  const n = ring.length;
  for (let i = 0; i < n; i++) {
    const [lon1, lat1] = ring[i];
    const [lon2, lat2] = ring[(i + 1) % n];
    a += lon1 * kx * (lat2 * KM_LAT) - lon2 * kx * (lat1 * KM_LAT);
  }
  return Math.abs(a / 2);
 }
 function outerRings(geom: Geometry): Ring[] {
  if (geom.type === 'Polygon') return [geom.coordinates[0]];
  if (geom.type === 'MultiPolygon') return geom.coordinates.map((p) => p[0]);
  return [];
 }
 /** Sum of a feature's outer-ring areas, each ring at its own mean latitude. */
 function featureAreaKm2(geom: Geometry): number {
  let total = 0;
  for (const ring of outerRings(geom)) {
    let lat = 0;
    for (const [, la] of ring) lat += la;
    total += ringAreaKm2(ring, ring.length ? lat / ring.length : 0);
  }
  return total;
 }
 function median(nums: number[]): number {
  if (!nums.length) return 0;
  const s = [...nums].sort((a, b) => a - b);
  const m = Math.floor(s.length / 2);
  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
 }
 /** Raw min/max bbox [w, s, e, n] of a geometry (all coordinates). */
 function rawBBox(geom: Geometry): [number, number, number, number] {
  const polys = geom.type === 'Polygon' ? [geom.coordinates] : geom.coordinates;
  let w = Infinity, s = Infinity, e = -Infinity, n = -Infinity;
  for (const poly of polys)
    for (const ring of poly)
      for (const [lo, la] of ring) {
        if (lo < w) w = lo;
        if (lo > e) e = lo;
        if (la < s) s = la;
        if (la > n) n = la;
      }
  return [w, s, e, n];
 }
 /**
 * Even-odd ray cast: is `[lon, lat]` inside `ring`? Planar, in raw lon/lat
 * space (no antimeridian handling — the polygons and the sample points live
 * in the same unwrapped space, so containment is mathematically consistent
 * even for countries that cross the date line). Used only as a fast,
 * deterministic coverage proxy (see the sampling test), never for areas.
 */
 function pointInRing(pt: [number, number], ring: Ring): boolean {
  const [x, y] = pt;
  let inside = false;
  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
    const [xi, yi] = ring[i];
    const [xj, yj] = ring[j];
    if (yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) inside = !inside;
  }
  return inside;
 }
 /** Is a point inside a (Multi)Polygon: inside the outer ring, outside all holes. */
 function pointInGeom(pt: [number, number], geom: Geometry): boolean {
  if (geom.type === 'Polygon') {
    if (!pointInRing(pt, geom.coordinates[0])) return false;
    return geom.coordinates.slice(1).every((h) => !pointInRing(pt, h));
  }
  if (geom.type === 'MultiPolygon')
    return geom.coordinates.some((p) => pointInGeom(pt, { type: 'Polygon', coordinates: p }));
  return false;
 }
 // ------------------------------------------------------------------------------
 interface RegionFeature {
  type: 'Feature';
  id: string;
  properties: { name: string; parent: string };
  geometry: Geometry;
 }
 interface CountryFeature {
  type: 'Feature';
  id: string;
  properties: { name: string };
  geometry: Geometry;
 }
 // Read each file exactly once.
 const regions = JSON.parse(
  readFileSync(path.join(root, 'public', 'regions.geo.json'), 'utf8'),
 ) as { type: 'FeatureCollection'; features: RegionFeature[] };
 const countries = JSON.parse(
  readFileSync(path.join(root, 'public', 'countries.geo.json'), 'utf8'),
 ) as { type: 'FeatureCollection'; features: CountryFeature[] };
 // Precompute once (O(total vertices)).
 const countryIds = new Set(countries.features.map((c) => c.id));
 const countryArea = new Map<string, number>();
 for (const c of countries.features) countryArea.set(c.id, featureAreaKm2(c.geometry));
 const regionArea = new Map<string, number>();
 for (const f of regions.features) regionArea.set(f.id, featureAreaKm2(f.geometry));
 const sumByParent = new Map<string, number>();
 for (const f of regions.features)
  sumByParent.set(f.properties.parent, (sumByParent.get(f.properties.parent) ?? 0) + (regionArea.get(f.id) ?? 0));
 const countByParent = new Map<string, number>();
 for (const f of regions.features)
  countByParent.set(f.properties.parent, (countByParent.get(f.properties.parent) ?? 0) + 1);
 // Raw bboxes for the sampling test's cheap reject (O(total vertices)).
 const regionBB = new Map<string, [number, number, number, number]>();
 for (const f of regions.features) regionBB.set(f.id, rawBBox(f.geometry));
 // --- island/close-neighbor helpers (mirror scripts/coarsen-regions.mjs) ------
 interface LonInt {
  a: number;
  b: number;
  full: boolean;
 }
 interface RegionBBox {
  latMin: number;
  latMax: number;
  lon: LonInt;
 }
 const COARSE_FLOOR_KM2 = 10_000; // the coarsener's ~100×100 km floor
 const CLOSE_DEG = 0.2; // "spatially close" bbox gap (both lat and lon ≤ this)
 /**
 * Unwrap a ring's longitudes to a continuous line (np.unwrap shortest-diff
 * scheme, anchored at the first vertex's [0,360) value). `full` when the
 * unwrapped span is ≥ 300° (a full-360° antimeridian band, e.g. Antarctica).
 * Must stay in sync with the coarsening script.
 */
 function unwrapRing(ring: Ring) {
  const n = ring.length;
  const norm = (x: number) => ((x % 360) + 360) % 360;
  const u: number[] = new Array(n);
  u[0] = norm(ring[0][0]);
  for (let i = 1; i < n; i++) {
    // the previous UNWRAPPED value may lie outside [0,360); normalize it
    // before measuring the shortest signed difference, or a bogus ~180° jump
    // is inserted and the ring's span balloons.
    const a = norm(u[i - 1]);
    const b = norm(ring[i][0]);
    const d = (((b - a) % 360) + 540) % 360 - 180;
    u[i] = u[i - 1] + d;
  }
  let min = Infinity;
  let max = -Infinity;
  for (const v of u) {
    if (v < min) min = v;
    if (v > max) max = v;
  }
  return { lons: u, full: max - min >= 300 };
 }
 /**
 * Cyclic 1-D gap (degrees) between two tight longitude intervals in their own
 * unwrapped spaces; a `full` interval is close to everything.
 */
 function lonGap(intA: LonInt, intB: LonInt): number {
  if (intA.full || intB.full) return 0;
  let best = Infinity;
  for (const k of [-1, 0, 1]) {
    const a2 = intB.a + 360 * k;
    const b2 = intB.b + 360 * k;
    const gap = intA.b < a2 ? a2 - intA.b : b2 < intA.a ? intA.a - b2 : 0;
    if (gap < best) best = gap;
  }
  return best;
 }
 // Per-region bbox in antimeridian-safe unwrapped longitude space.
 const regionBBox = new Map<string, RegionBBox>();
 for (const f of regions.features) {
  const polys = f.geometry.type === 'Polygon' ? [f.geometry.coordinates] : f.geometry.coordinates;
  let latMin = Infinity;
  let latMax = -Infinity;
  let a = Infinity;
  let b = -Infinity;
  let full = false;
  for (const poly of polys) {
    const outer = poly[0];
    for (const [, la] of outer) {
      if (la < latMin) latMin = la;
      if (la > latMax) latMax = la;
    }
    const { lons, full: fl } = unwrapRing(outer);
    if (fl) full = true;
    for (const v of lons) {
      if (v < a) a = v;
      if (v > b) b = v;
    }
  }
  regionBBox.set(f.id, { latMin, latMax, lon: { a, b, full } });
 }
 /** Bounding-box closeness (same definition the coarsening script uses). */
 function bboxesClose(x: RegionBBox, y: RegionBBox): boolean {
  const latGap = x.latMax < y.latMin ? y.latMin - x.latMax : y.latMax < x.latMin ? x.latMin - y.latMax : 0;
  if (latGap > CLOSE_DEG) return false;
  return lonGap(x.lon, y.lon) <= CLOSE_DEG;
 }
 describe('regions.geo.json', () => {
  it('is a valid GeoJSON FeatureCollection of well-formed features', () => {
    expect(regions.type).toBe('FeatureCollection');
    expect(Array.isArray(regions.features)).toBe(true);
    expect(regions.features.length).toBeGreaterThan(0);
    for (const f of regions.features) {
      expect(f.type, `${f.id ?? '?'}: not a Feature`).toBe('Feature');
      expect(typeof f.id, `${f.id ?? '?'}: id must be a string`).toBe('string');
      expect(f.id.length, `${f.id ?? '?'}: empty id`).toBeGreaterThan(0);
      expect(typeof f.properties?.name, `${f.id}: missing name`).toBe('string');
      expect(f.properties.name.length, `${f.id}: empty name`).toBeGreaterThan(0);
      expect(typeof f.properties.parent, `${f.id}: missing parent`).toBe('string');
      expect(countryIds.has(f.properties.parent), `${f.id}: unknown parent ${f.properties.parent}`).toBe(true);
      const g = f.geometry;
      expect(
        !!g && (g.type === 'Polygon' || g.type === 'MultiPolygon'),
        `${f.id}: bad geometry type ${g?.type}`,
      ).toBe(true);
      if (g) {
        const polys = g.type === 'Polygon' ? [g.coordinates] : g.coordinates;
        for (const poly of polys)
          for (const ring of poly)
            expect(ring.length, `${f.id}: ring with ${ring.length} pts`).toBeGreaterThanOrEqual(3);
      }
    }
  });
  it('has globally unique feature ids (ISO 3166-2 disambiguated on within-country collision)', () => {
    const seen = new Set<string>();
    const dups = new Set<string>();
    for (const f of regions.features) {
      if (seen.has(f.id)) dups.add(f.id);
      seen.add(f.id);
    }
    expect(
      dups.size,
      `duplicate ids: ${[...dups].slice(0, 10).join(', ')}`,
    ).toBe(0);
    expect(seen.size).toBe(regions.features.length);
  });
  it('covers every one of the 177 countries with at least one region', () => {
    const counts = countries.features.map((c) => countByParent.get(c.id) ?? 0);
    for (const c of countries.features) {
      expect(countByParent.get(c.id) ?? 0, `country ${c.id} has no regions`).toBeGreaterThanOrEqual(1);
    }
    const min = Math.min(...counts);
    const max = Math.max(...counts);
    const med = median(counts);
    const maxCountry = [...countByParent.entries()].sort((a, b) => b[1] - a[1])[0];
    const maxCountryName = countries.features.find((c) => c.id === maxCountry[0])?.properties.name ?? '';
    console.log(
      `\n  per-country region count: min ${min} / median ${med} / max ${max}` +
        ` (max: ${maxCountry[0]} ${maxCountryName} with ${maxCountry[1]})`,
    );
  });
  it('has sane region areas: median >= 100 km2, and no non-Antarctica region >= 5,000,000 km2', () => {
    const areas = regions.features.map((f) => regionArea.get(f.id) ?? 0);
    const med = median(areas);
    const maxRegion = regions.features.reduce((m, f) => ((regionArea.get(f.id) ?? 0) > (regionArea.get(m.id) ?? 0) ? f : m));
    const minRegion = regions.features.reduce((m, f) => ((regionArea.get(f.id) ?? 0) < (regionArea.get(m.id) ?? 0) ? f : m));
    const tiny = areas.filter((a) => a < 1).length;
    // Antarctica (ATA) is a full-360° wrap ring, so the planar model can't
    // measure it (it reports ~21.8M km2 for a ~14M km2 landmass) — exempt it.
    for (const f of regions.features) {
      if (f.properties.parent === 'ATA') continue;
      const a = regionArea.get(f.id) ?? 0;
      expect(a < 5_000_000, `${f.id}: area ${Math.round(a).toLocaleString('en-US')} km2 is absurdly large`).toBe(true);
    }
    expect(med, `median region area ${med.toFixed(1)} km2 is too small`).toBeGreaterThanOrEqual(100);
    console.log(
      `\n  region area: min ${minRegion.id} (${minRegion.properties.name}) ≈ ${(regionArea.get(minRegion.id) ?? 0).toExponential(2)} km2` +
        ` / median ${med.toLocaleString('en-US')} km2` +
        ` / max ${maxRegion.id} (${maxRegion.properties.name}) ≈ ${Math.round(regionArea.get(maxRegion.id) ?? 0).toLocaleString('en-US')} km2` +
        ` — ${tiny} regions < 1 km2 (legit micro-regions: tiny islands, small urban districts, degenerate disputed enclaves)`,
    );
  });
  it('leaves only islands below the ~10,000 km2 coarsening floor (non-island small regions merged)', () => {
    // v0.14 coarsening: every region smaller than the floor that has a
    // same-country sibling within CLOSE_DEG of its bbox is dissolved into its
    // nearest such neighbor, so a below-floor region may only survive if it
    // is an island. Count the non-island residuals below the floor and allow
    // a small tolerance band (strictly < 1% of all regions) — the coarsener's
    // fixed point leaves none, and this catches a regression in the merge
    // logic (e.g. a broken neighbor test that exempts land regions) without
    // being brittle to one or two borderline cases.
    const smallNonIslands: string[] = [];
    let smallIslands = 0;
    let smallTotal = 0;
    for (const f of regions.features) {
      const a = regionArea.get(f.id) ?? 0;
      if (a >= COARSE_FLOOR_KM2) continue;
      smallTotal++;
      const bb = regionBBox.get(f.id)!;
      let hasNeighbor = false;
      for (const g of regions.features) {
        if (g.id === f.id || g.properties.parent !== f.properties.parent) continue;
        if (bboxesClose(bb, regionBBox.get(g.id)!)) {
          hasNeighbor = true;
          break;
        }
      }
      if (hasNeighbor) {
        smallNonIslands.push(`${f.id} (${Math.round(a)} km2)`);
      } else smallIslands++;
    }
    const frac = regions.features.length ? smallNonIslands.length / regions.features.length : 0;
    expect(
      frac < 0.01,
      `${smallNonIslands.length} non-island region(s) below the ${COARSE_FLOOR_KM2} km2 floor ` +
        `(${(100 * frac).toFixed(2)}% of all regions): ${smallNonIslands.slice(0, 10).join(', ')}`,
    ).toBe(true);
    console.log(
      `\n  below-floor regions: ${smallTotal} — ${smallIslands} islands (exempt, no same-country neighbor within ${CLOSE_DEG}°)` +
        ` / ${smallNonIslands.length} non-island residuals (must stay < 1% of all regions)`,
    );
  });
  it('leaves exactly one enclosed hole: KZ-KZY (the real Aral Sea), still large', () => {
    // v0.15 filled every small hole; v0.16 smoothing never touches holes; and
    // v0.17's gap-filler explicitly keeps the Aral hole (its centroid matches a
    // pre-existing hole and it lies inside another country's landmass) while
    // dropping phantom holes. So the whole file must contain exactly one hole,
    // on KZ-KZY, at a realistic size (~5,860 km2 planar; the real Aral has
    // shrunk to roughly this by the 2020s) — no new holes of any size.
    let holes = 0;
    let maxHole = 0;
    const holeIds: string[] = [];
    let kzkzyHoleArea = 0;
    for (const f of regions.features) {
      const polys = f.geometry.type === 'Polygon' ? [f.geometry.coordinates] : f.geometry.coordinates;
      for (const poly of polys) {
        for (let i = 1; i < poly.length; i++) {
          holes++;
          let lat = 0;
          for (const [, la] of poly[i]) lat += la;
          const area = ringAreaKm2(poly[i], poly[i].length ? lat / poly[i].length : 0);
          if (area > maxHole) maxHole = area;
          holeIds.push(f.id);
          if (f.id === 'KZ-KZY') kzkzyHoleArea = area;
        }
      }
    }
    expect(holes, `expected exactly 1 hole (KZ-KZY), found ${holes}: ${[...new Set(holeIds)].join(', ')}`).toBe(1);
    expect(holeIds, 'the one remaining hole is KZ-KZY').toEqual(['KZ-KZY']);
    expect(
      kzkzyHoleArea >= 5_000 && kzkzyHoleArea <= 7_000,
      `KZ-KZY hole is ${Math.round(kzkzyHoleArea).toLocaleString('en-US')} km2 — outside the 5,000–7,000 km2 Aral band`,
    ).toBe(true);
    console.log(
      `\n  holes: exactly 1 (KZ-KZY ≈ ${Math.round(kzkzyHoleArea).toLocaleString('en-US')} km2) — the Aral hole survived v0.17's fill`,
    );
  });
  it('sums to within [40%, 190%] of each country area (median in [70%, 130%])', () => {
    // The band is a planar-approximation sanity check. It is wider than a naive
    // [40%, 110%] because Natural Earth's admin-1 polygons are digitized
    // independently of the admin-0 country polygons (they are NOT clipped to
    // them). v0.17's gap fill removed the large UNDER-fills (the old minimum
    // was Brunei at ~52% — its regions now cover the landmass, ≈ 79%), but
    // the OVER-fill tail is a pre-existing admin-1 artifact: a few tiny island
    // nations (Vanuatu 178.9%, Solomon Is. 133%, Bahamas 129%) have admin-1
    // polygons that extend beyond their own country polygon, and the fill
    // only added area *inside* the country, so it can't shrink that tail.
    // The band brackets the measured [78.8%, 178.9%] with margin while still
    // catching a genuinely missing or doubled-up region.
    const ratios: number[] = [];
    let minRatio = Infinity;
    let maxRatio = -Infinity;
    let minId = '';
    let maxId = '';
    for (const c of countries.features) {
      const ca = countryArea.get(c.id) ?? 0;
      if (ca <= 0) continue;
      const ratio = (sumByParent.get(c.id) ?? 0) / ca;
      ratios.push(ratio);
      if (ratio < minRatio) { minRatio = ratio; minId = c.id; }
      if (ratio > maxRatio) { maxRatio = ratio; maxId = c.id; }
      expect(
        ratio >= 0.4 && ratio <= 1.9,
        `${c.id}: coverage ${(100 * ratio).toFixed(1)}% is outside [40%, 190%]`,
      ).toBe(true);
    }
    const medRatio = median(ratios);
    expect(
      medRatio >= 0.7 && medRatio <= 1.3,
      `median coverage ${(100 * medRatio).toFixed(1)}% is outside [70%, 130%]`,
    ).toBe(true);
    console.log(
      `\n  coverage range: min ${minId} ${(100 * minRatio).toFixed(1)}%` +
        ` / median ${(100 * medRatio).toFixed(1)}%` +
        ` / max ${maxId} ${(100 * maxRatio).toFixed(1)}% (band 40–190%)`,
    );
  });
  it('covers each country\'s landmass with no significant no-one\'s-land (v0.17 gap fill, grid-sampled)', () => {
    // The v0.17 fill (scripts/fill-gaps.mjs) assigned every uncovered sliver of
    // each country's landmass (≥ 25 km²) to its nearest region, so the residual
    // no-one's-land per country should be small everywhere. Measuring the
    // exact union is too slow, so this samples a 25×25 grid over each
    // country's raw bbox (skipping points outside the country polygon) and
    // counts the fraction of in-land sample points that fall in NONE of the
    // country's regions — a fast, deterministic proxy (same planar space,
    // inline even-odd ray cast; antimeridian-safe because points and polygons
    // share the raw coordinate space). Sampling over-counts coastline
    // mismatch (admin-0 vs admin-1 edges), so the thresholds are generous:
    // they catch a real regression (a whole sliver left unfilled) without
    // being brittle to digitization fuzz.
    const N = 25;
    const results: { id: string; name: string; frac: number; land: number }[] = [];
    for (const c of countries.features) {
      const [w, s, e, n] = rawBBox(c.geometry);
      if (e - w < 0.01 || n - s < 0.01) continue; // degenerate (point-like) country
      const regs = regions.features.filter((f) => f.properties.parent === c.id);
      let land = 0;
      let uncov = 0;
      for (let i = 0; i < N; i++) {
        const la = s + ((i + 0.5) / N) * (n - s);
        for (let j = 0; j < N; j++) {
          const lo = w + ((j + 0.5) / N) * (e - w);
          const pt: [number, number] = [lo, la];
          if (!pointInGeom(pt, c.geometry)) continue;
          land++;
          // cheap bbox reject first, then the full containment test
          if (!regs.some((f) => {
            const [rw, rs, re, rn] = regionBB.get(f.id)!;
            if (lo < rw || lo > re || la < rs || la > rn) return false;
            return pointInGeom(pt, f.geometry);
          }))
            uncov++;
        }
      }
      if (land >= 4) results.push({ id: c.id, name: c.properties.name, frac: uncov / land, land });
    }
    expect(results.length, `only ${results.length} countries sampled (expected ~176)`).toBeGreaterThanOrEqual(150);
    const fracs = results.map((r) => r.frac).sort((a, b) => a - b);
    const med = median(fracs);
    const p90 = fracs[Math.floor(fracs.length * 0.9)];
    const worst = results.reduce((m, r) => (r.frac > m.frac ? r : m));
    const over20 = results.filter((r) => r.frac > 0.2).sort((a, b) => b.frac - a.frac);
    expect(
      med <= 0.05,
      `median country gap ${(100 * med).toFixed(1)}% > 5% — significant no-one's-land remains`,
    ).toBe(true);
    expect(
      p90 <= 0.15,
      `p90 country gap ${(100 * p90).toFixed(1)}% > 15% — many countries have real gaps`,
    ).toBe(true);
    expect(
      worst.frac <= 0.4,
      `worst country ${worst.id} (${worst.name}) gap ${(100 * worst.frac).toFixed(1)}% > 40%`,
    ).toBe(true);
    expect(
      over20.length <= 3,
      `${over20.length} countries with > 20% gap: ${over20.map((r) => `${r.id} ${(100 * r.frac).toFixed(1)}%`).join(', ')}`,
    ).toBe(true);
    console.log(
      `\n  no-one's-land (grid-sampled, N=${N}): median ${(100 * med).toFixed(1)}% / p90 ${(100 * p90).toFixed(1)}%` +
        ` / max ${worst.id} (${worst.name}) ${(100 * worst.frac).toFixed(1)}%` +
        (over20.length ? ` — >20%: ${over20.map((r) => `${r.id} ${(100 * r.frac).toFixed(1)}%`).join(', ')}` : ' — no country > 20%'),
    );
  });
  it('is at the v0.17 fixed point: 1,796 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).
    const polysOf = (g: Geometry) => (g.type === 'Polygon' ? [g.coordinates] : g.coordinates);
    let verts = 0,
      rings = 0,
      parts = 0,
      holes = 0;
    const holeIds: string[] = [];
    for (const f of regions.features) {
      const polys = polysOf(f.geometry);
      parts += polys.length;
      for (const poly of polys) {
        rings += poly.length;
        holes += Math.max(0, poly.length - 1);
        if (poly.length > 1) holeIds.push(f.id);
        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(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
    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`,
    );
  });
 });
@@ -0,0 +1,180 @@
 #!/usr/bin/env node
 /**
 * scripts/smooth-regions.mjs — smooths jagged sub-national region boundaries.
 *
 * Run:   npm run smooth:regions             (in place on public/regions.geo.json)
 *        node scripts/smooth-regions.mjs [out] [src]
 *
 * The v0.14 coarsening (boolean dissolve) and Natural Earth's 1:10m digitization
 * left some sub-national boundaries overly jagged — the worst being coastal /
 * borderland regions that the dissolve split into many small, zig-zag fragments
 * (e.g. SI-048 Kocevje, Slovenia, 57 parts; MK-36 Kavadartsi, N. Macedonia, 8
 * parts). This cleans the jaggedness in place with **Douglas–Peucker
 * vertex-thinning** (`@turf/simplify`), applied to every ring of every polygon.
 *
 *   DOUGLAS–PEUCKER  — `@turf/simplify` keeps a vertex only when it deviates from
 *   the chord joining its kept neighbours by more than the tolerance, removing
 *   the redundant "in-between" points of a shallow zig-zag. The tolerance is
 *   expressed in the GeoJSON degree space (its distance metric treats 1° lon
 *   == 1° lat); TOLERANCE_M (metres) is converted with the same ~111 km/° the
 *   area model uses, so TOLERANCE_M = 50 is a gentle ~50 m pass. Bump it to
 *   100 / 200 for a stronger pass and re-run — the pass is idempotent either way.
 *
 *   VERTEX-THINNING ONLY — DP only removes points. It never moves a border,
 *   never merges/dissolves regions or parts, and never creates or removes a
 *   ring, so topology is preserved exactly: the region count, every `id`,
 *   `properties.name`/`properties.parent`, the part count of every feature, the
 *   single real hole (KZ-KZY), and all 83 islands are all unchanged. Only the
 *   redundant vertices along each ring are dropped.
 *
 * Deterministic + idempotent: one @turf/simplify pass at a fixed tolerance, then
 * 4-dp rounding (the same convention as the other scripts). Because the output
 * is already at the tolerance's fixed point, re-running on the smoothed file
 * yields a byte-identical file (sha256-verified). The 18 degenerate 3-point
 * micro-rings (the ~0-area "dots" like Ragged Island / the Paracels) are kept
 * verbatim — @turf/simplify requires ≥4 points and would otherwise throw — so
 * no ring is ever dropped and every feature keeps its exact part/ring count.
 */
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { simplify } from '@turf/simplify';
 const here = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(here, '..');
 const DEFAULT_FILE = path.join(root, 'public', 'regions.geo.json');
 const args = process.argv.slice(2).filter((a) => !a.startsWith('-'));
 const OUT = args[0] ? path.resolve(args[0]) : DEFAULT_FILE;
 const SRC = args[1] ? path.resolve(args[1]) : DEFAULT_FILE;
 // --- parameters ---------------------------------------------------------------
 const TOLERANCE_M = 50; // DP tolerance in metres — ~50 m is gentle (bump to 100/200 for more)
 const M_PER_DEG = 111_000; // ~111 km per degree (same scale as the area model's 111.32/110.574)
 const TOL_DEG = TOLERANCE_M / M_PER_DEG; // @turf/simplify works in degree space → ≈ 0.00045°
 const R4 = 4; // coordinate precision (decimal places) — same as the other scripts
 // --- rounding / normalization (same conventions as the other scripts) ----------
 const rN = (v, N) => Math.round(v * 10 ** N) / 10 ** N;
 function roundRing(ring, N = R4) {
  const out = [];
  for (const [x, y] of ring) {
    const p = [rN(x, N), rN(y, N)];
    const last = out[out.length - 1];
    if (!last || last[0] !== p[0] || last[1] !== p[1]) out.push(p);
  }
  if (out.length > 1 && out[0][0] === out[out.length - 1][0] && out[0][1] === out[out.length - 1][1]) out.pop();
  if (out.length < 3) return ring; // degenerate — keep verbatim, never corrupt a ring
  return [...out, [...out[0]]];
 }
 // --- tiny geometry helpers -----------------------------------------------------
 const polysOf = (g) => (g.type === 'Polygon' ? [g.coordinates] : g.coordinates);
 const ringsOf = (g) => polysOf(g).flatMap((p) => p);
 const countVerts = (g) => ringsOf(g).reduce((s, r) => s + r.length, 0);
 const countParts = (g) => (g.type === 'Polygon' ? 1 : g.coordinates.length);
 const countRings = (g) => ringsOf(g).length;
 const countHoles = (g) => polysOf(g).reduce((s, p) => s + Math.max(0, p.length - 1), 0);
 /**
 * Smooth one closed ring with a single @turf/simplify (Douglas–Peucker) pass.
 * Only removes vertices — never adds, never drops the ring. Degenerate rings
 * (<4 pts) are returned verbatim (simplify would throw); a ring DP would
 * over-collapse below a valid 4-pt ring is kept as-is; any error keeps the
 * original. Never throws.
 */
 function smoothRing(ring) {
  if (!Array.isArray(ring) || ring.length < 4) return ring; // keep degenerate verbatim
  try {
    const feat = { type: 'Feature', geometry: { type: 'Polygon', coordinates: [ring] } };
    const next = simplify(feat, { tolerance: TOL_DEG }).geometry.coordinates[0];
    if (!Array.isArray(next) || next.length < 4) return ring; // over-collapsed — keep original
    const closed =
      next[next.length - 1][0] === next[0][0] && next[next.length - 1][1] === next[0][1]
        ? next
        : [...next, [next[0][0], next[0][1]]];
    const rounded = roundRing(closed);
    return rounded.length >= 4 ? rounded : ring;
  } catch {
    return ring;
  }
 }
 /** Smooth every ring of a geometry. Never drops a ring or a part. */
 function smoothGeom(geom) {
  const newPolys = polysOf(geom).map((poly) => poly.map(smoothRing));
  if (geom.type === 'Polygon' && newPolys.length === 1) return { type: 'Polygon', coordinates: newPolys[0] };
  return { type: 'MultiPolygon', coordinates: newPolys };
 }
 // --- main ----------------------------------------------------------------------
 function main() {
  const t0 = Date.now();
  const rawIn = readFileSync(SRC);
  const fc = JSON.parse(rawIn);
  const inBytes = Buffer.byteLength(rawIn);
  console.log(`input: ${fc.features.length} regions (${(inBytes / 1024).toFixed(0)} KB) from ${SRC}`);
  console.log(`mode: Douglas–Peucker via @turf/simplify, tolerance ${TOLERANCE_M} m (≈ ${TOL_DEG}°)`);
  // before stats
  let vb = 0, hb = 0, pb = 0, rb = 0, degenerate = 0;
  for (const f of fc.features) {
    vb += countVerts(f.geometry);
    hb += countHoles(f.geometry);
    pb += countParts(f.geometry);
    rb += countRings(f.geometry);
    for (const r of ringsOf(f.geometry)) if (r.length < 4) degenerate++;
  }
  const outFeatures = fc.features.map((f) => {
    const g = smoothGeom(f.geometry);
    return { type: 'Feature', id: f.id, properties: { name: f.properties.name, parent: f.properties.parent }, geometry: g };
  });
  const out = { type: 'FeatureCollection', features: outFeatures };
  // after stats + change count (compare against the original, in order)
  let va = 0, ha = 0, pa = 0, ra = 0, changed = 0;
  for (let i = 0; i < out.features.length; i++) {
    const f = out.features[i];
    va += countVerts(f.geometry);
    ha += countHoles(f.geometry);
    pa += countParts(f.geometry);
    ra += countRings(f.geometry);
    if (JSON.stringify(f.geometry) !== JSON.stringify(fc.features[i].geometry)) changed++;
  }
  const afterVerts = new Map(out.features.map((f) => [f.id, countVerts(f.geometry)]));
  const json = JSON.stringify(out);
  writeFileSync(OUT, json + '\n');
  const outBytes = Buffer.byteLength(json) + 1;
  console.log(`\n--- RESULTS ---`);
  console.log(`regions: ${fc.features.length} → ${out.features.length}  (unchanged)`);
  console.log(`vertices (incl. ring closure): ${vb} → ${va}   removed ${vb - va} (${(100 * (vb - va) / vb).toFixed(2)}%)`);
  console.log(`rings: ${rb} → ${ra}   parts: ${pb} → ${pa}   holes: ${hb} → ${ha}   (all unchanged)`);
  console.log(`regions whose geometry changed: ${changed} / ${fc.features.length}`);
  console.log(`degenerate rings (<4 pts, kept verbatim): ${degenerate}`);
  console.log(`file: ${(inBytes / 1024).toFixed(0)} KB → ${(outBytes / 1024).toFixed(0)} KB  (${(outBytes / 1024 / 1024).toFixed(2)} MB)`);
  // Diagnose the "messy" regions: the real problem is fragmentation — the
  // dissolve left coherent regions as many disconnected parts. Rank by part
  // count (then total vertices) so these surface; Kocelje/Kavadartsi are here.
  const messy = fc.features
    .map((f) => ({
      id: f.id,
      name: f.properties.name,
      parent: f.properties.parent,
      parts: countParts(f.geometry),
      vb: countVerts(f.geometry),
    }))
    .sort((a, b) => b.parts - a.parts || b.vb - a.vb)
    .slice(0, 15);
  console.log(`\nMOST-MESSY (top ${messy.length} by fragmentation = parts, then vertices):`);
  console.log(`  id         name                                    country  parts  verts  verts(after)`);
  for (const m of messy)
    console.log(`  ${m.id.padEnd(10)} ${m.name.slice(0, 37).padEnd(38)} ${m.parent.padEnd(7)} ${String(m.parts).padStart(4)}  ${String(m.vb).padStart(5)}  ${String(afterVerts.get(m.id)).padStart(5)}`);
  console.log(`\nwrote ${OUT}; elapsed ${((Date.now() - t0) / 1000).toFixed(1)}s`);
 }
 main();
@@ -23,6 +23,8 @@ function makeState(id: string): GameState {
    events: [],
    pending: [],
    version: 1,
    unowned: [],
    pendingNationOps: [],
  };
 }
@@ -73,6 +75,28 @@ describe('openDb', () => {
    db.close();
  });
  it('(v0.22 #16 P3) a legacy row saved before the unowned field existed loads with it defaulted to []', () => {
    const db = openDb(':memory:');
    const legacy = makeState('legacy');
    delete (legacy as { unowned?: string[] }).unowned; // a pre-v0.22 save (field absent)
    db.save(legacy);
    const loaded = db.load('legacy');
    expect(loaded).not.toBeNull();
    expect(loaded!.unowned).toEqual([]);
    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('delete removes a game by id and reports absence otherwise', () => {
    const db = openDb(':memory:');
    db.save(makeState('a'));
@@ -39,7 +39,14 @@ export function openDb(filePath: string): Db {
      const row = byId.get(id) as { data: string } | undefined;
      if (!row) return null;
      try {
-        return JSON.parse(row.data) as GameState;
+        const 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 = [];
        return state;
      } catch {
        return null;
      }
@@ -1,17 +1,24 @@
 import { describe, expect, it } from 'vitest';
 import type { GameState, Preset, RoundItem } from '../shared/types';
-import { makeEvent, type TurnResult } from '../shared/protocol';
+import { makeEvent, type NationOp, type TurnResult } from '../shared/protocol';
-import type { LlmClient } from './llm';
+import type { LlmClient, ToolDefinition, WireMessage } from './llm';
 import { makeStubLlmClient } from './stub';
 import {
  applyTurnResult,
  buildSystemPrompt,
  buildUserPrompt,
  confirmNationOp,
  GET_NEIGHBOURS_TOOL,
  isMeaningful,
  makeNeighboursExecutor,
  parseTurnResult,
  playerFrontier,
  queueRoundItem,
  rejectNationOp,
  removeRoundItem,
  resolveNationRef,
  runTurn,
  validateNationOps,
  validateTurnResult,
 } from './engine';
@@ -75,6 +82,8 @@ function baseState(): GameState {
    events: [],
    pending: [],
    version: 1,
    unowned: [],
    pendingNationOps: [],
  };
 }
@@ -88,7 +97,10 @@ const validResult = JSON.stringify({
    { nation: 'de', stat: 'economy', op: 'add', value: 10 },
  ],
  relations: [{ a: 'uk', b: 'us', set: 'ally' }],
-  territoryChanges: [{ nation: 'de', gain: ['POL'], lose: [] }],
+  // v0.21 (#16 P2): DE gains the UK's GBR — the key has exactly one previous
  // owner, so the transfer applies (since v0.22 #16 P3 a key owned by NOBODY
  // would be re-claimed instead of ignored; a release lives in "unowned").
  territoryChanges: [{ nation: 'de', gain: ['GBR'], lose: [] }],
 });
 describe('runTurn', () => {
@@ -109,8 +121,10 @@ describe('runTurn', () => {
    // relations are symmetric
    expect(state.nations.uk.relations.us).toBe('ally');
    expect(state.nations.us.relations.uk).toBe('ally');
-    // territory moved to DE
+    // territory moved to DE: it gains GBR (the UK's sole previous owner) and
-    expect(state.nations.de.territory).toContain('POL');
+    // the old owner correspondingly loses it (v0.21 #16 P2: one owner per key)
    expect(state.nations.de.territory).toContain('GBR');
    expect(state.nations.uk.territory).not.toContain('GBR');
    // one event appended, tagged with the turn that was resolved (1)
    expect(state.events).toHaveLength(1);
    expect(state.events[0].turn).toBe(1);
@@ -121,7 +135,8 @@ describe('runTurn', () => {
    // and the original state object is NOT mutated
    expect(original.turn).toBe(1);
    expect(original.nations.uk.stats.military).toBe(80);
-    expect(original.nations.de.territory).not.toContain('POL');
+    expect(original.nations.de.territory).not.toContain('GBR');
    expect(original.nations.uk.territory).toContain('GBR');
  });
  it('clamps out-of-range stat values into 0-100', async () => {
@@ -318,6 +333,33 @@ describe('buildUserPrompt (batched round)', () => {
  it('asks the model to keep its internal reasoning brief (concise-CoT constraint)', () => {
    expect(buildSystemPrompt(preset)).toMatch(/reasoning brief|a few sentences/i);
  });
  it('includes a regions reference table only when one is provided', () => {
    // with a reference table: the payload carries it (region key -> "name (parent)")
    const withRef = JSON.parse(
      buildUserPrompt(baseState(), [], { 'ain-lqtt': 'Ain (FRA)', 'wales-bbbb': 'Wales (GBR)' }),
    ) as { regions?: Record<string, string> };
    expect(withRef.regions).toEqual({ 'ain-lqtt': 'Ain (FRA)', 'wales-bbbb': 'Wales (GBR)' });
    // without one: the field is absent entirely (the legacy prompt shape is unchanged)
    const withoutRef = JSON.parse(buildUserPrompt(baseState(), [])) as { regions?: Record<string, string> };
    expect(withoutRef.regions).toBeUndefined();
  });
  it('(v0.22 #16 P3) emits the no-man\'s-land list when provided (even when empty) and omits it otherwise', () => {
    // runTurn always passes state.unowned (even []), so the field is present...
    const withEmpty = JSON.parse(buildUserPrompt(baseState(), [], undefined, undefined, [])) as {
      unowned?: string[];
    };
    expect(withEmpty.unowned).toEqual([]);
    // ...and a populated list reaches the model verbatim (it knows what it can re-claim)
    const withKeys = JSON.parse(
      buildUserPrompt(baseState(), [], undefined, undefined, ['GBR', 'POL']),
    ) as { unowned?: string[] };
    expect(withKeys.unowned).toEqual(['GBR', 'POL']);
    // but a caller that does not provide it keeps the legacy payload shape
    const omitted = JSON.parse(buildUserPrompt(baseState(), [])) as { unowned?: string[] };
    expect(omitted.unowned).toBeUndefined();
  });
 });
 describe('queueRoundItem', () => {
@@ -388,6 +430,271 @@ describe('removeRoundItem', () => {
  });
 });
 describe('resolveNationRef (v0.23 #16 P4a)', () => {
  it('resolves an exact id first (even if a name matches something else)', () => {
    const state = baseState();
    expect(resolveNationRef(state, 'de')).toBe('de');
  });
  it('resolves a unique name case-insensitively', () => {
    const state = baseState();
    expect(resolveNationRef(state, 'US')).toBe('us');
    expect(resolveNationRef(state, ' uS ')).toBe('us'); // trimmed, case-insensitive
  });
  it('returns null for an ambiguous name (two nations share it)', () => {
    const state = baseState();
    state.nations.us.name = 'UK'; // now uk and us are both "UK"
    expect(resolveNationRef(state, 'UK')).toBeNull();
    // but the exact id still resolves
    expect(resolveNationRef(state, 'uk')).toBe('uk');
  });
  it('returns null for an unknown or empty reference (never throws)', () => {
    const state = baseState();
    expect(resolveNationRef(state, 'zzz-not-a-nation')).toBeNull();
    expect(resolveNationRef(state, '   ')).toBeNull();
    expect(resolveNationRef(state, '')).toBeNull();
  });
 });
 describe('validateNationOps (v0.23 #16 P4a)', () => {
  it('parses a valid rename (trimmed, capped) and drops invalid ones', () => {
    const ops = validateNationOps([
      { kind: 'rename', nationRef: ' de ', to: 'Reich' },
      { kind: 'rename', nationRef: 'uk', to: '' }, // empty to -> dropped
      { kind: 'rename', to: 'no ref' }, // missing nationRef -> dropped
      { kind: 'rename', nationRef: 'us' }, // missing to -> dropped
      { kind: 'bogus-kind' }, // unknown kind -> ignored
      'not-an-object',
      null,
    ]);
    expect(ops).toEqual([{ kind: 'rename', nationRef: 'de', to: 'Reich' }]);
  });
  it('parses a valid split (parts with names kept, nameless parts dropped)', () => {
    const ops = validateNationOps([
      {
        kind: 'split',
        nationRef: 'de',
        parts: [
          { name: 'East', territory: ['DEU', ''] },
          { name: '   ' }, // empty name -> part dropped
          { name: 'West' },
        ],
      },
    ]);
    expect(ops).toEqual([
      {
        kind: 'split',
        nationRef: 'de',
        parts: [{ name: 'East', territory: ['DEU'] }, { name: 'West', territory: [] }],
      },
    ]);
    // a split with no usable parts is dropped entirely
    expect(validateNationOps([{ kind: 'split', nationRef: 'de', parts: [{ name: '' }] }])).toEqual([]);
  });
  it('parses a valid merge and drops malformed ones', () => {
    const ops = validateNationOps([
      { kind: 'merge', nationRefs: ['uk', 'us'], survivingRef: 'uk', into: 'Anglo-Saxon Union' },
      { kind: 'merge', nationRefs: [], survivingRef: 'uk', into: 'X' }, // no refs -> dropped
      { kind: 'merge', nationRefs: ['uk'], survivingRef: '', into: 'X' }, // no survivor -> dropped
      { kind: 'merge', nationRefs: ['uk'], survivingRef: 'uk' }, // no into -> dropped
    ]);
    expect(ops).toEqual([
      { kind: 'merge', nationRefs: ['uk', 'us'], survivingRef: 'uk', into: 'Anglo-Saxon Union' },
    ]);
  });
  it('returns [] for non-array input and is never thrown by', () => {
    expect(validateNationOps(undefined)).toEqual([]);
    expect(validateNationOps('nope')).toEqual([]);
    expect(validateNationOps({})).toEqual([]);
  });
  it('validateTurnResult carries validated nationOps through (and defaults to [] when absent)', () => {
    const withOps = validateTurnResult({
      date: '1939-09-03',
      events: [],
      stateChanges: [],
      relations: [],
      territoryChanges: [],
      unowned: [],
      nationOps: [{ kind: 'rename', nationRef: 'France', to: 'French Republic' }],
    });
    expect(withOps).not.toBeNull();
    expect(withOps!.nationOps).toEqual([{ kind: 'rename', nationRef: 'France', to: 'French Republic' }]);
    const without = validateTurnResult({ date: '1939-09-03', events: [], stateChanges: [] });
    expect(without).not.toBeNull();
    expect(without!.nationOps).toEqual([]);
  });
 });
 describe('applyTurnResult (nation-op proposals, v0.23 #16 P4a)', () => {
  it('a proposed rename is NOT applied by the turn — it lands in pendingNationOps, name untouched', () => {
    const state = baseState();
    const next = applyTurnResult(state, {
      date: '1939-09-03',
      events: [{ nation: 'de', type: 'political', title: 'Reunification', text: 'The nation is renamed.', outcome: 'success' }],
      stateChanges: [],
      relations: [],
      territoryChanges: [],
      unowned: [],
      nationOps: [{ kind: 'rename', nationRef: 'de', to: 'Reich' }],
    });
    expect(next.nations.de.name).toBe('DE'); // still the old name
    expect(next.pendingNationOps).toEqual([{ kind: 'rename', nationRef: 'de', to: 'Reich' }]);
    expect(next.version).toBe(2);
    // the input is not mutated
    expect(state.nations.de.name).toBe('DE');
    expect(state.pendingNationOps).toEqual([]);
  });
  it('pending proposals SURVIVE a subsequent turn (unlike the round queue) and new ones append', () => {
    const state = baseState();
    state.pendingNationOps = [{ kind: 'rename', nationRef: 'de', to: 'Reich' }]; // unresolved from turn N-1
    const next = applyTurnResult(state, {
      date: '1939-09-03',
      events: [],
      stateChanges: [],
      relations: [],
      territoryChanges: [],
      unowned: [],
      nationOps: [{ kind: 'rename', nationRef: 'us', to: 'USA' }], // new proposal this turn
    });
    expect(next.pendingNationOps).toEqual([
      { kind: 'rename', nationRef: 'de', to: 'Reich' }, // the old one survived
      { kind: 'rename', nationRef: 'us', to: 'USA' }, // the new one was appended
    ]);
  });
  it('a legacy state without the pendingNationOps field accepts proposals (defaulted to [])', () => {
    const state = baseState();
    delete (state as { pendingNationOps?: NationOp[] }).pendingNationOps; // simulate a pre-v0.23 row
    const next = applyTurnResult(state, {
      date: '1939-09-03',
      events: [],
      stateChanges: [],
      relations: [],
      territoryChanges: [],
      unowned: [],
      nationOps: [{ kind: 'rename', nationRef: 'de', to: 'Reich' }],
    });
    expect(next.pendingNationOps).toEqual([{ kind: 'rename', nationRef: 'de', to: 'Reich' }]);
  });
 });
 describe('confirmNationOp / rejectNationOp (v0.23 #16 P4a)', () => {
  /**
   * The pending list: op 0 is referenced by id ('de'); op 1 is referenced by
   * NAME ('US' — the id is lowercase 'us'), so confirming it exercises the
   * name-resolution path of resolveNationRef.
   */
  function stateWithPending(): GameState {
    const s = baseState();
    s.pendingNationOps = [
      { kind: 'rename', nationRef: 'de', to: 'Reich' },
      { kind: 'rename', nationRef: 'US', to: 'United States' },
    ];
    return s;
  }
  it('confirm applies a rename (name only — id/territory/relations/player pointer untouched) and removes the op, bumping the version', () => {
    const state = stateWithPending();
    const next = confirmNationOp(state, 0);
    expect(next).not.toBeNull();
    expect(next!.nations.de.name).toBe('Reich');
    expect(next!.nations.de.id).toBe('de'); // id unchanged
    expect(next!.nations.de.territory).toEqual(['DEU']); // territory unchanged
    expect(next!.nations.uk.relations.de).toBe('hostile'); // relations (keyed by id) unchanged
    expect(next!.playerNationId).toBe('uk'); // player pointer unchanged
    expect(next!.pendingNationOps).toEqual([{ kind: 'rename', nationRef: 'US', to: 'United States' }]);
    expect(next!.version).toBe(2);
    // the input state is not mutated
    expect(state.nations.de.name).toBe('DE');
    expect(state.pendingNationOps).toHaveLength(2);
    expect(state.version).toBe(1);
  });
  it('confirm with an edits.name override renames to the player-edited name', () => {
    const next = confirmNationOp(stateWithPending(), 0, { name: 'Greater Reich' });
    expect(next!.nations.de.name).toBe('Greater Reich');
  });
  it('confirm with an empty edits.name falls back to the proposed name', () => {
    const next = confirmNationOp(stateWithPending(), 0, { name: '   ' });
    expect(next!.nations.de.name).toBe('Reich');
  });
  it('confirm resolves the target by name (not just id) — case-insensitively', () => {
    const next = confirmNationOp(stateWithPending(), 1); // nationRef 'US' is a name, not the id 'us'
    expect(next).not.toBeNull();
    expect(next!.nations.us.name).toBe('United States');
  });
  it('confirm is a no-op on the world for a P4b-kind op (split/merge) — the op is still removed', () => {
    const state = baseState();
    state.pendingNationOps = [{ kind: 'split', nationRef: 'de', parts: [{ name: 'East' }] }];
    const next = confirmNationOp(state, 0);
    expect(next).not.toBeNull();
    expect(next!.nations).toEqual(state.nations); // the world is untouched
    expect(next!.pendingNationOps).toEqual([]); // ...but the proposal was resolved
    expect(next!.version).toBe(2);
  });
  it('confirm with an invalid index returns null and mutates nothing', () => {
    const state = stateWithPending();
    expect(confirmNationOp(state, -1)).toBeNull();
    expect(confirmNationOp(state, 2)).toBeNull();
    expect(confirmNationOp(state, 0.5)).toBeNull();
    expect(state.nations.de.name).toBe('DE');
    expect(state.version).toBe(1);
  });
  it('reject drops the proposal without applying it, bumping the version', () => {
    const state = stateWithPending();
    const next = rejectNationOp(state, 0);
    expect(next).not.toBeNull();
    expect(next!.nations.de.name).toBe('DE'); // unchanged
    expect(next!.pendingNationOps).toEqual([{ kind: 'rename', nationRef: 'US', to: 'United States' }]);
    expect(next!.version).toBe(2);
    expect(state.pendingNationOps).toHaveLength(2); // input untouched
  });
  it('reject with an invalid index returns null and mutates nothing', () => {
    const state = stateWithPending();
    expect(rejectNationOp(state, -1)).toBeNull();
    expect(rejectNationOp(state, 2)).toBeNull();
    expect(state.pendingNationOps).toHaveLength(2);
    expect(state.version).toBe(1);
  });
  it('an ambiguous/invalid nationRef is a no-op on confirm (the op is resolved, the world unchanged)', () => {
    const state = baseState();
    state.nations.us.name = 'UK'; // make "UK" ambiguous (uk and us)
    state.pendingNationOps = [{ kind: 'rename', nationRef: 'UK', to: 'Empire' }];
    const next = confirmNationOp(state, 0);
    expect(next).not.toBeNull();
    expect(next!.nations.uk.name).toBe('UK'); // neither nation was renamed
    expect(next!.nations.us.name).toBe('UK');
    expect(next!.pendingNationOps).toEqual([]);
  });
 });
 describe('buildSystemPrompt (nationOps contract, v0.23 #16 P4a)', () => {
  it('both modes contract the nationOps field and the rename proposal rule', () => {
    for (const p of [buildSystemPrompt(preset), buildSystemPrompt(preset, true)]) {
      // the JSON shape carries the field in both modes
      expect(p).toMatch(/"nationOps": \[\{"kind":"rename","nationRef":"<nation id or name>","to":"<new name>"\}\]/);
      // the rule explains that it is a proposal only the player can confirm
      expect(p).toMatch(/PROPOSAL/);
      expect(p).toMatch(/only takes effect if the player confirms/);
    }
  });
 });
 describe('parseTurnResult', () => {
  it('parses a fenced JSON block', () => {
    const r = parseTurnResult('```json\n{"date":"1939-09-03","events":[{"nation":"uk","type":"military","title":"t","text":"b","outcome":"success"}]}\n```');
@@ -440,6 +747,8 @@ describe('applyTurnResult', () => {
      stateChanges: [{ nation: 'uk', stat: 'military', op: 'set', value: 99 }],
      relations: [],
      territoryChanges: [],
      unowned: [],
      nationOps: [],
    };
    applyTurnResult(state, result);
    expect(JSON.stringify(state)).toBe(snapshot);
@@ -454,6 +763,8 @@ describe('applyTurnResult', () => {
      stateChanges: [],
      relations: [],
      territoryChanges: [],
      unowned: [],
      nationOps: [],
    };
    const next = applyTurnResult(state, result);
    expect(next.pending).toEqual([]);
@@ -461,12 +772,589 @@ describe('applyTurnResult', () => {
    expect(state.pending).toHaveLength(1); // original untouched
    expect(state.version).toBe(1);
  });
  it('with a validKeys set: applies real region keys, ignores hallucinated ones', () => {
    const state = baseState();
    // give the fixture's uk a real key ('wales-bbbb') for DE to be able to take
    state.nations.uk.territory = ['GBR', 'wales-bbbb'];
    const result: TurnResult = {
      date: '1939-09-03',
      events: [],
      stateChanges: [],
      relations: [],
      // 'wales-bbbb' is a real key (owned by uk in the fixture); 'not-a-region-xyz'
      // is not a real key at all. Both are proposed as a gain by DE.
      territoryChanges: [{ nation: 'de', gain: ['wales-bbbb', 'not-a-region-xyz'], lose: [] }],
      unowned: [],
      nationOps: [],
    };
    const next = applyTurnResult(state, result, new Set(['wales-bbbb']));
    // the valid key was gained (taken from its sole previous owner); the bogus one was ignored
    expect(next.nations.de.territory).toContain('wales-bbbb');
    expect(next.nations.uk.territory).not.toContain('wales-bbbb');
    // the bogus key never entered any nation's territory
    for (const n of Object.values(next.nations)) {
      expect(n.territory).not.toContain('not-a-region-xyz');
    }
  });
  it('without a validKeys set: applies every listed key (legacy/unit path)', () => {
    const state = baseState();
    state.nations.uk.territory = ['GBR', 'wales-bbbb'];
    const result: TurnResult = {
      date: '1939-09-03',
      events: [],
      stateChanges: [],
      relations: [],
      // 'wales-bbbb' has a sole previous owner (uk) -> it transfers; 'POL' is
      // owned by no one -> a re-claim (v0.22, #16 P3): DE gains it. It was never
      // released (not in state.unowned), so it does not enter GameState.unowned.
      territoryChanges: [{ nation: 'de', gain: ['POL', 'wales-bbbb'], lose: [] }],
      unowned: [],
      nationOps: [],
    };
    const next = applyTurnResult(state, result); // no validKeys -> nothing filtered
    expect(next.nations.de.territory).toContain('wales-bbbb');
    expect(next.nations.uk.territory).not.toContain('wales-bbbb');
    expect(next.nations.de.territory).toContain('POL'); // re-claimed, not ignored
    expect(next.unowned).toEqual([]); // never released -> not no man's land
  });
 });
 describe('applyTurnResult (sole-ownership invariants, v0.21 #16 P2)', () => {
  const noEvents = {
    date: '1939-09-03',
    events: [],
    stateChanges: [],
    relations: [],
    unowned: [],
    nationOps: [],
  };
  it('a double claim (two different gainers, one key) is rejected: the key stays with its original owner', () => {
    const state = baseState();
    state.nations.uk.territory = ['GBR', 'wales-bbbb'];
    const next = applyTurnResult(state, {
      ...noEvents,
      territoryChanges: [
        { nation: 'de', gain: ['wales-bbbb'], lose: [] },
        { nation: 'us', gain: ['wales-bbbb'], lose: [] },
      ],
    });
    expect(next.nations.uk.territory).toContain('wales-bbbb');
    expect(next.nations.de.territory).not.toContain('wales-bbbb');
    expect(next.nations.us.territory).not.toContain('wales-bbbb');
  });
  it('duplicate gain entries for the SAME nation are deduped (one claim, one copy)', () => {
    const state = baseState();
    state.nations.uk.territory = ['GBR', 'wales-bbbb'];
    const next = applyTurnResult(state, {
      ...noEvents,
      territoryChanges: [
        { nation: 'de', gain: ['wales-bbbb'], lose: [] },
        { nation: 'de', gain: ['wales-bbbb'], lose: [] },
      ],
    });
    expect(next.nations.de.territory.filter((k) => k === 'wales-bbbb')).toHaveLength(1);
    expect(next.nations.uk.territory).not.toContain('wales-bbbb');
  });
  it('a lone "lose" is a no-op: the key cannot be orphaned (zero owners)', () => {
    const state = baseState();
    const next = applyTurnResult(state, {
      ...noEvents,
      territoryChanges: [{ nation: 'uk', gain: [], lose: ['GBR'] }],
    });
    expect(next.nations.uk.territory).toContain('GBR');
  });
  it('a self-gain is a no-op (a nation keeps exactly one copy of its own key)', () => {
    const state = baseState();
    const next = applyTurnResult(state, {
      ...noEvents,
      territoryChanges: [{ nation: 'uk', gain: ['GBR'], lose: [] }],
    });
    expect(next.nations.uk.territory.filter((k) => k === 'GBR')).toHaveLength(1);
  });
  it('a pre-existing double ownership is never touched (a key with 2 owners keeps 2)', () => {
    const state = baseState();
    state.nations.us.territory = ['USA', 'GBR']; // uk AND us already share GBR
    const next = applyTurnResult(state, {
      ...noEvents,
      territoryChanges: [{ nation: 'de', gain: ['GBR'], lose: [] }],
    });
    expect(next.nations.uk.territory).toContain('GBR');
    expect(next.nations.us.territory).toContain('GBR');
    expect(next.nations.de.territory).not.toContain('GBR');
  });
  it('ownership is conserved across a transfer: exactly one owner before and after', () => {
    const state = baseState();
    state.nations.uk.territory = ['GBR', 'wales-bbbb'];
    const count = (s: GameState) =>
      Object.values(s.nations).reduce(
        (acc, n) => acc + n.territory.filter((k) => k === 'wales-bbbb').length,
        0,
      );
    const next = applyTurnResult(state, {
      ...noEvents,
      territoryChanges: [{ nation: 'de', gain: ['wales-bbbb'], lose: [] }],
    });
    expect(count(state)).toBe(1);
    expect(count(next)).toBe(1);
    expect(next.nations.de.territory).toContain('wales-bbbb');
    expect(next.nations.uk.territory).not.toContain('wales-bbbb');
  });
 });
 describe('applyTurnResult (no man\'s land, v0.22 #16 P3)', () => {
  const noEvents = {
    date: '1939-09-03',
    events: [],
    stateChanges: [],
    relations: [],
    territoryChanges: [],
    unowned: [],
    nationOps: [],
  };
  it('a release removes the key from its sole owner and marks it in GameState.unowned', () => {
    const state = baseState();
    const next = applyTurnResult(state, { ...noEvents, unowned: ['GBR'] });
    expect(next.nations.uk.territory).not.toContain('GBR');
    expect(next.unowned).toEqual(['GBR']);
    // nothing else moved
    expect(next.nations.us.territory).toEqual(['USA']);
    expect(next.nations.de.territory).toEqual(['DEU']);
  });
  it('a re-claim (a gain on a currently-unowned key) grants it and removes it from GameState.unowned', () => {
    const state = baseState();
    state.unowned = ['POL']; // released in an earlier turn
    const next = applyTurnResult(state, {
      ...noEvents,
      territoryChanges: [{ nation: 'de', gain: ['POL'], lose: [] }],
    });
    expect(next.nations.de.territory).toContain('POL');
    expect(next.unowned).toEqual([]); // it left no man's land
  });
  it('a release and a claim of the same key in one turn: the claim wins (the key is owned)', () => {
    const state = baseState();
    const next = applyTurnResult(state, {
      ...noEvents,
      territoryChanges: [{ nation: 'de', gain: ['GBR'], lose: [] }],
      unowned: ['GBR'],
    });
    expect(next.nations.de.territory).toContain('GBR');
    expect(next.nations.uk.territory).not.toContain('GBR');
    expect(next.unowned).toEqual([]);
  });
  it('a double claim on a released key is rejected: the key stays in no man\'s land', () => {
    const state = baseState();
    const next = applyTurnResult(state, {
      ...noEvents,
      territoryChanges: [
        { nation: 'de', gain: ['GBR'], lose: [] },
        { nation: 'us', gain: ['GBR'], lose: [] },
      ],
      unowned: ['GBR'], // released first, then both nations lunge for it
    });
    expect(next.nations.uk.territory).not.toContain('GBR'); // the release applied
    expect(next.nations.de.territory).not.toContain('GBR'); // both claims rejected
    expect(next.nations.us.territory).not.toContain('GBR');
    expect(next.unowned).toEqual(['GBR']);
  });
  it('releasing a key no nation owns (a preset-unassigned region) is a no-op — no man\'s land can only arise from a real release', () => {
    const state = baseState();
    const next = applyTurnResult(state, { ...noEvents, unowned: ['POL'] });
    expect(next.unowned).toEqual([]);
    for (const n of Object.values(next.nations)) expect(n.territory).not.toContain('POL');
  });
  it('releasing a key with two owners (a corrupt state) is a no-op', () => {
    const state = baseState();
    state.nations.us.territory = ['USA', 'GBR']; // uk AND us share GBR
    const next = applyTurnResult(state, { ...noEvents, unowned: ['GBR'] });
    expect(next.nations.uk.territory).toContain('GBR');
    expect(next.nations.us.territory).toContain('GBR');
    expect(next.unowned).toEqual([]);
  });
  it('releasing a key already in no man\'s land is a no-op (it stays listed once)', () => {
    const state = baseState();
    state.unowned = ['POL'];
    const next = applyTurnResult(state, { ...noEvents, unowned: ['POL'] });
    expect(next.unowned).toEqual(['POL']);
  });
  it('with a validKeys set: releasing a hallucinated key is a no-op', () => {
    const state = baseState();
    const next = applyTurnResult(state, { ...noEvents, unowned: ['not-a-region-xyz'] }, new Set(['wales-bbbb']));
    expect(next.unowned).toEqual([]);
  });
  it('a legacy state without the unowned field accepts a release (the result carries the field)', () => {
    const state = baseState();
    delete (state as { unowned?: string[] }).unowned; // simulate a pre-v0.22 row
    const next = applyTurnResult(state, { ...noEvents, unowned: ['GBR'] });
    expect(next.unowned).toEqual(['GBR']);
    expect(next.nations.uk.territory).not.toContain('GBR');
  });
  it('a turn with no releases leaves the existing no man\'s land list unchanged', () => {
    const state = baseState();
    state.unowned = ['POL'];
    const next = applyTurnResult(state, {
      ...noEvents,
      territoryChanges: [{ nation: 'de', gain: ['GBR'], lose: [] }],
    });
    expect(next.unowned).toEqual(['POL']);
    expect(next.nations.de.territory).toContain('GBR');
  });
  it('validateTurnResult dedupes and filters the unowned list (trimmed non-empty strings only)', () => {
    const r = validateTurnResult({
      date: '1939-09-03',
      events: [],
      stateChanges: [],
      relations: [],
      territoryChanges: [],
      unowned: [' a ', 'a', '', 42, null, ' b '],
    });
    expect(r).not.toBeNull();
    expect(r!.unowned).toEqual(['a', 'b']);
  });
  it('a lone release is meaningful (it survives the retry/nudge path)', () => {
    expect(
      isMeaningful({ date: 'x', events: [], stateChanges: [], relations: [], territoryChanges: [], unowned: ['GBR'], nationOps: [] }),
    ).toBe(true);
  });
  it('runTurn applies a release end-to-end: the model narrates it and the key leaves its owner', async () => {
    const original = baseState();
    original.pending = [{ kind: 'action', text: 'Scorch the earth on the retreat' }];
    const releaseJson = JSON.stringify({
      date: '1939-09-05',
      events: [
        {
          nation: 'uk',
          type: 'military',
          title: 'A retreat through the wastelands',
          text: 'The abandoned highlands burn and lie empty.',
          outcome: 'partial',
        },
      ],
      stateChanges: [],
      relations: [],
      territoryChanges: [],
      unowned: ['GBR'],
    });
    const payloads: string[] = [];
    const client: LlmClient = {
      chat: async (messages) => {
        const user = messages.find((m) => m.role === 'user');
        if (user) payloads.push(user.content as string);
        return releaseJson;
      },
      listModels: async () => [],
    };
    const { state } = await runTurn({ llm: client, preset, state: original, items: original.pending });
    // the event landed and the release applied
    expect(state.events).toHaveLength(1);
    expect(state.events[0].title).toBe('A retreat through the wastelands');
    expect(state.nations.uk.territory).not.toContain('GBR');
    expect(state.unowned).toEqual(['GBR']);
    // on the first turn the model was shown the (empty) no-man's-land list...
    const first = JSON.parse(payloads[0]) as { unowned?: string[] };
    expect(first.unowned).toEqual([]);
    // ...and on the next turn it is shown the released key (so it can re-claim it)
    const next = await runTurn({ llm: client, preset, state, items: [] });
    const second = JSON.parse(payloads[1]) as { unowned?: string[] };
    expect(second.unowned).toEqual(['GBR']);
    // the repeated "release" of an already-unowned key is a no-op
    expect(next.state.unowned).toEqual(['GBR']);
  });
 });
 describe('makeNeighboursExecutor (v0.21 #16 P2)', () => {
  const getNeighbours = (keys: string[]) => keys.map((k) => `nb-${k}`);
  it('answers getNeighbours with the resolver output', () => {
    const exec = makeNeighboursExecutor(getNeighbours);
    expect(exec('getNeighbours', { regionKeys: ['a', 'b'] })).toBe(
      JSON.stringify({ neighbours: ['nb-a', 'nb-b'] }),
    );
  });
  it('degrades unknown tools, malformed args, and unknown keys without throwing', () => {
    const exec = makeNeighboursExecutor(getNeighbours, new Set(['a']));
    expect(exec('otherTool', {})).toBe(JSON.stringify({ error: 'unknown tool: otherTool' }));
    expect(exec('getNeighbours', { regionKeys: 'not-an-array' })).toBe(
      JSON.stringify({ neighbours: [] }),
    );
    expect(exec('getNeighbours', { regionKeys: ['a', 'zzz-not-valid'] })).toBe(
      JSON.stringify({ neighbours: ['nb-a'] }), // the unknown key is filtered out
    );
  });
 });
 describe('playerFrontier (v0.21 #16 P2)', () => {
  const adjacency: Record<string, string[]> = {
    GBR: ['DEU', 'USA'],
    GBR2: ['DEU'],
    DEU: ['GBR', 'GBR2', 'USA'],
    USA: ['GBR', 'DEU'],
  };
  const getNeighbours = (keys: string[]) =>
    [...new Set(keys.flatMap((k) => adjacency[k] ?? []))]
      .filter((k) => !keys.includes(k))
      .sort();
  it('is the sorted, deduped set of other-nation keys bordering the player', () => {
    const state = baseState();
    state.nations.uk.territory = ['GBR', 'GBR2']; // the player owns both
    // DEU (de) and USA (us) border the player; deduped and sorted
    expect(playerFrontier(state, getNeighbours)).toEqual(['DEU', 'USA']);
  });
  it('drops candidates the player itself owns (a sloppy resolver may report them)', () => {
    const state = baseState();
    state.nations.uk.territory = ['GBR', 'GBR2'];
    const sloppy = () => ['GBR2', 'DEU'];
    expect(playerFrontier(state, sloppy)).toEqual(['DEU']);
  });
  it('is empty when the player has no territory or no controllable border', () => {
    const empty = baseState();
    empty.nations.uk.territory = [];
    expect(playerFrontier(empty, getNeighbours)).toEqual([]);
    const noBorders = () => [];
    expect(playerFrontier(baseState(), noBorders)).toEqual([]);
  });
 });
 describe('runTurn (getNeighbours tool path, v0.21 #16 P2)', () => {
  const adjacency: Record<string, string[]> = {
    GBR: ['DEU'],
    DEU: ['GBR', 'USA'],
    USA: ['DEU'],
  };
  const getNeighbours = (keys: string[]) =>
    [...new Set(keys.flatMap((k) => adjacency[k] ?? []))]
      .filter((k) => !keys.includes(k))
      .sort();
  const finalTurn = JSON.stringify({
    date: '1939-09-03',
    events: [
      {
        nation: 'uk',
        type: 'military',
        title: 'The border region falls',
        text: 'UK seizes the contiguous region.',
        outcome: 'success',
      },
    ],
    stateChanges: [],
    relations: [],
    // the player gains its only frontier region (DEU, owned by de)
    territoryChanges: [{ nation: 'uk', gain: ['DEU'], lose: [] }],
  });
  /**
   * A fake LlmClient implementing BOTH chat() and chatWithTools(). The
   * chatWithTools fake plays the model's side of the protocol: it records
   * the initial messages + tools, executes the scripted tool calls through
   * the executor the engine handed it, and returns the final content.
   */
  function toolLlm(final: string, scriptedCalls: Array<{ name: string; args: Record<string, unknown> }>) {
    const seen: {
      firstMessages: WireMessage[];
      tools: ToolDefinition[];
      executorCalls: Array<{ name: string; args: Record<string, unknown>; result: string }>;
      chatCalls: number;
    } = { firstMessages: [], tools: [], executorCalls: [], chatCalls: 0 };
    const client: LlmClient = {
      chat: async (messages) => {
        seen.chatCalls += 1;
        seen.firstMessages = messages as WireMessage[];
        return final;
      },
      listModels: async () => [],
      chatWithTools: async (messages, tools, executeTool) => {
        seen.firstMessages = messages;
        seen.tools = tools;
        for (const call of scriptedCalls) {
          seen.executorCalls.push({ ...call, result: executeTool(call.name, call.args) });
        }
        return final;
      },
    };
    return { client, seen };
  }
  it('uses chatWithTools with the tool, a frontier in the prompt, the wired executor, and applies the transfer', async () => {
    const original = baseState();
    original.pending = [{ kind: 'action', text: 'Seize the border region' }];
    const { client, seen } = toolLlm(finalTurn, [
      { name: 'getNeighbours', args: { regionKeys: ['GBR'] } },
    ]);
    const { state } = await runTurn({
      llm: client,
      preset,
      state: original,
      items: original.pending,
      getNeighbours,
    });
    // the tool was offered and the system prompt advertises it
    expect(seen.tools.map((t) => t.function.name)).toEqual([GET_NEIGHBOURS_TOOL.function.name]);
    const system = seen.firstMessages[0] as { role: 'system'; content: string };
    expect(system.content).toContain('getNeighbours');
    // the user payload carries the player's frontier (DEU: the player's only
    // controllable border, owned by de)
    const user = seen.firstMessages[1] as { role: 'user'; content: string };
    const payload = JSON.parse(user.content) as { frontier?: string[] };
    expect(payload.frontier).toEqual(['DEU']);
    // the executor the engine built answers from the resolver
    expect(seen.executorCalls).toHaveLength(1);
    expect(seen.executorCalls[0].args).toEqual({ regionKeys: ['GBR'] });
    expect(seen.executorCalls[0].result).toBe(JSON.stringify({ neighbours: ['DEU'] }));
    // chat() was never used on the tool path
    expect(seen.chatCalls).toBe(0);
    // the contiguous transfer was applied: uk gains DEU, de loses it
    expect(state.nations.uk.territory).toContain('DEU');
    expect(state.nations.de.territory).not.toContain('DEU');
  });
  it('falls back to plain chat() when the client lacks chatWithTools (no tool; the frontier hint stays in the prompt)', async () => {
    const original = baseState();
    const { client, seen } = toolLlm(validResult, []);
    delete client.chatWithTools; // simulate a minimal client (chat only)
    const { state } = await runTurn({
      llm: client,
      preset,
      state: original,
      items: original.pending,
      getNeighbours,
    });
    expect(seen.chatCalls).toBe(1);
    expect(seen.tools).toEqual([]); // the tool path was never entered
    const system = seen.firstMessages[0] as { content: string };
    expect(system.content).not.toContain('getNeighbours');
    const user = seen.firstMessages[1] as { content: string };
    const payload = JSON.parse(user.content) as { frontier?: string[] };
    // the frontier hint stays (a resolver was given) even without the tool —
    // it also tells the model which borders are realistically contestable
    expect(payload.frontier).toEqual(['DEU']);
    // the canned result still applied (GBR moved uk -> de)
    expect(state.nations.de.territory).toContain('GBR');
    expect(state.nations.uk.territory).not.toContain('GBR');
  });
 });
 describe('deterministic stub (one contiguous conquest per turn, v0.21 #16 P2)', () => {
  const adjacency: Record<string, string[]> = {
    GBR: ['DEU'],
    DEU: ['GBR', 'USA'],
    USA: ['DEU'],
  };
  const getNeighbours = (keys: string[]) =>
    [...new Set(keys.flatMap((k) => adjacency[k] ?? []))]
      .filter((k) => !keys.includes(k))
      .sort();
  it('transfers the first frontier region to the player (and its owner loses it)', async () => {
    const original = baseState();
    original.pending = [{ kind: 'action', text: 'March on the border region' }];
    const { state } = await runTurn({
      llm: makeStubLlmClient(),
      preset,
      state: original,
      items: original.pending,
      getNeighbours,
    });
    expect(state.nations.uk.territory).toContain('DEU'); // frontier[0]
    expect(state.nations.de.territory).not.toContain('DEU');
    // the rest of the stub behavior is unchanged
    expect(state.turn).toBe(2);
    expect(state.date).toBe('1939-09-03');
    expect(state.nations.uk.stats.military).toBe(85); // clamp(80 + 5)
    expect(state.events).toHaveLength(1);
  });
  it('with an empty frontier (no controllable border, like the UK in wwii-1939): no transfer, the turn still advances', async () => {
    const original = baseState();
    original.pending = [{ kind: 'action', text: 'Hold the line' }];
    const { state } = await runTurn({
      llm: makeStubLlmClient(),
      preset,
      state: original,
      items: original.pending,
      getNeighbours: () => [], // no borders at all
    });
    expect(state.nations.uk.territory).toEqual(['GBR']); // untouched
    expect(state.nations.de.territory).toEqual(['DEU']);
    expect(state.nations.us.territory).toEqual(['USA']);
    expect(state.turn).toBe(2);
    expect(state.events).toHaveLength(1);
  });
 });
 describe('buildSystemPrompt (tool mode, v0.21 #16 P2)', () => {
  it('mentions the getNeighbours tool and the contiguity rules only when the tool is sent', () => {
    const plain = buildSystemPrompt(preset);
    expect(plain).not.toContain('getNeighbours');
    expect(plain).toMatch(/Only change borders when war/i); // the legacy rule stays
    const withTool = buildSystemPrompt(preset, true);
    expect(withTool).toContain('getNeighbours');
    expect(withTool).toMatch(/contiguous/i);
    expect(withTool).toMatch(/frontier/i);
    expect(withTool).not.toMatch(/Only change borders when war/i);
  });
  it('(v0.22 #16 P3) both modes contract the no-man\'s-land field (release + re-claim) and constrain it to owned keys', () => {
    for (const p of [buildSystemPrompt(preset), buildSystemPrompt(preset, true)]) {
      // the JSON shape carries the field in both modes
      expect(p).toMatch(/"unowned": \["<region key>"\]/);
      // the rule explains release (narrated in events) and re-claim (ordinary gain)
      expect(p).toMatch(/no man's land/i);
      expect(p).toMatch(/narrate the cause in "events"/);
      expect(p).toMatch(/re-claims it with a "gain"/i);
      // the hard constraint: only currently-owned keys may be released
      expect(p).toMatch(/only region keys that a nation currently owns/);
    }
  });
 });
 describe('isMeaningful', () => {
  it('is true with an event, false when everything is empty', () => {
-    expect(isMeaningful({ date: 'x', events: [{ nation: 'uk', type: 'military', title: 't', text: 'b', outcome: 'neutral' }], stateChanges: [], relations: [], territoryChanges: [] })).toBe(true);
+    expect(isMeaningful({ date: 'x', events: [{ nation: 'uk', type: 'military', title: 't', text: 'b', outcome: 'neutral' }], stateChanges: [], relations: [], territoryChanges: [], unowned: [], nationOps: [] })).toBe(true);
-    expect(isMeaningful({ date: 'x', events: [], stateChanges: [{ nation: 'uk', stat: 'military', op: 'set', value: 5 }], relations: [], territoryChanges: [] })).toBe(true);
+    expect(isMeaningful({ date: 'x', events: [], stateChanges: [{ nation: 'uk', stat: 'military', op: 'set', value: 5 }], relations: [], territoryChanges: [], unowned: [], nationOps: [] })).toBe(true);
-    expect(isMeaningful({ date: 'x', events: [], stateChanges: [], relations: [], territoryChanges: [] })).toBe(false);
+    expect(isMeaningful({ date: 'x', events: [], stateChanges: [], relations: [], territoryChanges: [], unowned: [], nationOps: [] })).toBe(false);
  });
  it('(v0.23 #16 P4a) a turn that only proposes a nation-op is meaningful (it survives the retry/nudge path)', () => {
    expect(
      isMeaningful({
        date: 'x',
        events: [],
        stateChanges: [],
        relations: [],
        territoryChanges: [],
        unowned: [],
        nationOps: [{ kind: 'rename', nationRef: 'de', to: 'Reich' }],
      }),
    ).toBe(true);
  });
 });
@@ -19,10 +19,18 @@ import {
  isDateLike,
  makeEvent,
  nationForPrompt,
  type NationOp,
  type TurnEventSpec,
  type TurnResult,
 } from '../shared/protocol';
-import { DEFAULT_MAX_TOKENS, type LlmClient } from './llm';
+import {
  DEFAULT_MAX_TOKENS,
  type ChatMessage,
  type LlmClient,
  type ToolDefinition,
  type ToolExecutor,
  type WireMessage,
 } from './llm';
 import { ADVISOR_MARKER } from './stub';
 const VALID_EVENT_TYPES = new Set<string>(EVENT_TYPES);
@@ -30,13 +38,128 @@ const VALID_RELATIONS = new Set<string>(RELATION_STATUSES);
 const VALID_OUTCOMES = new Set<string>(['success', 'failure', 'partial', 'neutral']);
 const VALID_STATS = new Set<string>(['military', 'economy', 'stability', 'population']);
 // --- The LLM's getNeighbours tool (v0.21, #16 P2: contiguous region transfers) ---
 /**
 * The single tool the turn loop exposes to the model: the precomputed region
 * adjacency manifest (public/region-adjacency.json, via the resolver injected
 * into runTurn). Given a set of region keys it returns the union of their
 * bordering keys (the queried keys themselves excluded, sorted for
 * determinism) — so the model can verify that a territory transfer is
 * *contiguous* (a nation gains a region it already abuts) before committing
 * it, instead of moving whole countries at a whim.
 */
 export const GET_NEIGHBOURS_TOOL: ToolDefinition = {
  type: 'function',
  function: {
    name: 'getNeighbours',
    description:
      'List the region keys that share a land border with any of the given region keys. ' +
      'Pass a nation\'s territory keys (or a single region key) to see which regions are ' +
      'contiguous to it. Use it before transferring territory: a nation can realistically ' +
      'only gain regions that border its existing territory.',
    parameters: {
      type: 'object',
      properties: {
        regionKeys: {
          type: 'array',
          items: { type: 'string' },
          description: 'One or more region keys to query (e.g. a gaining nation\'s territory).',
        },
      },
      required: ['regionKeys'],
      additionalProperties: false,
    },
  },
 };
 /**
 * Build the tool executor for the turn loop. Never throws: unknown tool
 * names, malformed arguments, and unknown region keys all degrade to a safe
 * response (an error object or an empty list) that the model can recover from.
 */
 export function makeNeighboursExecutor(
  getNeighbours: (keys: string[]) => string[],
  validRegionKeys?: ReadonlySet<string>,
 ): ToolExecutor {
  return (name, args) => {
    if (name !== GET_NEIGHBOURS_TOOL.function.name) {
      return JSON.stringify({ error: `unknown tool: ${name}` });
    }
    const raw = Array.isArray(args.regionKeys) ? args.regionKeys : [];
    const keys = raw.filter((k): k is string => typeof k === 'string' && k.length > 0);
    const valid = validRegionKeys ? keys.filter((k) => validRegionKeys.has(k)) : keys;
    if (valid.length === 0) return JSON.stringify({ neighbours: [] });
    return JSON.stringify({ neighbours: getNeighbours(valid) });
  };
 }
 /**
 * The player's frontier: region keys owned by *other* nations that share a
 * land border with the player's territory (deduped, sorted — stable order for
 * the deterministic stub). Computed server-side from the adjacency manifest so
 * both the LLM (the `frontier` field of the user prompt) and the stub (which
 * cannot call tools) see the same candidates. Empty when there is no
 * adjacency data or no controllable border (e.g. the UK in 1939).
 */
 export function playerFrontier(
  state: GameState,
  getNeighbours: (keys: string[]) => string[],
 ): string[] {
  const player = state.nations[state.playerNationId];
  if (!player || player.territory.length === 0) return [];
  const playerKeys = new Set(player.territory);
  const candidates = new Set<string>();
  for (const key of getNeighbours(player.territory)) {
    if (!playerKeys.has(key)) candidates.add(key);
  }
  if (candidates.size === 0) return [];
  const frontier: string[] = [];
  for (const n of Object.values(state.nations)) {
    if (n.id === state.playerNationId) continue;
    for (const key of n.territory) {
      if (candidates.has(key)) {
        candidates.delete(key);
        frontier.push(key);
      }
    }
  }
  return frontier.sort();
 }
 // --- Prompt building ----------------------------------------------------------
-/** The LLM system prompt: world context + rules + a strict JSON contract. */
+/**
-export function buildSystemPrompt(preset: Preset): string {
+ * The LLM system prompt: world context + rules + a strict JSON contract.
 * When `withNeighboursTool` is set (the turn runs with the getNeighbours tool
 * available) the contract gains the contiguity rules for territory transfers
 * (v0.21, #16 P2): the model may only move regions across a shared border, and
 * may verify borders with the tool before answering.
 */
 export function buildSystemPrompt(preset: Preset, withNeighboursTool = false): string {
  const rules = preset.simulationRules
    .map((r) => `- ${r}`)
    .join('\n');
  const respondLine = withNeighboursTool
    ? 'You have a getNeighbours tool: given region keys it returns the region keys that border them. You may call it (a few times) to verify land borders before deciding territory transfers. Once done, respond with ONLY a valid JSON object of exactly this shape. No prose, no commentary, no markdown fences, no trailing commas:'
    : 'Respond with ONLY a valid JSON object of exactly this shape. No prose, no commentary, no markdown fences, no trailing commas:';
  // (v0.22, #16 P3) No man's land: a region can be left unowned after a war or
  // cataclysm (the model narrates the cause in "events" and lists the key in
  // "unowned"); unowned regions can later be re-claimed with an ordinary gain.
  // The model sees the current no-man's-land keys in the user payload's
  // "unowned" field and in the "regions" reference table.
  const noMansLandRule =
    '- A region key has at most one owner at all times — never assign a key to two nations. After a war or cataclysm a region may be left unowned ("no man\'s land"): list its key in "unowned" and narrate the cause in "events"; it stays unowned (grey on the map) until a nation re-claims it with a "gain". The "unowned" field of the user message lists the regions currently in no man\'s land.';
  const territoryRules = withNeighboursTool
    ? [
        '- Territory changes must be contiguous: a nation may only GAIN region keys that share a land border with a region it already owns (verify with getNeighbours) and may only LOSE region keys it currently owns.',
        '- The "frontier" field of the user message lists region keys owned by other nations that border the player\'s territory — the natural targets of a player-led conquest this turn.',
        noMansLandRule,
      ]
    : [
        '- Only change borders when war or a decisive political shift justifies it.',
        noMansLandRule,
      ];
  return [
    `WORLD: ${preset.title} — ${preset.startDate}`,
    preset.worldBackground,
@@ -45,7 +168,7 @@ export function buildSystemPrompt(preset: Preset): string {
    rules,
    '',
    'You are the world simulator. You advance the shared world state for ALL nations given the current state and the player\'s move.',
-    'Respond with ONLY a valid JSON object of exactly this shape. No prose, no commentary, no markdown fences, no trailing commas:',
+    respondLine,
    '{',
    '  "date": "YYYY-MM-DD (a few days after the current date)",',
    '  "events": [',
@@ -53,15 +176,20 @@ export function buildSystemPrompt(preset: Preset): string {
    '  ],',
    '  "stateChanges": [{"nation":"<nationId>","stat":"<military|economy|stability|population>","op":"<set|add>","value":<0-100>}],',
    '  "relations": [{"a":"<nationId>","b":"<nationId>","set":"<ally|neutral|rival|hostile|war>"}],',
-    '  "territoryChanges": [{"nation":"<nationId>","gain":["<ISO_A3>"],"lose":["<ISO_A3>"]}]',
+    '  "territoryChanges": [{"nation":"<nationId>","gain":["<region key>"],"lose":["<region key>"]}],',
    '  "unowned": ["<region key>"],',
    '  "nationOps": [{"kind":"rename","nationRef":"<nation id or name>","to":"<new name>"}]',
    '}',
    '',
    'HARD CONSTRAINTS',
-    '- Use only nation ids and ISO_A3 codes that exist in the provided state.',
+    '- Use only nation ids and region keys that exist in the provided state.',
    '- A region key identifies one sub-region; the "regions" table in the user message maps each key to "<region name> (<parent country ISO_A3>)". Use those keys in territoryChanges and unowned.',
    '- List in "unowned" only region keys that a nation currently owns, and narrate each release in "events".',
    '- To rename a nation, add {"kind":"rename","nationRef":"<nation id or name>","to":"<new name>"} to "nationOps". This is a PROPOSAL: it only takes effect if the player confirms it, so use it only when the narrative justifies it (a revolution, reunification, regime change) — at most 1-2 per turn — and narrate it in "events".',
    '- Prefer 1-4 events per turn; keep each text 1-3 sentences.',
    '- Keep your internal reasoning brief (a few sentences) and go straight to the JSON result; do not over-deliberate or re-derive facts already present in the state.',
    '- Keep every stat value between 0 and 100.',
-    '- Only change borders when war or a decisive political shift justifies it.',
+    ...territoryRules,
    '- If a field is not relevant this turn, set it to an empty array.',
  ].join('\n');
 }
@@ -75,7 +203,25 @@ export function buildSystemPrompt(preset: Preset): string {
 * model to simulate the combined consequences of the whole batch (or to let the
 * world advance on its own when the batch is empty) and return one TurnResult.
 */
-export function buildUserPrompt(state: GameState, items: RoundItem[]): string {
+export function buildUserPrompt(
  state: GameState,
  items: RoundItem[],
  regionReference?: Record<string, string>,
  /**
   * The player's frontier: region keys owned by other nations that border the
   * player's territory (v0.21, #16 P2). Emitted verbatim (even when empty) so
   * the model — and the deterministic stub, which reads it — see the same
   * contiguous targets. Omitted entirely when undefined (no adjacency data).
   */
  frontier?: string[],
  /**
   * (v0.22, #16 P3) Region keys that are currently "no man's land" (released
   * mid-game — `state.unowned`). Emitted verbatim (even when empty) so the
   * model knows which unowned regions exist and can be re-claimed this turn.
   * Omitted entirely when undefined.
   */
  noMansLand?: string[],
 ): string {
  const player = state.nations[state.playerNationId];
  const playerName = player?.name ?? state.playerNationId;
  const playerActions = items.map((i) =>
@@ -88,7 +234,7 @@ export function buildUserPrompt(state: GameState, items: RoundItem[]): string {
        )}. Simulate the combined consequences across all nations and advance the world by one period. Return a single TurnResult.`
      : 'The player takes no action this period; let the world advance on its own momentum. Return a single TurnResult.';
-  const payload = {
+  const payload: Record<string, unknown> = {
    state: {
      turn: state.turn,
      date: state.date,
@@ -110,6 +256,9 @@ export function buildUserPrompt(state: GameState, items: RoundItem[]): string {
    pending: items,
    roundInstruction,
  };
  if (regionReference) payload.regions = regionReference;
  if (frontier !== undefined) payload.frontier = frontier;
  if (noMansLand !== undefined) payload.unowned = noMansLand;
  return JSON.stringify(payload, null, 2);
 }
@@ -170,6 +319,53 @@ function str(s: unknown, max = 0): string | null {
  return max ? t.slice(0, max) : t;
 }
 /**
 * Validate a raw (LLM) `nationOps` array into safe {@link NationOp} values
 * (v0.23, #16 P4a). Defensive like the rest of the parser: entries with an
 * unknown `kind` or missing/empty required fields are dropped, never throw.
 * Rename: non-empty `nationRef` + `to` (each capped at 200 chars — resolution
 * of `nationRef` to a concrete nation happens later, at confirm time). Split:
 * non-empty `nationRef` + at least one part with a name. Merge: non-empty
 * `nationRefs` (capped at 20) + `survivingRef` + `into`.
 */
 export function validateNationOps(raw: unknown): NationOp[] {
  if (!Array.isArray(raw)) return [];
  const out: NationOp[] = [];
  for (const e of raw) {
    if (!e || typeof e !== 'object') continue;
    const o = e as Record<string, unknown>;
    if (o.kind === 'rename') {
      const nationRef = str(o.nationRef, 200);
      const to = str(o.to, 200);
      if (nationRef && to) out.push({ kind: 'rename', nationRef, to });
    } else if (o.kind === 'split') {
      const nationRef = str(o.nationRef, 200);
      const parts = (Array.isArray(o.parts) ? o.parts : [])
        .filter((p): p is Record<string, unknown> => !!p && typeof p === 'object')
        .map((p) => {
          const name = str(p.name, 200);
          const territory = Array.isArray(p.territory)
            ? p.territory.filter((k): k is string => typeof k === 'string' && k.trim() !== '')
            : [];
          return { name, territory };
        })
        .filter((p): p is { name: string; territory: string[] } => p.name !== null);
      if (nationRef && parts.length > 0) out.push({ kind: 'split', nationRef, parts });
    } else if (o.kind === 'merge') {
      const nationRefs = (Array.isArray(o.nationRefs) ? o.nationRefs : [])
        .map((x) => (typeof x === 'string' ? x.trim().slice(0, 200) : ''))
        .filter((x) => x !== '')
        .slice(0, 20);
      const survivingRef = str(o.survivingRef, 200);
      const into = str(o.into, 200);
      if (nationRefs.length > 0 && survivingRef && into) {
        out.push({ kind: 'merge', nationRefs, survivingRef, into });
      }
    }
  }
  return out;
 }
 /**
 * Validate and normalize an arbitrary parsed object into a safe TurnResult.
 * Ignores unknown/invalid entries; clamps numeric stats to 0-100. Returns null
@@ -184,6 +380,8 @@ export function validateTurnResult(input: unknown): TurnResult | null {
    stateChanges: [],
    relations: [],
    territoryChanges: [],
    unowned: [],
    nationOps: [],
  };
  if (Array.isArray(o.events)) {
@@ -259,12 +457,38 @@ export function validateTurnResult(input: unknown): TurnResult | null {
    }
  }
  // (v0.22, #16 P3) Keys released to "no man's land": deduped, non-empty
  // strings only (applied later by applyTurnResult against validKeys).
  if (Array.isArray(o.unowned)) {
    for (const k of o.unowned) {
      const s = typeof k === 'string' ? k.trim() : '';
      if (s && !result.unowned.includes(s)) result.unowned.push(s);
    }
  }
  // (v0.23, #16 P4a) Nation-management ops the LLM proposes this turn. These
  // are NOT applied by the turn — applyTurnResult appends them to the pending
  // list for the player to confirm/reject.
  result.nationOps = validateNationOps(o.nationOps);
  return result;
 }
-/** A turn is "meaningful" if it produced at least an event or a stat change. */
+/**
 * A turn is "meaningful" if it produced at least an event, a stat change, a
 * no-man's-land release (v0.22 #16 P3: a release is a real world change even
 * when the model under-narrates it), or a nation-op proposal (v0.23 #16 P4a:
 * a proposal is a real pending-world change the player will resolve, so it
 * must survive the retry/nudge path instead of being replaced by the generic
 * "unclear" result).
 */
 export function isMeaningful(result: TurnResult): boolean {
-  return result.events.length > 0 || result.stateChanges.length > 0;
+  return (
    result.events.length > 0 ||
    result.stateChanges.length > 0 ||
    result.unowned.length > 0 ||
    result.nationOps.length > 0
  );
 }
 // --- Applying the delta -------------------------------------------------------
@@ -281,9 +505,13 @@ function genericUnclearEvent(state: GameState): TurnEventSpec {
 /**
 * Apply a TurnResult to a GameState immutably: advance the date/turn, append
- * events, apply stat changes (clamped), symmetric relations, and territory moves.
+ * events, apply stat changes (clamped), symmetric relations, and territory
 * moves (including no-man's-land releases, v0.22 #16 P3). It also appends any
 * proposed nation-ops to the pending list (v0.23 #16 P4a) without applying
 * them — see the doc comment on `pendingNationOps` for why that list
 * deliberately survives across turns.
 */
-export function applyTurnResult(state: GameState, result: TurnResult): GameState {
+export function applyTurnResult(state: GameState, result: TurnResult, validKeys?: ReadonlySet<string>): GameState {
  const next: GameState = JSON.parse(JSON.stringify(state));
  next.version = (state.version ?? 0) + 1; // every mutation is a new revision
  const actingTurn = state.turn; // this action resolves the current turn
@@ -306,21 +534,104 @@ export function applyTurnResult(state: GameState, result: TurnResult): GameState
    a.relations[r.b] = r.set;
    b.relations[r.a] = r.set;
  }
  // --- Territory (v0.21, #16 P2: at most one owner per key;
  //     v0.22, #16 P3: a key may also be released to "no man's land") ---
  //
  // Two kinds of change, applied in this order:
  //
  //  (1) RELEASES (`result.unowned`, v0.22 #16 P3): each key that a nation
  //      CURRENTLY owns (exactly one owner) is removed from that owner, left
  //      ownerless, and added to `GameState.unowned` — the client renders it
  //      as the distinct no-man's-land grey. A key with zero owners (a preset
  //      never assigned it) is never released: doing so would fabricate a
  //      visible no-man's-land out of an ordinary unowned region. A key with
  //      two or more owners (pre-existing corruption) is never touched, and
  //      a key already in `unowned` is a no-op (it is already unowned).
  //
  //  (2) CLAIMS (`gain` entries), resolved against the ownership AFTER the
  //      releases (snapshot-first):
  //      - a key with exactly one owner that is not the gainer → a TRANSFER:
  //        removed from the old owner, granted to the gainer (v0.21 rules);
  //      - a key with NO owner → a RE-CLAIM: granted to the (sole) gainer and
  //        removed from `GameState.unowned` (it leaves no man's land);
  //      - a double claim (two or more distinct gainers) is rejected — the
  //        key stays as it is; a self-gain is a no-op; a pre-existing double
  //        ownership is never touched.
  //
  // Invariants after the turn: no key sits in two or more territories; a
  // released key sits in none; `GameState.unowned` holds exactly the
  // zero-owner keys that were released mid-game (not the preset-unassigned
  // ones). "lose" entries remain deliberate no-ops: releasing is the
  // `unowned` list's job, and a lone loss without a release would just
  // orphan a key silently.
  const valid = (k: string) => !validKeys || validKeys.has(k);
  const unowned = new Set(state.unowned ?? []);
  // (1) Releases: establish the new no-man's-land set before any claim.
  for (const key of new Set(result.unowned)) {
    if (!valid(key) || unowned.has(key)) continue;
    const owners = Object.values(next.nations)
      .filter((n) => n.territory.includes(key))
      .map((n) => n.id);
    if (owners.length !== 1) continue; // 0 owners (never assigned) or 2+ (corrupt): no-op
    unowned.add(key);
    next.nations[owners[0]].territory = next.nations[owners[0]].territory.filter((k) => k !== key);
  }
  // (2) Claims against the post-release ownership snapshot.
  const ownerOf = new Map<string, string>(); // key -> sole owner id, or '' (2+ owners; 0 = absent)
  for (const n of Object.values(next.nations)) {
    for (const key of n.territory) {
      if (!valid(key)) continue;
      const cur = ownerOf.get(key);
      if (cur === undefined) ownerOf.set(key, n.id);
      else if (cur !== '') ownerOf.set(key, '');
    }
  }
  // Claim pairs, deduped: one (key, gainer) per pair even if the model emits
  // duplicate entries; two DIFFERENT gainers for one key is a double claim.
  const claimPairs = new Set<string>();
  for (const t of result.territoryChanges) {
-    const n = next.nations[t.nation];
+    if (!next.nations[t.nation]) continue;
-    if (!n) continue;
+    for (const key of new Set(t.gain)) {
-    for (const code of t.gain) {
+      if (!valid(key)) continue;
-      for (const other of Object.values(next.nations)) {
+      claimPairs.add(`${key}\u0000${t.nation}`);
        const i = other.territory.indexOf(code);
        if (i !== -1) other.territory.splice(i, 1);
    }
      if (!n.territory.includes(code)) n.territory.push(code);
  }
-    for (const code of t.lose) {
+  const claimants = new Map<string, Set<string>>(); // key -> distinct gainers
-      const i = n.territory.indexOf(code);
+  for (const pair of claimPairs) {
    const idx = pair.indexOf('\u0000');
    const key = pair.slice(0, idx);
    const gainer = pair.slice(idx + 1);
    let set = claimants.get(key);
    if (set === undefined) {
      set = new Set();
      claimants.set(key, set);
    }
    set.add(gainer);
  }
  for (const [key, claiming] of claimants) {
    if (claiming.size !== 1) continue; // double claim: the key stays as it was
    const gainer = [...claiming][0];
    const owner = ownerOf.get(key); // undefined: no owner; '': 2+ owners (corrupt)
    if (owner === '') continue; // pre-existing double ownership: never touched
    if (owner !== undefined && owner === gainer) continue; // self-gain: no-op
    for (const n of Object.values(next.nations)) {
      const i = n.territory.indexOf(key);
      if (i !== -1) n.territory.splice(i, 1);
    }
    next.nations[gainer].territory.push(key);
    unowned.delete(key); // re-claimed: the key leaves no man's land
  }
  next.unowned = [...unowned];
  // (v0.23, #16 P4a) Nation-op proposals are NOT applied by the turn — they
  // are appended to the pending list, which (unlike `pending`) SURVIVES
  // across turns until the player confirms or rejects each one. `next` is a
  // deep clone of `state`, so `next.pendingNationOps` is a copy of whatever
  // the state already held (or undefined for a legacy row) — start from that
  // and append the new proposals, defaulting a missing field to `[]`.
  next.pendingNationOps = [...(next.pendingNationOps ?? []), ...result.nationOps];
  return next;
 }
@@ -355,37 +666,167 @@ export function removeRoundItem(state: GameState, index: number | undefined): Ga
  return next;
 }
 // --- Nation-management ops (v0.23, #16 P4a: the hybrid "LLM proposes,
 // player confirms" model) ----------------------------------------------------
 //
 // A NationOp proposed by a turn lands in `GameState.pendingNationOps` (see
 // applyTurnResult) and waits there across turns. These functions resolve the
 // player's decision on one pending proposal, by index. Like removeRoundItem
 // they are pure: clone the state, mutate the clone, bump `version` once,
 // return the new state — and return `null` for a bad index so the route can
 // answer 400 without mutating anything.
 /** True when `index` is a valid, in-bounds integer position in the pending list. */
 function validPendingOpIndex(state: GameState, index: number): boolean {
  const len = state.pendingNationOps?.length ?? 0;
  return Number.isInteger(index) && index >= 0 && index < len;
 }
 /**
- * Run one turn end-to-end against the (injectable) LLM: build prompts, call the
+ * Resolve a nation reference (the `nationRef` of a NationOp — the LLM may
- * model ONCE over the whole pending batch, parse/validate, retry once with a
+ * write either the nation's stable `id` or its human-readable `name`) to a
- * nudge if the result is empty/invalid, and — if it is still invalid — emit a
+ * concrete nation id: an exact id match wins, then a unique case-insensitive
- * generic "unclear" event and advance. The committed state has `pending` cleared.
+ * name match. Returns `null` when the reference is empty, unknown, or
- * Never throws on bad model output; only the underlying transport/network can throw.
+ * ambiguous (two or more nations share that name) — every caller treats
 * `null` as "no-op" and nothing here ever throws.
 */
 export function resolveNationRef(state: GameState, ref: string): string | null {
  const r = (ref ?? '').trim();
  if (!r) return null;
  if (state.nations[r]) return r; // exact id first
  const matches = Object.values(state.nations).filter(
    (n) => n.name.trim().toLowerCase() === r.toLowerCase(),
  );
  return matches.length === 1 ? matches[0].id : null;
 }
 /**
 * Apply one NationOp to a state, MUTATING the passed object in place (the
 * caller passes a clone — confirmNationOp does) and NOT bumping `version`
 * (the route-level functions do that once per decision). Rename changes only
 * `Nation.name` — the id, its territory, its relations (keyed by id), and the
 * player pointer all stay valid, so nothing downstream breaks; a
 * player-supplied `edits.name` overrides the proposed `to` (an empty edit
 * falls back to the proposal's own name). An unresolvable or ambiguous
 * `nationRef` is a silent no-op. Split and merge are declared for P4b and are
 * a no-op until then — the op stays pending-free once the player resolves it,
 * but the world does not change yet.
 */
 export function applyNationOp(state: GameState, op: NationOp, edits?: { name?: string }): void {
  if (op.kind !== 'rename') return; // split/merge: declared for P4b, not applied yet
  const id = resolveNationRef(state, op.nationRef);
  if (id === null) return; // invalid/ambiguous ref: no-op
  const n = state.nations[id];
  if (!n) return;
  const name = (edits?.name ?? '').trim() || op.to.trim();
  if (name) n.name = name;
 }
 /**
 * Confirm a pending nation-op proposal by index: apply it (a rename takes
 * effect, optionally with a player-edited name; split/merge are a no-op until
 * P4b) and remove it from `pendingNationOps`, bumping `version`. Returns
 * `null` for an invalid index, so the route answers 400 without mutating.
 * Reused by the /nation-op/confirm route.
 */
 export function confirmNationOp(
  state: GameState,
  index: number,
  edits?: { name?: string },
 ): GameState | null {
  if (!validPendingOpIndex(state, index)) return null;
  const next: GameState = JSON.parse(JSON.stringify(state));
  next.version = (state.version ?? 0) + 1;
  const op = next.pendingNationOps[index];
  applyNationOp(next, op, edits);
  next.pendingNationOps.splice(index, 1);
  return next;
 }
 /**
 * Reject (drop) a pending nation-op proposal by index without applying it,
 * bumping `version`. Returns `null` for an invalid index, so the route
 * answers 400 without mutating. Reused by the /nation-op/reject route.
 */
 export function rejectNationOp(state: GameState, index: number): GameState | null {
  if (!validPendingOpIndex(state, index)) return null;
  const next: GameState = JSON.parse(JSON.stringify(state));
  next.version = (state.version ?? 0) + 1;
  next.pendingNationOps.splice(index, 1);
  return next;
 }
 /**
 * Run one turn end-to-end against the (injectable) LLM: build prompts, parse/
 * validate, retry once with a nudge if the result is empty/invalid, and — if
 * it is still invalid — emit a generic "unclear" event and advance. The
 * committed state has `pending` cleared. Never throws on bad model output;
 * only the underlying transport/network can throw.
 *
 * When `getNeighbours` is provided AND the LLM client implements
 * `chatWithTools` (v0.21, #16 P2), the turn runs the bounded function-
 * calling loop with the getNeighbours tool (the model may verify land
 * borders before committing a territory transfer) and the user prompt gains
 * the player's `frontier` field. Otherwise it falls back to a plain chat()
 * call — same as before the tool existed.
 */
 export async function runTurn(opts: {
  llm: LlmClient;
  preset: Preset;
  state: GameState;
  items: RoundItem[];
  /** Region reference table (key -> "name (parent)") to include in the user prompt. */
  regionReference?: Record<string, string>;
  /** Set of valid region keys; territory changes with other keys are ignored. */
  validRegionKeys?: ReadonlySet<string>;
  /**
   * Region adjacency resolver (keys -> bordering keys, from the precomputed
   * manifest). Its presence (together with the client's chatWithTools)
   * switches the turn onto the getNeighbours tool path.
   */
  getNeighbours?: (keys: string[]) => string[];
 }): Promise<{ state: GameState; result: TurnResult }> {
-  const { llm, preset, state, items } = opts;
+  const { llm, preset, state, items, regionReference, validRegionKeys, getNeighbours } = opts;
-  const system = buildSystemPrompt(preset);
+  const chatWithTools = llm.chatWithTools;
-  const user = buildUserPrompt(state, items);
+  const useTools = getNeighbours !== undefined && chatWithTools !== undefined;
  const system = buildSystemPrompt(preset, useTools);
  const frontier = getNeighbours ? playerFrontier(state, getNeighbours) : undefined;
  // (v0.22, #16 P3) the model always sees the current no-man's-land keys (empty
  // list on a fresh game) so it knows which unowned regions can be re-claimed.
  const user = buildUserPrompt(state, items, regionReference, frontier, state.unowned ?? []);
  const nudge =
    'Your previous output was invalid. Respond with ONLY the JSON object described above for this batch — no prose, no fences.';
-  let result = parseTurnResult(await llm.chat([
+  /**
   * One model call with the standard turn sampling: the bounded
   * function-calling loop when available, else a plain chat(). The nudge
   * re-send below always starts a FRESH history (no tool context carried
   * over).
   */
  const call = async (history: WireMessage[]): Promise<string> => {
    if (useTools) {
      return await chatWithTools(
        history,
        [GET_NEIGHBOURS_TOOL],
        makeNeighboursExecutor(getNeighbours, validRegionKeys),
        { temperature: 0.4, maxTokens: DEFAULT_MAX_TOKENS },
      );
    }
    return llm.chat(history as ChatMessage[], { temperature: 0.4, maxTokens: DEFAULT_MAX_TOKENS });
  };
  let result = parseTurnResult(await call([
    { role: 'system', content: system },
    { role: 'user', content: user },
-  ], { temperature: 0.4, maxTokens: DEFAULT_MAX_TOKENS }));
+  ]));
  if (result === null || !isMeaningful(result)) {
-    result = parseTurnResult(await llm.chat([
+    result = parseTurnResult(await call([
      { role: 'system', content: system },
      { role: 'user', content: user },
      { role: 'assistant', content: '' },
      { role: 'user', content: nudge },
-    ], { temperature: 0.4, maxTokens: DEFAULT_MAX_TOKENS }));
+    ]));
  }
  if (result === null || !isMeaningful(result)) {
@@ -395,10 +836,12 @@ export async function runTurn(opts: {
      stateChanges: [],
      relations: [],
      territoryChanges: [],
      unowned: [],
      nationOps: [],
    };
  }
-  return { state: applyTurnResult(state, result), result };
+  return { state: applyTurnResult(state, result, validRegionKeys), result };
 }
 // --- Advisor (brainstorm) -----------------------------------------------------
@@ -12,14 +12,17 @@ import { deepClone } from '../shared/protocol';
 import type {
  AddActionRequest,
  AddDiplomacyRequest,
  ConfirmNationOpRequest,
  CreateGameRequest,
  RejectNationOpRequest,
  RemoveQueueItemRequest,
 } from '../shared/protocol';
 import type { GameState } from '../shared/types';
 import { createLlmClient } from './llm';
 import { makeStubLlmClient } from './stub';
-import { askAdvisor, queueRoundItem, removeRoundItem, runTurn } from './engine';
+import { askAdvisor, confirmNationOp, queueRoundItem, rejectNationOp, removeRoundItem, runTurn } from './engine';
 import { buildRegionMap } from './map';
 import { allTerritoryKeys, expandCountriesToKeys, hasAdjacency, loadRegions, neighboursOf, referenceForKeys, validKeys } from './regions';
 import { createPresetStore } from './presets';
 import { openDb, type Db } from './db';
@@ -49,6 +52,9 @@ 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);
 // 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);
 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';
@@ -120,7 +126,19 @@ app.post('/api/games', (req: Request, res) => {
    events: [],
    pending: [],
    version: 1, // the first saved revision; every later mutation bumps it
    // (v0.22, #16 P3) No man's land can only arise mid-game — a fresh game
    // 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.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);
  db.save(state);
  res.json({ game: state });
 });
@@ -212,6 +230,34 @@ app.post('/api/games/:id/queue/remove', (req, res) => {
  res.json({ game: next });
 });
 // (v0.23, #16 P4a) Resolve a pending nation-op proposal (a rename the LLM
 // proposed in an earlier turn, waiting in game.pendingNationOps). 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.
@@ -227,6 +273,17 @@ app.post('/api/games/:id/jump', async (req, res) => {
      preset,
      state: game,
      items: game.pending,
      // (v0.22, #16 P3) the region reference table must also cover released
      // (no-man's-land) keys — they belong to no nation's territory, but the
      // model needs their names to re-claim them.
      regionReference: referenceForKeys(
        new Set([...allTerritoryKeys(game), ...(game.unowned ?? [])]),
      ),
      validRegionKeys: validKeys(),
      // v0.21 (#16 P2): when the region-adjacency manifest loaded, hand the
      // 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,
    });
    db.save(state);
    broadcast(id, 'turn', { state, result });
@@ -208,3 +208,182 @@ describe('createLlmClient (injectable transport)', () => {
    );
  });
 });
 describe('createLlmClient.chatWithTools (function-calling loop, v0.21 #16 P2)', () => {
  const tool = {
    type: 'function' as const,
    function: {
      name: 'getNeighbours',
      description: 'list bordering region keys',
      parameters: { type: 'object' },
    },
  };
  function toolCallResponse(id: string, name: string, args: string) {
    return json({
      choices: [
        {
          finish_reason: 'tool_calls',
          message: {
            content: null,
            tool_calls: [{ id, type: 'function', function: { name, arguments: args } }],
          },
        },
      ],
    });
  }
  function contentResponse(content: string) {
    return json({ choices: [{ finish_reason: 'stop', message: { content } }] });
  }
  it('sends tools in the first request; echoes the assistant tool_calls + tool result; the executor gets parsed args', async () => {
    const sent: string[] = [];
    const transport = async (_url: string, init?: RequestInit) => {
      sent.push(String(init?.body ?? ''));
      if (sent.length === 1) return toolCallResponse('call_1', 'getNeighbours', '{"regionKeys":["a"]}');
      return contentResponse('final answer');
    };
    const executorCalls: Array<{ name: string; args: Record<string, unknown> }> = [];
    const llm = createLlmClient({ transport, apiBase: 'http://x/v1', model: 'm' });
    const out = await llm.chatWithTools!(
      [{ role: 'user', content: 'hi' }],
      [tool],
      (name, args) => {
        executorCalls.push({ name, args });
        return JSON.stringify({ neighbours: ['b'] });
      },
    );
    expect(out).toBe('final answer');
    expect(sent).toHaveLength(2);
    // request 1: the tools array is present, history is just the initial message
    const body1 = JSON.parse(sent[0]);
    expect(body1.tools).toEqual([tool]);
    expect(body1.messages).toEqual([{ role: 'user', content: 'hi' }]);
    // request 2: the assistant tool-call and the tool result are echoed back
    const body2 = JSON.parse(sent[1]);
    expect(body2.tools).toEqual([tool]);
    expect(body2.messages).toEqual([
      { role: 'user', content: 'hi' },
      {
        role: 'assistant',
        content: null,
        tool_calls: [
          {
            id: 'call_1',
            type: 'function',
            function: { name: 'getNeighbours', arguments: '{"regionKeys":["a"]}' },
          },
        ],
      },
      { role: 'tool', tool_call_id: 'call_1', content: JSON.stringify({ neighbours: ['b'] }) },
    ]);
    // the executor received the parsed (object) arguments, not the raw string
    expect(executorCalls).toEqual([{ name: 'getNeighbours', args: { regionKeys: ['a'] } }]);
  });
  it('a content-only response ends in one round (the executor is never called)', async () => {
    const sent: string[] = [];
    const transport = async (_url: string, init?: RequestInit) => {
      sent.push(String(init?.body ?? ''));
      return contentResponse('done');
    };
    const llm = createLlmClient({ transport, apiBase: 'http://x/v1', model: 'm' });
    const out = await llm.chatWithTools!(
      [{ role: 'user', content: 'hi' }],
      [tool],
      () => {
        throw new Error('the executor must not be called');
      },
    );
    expect(out).toBe('done');
    expect(sent).toHaveLength(1);
  });
  it('bounds the tool rounds: maxRounds tool-call rounds, then one final no-tools request', async () => {
    const sent: string[] = [];
    let n = 0;
    const transport = async (_url: string, init?: RequestInit) => {
      sent.push(String(init?.body ?? ''));
      n += 1;
      if (n <= 2) return toolCallResponse(`call_${n}`, 'getNeighbours', '{}');
      return contentResponse('committed');
    };
    const llm = createLlmClient({ transport, apiBase: 'http://x/v1', model: 'm' });
    const out = await llm.chatWithTools!(
      [{ role: 'user', content: 'hi' }],
      [tool],
      () => JSON.stringify({ neighbours: [] }),
      { maxRounds: 2 },
    );
    expect(out).toBe('committed');
    expect(sent).toHaveLength(3); // 2 tool rounds + the forced final request
    expect(JSON.parse(sent[2]).tools).toBeUndefined(); // the final request has no tools
  });
  it('malformed tool arguments produce an "invalid tool arguments" tool message (no throw)', async () => {
    const sent: string[] = [];
    let n = 0;
    const transport = async (_url: string, init?: RequestInit) => {
      sent.push(String(init?.body ?? ''));
      n += 1;
      if (n === 1) return toolCallResponse('call_1', 'getNeighbours', '{not valid json');
      return contentResponse('recovered');
    };
    const llm = createLlmClient({ transport, apiBase: 'http://x/v1', model: 'm' });
    const out = await llm.chatWithTools!(
      [{ role: 'user', content: 'hi' }],
      [tool],
      () => {
        throw new Error('the executor must not be called on malformed args');
      },
    );
    expect(out).toBe('recovered');
    const body2 = JSON.parse(sent[1]);
    const toolMsg = body2.messages.find((m: { role?: string }) => m.role === 'tool');
    expect(toolMsg).toBeDefined();
    expect(toolMsg.content).toMatch(/invalid tool arguments/);
  });
  it('retries a tool-call round on transient failure and still resolves the tool (500 → tool_calls → content)', async () => {
    const sent: string[] = [];
    let n = 0;
    const transport = async (_url: string, init?: RequestInit) => {
      sent.push(String(init?.body ?? ''));
      n += 1;
      if (n === 1) return httpError(500);
      if (n === 2) return toolCallResponse('call_1', 'getNeighbours', '{"regionKeys":["a"]}');
      return contentResponse('ok');
    };
    const llm = createLlmClient({
      transport,
      apiBase: 'http://x/v1',
      model: 'm',
      retryBaseDelayMs: 1,
    });
    const out = await llm.chatWithTools!(
      [{ role: 'user', content: 'hi' }],
      [tool],
      () => JSON.stringify({ neighbours: [] }),
    );
    expect(out).toBe('ok');
    expect(sent).toHaveLength(3);
  });
  it('a tool-call response is never treated as a truncation failure (content null is fine)', async () => {
    const sent: string[] = [];
    const transport = async (_url: string, init?: RequestInit) => {
      sent.push(String(init?.body ?? ''));
      if (sent.length === 1) return toolCallResponse('call_1', 'getNeighbours', '{}');
      return contentResponse('ok');
    };
    const llm = createLlmClient({ transport, apiBase: 'http://x/v1', model: 'm' });
    const out = await llm.chatWithTools!(
      [{ role: 'user', content: 'hi' }],
      [tool],
      () => JSON.stringify({ neighbours: [] }),
    );
    expect(out).toBe('ok');
    expect(sent).toHaveLength(2); // no retry of the first (successful) round
  });
 });
@@ -23,12 +23,55 @@
 // to 3 total attempts and 2s→3s backoff (±20% jitter). HTTP 4xx is a
 // deterministic client error and throws immediately, with no retry. Every
 // call is logged: one line on success, one on final failure.
 //
 // Function calling: `chatWithTools()` extends `chat()` with the OpenAI tool
 // loop. When the model answers with `finish_reason: "tool_calls"`, the client
 // runs the provided executor for every requested call, appends the assistant
 // tool-call message plus one `tool` result message per call, and re-sends the
 // growing history until the model produces a final `content`. The loop is
 // bounded to DEFAULT_MAX_TOOL_ROUNDS (6) tool rounds; if the budget is spent
 // without a final answer, one last *no-tools* request forces the model to
 // commit. The same retry/backoff/reasoning-effort machinery applies per
 // request, so an injectable transport only has to forward `tools` in the body
 // and accept `assistant`/`tool` messages in the history. The deterministic
 // stub answers plain `content` (no tool calls) and therefore bypasses the
 // loop in a single round.
 export interface ChatMessage {
  role: 'system' | 'user' | 'assistant';
  content: string;
 }
 /** One OpenAI-style function call the model requests (`finish_reason: "tool_calls"`). */
 export interface ToolCallSpec {
  id: string;
  type: 'function';
  function: { name: string; arguments: string };
 }
 /** A function the model may call (one OpenAI `tools` entry). */
 export interface ToolDefinition {
  type: 'function';
  function: {
    name: string;
    description?: string;
    parameters?: Record<string, unknown>;
  };
 }
 /**
 * The full message vocabulary a request can carry: plain chat messages, plus
 * assistant messages that request tool calls and the `tool` results that
 * answer them (the OpenAI function-calling wire shape).
 */
 export type WireMessage =
  | ChatMessage
  | { role: 'assistant'; content: string | null; tool_calls: ToolCallSpec[] }
  | { role: 'tool'; tool_call_id: string; content: string };
 /** Executes one tool call; the returned string is fed back to the model as the `tool` result. */
 export type ToolExecutor = (name: string, args: Record<string, unknown>) => string;
 /** A network call. The default implementation is native fetch. */
 export type Transport = (url: string, init?: RequestInit) => Promise<Response>;
@@ -39,6 +82,18 @@ export interface ChatOptions {
 export interface LlmClient {
  chat(messages: ChatMessage[], opts?: ChatOptions): Promise<string>;
  /**
   * The function-calling variant of chat() — see the file header for the loop
   * semantics (bounded tool rounds, then a forced final answer). Optional on
   * the interface: minimal test doubles may omit it, and callers (the
   * engine's runTurn) fall back to chat() when it is absent.
   */
  chatWithTools?(
    messages: WireMessage[],
    tools: ToolDefinition[],
    executeTool: ToolExecutor,
    opts?: ChatOptions & { maxRounds?: number },
  ): Promise<string>;
  listModels(): Promise<string[]>;
 }
@@ -63,9 +118,17 @@ export const DEFAULT_MAX_TOKENS = 4000;
 */
 export const DEFAULT_REASONING_EFFORT = 'low';
-/** Total attempts `chat()` makes before giving up (1 initial + 2 retries). */
+/** Total attempts per request (chat / chatWithTools) before giving up (1 initial + 2 retries). */
 export const MAX_ATTEMPTS = 3;
 /**
 * Max tool-call rounds (assistant tool_calls → tool results) a chatWithTools
 * loop may make before a final no-tools request forces the answer. Keeps a
 * turn bounded even if the model keeps asking for data; a realistic turn uses
 * 0–2 rounds.
 */
 export const DEFAULT_MAX_TOOL_ROUNDS = 6;
 /** Base retry backoff: retry 1 waits 2000ms, retry 2 waits 3000ms, each ±20% jitter. */
 const RETRY_BASE_DELAY_MS = 2000;
@@ -154,6 +217,30 @@ function isNetworkError(err: unknown): boolean {
  );
 }
 /** Parse the wire `tool_calls` array into validated ToolCallSpecs (malformed entries are dropped). */
 function parseToolCalls(raw: unknown): ToolCallSpec[] {
  if (!Array.isArray(raw)) return [];
  const out: ToolCallSpec[] = [];
  for (const tc of raw) {
    if (!tc || typeof tc !== 'object') continue;
    const t = tc as Record<string, unknown>;
    const fn = t.function as Record<string, unknown> | undefined;
    if (!fn || typeof fn.name !== 'string' || fn.name === '') continue;
    const argumentsText =
      typeof fn.arguments === 'string'
        ? fn.arguments
        : fn.arguments != null
          ? JSON.stringify(fn.arguments)
          : '{}';
    out.push({
      id: typeof t.id === 'string' && t.id !== '' ? t.id : `call_${out.length}`,
      type: 'function',
      function: { name: fn.name, arguments: argumentsText },
    });
  }
  return out;
 }
 /** One transport attempt, classified as success / retryable / fatal. */
 interface Attempt {
  status?: number;
@@ -161,6 +248,7 @@ interface Attempt {
  retryable: boolean;
  content?: string;
  finishReason?: string | null;
  toolCalls?: ToolCallSpec[];
 }
 export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
@@ -179,7 +267,7 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
  /**
   * One POST to /chat/completions. Classifies the outcome:
-   *   - success   → content + finish_reason
+   *   - success   → content and/or tool_calls
   *   - retryable → timeout/abort, HTTP 5xx, network error, null/empty content
   *   - fatal     → HTTP 4xx (deterministic client error) or an unexpected throw
   */
@@ -213,12 +301,27 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
    const body = (await res.json()) as {
      choices?: {
        finish_reason?: string | null;
-        message?: { content?: string; reasoning?: string | null };
+        message?: { content?: string; reasoning?: string | null; tool_calls?: unknown };
      }[];
    };
    const choice = body.choices?.[0];
    const message = choice?.message;
    // A tool-call round is a SUCCESS even though `content` is null there: the
    // model is asking for data, not failing (never treat it as truncation).
    const toolCalls = parseToolCalls(message?.tool_calls);
    if (toolCalls.length > 0) {
      return {
        status: res.status,
        retryable: false,
        content:
          typeof message?.content === 'string' && message.content !== '' ? message.content : undefined,
        finishReason: choice?.finish_reason ?? null,
        toolCalls,
      };
    }
    // The reasoning model can exhaust its output budget on the CoT and return
    // a null `content` — treat that as a retryable truncation, not a success.
-    const content = body.choices?.[0]?.message?.content;
+    const content = message?.content;
    if (typeof content !== 'string' || content === '') {
      return {
        status: res.status,
@@ -230,11 +333,16 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
      status: res.status,
      retryable: false,
      content,
-      finishReason: body.choices?.[0]?.finish_reason ?? null,
+      finishReason: choice?.finish_reason ?? null,
    };
  }
-  async function chat(messages: ChatMessage[], opts: ChatOptions = {}): Promise<string> {
+  /** Build one /chat/completions request body. `tools` is only included when non-empty, so plain chat() keeps its exact legacy shape. */
  function buildPayload(
    messages: WireMessage[],
    tools: ToolDefinition[] | undefined,
    opts: ChatOptions,
  ): Record<string, unknown> {
    const payload: Record<string, unknown> = {
      model,
      messages,
@@ -245,7 +353,16 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
    };
    if (opts.temperature != null) payload.temperature = opts.temperature;
    if (sendEffort) payload.reasoning_effort = effort;
    if (tools && tools.length > 0) payload.tools = tools;
    return payload;
  }
  /**
   * One request with the standard retry/backoff: up to MAX_ATTEMPTS per
   * request; resolves with a successful Attempt (content and/or toolCalls) or
   * throws the last error once the attempts are spent.
   */
  async function requestWithRetry(payload: Record<string, unknown>): Promise<Attempt> {
    const totalStart = Date.now();
    let lastStatus: number | undefined;
    let lastError: Error = new Error('chat failed: no attempt completed');
@@ -255,12 +372,13 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
      if (out.status !== undefined) lastStatus = out.status;
      if (out.error) lastError = out.error;
-      if (out.content !== undefined) {
+      if (out.content !== undefined || out.toolCalls !== undefined) {
        console.log('[llm] chat ok', {
          ms: Date.now() - totalStart,
          finishReason: out.finishReason ?? null,
          toolCalls: out.toolCalls?.length ?? 0,
        });
-        return out.content;
+        return out;
      }
      // Give up on a non-retryable failure, or when the last attempt is spent.
      if (!out.retryable || attempt === MAX_ATTEMPTS) {
@@ -278,6 +396,68 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
    throw lastError;
  }
  async function chat(messages: ChatMessage[], opts: ChatOptions = {}): Promise<string> {
    const out = await requestWithRetry(buildPayload(messages, undefined, opts));
    return out.content ?? '';
  }
  /**
   * The function-calling loop — see the file header. Bounded: at most
   * `maxRounds` tool rounds, then one final no-tools request forces an answer.
   * Throws like chat() only on transport-level exhaustion (the engine maps that
   * to a 502; bad *content* never throws, it is parsed defensively downstream).
   */
  async function chatWithTools(
    initial: WireMessage[],
    tools: ToolDefinition[],
    executeTool: ToolExecutor,
    opts: ChatOptions & { maxRounds?: number } = {},
  ): Promise<string> {
    const maxRounds = Math.max(1, opts.maxRounds ?? DEFAULT_MAX_TOOL_ROUNDS);
    const messages: WireMessage[] = [...initial];
    for (let round = 0; round < maxRounds; round++) {
      const out = await requestWithRetry(buildPayload(messages, tools, opts));
      // Tool calls win over any partial content: the model asked for data
      // before it finished.
      if (out.toolCalls && out.toolCalls.length > 0) {
        messages.push({
          role: 'assistant',
          content: out.content ?? null,
          tool_calls: out.toolCalls,
        });
        for (const tc of out.toolCalls) {
          let result: string;
          try {
            const parsed: unknown =
              tc.function.arguments !== '' ? JSON.parse(tc.function.arguments) : {};
            const args =
              parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
                ? (parsed as Record<string, unknown>)
                : {};
            result = executeTool(tc.function.name, args);
          } catch (err) {
            // Malformed arguments are not fatal: hand the model an error
            // result so it can re-call with valid arguments or move on.
            result = JSON.stringify({
              error: `invalid tool arguments: ${err instanceof Error ? err.message : String(err)}`,
            });
          }
          messages.push({ role: 'tool', tool_call_id: tc.id, content: result });
        }
        continue;
      }
      if (out.content !== undefined) return out.content;
    }
    // The tool budget is spent without a final answer: one last no-tools
    // request forces the model to commit.
    messages.push({
      role: 'user',
      content: 'You have reached your tool budget. Answer now with the final result only.',
    });
    const out = await requestWithRetry(buildPayload(messages, undefined, opts));
    return out.content ?? '';
  }
  async function listModels(): Promise<string[]> {
    const res = await transport(`${apiBase}/models`, {
      signal: AbortSignal.timeout(timeoutMs),
@@ -287,5 +467,5 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
    return (body.data ?? []).map((m) => m.id);
  }
-  return { chat, listModels };
+  return { chat, chatWithTools, listModels };
 }
@@ -1,8 +1,24 @@
 import { describe, expect, it } from 'vitest';
 import { buildRegionMap } from './map';
-import { nationColor, regionOwner, type RegionMap } from '../shared/protocol';
+import {
  mapFeatureOwner,
  nationColor,
  NO_MANS_LAND_FILL,
  NO_MANS_LAND_STROKE,
  OWNED_STROKE,
  regionFillStyle,
  regionOwner,
  UNOWNED_FILL,
  UNOWNED_STROKE,
  unownedTooltipLabel,
  type RegionMap,
 } from '../shared/protocol';
 import type { GameState } from '../shared/types';
 // Region-key fixtures (v0.19, #16 P1): ownership and the RegionMap are now keyed
 // by region key (one per owned sub-region), not by a parent-country ISO_A3. The
 // keys below are deliberately fake (obviously not real manifest entries) so this
 // test stays self-contained and format-agnostic.
 const state: GameState = {
  id: 'g',
  presetId: 'p',
@@ -16,7 +32,7 @@ const state: GameState = {
      name: 'UK',
      type: 'major',
      stats: { military: 80, economy: 70, stability: 60, population: 50 },
-      territory: ['GBR', 'IRL'],
+      territory: ['albania-aaaa', 'wales-bbbb'],
      relations: {},
    },
    de: {
@@ -24,37 +40,49 @@ const state: GameState = {
      name: 'DE',
      type: 'major',
      stats: { military: 90, economy: 70, stability: 70, population: 90 },
-      territory: ['DEU'],
+      territory: ['brandenburg-cccc'],
      relations: {},
    },
  },
  events: [],
  pending: [],
  version: 1,
  unowned: [],
  pendingNationOps: [],
 };
-// The RegionMap built from the fixture: the authoritative ISO_A3 → owner source.
+// The RegionMap built from the fixture: the authoritative region key → owner source.
 const regions: RegionMap = buildRegionMap(state);
 describe('buildRegionMap', () => {
-  it('maps each ISO_A3 region to its owner + that nation\'s stable color', () => {
+  it('maps each owned region key to its owner + that nation\'s stable color', () => {
    const m = buildRegionMap(state);
-    expect(m.GBR).toEqual({ color: nationColor('uk'), owner: 'UK', ownerId: 'uk' });
+    expect(m['albania-aaaa']).toEqual({ color: nationColor('uk'), owner: 'UK', ownerId: 'uk' });
-    expect(m.IRL).toEqual({ color: nationColor('uk'), owner: 'UK', ownerId: 'uk' });
+    expect(m['wales-bbbb']).toEqual({ color: nationColor('uk'), owner: 'UK', ownerId: 'uk' });
-    expect(m.DEU).toEqual({ color: nationColor('de'), owner: 'DE', ownerId: 'de' });
+    expect(m['brandenburg-cccc']).toEqual({ color: nationColor('de'), owner: 'DE', ownerId: 'de' });
    // a region nobody owns is simply absent
-    expect(m.FRA).toBeUndefined();
+    expect(m['normandie-dddd']).toBeUndefined();
  });
  it('(v0.22 #16 P3) a released (no-man\'s-land) key — in GameState.unowned, owned by no nation — is absent: absence IS unowned', () => {
    const s: GameState = JSON.parse(JSON.stringify(state));
    // simulate a mid-game release: the key left every territory and entered unowned
    s.nations.uk.territory = s.nations.uk.territory.filter((k) => k !== 'albania-aaaa');
    s.unowned = ['albania-aaaa'];
    const m = buildRegionMap(s);
    expect(m['albania-aaaa']).toBeUndefined(); // the map cannot tell which kind of unowned
    expect(s.unowned).toEqual(['albania-aaaa']); // ...the client's GameState.unowned decides that
  });
 });
 describe('regionOwner', () => {
-  it('resolves an owned region\'s ISO_A3 to its owner record', () => {
+  it('resolves an owned region key to its owner record', () => {
-    expect(regionOwner(regions, 'GBR')).toEqual({
+    expect(regionOwner(regions, 'albania-aaaa')).toEqual({
      color: nationColor('uk'),
      owner: 'UK',
      ownerId: 'uk',
    });
-    expect(regionOwner(regions, 'DEU')).toEqual({
+    expect(regionOwner(regions, 'brandenburg-cccc')).toEqual({
      color: nationColor('de'),
      owner: 'DE',
      ownerId: 'de',
@@ -62,11 +90,11 @@ describe('regionOwner', () => {
  });
  it('returns undefined for an unowned region (no RegionMap entry)', () => {
-    expect(regionOwner(regions, 'FRA')).toBeUndefined();
+    expect(regionOwner(regions, 'normandie-dddd')).toBeUndefined();
-    expect(regionOwner(regions, 'USA')).toBeUndefined();
+    expect(regionOwner(regions, 'yorkshire-eeee')).toBeUndefined();
  });
-  it('returns undefined for an empty or missing code', () => {
+  it('returns undefined for an empty or missing key', () => {
    expect(regionOwner(regions, '')).toBeUndefined();
    expect(regionOwner(regions, null)).toBeUndefined();
    expect(regionOwner(regions, undefined)).toBeUndefined();
@@ -74,40 +102,63 @@ describe('regionOwner', () => {
 });
 /**
- * #6 regression guard. The click/hover handlers resolve the owning nation from a
+ * #6 regression guard (sub-national map, region-keyed). The click/hover handlers
- * map feature. MapLibre repacks a GeoJSON source's top-level `id` (the ISO_A3
+ * resolve the owning nation from a rendered map feature. MapLibre repacks a
- * string) into a *numeric index* when it stores the source, so a feature the map
+ * GeoJSON source's top-level `id` into a *numeric index* when it stores the
- * hands back at interaction time has a number for `id` and the ISO_A3 only lives
+ * source, so a feature the map hands back at interaction time has a number for
- * in `properties.regionId`. This test pins the exact data shape and proves the
+ * `id`. The choropleth is sub-national: a feature's own sub-region id is a code
- * fix: resolution via `properties.regionId` works, while the pre-fix path that
+ * (`DEU-03`), and its owner now lives at its **region key** (`brandenburg-cccc`),
- * read `feature.id` does not.
+ * which the client stamps into `properties.regionKey` from `region-keys.json`
 * (the RegionMap is keyed by that key, never the sub-region id nor the repacked
 * id). This pins the exact data shape and proves the resolution:
 * `mapFeatureOwner` works via `properties.regionKey`, while the two wrong paths
 * (the repacked numeric `feature.id`, and the sub-region `regionId`, which is
 * not a RegionMap key) do not.
 */
-describe('#6 — owner must be resolved from properties.regionId, not the repacked feature.id', () => {
+describe('#6 — sub-region owner must be resolved from properties.regionKey, not the sub-region id / repacked feature.id', () => {
-  // The shape MapLibre returns for a source feature after setData(): `id` is a
+  // The shape MapLibre returns for a sub-region feature after setData(): `id`
-  // number (here 0, as observed in the live map), and the ISO_A3 is preserved
+  // is a number (repacked), and the stable identifiers live only in properties —
-  // only in properties (the client stamps it as `regionId`).
+  // `regionId` (the sub-region code) and `regionKey` (the region key).
  const repackedFeature = {
    id: 0,
-    properties: { name: 'DE', regionId: 'DEU' },
+    properties: { name: 'Brandenburg R03', regionId: 'DEU-03', regionKey: 'brandenburg-cccc' },
  };
-  it('resolves the owner from properties.regionId (the fix)', () => {
+  it('resolves the owner from properties.regionKey (the fix)', () => {
-    const code = typeof repackedFeature.properties.regionId === 'string' ? repackedFeature.properties.regionId : '';
+    expect(mapFeatureOwner(regions, repackedFeature)).toEqual({
    expect(regionOwner(regions, code)).toEqual({
      color: nationColor('de'),
      owner: 'DE',
      ownerId: 'de',
    });
  });
-  it('the old path (feature.id as a string key) does NOT resolve — the bug', () => {
+  it('the sub-region regionId is NOT a RegionMap key — resolving from it fails', () => {
-    // String(0) === '0' is not a valid ISO_A3 key, so the pre-fix lookup failed
+    // 'DEU-03' is a sub-region id; the RegionMap is keyed by region key.
-    // and the click popup reported "No owner" even for owned regions.
+    expect(regionOwner(regions, repackedFeature.properties.regionId)).toBeUndefined();
-    expect(regions[String(repackedFeature.id)]).toBeUndefined();
+  });
  it('the repacked numeric feature.id does NOT resolve — the bug', () => {
    // String(0) === '0' is not a valid key, so the pre-fix lookup failed and
    // reported "No owner" even for owned regions.
    expect(regionOwner(regions, String(repackedFeature.id))).toBeUndefined();
  });
 });
 describe('mapFeatureOwner', () => {
  it('returns undefined for a missing feature, missing regionKey, or non-string regionKey', () => {
    expect(mapFeatureOwner(regions, null)).toBeUndefined();
    expect(mapFeatureOwner(regions, undefined)).toBeUndefined();
    expect(mapFeatureOwner(regions, {})).toBeUndefined();
    expect(mapFeatureOwner(regions, { properties: {} })).toBeUndefined();
    expect(mapFeatureOwner(regions, { properties: { regionKey: 42 } })).toBeUndefined();
  });
  it('returns undefined for a region key nobody owns', () => {
    expect(mapFeatureOwner(regions, { properties: { regionKey: 'normandie-dddd' } })).toBeUndefined();
    expect(mapFeatureOwner(regions, { properties: { regionKey: 'yorkshire-eeee' } })).toBeUndefined();
  });
 });
 describe('nationColor', () => {
  it('is deterministic per id and distinct across different ids', () => {
    expect(nationColor('uk')).toBe(nationColor('uk'));
@@ -116,3 +167,48 @@ describe('nationColor', () => {
    expect(nationColor('uk')).toMatch(/^hsl\(\d+ 58% 46%\)$/);
  });
 });
 // (v0.22, #16 P3) The no-man's-land presentation contract lives in
 // shared/protocol (shared/*.test.ts is not in the vitest glob, so these
 // tests live here): the distinct visible grey, the faint preset-unassigned
 // look, the per-kind borders, and the tooltip sub-line.
 describe('no man\'s land presentation contract (v0.22 #16 P3)', () => {
  it('regionFillStyle: an owned region uses its nation color + the owned border', () => {
    expect(regionFillStyle(regions['albania-aaaa'], false)).toEqual({
      fill: nationColor('uk'),
      stroke: OWNED_STROKE,
    });
    expect(regionFillStyle(regions['brandenburg-cccc'], true)).toEqual({
      fill: nationColor('de'),
      stroke: OWNED_STROKE,
    }); // the no-man's-land flag never affects an owned region
  });
  it('regionFillStyle: an unowned region that IS no man\'s land gets the distinct visible grey', () => {
    expect(regionFillStyle(undefined, true)).toEqual({
      fill: NO_MANS_LAND_FILL,
      stroke: NO_MANS_LAND_STROKE,
    });
  });
  it('regionFillStyle: an unowned region that was never released keeps the faint look', () => {
    expect(regionFillStyle(undefined, false)).toEqual({
      fill: UNOWNED_FILL,
      stroke: UNOWNED_STROKE,
    });
  });
  it('the no-man\'s-land grey can never collide with a nation color (hue-less vs HSL)', () => {
    expect(NO_MANS_LAND_FILL).not.toMatch(/^hsl\(/);
    expect(NO_MANS_LAND_FILL).not.toBe(nationColor('uk'));
    expect(NO_MANS_LAND_FILL).not.toBe(nationColor('de'));
    // and it must be visibly different from the faint preset-unassigned fill
    expect(NO_MANS_LAND_FILL).not.toBe(UNOWNED_FILL);
    expect(NO_MANS_LAND_STROKE).not.toBe(UNOWNED_STROKE);
  });
  it('unownedTooltipLabel: the tooltip sub-line names the two kinds of unowned', () => {
    expect(unownedTooltipLabel(true)).toBe("No man's land");
    expect(unownedTooltipLabel(false)).toBe('No owner');
  });
 });
@@ -1,6 +1,15 @@
-// Build the choropleth payload from a GameState: every ISO_A3 region maps to its
+// Build the choropleth payload from a GameState: every region key (see
-// owning nation plus that nation's stable color (see shared.nationColor). The
+// public/region-keys.json) maps to its owning nation plus that nation's stable
-// client merges this onto public/countries.geo.json and calls source.setData().
+// color (see shared.nationColor). The client merges this onto the sub-national
 // regions.geo.json (resolving each feature by its own region key) and calls
 // source.setData(). Format-agnostic: it maps whatever keys sit in territory.
 //
 // A key ABSENT from the returned map is unowned (no nation's territory holds
 // it) — this covers both regions a preset never assigned and regions released
 // to no man's land mid-game (v0.22, #16 P3). The map deliberately does NOT
 // distinguish the two: the visible no-man's-land grey vs the faint
 // preset-unassigned look is decided by the client from `GameState.unowned`
 // (see shared/protocol.ts's regionFillStyle).
 import { nationColor, type RegionMap } from '../shared/protocol';
 import type { GameState } from '../shared/types';
@@ -8,8 +17,8 @@ export function buildRegionMap(state: GameState): RegionMap {
  const map: RegionMap = {};
  for (const [id, nation] of Object.entries(state.nations)) {
    const color = nationColor(id);
-    for (const code of nation.territory) {
+    for (const key of nation.territory) {
-      map[code] = { color, owner: nation.name, ownerId: id };
+      map[key] = { color, owner: nation.name, ownerId: id };
    }
  }
  return map;
@@ -0,0 +1,194 @@
 import { afterAll, afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { fileURLToPath } from 'node:url';
 import { copyFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import {
  allTerritoryKeys,
  expandCountriesToKeys,
  hasAdjacency,
  hasRegionData,
  loadRegions,
  neighboursOf,
  referenceForKeys,
  regionName,
  resetRegions,
  validKeys,
 } from './regions';
 import type { GameState } from '../shared/types';
 // The repo root: this file lives in server/, so '..' is the directory holding
 // public/region-keys.json and public/regions.geo.json. cwd-independent (mirrors
 // how server/index.ts locates its root via import.meta.url).
 const root = fileURLToPath(new URL('..', import.meta.url));
 describe('regions (region-key loader, v0.19 #16 P1)', () => {
  beforeEach(() => {
    expect(loadRegions(root)).toBe(true);
  });
  it('loads the full manifest: 1,796 unique valid region keys', () => {
    expect(hasRegionData()).toBe(true);
    expect(validKeys().size).toBe(1796);
  });
  it('expands an ISO_A3 country to the region keys of all its sub-regions', () => {
    const fra = expandCountriesToKeys(['FRA']);
    // FRA has 42 sub-regions in the committed dataset.
    expect(fra).toHaveLength(42);
    // every expanded key is a real region key
    for (const k of fra) expect(validKeys().has(k)).toBe(true);
    // and the reference table labels each one with its parent country
    const ref = referenceForKeys(fra);
    expect(Object.keys(ref)).toHaveLength(42);
    for (const [k, label] of Object.entries(ref)) {
      expect(label.endsWith('(FRA)')).toBe(true);
      expect(regionName(k)).toBeTruthy();
    }
    // sample known FRA keys, and their exact reference strings
    expect(fra).toContain('ain-lqtt');
    expect(ref['ain-lqtt']).toBe('Ain (FRA)');
    expect(ref['aisne-gstu']).toBe('Aisne (FRA)');
  });
  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)');
    expect(ref['not-a-real-key-xyz']).toBeUndefined();
  });
  it('allTerritoryKeys unions every nation\'s territory keys (no overlap)', () => {
    const state: GameState = {
      id: 'g',
      presetId: 'p',
      presetTitle: 'P',
      playerNationId: 'uk',
      turn: 1,
      date: '1939-09-01',
      nations: {
        uk: {
          id: 'uk',
          name: 'UK',
          type: 'major',
          stats: { military: 80, economy: 70, stability: 60, population: 50 },
          territory: expandCountriesToKeys(['GBR']),
          relations: {},
        },
        fr: {
          id: 'fr',
          name: 'FR',
          type: 'major',
          stats: { military: 80, economy: 70, stability: 60, population: 50 },
          territory: expandCountriesToKeys(['FRA']),
          relations: {},
        },
      },
      events: [],
      pending: [],
      version: 1,
      unowned: [],
      pendingNationOps: [],
    };
    // 16 GBR sub-regions + 42 FRA sub-regions, no overlap between the two.
    expect(allTerritoryKeys(state).size).toBe(58);
  });
  it('hasAdjacency() is true: the region-adjacency manifest loaded (v0.21 #16 P2)', () => {
    expect(hasAdjacency()).toBe(true);
  });
  it('neighboursOf returns the union of bordering keys (deduped, sorted, queried excluded)', () => {
    // known mutual pairs from the manifest (verified in the Stage 1 spot checks)
    const moselle = neighboursOf(['moselle-rygy']);
    expect(moselle).toContain('baden-wurttemberg-oyje'); // FRA/DEU border
    expect(neighboursOf(['baden-wurttemberg-oyje'])).toContain('moselle-rygy'); // mutual
    expect(neighboursOf(['acre-ekzw'])).toContain('loreto-ipkx'); // BRA/PER border
    expect(neighboursOf(['loreto-ipkx'])).toContain('acre-ekzw'); // mutual
    // union + dedupe + sorted + the queried keys themselves excluded
    const union = neighboursOf(['moselle-rygy', 'baden-wurttemberg-oyje']);
    expect(union).toEqual([...union].sort());
    expect(new Set(union).size).toBe(union.length); // no duplicates
    expect(union).not.toContain('moselle-rygy');
    expect(union).not.toContain('baden-wurttemberg-oyje');
  });
  it('neighboursOf returns [] for unknown keys or an empty set', () => {
    expect(neighboursOf(['not-a-real-key-xyz'])).toEqual([]);
    expect(neighboursOf([])).toEqual([]);
  });
  describe('graceful degradation with no region data', () => {
    beforeEach(() => resetRegions());
    it('expands to the raw input, omits references, and reports no data', () => {
      expect(hasRegionData()).toBe(false);
      // no manifest -> the country list passes through unchanged (old model)
      expect(expandCountriesToKeys(['FRA', 'GBR'])).toEqual(['FRA', 'GBR']);
      expect(referenceForKeys(['FRA'])).toEqual({});
      expect(validKeys().size).toBe(0);
      expect(regionName('FRA')).toBeUndefined();
      // and no adjacency: the LLM tool / frontier field switch off
      expect(hasAdjacency()).toBe(false);
      expect(neighboursOf(['moselle-rygy'])).toEqual([]);
    });
  });
  afterAll(() => resetRegions());
 });
 describe('loadRegions resolves the manifest per environment (dev public/ vs prod dist/)', () => {
  const realRoot = root;
  // A root that mimics the prod Docker image: no public/, the region files live
  // in dist/ (where Vite copies public/* at build). This is the exact layout that
  // broke v0.19.0 in prod (the loader only looked in public/).
  const base = mkdtempSync(path.join(tmpdir(), 'history-regions-'));
  const prodRoot = path.join(base, 'prod');
  beforeEach(() => {
    mkdirSync(path.join(prodRoot, 'dist'), { recursive: true });
    copyFileSync(
      path.join(realRoot, 'public', 'region-keys.json'),
      path.join(prodRoot, 'dist', 'region-keys.json'),
    );
    copyFileSync(
      path.join(realRoot, 'public', 'regions.geo.json'),
      path.join(prodRoot, 'dist', 'regions.geo.json'),
    );
  });
  afterEach(() => resetRegions());
  afterAll(() => {
    rmSync(base, { recursive: true, force: true });
  });
  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(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);
  });
  it('a dist/ WITHOUT the adjacency manifest degrades: hasAdjacency() false, neighboursOf []', () => {
    // this fixture copies only region-keys.json + regions.geo.json (no
    // region-adjacency.json) — the server must boot and serve turns with the
    // tool/frontier simply switched off.
    expect(loadRegions(prodRoot)).toBe(true);
    expect(hasAdjacency()).toBe(false);
    expect(neighboursOf(['moselle-rygy'])).toEqual([]);
  });
  it('returns false and no data when neither public/ nor dist/ holds the files', () => {
    const emptyRoot = path.join(base, 'empty');
    mkdirSync(emptyRoot, { recursive: true });
    expect(loadRegions(emptyRoot)).toBe(false);
    expect(hasRegionData()).toBe(false);
    expect(validKeys().size).toBe(0);
  });
 });
@@ -0,0 +1,207 @@
 // Region-key data access (server). Loads the deterministic region-key manifest
 // (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
 // 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:
 //
 //   - expand a nation's ISO_A3 country list -> the region keys of all its sub-regions (v0.19, #16 P1)
 //   - build the LLM "regions" reference table (key -> "name (parent ISO_A3)")
 //   - the set of all valid region keys (to ignore hallucinated keys in applyTurnResult)
 //   - 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)
 //
 // Deliberately turf-free: it reads the JSON files with plain JSON.parse and
 // never imports @turf/@types/geojson (importing one pulls @types/geojson into
 // the tsc program and breaks WorldMap.tsx; see the v0.17 changelog note).
 // Loaded once at boot; the accessors below are pure data reads thereafter.
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import type { GameState } from '../shared/types';
 /** { name, parent } for one sub-region, where parent is the ISO_A3 country. */
 interface RegionInfo {
  name: string;
  parent: string;
 }
 interface RegionData {
  /** stable feature id -> region key (from public/region-keys.json). */
  idToKey: Record<string, string>;
  /** region key -> { name, parent }. */
  keyToInfo: Record<string, RegionInfo>;
  /** ISO_A3 parent -> region keys of its sub-regions (file order, stable). */
  keysByCountry: Record<string, string[]>;
  /** the set of all region keys. */
  validKeys: Set<string>;
  /** region key -> bordering region keys (from public/region-adjacency.json). */
  adjacency: Record<string, string[]>;
 }
 let data: RegionData | null = null;
 /**
 * Load (or reload) the region-key manifest, geo, and adjacency. 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/`
 * (plus the root as a last resort) and use the first directory that holds the
 * 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
 * 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).
 */
 export function loadRegions(root: string): boolean {
  const keyFile = 'region-keys.json';
  const geoFile = 'regions.geo.json';
  const adjacencyFile = 'region-adjacency.json';
  const base = [
    path.join(root, 'public'), // dev: Vite serves public/ at /
    path.join(root, 'dist'), // prod: Vite copies public/* -> dist/ (== clientDir)
    root, // last resort
  ].find((d) => existsSync(path.join(d, keyFile)) && existsSync(path.join(d, geoFile)));
  if (!base) {
    data = null;
    return false;
  }
  const keyPath = path.join(base, keyFile);
  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 {
      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 ?? []) {
      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 name = typeof f.properties?.name === 'string' ? f.properties.name : '';
      const parent = typeof f.properties?.parent === 'string' ? f.properties.parent : '';
      keyToInfo[key] = { name, parent };
      validKeys.add(key);
      if (parent) (keysByCountry[parent] ??= []).push(key);
    }
    // Adjacency is optional: a missing file means "no adjacency data".
    let adjacency: Record<string, string[]> = {};
    const adjacencyPath = path.join(base, adjacencyFile);
    if (existsSync(adjacencyPath)) {
      try {
        adjacency = JSON.parse(readFileSync(adjacencyPath, 'utf8')) as Record<string, string[]>;
      } catch (err) {
        // A corrupt manifest must not kill the core region data: degrade to
        // "no adjacency" (the LLM tool / frontier guidance simply switch off).
        console.error('[regions] failed to load region-adjacency.json, continuing without it', err);
        adjacency = {};
      }
    }
    data = { idToKey, keyToInfo, keysByCountry, validKeys, adjacency };
    return validKeys.size > 0;
  } catch (err) {
    console.error('[regions] failed to load region data', err);
    data = null;
    return false;
  }
 }
 /** Test/dev seam: drop the loaded data (the next accessors behave as "no data"). */
 export function resetRegions(): void {
  data = null;
 }
 /** True when the manifest + geo loaded cleanly. */
 export function hasRegionData(): boolean {
  return data !== null;
 }
 /**
 * Expand a nation's ISO_A3 country list to the region keys of all its sub-regions
 * (file order, deduped). This is what turns a preset's country-level territory
 * into region-level ownership at game creation. Returns the input unchanged when
 * no region data is loaded (graceful degradation — behaves like the old model).
 */
 export function expandCountriesToKeys(countries: string[]): string[] {
  if (!data) return countries;
  const out: string[] = [];
  const seen = new Set<string>();
  for (const c of countries) {
    for (const key of data.keysByCountry[c] ?? []) {
      if (!seen.has(key)) {
        seen.add(key);
        out.push(key);
      }
    }
  }
  return out;
 }
 /**
 * Build the LLM reference table: region key -> "<name> (<parent ISO_A3>)", e.g.
 * `moselle-rygy -> "Moselle (FRA)"`. Only the given keys are included (the caller
 * passes the game's owned-region universe) so the prompt stays bounded.
 */
 export function referenceForKeys(keys: Iterable<string>): Record<string, string> {
  const out: Record<string, string> = {};
  if (!data) return out;
  for (const key of keys) {
    const info = data.keyToInfo[key];
    if (info) out[key] = info.parent ? `${info.name} (${info.parent})` : info.name;
  }
  return out;
 }
 /** The region key's human name (for the dossier), or undefined if unknown. */
 export function regionName(key: string): string | undefined {
  return data?.keyToInfo[key]?.name;
 }
 /** The union of every nation's territory region keys (the game's region universe). */
 export function allTerritoryKeys(state: GameState): Set<string> {
  const out = new Set<string>();
  for (const n of Object.values(state.nations)) {
    for (const key of n.territory) out.add(key);
  }
  return out;
 }
 /** The set of all valid region keys (to ignore hallucinated keys in applyTurnResult). */
 export function validKeys(): ReadonlySet<string> {
  return data ? data.validKeys : 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
 * engine an adjacency resolver (which turns on the LLM's getNeighbours tool
 * and the frontier prompt field) or fall back to the plain chat() path.
 */
 export function hasAdjacency(): boolean {
  return data !== null && Object.keys(data.adjacency).length > 0;
 }
 /**
 * 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
 * determinism. This is the data behind the LLM's getNeighbours tool and the
 * player-frontier computation in the turn prompt (v0.21, #16 P2). Returns
 * `[]` when no region data (or no adjacency manifest) is loaded.
 */
 export function neighboursOf(keys: Iterable<string>): string[] {
  if (!data) return [];
  const out = new Set<string>();
  for (const key of keys) {
    for (const n of data.adjacency[key] ?? []) out.add(n);
  }
  for (const key of keys) out.delete(key); // never report a key as its own neighbour
  return [...out].sort();
 }
@@ -2,7 +2,7 @@
 // sets LLM_STUB=1) so the whole loop is reproducible with no live model. It
 // 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 TurnEventSpec, type TurnResult } from '../shared/protocol';
+import { addDays, clampStat, type TerritoryChange, type TurnEventSpec, type TurnResult } from '../shared/protocol';
 import type { RoundItem } from '../shared/types';
 export const ADVISOR_MARKER = '<<ADVISOR>>';
@@ -13,10 +13,24 @@ export interface StubPayload {
    turn: number;
    date: string;
    playerNationId: string;
-    nations: Record<string, { stats: Record<string, number> }>;
+    nations: Record<string, { stats: Record<string, number>; territory?: string[] }>;
  };
  /** The raw pending round the engine emitted (one entry per queued item). */
  pending?: RoundItem[];
  /**
   * Region keys owned by other nations that share a land border with the
   * player's territory — the engine's `frontier` field, computed from the
   * adjacency manifest (v0.21, #16 P2). The stub cannot call tools, so it
   * reads the frontier from the prompt instead.
   */
  frontier?: string[];
  /**
   * (v0.22, #16 P3) Region keys currently in no man's land (`state.unowned`),
   * emitted by the engine's user prompt. The stub ignores this field — it
   * never releases a region (see deterministicTurn), so no-man's-land behavior
   * is covered by unit tests against applyTurnResult, not by the stub.
   */
  unowned?: string[];
 }
 function truncate(s: string, n: number): string {
@@ -31,6 +45,22 @@ function truncate(s: string, n: number): string {
 * caller can predict the exact next state for assertions. It always sets the
 * player's military to (current + 5) and allies the player with the first other
 * nation, advancing the date by 2 days.
 *
 * (v0.21, #16 P2) It also makes ONE contiguous conquest per turn: the player
 * gains the first frontier region (sorted order) from its current owner, and
 * that owner loses it. The stub bypasses the tool loop (it answers with plain
 * content in one round), so the frontier comes from the prompt payload, not
 * from a getNeighbours call. With an empty frontier (no controllable border)
 * no territory change is emitted, keeping every existing assertion stable.
 *
 * (v0.22, #16 P3) The stub NEVER releases a region to no man's land (it
 * 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.
 */
 export function deterministicTurn(p: StubPayload): TurnResult {
  const state = p.state;
@@ -42,6 +72,23 @@ export function deterministicTurn(p: StubPayload): TurnResult {
    : 'us';
  const items = p.pending ?? [];
  // The one deterministic region transfer: the player takes the first
  // frontier region (sorted → stable) from whichever other nation owns it.
  let territoryChanges: TerritoryChange[] = [];
  const frontier = p.frontier ?? [];
  if (state && frontier.length > 0) {
    const key = frontier[0];
    const loserId = Object.keys(state.nations).find(
      (id) => id !== pid && (state.nations[id].territory ?? []).includes(key),
    );
    if (loserId) {
      territoryChanges = [
        { nation: pid, gain: [key], lose: [] },
        { nation: loserId, gain: [], lose: [key] },
      ];
    }
  }
  const events: TurnEventSpec[] =
    items.length === 0
      ? [
@@ -76,7 +123,9 @@ export function deterministicTurn(p: StubPayload): TurnResult {
    events,
    stateChanges: [{ nation: pid, stat: 'military', op: 'set', value: mil }],
    relations: otherId ? [{ a: pid, b: otherId, set: 'ally' }] : [],
-    territoryChanges: [],
+    territoryChanges,
    unowned: [], // the stub never creates no man's land (see doc comment)
    nationOps: [], // the stub never proposes nation ops (see doc comment)
  };
 }
@@ -23,13 +23,81 @@ export interface RelationChange {
  set: RelationStatus;
 }
-/** A nation gains/loses ISO_A3 regions this turn. */
+/** A nation gains/loses region keys (see `public/region-keys.json`) this turn. */
 export interface TerritoryChange {
  nation: string;
  gain: string[];
  lose: string[];
 }
 // --- Nation-management ops (v0.23, #16 P4a: 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. Rename
 // is implemented in v0.23 (P4a); split and merge are declared here so the union
 // is stable for P4b, and are defensively accepted-but-not-applied until then.
 /**
 * 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`).
 */
 /**
 * 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 (declared for #16 P4b; **not** applied by the engine yet
 * — it is accepted into the pending list, but confirming it is a no-op until
 * P4b lands). Describes the new nations a source nation is divided into.
 */
 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 (declared for #16 P4b; **not** applied by the engine yet
 * — accepted into the pending list, no-op on confirm until P4b). Folds several
 * nations into a single surviving nation.
 */
 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. Rename is implemented (P4a); split/merge are
 * declared for P4b and are a safe no-op until then.
 */
 export type NationOp = RenameOp | SplitOp | MergeOp;
 /** One narrative event the LLM proposes for this turn. */
 export interface TurnEventSpec {
  nation: string;
@@ -46,31 +114,78 @@ export interface TurnResult {
  stateChanges: StateChange[];
  relations: RelationChange[];
  territoryChanges: TerritoryChange[];
  /**
   * (v0.22, #16 P3) Region keys that become **unowned** — "no man's land" —
   * this turn. The engine removes each key from its current (sole) owner so it
   * ends the turn ownerless and marks it in `GameState.unowned`; the LLM
   * narrates the cause (war, cataclysm, collapse) in `events`. Re-claiming is
   * NOT expressed here: a nation re-claims an unowned region with an ordinary
   * `gain` on that key. Only keys a nation currently owns can be released;
   * empty on normal turns.
   */
  unowned: string[];
  /**
   * (v0.23, #16 P4a) 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. Rename is the only kind the engine currently applies;
   * split/merge are declared for P4b and are accepted-but-dropped. Empty on
   * turns where the model proposes none.
   */
  nationOps: NationOp[];
 }
-/** Per-region map payload: ISO_A3 -> owning nation + its stable color. */
+/** Per-region map payload: region key -> owning nation + its stable color. */
 export interface RegionOwner {
  color: string;
  owner: string;
  ownerId: string;
 }
 /**
 * The authoritative ownership map: a **region key** (see `public/region-keys.json`)
 * -> the owning nation + its stable color. Owned at sub-region granularity (v0.19,
 * #16 P1); a key absent from this map is unowned (rendered grey).
 */
 export type RegionMap = Record<string, RegionOwner>;
 /**
- * Look up the owner record for a map region from the authoritative RegionMap by
+ * Look up the owner record from the authoritative RegionMap by a RegionMap key.
- * its ISO_A3 code. Returns `undefined` for an empty/missing code or an unowned
+ * The RegionMap is keyed by **region key** (see `public/region-keys.json`) — one
- * region. Pure + shared: the client resolves a clicked or hovered map feature by
+ * per owned sub-region (v0.19, #16 P1) — so `key` is a region key such as
- * first reading the feature's stable ISO_A3 code (stored in `properties.regionId`
+ * `moselle-rygy`, never a raw feature id such as `FR-57` and never a
- * by the client when it repacks the source — see WorldMap) and then calling this.
+ * parent-country ISO_A3. Returns `undefined` for an empty/missing key or an
 * unowned region.
 *
- * The code must NOT be taken from the feature's top-level `id`: MapLibre repacks
+ * Pure + shared: the primitive "key → owner" lookup. The *map feature → owner*
- * a GeoJSON source's `id` (an ISO_A3 string) into a numeric index when it stores
+ * resolution (deciding which key to pass) lives in {@link mapFeatureOwner} below,
- * the source, so at click/hover time `feature.id` is a number, never the ISO_A3
+ * which reads the feature's stamped `properties.regionKey` — never the repacked
- * — resolving from it is exactly the "no owner" bug (#6).
+ * top-level `id` (MapLibre turns it into a numeric index, the "no owner" bug #6)
 * and never the sub-region id.
 */
-export function regionOwner(regions: RegionMap, isoA3: string | null | undefined): RegionOwner | undefined {
+export function regionOwner(regions: RegionMap, key: string | null | undefined): RegionOwner | undefined {
-  if (!isoA3) return undefined;
+  if (!key) return undefined;
-  return regions[isoA3];
+  return regions[key];
 }
 /**
 * Resolve the owning-nation record for a **rendered map feature** from the
 * authoritative RegionMap. The choropleth renders sub-national regions, and the
 * RegionMap is now keyed by **region key** (one per sub-region, v0.19 #16 P1),
 * so a feature's owner is found via its `properties.regionKey` — the region key
 * the client stamps from `public/region-keys.json` by the feature's stable id
 * (see WorldMap) — and then `regionOwner`. This is the single shared source of
 * truth for that resolution, so the "use `regionKey`, never the sub-region `id`
 * / repacked `feature.id`" rule lives in one tested place rather than in the
 * React component.
 *
 * Returns `undefined` for a missing feature/regionKey or an unowned region.
 */
 export function mapFeatureOwner(
  regions: RegionMap,
  feature: { properties?: { regionKey?: unknown } } | null | undefined,
 ): RegionOwner | undefined {
  const regionKey = feature?.properties?.regionKey;
  return regionOwner(regions, typeof regionKey === 'string' ? regionKey : '');
 }
 /** Server -> client Server-Sent Events payload (see server/index.ts /sse). */
@@ -124,6 +239,32 @@ export interface RemoveQueueItemResponse {
  game: GameState;
 }
 /**
 * (v0.23, #16 P4a) 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`); split/merge proposals are a no-op on
 * confirm until P4b. No LLM call, no turn advance.
 */
 export interface ConfirmNationOpRequest {
  index: number;
  /** Optional player edits applied on confirm (rename: the final display name). */
  edits?: { name?: string };
 }
 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;
@@ -160,6 +301,47 @@ export function nationColor(id: string): string {
  return `hsl(${hue} 58% 46%)`;
 }
 // --- 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
 // RegionMap (a key absent there is simply unowned): it is decided by the
 // client from `GameState.unowned` (the keys released mid-game). The constants
 // and the one decision function live here — shared and pure — so the
 // client's choropleth is the only consumer and the color contract is testable
 // from the server-side tests (shared/*.test.ts is not in the vitest glob).
 /** The distinct, visible neutral grey for a **no man's land** region (released mid-game). Hue-less by construction, so it can never collide with a nation's `nationColor` (`hsl(h 58% 46%)`, always chromatic). */
 export const NO_MANS_LAND_FILL = '#3f3f46';
 /** The border of a no-man's-land region (brighter than a plain unowned one). */
 export const NO_MANS_LAND_STROKE = 'rgba(255,255,255,0.25)';
 /** The faint neutral fill for a region no nation owns that was never released mid-game (a preset never assigned it). */
 export const UNOWNED_FILL = 'rgba(148,163,184,0.05)';
 /** The border of a plain unowned region. */
 export const UNOWNED_STROKE = 'rgba(255,255,255,0.14)';
 /** The border of an owned region (brighter than unowned). */
 export const OWNED_STROKE = 'rgba(255,255,255,0.30)';
 /** The hover-tooltip sub-line for a region with no owning nation. */
 export function unownedTooltipLabel(isNoMansLand: boolean): string {
  return isNoMansLand ? "No man's land" : 'No owner';
 }
 /**
 * The fill + border for one sub-region, given its RegionMap entry
 * (`undefined` = unowned) and whether its key is no man's land (released
 * mid-game, i.e. in `GameState.unowned`). Pure + shared; see the section
 * comment above for why the distinction is not encoded in the RegionMap.
 */
 export function regionFillStyle(
  owner: RegionOwner | undefined,
  isNoMansLand: boolean,
 ): { fill: string; stroke: string } {
  if (owner) return { fill: owner.color, stroke: OWNED_STROKE };
  return isNoMansLand
    ? { fill: NO_MANS_LAND_FILL, stroke: NO_MANS_LAND_STROKE }
    : { fill: UNOWNED_FILL, stroke: UNOWNED_STROKE };
 }
 /** Rebuild the full event list entry shape from a TurnEventSpec + turn/date. */
 export function makeEvent(
  spec: TurnEventSpec,
@@ -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 {
@@ -26,8 +30,10 @@ export const RELATION_STATUSES: RelationStatus[] = [
 ];
 /**
- * A single nation in the world. `territory` holds ISO_A3 codes; the map colors
+ * A single nation in the world. `territory` holds **region keys** (see
- * each of those regions with this nation's stable color (see protocol.nationColor).
+ * `public/region-keys.json`) — one per owned sub-region, so the choropleth can
 * color individual sub-regions, not whole countries (v0.19, #16 P1). The map
 * resolves each sub-region's owner by its region key (see protocol.mapFeatureOwner).
 */
 export interface Nation {
  id: string;
@@ -118,6 +124,34 @@ export interface GameState {
   * in src/App.tsx. Starts at 1 on game creation.
   */
  version: GameVersion;
  /**
   * (v0.22, #16 P3) Region keys that became **unowned** — "no man's land" —
   * during play: a region that was owned and was released to no owner by a
   * committed turn (the LLM narrates the cause in that turn's events). This is
   * deliberately distinct from the many regions a preset never assigns, which
   * are also unowned but were never *released* mid-game; only the keys in this
   * list render as the distinct visible no-man's-land grey (see
   * protocol.regionFillStyle). A region leaves the list when any nation
   * re-claims it (an ordinary `gain`). Always `[]` on a fresh game — no
   * man's land can only arise mid-game. Rows saved before v0.22 load with
   * this defaulted to `[]` (see server/db.ts).
   */
  unowned: string[];
  /**
   * (v0.23, #16 P4a) 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 — the id, its territory,
   * its relations, and the player pointer all stay valid) and removes it;
   * rejecting removes it without applying. Split/merge are declared for P4b
   * and are a safe no-op on confirm until then. 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[];
 }
 /**
@@ -177,6 +177,10 @@ 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);
  // 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());
@@ -401,6 +405,43 @@ export default function App() {
    [game, applyState],
  );
  // Apply a pending nation op the model proposed (confirm, with an optional
  // rename-name edit). 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 }) => {
      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 +548,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}
        />
      </>
@@ -551,12 +595,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 }) => void;
  onRejectNationOp: (index: number) => void;
  onHome: () => void;
 }
@@ -579,16 +627,31 @@ 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.
  const [viewingId, setViewingId] = useState(game.playerNationId);
  // When the dossier target was set by a map click, remember which sub-region
  // was clicked, for a small label in the dossier. The label shows only the
  // region's name. Cleared when the user picks a nation via the manual Inspect
  // select.
  const [selectedRegion, setSelectedRegion] = useState<{ name?: string } | null>(null);
  const focusNation = useCallback(
    (id: string, info?: { name?: string }) => {
      setViewingId(id);
      setSelectedRegion(info ?? null);
    },
    [],
  );
  const player = game.nations[game.playerNationId];
  const viewed = game.nations[viewingId] ?? player;
  const nations = Object.values(game.nations).sort((a, b) => a.name.localeCompare(b.name));
@@ -641,7 +704,8 @@ function GameScreen({
        playerNationId={game.playerNationId}
        nations={game.nations}
        presetId={game.presetId}
-        onFocusNation={setViewingId}
+        unowned={game.unowned ?? []}
        onFocusNation={focusNation}
      />
      {/* Pinned top bar: brand, turn + date, player nation, live status, Focus map.
@@ -747,7 +811,14 @@ function GameScreen({
          <div className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">
            Inspect
          </div>
-          <Select value={viewingId} onValueChange={setViewingId}>
+          <Select
            value={viewingId}
            onValueChange={(id) => {
              // A manual pick supersedes a map-click selection: clear the label.
              setViewingId(id);
              setSelectedRegion(null);
            }}
          >
            <SelectTrigger className="w-full" data-testid="inspect-select">
              <SelectValue />
            </SelectTrigger>
@@ -759,6 +830,11 @@ function GameScreen({
              ))}
            </SelectContent>
          </Select>
          {selectedRegion && (
            <div className="mt-1.5 truncate text-[11px] text-muted-foreground" data-testid="selected-region">
              Selected: {selectedRegion.name ?? 'region'}
            </div>
          )}
        </div>
        <NationPanel nation={viewed} nations={game.nations} isPlayer={viewingId === game.playerNationId} inWindow />
      </FloatingWindow>
@@ -810,12 +886,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>
@@ -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,10 @@ 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` optionally overrides a rename. */
  onConfirmNationOp: (index: number, edits?: { name?: string }) => 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 +76,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 +94,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 +123,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 +341,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}
@@ -0,0 +1,156 @@
 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` optionally overrides a rename's target name. */
  onConfirm: (index: number, edits?: { name?: string }) => 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 model's proposed name in an editable field (so the player
 * can tweak it before confirming); split and merge are declared but not yet
 * applied (P4b) — they can be dismissed but not confirmed.
 */
 export default function NationOpDialog({
  game,
  open,
  onOpenChange,
  opBusy,
  onConfirm,
  onReject,
 }: Props) {
  const ops = game.pendingNationOps;
  const name = (ref: string) => game.nations[ref]?.name ?? ref;
  // The player's edit to a rename's target name, keyed by pending-op index.
  // An unset entry means "use the model's proposed name" (`op.to`).
  const [edits, setEdits] = useState<Record<number, string>>({});
  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
            rename) 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 finalName = isRename ? (edits[i] ?? (op as RenameOp).to).trim() : '';
              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={() => onConfirm(i, finalName ? { name: finalName } : undefined)}
                          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="flex items-center justify-between gap-2">
                      <span className="text-[11px] text-muted-foreground">
                        {op.kind === 'split' ? 'Split' : 'Merge'} isn’t available yet — dismiss to ignore it.
                      </span>
                      <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" />
                        Dismiss
                      </Button>
                    </div>
                  )}
                </li>
              );
            })}
          </ul>
        )}
      </DialogContent>
    </Dialog>
  );
 }
@@ -1,8 +1,10 @@
 import { useEffect, useState } from 'react';
 import { Badge } from './ui/badge';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from './ui/card';
 import StatBar from './StatBar';
 import { nationColor } from '@shared/protocol';
 import { RELATION_COLORS } from '@/lib/colors';
 import { keyToName } from '@/lib/regions';
 import type { Nation, RelationStatus } from '@shared/types';
 /** Human labels for a diplomatic status (the raw value is kept in data-attrs). */
@@ -38,6 +40,23 @@ export default function NationPanel({ nation, nations, isPlayer, inWindow = fals
  const relations = Object.entries(nation.relations).sort(([a], [b]) => a.localeCompare(b));
  const regions = nation.territory;
  // Human region names for the territory chips (region key -> name), loaded once
  // (cached in @/lib/regions). A key with no known name falls back to the raw key.
  const [keyNames, setKeyNames] = useState<Record<string, string>>({});
  useEffect(() => {
    let cancelled = false;
    keyToName()
      .then((m) => {
        if (!cancelled) setKeyNames(m);
      })
      .catch(() => {
        /* names are cosmetic — a failed fetch just leaves the raw keys */
      });
    return () => {
      cancelled = true;
    };
  }, []);
  const identity = (
    <div className="flex items-center gap-3">
      <span
@@ -95,15 +114,20 @@ export default function NationPanel({ nation, nations, isPlayer, inWindow = fals
        </h3>
        {regions.length > 0 ? (
          <div className="flex flex-wrap gap-1.5">
-            {regions.map((code) => (
+            {regions.map((key) => {
              const label = keyNames[key] ?? key;
              return (
                <span
-                key={code}
+                  key={key}
-                className="rounded border px-1.5 py-0.5 text-xs tabular-nums"
+                  className="rounded border px-1.5 py-0.5 text-xs"
                  style={{ borderColor: `${color}66`, color, background: `${color}12` }}
                  title={key}
                  data-region-key={key}
                >
-                {code}
+                  {label}
                </span>
-            ))}
+              );
            })}
          </div>
        ) : (
          <p className="text-sm text-muted-foreground">No territory.</p>
@@ -8,11 +8,21 @@ import 'maplibre-gl/dist/maplibre-gl.css';
 // Point it at a Vite-emitted copy of the worker module so it loads in prod.
 import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?url';
 maplibregl.setWorkerUrl(workerUrl);
-import { regionOwner, type RegionMap, type RegionOwner } from '@shared/protocol';
+import {
  mapFeatureOwner,
  regionFillStyle,
  unownedTooltipLabel,
  type RegionMap,
  type RegionOwner,
 } from '@shared/protocol';
 import type { Nation } from '@shared/types';
 import { cn } from '@/lib/utils';
 import { idToKey } from '@/lib/regions';
-// Minimal GeoJSON types (avoids a hard @types/geojson dependency).
+// Minimal GeoJSON types (avoids a hard @types/geojson dependency). The choropleth
 // source is the sub-national `regions.geo.json`: each feature is a sub-region with
 // a top-level `id` of the form `<ISO_A3>-<nn>` (e.g. `FRA-03`) and
 // `properties = { name, parent }` where `parent` is the parent country's ISO_A3.
 interface GeoFeature {
  type: 'Feature';
  id?: string | number;
@@ -27,7 +37,7 @@ type GeoSource = maplibregl.GeoJSONSource;
 // Inline basemap style — a visible dark-navy background plus a subtle
 // OpenFreeMap shaded-relief raster so the ocean is never pure black and terrain
-// is faintly visible. The country choropleth (added in `ensureLayers`) is drawn
+// is faintly visible. The regional choropleth (added in `ensureLayers`) is drawn
 // on top and is the real star.
 //
 // Why inline instead of a remote style URL: the OFM "dark" style's vector tiles
@@ -61,7 +71,7 @@ const INLINE_STYLE: maplibregl.StyleSpecification = {
      type: 'raster',
      source: 'terrain',
      paint: {
-        'raster-opacity': 0.5,
+        'raster-opacity': 0.15,
        'raster-brightness-max': 0.8,
        'raster-fade-duration': 200,
      },
@@ -69,11 +79,11 @@ const INLINE_STYLE: maplibregl.StyleSpecification = {
  ],
 };
-const COUNTRIES_SOURCE = 'countries';
+const REGIONS_SOURCE = 'regions';
 const HOVER_SOURCE = 'hover';
 const FLASH_SOURCE = 'flash';
-const FILL_LAYER = 'countries-fill';
+const FILL_LAYER = 'regions-fill';
-const LINE_LAYER = 'countries-line';
+const LINE_LAYER = 'regions-line';
 const PLAYER_LINE = 'player-line';
 const FLASH_LINE = 'flash-line';
 const HOVER_FILL = 'hover-fill';
@@ -97,38 +107,66 @@ function cameraForPreset(presetId: string): { center: [number, number]; zoom: nu
 }
 /**
- * Stamp the current ownership + colors onto a clone of the base geo. Each region
+ * Stamp the current ownership + colors onto a clone of the sub-national base geo.
- * carries its owner's stable fill color, a subtle stroke, and a flag for the
+ * Ownership is at **region-key** granularity (v0.19, #16 P1): each sub-region has
- * player's own regions (rendered as a brighter, thicker border by a dedicated
+ * its own region key (from `public/region-keys.json`, looked up by the feature's
- * layer). Unknown owners fall back to a faint neutral fill — never an error.
+ * stable id) and the RegionMap is keyed by that region key, so a single
 * sub-region can change owner while its neighbours keep theirs. Each feature
 * therefore carries:
 *
- * Crucially, the base GeoJSON feature's top-level `id` (the ISO_A3 code) is
+ *  - `regionId`  – its own sub-region id (e.g. `FRA-03`), kept in a property that
- * stamped into `properties.regionId`, and the owner's id into `properties.ownerId`.
+ *                  survives into the features MapLibre hands back on click/hover
- * MapLibre repacks a GeoJSON source's top-level `id` into a numeric index when it
+ *                  (the top-level `id` is repacked into a numeric index, #6);
- * stores it, so a later click/hover event exposes that number on
+ *  - `regionKey` – the region key (e.g. `moselle-rygy`), the RegionMap key;
- * `e.features[i].id` — the top-level `id` is *not* a reliable lookup key at
+ *  - `fill`      – the owning nation's stable color (from `RegionMap[regionKey]`);
- * interaction time (the root cause of #6). `properties`, however, survive into the
+ *  - `owner`/`ownerId` – that nation's name/id (empty for an unowned region);
- * rendered features, so the interaction handlers resolve the owning nation from
+ *  - `stroke`    – a per-border alpha (owned brightest, no man's land next,
- * `properties.regionId` via the RegionMap (see `regionOwner`).
+ *                  plain-unowned faintest);
 *  - `isPlayer`  – 1 when the owning nation is the player (drives the amber
 *                  player-highlight border).
 *
 * Crucially, the owner lookup keys the RegionMap by the stamped
 * `properties.regionKey`, **never** by the sub-region id or the repacked
 * top-level `id` — the RegionMap has no `FRA-03` entries, only region keys.
 *
 * (v0.22, #16 P3) Unowned regions have two looks, decided here (the
 * RegionMap simply has no entry for them): a key in `unownedSet` — released to
 * no man's land mid-game (`GameState.unowned`) — gets the distinct visible grey
 * (`NO_MANS_LAND_FILL`); every other ownerless region keeps the faint
 * preset-unassigned look. Both come from the shared `regionFillStyle` contract.
 */
-function applyRegions(geo: FeatureCollection, regions: RegionMap, playerNationId: string): FeatureCollection {
+function applyRegions(
  geo: FeatureCollection,
  regions: RegionMap,
  playerNationId: string,
  idKey: Record<string, string>,
  unownedSet: ReadonlySet<string>,
 ): FeatureCollection {
  const out: FeatureCollection = JSON.parse(JSON.stringify(geo));
  for (const f of out.features) {
    f.properties = f.properties ?? {};
-    // The base GeoJSON `id` is the ISO_A3 code; keep it in a property that
+    // The sub-region's own id (e.g. `FRA-03`) — stamped into a property that
-    // survives into the features MapLibre hands back on click/hover.
+    // survives into the rendered features (the top-level `id` gets repacked).
-    const code = f.id == null ? '' : String(f.id);
+    const subId = f.id == null ? '' : String(f.id);
-    f.properties.regionId = code;
+    f.properties.regionId = subId;
-    const r = code ? regions[code] : undefined;
+    // Resolve this feature's **region key** from the manifest (id -> key) and
    // key the RegionMap by it — never the sub-region id or the repacked id.
    const key = idKey[subId] ?? '';
    f.properties.regionKey = key;
    const r = key ? regions[key] : undefined;
    if (r) {
-      f.properties.fill = r.color;
+      const style = regionFillStyle(r, false);
      f.properties.fill = style.fill;
      f.properties.stroke = style.stroke;
      f.properties.owner = r.owner;
      f.properties.ownerId = r.ownerId;
      f.properties.stroke = 'rgba(255,255,255,0.10)';
      f.properties.isPlayer = r.ownerId === playerNationId ? 1 : 0;
    } else {
-      f.properties.fill = 'rgba(148,163,184,0.05)';
+      // Ownerless: visible grey only for keys released mid-game (no man's
-      f.properties.stroke = 'rgba(255,255,255,0.06)';
+      // land); a preset that never assigned this sub-region stays faint.
      const style = regionFillStyle(undefined, key !== '' && unownedSet.has(key));
      f.properties.fill = style.fill;
      f.properties.stroke = style.stroke;
      f.properties.owner = '';
      f.properties.ownerId = '';
      f.properties.isPlayer = 0;
@@ -137,10 +175,23 @@ function applyRegions(geo: FeatureCollection, regions: RegionMap, playerNationId
  return out;
 }
-/** Build a FeatureCollection of just the features whose id is in `codes` (cloned). */
+/**
-function featuresByCodes(geo: FeatureCollection, codes: Iterable<string>): FeatureCollection {
+ * Build a FeatureCollection of just the sub-regions whose **region key** is in
-  const set = new Set(codes);
+ * `keys` (cloned). Used by the territory-change flash: a turn can change
-  const features = geo.features.filter((f) => f.id != null && set.has(String(f.id)));
+ * individual sub-regions (the RegionMap is region-keyed, v0.19 #16 P1), so each
 * changed region key lights up exactly the sub-region that owns it.
 */
 function featuresByRegionKeys(
  geo: FeatureCollection,
  keys: Iterable<string>,
  idKey: Record<string, string>,
 ): FeatureCollection {
  const set = new Set(keys);
  const features = geo.features.filter((f) => {
    const id = f.id == null ? '' : String(f.id);
    const key = idKey[id] ?? '';
    return key !== '' && set.has(key);
  });
  return { type: 'FeatureCollection', features: JSON.parse(JSON.stringify(features)) };
 }
@@ -152,14 +203,28 @@ function statRow(label: string, value?: number): string {
  return `<div class="hm-stat"><span class="hm-stat-k">${label}</span><span class="hm-stat-v">${Math.round(value)}</span></div>`;
 }
-/** Compact hover tooltip: country, its owner (color-chipped), and 1–2 key stats. */
+/**
-function hoverHtml(countryName: string, region?: RegionOwner, nation?: Nation): string {
+ * Compact hover tooltip: the sub-region's name, its **current owner**
 * (color-chipped), and 1–2 key stats. When the region's country has no owning
 * nation, a minimal card is shown instead; its sub-line says "No man's land"
 * for a region released mid-game (v0.22, #16 P3) and "No owner" for a region
 * no preset ever assigned. The static parent-country code
 * (`properties.parent`) is deliberately NOT printed here — it never updates
 * when ownership is transferred, so only the live owner chip (resolved from
 * the RegionMap) is shown.
 */
 function hoverHtml(
  subRegionName: string,
  region?: RegionOwner,
  nation?: Nation,
  noMansLand = false,
 ): string {
  if (!region || !nation) {
-    return `<div class="hm-popup"><div class="hm-popup-title">${esc(countryName || 'Unclaimed')}</div><div class="hm-popup-sub">No owner</div></div>`;
+    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('');
  return `<div class="hm-popup">
-    <div class="hm-popup-title">${esc(countryName || region.owner)}</div>
+    <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>
    <div class="hm-stats">${stats}</div>
  </div>`;
@@ -174,27 +239,52 @@ interface Props {
  presetId: string;
  className?: string;
  /**
-   * Called with a region's owning-nation id when that region is clicked, so the
+   * (v0.22, #16 P3) Region keys currently in no man's land (released
-   * dossier switches to that nation. Not called for unowned regions (the dossier
+   * mid-game — `GameState.unowned`). Such regions render the distinct visible
-   * keeps its current target). See the component doc for the full behavior.
+   * grey (vs the faint preset-unassigned look of every other ownerless
   * region) and their hover tooltip says "No man's land" instead of "No
   * owner".
   */
-  onFocusNation?: (id: string) => void;
+  unowned?: string[];
  /**
   * Called with a region's owning-nation id when a sub-region is clicked, so the
   * dossier switches to that nation. The optional `info` carries the clicked
   * sub-region's name, for a small "which region" label in the dossier. Not
   * called for unowned regions (the dossier keeps its current target). See the
   * component doc for the full behavior.
   */
  onFocusNation?: (id: string, info?: { name?: string }) => void;
 }
 /**
- * World basemap (MapLibre GL) + a country choropleth colored by the owning
+ * World basemap (MapLibre GL) + a **sub-national** choropleth. The map renders
- * nation. Rendered as a fixed, full-viewport background layer (z-0) behind the
+ * the finer `regions.geo.json` dataset: each country is subdivided into
- * floating HUD windows: a dark-navy basemap with subtle terrain, per-nation
+ * ~100–200 km sub-regions, drawn as a finer choropleth with thin internal border
- * stable fills (the choropleth is the star), thin borders, a brighter/thicker
+ * lines. Ownership is at **region-key** granularity (v0.19, #16 P1): each
- * border for the player, a hover tooltip (owner + key stats), a **click that
+ * sub-region has its own region key (from `public/region-keys.json`, looked up
- * switches the dossier to the region's owning nation** (no popup — see #7), a
+ * by the feature's stable id) and the RegionMap is keyed by that key, so a
- * transient flash on territory changes, and a per-scenario initial camera.
+ * single sub-region can change owner independently of its neighbours. Rendered
 * as a fixed, full-viewport background layer (z-0) behind the floating HUD
 * windows: a dark-navy basemap with subtle terrain, per-nation stable fills,
 * thin sub-region borders, a brighter/thicker amber border for the player's
 * regions, a hover tooltip (sub-region name + current owner + key stats), a
 * **click that switches the dossier to the sub-region's owning nation** (no
 * popup — see #7), a transient flash when a sub-region's owner changes, and a
 * per-scenario initial camera.
 *
- * Ownership for a hovered/clicked region is resolved from the authoritative
+ * Ownership for a hovered/clicked sub-region is resolved from the authoritative
- * RegionMap by the feature's stable ISO_A3 code in `properties.regionId`
+ * RegionMap by its stamped **region key** (`properties.regionKey`, via
- * (see `regionOwner` in @shared/protocol) — never from the feature's top-level
+ * `mapFeatureOwner` in @shared/protocol) — never from the feature's top-level
- * `id`, which MapLibre repacks into a numeric index at interaction time (#6).
+ * `id` (MapLibre repacks it into a numeric index at interaction time, #6) and
- * Unowned regions (no RegionMap entry) simply do not change the dossier.
+ * never from the raw sub-region id (not a RegionMap key). Unowned sub-regions
 * (no RegionMap entry for their key) simply do not change the dossier.
 *
 * (v0.22, #16 P3) An unowned region renders two distinct ways: a key in the
 * `unowned` prop (released to no man's land mid-game — `GameState.unowned`)
 * gets the distinct visible grey with a "No man's land" tooltip sub-line; every
 * other ownerless region (a preset never assigned it) keeps the faint look and
 * a plain "No owner" sub-line. The colors/labels come from the shared
 * `regionFillStyle` / `unownedTooltipLabel` contract in @shared/protocol.
 *
 * Zoom and pan are driven directly by the user (MapLibre wheel/trackpad + drag)
 * — no floating control and no external API.
@@ -205,21 +295,27 @@ export default function WorldMap({
  nations,
  presetId,
  className,
  unowned,
  onFocusNation,
 }: Props) {
  const containerRef = useRef<HTMLDivElement>(null);
  const mapRef = useRef<maplibregl.Map | null>(null);
  const baseGeoRef = useRef<FeatureCollection | null>(null);
  // The region-key manifest (feature id -> region key), loaded once; used to
  // stamp each feature's region key and to expand the flash to its sub-region.
  const idKeyRef = useRef<Record<string, string> | null>(null);
  // Latest props, so the mount effect's (re)establish closure always sees them.
  const regionsRef = useRef(regions);
  const nationsRef = useRef(nations);
  const playerRef = useRef(playerNationId);
  const presetRef = useRef(presetId);
  const unownedRef = useRef<Set<string>>(new Set(unowned ?? []));
  const onFocusNationRef = useRef(onFocusNation);
  regionsRef.current = regions;
  nationsRef.current = nations;
  playerRef.current = playerNationId;
  presetRef.current = presetId;
  unownedRef.current = new Set(unowned ?? []);
  onFocusNationRef.current = onFocusNation;
  // Diffing state for the transient territory-change flash (owned by this component
@@ -255,9 +351,9 @@ export default function WorldMap({
    const loadGeo = (): Promise<FeatureCollection> =>
      baseGeoRef.current
        ? Promise.resolve(baseGeoRef.current)
-        : fetch('/countries.geo.json')
+        : fetch('/regions.geo.json')
            .then((r) => {
-              if (!r.ok) throw new Error(`countries.geo.json → HTTP ${r.status}`);
+              if (!r.ok) throw new Error(`regions.geo.json → HTTP ${r.status}`);
              return r.json();
            })
            .then((g: FeatureCollection) => {
@@ -265,15 +361,28 @@ export default function WorldMap({
              return g;
            });
    // The region-key manifest (feature id -> region key), fetched once and
    // cached in a ref so both the paint path and the flash can resolve keys.
    const loadIdKey = (): Promise<Record<string, string>> =>
      idKeyRef.current
        ? Promise.resolve(idKeyRef.current)
        : idToKey().then((k) => {
            idKeyRef.current = k;
            return k;
          });
    const emptyFC = (): FeatureCollection => ({ type: 'FeatureCollection', features: [] });
    // Transient flash: pulse a bright outline over the changed regions, then fade
-    // to zero over a few seconds and self-clean. Idempotent per call.
+    // to zero over a few seconds and self-clean. Idempotent per call. `codes` are
    // region keys (a turn can change individual sub-regions, v0.19 #16 P1); each
    // lights up exactly the sub-region that owns that key.
    function animateFlash(codes: string[]) {
      const geo = baseGeoRef.current;
      const idKey = idKeyRef.current;
      const src = map.getSource(FLASH_SOURCE) as GeoSource | undefined;
-      if (!geo || !src || cancelled) return;
+      if (!geo || !idKey || !src || cancelled) return;
-      src.setData(featuresByCodes(geo, codes));
+      src.setData(featuresByRegionKeys(geo, codes, idKey));
      if (!map.getLayer(FLASH_LINE)) {
        // Defensive re-add (normally created by ensureLayers). Keep it beneath the
        // hover highlight when that layer exists; otherwise just append.
@@ -306,33 +415,38 @@ export default function WorldMap({
    }
    flashApiRef.current = animateFlash;
-    // The region a hovered/clicked feature belongs to is identified by its stable
+    // The sub-region a hovered/clicked feature belongs to is identified by its
-    // ISO_A3 code, read from `properties.regionId` (stamped by `applyRegions`).
+    // stable sub-region id in `properties.regionId` (stamped by `applyRegions`),
-    // We must NOT use the feature's top-level `id`: MapLibre repacks a GeoJSON
+    // and its **owner** is resolved from the authoritative RegionMap via the
-    // source's `id` into a numeric index when it stores the source, so the value
+    // feature's stamped `properties.regionKey` through
-    // exposed on `e.features[i].id` at interaction time is a number, never the
+    // `mapFeatureOwner` — never from the repacked top-level `id` (a numeric
-    // ISO_A3 — resolving the owner from it is the "no owner" bug (#6).
+    // index, #6) and never from the raw sub-region id (not a RegionMap key).
    const onHover = (e: maplibregl.MapLayerMouseEvent) => {
      const f = e.features?.[0];
      if (!f) return;
      const p = f.properties as { name?: string; regionId?: string };
-      const code = typeof p?.regionId === 'string' ? p.regionId : '';
+      const subId = typeof p?.regionId === 'string' ? p.regionId : '';
-      if (code && code !== lastHoverId) {
+      if (subId && subId !== lastHoverId) {
-        lastHoverId = code;
+        lastHoverId = subId;
        const geo = baseGeoRef.current;
-        // The base GeoJSON feature's top-level `id` IS the ISO_A3, so match on
+        // The base GeoJSON feature's top-level `id` IS the sub-region id, so
-        // that to recover the feature for the hover-highlight outline (the
+        // match on it to recover the exact feature for the hover-highlight
-        // feature MapLibre hands us has a repacked numeric `id` we can't use).
+        // outline (the feature MapLibre hands us has a repacked numeric `id`).
-        const feat = geo?.features.find((x) => x.id != null && String(x.id) === code);
+        const feat = geo?.features.find((x) => x.id != null && String(x.id) === subId);
        (map.getSource(HOVER_SOURCE) as GeoSource | undefined)?.setData(
          feat ? { type: 'FeatureCollection', features: [JSON.parse(JSON.stringify(feat))] } : emptyFC(),
        );
      }
-      const region = regionOwner(regionsRef.current, code);
+      const region = mapFeatureOwner(regionsRef.current, f);
      const nation = region ? nationsRef.current[region.ownerId] : undefined;
      // (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);
      hoverPopup
        .setLngLat(e.lngLat)
-        .setHTML(hoverHtml(p?.name ?? code, region, nation))
+        .setHTML(hoverHtml(p?.name ?? subId, region, nation, noMansLand))
        .addTo(map);
      map.getCanvas().style.cursor = 'pointer';
    };
@@ -345,17 +459,20 @@ export default function WorldMap({
    };
    // #7: a click does NOT open a popup — it switches the dossier to the region's
-    // owning nation. The owner is resolved from the stable ISO_A3 in
+    // owning nation, resolved from the feature's stamped `properties.regionKey`
-    // `properties.regionId` via the RegionMap (never the repacked top-level
+    // via the RegionMap (never the repacked top-level `f.id`, #6, and never the
-    // `f.id`, #6). A region with no owner in the RegionMap (unowned territory)
+    // raw sub-region id). A sub-region whose key has no owner leaves the current
-    // leaves the current dossier target unchanged — never a broken dossier.
+    // dossier target unchanged — never a broken dossier.
    const onClick = (e: maplibregl.MapLayerMouseEvent) => {
      const f = e.features?.[0];
      if (!f) return;
-      const p = f.properties as { regionId?: string };
+      const region = mapFeatureOwner(regionsRef.current, f);
-      const code = typeof p?.regionId === 'string' ? p.regionId : '';
+      if (!region?.ownerId) return;
-      const region = regionOwner(regionsRef.current, code);
+      // Carry the clicked sub-region's name so the dossier can show which region
-      if (region?.ownerId) onFocusNationRef.current?.(region.ownerId);
+      // was selected.
      const p = f.properties as { name?: string };
      const info = { name: typeof p?.name === 'string' ? p.name : undefined };
      onFocusNationRef.current?.(region.ownerId, info);
    };
    // Idempotent: (re)creates the sources + layers after any style (re)load and
@@ -363,16 +480,16 @@ export default function WorldMap({
    // automatically, so no setWorkerUrl is needed.)
    //
    // The three choropleth sources are created up front (empty until the base
-    // geo arrives) so the layer structure always exists; `paintCountries` then
+    // geo arrives) so the layer structure always exists; `paintRegions` then
-    // stamps ownership + colors onto the countries source. This makes it immune
+    // stamps ownership + colors onto the regions source. This makes it immune
    // to load-order races: if `ensureLayers` runs before the geo fetch
    // resolves, the data is applied the moment the fetch lands; if the geo
    // resolves first, `ensureLayers` uses it. No source is ever left stuck on
    // `emptyFC()` — `ensureLayers` is retried on every `styledata`, and the
    // regions effect re-paints whenever ownership changes.
    const ensureSources = () => {
-      if (!map.getSource(COUNTRIES_SOURCE)) {
+      if (!map.getSource(REGIONS_SOURCE)) {
-        map.addSource(COUNTRIES_SOURCE, { type: 'geojson', data: emptyFC() });
+        map.addSource(REGIONS_SOURCE, { type: 'geojson', data: emptyFC() });
      }
      if (!map.getSource(HOVER_SOURCE)) {
        map.addSource(HOVER_SOURCE, { type: 'geojson', data: emptyFC() });
@@ -382,44 +499,57 @@ export default function WorldMap({
      }
    };
-    // Stamp ownership + colors onto the countries source (no-op until geo loads).
+    // Stamp ownership + colors onto the regions source (no-op until both the
-    const paintCountries = () => {
+    // base geo and the region-key manifest are loaded).
    const paintRegions = () => {
      const geo = baseGeoRef.current;
-      const src = map.getSource(COUNTRIES_SOURCE) as GeoSource | undefined;
+      const idKey = idKeyRef.current;
-      if (!geo || !src) return;
+      const src = map.getSource(REGIONS_SOURCE) as GeoSource | undefined;
-      src.setData(applyRegions(geo, regionsRef.current, playerRef.current));
+      if (!geo || !idKey || !src) return;
      src.setData(applyRegions(geo, regionsRef.current, playerRef.current, idKey, unownedRef.current));
    };
    const ensureLayers = async () => {
      if (cancelled) return;
      ensureSources();
-      if (baseGeoRef.current) {
+      if (!baseGeoRef.current) {
        paintCountries();
      } else {
        try {
          await loadGeo();
        } catch (err) {
-          console.error('failed to load countries geojson', err);
+          console.error('failed to load regions geojson', err);
        }
      }
      if (!idKeyRef.current) {
        try {
          await loadIdKey();
        } catch (err) {
          console.error('failed to load region keys', err);
        }
      }
      if (cancelled) return;
-        paintCountries();
+      paintRegions();
      }
      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.
        // Each sub-region carries its own owning nation's color (v0.19 #16 P1),
        // so the fill traces region-key ownership, not country borders.
        map.addLayer({
          id: FILL_LAYER,
          type: 'fill',
-          source: COUNTRIES_SOURCE,
+          source: REGIONS_SOURCE,
-          paint: { 'fill-color': ['get', 'fill'], 'fill-opacity': 0.85 },
+          paint: { 'fill-color': ['get', 'fill'], 'fill-opacity': 1.0 },
        });
      }
      if (!map.getLayer(LINE_LAYER)) {
        // Thin internal borders: every sub-region outline at a light weight so
        // the subdivision reads within each country's uniform fill. The per-
        // feature `stroke` alpha keeps owned borders a touch brighter than
        // unowned ones (the v0.10 treatment, thinned for the finer grid).
        map.addLayer({
          id: LINE_LAYER,
          type: 'line',
-          source: COUNTRIES_SOURCE,
+          source: REGIONS_SOURCE,
-          paint: { 'line-color': ['get', 'stroke'], 'line-width': 0.7, 'line-opacity': 0.95 },
+          paint: { 'line-color': ['get', 'stroke'], 'line-width': 0.75, 'line-opacity': 0.95 },
        });
      }
      // NOTE: layers are added in bottom→top order (each appends on top). The
@@ -430,7 +560,7 @@ export default function WorldMap({
        map.addLayer({
          id: PLAYER_LINE,
          type: 'line',
-          source: COUNTRIES_SOURCE,
+          source: REGIONS_SOURCE,
          filter: ['==', ['get', 'isPlayer'], 1],
          paint: { 'line-color': '#f59e0b', 'line-width': 2.2, 'line-opacity': 0.95 },
        });
@@ -482,30 +612,39 @@ export default function WorldMap({
    };
  }, []);
-  // Re-color the choropleth whenever ownership changes, and flash any regions
+  // Re-color the choropleth whenever ownership changes, and flash each
-  // whose owner changed since the last update (transient, self-cleaning).
+  // sub-region whose owner changed since the last update (a transient,
  // self-cleaning pulse). The diff is over the region-keyed RegionMap (v0.19
  // #16 P1); `animateFlash` lights up exactly the sub-region for each changed
  // key. Re-runs when the no-man's-land set changes too (v0.22 #16 P3) so a
  // release/re-claim repaints the grey even if the RegionMap diff alone
  // wouldn't catch it.
  useEffect(() => {
    const map = mapRef.current;
    const geo = baseGeoRef.current;
    const idKey = idKeyRef.current;
    const cur = regions;
    const prev = prevRegionsRef.current;
    prevRegionsRef.current = cur;
    const wasPrimed = primedRef.current;
    if (Object.keys(cur).length > 0) primedRef.current = true;
    const unownedSet = new Set(unowned ?? []);
-    if (map && geo) {
+    if (map && geo && idKey) {
-      const src = map.getSource(COUNTRIES_SOURCE) as GeoSource | undefined;
+      const src = map.getSource(REGIONS_SOURCE) as GeoSource | undefined;
-      if (src) void src.setData(applyRegions(geo, cur, playerNationId));
+      if (src) void src.setData(applyRegions(geo, cur, playerNationId, idKey, unownedSet));
    }
-    if (wasPrimed && prev) {
+    if (wasPrimed && prev && idKey) {
      const changed = new Set<string>();
-      for (const code of new Set([...Object.keys(prev), ...Object.keys(cur)])) {
+      for (const key of new Set([...Object.keys(prev), ...Object.keys(cur)])) {
-        if ((prev[code]?.ownerId ?? '') !== (cur[code]?.ownerId ?? '')) changed.add(code);
+        if ((prev[key]?.ownerId ?? '') !== (cur[key]?.ownerId ?? '')) changed.add(key);
      }
      // A release (owned → unowned) and a re-claim (unowned → owned) both show
      // up as ownerId changes above, so they flash like any other transfer.
      if (changed.size > 0) flashApiRef.current?.([...changed]);
    }
-  }, [regions, playerNationId]);
+  }, [regions, playerNationId, unowned]);
  // Full-viewport, edge-to-edge background layer. `position: fixed` is set
  // inline because MapLibre's own stylesheet sets `.maplibregl-map` to
@@ -6,9 +6,11 @@ import type {
  AddActionResponse,
  AddDiplomacyResponse,
  AdvisorResponse,
  ConfirmNationOpResponse,
  CreateGameResponse,
  DeleteGameResponse,
  GameSummary,
  RejectNationOpResponse,
  RemoveQueueItemResponse,
  TurnResponse,
 } from '@shared/protocol';
@@ -60,6 +62,21 @@ export const api = {
      method: 'POST',
      body: JSON.stringify({ index }),
    }),
  // (v0.23, #16 P4a) Confirm a pending nation-op proposal by its index in
  // `game.pendingNationOps` (a rename takes effect; `edits.name` overrides the
  // proposed name). Fast, non-LLM — no turn advance. Returns the updated game.
  confirmNationOp: (id: string, index: number, edits?: { name?: string }) =>
    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`, {
@@ -0,0 +1,46 @@
 // Client-side region-key data access. Fetches the two static JSON files served
 // from public/ and builds the lookups the region-level UI needs:
 //   - idToKey():   feature id -> region key (to stamp each map feature + resolve owner)
 //   - keyToName(): region key -> human name (to show region names in the dossier)
 // Each is fetched once and cached (Promise singleton) so WorldMap and NationPanel
 // share a single fetch. Same-origin relative URLs (proxy/Traefik safe) — never a
 // hardcoded origin.
 type GeoLike = {
  features?: Array<{ id?: string | number; properties?: { name?: string } }>;
 };
 let idKeyPromise: Promise<Record<string, string>> | null = null;
 let keyNamePromise: Promise<Record<string, string>> | null = null;
 async function fetchJson<T>(url: string): Promise<T> {
  const r = await fetch(url);
  if (!r.ok) throw new Error(`${url} → HTTP ${r.status}`);
  return (await r.json()) as T;
 }
 /** feature id (from regions.geo.json) -> region key (from region-keys.json). */
 export function idToKey(): Promise<Record<string, string>> {
  idKeyPromise ??= fetchJson<Record<string, string>>('/region-keys.json');
  return idKeyPromise;
 }
 /**
 * region key -> human region name. Built by joining region-keys.json (id -> key)
 * with regions.geo.json (id -> properties.name). A key with no known name is
 * simply absent (callers fall back to the raw key).
 */
 export function keyToName(): Promise<Record<string, string>> {
  keyNamePromise ??= Promise.all([idToKey(), fetchJson<GeoLike>('/regions.geo.json')]).then(
    ([keys, geo]) => {
      const out: Record<string, string> = {};
      for (const f of geo.features ?? []) {
        const id = f.id == null ? '' : String(f.id);
        const key = keys[id];
        const name = f.properties?.name;
        if (key && typeof name === 'string') out[key] = name;
      }
      return out;
    },
  );
  return keyNamePromise;
 }
@@ -20,5 +20,5 @@
      "@/*": ["./src/*"]
    }
  },
-  "include": ["src", "server", "shared", "e2e", "vite.config.ts"]
+  "include": ["src", "server", "shared", "e2e", "scripts", "vite.config.ts"]
 }
@@ -13,7 +13,7 @@ export default defineConfig({
  },
  test: {
    environment: 'node',
-    include: ['server/**/*.test.ts'],
+    include: ['server/**/*.test.ts', 'scripts/**/*.test.ts'],
    testTimeout: 20000,
    hookTimeout: 20000,
  },
Author	SHA1	Message	Date
kamilkrzywda	f72a59bf5e	Merge pull request 'feat: nation-op rename — LLM proposes, player confirms (v0.23.0, #16 P4a)' (#38 ) from feat/16-p4a-rename into master CI / build + unit + e2e (push) Successful in 2m27s Details	2026-10-14 15:03:41 +02:00
kamilkrzywda	6ebe21591e	chore: bump to v0.23.0 (nation-op rename, #16 P4a) + CHANGELOG CI / build + unit + e2e (pull_request) Successful in 2m26s Details	2026-10-14 13:00:33 +00:00
kamilkrzywda	9f230606c4	feat: nation-op rename review — confirm/reject routes, client dialog, AGENTS.md (P4a, #16 ) Wire the 'LLM proposes, player confirms' nation-rename flow end to end: - server: POST /api/games/:id/nation-op/confirm\|reject (404/400, version-bumped SSE state) - client: confirmNationOp/rejectNationOp api helpers + NationOpDialog (editable rename) wired into the Action panel via a 'Nation proposals' trigger - AGENTS.md: document the pendingNationOps mechanism, routes, nationRef resolution, stub-never-proposes	2026-10-14 13:00:28 +00:00
kamilkrzywda	e9fa267fd0	Nation-op proposals (P4a, #16 ): protocol types, pendingNationOps state, engine propose/resolve (stage 1) - shared/protocol.ts: RenameOp/SplitOp/MergeOp + NationOp union; TurnResult.nationOps (required); ConfirmNationOp/RejectNationOp request+response types - shared/types.ts: GameState.pendingNationOps (type-only import of NationOp — no runtime cycle) - server/engine.ts: validateNationOps parser wired into validateTurnResult; isMeaningful counts proposals; applyTurnResult appends to the surviving pending list (never applies); runTurn fallback literal; system prompt gains the nationOps JSON field + rename proposal rule (both modes); new resolveNationRef/applyNationOp/confirmNationOp/rejectNationOp (id-first then unique case-insensitive name; rename changes Nation.name only; split/merge no-op until P4b; index validation returns null for 400) - server/db.ts: legacy rows load with pendingNationOps defaulted to [] - server/index.ts: fresh games start with pendingNationOps: [] - server/stub.ts: deterministicTurn returns nationOps: [] (the stub never proposes — unit-only coverage, matching P3) - tests: fixture updates (engine/db/map/regions) + new suites for resolveNationRef, validateNationOps, proposal lifecycle, confirm/reject (151 tests total)	2026-10-14 12:47:58 +00:00
kamilkrzywda	edaa8f55d1	Merge pull request 'No man's land: region release + re-claim + distinct grey map rendering (v0.22.0) — part 3 of #16 ' (#37 ) from feat/16-p3-no-mans-land into master CI / build + unit + e2e (push) Successful in 2m48s Details	2026-10-14 14:09:22 +02:00
kamilkrzywda	6c52e10898	Bump to v0.22.0 (no man's land, #16 P3) + AGENTS.md/CHANGELOG CI / build + unit + e2e (pull_request) Successful in 1m33s Details	2026-10-14 12:04:03 +00:00
kamilkrzywda	764f24fc55	No man's land: TurnResult.unowned + release/re-claim in applyTurnResult + distinct grey map rendering (#16 P3) - shared/protocol.ts: TurnResult.unowned (keys released this turn) + the map presentation contract (regionFillStyle / unownedTooltipLabel, hue-less grey) - shared/types.ts: required GameState.unowned (cumulative mid-game releases; [] at init, distinct from preset-unassigned regions) - server/engine.ts: applyTurnResult applies releases first (sole-owner only, never fabricating no man's land from unassigned keys), then claims against the post-release snapshot (gain on an ownerless key = re-claim); lone release is isMeaningful; prompts + user payload carry the unowned field - server/stub.ts: unchanged behavior (never releases; e2e stays stable) - server/db.ts: legacy rows load with unowned defaulted to [] - server/index.ts: create-game sets []; jump reference table includes released keys so the model can name them for re-claim - WorldMap/App: unowned prop -> visible grey + 'No man's land' tooltip - unit tests: 105 -> 127 (release/re-claim suites, presentation contract, legacy-row normalization)	2026-10-14 12:04:03 +00:00
kamilkrzywda	cb426273a9	Merge pull request 'Region transfers along real borders + getNeighbours LLM tool (v0.21.0) — part 2 of #16 ' (#36 ) from feat/16-p2-region-transfers into master CI / build + unit + e2e (push) Successful in 1m31s Details	2026-10-14 12:51:30 +02:00
kamilkrzywda	0b999f1448	Bump to v0.21.0 (region transfers + getNeighbours tool, #16 P2) CI / build + unit + e2e (pull_request) Successful in 1m34s Details	2026-10-14 10:48:28 +00:00
kamilkrzywda	5abbebc58f	LLM getNeighbours tool + contiguous region transfers (Stage 2 of #16 P2) - llm.ts: LlmClient.chatWithTools — bounded OpenAI function-calling loop (default 6 tool rounds, then one forced no-tools request); shares the retry/backoff/reasoning-effort machinery with chat(); tools are only added to the request body when non-empty, so plain chat() bodies and their tests are unchanged; a tool-call response is a success (never a truncation); malformed tool arguments become an error tool-message. - engine.ts: GET_NEIGHBOURS_TOOL + makeNeighboursExecutor (degrades unknown tools/args/keys without throwing); playerFrontier (sorted, deduped, other-nation-owned only); buildSystemPrompt gains a tool variant (contiguity rules, frontier hint) used only when the tool is actually sent; buildUserPrompt emits a frontier field whenever a resolver is given; runTurn takes getNeighbours and uses chatWithTools when both the resolver and the client's capability are present, falling back to plain chat() otherwise. - applyTurnResult: snapshot-first sole-ownership algorithm — a region key transfers only with exactly one claimant and exactly one previous owner (different from the gainer); double claims and pre-existing double ownership are left untouched; lone losses are no-ops; every key has 0 or 2+ -> 1 owner post-turn, never orphaned or duplicated. - stub.ts: deterministic one-region contiguous conquest per turn from the prompt's frontier field (bypasses the tool loop; empty frontier -> no transfer, all existing assertions stay stable). - regions.ts: optional region-adjacency.json load; hasAdjacency() and neighboursOf(keys) (union, deduped, queried excluded, sorted). - index.ts: jump route passes the adjacency resolver when loaded. - tests: chatWithTools protocol (echo, executor args, bounded rounds, malformed args, retry), tool-path runTurn wiring + fallback, playerFrontier, executor, applyTurnResult invariants, neighboursOf/ hasAdjacency (105 unit tests, 14 e2e — all green).	2026-10-14 10:37:25 +00:00
kamilkrzywda	f53f9072f4	Build region-adjacency manifest (Stage 1 of #16 P2) Generate public/region-adjacency.json: regionKey -> neighbourKeys, built from regions.geo.json (bbox proximity reject + @turf/boolean-intersects arbitration; symmetric, deduped, no self-refs). Deterministic + idempotent. This is the data backing the LLM's getNeighbours tool (Stage 2) which lets it move contiguous frontier regions instead of whole countries.	2026-10-14 10:05:06 +00:00
kamilkrzywda	6f14a4e4c0	Merge pull request 'Fix: region loader finds the manifest in prod (dist/) — completes P1 region ownership (v0.20.0)' (#35 ) from fix/16-p1-region-keys-prod into master CI / build + unit + e2e (push) Successful in 1m36s Details Merge v0.20.0: region loader prod-path fix (completes #16 P1)	2026-10-14 11:35:22 +02:00
kamilkrzywda	6949739956	Bump to v0.20.0 (region loader prod-path fix) CI / build + unit + e2e (pull_request) Successful in 1m31s Details	2026-10-14 09:32:29 +00:00
kamilkrzywda	cf7d3cb122	Fix region loader to find the manifest in prod (dist/) — dev-vs-prod path (v0.20.0, completes #16 P1) v0.19.0's region-level ownership did not activate in the production image: server/regions.ts loadRegions only looked in public/, but the Docker image keeps only dist/ (Vite copies public/* -> dist/ at build), so the loader found nothing and expandCountriesToKeys degraded to a no-op — fresh games kept raw ISO_A3 codes instead of region keys (the client's own /region-keys.json fetch still worked, since the client is served from dist/). loadRegions now probes public/ (dev) then dist/ (prod, == clientDir) and uses the first directory holding both files. A new test covers the prod-only (dist/), dev (public/), and empty-root (no data) layouts.	2026-10-14 09:32:29 +00:00
kamilkrzywda	99ee93f6da	Merge pull request 'Region-level ownership foundation (Part 1 of #16 ) (v0.19.0)' (#34 ) from feat/16-p1-region-ownership into master CI / build + unit + e2e (push) Successful in 1m35s Details Merge v0.19.0: region-level ownership (Part 1 of #16)	2026-10-14 11:18:12 +02:00
kamilkrzywda	b9ac79c57f	Bump to v0.19.0: region-level ownership (Part 1 of #16 ) CI / build + unit + e2e (pull_request) Successful in 1m36s Details Version 0.19.0 + changelog. Breaking: pre-v0.19 saved games are dropped (territory now holds region keys, not ISO_A3 codes) — deploy wipes the history-data volume.	2026-10-14 09:15:33 +00:00
kamilkrzywda	1c64aa1da4	Tests: region-key contract (map rewrite + regions loader + engine) (v0.19 P1 of #16 ) - map.test.ts: rewrite the fixture for region keys; the #6 regression guard now proves the owner resolves via properties.regionKey while the repacked numeric feature.id and the sub-region regionId do not. - regions.test.ts (new): the loader sees 1,796 valid keys; FRA expands to its 42 sub-region keys (all valid, all labelled '… (FRA)'); allTerritoryKeys unions correctly; and with no data it degrades to the raw input. - engine.test.ts: buildUserPrompt includes a regions table only when provided; applyTurnResult with a validKeys set applies real keys and ignores bogus ones, and without one applies all (the legacy/unit path).	2026-10-14 09:14:24 +00:00
kamilkrzywda	29927bae34	Flip the client to region-key resolution + region names in the dossier (v0.19 P1 of #16 ) - src/lib/regions.ts (new): cached, turf-free same-origin fetches of /region-keys.json (feature id -> key) and /regions.geo.json (id -> name) so WorldMap and NationPanel share one fetch each. - WorldMap.tsx: stamps each feature's properties.regionKey (from the manifest, by its stable id) and resolves owner / flash / hover / click from that key via the shared mapFeatureOwner; the per-region flash lights the exact sub-region whose owner changed; click carries only the sub-region name. - NationPanel.tsx: territory chips show the region's human name (falling back to the raw key) with the key in the title / data-attr. - App.tsx: the selected-region dossier label drops the now-unused parent code.	2026-10-14 09:14:17 +00:00
kamilkrzywda	325bdc5255	Flip ownership to region keys: shared contract + server (v0.19 P1 of #16 ) The single source of truth now keys ownership by region key (one per owned sub-region) instead of a parent-country ISO_A3: - shared/types.ts, shared/protocol.ts: TerritoryChange / RegionMap / regionOwner doc flips; mapFeatureOwner now reads the feature's stamped properties.regionKey (never the repacked numeric feature.id, nor the sub-region id — the #6 guard). - server/regions.ts (new, turf-free): loads region-keys.json + regions.geo.json once at boot; expands a nation's ISO_A3 list to its sub-regions' keys, builds the LLM 'regions' reference table (key -> "name (parent)"), and exposes the set of valid keys. Degrades gracefully when the files are missing. - server/engine.ts: buildSystemPrompt instructs the model to use region keys; buildUserPrompt gains an optional regionReference table; applyTurnResult gains an optional validKeys set so hallucinated keys are ignored. - server/index.ts: loads region data at boot; expands each nation's country list to region keys at game creation; the jump route passes the reference + valid keys through runTurn. The stub is unchanged (it emits an empty, region-key-conformant territoryChanges).	2026-10-14 09:14:10 +00:00
kamilkrzywda	2cfa2f78f9	Add region-keys.test.ts: 1,796 unique <slug>-<4char> keys, geo-id join (v0.19 P1 of #16 )	2026-10-14 08:32:36 +00:00
kamilkrzywda	2b84c34f41	Add region-key manifest (build:region-keys) + public/region-keys.json (v0.19 P1 of #16 ) Deterministic <name-slug>-<4char> key per sub-region: name via NFKD strip + fold table (ə ø ð đ œ ł) + a-z0-9 collapse; 4-char from FNV-1a of the stable feature id, salted on within-slug collision so all 1,796 keys are unique. Builtins only (no @turf). Idempotent (byte-identical on re-run).	2026-10-14 08:32:36 +00:00
kamilkrzywda	9c29779572	Merge pull request 'Region hover/selected shows current owner, not stale parent-country code (v0.18.0)' (#33 ) from fix/region-display-owner into master CI / build + unit + e2e (push) Successful in 2m32s Details	2026-10-13 21:15:45 +02:00
kamilkrzywda	3cd8dcecfa	Stop printing the static parent-country code in the region hover tooltip and dossier label (v0.18.0) CI / build + unit + e2e (pull_request) Successful in 2m34s Details	2026-10-13 18:58:43 +00:00
kamilkrzywda	acb4f0800f	Merge pull request 'Fill no-one's-land gaps between merged sub-regions (v0.17.0)' (#32 ) from feat/fill-gaps into master CI / build + unit + e2e (push) Successful in 1m39s Details	2026-10-13 17:48:17 +02:00
kamilkrzywda	b1081eefde	Fill no-one's-land gaps between merged sub-regions (v0.17.0) CI / build + unit + e2e (pull_request) Successful in 2m19s Details Part of #16	2026-10-13 15:18:31 +00:00
kamilkrzywda	e92bf47d7d	Merge pull request 'Smooth jagged sub-national region boundaries (v0.16.0)' (#30 ) from feat/smooth-regions into master CI / build + unit + e2e (push) Successful in 2m21s Details	2026-10-13 11:53:58 +02:00
kamilkrzywda	f1cc4fbc10	Smooth jagged sub-national region boundaries (v0.16.0) CI / build + unit + e2e (pull_request) Successful in 2m18s Details Part of #16	2026-10-13 09:42:44 +00:00
kamilkrzywda	97702940cd	Merge pull request 'Clean up holes/gaps in sub-national regions (v0.15.0)' (#29 ) from feat/cleanup-regions into master CI / build + unit + e2e (push) Successful in 2m21s Details	2026-10-12 16:00:44 +02:00
kamilkrzywda	8eedc37e05	Clean up holes/gaps in sub-national regions (v0.15.0) CI / build + unit + e2e (pull_request) Successful in 2m15s Details Part of #16	2026-10-12 13:51:47 +00:00
kamilkrzywda	69782aad69	Merge pull request 'Coarsen sub-national regions to a ~100km floor (v0.14.0)' (#28 ) from feat/coarsen-regions into master CI / build + unit + e2e (push) Successful in 2m19s Details	2026-10-12 11:59:39 +02:00
kamilkrzywda	7bf11fa5b9	Coarsen sub-national regions to ~100km floor (v0.14.0) CI / build + unit + e2e (pull_request) Successful in 1m47s Details Part of #16	2026-10-12 09:52:52 +00:00
kamilkrzywda	db46e1a5ec	Merge pull request 'Use real historical sub-national regions instead of the geometric grid (v0.13.0)' (#27 ) from feat/historical-regions into master CI / build + unit + e2e (push) Successful in 1m44s Details	2026-10-12 10:43:09 +02:00
kamilkrzywda	99188b5b15	Replace geometric sub-regions with real historical regions (v0.13.0) CI / build + unit + e2e (pull_request) Successful in 2m34s Details Part of #16	2026-10-12 08:33:07 +00:00
kamilkrzywda	0ebdb36daa	Merge pull request 'Switch map to sub-national regions (v0.12.0)' (#26 ) from feat/sub-national-map into master CI / build + unit + e2e (push) Successful in 1m20s Details	2026-10-12 03:13:22 +02:00
kamilkrzywda	06cdbf3d81	Switch map to sub-national regions (v0.12.0) CI / build + unit + e2e (pull_request) Successful in 1m18s Details Part of #16	2026-10-12 01:07:33 +00:00
kamilkrzywda	344b5b4a5e	Merge pull request 'Add sub-national regional dataset + generator (v0.11.0)' (#25 ) from feat/sub-national-regions into master CI / build + unit + e2e (push) Successful in 1m21s Details	2026-10-12 02:47:21 +02:00
kamilkrzywda	d5285ce28d	Add sub-national regional dataset + generator (v0.11.0) CI / build + unit + e2e (pull_request) Successful in 1m21s Details Fixes #16	2026-10-12 00:33:11 +00:00
kamilkrzywda	8252b665b5	Merge pull request 'Fix map coastal-water bleed-through and border lines (v0.10.0)' (#24 ) from feat/map-border-style into master CI / build + unit + e2e (push) Successful in 1m15s Details	2026-10-11 23:32:46 +02:00
kamilkrzywda	7d50cba061	Fix map coastal-water bleed-through and border lines (v0.10.0) CI / build + unit + e2e (pull_request) Successful in 2m13s Details Fixes #2	2026-10-11 21:26:25 +00:00