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).
2026-10-14 22:37:29 +00:00
parent aa1bd3c5aa
commit a129c2ab81
19 changed files with 10437 additions and 45 deletions
@@ -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);
+  });
+});