@diagrammo/dgmo 0.46.0 → 0.48.0

package/src/map/diagnostics.ts

@@ -1,134 +0,0 @@
-// Map chart-type diagnostic catalog.
-//
-// The map resolver (`./resolver.ts`) emits every coded diagnostic through the
-// shared `emit(spec, line, params)` helper against the keyed specs below — the
-// wording lives here ONLY, never re-typed at the call site. Consumers (CLI
-// `diagnostics`, console error-review, MCP `validate_diagram`, spec docs)
-// enumerate map diagnostics via `MAP_DIAGNOSTICS` alongside every other chart
-// type's `DiagnosticSpec`.
-//
-// Every `message` builder tolerates being called with `{}` (renders a
-// representative message with empty placeholders) per the DiagnosticSpec
-// contract.
-
-import type { DiagnosticSpec } from '../diagnostics';
-
-/** Keyed specs — referenced by the resolver's `emit()` call sites. */
-export const MAP_DX = {
-  // Runtime severity: 'error' (matches E_ prefix). ONE code, THREE distinct
-  // emit sites in resolver.ts. The builder switches on params:
-  //   • `iso` present → `No subdivision "<name>" in scope <scope> (it is <iso>).`
-  //     (region names a state but the explicit US-XX scope points elsewhere)
-  //   • `place: true` → `No "<name>" found in scope <scope>.`
-  //     (a scoped POI/place lookup misses)
-  //   • otherwise (and for the `{}` catalog render) → the REPRESENTATIVE
-  //     region-scope-miss wording `No region "<name>" found in scope <scope>.`
-  SCOPE_MISS: {
-    code: 'E_MAP_SCOPE_MISS',
-    severity: 'error',
-    chartType: 'map',
-    title: 'No match in the given scope',
-    message: (p) =>
-      p.iso !== undefined
-        ? `No subdivision "${p.name ?? ''}" in scope ${p.scope ?? ''} (it is ${p.iso}).`
-        : p.place
-          ? `No "${p.name ?? ''}" found in scope ${p.scope ?? ''}.`
-          : `No region "${p.name ?? ''}" found in scope ${p.scope ?? ''}.`,
-    hint: 'Drop or correct the scope qualifier, or use an ISO code / coordinates.',
-    example: 'map\nGeorgia US-CA heat: 2',
-  },
-  UNKNOWN_AIRPORT_CODE: {
-    // Runtime severity: 'error' (matches E_ prefix).
-    code: 'E_MAP_UNKNOWN_AIRPORT_CODE',
-    severity: 'error',
-    chartType: 'map',
-    title: 'Unknown airport code',
-    message: (p) =>
-      `Unknown airport code "${p.code ?? ''}" — not in the bundled airport set (large hubs + US commercial). Use coordinates with \`as ${p.code ?? ''}\` if you need it.`,
-    hint: 'A 3-letter token that is not a bundled IATA code — supply coordinates with `poi <lat> <lon> as <CODE>`.',
-    example: 'map\npoi ZZZ',
-  },
-  UNKNOWN_PLACE: {
-    // Runtime severity: 'error' (matches E_ prefix). `hint` (a "did you mean?"
-    // suggestion) is interpolated only when a near match exists.
-    code: 'E_MAP_UNKNOWN_PLACE',
-    severity: 'error',
-    chartType: 'map',
-    title: 'Unknown place',
-    message: (p) =>
-      `Unknown place "${p.name ?? ''}" — not in the gazetteer.${p.hint ? ' ' + p.hint : ''} Search the exact token with \`dgmo map-search "${p.name ?? ''}"\` (or the lookup_map_location tool), or use coordinates \`poi <lat> <lon>\`.`,
-    hint: 'The POI name is not in the gazetteer — check spelling or use coordinates.',
-    example: 'map\npoi Nowheresville',
-  },
-  UNKNOWN_SUBDIVISION: {
-    // Runtime severity: 'error' (matches E_ prefix). `hint` (a "did you mean?"
-    // suggestion) is interpolated only when a near match exists.
-    code: 'E_MAP_UNKNOWN_SUBDIVISION',
-    severity: 'error',
-    chartType: 'map',
-    title: 'Unknown region',
-    message: (p) =>
-      `Unknown region "${p.name ?? ''}" — not a known country or US state.${p.hint ? ' ' + p.hint : ''} Search the exact token with \`dgmo map-search "${p.name ?? ''}"\` (or the lookup_map_location tool), use an ISO code (e.g. FR, US-CA), or coordinates.`,
-    hint: 'The region is neither a known country nor a US state — check spelling or use an ISO code.',
-    example: 'map\nBavaria heat: 1',
-  },
-  AIRPORT_SHADOWED_BY_CITY: {
-    // Runtime severity: 'warning' (matches W_ prefix). Non-blocking, emitted at
-    // most once per shadowed IATA code.
-    code: 'W_MAP_AIRPORT_SHADOWED_BY_CITY',
-    severity: 'warning',
-    chartType: 'map',
-    title: 'Airport code shadowed by a city',
-    message: (p) =>
-      `"${p.name ?? ''}" resolved to the city; "${p.code ?? ''}" is also an airport code. Use coordinates with \`as ${p.code ?? ''}\` for the airport.`,
-    hint: 'A city won a token that is also a bundled airport code — use coordinates with `as <CODE>` for the airport.',
-    example: 'map\npoi Ufa',
-  },
-  AMBIGUOUS_NAME: {
-    // Runtime severity: 'warning' (matches W_ prefix).
-    code: 'W_MAP_AMBIGUOUS_NAME',
-    severity: 'warning',
-    chartType: 'map',
-    title: 'Ambiguous place name',
-    message: (p) =>
-      `"${p.name ?? ''}" is ambiguous — resolved to the most-populous match. Set a default with \`locale <ISO>\` (e.g. \`locale US\` / \`locale US-GA\`) to steer it.`,
-    hint: 'Multiple places share this name — add a scope or `locale <ISO>` to steer it.',
-    example: 'map\npoi Portland',
-  },
-  DUPLICATE_POI: {
-    // Runtime severity: 'warning' (matches W_ prefix). Only a declared-over-
-    // declared collision warns; an implicit endpoint never triggers it.
-    code: 'W_MAP_DUPLICATE_POI',
-    severity: 'warning',
-    chartType: 'map',
-    title: 'Duplicate POI',
-    message: (p) => `Duplicate POI "${p.id ?? ''}" — last definition wins.`,
-    hint: 'Two POIs resolved to the same id — remove one or give it a distinct alias.',
-    example: 'map\npoi Tokyo\npoi Tokyo',
-  },
-  DUPLICATE_REGION: {
-    // Runtime severity: 'warning' (matches W_ prefix).
-    code: 'W_MAP_DUPLICATE_REGION',
-    severity: 'warning',
-    chartType: 'map',
-    title: 'Duplicate region',
-    message: (p) =>
-      `Duplicate region "${p.name ?? ''}" — last definition wins.`,
-    hint: 'The same region is defined twice — remove the earlier definition.',
-    example: 'map\nCalifornia heat: 1\nCalifornia heat: 9',
-  },
-  REGION_AMBIGUOUS: {
-    // Runtime severity: 'warning' (matches W_ prefix). Suppressed under a US
-    // scope (`locale US`, an explicit ISO scope, or another US-state reference).
-    code: 'W_MAP_REGION_AMBIGUOUS',
-    severity: 'warning',
-    chartType: 'map',
-    title: 'Region is both a country and a US state',
-    message: (p) =>
-      `"${p.name ?? ''}" is both a country and a US state — resolved as ${p.layer ?? ''} (${p.chosenId ?? ''}). Pin it with an ISO code (${p.stateId ?? ''} / ${p.countryId ?? ''}) or name + scope ("${p.name ?? ''} US" / "${p.name ?? ''} ${p.countryId ?? ''}").`,
-    hint: 'The name collides between a country and a US state — pin it with an ISO code or a `US` / `US-XX` scope.',
-    example: 'map\nGeorgia heat: 2',
-  },
-} satisfies Record<string, DiagnosticSpec>;
-
-export const MAP_DIAGNOSTICS: DiagnosticSpec[] = Object.values(MAP_DX);

package/src/map/dimensions.ts

@@ -1,150 +0,0 @@
-// Content-aware export dimensions for maps (§ export-content-aspect).
-//
-// Outside the app — CLI, MCP, SSG embeds (remark/astro/docusaurus/fumadocs), and
-// Obsidian — maps were rendered into a fixed 1200×800 canvas. A world map is
-// ~2.3:1, so the global stretch-fill distorted it vertically to fill the too-tall
-// box. These helpers derive the canvas HEIGHT from the map's intrinsic projected
-// aspect so the export matches the content's natural shape.
-//
-// dgmo emits the intrinsic aspect; the host context decides display fit (Obsidian
-// sets the embedded <svg> to width:100% + aspect-ratio from the viewBox). Aspect
-// is the invariant; `baseWidth` is just a resolution knob.
-import { geoPath } from 'd3-geo';
-import { TITLE_FONT_SIZE, TITLE_Y } from '../utils/title-constants';
-import { buildMapProjection } from './layout';
-import type { ResolvedMap } from './resolved-types';
-import type { MapData } from './resolved-types';
-
-// Mirror the layout constants so the chrome reserve matches what the renderer
-// actually reserves (layout.ts FIT_PAD / TITLE_GAP).
-const FIT_PAD = 24;
-const TITLE_GAP = 16;
-
-// Clamp guardrails (w/h). The clamp is for PATHOLOGICAL extents, not the common
-// case — world/continent/country must land at their true projected aspect.
-//   ASPECT_MAX = 3.0  → never wider/shorter than 3:1. The default world projection
-//                       is EQUIRECTANGULAR (see resolver.ts ~L744); a full-world
-//                       extent measures ~2.4:1 and a narrower-latitude world up to
-//                       ~2.65:1 — all comfortably under 3.0, so any reasonable world
-//                       renders at its true aspect (no letterbox). Only a genuinely
-//                       extreme >3:1 band (e.g. a thin trans-global route) is clamped.
-//   ASPECT_MIN = 0.9  → never taller than ~1:1.1, so a tall country embedded at
-//                       width:100% in a narrow note column stays sane.
-const ASPECT_MAX = 3.0;
-const ASPECT_MIN = 0.9;
-// Deliberate vertical boost for GLOBAL (whole-world) extents only. An honest
-// whole-world projection is ~2.4:1, which reads as a flat letterbox band. We emit
-// a canvas this fraction taller and let the global stretch-fill (layout.ts) fill
-// the extra height — the projected land stretches ~12% taller while POI radii and
-// label fonts (applied in the renderer, not here) stay un-squashed. US, regional,
-// and non-global extents are untouched (they keep their true projected aspect).
-const GLOBAL_HEIGHT_BOOST = 1.12;
-// Minimum px of actual map area (below the chrome band) — keeps a short canvas
-// (very wide extent) from being crowded out by the title/caption.
-const MIN_MAP_BAND = 200;
-// Defensive fallback when the content aspect is non-finite (NaN/0/Infinity). The
-// resolver always pads the extent to a non-degenerate box, so in practice this is
-// not reached via the public pipeline — it guards a degenerate `fitTarget` directly.
-const FALLBACK_ASPECT = 1.5; // 3:2
-// Square reference box for aspect measurement. Uniform `fitSize` scaling makes the
-// measured aspect invariant to this value — it MUST be square (a non-square box
-// would leak into the ratio).
-const REF = 1000;
-
-/** The map's intrinsic projected aspect (width / height) for a resolved map.
- *
- *  Measured by fitting the projection + fit target (the SAME `buildMapProjection`
- *  output the renderer draws with) into a square reference box and reading the
- *  projected bounds of the fit target. `fitSize` scales uniformly, so the ratio is
- *  independent of the box size (see the reference-box invariance test).
- *
- *  Returns {@link FALLBACK_ASPECT} (3:2) if the result is non-finite or ≤ 0 — the
- *  helper never emits a NaN/0/Infinity aspect. */
-export function mapContentAspect(
-  resolved: ResolvedMap,
-  data: MapData,
-  /** Square reference box for the measurement. Uniform `fitSize` scaling makes the
-   *  result invariant to this value; exposed only so tests can assert that. */
-  ref = REF
-): number {
-  const { projection, fitTarget } = buildMapProjection(resolved, data);
-  projection.fitSize([ref, ref], fitTarget as never);
-  const b = geoPath(projection).bounds(fitTarget as never);
-  const w = b[1][0] - b[0][0];
-  const h = b[1][1] - b[0][1];
-  const aspect = w / h;
-  return Number.isFinite(aspect) && aspect > 0 ? aspect : FALLBACK_ASPECT;
-}
-
-/** Content-aware export dimensions for a map: `width` fixed at `baseWidth`,
- *  `height` derived from the clamped intrinsic aspect, with a minimum-map-band
- *  floor for very wide extents. `preferContain` is true when the clamp or floor
- *  forced the canvas off the content aspect — the renderer then contain-fits
- *  (letterbox) instead of stretching, so the off-aspect canvas doesn't re-distort. */
-export interface MapExportDimensions {
-  readonly width: number;
-  readonly height: number;
-  readonly preferContain: boolean;
-}
-
-export function mapExportDimensions(
-  resolved: ResolvedMap,
-  data: MapData,
-  baseWidth = 1200,
-  /** WYSIWYG override (app export): the live preview pane's displayed aspect
-   *  (width / height). When provided, the canvas adopts it verbatim and
-   *  stretch-fills (no clamp, no contain) so the PNG matches exactly what's on
-   *  screen. Omitted by every headless consumer (CLI / MCP / SSG / Obsidian),
-   *  which keep the intrinsic-aspect sizing below. */
-  aspectOverride?: number
-): MapExportDimensions {
-  const useOverride =
-    aspectOverride !== undefined &&
-    Number.isFinite(aspectOverride) &&
-    aspectOverride > 0;
-  const raw = useOverride ? aspectOverride : mapContentAspect(resolved, data);
-  // Whole-world extents get the vertical boost (a taller canvas the global
-  // stretch-fill then fills). `fitIsGlobal` is the SAME classification the layout
-  // uses to decide stretch-fill vs contain, so the two always agree. The override
-  // path (app WYSIWYG) and non-global extents pass through at their true aspect.
-  const isGlobal =
-    !useOverride && buildMapProjection(resolved, data).fitIsGlobal;
-  // The target the renderer should hit BEFORE the pathological clamp: the boosted
-  // aspect for global views, the raw aspect otherwise. preferContain compares the
-  // clamp against THIS (not raw) so the deliberate boost never trips the letterbox.
-  const target = isGlobal ? raw / GLOBAL_HEIGHT_BOOST : raw;
-  // The override is the user's on-screen aspect — honour it as-is (no clamp);
-  // only the intrinsic path guards against pathological extents.
-  const clamped = useOverride
-    ? raw
-    : Math.max(ASPECT_MIN, Math.min(ASPECT_MAX, target));
-  const width = baseWidth;
-  let height = Math.round(width / clamped);
-
-  // Chrome reserve mirrors layout.ts `topPad` EXACTLY — the only chrome the layout
-  // actually subtracts from the map's fit box. The top banner reserves space ONLY
-  // when a title AND POIs are present (a POI-less choropleth lets the title overlay
-  // the land). The legend (foreground, top-center) and the caption (drawn at
-  // height-8, overlapping the bottom) reserve NO layout height in the renderer, so
-  // they are deliberately excluded — adding them would over-reserve.
-  let chromeReserve = 0;
-  if (resolved.title && resolved.pois.length > 0) {
-    const bannerBottom =
-      (resolved.subtitle ? TITLE_Y + TITLE_FONT_SIZE : TITLE_Y) +
-      TITLE_FONT_SIZE / 2;
-    chromeReserve += Math.max(FIT_PAD, bannerBottom + TITLE_GAP) - FIT_PAD;
-  }
-
-  let floored = false;
-  if (height - chromeReserve < MIN_MAP_BAND) {
-    height = Math.round(chromeReserve + MIN_MAP_BAND);
-    floored = true;
-  }
-
-  // The canvas was forced off the content aspect ⇒ tell the renderer to
-  // contain-fit (letterbox) rather than stretch-distort. The WYSIWYG override is
-  // exempt: it stretch-fills (mirroring the preview pane) unless the MIN_MAP_BAND
-  // floor had to grow the canvas off-aspect.
-  const preferContain = useOverride ? floored : clamped !== target || floored;
-  return { width, height, preferContain };
-}

package/src/map/geo-query.ts

@@ -1,295 +0,0 @@
-// Map geo-query (step-5 inspector backend). A SEPARATE entry from the renderer:
-// `renderMap` returns void + mutates the DOM, so it cannot hand back a query
-// handle. `createMapGeoQuery` re-runs the deterministic parse→resolve→layout
-// pipeline (cheap, lazy — only when the app arms Inspect) and wraps the fitted
-// projection captured on the layout, exposing:
-//   - invert(px,py)  — composite/stretch-aware pixel → [lon,lat]
-//   - project(lonLat) — [lon,lat] → pixel (re-project pins/markers each render)
-//   - locate(px,py)  — ONE unified result card (coords + reverse-geocode + tokens)
-//   - cities(extent?) — culled + projected gazetteer cities for the all-cities layer
-//
-// DI: `data: MapData` is injected by the caller (the Node-only `loadMapData` is
-// never called here), so this is browser-safe — no `node:fs`, no boundary
-// TopoJSON pulled into the synchronous render bundle (F7/AC15).
-import type { PaletteColors } from '../palettes/types';
-import { parseMap } from './parser';
-import { resolveMap } from './resolver';
-import { layoutMap } from './layout';
-import type { MapLayout } from './layout';
-import { decodeFeatures, regionAt } from './geo';
-import type { DecodedFeature } from './geo';
-import { pixelToLonLat, lonLatToPixel } from './invert';
-import type { MapData, GeoExtent } from './resolved-types';
-import type { Gazetteer } from './data/types';
-import type { DgmoError } from '../diagnostics';
-
-/** Nearest gazetteer city to a point: the real haversine distance, plus the
- *  canonical name + ISO + (US-only) subdivision for token shaping. `lon`/`lat`
- *  are the city's own gazetteer coordinates (so callers can mark it on the map,
- *  distinct from the inspected point). */
-export interface NearestCity {
-  readonly name: string;
-  readonly iso: string;
-  readonly sub?: string;
-  readonly distanceKm: number;
-  readonly lon: number;
-  readonly lat: number;
-}
-
-/** A region declaration with its canonical/primary form plus bare alternates
- *  (behind the card's "other forms" expander). */
-export interface RegionToken {
-  /** Explicit scoped form, shown first (`Florida US-FL` / `France FR`). */
-  readonly primary: string;
-  /** Bare forms (bare ISO, bare code, bare name). */
-  readonly alternates: string[];
-}
-
-/** Paste-ready DGMO tokens for one inspected point — each round-trips through the
- *  map parser with zero diagnostics (the app inserts verbatim, never synthesizes
- *  syntax). */
-export interface ResultTokens {
-  /** Positional POI line, e.g. `poi 40.7608 -111.891` (NEVER `@lat,lon`). */
-  readonly coordPoiLine: string;
-  /** US-state region tokens — null when the click isn't in a US state. */
-  readonly state: RegionToken | null;
-  /** Country region tokens — null over open ocean (no country). */
-  readonly country: RegionToken | null;
-  /** Scoped city token (`New York US-NY` / `Paris FR`), or a bare ambiguous name. */
-  readonly city: { readonly token: string; readonly ambiguous: boolean } | null;
-}
-
-/** The single unified Inspect result. */
-export interface ResultCard {
-  readonly lonLat: [number, number];
-  readonly country: { iso: string; name: string } | null;
-  readonly state: { iso: string; name: string } | null;
-  readonly nearestCity: NearestCity | null;
-  readonly tokens: ResultTokens;
-}
-
-/** A gazetteer city projected to screen pixels for the all-cities overlay. */
-export interface ProjectedCity {
-  readonly name: string;
-  readonly iso: string;
-  readonly sub?: string;
-  readonly lon: number;
-  readonly lat: number;
-  readonly px: number;
-  readonly py: number;
-  readonly pop: number;
-}
-
-export interface MapGeoQuery {
-  /** Pixel → `[lon,lat]`, or null for an out-of-domain pixel. */
-  invert(px: number, py: number): [number, number] | null;
-  /** `[lon,lat]` → pixel, or null if it projects nowhere. */
-  project(lonLat: readonly [number, number]): [number, number] | null;
-  /** One click → the unified result card, or null if the pixel inverts to
-   *  nothing (graceful "no location"). */
-  locate(px: number, py: number): ResultCard | null;
-  /** Culled + projected cities for the all-cities layer (population-primary). */
-  cities(extent?: GeoExtent): ProjectedCity[];
-  /** Layout-time, dimension-dependent diagnostics. They live on the geo-query
-   *  (bound to the rendered layout) rather than the resolver. Callers merge them
-   *  with `resolved.diagnostics`. (No producers currently — always empty.) */
-  readonly diagnostics: readonly DgmoError[];
-}
-
-export interface CreateMapGeoQueryOptions {
-  readonly content: string;
-  readonly width: number;
-  readonly height: number;
-  /** Injected map assets — same `MapData` the app passes to `renderMap`. */
-  readonly data: MapData;
-  /** Same palette/isDark the app renders with (geometry is palette-independent,
-   *  but `layoutMap` mandates them). */
-  readonly palette: PaletteColors;
-  readonly isDark: boolean;
-}
-
-const EARTH_R_KM = 6371;
-const DEG = Math.PI / 180;
-
-/** Great-circle distance in km (haversine; no d3 dependency). */
-function haversineKm(
-  lat1: number,
-  lon1: number,
-  lat2: number,
-  lon2: number
-): number {
-  const dLat = (lat2 - lat1) * DEG;
-  const dLon = (lon2 - lon1) * DEG;
-  const a =
-    Math.sin(dLat / 2) ** 2 +
-    Math.cos(lat1 * DEG) * Math.cos(lat2 * DEG) * Math.sin(dLon / 2) ** 2;
-  return 2 * EARTH_R_KM * Math.asin(Math.min(1, Math.sqrt(a)));
-}
-
-// Each decade of population is worth this many km of "pull" — so a notable city
-// a little farther beats a tiny suburb that's technically closer (A4). Tuned so
-// a ~200k-pop city (log10≈5.3) outranks a ~5k hamlet (log10≈3.7) within ~20 km.
-const POP_PULL_KM = 12;
-
-/** Nearest gazetteer city, blending true distance with notability (A4). Returns
- *  the chosen city's REAL `distanceKm` regardless of the ranking blend (F4). */
-function nearestCity(
-  lonLat: readonly [number, number],
-  gazetteer: Gazetteer
-): NearestCity | null {
-  const [lon, lat] = lonLat;
-  let best: { score: number; idx: number; dist: number } | null = null;
-  const cities = gazetteer.cities;
-  for (let i = 0; i < cities.length; i++) {
-    const c = cities[i]!;
-    const dist = haversineKm(lat, lon, c[0], c[1]);
-    const score = dist - POP_PULL_KM * Math.log10((c[3] || 0) + 1);
-    if (!best || score < best.score) best = { score, idx: i, dist };
-  }
-  if (!best) return null;
-  const c = cities[best.idx]!;
-  return {
-    name: c[4],
-    iso: c[2],
-    ...(c[5] !== undefined && { sub: c[5] }),
-    distanceKm: best.dist,
-    lat: c[0],
-    lon: c[1],
-  };
-}
-
-/** Round a coordinate to 2 dp (≈1 km — within a pixel even at single-state zoom;
- *  a POI dot is 6+ px wide, so more decimals are false precision invisible on the
- *  rendered map). */
-function roundCoord(n: number): number {
-  return Number(n.toFixed(2));
-}
-
-/** Build the paste-ready tokens for one inspected point. Display name + ISO come
- *  from the matched boundary feature itself (no `region-names.json` dependency).*/
-function buildTokens(
-  lonLat: readonly [number, number],
-  region: {
-    country: { iso: string; name: string } | null;
-    state: { iso: string; name: string } | null;
-  },
-  city: NearestCity | null
-): ResultTokens {
-  const coordPoiLine = `poi ${roundCoord(lonLat[1])} ${roundCoord(lonLat[0])}`;
-
-  // Region token forms are validated against the RESOLVER, not just the parser
-  // (a token can parse yet fail to resolve). Verified resolving forms:
-  //   - US state: `Florida US-FL` (scoped) and bare `US-FL` / `Florida`. NOTE a
-  //     bare 2-letter code (`FL`) is REJECTED ("Unknown subdivision") — only the
-  //     `US-FL` form resolves — so it is intentionally NOT offered.
-  //   - Country: the BARE name (`United States of America`) or bare ISO (`US`).
-  //     The scoped `<name> <iso>` form does NOT resolve for a country whose
-  //     subdivisions are loaded (the scope makes the resolver hunt for a
-  //     SUBDIVISION named after the country) — so a country leads with its name.
-  let stateTok: RegionToken | null = null;
-  if (region.state) {
-    const { iso, name } = region.state; // iso like `US-FL`
-    stateTok = { primary: `${name} ${iso}`, alternates: [iso, name] };
-  }
-
-  let countryTok: RegionToken | null = null;
-  if (region.country) {
-    const { iso, name } = region.country; // iso like `FR` / `US`
-    countryTok = { primary: name, alternates: [iso] };
-  }
-
-  // The nearest-city row inserts a POI for that city, so the token is a POSITIONAL
-  // `poi <City> <scope>` line — a bare `<City> <scope>` would parse as a REGION
-  // declaration and fail to resolve. Scope = the US subdivision (US-only), else
-  // the country ISO; bare `poi <City>` when neither disambiguates.
-  let cityTok: ResultTokens['city'] = null;
-  if (city) {
-    const scope = city.sub ?? (city.iso || '');
-    cityTok = scope
-      ? { token: `poi ${city.name} ${scope}`, ambiguous: false }
-      : { token: `poi ${city.name}`, ambiguous: true };
-  }
-
-  return { coordPoiLine, state: stateTok, country: countryTok, city: cityTok };
-}
-
-const MAX_CITY_DOTS = 250;
-
-/** Construct a geo-query handle bound to the layout for `(content, width,
- *  height, data, palette, isDark)`. Deterministic: identical inputs ⇒ the same
- *  fitted projection the rendered SVG used, so inverted clicks align.
- *
- *  INVARIANT: this is the PREVIEW path — it never passes `preferContain`, so its
- *  layout matches the in-app preview (stretch-fill), where geo-query is used. It is
- *  NOT valid against a content-aware EXPORT canvas (which may set `preferContain` →
- *  contain-fit): the inverted positions would not match that export's pixels. If
- *  geo-query is ever pointed at an export canvas, thread `preferContain` through
- *  `CreateMapGeoQueryOptions` to keep the projection in sync. */
-export function createMapGeoQuery(opts: CreateMapGeoQueryOptions): MapGeoQuery {
-  const { content, width, height, data, palette, isDark } = opts;
-  const resolved = resolveMap(parseMap(content), data);
-  const layout: MapLayout = layoutMap(
-    resolved,
-    data,
-    { width, height },
-    { palette, isDark }
-  );
-
-  // Decode the boundary features ONCE (review L3) — country containment against
-  // world-detail (50m); US-state against us-states (10m).
-  const countries: DecodedFeature[] = decodeFeatures(data.worldDetail);
-  const states: DecodedFeature[] = decodeFeatures(data.usStates);
-  const gazetteer = data.gazetteer;
-
-  const invert = (px: number, py: number): [number, number] | null =>
-    pixelToLonLat(layout, px, py);
-  const project = (
-    lonLat: readonly [number, number]
-  ): [number, number] | null => lonLatToPixel(layout, lonLat);
-
-  const locate = (px: number, py: number): ResultCard | null => {
-    const lonLat = invert(px, py);
-    if (!lonLat) return null;
-    const region = regionAt(lonLat, countries, states);
-    const city = nearestCity(lonLat, gazetteer);
-    return {
-      lonLat,
-      country: region.country,
-      state: region.state,
-      nearestCity: city,
-      tokens: buildTokens(lonLat, region, city),
-    };
-  };
-
-  const cities = (extent?: GeoExtent): ProjectedCity[] => {
-    // Population-primary cull (extent only a coarse secondary filter — review
-    // L-NEW-3): the data extent is NOT the visible viewport when a wide map is
-    // scrolled, so rank by population and cap, keeping only on-canvas dots.
-    const sorted = [...gazetteer.cities].sort((a, b) => b[3] - a[3]);
-    const out: ProjectedCity[] = [];
-    for (const c of sorted) {
-      const [lat, lon, iso, pop, name, sub] = c;
-      if (extent) {
-        const [[w, s], [e, n]] = extent;
-        if (lon < w || lon > e || lat < s || lat > n) continue;
-      }
-      const p = project([lon, lat]);
-      if (!p) continue;
-      if (p[0] < 0 || p[0] > width || p[1] < 0 || p[1] > height) continue;
-      out.push({
-        name,
-        iso,
-        ...(sub !== undefined && { sub }),
-        lon,
-        lat,
-        px: p[0],
-        py: p[1],
-        pop,
-      });
-      if (out.length >= MAX_CITY_DOTS) break;
-    }
-    return out;
-  };
-
-  return { invert, project, locate, cities, diagnostics: layout.diagnostics };
-}