v0.27.0 (#44): LLM-placed named map point markers

- shared: 8 MarkerTypes + MARKER_TYPE_INFO (label/color/glyph); MapMarker;
  GameState.markers (required, [] at init); TurnResult.markers {add,remove};
  MarkerSpec/MarkerInfo; FNV-1a 4-char markerId; MAX_MARKERS=400.
- data: new public/region-centroids.json (1,800 anchors = largest-part centroid
  + spread ~0.1x min-bbox) built by new idempotent scripts/build-region-centroids.mjs.
- server: regions.ts centroid loader (public/ then dist/); engine applyTurnResult
  marker ops (remove -> owner-recompute -> add, jitter, cap, never throws);
  prompt documents the contract; buildUserPrompt carries markers; stub marker-free.
- client: WorldMap symbol layer rendered as canvas per-type icons (glyph CDN dead);
  hover tooltip shows name; click focuses owning nation.
- tests: 168 -> 189 (centroids script, regions centroids, db legacy, engine markers).

AGENTS.md

@@ -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
-│   └── *.test.ts           # turf-free vitest tests pinning the dataset + both manifests
+│   │                       #   → build-region-adjacency → build-region-centroids
+│   └── *.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