Merge pull request 'v0.27.0 (#44): LLM-placed named map point markers' (#45) from feat/44-llm-map-pointers into master

2026-10-15 00:40:52 +02:00
parent aa1bd3c5aa a129c2ab81
commit 7f26bc2b3b
19 changed files with 10437 additions and 45 deletions
@@ -56,7 +56,7 @@ history/
 ├── eslint.config.js        # flat config (ESLint 9)
 ├── tsconfig.json           # strict; aliases @/ → src/, @shared/ → shared/
 ├── vite.config.ts          # dev server + proxy /api,/sse → :4321; @ / @shared aliases
-├── vitest.config.ts        # unit tests (server/**/*.test.ts + scripts/**/*.test.ts; 168 tests)
+├── vitest.config.ts        # unit tests (server/**/*.test.ts + scripts/**/*.test.ts; 189 tests)
 ├── playwright.config.ts    # deterministic e2e (webServer runs npm run dev, LLM_STUB=1)
 ├── index.html
 ├── presets/                # 5 scenario JSON files + index.json (manifest)
@@ -64,12 +64,13 @@ history/
 │   ├── countries.geo.json  # 177 countries, id=ISO_A3 (input to the region generator)
 │   ├── regions.geo.json    # 1,800 sub-regions, id=<ISO_A3>-<nn>, parent=ISO_A3 (the choropleth)
 │   ├── region-keys.json    # feature id -> region key, 1,800 entries (the ownership/LLM address space, #16 P1)
-│   └── region-adjacency.json # region key -> bordering region keys, 1,800 entries (the getNeighbours data, #16 P2)
+│   ├── region-adjacency.json # region key -> bordering region keys, 1,800 entries (the getNeighbours data, #16 P2)
 │   └── region-centroids.json # region key -> {lat,lon,spread} anchor for map markers, 1,800 entries (#44)
 ├── scripts/                # the geo/manifest data pipeline — .mjs (turf allowed HERE only;
 │   │                       #   never imported by .ts): generate → coarsen → cleanup → smooth →
 │   │                       #   fill-gaps → split-arkhangel → split-arkhangel-band → build-region-keys
-│   │                       #   → build-region-adjacency
+│   │                       #   → build-region-adjacency → build-region-centroids
-│   └── *.test.ts           # turf-free vitest tests pinning the dataset + both manifests
+│   └── *.test.ts           # turf-free vitest tests pinning the dataset + the manifests
 ├── shared/                 # NO runtime deps — the single source of truth
 │   ├── types.ts            #   domain types (Nation, GameState, RoundItem, Preset, …)
 │   └── protocol.ts         #   LLM TurnResult schema (incl. `unowned`, v0.22 #16 P3, and
@@ -115,13 +116,13 @@ history/
 | `npm run dev` | Express on :4321 (tsx watch) + Vite on :5173 (proxies `/api`,`/sse`) concurrently |
 | `npm run build` | `vite build` (client → `dist/`) then `tsup server/index.ts` → `server/dist/index.js` |
 | `npm start` | run the compiled server (`node server/dist/index.js`) on :4321 |
-| `npm test` | vitest unit tests (`server/` + `scripts/`; 168 tests) |
+| `npm test` | vitest unit tests (`server/` + `scripts/`; 189 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 split:regions` | (re)apply the #31 Arkhangel'sk split (`RU-ARK` → mainland + `RU-ARK-NE` + `RU-ARK-SZ`) — idempotent no-op once applied |
 | `npm run split:regions:band` | (re)apply the #41 Arctic-coast-band split (`RU-ARK` mainland's 28-part lat ≥ 68 band → `RU-PEO` + `RU-YAM`) — idempotent no-op once applied |
-| `npm run build:region-keys` / `build:region-adjacency` | (re)generate the `public/region-keys.json` / `region-adjacency.json` manifests — deterministic + idempotent (byte-identical re-run) |
+| `npm run build:region-keys` / `build:region-adjacency` / `build:region-centroids` | (re)generate the `public/region-keys.json` / `region-adjacency.json` / `region-centroids.json` manifests — deterministic + idempotent (byte-identical re-run) |
 | `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.
@@ -249,6 +250,42 @@ history/
  three op shapes as a proposal queue (at most 1–2 per turn, each narrated in events). The stub
  never proposes a nation op (`nationOps: []`), so this path is covered by unit tests only
  (`server/engine.test.ts`).
 - **Map markers (v0.27, #44) — LLM-placed named points, region-anchored, canvas-icon rendered.**
  The LLM can place named **point markers** on the map each turn: eight `MarkerType`s
  (`city, factory, army, port, capital, fleet, rocket, gathering`; a **capital** is at most one
  per nation, a **gathering** a political/social mass event that can enable a non-military
  takeover). `TurnResult.markers = { add: MarkerSpec[]; remove: string[] }` (both required,
  default `[]`; `MarkerSpec = { type, name, regionKey }`). A marker's stable `id` is the FNV-1a
  32-bit hash of `` `${type}\u0000${name}\u0000${regionKey}` `` rendered as four lowercase
  base-26 characters (mirroring the region-key scheme) — so a **re-add is idempotent** and a
  **remove is unambiguous** (by id). `GameState.markers: MapMarker[]` is required (`[]` at game
  creation; a legacy SQLite row without the field loads as `[]` — additive, never wipes).
  `applyTurnResult` handles markers **after** territory claims: (1) remove by id (absent id →
  no-op); (2) **recompute every surviving marker's `ownerNationId` from the final post-claim
  ownership** — a marker always follows its region (a captured region follows its new owner; a
  region released to no man's land, or a key with 0 or 2+ owners, becomes `null`); (3) add — each
  new spec is placed at its region's centroid (from `public/region-centroids.json`, injected via
  the optional `centroidOf` param on `applyTurnResult`) plus a deterministic per-axis jitter
  (`spread ≈ 0.1 × the largest part's smallest bbox dimension`, so multiple markers of one region
  scatter instead of stacking), owned by the region's post-turn owner, stamped with the acting
  turn. Adds are **dropped, never thrown**, when the region key is unknown or has no centroid,
  when the id already exists, or beyond the hard cap `MAX_MARKERS = 400`. The system prompt
  documents the field + types + placement rules; `buildUserPrompt` carries the current markers
  (as `MarkerInfo[]`) so the model can reference their ids in `remove`; a marker add/remove makes
  a turn "meaningful". **Rendering is canvas-generated per-type ICON images, NOT text labels**
  (`src/components/WorldMap.tsx`): every external glyph/font endpoint is a dead 404 (OpenFreeMap's
  `fonts/{stack}/{range}.pbf` and `demotiles.maplibre.org/font/…`) and the OFM dark basemap only
  renders because it is **raster** (labels baked into the tiles) — there is no working vector
  font, so markers are drawn as self-contained, offline, deterministic per-type icons
  (`drawMarkerIcon`: distinct shape per type, filled with the type color, outlined for legibility),
  registered as named `ImageData` images that survive `styledata`. The marker **name shows in the
  hover tooltip** (not a persistent on-map label), and **clicking a marker focuses its owning
  nation's dossier**. There are **no separate marker event handlers** — MapLibre's per-layer event
  delegates fire independently (no `stopPropagation`), so the region hover/click handlers instead
  `queryRenderedFeatures` the marker layer under the cursor and act on the marker when present.
  The **stub is marker-free** (`markers: { add: [], remove: [] }`) — e2e (CI, `LLM_STUB=1`) is
  unaffected and the marker path is unit-tested only (`server/engine.test.ts`,
  `scripts/region-centroids.test.ts`, `server/regions.test.ts`, `server/db.test.ts`).
 - **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
@@ -369,7 +406,8 @@ history/
  (works on `node:22-slim`/glibc). It's the sole `--external` in the tsup server bundle.
 - The `dist/` client is committed to the build output only; the `public/` data files
  (`regions.geo.json` — the choropleth — `region-keys.json` + `region-adjacency.json` — the
-  ownership/adjacency manifests — and `countries.geo.json`) are copied into `dist/` by Vite at
+  ownership/adjacency manifests — `region-centroids.json` — the marker anchors (#44) — and
   `countries.geo.json`) are copied into `dist/` by Vite at
  build time, so the prod image serves them from `dist/` (no separate copy). The server's region
  loader (`server/regions.ts`) probes `public/` then `dist/` for the manifest pair, because the
  Docker image keeps only `dist/` (the v0.20 fix — before it, region-level ownership silently
@@ -2,6 +2,18 @@
 All notable changes to **History** are listed here, newest first.
 ## v0.27.0 — 2026-10-14 22:34
 - **#44: the LLM can place named point markers on the map.** The model may now place up to a handful of named *point markers* per turn (a capital, city, factory complex, army deployment, port, fleet concentration, rocket launch site, or a political **gathering**), each anchored to a region key, persisted per game, and rendered on the choropleth as a MapLibre symbol layer.
  - **Types (`shared/types.ts` + `shared/protocol.ts`).** Eight `MarkerType`s — `city, factory, army, port, capital, fleet, rocket, gathering` — with a shared `MARKER_TYPE_INFO` map (display label + color + glyph). A `MapMarker = { id, type, name, regionKey, lat, lon, ownerNationId, placedTurn }`; `GameState.markers: MapMarker[]` is **required** (`[]` at game creation, and a legacy SQLite row without the field loads as `[]` — additive, never wipes existing markers). `TurnResult.markers = { add: MarkerSpec[]; remove: string[] }` (both required, default `[]`); `MarkerSpec = { type, name, regionKey }`.
  - **Stable ids (`shared/protocol.ts`).** A marker's `id` is the FNV-1a 32-bit hash of `` `${type}\u0000${name}\u0000${regionKey}` `` rendered as four lowercase base-26 characters (mirroring the region-key scheme). This makes a **re-add idempotent** (the same type+name+region never creates a second marker) and a **remove unambiguous** (by id).
  - **Centroid data (`public/region-centroids.json`, new).** ~1,800 entries keyed identically to `region-keys.json`, each `{ lat, lon, spread }`: the anchor is the **centroid of the region's largest-area part** (a single representative point, not an average across disjoint parts), and `spread` ≈ **0.1 × that part's smallest bbox dimension** (in degrees). A new idempotent pipeline stage `scripts/build-region-centroids.mjs` (`npm run build:region-centroids`) regenerates it deterministically (byte-identical re-run, sha256-pinned by the test). The engine uses the centroid as the marker's base position and the `spread` to jitter multiple markers of one region around it (a deterministic per-axis FNV-1a-derived offset, so markers scatter instead of stacking).
  - **Engine (`server/engine.ts`).** `applyTurnResult` processes markers **after** territory claims, in three steps: (1) remove by id (a listed-but-absent id is a no-op); (2) **recompute every surviving marker's `ownerNationId` from the final post-claim ownership** — a captured region follows its new owner, a region released to no man's land (or a key with 0 or 2+ owners) becomes `null` (a marker always follows its region); (3) add — each new spec is placed at its region's centroid (injected via a new optional `centroidOf` param) plus the per-axis jitter, owned by the region's post-turn owner, stamped with the acting turn. Adds are dropped (never thrown) when their region key is unknown / has no centroid, when the id already exists (idempotent re-add), or beyond the hard cap `MAX_MARKERS = 400` (later adds dropped). The system prompt documents the field, the eight types, and the placement rules; `buildUserPrompt` carries the current markers (as `MarkerInfo[]`) so the model can reference their stable ids in `remove`; `isMeaningful` treats a marker add/remove as a real world change.
  - **Client (`src/components/WorldMap.tsx`).** A second GeoJSON source + a symbol layer sits above the choropleth. **Deliberate deviation from the original "name as a text label" design:** every external glyph endpoint is a dead 404 (OpenFreeMap's `fonts/{stack}/{range}.pbf` and `demotiles.maplibre.org/font/…`), and the OFM dark basemap only renders at all because it is **raster** (labels baked into the PNG tiles) — there is no working vector font. So markers are drawn as **self-contained, offline, canvas-generated per-type icons** (`drawMarkerIcon`: a distinct shape per type — circle / rounded-square / triangle / diamond / star / center-dotted circles / up-arrow — filled with the type color, outlined for legibility on the dark basemap), registered as named `ImageData` images that survive `styledata`. The marker **name is shown in the hover tooltip** (region name + owner chip + marker name) instead of a persistent on-map label, and **clicking a marker focuses its owning nation's dossier** (a marker's owner is its region's owner). There are no separate marker event handlers: MapLibre's per-layer event delegates fire independently (no `stopPropagation`), so the region hover/click handlers instead `queryRenderedFeatures` the marker layer under the cursor and act on the marker when present.
  - **Stub (`server/stub.ts`) stays marker-free** — it returns `markers: { add: [], remove: [] }` — so the e2e suite (CI, `LLM_STUB=1`) is unaffected and fully deterministic; the full marker path is covered by unit tests only.
 - **Tests (168 → 189).** New `scripts/region-centroids.test.ts` (1,800 entries, key-set match, finite/world-bounds, each centroid inside its feature's bbox via turf-free coordinate iteration, spot-checked anchors, byte-identical re-run determinism); `server/regions.test.ts` (`hasCentroids`/`centroidOf` in dev + prod-`dist/` layouts, graceful degradation when absent); `server/db.test.ts` (legacy row → `markers: []`); and an `engine.test.ts` marker suite (valid add → id/position/owner/placedTurn, idempotent re-add, region-validity/centroid drops, the 400 cap, remove by id / no-op, owner-follows-region incl. release→null and re-claim, `buildUserPrompt`/system-prompt contract, `validateMarkerOps` raw cleaner, and the `runTurn` centroid wiring).
 - **Verification.** Typecheck, lint, **189 unit tests**, and the production build all pass (the build copies `region-centroids.json` into `dist/` like the other manifests, so it works in the prod container layout).
 - **Deploy:** manual `docker compose up -d --build` on the host — **no `down -v`** (markers are additive; legacy games load with `markers: []`).
 ## v0.26.0 — 2026-10-14 19:24
 - **#41: the `RU-ARK` mainland's Arctic-coast band is re-coarsened into two new regions** — a pure re-partition of the existing polygon parts: no new geometry, no coordinate change (the feature union stays byte-identical). After #31 the mainland `RU-ARK` was a 33-part MultiPolygon; its 28-part band (parts whose centroid lat ≥ 68 — the Arctic-coast strip) is now split into:
  - `RU-PEO` — Pechora (13 parts, ~37,678 km²) → new region key `pechora-qwhs`. The southwestern band (around the Pechora delta / Nenets border).
@@ -1,6 +1,6 @@
 {
  "name": "history",
-  "version": "0.26.0",
+  "version": "0.27.0",
  "private": true,
  "type": "module",
  "description": "AI-driven alternate-history simulator — the LLM is the world engine (Pax Historia style).",
@@ -18,6 +18,7 @@
    "split:regions:band": "node scripts/split-arkhangel-band.mjs",
    "build:region-keys": "node scripts/build-region-keys.mjs",
    "build:region-adjacency": "node scripts/build-region-adjacency.mjs",
    "build:region-centroids": "node scripts/build-region-centroids.mjs",
    "typecheck": "tsc --noEmit",
    "lint": "eslint .",
    "e2e": "playwright test"
@@ -0,0 +1,132 @@
 /**
 * scripts/build-region-centroids.mjs — build the precomputed region-centroid
 * manifest: `public/region-centroids.json` = `{ "<regionKey>": { "lat": <number>, "lon": <number>, "spread": <number> }, ... }`.
 *
 * For every sub-region (region key, see `public/region-keys.json`) this records
 * the point the LLM's map markers (v0.27, #44) will be anchored to: the
 * **centroid of the region's largest-area part** (a MultiPolygon's biggest
 * island/lake-piece rather than an area-weighted average of all parts), plus
 * a `spread` value ≈ 0.1 × the smallest bbox dimension of that part (in
 * degrees) — the engine scatters markers of one region within ±(spread/2)
 * around the centroid using a deterministic per-marker offset, so several
 * markers of the same region do not stack on one pixel.
 *
 * Method — plain turf on the pre-generated geo file (turf is allowed in .mjs
 * scripts; it is deliberately kept OUT of the TS typecheck program, see the
 * v0.17 note). For each feature we (1) split a MultiPolygon into its parts
 * (a plain Polygon is its own single part), (2) pick the part with the
 * greatest `@turf/area`, (3) take `@turf/centroid` of that part and
 * `@turf/bbox` of that part, and (4) round everything to 6 decimal places
 * (≈ 0.1 m at this scale — far below the map's visual precision).
 *
 * Output contract (asserted by scripts/region-centroids.test.ts):
 *   - one entry for **every** region key, keyed identically to
 *     `public/region-keys.json` (same key set, 1,800 entries);
 *   - each centroid lies inside its region's (largest part's) bbox;
 *   - `spread` is a non-negative number of degrees (0 for degenerate parts);
 *   - values are rounded to at most 6 decimal places.
 *
 * Deterministic + idempotent: the input files are fixed, turf is a pure
 * geometric computation, the output keeps the geo file's (stable) feature
 * order and rounds to fixed precision — so a re-run rewrites a byte-identical
 * file (the test re-runs this script and compares bytes).
 *
 * Usage: `node scripts/build-region-centroids.mjs`  (or `npm run build:region-centroids`).
 */
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import area from '@turf/area';
 import bbox from '@turf/bbox';
 import centroid from '@turf/centroid';
 import { feature } from '@turf/helpers';
 const here = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(here, '..');
 const round6 = (v) => Math.round(v * 1e6) / 1e6;
 // --- load the geo + region-key manifest (plain parse; keys join feature->key) --
 const geo = JSON.parse(readFileSync(path.join(root, 'public', 'regions.geo.json'), 'utf8'));
 const idToKey = JSON.parse(readFileSync(path.join(root, 'public', 'region-keys.json'), 'utf8'));
 /**
 * The polygon parts of a geometry: a MultiPolygon's individual polygons, a
 * plain Polygon as its own single part, anything else as an empty list (the
 * caller falls back to the whole-feature centroid).
 */
 function partsOf(geometry) {
  if (geometry?.type === 'MultiPolygon') return geometry.coordinates ?? [];
  if (geometry?.type === 'Polygon') return [geometry.coordinates];
  return [];
 }
 const manifest = {};
 let skipped = 0;
 for (const f of geo.features ?? []) {
  const id = f.id == null ? '' : String(f.id);
  const key = idToKey[id];
  if (!key) continue; // a geo feature with no manifest entry is skipped
  const parts = partsOf(f.geometry);
  if (parts.length === 0) {
    // Degenerate geometry (a point/line region): anchor at the feature's own
    // centroid. Can't happen with the current 1,800-polygon dataset, but the
    // fallback keeps the manifest complete if the generator ever changes.
    skipped += 1;
    const c = centroid(feature(f.geometry));
    const b = bbox(feature(f.geometry));
    manifest[key] = {
      lat: round6(c.geometry.coordinates[1]),
      lon: round6(c.geometry.coordinates[0]),
      spread: round6(Math.min(b[2] - b[0], b[3] - b[1]) * 0.1),
    };
    continue;
  }
  // Pick the part with the greatest area (km²) and anchor to IT, so a
  // multi-part region's markers cluster on its main mass, not between parts.
  let best = 0;
  let bestArea = -1;
  for (let i = 0; i < parts.length; i++) {
    const a = area(feature({ type: 'Polygon', coordinates: parts[i] }));
    if (a > bestArea) {
      bestArea = a;
      best = i;
    }
  }
  const part = feature({ type: 'Polygon', coordinates: parts[best] });
  const c = centroid(part);
  const b = bbox(part);
  manifest[key] = {
    lat: round6(c.geometry.coordinates[1]),
    lon: round6(c.geometry.coordinates[0]),
    spread: round6(Math.min(b[2] - b[0], b[3] - b[1]) * 0.1),
  };
 }
 // --- hard assertions (the test re-checks these against the committed file) ---
 const expectedKeys = Object.values(idToKey);
 if (Object.keys(manifest).length !== expectedKeys.length) {
  throw new Error(
    `expected ${expectedKeys.length} centroid entries (one per region key), got ${Object.keys(manifest).length}`,
  );
 }
 for (const k of expectedKeys) {
  if (!(k in manifest)) throw new Error(`missing centroid for region key ${JSON.stringify(k)}`);
 }
 for (const [k, v] of Object.entries(manifest)) {
  if (!Number.isFinite(v.lat) || !Number.isFinite(v.lon) || !Number.isFinite(v.spread)) {
    throw new Error(`non-finite centroid for ${k}: ${JSON.stringify(v)}`);
  }
  if (v.spread < 0) throw new Error(`negative spread for ${k}: ${v.spread}`);
 }
 // --- write idempotently (stable order = insertion order = geo file order) ---
 writeFileSync(path.join(root, 'public', 'region-centroids.json'), JSON.stringify(manifest, null, 2) + '\n');
 // --- summary ------------------------------------------------------------------
 const spreads = Object.values(manifest).map((v) => v.spread);
 console.log(
  `[build-region-centroids] wrote public/region-centroids.json — ${Object.keys(manifest).length} region keys` +
    (skipped ? ` (${skipped} non-polygon fallbacks)` : '') +
    `, spread min/max ${Math.min(...spreads)} / ${Math.max(...spreads)} deg`,
 );
@@ -0,0 +1,158 @@
 /**
 * scripts/region-centroids.test.ts — validation for the committed
 * `public/region-centroids.json` (built by `scripts/build-region-centroids.mjs`).
 *
 * The manifest maps each region key to the anchor point a map marker (v0.27,
 * #44) is placed at: the centroid of the region's largest-area part, plus a
 * `spread` (≈ 0.1 × that part's smallest bbox dimension, in degrees) that the
 * engine uses to scatter multiple markers of one region around the centroid.
 * It is a load-bearing data artifact for the marker placement path — this test
 * pins its contract.
 *
 * Deliberately dependency-free: it reads the JSON with plain `fs`/`JSON.parse`
 * and computes bbox checks by iterating coordinates directly (no `@turf`/
 * geojson types, which would pull `@types/geojson` into the tsc program and
 * break `WorldMap.tsx` — see the v0.17 note). Mirrors the style of
 * `scripts/region-adjacency.test.ts`; the determinism test re-runs the (turf
 * `.mjs`) builder and compares bytes, matching that the builder is idempotent.
 */
 import { readFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 const here = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(here, '..');
 function readJson(rel: string): Record<string, unknown> {
  return JSON.parse(readFileSync(path.join(root, rel), 'utf8'));
 }
 interface CentroidEntry {
  lat: number;
  lon: number;
  spread: number;
 }
 /** All [lon, lat] coordinate pairs of a Polygon / MultiPolygon geometry. */
 function allCoords(geometry: { type?: string; coordinates?: unknown }): Array<[number, number]> {
  const c = geometry?.coordinates as
    | Array<Array<[number, number]>>
    | Array<Array<Array<[number, number]>>>
    | undefined;
  if (!c) return [];
  if (geometry?.type === 'Polygon') {
    const rings = c as Array<Array<[number, number]>>;
    const out: Array<[number, number]> = [];
    for (const ring of rings) for (const p of ring) out.push(p);
    return out;
  }
  if (geometry?.type === 'MultiPolygon') {
    const polys = c as Array<Array<Array<[number, number]>>>;
    const out: Array<[number, number]> = [];
    for (const poly of polys) for (const ring of poly) for (const p of ring) out.push(p);
    return out;
  }
  return [];
 }
 /** The bounding box [minLon, minLat, maxLon, maxLat] of a geometry. */
 function bboxOf(geometry: { type?: string; coordinates?: unknown }): [number, number, number, number] {
  let minLon = Infinity;
  let minLat = Infinity;
  let maxLon = -Infinity;
  let maxLat = -Infinity;
  for (const [x, y] of allCoords(geometry)) {
    if (x < minLon) minLon = x;
    if (y < minLat) minLat = y;
    if (x > maxLon) maxLon = x;
    if (y > maxLat) maxLat = y;
  }
  return [minLon, minLat, maxLon, maxLat];
 }
 describe('region-centroids.json', () => {
  const centroids = readJson('public/region-centroids.json') as Record<string, CentroidEntry>;
  const manifest = readJson('public/region-keys.json') as Record<string, string>;
  const geo = readJson('public/regions.geo.json') as {
    features?: Array<{ id?: string | number; geometry?: { type?: string; coordinates?: unknown } }>;
  };
  const keys = Object.values(manifest);
  // featureId -> feature, then regionKey -> feature (via the key manifest).
  const featureByKey = new Map<string, { geometry?: { type?: string; coordinates?: unknown } }>();
  for (const f of geo.features ?? []) {
    const key = manifest[String(f.id)];
    if (key) featureByKey.set(key, f);
  }
  it('has exactly one entry per region key (same key set as region-keys.json)', () => {
    expect(new Set(Object.keys(centroids))).toEqual(new Set(keys));
    expect(Object.keys(centroids)).toHaveLength(1800);
  });
  it('every entry is a finite { lat, lon, spread } with a non-negative spread, in world bounds', () => {
    for (const [k, v] of Object.entries(centroids)) {
      expect(Number.isFinite(v.lat), `non-finite lat for ${k}`).toBe(true);
      expect(Number.isFinite(v.lon), `non-finite lon for ${k}`).toBe(true);
      expect(Number.isFinite(v.spread), `non-finite spread for ${k}`).toBe(true);
      expect(v.spread >= 0, `negative spread for ${k}`).toBe(true);
      expect(v.lat >= -90 && v.lat <= 90, `lat out of range for ${k}: ${v.lat}`).toBe(true);
      expect(v.lon >= -180 && v.lon <= 180, `lon out of range for ${k}: ${v.lon}`).toBe(true);
    }
  });
  it('each centroid lies inside its region feature bounding box', () => {
    // The recorded point is the centroid of the LARGEST part, which is a subset
    // of the whole feature, so it must fall inside the feature's overall bbox.
    let checked = 0;
    for (const [key, c] of Object.entries(centroids)) {
      const feat = featureByKey.get(key);
      if (!feat?.geometry) continue;
      const [minLon, minLat, maxLon, maxLat] = bboxOf(feat.geometry);
      const eps = 1e-4; // allow for the 6-dp rounding in the builder
      expect(
        c.lat >= minLat - eps && c.lat <= maxLat + eps,
        `lat ${c.lat} outside bbox [${minLat}, ${maxLat}] for ${key}`,
      ).toBe(true);
      expect(
        c.lon >= minLon - eps && c.lon <= maxLon + eps,
        `lon ${c.lon} outside bbox [${minLon}, ${maxLon}] for ${key}`,
      ).toBe(true);
      checked++;
    }
    expect(checked).toBe(1800);
  });
  it('spot-checks a couple of well-known anchors land in the right place', () => {
    // Region keys are sub-national (states/provinces), so we spot-check a few
    // whose geography is unambiguous. A gross error in the centroid method
    // (e.g. averaging across all parts of a large multi-part region, or a
    // lon/lat swap) would land one of these far off.
    const near = (k: string, lat: number, lon: number, tol: number) => {
      const c = centroids[k];
      expect(c, `missing centroid for ${k}`).toBeDefined();
      expect(Math.abs(c!.lat - lat)).toBeLessThan(tol);
      expect(Math.abs(c!.lon - lon)).toBeLessThan(tol);
    };
    near('ain-lqtt', 46.16, 4.8, 0.5); // FR-01 — eastern France
    near('california-kikh', 36.87, -120.67, 0.7); // US-CA — central California
    near('alberta-zopq', 52.09, -116.94, 1.5); // CA-AB — Alberta (large province)
    near('acre-ekzw', -9.49, -71.11, 0.5); // BR-AC — western Brazil
  });
  it('is deterministic: re-running the builder rewrites a byte-identical file', () => {
    const file = path.join(root, 'public', 'region-centroids.json');
    const before = readFileSync(file, 'utf8');
    // The builder is cwd-independent (it resolves the repo root from its own
    // location) and idempotent: same input files + pure turf + fixed rounding
    // + stable insertion order → identical bytes.
    execFileSync(process.execPath, [path.join(root, 'scripts', 'build-region-centroids.mjs')], {
      cwd: root,
      stdio: 'pipe',
    });
    const after = readFileSync(file, 'utf8');
    expect(after).toBe(before);
  });
 });
@@ -25,6 +25,7 @@ function makeState(id: string): GameState {
    version: 1,
    unowned: [],
    pendingNationOps: [],
    markers: [],
  };
 }
@@ -97,6 +98,17 @@ describe('openDb', () => {
    db.close();
  });
  it('(v0.27 #44) a legacy row saved before the markers field existed loads with it defaulted to []', () => {
    const db = openDb(':memory:');
    const legacy = makeState('legacy');
    delete (legacy as { markers?: unknown[] }).markers; // a pre-v0.27 save (field absent)
    db.save(legacy);
    const loaded = db.load('legacy');
    expect(loaded).not.toBeNull();
    expect(loaded!.markers).toEqual([]);
    db.close();
  });
  it('delete removes a game by id and reports absence otherwise', () => {
    const db = openDb(':memory:');
    db.save(makeState('a'));
@@ -46,6 +46,8 @@ export function openDb(filePath: string): Db {
        // (v0.23, #16 P4a) Same for pending nation-op proposals: a legacy game
        // has none awaiting confirm/reject.
        if (state.pendingNationOps === undefined) state.pendingNationOps = [];
        // (v0.27, #44) Same for map markers: a legacy game has none placed.
        if (state.markers === undefined) state.markers = [];
        return state;
      } catch {
        return null;
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
-import type { GameState, Preset, RoundItem } from '../shared/types';
+import type { GameState, MarkerType, Preset, RoundItem } from '../shared/types';
-import { makeEvent, type NationOp, type TurnResult } from '../shared/protocol';
+import { makeEvent, markerId, MAX_MARKERS, type MarkerSpec, type NationOp, type TurnResult } from '../shared/protocol';
 import type { LlmClient, ToolDefinition, WireMessage } from './llm';
 import { makeStubLlmClient } from './stub';
 import {
@@ -21,6 +21,7 @@ import {
  removeRoundItem,
  resolveNationRef,
  runTurn,
  validateMarkerOps,
  validateNationOps,
  validateTurnResult,
 } from './engine';
@@ -87,6 +88,7 @@ function baseState(): GameState {
    version: 1,
    unowned: [],
    pendingNationOps: [],
    markers: [],
  };
 }
@@ -524,7 +526,7 @@ describe('validateNationOps (v0.23 #16 P4a)', () => {
      relations: [],
      territoryChanges: [],
      unowned: [],
-      nationOps: [{ kind: 'rename', nationRef: 'France', to: 'French Republic' }],
+      nationOps: [{ kind: 'rename', nationRef: 'France', to: 'French Republic' }], markers: { add: [], remove: [] },
    });
    expect(withOps).not.toBeNull();
    expect(withOps!.nationOps).toEqual([{ kind: 'rename', nationRef: 'France', to: 'French Republic' }]);
@@ -545,7 +547,7 @@ describe('applyTurnResult (nation-op proposals, v0.23 #16 P4a)', () => {
      relations: [],
      territoryChanges: [],
      unowned: [],
-      nationOps: [{ kind: 'rename', nationRef: 'de', to: 'Reich' }],
+      nationOps: [{ kind: 'rename', nationRef: 'de', to: 'Reich' }], markers: { add: [], remove: [] },
    });
    expect(next.nations.de.name).toBe('DE'); // still the old name
    expect(next.pendingNationOps).toEqual([{ kind: 'rename', nationRef: 'de', to: 'Reich' }]);
@@ -565,7 +567,7 @@ describe('applyTurnResult (nation-op proposals, v0.23 #16 P4a)', () => {
      relations: [],
      territoryChanges: [],
      unowned: [],
-      nationOps: [{ kind: 'rename', nationRef: 'us', to: 'USA' }], // new proposal this turn
+      nationOps: [{ kind: 'rename', nationRef: 'us', to: 'USA' }], markers: { add: [], remove: [] }, // new proposal this turn
    });
    expect(next.pendingNationOps).toEqual([
      { kind: 'rename', nationRef: 'de', to: 'Reich' }, // the old one survived
@@ -583,7 +585,7 @@ describe('applyTurnResult (nation-op proposals, v0.23 #16 P4a)', () => {
      relations: [],
      territoryChanges: [],
      unowned: [],
-      nationOps: [{ kind: 'rename', nationRef: 'de', to: 'Reich' }],
+      nationOps: [{ kind: 'rename', nationRef: 'de', to: 'Reich' }], markers: { add: [], remove: [] },
    });
    expect(next.pendingNationOps).toEqual([{ kind: 'rename', nationRef: 'de', to: 'Reich' }]);
  });
@@ -1039,7 +1041,7 @@ describe('applyTurnResult', () => {
      relations: [],
      territoryChanges: [],
      unowned: [],
-      nationOps: [],
+      nationOps: [], markers: { add: [], remove: [] },
    };
    applyTurnResult(state, result);
    expect(JSON.stringify(state)).toBe(snapshot);
@@ -1055,7 +1057,7 @@ describe('applyTurnResult', () => {
      relations: [],
      territoryChanges: [],
      unowned: [],
-      nationOps: [],
+      nationOps: [], markers: { add: [], remove: [] },
    };
    const next = applyTurnResult(state, result);
    expect(next.pending).toEqual([]);
@@ -1077,7 +1079,7 @@ describe('applyTurnResult', () => {
      // 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: [],
+      nationOps: [], markers: { add: [], remove: [] },
    };
    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
@@ -1102,7 +1104,7 @@ describe('applyTurnResult', () => {
      // released (not in state.unowned), so it does not enter GameState.unowned.
      territoryChanges: [{ nation: 'de', gain: ['POL', 'wales-bbbb'], lose: [] }],
      unowned: [],
-      nationOps: [],
+      nationOps: [], markers: { add: [], remove: [] },
    };
    const next = applyTurnResult(state, result); // no validKeys -> nothing filtered
    expect(next.nations.de.territory).toContain('wales-bbbb');
@@ -1119,7 +1121,7 @@ describe('applyTurnResult (sole-ownership invariants, v0.21 #16 P2)', () => {
    stateChanges: [],
    relations: [],
    unowned: [],
-    nationOps: [],
+    nationOps: [], markers: { add: [], remove: [] },
  };
  it('a double claim (two different gainers, one key) is rejected: the key stays with its original owner', () => {
@@ -1208,7 +1210,7 @@ describe('applyTurnResult (no man\'s land, v0.22 #16 P3)', () => {
    relations: [],
    territoryChanges: [],
    unowned: [],
-    nationOps: [],
+    nationOps: [], markers: { add: [], remove: [] },
  };
  it('a release removes the key from its sole owner and marks it in GameState.unowned', () => {
@@ -1323,7 +1325,7 @@ describe('applyTurnResult (no man\'s land, v0.22 #16 P3)', () => {
  it('a lone release is meaningful (it survives the retry/nudge path)', () => {
    expect(
-      isMeaningful({ date: 'x', events: [], stateChanges: [], relations: [], territoryChanges: [], unowned: ['GBR'], nationOps: [] }),
+      isMeaningful({ date: 'x', events: [], stateChanges: [], relations: [], territoryChanges: [], unowned: ['GBR'], nationOps: [], markers: { add: [], remove: [] } }),
    ).toBe(true);
  });
@@ -1630,9 +1632,9 @@ describe('buildSystemPrompt (tool mode, v0.21 #16 P2)', () => {
 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: [], unowned: [], nationOps: [] })).toBe(true);
+    expect(isMeaningful({ date: 'x', events: [{ nation: 'uk', type: 'military', title: 't', text: 'b', outcome: 'neutral' }], stateChanges: [], relations: [], territoryChanges: [], unowned: [], nationOps: [], markers: { add: [], remove: [] } })).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: [{ nation: 'uk', stat: 'military', op: 'set', value: 5 }], relations: [], territoryChanges: [], unowned: [], nationOps: [], markers: { add: [], remove: [] } })).toBe(true);
-    expect(isMeaningful({ date: 'x', events: [], stateChanges: [], relations: [], territoryChanges: [], unowned: [], nationOps: [] })).toBe(false);
+    expect(isMeaningful({ date: 'x', events: [], stateChanges: [], relations: [], territoryChanges: [], unowned: [], nationOps: [], markers: { add: [], remove: [] } })).toBe(false);
  });
  it('(v0.23 #16 P4a) a turn that only proposes a nation-op is meaningful (it survives the retry/nudge path)', () => {
@@ -1644,8 +1646,265 @@ describe('isMeaningful', () => {
        relations: [],
        territoryChanges: [],
        unowned: [],
-        nationOps: [{ kind: 'rename', nationRef: 'de', to: 'Reich' }],
+        nationOps: [{ kind: 'rename', nationRef: 'de', to: 'Reich' }], markers: { add: [], remove: [] },
      }),
    ).toBe(true);
  });
  it('(v0.27 #44) a turn that only adds a marker is meaningful (it survives the retry/nudge path)', () => {
    expect(
      isMeaningful({
        date: 'x',
        events: [],
        stateChanges: [],
        relations: [],
        territoryChanges: [],
        unowned: [],
        nationOps: [],
        markers: { add: [{ type: 'city', name: 'Lyon', regionKey: 'rhone-rhne' }], remove: [] },
      }),
    ).toBe(true);
  });
 });
 describe('markers (point placement, v0.27 #44)', () => {
  // a deterministic centroid for one region key, undefined for everything else
  const centroidOf = (key: string) =>
    key === 'moselle-rygy' ? { lat: 48, lon: 6, spread: 1 } : undefined;
  // build a MarkerSpec from a (possibly invalid, for the guard tests) type string
  const mk = (type: string, name: string, regionKey: string): MarkerSpec =>
    ({ type: type as MarkerType, name, regionKey });
  it('adds a valid marker with a stable id, a jittered position within the spread, the region owner, and the placed turn', () => {
    const state = baseState();
    state.turn = 4; // placedTurn should equal the resolved turn
    state.nations.uk.territory = ['GBR', 'moselle-rygy']; // the region is owned by uk
    const result: TurnResult = {
      date: '1939-09-03',
      events: [],
      stateChanges: [],
      relations: [],
      territoryChanges: [],
      unowned: [],
      nationOps: [],
      markers: { add: [mk('city', 'Strasbourg', 'moselle-rygy')], remove: [] },
    };
    const next = applyTurnResult(state, result, undefined, centroidOf);
    expect(next.markers).toHaveLength(1);
    const m = next.markers[0];
    expect(m.id).toBe(markerId('city', 'Strasbourg', 'moselle-rygy'));
    expect(m.type).toBe('city');
    expect(m.name).toBe('Strasbourg');
    expect(m.regionKey).toBe('moselle-rygy');
    expect(m.ownerNationId).toBe('uk'); // the region's sole owner
    expect(m.placedTurn).toBe(4);
    // the position is the centroid jittered within ±spread/2
    expect(m.lat).toBeGreaterThanOrEqual(47.5);
    expect(m.lat).toBeLessThanOrEqual(48.5);
    expect(m.lon).toBeGreaterThanOrEqual(5.5);
    expect(m.lon).toBeLessThanOrEqual(6.5);
  });
  it('is idempotent: re-adding the same (type, name, regionKey) does not duplicate the marker', () => {
    const state = baseState();
    state.nations.uk.territory = ['moselle-rygy'];
    const add = [mk('city', 'Strasbourg', 'moselle-rygy')];
    const first = applyTurnResult(state, {
      date: '1939-09-03', events: [], stateChanges: [], relations: [], territoryChanges: [],
      unowned: [], nationOps: [], markers: { add, remove: [] },
    }, undefined, centroidOf);
    expect(first.markers).toHaveLength(1);
    // a second turn proposes the exact same marker again
    const second = applyTurnResult(first, {
      date: '1939-09-05', events: [], stateChanges: [], relations: [], territoryChanges: [],
      unowned: [], nationOps: [], markers: { add, remove: [] },
    }, undefined, centroidOf);
    expect(second.markers).toHaveLength(1);
    expect(second.markers[0].id).toBe(first.markers[0].id); // stable id, no second copy
  });
  it('applyTurnResult drops a new add whose region is unknown or has no centroid, but keeps a valid one', () => {
    const state = baseState();
    state.nations.uk.territory = ['moselle-rygy'];
    // validKeys knows two keys; the centroid resolves only the first.
    const validKeys = new Set(['moselle-rygy', 'other-key']);
    const centroidOf2 = (k: string) =>
      k === 'moselle-rygy' ? { lat: 48, lon: 6, spread: 1 } : undefined;
    const result: TurnResult = {
      date: '1939-09-03',
      events: [],
      stateChanges: [],
      relations: [],
      territoryChanges: [],
      unowned: [],
      nationOps: [],
      markers: {
        add: [
          { type: 'city', name: 'Good', regionKey: 'moselle-rygy' }, // valid + centroid → kept
          { type: 'city', name: 'NoCent', regionKey: 'other-key' }, // in validKeys, no centroid → dropped
          { type: 'city', name: 'Unknown', regionKey: 'zzz-not-a-key' }, // not in validKeys → dropped
        ],
        remove: [],
      },
    };
    const next = applyTurnResult(state, result, validKeys, centroidOf2);
    expect(next.markers).toHaveLength(1);
    expect(next.markers[0].name).toBe('Good');
  });
  it('caps the total marker count at MAX_MARKERS, dropping the newest add that exceeds the cap', () => {
    const state = baseState();
    // pre-seed the state with MAX_MARKERS - 1 distinct markers
    const seeded: typeof state.markers = [];
    for (let i = 0; i < MAX_MARKERS - 1; i++) {
      const k = `seed-${i}`;
      seeded.push({
        id: markerId('city', `S${i}`, k),
        type: 'city',
        name: `S${i}`,
        regionKey: k,
        lat: 0, lon: 0,
        ownerNationId: null,
        placedTurn: 1,
      });
    }
    state.markers = seeded;
    // a permissive centroid: every region key resolves
    const anyCentroid = () => ({ lat: 0, lon: 0, spread: 0 });
    const result: TurnResult = {
      date: '1939-09-03',
      events: [],
      stateChanges: [],
      relations: [],
      territoryChanges: [],
      unowned: [],
      nationOps: [],
      markers: {
        add: [
          { type: 'city', name: 'NewA', regionKey: 'new-a' },
          { type: 'city', name: 'NewB', regionKey: 'new-b' },
        ],
        remove: [],
      },
    };
    const next = applyTurnResult(state, result, undefined, anyCentroid);
    expect(next.markers).toHaveLength(MAX_MARKERS); // capped, not MAX_MARKERS + 1
    expect(next.markers.some((m) => m.name === 'NewA')).toBe(true); // the 1st new one kept
    expect(next.markers.some((m) => m.name === 'NewB')).toBe(false); // the 2nd (over cap) dropped
  });
  it('removes a marker by id; removing an absent id is a no-op', () => {
    const state = baseState();
    state.nations.uk.territory = ['moselle-rygy'];
    const idA = markerId('city', 'Strasbourg', 'moselle-rygy');
    const idB = markerId('port', 'Dunkirk', 'moselle-rygy');
    state.markers = [
      { id: idA, type: 'city', name: 'Strasbourg', regionKey: 'moselle-rygy', lat: 48, lon: 6, ownerNationId: 'uk', placedTurn: 1 },
      { id: idB, type: 'port', name: 'Dunkirk', regionKey: 'moselle-rygy', lat: 48, lon: 6, ownerNationId: 'uk', placedTurn: 1 },
    ];
    const next = applyTurnResult(state, {
      date: '1939-09-03', events: [], stateChanges: [], relations: [], territoryChanges: [],
      unowned: [], nationOps: [], markers: { add: [], remove: [idA, 'zzzz-not-there'] },
    }, undefined, centroidOf);
    expect(next.markers).toHaveLength(1);
    expect(next.markers[0].id).toBe(idB); // only A removed; the bogus id was a no-op
  });
  it('a marker owner follows its region: released to no man\'s land → null; re-claimed → the new owner', () => {
    const state = baseState();
    state.nations.uk.territory = ['moselle-rygy'];
    const idA = markerId('city', 'Strasbourg', 'moselle-rygy');
    state.markers = [
      { id: idA, type: 'city', name: 'Strasbourg', regionKey: 'moselle-rygy', lat: 48, lon: 6, ownerNationId: 'uk', placedTurn: 1 },
    ];
    // 1) uk releases the region → the marker becomes ownerless
    const released = applyTurnResult(state, {
      date: '1939-09-03', events: [], stateChanges: [], relations: [], territoryChanges: [],
      unowned: ['moselle-rygy'], nationOps: [], markers: { add: [], remove: [] },
    }, undefined, centroidOf);
    expect(released.markers[0].ownerNationId).toBeNull();
    // 2) de re-claims the region → the marker's owner follows to de
    const reclaimed = applyTurnResult(released, {
      date: '1939-09-05', events: [], stateChanges: [], relations: [],
      territoryChanges: [{ nation: 'de', gain: ['moselle-rygy'], lose: [] }],
      unowned: [], nationOps: [], markers: { add: [], remove: [] },
    }, undefined, centroidOf);
    expect(reclaimed.markers[0].ownerNationId).toBe('de');
  });
  it('the user prompt carries the existing markers when provided (and omits the field otherwise)', () => {
    const state = baseState();
    const info = {
      id: markerId('city', 'Strasbourg', 'moselle-rygy'),
      type: 'city' as MarkerType,
      name: 'Strasbourg',
      regionKey: 'moselle-rygy',
      owner: 'uk',
    };
    const payload = JSON.parse(
      buildUserPrompt(state, [], undefined, undefined, undefined, [info]),
    ) as { markers?: Array<Record<string, unknown>> };
    expect(payload.markers).toHaveLength(1);
    expect(payload.markers![0].name).toBe('Strasbourg');
    expect(payload.markers![0].owner).toBe('uk');
    // a bare call (no markers arg) omits the field entirely
    const bare = JSON.parse(buildUserPrompt(state, [])) as { markers?: unknown };
    expect(bare.markers).toBeUndefined();
  });
  it('the system prompt documents the markers contract (field + placement rule + a type)', () => {
    const prompt = buildSystemPrompt(preset);
    expect(prompt).toMatch(/named points on the map/i);
    expect(prompt).toMatch(/"markers"/);
    expect(prompt).toMatch(/"add"/);
    expect(prompt).toMatch(/"remove"/);
    expect(prompt).toMatch(/gathering/);
    expect(prompt).toMatch(/no man's land/); // owner recompute on release
  });
  it('validateMarkerOps cleans a raw markers field: drops bad types/empty names, dedupes, trims removes', () => {
    const raw = {
      add: [
        { type: 'city', name: 'X', regionKey: 'a' },
        { type: 'not-a-type', name: 'Y', regionKey: 'a' }, // invalid type -> dropped
        { type: 'city', name: '   ', regionKey: 'a' }, // empty name -> dropped
        { type: 'city', name: 'X', regionKey: 'a' }, // duplicate (same id) -> deduped
        { type: 'port', name: 'Z', regionKey: 'b' }, // valid
      ],
      remove: ['id-1', 42, '', '  id-2  ', 'id-1'], // number/empty dropped, trimmed, deduped
    };
    const out = validateMarkerOps(raw);
    expect(out.add.map((m) => m.name).sort()).toEqual(['X', 'Z']);
    expect(out.remove).toEqual(['id-1', 'id-2']);
  });
  it('validateMarkerOps returns empty ops for a non-object raw value (a string, an array, null)', () => {
    for (const bad of ['oops', [{ type: 'city', name: 'X', regionKey: 'a' }], null, undefined]) {
      expect(validateMarkerOps(bad)).toEqual({ add: [], remove: [] });
    }
  });
  it('runTurn wires the centroid through: a marker added over the LLM path is placed (owner = region owner)', async () => {
    const result = JSON.stringify({
      date: '1939-09-03',
      events: [],
      stateChanges: [],
      relations: [],
      territoryChanges: [{ nation: 'uk', gain: ['moselle-rygy'], lose: [] }],
      unowned: [],
      nationOps: [],
      markers: { add: [{ type: 'city', name: 'Strasbourg', regionKey: 'moselle-rygy' }], remove: [] },
    });
    const { state } = await runTurn({
      llm: fakeLlm([result]),
      preset,
      state: baseState(),
      items: [],
      centroidOf,
    });
    expect(state.markers).toHaveLength(1);
    expect(state.markers[0].name).toBe('Strasbourg');
    expect(state.markers[0].ownerNationId).toBe('uk'); // uk gained the region this turn
  });
 });
@@ -7,6 +7,7 @@ import type {
  EventOutcome,
  EventType,
  GameState,
  MapMarker,
  Nation,
  NationStats,
  Preset,
@@ -18,9 +19,15 @@ import { EVENT_TYPES, RELATION_STATUSES } from '../shared/types';
 import {
  addDays,
  clampStat,
  fnv1a32,
  isDateLike,
  isMarkerType,
  makeEvent,
  markerId,
  MAX_MARKERS,
  nationForPrompt,
  type MarkerInfo,
  type MarkerSpec,
  type NationOp,
  type TurnEventSpec,
  type TurnResult,
@@ -187,12 +194,14 @@ export function buildSystemPrompt(preset: Preset, withNeighboursTool = false): s
    '    {"kind":"split","nationRef":"<nation id or name>","parts":[{"name":"<new name>","territory":["<region key>"]}]}',
    '    {"kind":"merge","nationRefs":["<id>","<id>"],"survivingRef":"<id of the surviving nation>","into":"<new name>"}',
    '  ],',
    '  "markers": {"add":[{"type":"<city|factory|army|port|capital|fleet|rocket|gathering>","name":"<short name>","regionKey":"<region key>"}],"remove":["<marker id>"]}',
    '}',
    '',
    'HARD CONSTRAINTS',
    '- 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".',
    '- Map markers ("markers") are named points on the map, anchored to a region key you own or that the narrative justifies: a capital (a nation\'s main seat of power — at most one per nation), major cities, factory complexes, army deployments, ports, fleet concentrations, rocket launch sites, or a gathering (a large political/social mass event that can enable a non-military takeover). Use only region keys from the "regions" table, keep each name under 40 characters, and place at most a handful of new markers per turn — only where the narrative justifies it. List a marker id from the user message\'s "markers" field in "remove" when it ceases to exist (a city razed, an army dispersed, a site destroyed).',
    '- Nation-management ops ("nationOps") are PROPOSALS: they only take effect if the player confirms them afterwards. Propose at most 1-2 per turn, only when the narrative justifies it, and narrate each one in "events".',
    '- Rename: add {"kind":"rename","nationRef":"<nation id or name>","to":"<new name>"} for a revolution, regime change or reunification that changes a nation\'s name.',
    '- Split: add {"kind":"split","nationRef":"<nation id or name>","parts":[{"name":"<new name>","territory":["<region key>"]}, ...]} when a state breaks up (dissolution, secession). Use at least 2 parts and assign each of the nation\'s region keys to at most one part — any key you leave unassigned goes to the first part.',
@@ -232,6 +241,14 @@ export function buildUserPrompt(
   * Omitted entirely when undefined.
   */
  noMansLand?: string[],
  /**
   * (v0.27, #44) The game's current map markers, as the model sees them:
   * stable id, type, name, region key and current owner. Emitted verbatim
   * (even when empty) so the model can reference a marker's id in
   * `TurnResult.markers.remove` or leave an existing marker untouched.
   * Omitted entirely when undefined.
   */
  markers?: MarkerInfo[],
 ): string {
  const player = state.nations[state.playerNationId];
  const playerName = player?.name ?? state.playerNationId;
@@ -270,6 +287,7 @@ export function buildUserPrompt(
  if (regionReference) payload.regions = regionReference;
  if (frontier !== undefined) payload.frontier = frontier;
  if (noMansLand !== undefined) payload.unowned = noMansLand;
  if (markers !== undefined) payload.markers = markers;
  return JSON.stringify(payload, null, 2);
 }
@@ -393,6 +411,7 @@ export function validateTurnResult(input: unknown): TurnResult | null {
    territoryChanges: [],
    unowned: [],
    nationOps: [],
    markers: { add: [], remove: [] },
  };
  if (Array.isArray(o.events)) {
@@ -482,9 +501,51 @@ export function validateTurnResult(input: unknown): TurnResult | null {
  // list for the player to confirm/reject.
  result.nationOps = validateNationOps(o.nationOps);
  // (v0.27, #44) Map-marker ops: new placements (validated here) and
  // removals by stable id. Applied by applyTurnResult after the territory
  // moves (a new marker's owner is the region's post-turn owner).
  result.markers = validateMarkerOps(o.markers);
  return result;
 }
 /**
 * (v0.27, #44) Validate the raw `markers` object of a turn into a safe
 * `{ add, remove }` shape. Defensive like the rest of the parser — never
 * throws. `add`: each spec needs a known marker type, a non-empty `name`
 * (capped at 120 chars) and a non-empty `regionKey` (capped at 120 chars);
 * specs whose derived id collides with an earlier one in the same batch
 * collapse to the first (re-adding is idempotent). `remove`: deduped,
 * non-empty marker ids (capped at 120 chars).
 */
 export function validateMarkerOps(raw: unknown): { add: MarkerSpec[]; remove: string[] } {
  const out: { add: MarkerSpec[]; remove: string[] } = { add: [], remove: [] };
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return out;
  const o = raw as Record<string, unknown>;
  if (Array.isArray(o.add)) {
    const seen = new Set<string>();
    for (const e of o.add) {
      if (!e || typeof e !== 'object') continue;
      const s = e as Record<string, unknown>;
      if (!isMarkerType(s.type)) continue;
      const name = str(s.name, 120);
      const regionKey = str(s.regionKey, 120);
      if (!name || !regionKey) continue;
      const id = markerId(s.type, name, regionKey);
      if (seen.has(id)) continue;
      seen.add(id);
      out.add.push({ type: s.type, name, regionKey });
    }
  }
  if (Array.isArray(o.remove)) {
    for (const k of o.remove) {
      const s = typeof k === 'string' ? k.trim() : '';
      if (s && !out.remove.includes(s)) out.remove.push(s.slice(0, 120));
    }
  }
  return out;
 }
 /**
 * 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
@@ -498,7 +559,10 @@ export function isMeaningful(result: TurnResult): boolean {
    result.events.length > 0 ||
    result.stateChanges.length > 0 ||
    result.unowned.length > 0 ||
-    result.nationOps.length > 0
+    result.nationOps.length > 0 ||
    // (v0.27, #44) a marker placed or removed this turn is a real world change.
    result.markers.add.length > 0 ||
    result.markers.remove.length > 0
  );
 }
@@ -516,13 +580,25 @@ 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
+ * events, apply stat changes (clamped), symmetric relations, territory moves
- * moves (including no-man's-land releases, v0.22 #16 P3). It also appends any
+ * (including no-man's-land releases, v0.22 #16 P3) and map markers (v0.27
- * proposed nation-ops to the pending list (v0.23 #16 P4a) without applying
+ * #44). It also appends any proposed nation-ops to the pending list (v0.23
- * them — see the doc comment on `pendingNationOps` for why that list
+ * #16 P4a) without applying them — see the doc comment on `pendingNationOps`
- * deliberately survives across turns.
+ * for why that list deliberately survives across turns.
 *
 * `centroidOf` (v0.27, #44) resolves a region key to its precomputed centroid
 * (`{ lat, lon, spread }`, from public/region-centroids.json via
 * server/regions.ts). New markers are positioned at that centroid plus a small
 * deterministic offset; a spec whose key has no known centroid is dropped.
 * Without it no marker can be placed (all adds are dropped), which keeps the
 * engine pure and lets tests inject their own data.
 */
-export function applyTurnResult(state: GameState, result: TurnResult, validKeys?: ReadonlySet<string>): GameState {
+export function applyTurnResult(
  state: GameState,
  result: TurnResult,
  validKeys?: ReadonlySet<string>,
  centroidOf?: (key: string) => { lat: number; lon: number; spread: number } | undefined,
 ): 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
@@ -636,6 +712,73 @@ export function applyTurnResult(state: GameState, result: TurnResult, validKeys?
  }
  next.unowned = [...unowned];
  // --- Map markers (v0.27, #44) ---
  //
  // Markers are anchored to a region key and are processed against the FINAL
  // post-claim ownership, in this order:
  //   (1) REMOVE: a marker whose id is in result.markers.remove is dropped
  //       (a listed-but-absent id is a no-op).
  //   (2) OWNER RECOMPUTE: every surviving marker's ownerNationId is set to
  //       its region's current owner — a captured region follows the new
  //       owner, a region released to no man's land (or a key with 0 or 2+
  //       owners) becomes `null`. A marker always follows its region.
  //   (3) ADD: each new spec (in order) is placed at its region's centroid
  //       (injected via centroidOf) plus a small deterministic per-axis
  //       offset, owned by the region's post-turn owner, and stamped with
  //       the acting turn. Dropped (never throws): a region key that is not
  //       in validKeys or has no known centroid, an id that already exists
  //       (a re-add is idempotent — the existing marker stays), and any adds
  //       beyond MAX_MARKERS (the later ones).
  {
    const finalOwner = new Map<string, string | null>();
    {
      const owners = new Map<string, string[]>();
      for (const n of Object.values(next.nations)) {
        for (const key of n.territory) {
          if (!valid(key)) continue;
          const list = owners.get(key);
          if (list) list.push(n.id);
          else owners.set(key, [n.id]);
        }
      }
      for (const [key, list] of owners) finalOwner.set(key, list.length === 1 ? list[0] : null);
    }
    const removeIds = new Set(result.markers.remove);
    const markers: MapMarker[] = [];
    for (const m of next.markers ?? []) {
      if (removeIds.has(m.id)) continue;
      markers.push({ ...m, ownerNationId: finalOwner.get(m.regionKey) ?? null });
    }
    // Deterministic ±(spread/2) offset per axis: a FNV-1a-derived unit
    // fraction of the marker id (stable across runs and platforms), so
    // markers of one region scatter naturally instead of stacking.
    const jitter = (id: string, axis: 'lat' | 'lon', spread: number): number => {
      const frac = (fnv1a32(`${id}#${axis}`) >>> 8) / 0x00ffffff;
      return (frac * 2 - 1) * (spread / 2);
    };
    const round6 = (v: number): number => Math.round(v * 1e6) / 1e6;
    for (const spec of result.markers.add) {
      const id = markerId(spec.type, spec.name, spec.regionKey);
      if (markers.some((m) => m.id === id)) continue; // re-add: idempotent, keep the existing
      if (markers.length >= MAX_MARKERS) continue; // hard cap: drop the excess
      if (!valid(spec.regionKey)) continue; // unknown region key
      const c = centroidOf?.(spec.regionKey);
      if (!c) continue; // no centroid data for this key
      markers.push({
        id,
        type: spec.type,
        name: spec.name,
        regionKey: spec.regionKey,
        lat: round6(c.lat + jitter(id, 'lat', c.spread)),
        lon: round6(c.lon + jitter(id, 'lon', c.spread)),
        ownerNationId: finalOwner.get(spec.regionKey) ?? null,
        placedTurn: actingTurn,
      });
    }
    next.markers = markers;
  }
  // (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
@@ -965,15 +1108,31 @@ export async function runTurn(opts: {
   * switches the turn onto the getNeighbours tool path.
   */
  getNeighbours?: (keys: string[]) => string[];
  /**
   * (v0.27, #44) Region-key -> precomputed centroid resolver (from
   * public/region-centroids.json). Present, the turn's new markers can be
   * placed at their region's centroid; absent, marker adds are dropped and
   * the existing markers' owners still get recomputed.
   */
  centroidOf?: (key: string) => { lat: number; lon: number; spread: number } | undefined;
 }): Promise<{ state: GameState; result: TurnResult }> {
-  const { llm, preset, state, items, regionReference, validRegionKeys, getNeighbours } = opts;
+  const { llm, preset, state, items, regionReference, validRegionKeys, getNeighbours, centroidOf } = opts;
  const chatWithTools = llm.chatWithTools;
  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 ?? []);
+  // (v0.27, #44) likewise the current map markers, so it can reference their
  // stable ids in `markers.remove` (or leave them untouched).
  const markers = (state.markers ?? []).map((m) => ({
    id: m.id,
    type: m.type,
    name: m.name,
    regionKey: m.regionKey,
    owner: m.ownerNationId,
  }));
  const user = buildUserPrompt(state, items, regionReference, frontier, state.unowned ?? [], markers);
  const nudge =
    'Your previous output was invalid. Respond with ONLY the JSON object described above for this batch — no prose, no fences.';
@@ -1018,10 +1177,11 @@ export async function runTurn(opts: {
      territoryChanges: [],
      unowned: [],
      nationOps: [],
      markers: { add: [], remove: [] },
    };
  }
-  return { state: applyTurnResult(state, result, validRegionKeys), result };
+  return { state: applyTurnResult(state, result, validRegionKeys, centroidOf), result };
 }
 // --- Advisor (brainstorm) -----------------------------------------------------
@@ -22,7 +22,7 @@ import { createLlmClient } from './llm';
 import { makeStubLlmClient } from './stub';
 import { askAdvisor, confirmNationOp, queueRoundItem, rejectNationOp, removeRoundItem, runTurn } from './engine';
 import { buildRegionMap } from './map';
-import { allTerritoryKeys, expandCountriesToKeys, hasAdjacency, loadRegions, neighboursOf, referenceForKeys, validKeys } from './regions';
+import { allTerritoryKeys, centroidOf, expandCountriesToKeys, hasAdjacency, hasCentroids, loadRegions, neighboursOf, referenceForKeys, validKeys } from './regions';
 import { createPresetStore } from './presets';
 import { openDb, type Db } from './db';
@@ -134,6 +134,8 @@ app.post('/api/games', (req: Request, res) => {
    // list grows as the LLM proposes renames (and, later, splits/merges) and
    // shrinks as the player confirms or rejects them.
    pendingNationOps: [],
    // (v0.27, #44) No markers on a fresh game; the LLM places them over time.
    markers: [],
  };
  // v0.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
@@ -288,6 +290,11 @@ app.post('/api/games/:id/jump', async (req, res) => {
      // engine the resolver — the turn then runs with the LLM's getNeighbours
      // tool and the player-frontier prompt field (both switch off without it).
      getNeighbours: hasAdjacency() ? (keys) => neighboursOf(keys) : undefined,
      // (v0.27, #44) when the centroid manifest loaded, hand the engine the
      // resolver so a turn can place new map markers at their region's
      // centroid (without it, marker adds are dropped; existing markers are
      // still maintained).
      centroidOf: hasCentroids() ? (key) => centroidOf(key) : undefined,
    });
    db.save(state);
    broadcast(id, 'turn', { state, result });
@@ -49,6 +49,7 @@ const state: GameState = {
  version: 1,
  unowned: [],
  pendingNationOps: [],
  markers: [],
 };
 // The RegionMap built from the fixture: the authoritative region key → owner source.
@@ -5,8 +5,10 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 import {
  allTerritoryKeys,
  centroidOf,
  expandCountriesToKeys,
  hasAdjacency,
  hasCentroids,
  hasRegionData,
  loadRegions,
  neighboursOf,
@@ -103,6 +105,7 @@ describe('regions (region-key loader, v0.19 #16 P1)', () => {
      version: 1,
      unowned: [],
      pendingNationOps: [],
      markers: [],
    };
    // 16 GBR sub-regions + 42 FRA sub-regions, no overlap between the two.
    expect(allTerritoryKeys(state).size).toBe(58);
@@ -133,6 +136,19 @@ describe('regions (region-key loader, v0.19 #16 P1)', () => {
    expect(neighboursOf([])).toEqual([]);
  });
  it('(v0.27 #44) hasCentroids() is true and centroidOf resolves a real key to a plausible location', () => {
    expect(hasCentroids()).toBe(true);
    const ain = centroidOf('ain-lqtt');
    expect(ain).toBeDefined();
    expect(ain!.lat).toBeCloseTo(46.16, 1);
    expect(ain!.lon).toBeCloseTo(4.8, 1);
    expect(ain!.spread).toBeGreaterThan(0);
  });
  it('(v0.27 #44) centroidOf returns undefined for an unknown key', () => {
    expect(centroidOf('not-a-real-key-xyz')).toBeUndefined();
  });
  describe('graceful degradation with no region data', () => {
    beforeEach(() => resetRegions());
@@ -146,6 +162,9 @@ describe('regions (region-key loader, v0.19 #16 P1)', () => {
      // and no adjacency: the LLM tool / frontier field switch off
      expect(hasAdjacency()).toBe(false);
      expect(neighboursOf(['moselle-rygy'])).toEqual([]);
      // and no centroids: the marker-placement path degrades to a no-op
      expect(hasCentroids()).toBe(false);
      expect(centroidOf('ain-lqtt')).toBeUndefined();
    });
  });
@@ -197,6 +216,21 @@ describe('loadRegions resolves the manifest per environment (dev public/ vs prod
    expect(loadRegions(prodRoot)).toBe(true);
    expect(hasAdjacency()).toBe(false);
    expect(neighboursOf(['moselle-rygy'])).toEqual([]);
    // and no centroids (not copied into this dist/) -> marker placement degrades
    expect(hasCentroids()).toBe(false);
    expect(centroidOf('ain-lqtt')).toBeUndefined();
  });
  it('(v0.27 #44) a dist/ WITH the centroids manifest loads them (prod layout)', () => {
    copyFileSync(
      path.join(realRoot, 'public', 'region-centroids.json'),
      path.join(prodRoot, 'dist', 'region-centroids.json'),
    );
    expect(loadRegions(prodRoot)).toBe(true);
    expect(hasCentroids()).toBe(true);
    const ain = centroidOf('ain-lqtt');
    expect(ain).toBeDefined();
    expect(ain!.lat).toBeCloseTo(46.16, 1);
  });
  it('returns false and no data when neither public/ nor dist/ holds the files', () => {
@@ -2,7 +2,9 @@
 // (region-keys.json: stable feature id -> region key), the sub-national geo
 // (regions.geo.json: feature id -> { name, parent }), and — optionally — the
 // precomputed region-adjacency manifest (region-adjacency.json: region key ->
-// bordering region keys, built by scripts/build-region-adjacency.mjs) — all
+// bordering region keys, built by scripts/build-region-adjacency.mjs) and the
 // precomputed region-centroid manifest (region-centroids.json: region key ->
 // { lat, lon, spread }, built by scripts/build-region-centroids.mjs) — all
 // from public/ in dev (Vite serves it) or dist/ in prod (Vite copies
 // public/* -> dist/ at build, and the Docker image keeps only dist/) — and
 // joins them into the lookups the region-level ownership model needs:
@@ -13,6 +15,8 @@
 //   - neighboursOf(): the union of the bordering keys for a set of keys — the
 //     data behind the LLM's getNeighbours tool and the player-frontier prompt
 //     field (v0.21, #16 P2)
 //   - centroidOf(): a region key's precomputed anchor point ({ lat, lon, spread })
 //     — the data behind LLM-placed map markers (v0.27, #44)
 //
 // Deliberately turf-free: it reads the JSON files with plain JSON.parse and
 // never imports @turf/@types/geojson (importing one pulls @types/geojson into
@@ -39,12 +43,15 @@ interface RegionData {
  validKeys: Set<string>;
  /** region key -> bordering region keys (from public/region-adjacency.json). */
  adjacency: Record<string, string[]>;
  /** region key -> anchor point (from public/region-centroids.json). */
  centroids: Record<string, { lat: number; lon: number; spread: number }>;
 }
 let data: RegionData | null = null;
 /**
- * Load (or reload) the region-key manifest, geo, and adjacency. Idempotent.
+ * Load (or reload) the region-key manifest, geo, adjacency, and centroids.
 * Idempotent.
 * The files are served to the client from `public/` in dev (Vite serves it
 * directly) and from `dist/` in prod (Vite copies `public/*` → `dist/` at build
 * and the Docker image keeps only `dist/`), so probe `public/` then `dist/`
@@ -52,7 +59,10 @@ let data: RegionData | null = null;
 * key manifest + geo. The adjacency manifest is OPTIONAL: when it is missing
 * or broken, `adjacency` stays empty and `neighboursOf`/`hasAdjacency` simply
 * report "no adjacency" (the LLM tool and the frontier prompt field switch
- * off; everything else keeps working). Returns true when the core pair loaded
+ * off; everything else keeps working). The centroid manifest is likewise
 * OPTIONAL (v0.27, #44): when missing or broken, `centroids` stays empty and
 * `centroidOf`/`hasCentroids` report "no centroids" (new map markers can't be
 * placed, but everything else keeps working). Returns true when the core pair loaded
 * cleanly; a missing/broken pair clears the data and returns false so the
 * server still boots and degrades gracefully (expansion becomes a no-op,
 * ownership falls back to the raw input keys).
@@ -61,6 +71,7 @@ export function loadRegions(root: string): boolean {
  const keyFile = 'region-keys.json';
  const geoFile = 'regions.geo.json';
  const adjacencyFile = 'region-adjacency.json';
  const centroidsFile = 'region-centroids.json';
  const base = [
    path.join(root, 'public'), // dev: Vite serves public/ at /
    path.join(root, 'dist'), // prod: Vite copies public/* -> dist/ (== clientDir)
@@ -105,7 +116,38 @@ export function loadRegions(root: string): boolean {
      }
    }
-    data = { idToKey, keyToInfo, keysByCountry, validKeys, adjacency };
+    // Centroids are optional too (v0.27, #44): a missing/broken file means
    // "no centroid data" — new markers can't be placed (their adds are
    // dropped), but everything else keeps working.
    let centroids: Record<string, { lat: number; lon: number; spread: number }> = {};
    const centroidsPath = path.join(base, centroidsFile);
    if (existsSync(centroidsPath)) {
      try {
        const raw = JSON.parse(readFileSync(centroidsPath, 'utf8')) as Record<
          string,
          { lat?: unknown; lon?: unknown; spread?: unknown }
        >;
        // Keep only well-formed entries; a corrupt file degrades to "none".
        for (const [k, v] of Object.entries(raw)) {
          if (
            v &&
            typeof v.lat === 'number' &&
            typeof v.lon === 'number' &&
            typeof v.spread === 'number' &&
            Number.isFinite(v.lat) &&
            Number.isFinite(v.lon) &&
            Number.isFinite(v.spread)
          ) {
            centroids[k] = { lat: v.lat, lon: v.lon, spread: v.spread };
          }
        }
      } catch (err) {
        console.error('[regions] failed to load region-centroids.json, continuing without it', err);
        centroids = {};
      }
    }
    data = { idToKey, keyToInfo, keysByCountry, validKeys, adjacency, centroids };
    return validKeys.size > 0;
  } catch (err) {
    console.error('[regions] failed to load region data', err);
@@ -189,6 +231,27 @@ export function hasAdjacency(): boolean {
  return data !== null && Object.keys(data.adjacency).length > 0;
 }
 /**
 * True when the region-centroid manifest loaded with at least one entry
 * (v0.27, #44). The server's jump route uses this to decide whether to hand
 * the engine a centroid resolver (which lets a turn place new map markers)
 * or skip marker placement (existing markers are still maintained).
 */
 export function hasCentroids(): boolean {
  return data !== null && Object.keys(data.centroids).length > 0;
 }
 /**
 * The precomputed anchor point for a region key: the centroid of its
 * largest-area part, plus a `spread` (≈ 0.1 × that part's smallest bbox
 * dimension, in degrees) the engine scatters markers within
 * ±(spread/2) of the centroid. `undefined` for an unknown key or when no
 * centroid data is loaded (v0.27, #44).
 */
 export function centroidOf(key: string): { lat: number; lon: number; spread: number } | undefined {
  return data?.centroids[key];
 }
 /**
 * The 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
@@ -31,6 +31,13 @@ export interface StubPayload {
   * is covered by unit tests against applyTurnResult, not by the stub.
   */
  unowned?: string[];
  /**
   * (v0.27, #44) Current map markers (`{ id, type, name, regionKey, owner }`),
   * emitted by the engine's user prompt. The stub ignores this field — it
   * never places or removes a marker (see deterministicTurn), so the marker
   * path is covered by unit tests against applyTurnResult, not by the stub.
   */
  markers?: Array<{ id: string; type: string; name: string; regionKey: string; owner: string | null }>;
 }
 function truncate(s: string, n: number): string {
@@ -61,6 +68,10 @@ function truncate(s: string, n: number): string {
 * (v0.23, #16 P4a) The stub likewise NEVER proposes nation-management ops (it
 * always returns `nationOps: []`) — the propose→confirm/reject flow is
 * covered by unit tests only, keeping the e2e assertions untouched.
 *
 * (v0.27, #44) The stub likewise NEVER places or removes a map marker (it
 * always returns `markers: { add: [], remove: [] }`) — the marker path is
 * covered by unit tests only, keeping the e2e assertions untouched.
 */
 export function deterministicTurn(p: StubPayload): TurnResult {
  const state = p.state;
@@ -126,6 +137,7 @@ export function deterministicTurn(p: StubPayload): TurnResult {
    territoryChanges,
    unowned: [], // the stub never creates no man's land (see doc comment)
    nationOps: [], // the stub never proposes nation ops (see doc comment)
    markers: { add: [], remove: [] }, // the stub never touches markers (see doc comment)
  };
 }
@@ -6,10 +6,12 @@ import type {
  EventOutcome,
  EventType,
  GameState,
  MarkerType,
  Nation,
  RelationStatus,
  StatKey,
 } from './types';
 import { MARKER_TYPES } from './types';
 /** A numeric change to one of a nation's 0–100 stats. */
 export type StateChange =
@@ -114,6 +116,100 @@ export interface TurnEventSpec {
  outcome: EventOutcome;
 }
 // --- Map markers (v0.27, #44) -------------------------------------------------
 //
 // The LLM places named point markers (cities, factories, armies, ports,
 // capitals, fleets, rocket launch sites, gatherings) anchored to a region
 // key. It never sees or sets coordinates: the engine derives the position
 // from the region's precomputed centroid (public/region-centroids.json) plus a
 // small deterministic offset, and it recomputes each marker's owner from the
 // region's current owner on every turn (a released region → null).
 //
 // The marker id is a STABLE, deterministic 4-letter code (FNV-1a 32-bit →
 // base 26, the same scheme as the region keys' 4-char suffix) derived from
 // (type, name, regionKey) — so re-adding an identical marker is idempotent
 // (same id, skipped) and removing by id is unambiguous.
 /** The spec the LLM emits to place a marker: type, name and the region it sits in. */
 export interface MarkerSpec {
  type: MarkerType;
  name: string;
  regionKey: string;
 }
 /**
 * One existing marker as the user prompt presents it to the model (v0.27,
 * #44): its stable `id` (the model may echo it in `TurnResult.markers.remove`),
 * type, name, region key, and the id of the nation currently owning its
 * region (`null` when the region is unowned / no man's land).
 */
 export interface MarkerInfo {
  id: string;
  type: MarkerType;
  name: string;
  regionKey: string;
  owner: string | null;
 }
 /**
 * The per-type presentation of a marker: its display label (tooltip /
 * dossier), its color, and its glyph character (a symbol-layer text label —
 * a small, font-safe character in front of the name). Pure + shared so the
 * client's marker layer and any server-side consumers agree on the look.
 */
 export const MARKER_TYPE_INFO: Record<MarkerType, { label: string; color: string; glyph: string }> = {
  city: { label: 'City', color: '#cbd5e1', glyph: '●' },
  factory: { label: 'Factory', color: '#fb923c', glyph: '■' },
  army: { label: 'Army', color: '#ef4444', glyph: '▲' },
  port: { label: 'Port', color: '#38bdf8', glyph: '◆' },
  capital: { label: 'Capital', color: '#fbbf24', glyph: '★' },
  fleet: { label: 'Fleet', color: '#22d3ee', glyph: '◗' },
  rocket: { label: 'Rocket site', color: '#a78bfa', glyph: '↥' },
  gathering: { label: 'Gathering', color: '#4ade80', glyph: '◉' },
 };
 /** Hard cap on a game's total markers (new adds beyond the cap are dropped, v0.27 #44). */
 export const MAX_MARKERS = 400;
 /**
 * FNV-1a 32-bit — the same tiny, stable, pure string hash the region keys use
 * (see scripts/build-region-keys.mjs). Exported so the engine can derive
 * deterministic per-axis jitter fractions from it (marker placement, v0.27 #44).
 */
 export function fnv1a32(str: string): number {
  let h = 0x811c9dc5;
  for (let i = 0; i < str.length; i++) {
    h ^= str.charCodeAt(i);
    h = Math.imul(h, 0x01000193) >>> 0;
  }
  return h >>> 0;
 }
 /** Spread a 32-bit hash across four lowercase letters (base 26 per byte). */
 function code4(h: number): string {
  let out = '';
  for (let i = 0; i < 4; i++) {
    out += String.fromCharCode(97 + (((h >>> (i * 8)) & 0xff) % 26));
  }
  return out;
 }
 /**
 * The stable id for a marker: 4 base-26 lowercase chars from the FNV-1a hash
 * of `(type, name, regionKey)` (NUL-separated so no field boundary is
 * ambiguous). Deterministic across runs and platforms (pure string math), so
 * the same (type, name, regionKey) always maps to the same id — re-adding is
 * idempotent, removing by id is unambiguous.
 */
 export function markerId(type: MarkerType, name: string, regionKey: string): string {
  return code4(fnv1a32(`${type}\u0000${name}\u0000${regionKey}`));
 }
 /** True when `t` is one of the eight known marker types (v0.27, #44). */
 export function isMarkerType(t: unknown): t is MarkerType {
  return typeof t === 'string' && (MARKER_TYPES as string[]).includes(t);
 }
 /** The exact JSON object the world-simulator LLM must return for a turn. */
 export interface TurnResult {
  date: string;
@@ -141,6 +237,16 @@ export interface TurnResult {
   * survivor. Empty on turns where the model proposes none.
   */
  nationOps: NationOp[];
  /**
   * (v0.27, #44) Map-marker ops this turn. `add` places new named markers
   * (the engine positions each at its region's centroid + a small
   * deterministic offset, sets the owner to the region's post-turn owner,
   * derives the stable id, and drops unknown types/region keys, duplicates,
   * and adds beyond MAX_MARKERS); `remove` drops markers by their stable id
   * (a no-op for an id that is not present). Both required, `[]` on turns
   * with no marker activity.
   */
  markers: { add: MarkerSpec[]; remove: string[] };
 }
 /** Per-region map payload: region key -> owning nation + its stable color. */
@@ -68,6 +68,60 @@ export const EVENT_TYPES: EventType[] = [
 export type EventOutcome = 'success' | 'failure' | 'partial' | 'neutral';
 // --- Map markers (v0.27, #44) -------------------------------------------------
 //
 // Named point markers the LLM can place on the map (cities, factories, armies,
 // ports, capitals, fleets, rocket launch sites, political/social gatherings).
 // A marker is anchored to a **region key** (see `public/region-keys.json`): the
 // engine positions it at that region's precomputed centroid (with a small
 // deterministic offset) and its `ownerNationId` follows the region's current
 // owner (recomputed on every turn; `null` when the region is unowned / no
 // man's land). See protocol.ts for the LLM-facing `TurnResult.markers`
 // contract and the `markerId` derivation.
 /** The eight marker categories the model may place (v0.27, #44). */
 export type MarkerType =
  | 'city'
  | 'factory'
  | 'army'
  | 'port'
  | 'capital'
  | 'fleet'
  | 'rocket'
  | 'gathering';
 /** All marker types, in canonical order (used by the LLM contract + map layer). */
 export const MARKER_TYPES: MarkerType[] = [
  'city',
  'factory',
  'army',
  'port',
  'capital',
  'fleet',
  'rocket',
  'gathering',
 ];
 /**
 * A named point marker on the map (v0.27, #44). `id` is a stable,
 * deterministic 4-character code derived from `type + name + regionKey`
 * (see protocol.markerId) — re-adding the same marker is idempotent and
 * removing by id is unambiguous. `lat`/`lon` are filled in by the engine from
 * the region's centroid manifest (never by the model); `ownerNationId` is the
 * marker's region's current owner (`null` when unowned) and is recomputed by
 * the engine on every committed turn, so a marker always follows its region.
 */
 export interface MapMarker {
  id: string;
  type: MarkerType;
  name: string;
  regionKey: string;
  lat: number;
  lon: number;
  ownerNationId: string | null;
  placedTurn: number;
 }
 /** A narrative event the simulation emitted on some turn. */
 export interface EventEntry {
  id: string;
@@ -153,6 +207,16 @@ export interface GameState {
   * runtime dependencies.)
   */
  pendingNationOps: NationOp[];
  /**
   * (v0.27, #44) Named point markers on the map: the LLM places them (via a
   * turn's `markers.add`) and removes them (`markers.remove`, by id). The
   * engine positions each at its region's centroid (deterministic small
   * offset) and recomputes `ownerNationId` from the region's current owner on
   * EVERY committed turn (a released region → `null`). Always `[]` on a fresh
   * game; rows saved before v0.27 load with this defaulted to `[]` (see
   * server/db.ts) — additive, no data wipe. Capped at protocol.MAX_MARKERS.
   */
  markers: MapMarker[];
 }
 /**
@@ -706,6 +706,7 @@ function GameScreen({
        nations={game.nations}
        presetId={game.presetId}
        unowned={game.unowned ?? []}
        markers={game.markers ?? []}
        onFocusNation={focusNation}
      />
@@ -10,12 +10,14 @@ import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?url';
 maplibregl.setWorkerUrl(workerUrl);
 import {
  mapFeatureOwner,
  MARKER_TYPE_INFO,
  nationColor,
  regionFillStyle,
  unownedTooltipLabel,
  type RegionMap,
  type RegionOwner,
 } from '@shared/protocol';
-import type { Nation } from '@shared/types';
+import { MARKER_TYPES, type MapMarker, type Nation } from '@shared/types';
 import { cn } from '@/lib/utils';
 import { idToKey } from '@/lib/regions';
@@ -45,8 +47,16 @@ type GeoSource = maplibregl.GeoJSONSource;
 // looked black, and `styledata` was gated on fetching a remote document. An
 // inline object loads instantly, so `isStyleLoaded()` / `styledata` fire
 // immediately and the choropleth is guaranteed to paint. (The OFM `ne2sr`
-// raster has no vector tiles, so no glyphs endpoint is needed — we don't add
+// raster has no vector tiles, so the basemap itself needs no label layers —
-// label layers; the choropleth provides the borders.)
+// the choropleth provides the borders.)
 //
 // No `glyphs` URL: the map needs no MapLibre *text* rendering. The basemap is
 // raster (its labels are baked into the PNG tiles), and the LLM-placed map
 // markers (v0.27, #44) are drawn as canvas-generated icon images in a symbol
 // layer — fully self-contained, so they render offline and deterministically
 // without depending on any external font/glyph endpoint (the OpenFreeMap
 // `fonts/` path is a dead nginx 404, and the basemap's apparent labels come
 // from the raster, not from glyphs).
 const NE2SR_TILES = ['https://tiles.openfreemap.org/natural_earth/ne2sr/{z}/{x}/{y}.png'];
 const INLINE_STYLE: maplibregl.StyleSpecification = {
@@ -88,6 +98,8 @@ const PLAYER_LINE = 'player-line';
 const FLASH_LINE = 'flash-line';
 const HOVER_FILL = 'hover-fill';
 const HOVER_LINE = 'hover-line';
 const MARKERS_SOURCE = 'markers';
 const MARKER_SYMBOL = 'markers-symbol';
 /** Sensible per-scenario initial camera: Europe for the WWII scenarios, wider for the global ones. */
 function cameraForPreset(presetId: string): { center: [number, number]; zoom: number } {
@@ -195,6 +207,186 @@ function featuresByRegionKeys(
  return { type: 'FeatureCollection', features: JSON.parse(JSON.stringify(features)) };
 }
 // --- Map markers (v0.27, #44) ------------------------------------------------
 //
 // The LLM places named point markers (cities, factories, armies, ports,
 // capitals, fleets, rocket sites, gatherings) anchored to a region key. The
 // engine positions each at its region's centroid (deterministic small offset)
 // and recomputes its owner from the region's current owner every turn. The
 // map renders them as a single top-most symbol layer: a per-type glyph
 // character in front of the name, per-type color, dark-theme halo.
 /**
 * The GeoJSON behind the marker symbol layer: one Point per marker at
 * `[lon, lat]`, carrying the stable id, type, name, its type's glyph, and the
 * current owner's name + stable color (empty when the region is unowned).
 * Pure; the caller passes the current marker list + nations record, so a
 * renamed/removed owner is picked up on the next paint.
 */
 function buildMarkersFC(markers: MapMarker[], nations: Record<string, Nation>): FeatureCollection {
  const features = markers.map((m) => {
    const owner = m.ownerNationId ? nations[m.ownerNationId] : undefined;
    return {
      type: 'Feature' as const,
      geometry: { type: 'Point' as const, coordinates: [m.lon, m.lat] as [number, number] },
      properties: {
        id: m.id,
        type: m.type,
        name: m.name,
        glyph: MARKER_TYPE_INFO[m.type]?.glyph ?? '',
        owner: owner?.name ?? '',
        ownerId: owner?.id ?? '',
        ownerColor: owner ? nationColor(owner.id) : '',
      },
    };
  });
  return { type: 'FeatureCollection', features };
 }
 // Small canvas-path helpers for the marker icons (self-contained shapes — no
 // unicode/font dependency, so they render identically in any environment).
 function roundRectPath(
  ctx: CanvasRenderingContext2D,
  x: number,
  y: number,
  w: number,
  h: number,
  r: number,
 ): void {
  ctx.beginPath();
  ctx.moveTo(x + r, y);
  ctx.lineTo(x + w - r, y);
  ctx.quadraticCurveTo(x + w, y, x + w, y + r);
  ctx.lineTo(x + w, y + h - r);
  ctx.quadraticCurveTo(x + w, y + h, x + w - r, y + h);
  ctx.lineTo(x + r, y + h);
  ctx.quadraticCurveTo(x, y + h, x, y + h - r);
  ctx.lineTo(x, y + r);
  ctx.quadraticCurveTo(x, y, x + r, y);
  ctx.closePath();
 }
 function starPath(
  ctx: CanvasRenderingContext2D,
  cx: number,
  cy: number,
  spikes: number,
  outer: number,
  inner: number,
 ): void {
  let rot = (Math.PI / 2) * -1;
  const step = Math.PI / spikes;
  ctx.beginPath();
  ctx.moveTo(cx + Math.cos(rot) * outer, cy + Math.sin(rot) * outer);
  for (let i = 0; i < spikes; i++) {
    rot += step;
    ctx.lineTo(cx + Math.cos(rot) * inner, cy + Math.sin(rot) * inner);
    rot += step;
    ctx.lineTo(cx + Math.cos(rot) * outer, cy + Math.sin(rot) * outer);
  }
  ctx.closePath();
 }
 /**
 * (v0.27, #44) Draw one marker-type icon into an offscreen canvas: a distinct
 * shape per type, filled with the type's color from the shared
 * `MARKER_TYPE_INFO` contract, with a dark outline for legibility on any
 * choropleth fill. Added to the map as a named image and referenced by the
 * symbol layer's `icon-image` — a real symbol layer, per-type color + form,
 * with zero external font/glyph dependency.
 */
 function drawMarkerIcon(type: MapMarker['type']): ImageData {
  const S = 44;
  const c = document.createElement('canvas');
  c.width = S;
  c.height = S;
  const ctx = c.getContext('2d')!;
  const cx = S / 2;
  const cy = S / 2;
  ctx.fillStyle = MARKER_TYPE_INFO[type]?.color ?? '#cbd5e1';
  ctx.strokeStyle = '#0b1220';
  ctx.lineWidth = 2.5;
  ctx.lineJoin = 'round';
  switch (type) {
    case 'city':
      ctx.beginPath();
      ctx.arc(cx, cy, S * 0.3, 0, Math.PI * 2);
      break;
    case 'factory': {
      const h = S * 0.5;
      roundRectPath(ctx, cx - h / 2, cy - h / 2, h, h, 5);
      break;
    }
    case 'army': {
      const r = S * 0.34;
      ctx.beginPath();
      ctx.moveTo(cx, cy - r);
      ctx.lineTo(cx + r, cy + r * 0.8);
      ctx.lineTo(cx - r, cy + r * 0.8);
      ctx.closePath();
      break;
    }
    case 'port': {
      const r = S * 0.36;
      ctx.beginPath();
      ctx.moveTo(cx, cy - r);
      ctx.lineTo(cx + r, cy);
      ctx.lineTo(cx, cy + r);
      ctx.lineTo(cx - r, cy);
      ctx.closePath();
      break;
    }
    case 'capital':
      starPath(ctx, cx, cy, 5, S * 0.36, S * 0.15);
      break;
    case 'fleet':
    case 'gathering':
      ctx.beginPath();
      ctx.arc(cx, cy, S * 0.32, 0, Math.PI * 2);
      break;
    case 'rocket': {
      const w = S * 0.14;
      ctx.beginPath();
      ctx.moveTo(cx, cy - S * 0.36);
      ctx.lineTo(cx + S * 0.22, cy - S * 0.04);
      ctx.lineTo(cx + w, cy - S * 0.04);
      ctx.lineTo(cx + w, cy + S * 0.34);
      ctx.lineTo(cx - w, cy + S * 0.34);
      ctx.lineTo(cx - w, cy - S * 0.04);
      ctx.lineTo(cx - S * 0.22, cy - S * 0.04);
      ctx.closePath();
      break;
    }
  }
  ctx.fill();
  ctx.stroke();
  // fleet and gathering share a circle base; an inner mark tells them apart
  // (fleet = a dark porthole dot, gathering = a white bullseye dot).
  if (type === 'fleet' || type === 'gathering') {
    ctx.beginPath();
    ctx.arc(cx, cy, S * 0.13, 0, Math.PI * 2);
    ctx.fillStyle = type === 'fleet' ? '#0b1220' : '#ffffff';
    ctx.fill();
  }
  // Hand MapLibre the raw pixels (an untainted canvas, so getImageData is safe)
  // rather than the canvas element — `addImage` accepts ImageData directly.
  return ctx.getImageData(0, 0, S, S);
 }
 /** The hover tooltip for a marker: its type label + name, then the owner chip. */
 function markerTooltipHtml(
  type: string,
  name: string,
  owner: string,
  ownerColor: string,
 ): string {
  const label = MARKER_TYPE_INFO[type as MapMarker['type']]?.label ?? 'Marker';
  const ownerLine = owner
    ? `<div class="hm-popup-owner"><span class="hm-chip" style="background:${ownerColor}"></span>${esc(owner)}</div>`
    : '<div class="hm-popup-sub">No owner</div>';
  return `<div class="hm-popup"><div class="hm-popup-title">${esc(label)}: ${esc(name)}</div>${ownerLine}</div>`;
 }
 const esc = (s: string) =>
  s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c] as string));
@@ -254,6 +446,13 @@ interface Props {
   * component doc for the full behavior.
   */
  onFocusNation?: (id: string, info?: { name?: string }) => void;
  /**
   * (v0.27, #44) The game's named map markers (`GameState.markers`): the LLM
   * places/removes them over time, the engine positions each at its region's
   * centroid and keeps its owner in sync with the region's owner. Rendered as
   * a top-most symbol layer (per-type glyph + name, per-type color).
   */
  markers?: MapMarker[];
 }
 /**
@@ -286,6 +485,18 @@ interface Props {
 * a plain "No owner" sub-line. The colors/labels come from the shared
 * `regionFillStyle` / `unownedTooltipLabel` contract in @shared/protocol.
 *
 * (v0.27, #44) LLM-placed **map markers** (`markers` prop = `GameState.markers`)
 * render on a top-most symbol layer: each is its type's canvas-generated icon
 * (a distinct shape, per-type color from the shared `MARKER_TYPE_INFO`
 * contract, dark-outlined) at the engine-derived position (region centroid +
 * small deterministic offset). The icons are drawn into named map images
 * (`marker-<type>`), so there is no external font/glyph dependency and markers
 * render offline and deterministically. Hovering a marker shows a tooltip
 * (type label + name + owner chip); clicking one switches the dossier to the
 * owning nation (no-op when the marker's region is unowned). The region
 * hover/click handlers detect a marker under the cursor (MapLibre layer events
 * have no propagation) and act on the marker's data.
 *
 * Zoom and pan are driven directly by the user (MapLibre wheel/trackpad + drag)
 * — no floating control and no external API.
 */
@@ -297,6 +508,7 @@ export default function WorldMap({
  className,
  unowned,
  onFocusNation,
  markers,
 }: Props) {
  const containerRef = useRef<HTMLDivElement>(null);
  const mapRef = useRef<maplibregl.Map | null>(null);
@@ -311,12 +523,14 @@ export default function WorldMap({
  const presetRef = useRef(presetId);
  const unownedRef = useRef<Set<string>>(new Set(unowned ?? []));
  const onFocusNationRef = useRef(onFocusNation);
  const markersRef = useRef<MapMarker[]>(markers ?? []);
  regionsRef.current = regions;
  nationsRef.current = nations;
  playerRef.current = playerNationId;
  presetRef.current = presetId;
  unownedRef.current = new Set(unowned ?? []);
  onFocusNationRef.current = onFocusNation;
  markersRef.current = markers ?? [];
  // Diffing state for the transient territory-change flash (owned by this component
  // so a resync with identical data never re-flashes).
@@ -424,6 +638,39 @@ export default function WorldMap({
    const onHover = (e: maplibregl.MapLayerMouseEvent) => {
      const f = e.features?.[0];
      if (!f) return;
      // (v0.27, #44) A marker rendered on top of this region wins the hover.
      // The region polygon is always beneath a marker, so this FILL_LAYER
      // delegate fires in both cases; if a marker icon is under the cursor,
      // show the marker's tooltip (name + type + owner) instead of the
      // region's. `e.point` is the cursor's pixel position, so querying the
      // marker layer there tests the icon's (small) hit area, not the whole
      // region.
      const markerHits = map.queryRenderedFeatures(e.point, { layers: [MARKER_SYMBOL] });
      if (markerHits.length > 0) {
        const mp = (markerHits[0].properties ?? {}) as {
          type?: string;
          name?: string;
          owner?: string;
          ownerColor?: string;
        };
        hoverPopup
          .setLngLat(e.lngLat)
          .setHTML(
            markerTooltipHtml(
              typeof mp.type === 'string' ? mp.type : '',
              typeof mp.name === 'string' ? mp.name : '',
              typeof mp.owner === 'string' ? mp.owner : '',
              typeof mp.ownerColor === 'string' ? mp.ownerColor : '',
            ),
          )
          .addTo(map);
        map.getCanvas().style.cursor = 'pointer';
        // A marker has no region outline to highlight; clear the previous one
        // (and reset lastHoverId so moving back onto a region re-triggers it).
        lastHoverId = null;
        (map.getSource(HOVER_SOURCE) as GeoSource | undefined)?.setData(emptyFC());
        return;
      }
      const p = f.properties as { name?: string; regionId?: string };
      const subId = typeof p?.regionId === 'string' ? p.regionId : '';
      if (subId && subId !== lastHoverId) {
@@ -466,6 +713,19 @@ export default function WorldMap({
    const onClick = (e: maplibregl.MapLayerMouseEvent) => {
      const f = e.features?.[0];
      if (!f) return;
      // (v0.27, #44) A marker under the cursor: focus its owning nation
      // (identical to its region's owner — the engine keeps a marker's owner in
      // sync with the region) and carry the marker's name into the dossier.
      const markerHits = map.queryRenderedFeatures(e.point, { layers: [MARKER_SYMBOL] });
      if (markerHits.length > 0) {
        const mp = (markerHits[0].properties ?? {}) as { ownerId?: string; name?: string };
        const owner = typeof mp.ownerId === 'string' ? mp.ownerId : '';
        if (owner) {
          const info = typeof mp.name === 'string' ? { name: mp.name } : undefined;
          onFocusNationRef.current?.(owner, info);
        }
        return;
      }
      const region = mapFeatureOwner(regionsRef.current, f);
      if (!region?.ownerId) return;
      // Carry the clicked sub-region's name so the dossier can show which region
@@ -497,6 +757,9 @@ export default function WorldMap({
      if (!map.getSource(FLASH_SOURCE)) {
        map.addSource(FLASH_SOURCE, { type: 'geojson', data: emptyFC() });
      }
      if (!map.getSource(MARKERS_SOURCE)) {
        map.addSource(MARKERS_SOURCE, { type: 'geojson', data: emptyFC() });
      }
    };
    // Stamp ownership + colors onto the regions source (no-op until both the
@@ -509,6 +772,26 @@ export default function WorldMap({
      src.setData(applyRegions(geo, regionsRef.current, playerRef.current, idKey, unownedRef.current));
    };
    // Stamp the current markers onto the marker source (v0.27, #44).
    const paintMarkers = () => {
      const src = map.getSource(MARKERS_SOURCE) as GeoSource | undefined;
      if (!src) return;
      src.setData(buildMarkersFC(markersRef.current, nationsRef.current));
    };
    // Register the eight canvas-generated marker-type icon images (v0.27, #44).
    // Images are cleared on a style (re)load, so this is (re)run from
    // `ensureLayers` (which fires on every `styledata`). Self-contained — no
    // external font/glyph endpoint — so markers render offline and
    // deterministically.
    const ensureMarkerImages = async () => {
      for (const type of MARKER_TYPES) {
        const id = `marker-${type}`;
        if (map.getImage(id)) continue;
        await map.addImage(id, drawMarkerIcon(type));
      }
    };
    const ensureLayers = async () => {
      if (cancelled) return;
      ensureSources();
@@ -528,6 +811,7 @@ export default function WorldMap({
      }
      if (cancelled) return;
      paintRegions();
      paintMarkers();
      if (!map.getLayer(FILL_LAYER)) {
        // The choropleth is the star: a high opacity so the vivid per-nation
        // colors read clearly even on the dark background / over the terrain.
@@ -554,8 +838,9 @@ export default function WorldMap({
      }
      // NOTE: layers are added in bottom→top order (each appends on top). The
      // stack is: fill, base borders, player border, territory-change flash,
-      // hover brighten, hover outline. Do not use a `beforeId` here — it throws
+      // hover brighten, hover outline, and (top-most) the LLM-placed map
-      // if that layer does not exist yet on a fresh style load.
+      // markers' symbol layer (v0.27, #44). Do not use a `beforeId` here — it
      // throws if that layer does not exist yet on a fresh style load.
      if (!map.getLayer(PLAYER_LINE)) {
        map.addLayer({
          id: PLAYER_LINE,
@@ -589,6 +874,36 @@ export default function WorldMap({
          paint: { 'line-color': '#ffffff', 'line-width': 1.6, 'line-opacity': 0.9 },
        });
      }
      // (v0.27, #44) The LLM-placed map markers: a top-most symbol layer.
      // Each marker renders its type's canvas-generated icon (a distinct shape,
      // per-type color from the shared MARKER_TYPE_INFO contract) with a dark
      // outline for legibility on any choropleth fill. The icon images are
      // self-contained (no external font/glyph endpoint), so markers render
      // offline and deterministically. `icon-image` is `marker-<type>`, the
      // named canvas images registered by `ensureMarkerImages` above.
      await ensureMarkerImages();
      if (!map.getLayer(MARKER_SYMBOL)) {
        map.addLayer({
          id: MARKER_SYMBOL,
          type: 'symbol',
          source: MARKERS_SOURCE,
          layout: {
            'icon-image': ['concat', 'marker-', ['get', 'type']],
            'icon-size': 0.8,
            'icon-allow-overlap': true,
            'icon-ignore-placement': true,
          },
        });
      }
      // Marker interactions: the markers sit above the choropleth, but they
      // deliberately share the region (FILL_LAYER) handlers registered below.
      // MapLibre layer-scoped events are independent per-layer delegates (no
      // propagation, no stopPropagation), so a marker-on-region would fire
      // both a marker and a region handler. Instead the region handlers detect
      // a marker under the cursor (see onHover/onClick) and act on the
      // marker's data; clicking a marker focuses its owning nation via the
      // same path as clicking its region (the marker's owner == its region's
      // owner).
      map.off('mousemove', FILL_LAYER, onHover);
      map.off('mouseout', FILL_LAYER, onHoverOut);
      map.off('click', FILL_LAYER, onClick);
@@ -646,6 +961,19 @@ export default function WorldMap({
    }
  }, [regions, playerNationId, unowned]);
  // (v0.27, #44) Repaint the marker symbol layer whenever the marker list
  // changes (a turn placed/removed markers) or the nations record changes
  // (a confirmed rename/merge changes an owner's display name). No-op until
  // the map + source exist (the mount effect's ensureLayers applies the
  // current data once the layer structure is in place).
  useEffect(() => {
    const map = mapRef.current;
    if (!map) return;
    const src = map.getSource(MARKERS_SOURCE) as GeoSource | undefined;
    if (!src) return;
    src.setData(buildMarkersFC(markers ?? [], nations));
  }, [markers, nations]);
  // Full-viewport, edge-to-edge background layer. `position: fixed` is set
  // inline because MapLibre's own stylesheet sets `.maplibregl-map` to
  // `position: relative`, which would otherwise win over a Tailwind class.