@diagrammo/dgmo 0.21.1 → 0.23.0

package/src/infra/renderer.ts

@@ -2080,9 +2080,13 @@ function renderLegend(
   isDark: boolean,
   activeGroup: string | null,
   playback?: InfraPlaybackState,
-  exportMode = false
+  exportMode = false,
+  controlsHost?: 'app' | 'inline'
 ) {
   if (legendGroups.length === 0 && !playback) return;
+  // App-hosted playback: the play/pause + speed UI lives in the app overlay
+  // strip, so suppress the in-SVG Playback pill and emit the controls anchor.
+  const appHostedPlayback = controlsHost === 'app' && !!playback;
 
   const legendG = rootSvg
     .append('g')
@@ -2097,8 +2101,9 @@ function renderLegend(
     name: g.name,
     entries: g.entries.map((e) => ({ value: e.value, color: e.color })),
   }));
-  // Add Playback as a group with empty entries (collapsed pill) or dummy entries (expanded)
-  if (playback) {
+  // Add Playback as a group with empty entries (collapsed pill) or dummy entries
+  // (expanded) — unless the app hosts it, in which case it's suppressed.
+  if (playback && !appHostedPlayback) {
     allGroups.push({ name: 'Playback', entries: [] });
   }
 
@@ -2107,6 +2112,20 @@ function renderLegend(
     position: { placement: 'top-center', titleRelation: 'below-title' },
     mode: exportMode ? 'export' : 'preview',
     showEmptyGroups: true,
+    ...(appHostedPlayback && {
+      controlsHost: 'app' as const,
+      controlsGroup: {
+        toggles: [
+          {
+            id: 'playback',
+            type: 'toggle' as const,
+            label: 'Playback',
+            active: true,
+            onToggle: () => {},
+          },
+        ],
+      },
+    }),
   };
   const legendState: LegendState = { activeGroup };
   renderLegendD3(
@@ -2233,9 +2252,13 @@ export function renderInfra(
   playback?: InfraPlaybackState | null,
   expandedNodeIds?: Set<string> | null,
   exportMode?: boolean,
-  collapsedNodes?: Set<string> | null
+  collapsedNodes?: Set<string> | null,
+  /** When 'app', the playback pill is suppressed and a controls row + anchor are
+   *  reserved for the app overlay strip (play/pause + speed live there). */
+  controlsHost?: 'app' | 'inline'
 ) {
   d3Selection.select(container).selectAll(':not([data-d3-tooltip])').remove();
+  const appHostedPlayback = controlsHost === 'app' && !!playback;
 
   const ctx = ScaleContext.identity();
   const sc = buildScaledConstants(ctx);
@@ -2246,7 +2269,10 @@ export function renderInfra(
     palette,
     layout.edges
   );
-  const hasLegend = legendGroups.length > 0 || !!playback;
+  // App-hosted: the playback pill moves to the app overlay, so a playback-only
+  // legend (no tag groups) has nothing left to render.
+  const hasLegend =
+    legendGroups.length > 0 || (!!playback && !appHostedPlayback);
   const fixedLegend = !exportMode && hasLegend;
   const legendDynamicH = hasLegend
     ? getMaxLegendReservedHeight(
@@ -2461,7 +2487,8 @@ export function renderInfra(
         isDark,
         activeGroup ?? null,
         playback ?? undefined,
-        exportMode
+        exportMode,
+        controlsHost
       );
       // Re-enable pointer events on interactive legend elements
       legendSvg
@@ -2478,7 +2505,8 @@ export function renderInfra(
         isDark,
         activeGroup ?? null,
         playback ?? undefined,
-        exportMode
+        exportMode,
+        controlsHost
       );
     }
   }

package/src/map/colorize.ts

@@ -0,0 +1,54 @@
+// Political fill-assignment pass (§24B colorize). PURE + DETERMINISTIC — no
+// projection, no palette, no DOM. Given the per-topology arc-adjacency graph
+// (from geo.ts buildAdjacency), assign every drawn region a colour INDEX such
+// that no two arc-neighbours share one. The only job of a political fill is
+// boundary disambiguation; "no two neighbours share a hue" is the minimal
+// property — and a planar political map famously needs only a handful of colours.
+//
+// FIRST-FIT greedy: each region takes the LOWEST index not used by an
+// already-coloured neighbour. This is collision-free by construction (a node with
+// k coloured neighbours has at most k forbidden indices, so index ≤ k is always
+// free) AND clusters regions into the FEWEST colours — on the shipped graphs the
+// max index used is 5 (world) / 4 (us-states), i.e. 5–6 colours total. The caller
+// generates exactly that many palette tints, so the fills stay on-palette (no
+// need for the old Δ+1 ≈ 17 wheel hues).
+
+/** Result of {@link assignColors}: a colour INDEX per ISO + the number of
+ *  distinct colours actually used (`= maxIndex + 1`). The index is a stable
+ *  function of (ISO, global arc-adjacency) — extent-independent (AC10). */
+export interface ColorAssignment {
+  readonly byIso: Map<string, number>;
+  readonly huesNeeded: number;
+}
+
+/** First-fit greedy graph-coloring over `isos` using `adjacency` (ISO → neighbour
+ *  ISOs). Visits ISOs in stable ascending order; each takes the lowest index not
+ *  taken by an already-coloured neighbour — collision-free, and minimises the
+ *  total colour count.
+ *
+ *  EVERY iso in `isos` is assigned an index — including zero-degree nodes
+ *  (islands, DC, territories with no neighbour entry) — so the caller never needs
+ *  a fallback fill (F14). */
+export function assignColors(
+  isos: readonly string[],
+  adjacency: ReadonlyMap<string, readonly string[]>
+): ColorAssignment {
+  const sorted = [...isos].sort();
+  const byIso = new Map<string, number>();
+  let maxIndex = -1;
+
+  for (const iso of sorted) {
+    const taken = new Set<number>();
+    for (const n of adjacency.get(iso) ?? []) {
+      const c = byIso.get(n);
+      if (c !== undefined) taken.add(c);
+    }
+    // Lowest index not taken by a neighbour (always exists: ≤ neighbour count).
+    let h = 0;
+    while (taken.has(h)) h++;
+    byIso.set(iso, h);
+    if (h > maxIndex) maxIndex = h;
+  }
+
+  return { byIso, huesNeeded: maxIndex + 1 };
+}

package/src/map/context-labels.ts

@@ -0,0 +1,429 @@
+// Context-label placement (step 4, part of layout). Produces a sparse,
+// density-thinned ORIENTATION layer — water-body names + unreferenced notable
+// country names — distinct from `region-labels`. PURE + SYNC + DETERMINISTIC.
+//
+// Design (tech-spec §map-context-labels): a deliberately LOW per-view label
+// BUDGET is the primary noise lever; a span-derived TIER BAND orders candidates
+// into it; each candidate is committed only if it survives COLLISION against
+// every already-placed data/region/POI/route label (the `collides` closure) AND
+// the other context labels. Context labels place DEAD LAST and never displace
+// data — they only fill leftover space, degrading gracefully to zero. See
+// Decisions 6 (budget), 7 (dead-last), 8 (viewport/projection guards).
+import { mix } from '../palettes/color-utils';
+import type { PaletteColors } from '../palettes/types';
+import type { LabelRect } from '../label-layout';
+import { measureLegendText } from '../utils/legend-constants';
+import type { ProjectionFamily } from './resolved-types';
+import type { WaterBodies, WaterKind } from './data/types';
+import type { PlacedLabel } from './layout';
+
+/** A view span band → priority ordering (NOT a hard zoom cutoff, Decision 6). */
+export type TierBand = 'world' | 'continental' | 'regional' | 'local';
+
+/** An unreferenced country, pre-projected by layout (geo work stays in layout;
+ *  area-rank + name-fit + collision live here so the module is unit-testable). */
+export interface CountryCandidate {
+  readonly name: string;
+  /** Projected screen bbox `[x0, y0, x1, y1]` (from `path.bounds`). */
+  readonly bbox: readonly [number, number, number, number];
+  /** Projected screen anchor `[x, y]` (mainland anchor or `path.centroid`), or
+   *  null when the feature doesn't project to a finite point. */
+  readonly anchor: readonly [number, number] | null;
+}
+
+export interface ContextLabelArgs {
+  readonly projection: ProjectionFamily;
+  readonly dLonSpan: number;
+  readonly dLatSpan: number;
+  readonly width: number;
+  readonly height: number;
+  readonly waterBodies?: WaterBodies | undefined;
+  readonly countries: readonly CountryCandidate[];
+  readonly palette: PaletteColors;
+  readonly project: (lon: number, lat: number) => [number, number] | null;
+  /** Collision test against every committed data/region/POI/route obstacle. */
+  readonly collides: (rect: LabelRect) => boolean;
+  /** True when the screen point sits over LAND (a country/state fill) rather than
+   *  open water. WATER labels are rejected when their footprint touches land — an
+   *  ocean name belongs over the ocean (they're optional orientation aids, so drop
+   *  rather than misplace). Country labels are exempt (they label land). Optional
+   *  for unit tests; absent ⇒ no land rejection. */
+  readonly overLand?: (x: number, y: number) => boolean;
+}
+
+const FONT = 11; // matches layout's on-map label font
+const LINE_HEIGHT = FONT + 2; // px per wrapped line — MUST match the renderer's
+const PADX = 4; // half-padding around a context label rect
+const PADY = 3;
+const WATER_LETTER_SPACING = 1.5; // px — cartographic spread for water names
+const CONTEXT_PAD = 4; // extra gap enforced between two context labels
+const EDGE_CLAMP_MARGIN = 8; // px inset for edge-clamped ocean labels
+const EDGE_CLAMP_OVERSHOOT = 0.35; // max off-frame overshoot (× dim) to still clamp
+
+// Water-kind priority within a tier (oceans first, then seas, then the rest) so
+// a thin budget always spends on the highest-orientation-value names.
+const KIND_ORDER: Record<WaterKind, number> = {
+  ocean: 0,
+  sea: 1,
+  gulf: 2,
+  bay: 3,
+  strait: 4,
+  channel: 5,
+  sound: 6,
+};
+
+/** Span band from the larger of the two view spans (Decision 6 — priority, not
+ *  a hard gate). */
+export function tierBand(maxSpanDeg: number): TierBand {
+  if (maxSpanDeg >= 90) return 'world';
+  if (maxSpanDeg >= 20) return 'continental';
+  if (maxSpanDeg >= 5) return 'regional';
+  return 'local';
+}
+
+/** Deliberately-LOW combined label budget = f(canvas area, band). Floors to ~1
+ *  on a thumbnail and 0 on a tiny canvas (Decision 6, ADR-3; AC9). Caps the
+ *  TOTAL context labels (water + country), so `relief`/data don't get extra
+ *  headroom (Decision 13). */
+export function labelBudget(
+  width: number,
+  height: number,
+  band: TierBand
+): number {
+  const bandCap: Record<TierBand, number> = {
+    world: 6,
+    continental: 5,
+    regional: 4,
+    local: 3,
+  };
+  const area = Math.floor(Math.sqrt(Math.max(0, width * height)) / 150);
+  return Math.max(0, Math.min(area, bandCap[band]));
+}
+
+/** Which water tiers/kinds are eligible at a band. World view is oceans + major
+ *  seas ONLY (never bays/sounds/minor gulfs, AC3); broader views progressively
+ *  admit smaller features by `scalerank` (AC4). */
+function waterEligible(tier: number, kind: WaterKind, band: TierBand): boolean {
+  switch (band) {
+    case 'world':
+      return tier <= 1 && (kind === 'ocean' || kind === 'sea');
+    case 'continental':
+      return tier <= 2;
+    case 'regional':
+      return tier <= 3;
+    case 'local':
+      return tier <= 4;
+  }
+}
+
+function insideViewport(
+  p: readonly [number, number] | null,
+  width: number,
+  height: number
+): p is [number, number] {
+  return (
+    !!p &&
+    Number.isFinite(p[0]) &&
+    Number.isFinite(p[1]) &&
+    p[0] >= 0 &&
+    p[0] <= width &&
+    p[1] >= 0 &&
+    p[1] <= height
+  );
+}
+
+/** Rendered label width INCLUDING letter-spacing — `measureLegendText` ignores
+ *  the per-gap `letter-spacing` the renderer applies to water names, so without
+ *  this the fit/clamp math under-measures by ~`(len-1)*spacing` and the label
+ *  clips at the canvas edge. */
+export function labelWidth(text: string, letterSpacing: number): number {
+  const spacing =
+    letterSpacing > 0 ? Math.max(0, text.length - 1) * letterSpacing : 0;
+  return measureLegendText(text, FONT) + spacing + 2 * PADX;
+}
+
+/** Wrap a multi-word name into balanced lines, biased to wrap READILY — water
+ *  names ("North Pacific Ocean") read better stacked, and a narrower footprint
+ *  is far likelier to clear surrounding land (the hard rule below). Of every
+ *  contiguous split into ≤`maxLines`, picks the one minimising the widest line
+ *  (so it shrinks horizontally whenever a break helps); ties break to fewer
+ *  lines, then top-heavy ("North Pacific" / "Ocean", not "North" / "Pacific
+ *  Ocean"). Single-word names pass through unwrapped. */
+export function wrapLabel(text: string, letterSpacing: number): string[] {
+  const words = text.split(/\s+/).filter(Boolean);
+  if (words.length <= 1) return [text];
+  const maxLines = words.length >= 4 ? 3 : 2;
+  const n = words.length;
+  type Split = { lines: string[]; cost: number; head: number };
+  let best: Split | null = null;
+  for (let mask = 0; mask < 1 << (n - 1); mask++) {
+    const lines: string[] = [];
+    let cur = [words[0]!];
+    for (let i = 1; i < n; i++) {
+      if (mask & (1 << (i - 1))) {
+        lines.push(cur.join(' '));
+        cur = [words[i]!];
+      } else cur.push(words[i]!);
+    }
+    lines.push(cur.join(' '));
+    if (lines.length > maxLines) continue;
+    const cost = Math.round(
+      Math.max(...lines.map((l) => labelWidth(l, letterSpacing)))
+    );
+    const head = labelWidth(lines[0]!, letterSpacing);
+    if (
+      !best ||
+      cost < best.cost ||
+      (cost === best.cost && lines.length < best.lines.length) ||
+      (cost === best.cost &&
+        lines.length === best.lines.length &&
+        head > best.head)
+    )
+      best = { lines, cost, head };
+  }
+  return best?.lines ?? [text];
+}
+
+function rectAround(
+  cx: number,
+  cy: number,
+  lines: readonly string[],
+  letterSpacing: number
+): LabelRect {
+  const w = Math.max(...lines.map((l) => labelWidth(l, letterSpacing)));
+  const h = (lines.length - 1) * LINE_HEIGHT + FONT + 2 * PADY;
+  return { x: cx - w / 2, y: cy - h / 2, w, h };
+}
+
+function rectFits(r: LabelRect, width: number, height: number): boolean {
+  return r.x >= 0 && r.y >= 0 && r.x + r.w <= width && r.y + r.h <= height;
+}
+
+function overlapsPadded(a: LabelRect, b: LabelRect, pad: number): boolean {
+  return (
+    a.x - pad < b.x + b.w &&
+    a.x + a.w + pad > b.x &&
+    a.y - pad < b.y + b.h &&
+    a.y + a.h + pad > b.y
+  );
+}
+
+/** Place the orientation backdrop. Returns committed labels in priority order;
+ *  caller pushes them onto `labels` LAST so they never displace data. */
+export function placeContextLabels(args: ContextLabelArgs): PlacedLabel[] {
+  const {
+    projection,
+    dLonSpan,
+    dLatSpan,
+    width,
+    height,
+    waterBodies,
+    countries,
+    palette,
+    project,
+    collides,
+    overLand,
+  } = args;
+
+  // albers-usa is supported: the CONUS conic projects CONUS-area water (Gulf of
+  // America, the Pacific/Atlantic margins) correctly, and the viewport-visibility
+  // check below drops the off-frame anchors (Gulf of Alaska, mid-Pacific) that the
+  // AK/HI inset relocation would otherwise mislabel. The caller additionally feeds
+  // the AK/HI inset frames into `collides` so a label never lands on an inset box.
+  // (Supersedes the original blanket albers-usa disable — the US map is the
+  // flagship orientation case.)
+  void projection;
+
+  const band = tierBand(Math.max(dLonSpan, dLatSpan));
+  const budget = labelBudget(width, height, band);
+  if (budget <= 0) return [];
+
+  // Subordinate cartographic colours (palette-derived, no hex; resvg-safe via
+  // pre-computed mix()). Water = muted blue-gray italic; country = muted gray.
+  const waterColor = mix(palette.colors.blue, palette.textMuted, 50);
+  const countryColor = palette.textMuted;
+  const haloColor = palette.bg;
+
+  type Candidate = {
+    text: string;
+    lines: string[];
+    cx: number;
+    cy: number;
+    italic: boolean;
+    letterSpacing: number;
+    color: string;
+    sort: number; // priority key (lower first)
+  };
+  const candidates: Candidate[] = [];
+
+  // -- Water candidates (priority core: oceans → seas → minor water) --
+  const center: [number, number] = [width / 2, height / 2];
+  for (const e of waterBodies?.entries ?? []) {
+    const [lat, lon, name, tier, kind, alt] = e;
+    if (!waterEligible(tier, kind, band)) continue;
+    // Wrap eagerly (Decision: water names stack readily) so the clamp/fit math
+    // below sees the real, narrower wrapped footprint, not the one-line width.
+    const wlines = wrapLabel(name, WATER_LETTER_SPACING);
+    // Multi-anchor (Decision 5 / ADR-4): of the anchors that project inside the
+    // viewport, pick the one nearest the viewport centre.
+    const anchorsLngLat: Array<[number, number]> = [[lon, lat]];
+    for (const a of alt ?? []) anchorsLngLat.push([a[1], a[0]]);
+    let best: [number, number] | null = null;
+    let bestD = Infinity;
+    let nearestProj: [number, number] | null = null; // best finite proj (any side)
+    let nearestProjD = Infinity;
+    for (const [aLon, aLat] of anchorsLngLat) {
+      const p = project(aLon, aLat);
+      if (!p || !Number.isFinite(p[0]) || !Number.isFinite(p[1])) continue;
+      const d = (p[0] - center[0]) ** 2 + (p[1] - center[1]) ** 2;
+      if (d < nearestProjD) {
+        nearestProjD = d;
+        nearestProj = p;
+      }
+      if (!insideViewport(p, width, height)) continue;
+      if (d < bestD) {
+        bestD = d;
+        best = p;
+      }
+    }
+    // Oceans (tier 0) are large enough that a frame-edge label still reads
+    // correctly, so when their anchor falls off-screen on a zoomed-in view
+    // (e.g. the mid-Atlantic/Pacific centroid on a US map) we CLAMP it to the
+    // viewport margin rather than drop it — the standard cartographic "ocean
+    // name hugs the edge" behaviour. Smaller basins keep the strict drop-if-
+    // off-screen rule (AC10) to avoid mislabelling an adjacent basin.
+    if (!best && tier === 0 && nearestProj) {
+      // Only clamp an ocean ADJACENT to the frame: if its centroid overshoots
+      // the viewport by more than ~half a dimension it's a distant ocean (e.g.
+      // the South Atlantic / Arctic relative to a US view) and edge-clamping it
+      // would mislabel that margin — drop instead. The surviving oceans are the
+      // ones the frame actually borders (Pacific to the west, Atlantic east).
+      const overX = Math.max(0, -nearestProj[0], nearestProj[0] - width);
+      const overY = Math.max(0, -nearestProj[1], nearestProj[1] - height);
+      if (
+        overX <= width * EDGE_CLAMP_OVERSHOOT &&
+        overY <= height * EDGE_CLAMP_OVERSHOOT
+      ) {
+        // Clamp the CENTRE inward by half the label so the whole (centre-
+        // anchored) rect stays on-canvas — clamping to the bare margin would
+        // overflow a wide name like "North Atlantic Ocean" off the edge.
+        // letter-spacing IS counted (labelWidth) so the clamp matches render.
+        const halfW =
+          Math.max(...wlines.map((l) => labelWidth(l, WATER_LETTER_SPACING))) /
+          2;
+        const halfH = ((wlines.length - 1) * LINE_HEIGHT + FONT + 2 * PADY) / 2;
+        const m = EDGE_CLAMP_MARGIN;
+        best = [
+          Math.min(Math.max(nearestProj[0], halfW + m), width - halfW - m),
+          Math.min(Math.max(nearestProj[1], halfH + m), height - halfH - m),
+        ];
+      }
+    }
+    if (!best) continue;
+    candidates.push({
+      text: name,
+      lines: wlines,
+      cx: best[0],
+      cy: best[1],
+      italic: true,
+      letterSpacing: WATER_LETTER_SPACING,
+      color: waterColor,
+      // Water before any country (×1000), then by tier, then kind, then name.
+      sort: tier * 10 + KIND_ORDER[kind],
+    });
+  }
+
+  // -- Country candidates (unreferenced; biggest projected area first) --
+  // Rank by screen bbox area; keep only those whose name fits the footprint
+  // (width-fit, like region-labels) and whose anchor projects inside the view.
+  const ranked = countries
+    .map((c) => {
+      const [x0, y0, x1, y1] = c.bbox;
+      const w = x1 - x0;
+      const h = y1 - y0;
+      return { c, w, h, area: w * h };
+    })
+    .filter((r) => Number.isFinite(r.area) && r.area > 0)
+    .sort((a, b) => b.area - a.area);
+  let ci = 0;
+  for (const r of ranked) {
+    const { c, w, h } = r;
+    // F2: an antimeridian-crossing / global-smear country yields a near-full-
+    // canvas bbox while its real landmass is split — the `path.centroid` anchor
+    // is then unreliable (mid-map, wrong basin). Drop such over-wide candidates
+    // rather than spend a top-priority slot on a mispositioned name.
+    if (w > width * 0.66 || h > height * 0.66) continue;
+    if (!insideViewport(c.anchor, width, height)) continue;
+    // Always the full country name — never an ISO abbreviation. If the name
+    // doesn't fit the footprint, drop the label rather than abbreviate.
+    const text = c.name;
+    const tw = labelWidth(text, 0);
+    // Approximate fit (Decision 4): name fits inside the footprint bbox. NOT
+    // true point-in-polygon — cartographic labels routinely overrun coastlines.
+    if (tw > w || FONT + 2 * PADY > h) continue;
+    candidates.push({
+      text,
+      lines: [text],
+      cx: c.anchor[0],
+      cy: c.anchor[1],
+      italic: false,
+      letterSpacing: 0,
+      color: countryColor,
+      // Always after every water body (+1e6); larger area = earlier.
+      sort: 1_000_000 + ci++,
+    });
+  }
+
+  // -- Commit dead-last, highest-priority-first, into leftover space only --
+  candidates.sort((a, b) => a.sort - b.sort);
+  const placed: PlacedLabel[] = [];
+  const placedRects: LabelRect[] = [];
+  for (const cand of candidates) {
+    if (placed.length >= budget) break;
+    const rect = rectAround(cand.cx, cand.cy, cand.lines, cand.letterSpacing);
+    if (!rectFits(rect, width, height)) continue;
+    // Water labels must sit over OPEN WATER and NEVER touch land — sample a grid
+    // over every wrapped line (each line's own horizontal extent at five points);
+    // drop the whole label if ANY sample hits land (Decision: optional orientation
+    // aids, so exclude rather than misplace over a coastline). Country labels are
+    // exempt — they belong on their country.
+    if (cand.italic && overLand) {
+      const inset = 2;
+      const top = cand.cy - ((cand.lines.length - 1) / 2) * LINE_HEIGHT;
+      const touchesLand = cand.lines.some((line, li) => {
+        const lw = labelWidth(line, cand.letterSpacing);
+        const x0 = cand.cx - lw / 2 + inset;
+        const x1 = cand.cx + lw / 2 - inset;
+        const xs = [x0, (x0 + cand.cx) / 2, cand.cx, (cand.cx + x1) / 2, x1];
+        const base = top + li * LINE_HEIGHT;
+        // Sample the glyph body top→baseline (text rises above the baseline) so a
+        // label whose ascenders clip a coastline is rejected, not just one whose
+        // baseline sits on land.
+        return [base, base - FONT * 0.4, base - FONT * 0.8].some((y) =>
+          xs.some((x) => overLand(x, y))
+        );
+      });
+      if (touchesLand) continue;
+    }
+    if (collides(rect)) continue;
+    if (placedRects.some((r) => overlapsPadded(rect, r, CONTEXT_PAD))) continue;
+    placedRects.push(rect);
+    placed.push({
+      x: cand.cx,
+      y: cand.cy,
+      text: cand.text,
+      anchor: 'middle',
+      color: cand.color,
+      // No halo: the bg-coloured outline reads as a ghost box behind the text
+      // over the tinted water/land. Context labels are muted enough to sit
+      // cleanly on the basemap without one.
+      halo: false,
+      haloColor,
+      italic: cand.italic,
+      letterSpacing: cand.letterSpacing,
+      ...(cand.lines.length > 1 ? { lines: cand.lines } : {}),
+      lineNumber: 0,
+    });
+  }
+  return placed;
+}

package/src/map/data/PROVENANCE.json

@@ -1 +1 @@
-{"assets":{"gazetteer.json":{"bytes":130706,"gzBytes":56251,"sha256":"8cefc36db73c9337429e66c94339a385656de3ec22a67487b0a146aa37dd632a"},"lakes.json":{"bytes":6315,"gzBytes":1487,"sha256":"5840ffd49b8dbf30183a9534a72adf80b6e77ceec224665393fa94e956220323"},"mountain-ranges.json":{"bytes":30081,"gzBytes":8971,"sha256":"b0eb87e6b3c514b882245299fbe698b3caaa3f40494e3d220f973caf6a12a16c"},"region-names.json":{"bytes":11667,"gzBytes":2235,"sha256":"059662d30b6ee8572c5943096905e05218e5f337e6973a9d43d6b41b7313a9ac"},"rivers.json":{"bytes":6707,"gzBytes":2158,"sha256":"3912508469099b1c37360c5505ea033c4ffa30ce95f7428e668e9d824cb81407"},"us-states.json":{"bytes":23313,"gzBytes":7413,"sha256":"0fe3a8937bc7566192662439f29a7866e8823d687290bcb003433ad5edd86567"},"world-coarse.json":{"bytes":55426,"gzBytes":18390,"sha256":"9ed5a15d775c0a303003dcf096a209dd433383ea52e18014885d482c38bc01a4"},"world-detail.json":{"bytes":163555,"gzBytes":46762,"sha256":"e99dddc3fccd96465ad4e5cd7bcca839095672e9c595d78276d510c44db84fd7"}},"counts":{"countries":175,"gazetteerAliases":8,"gazetteerCities":2118,"mountainRanges":114,"usStates":56},"generatedBy":"scripts/build-map-data.mjs","sourceHashes":{"https://cdn.jsdelivr.net/gh/martynafford/natural-earth-geojson@master/110m/physical/ne_110m_lakes.json":{"bytes":27711,"sha256":"6f315b60488e0cf5da9c360e3ce593babf64c2f44cc21e2820c536f7a2aff606"},"https://cdn.jsdelivr.net/gh/martynafford/natural-earth-geojson@master/110m/physical/ne_110m_rivers_lake_centerlines.json":{"bytes":54146,"sha256":"959e13128e4eb5a6ee530b8270c5017bcee9149ce48a97f6fe7fee1fce600b5d"},"https://cdn.jsdelivr.net/gh/nvkelso/natural-earth-vector@master/geojson/ne_50m_geography_regions_polys.geojson":{"bytes":4305815,"sha256":"33396643d8f0eed408e80bf5ca43dcdb7993f790fdc4eadae311660f8b91fe76"},"https://cdn.jsdelivr.net/npm/us-atlas@3.0.1/states-10m.json":{"bytes":114554,"sha256":"d76b391ccfa8bff601d51e3e3da5d43a89fa46cd5caca72ce731b383be5596d0"},"https://cdn.jsdelivr.net/npm/world-atlas@2.0.2/countries-110m.json":{"bytes":107761,"sha256":"2516c915867c7baf18ddec727aec46c315541a07cfb3d79a6559b05d5e94eee8"},"https://cdn.jsdelivr.net/npm/world-atlas@2.0.2/countries-50m.json":{"bytes":756420,"sha256":"04342cdc1e3016bcd7db1630de95684d67b79fe3c8c460321e87aef469502394"},"https://download.geonames.org/export/dump/cities5000.zip":{"bytes":5546862,"sha256":"e898c1399b05bd521540c5fa56ac3db44b4b2029d432b5f40a1e45f66d5a0929"}},"sources":{"geonames":{"citiesUrl":"https://download.geonames.org/export/dump/cities5000.zip","license":"CC BY 4.0 — https://creativecommons.org/licenses/by/4.0/","modificationDateRange":"2006-01-17..2026-05-25 (filtered subset)"},"lakes":{"url":"https://cdn.jsdelivr.net/gh/martynafford/natural-earth-geojson@master/110m/physical/ne_110m_lakes.json","version":"natural-earth 110m (martynafford snapshot)"},"mountainRanges":{"license":"public domain (Natural Earth)","url":"https://cdn.jsdelivr.net/gh/nvkelso/natural-earth-vector@master/geojson/ne_50m_geography_regions_polys.geojson","version":"natural-earth 50m (nvkelso vector snapshot)"},"rivers":{"url":"https://cdn.jsdelivr.net/gh/martynafford/natural-earth-geojson@master/110m/physical/ne_110m_rivers_lake_centerlines.json","version":"natural-earth 110m (martynafford snapshot)"},"usAtlas":{"url":"https://cdn.jsdelivr.net/npm/us-atlas@3.0.1/states-10m.json","version":"3.0.1"},"worldCoarse":{"url":"https://cdn.jsdelivr.net/npm/world-atlas@2.0.2/countries-110m.json","version":"2.0.2"},"worldDetail":{"url":"https://cdn.jsdelivr.net/npm/world-atlas@2.0.2/countries-50m.json","version":"2.0.2"}},"tooling":{"mapshaper":"0.7.22"}}
+{"assets":{"gazetteer.json":{"bytes":130767,"gzBytes":56261,"sha256":"5ad56e5ba0b3a4f9a6dc8bd3bf8b0fda0e7b86cbe4d85d231114f5dd967d65f7"},"lakes.json":{"bytes":6315,"gzBytes":1487,"sha256":"5840ffd49b8dbf30183a9534a72adf80b6e77ceec224665393fa94e956220323"},"mountain-ranges.json":{"bytes":90845,"gzBytes":26493,"sha256":"a698b3f296e61712fb39b3d8d42ec7c4699f8aadecb549367feb7d09f7785580"},"na-lakes.json":{"bytes":39387,"gzBytes":11281,"sha256":"2a41c04969209380d544a09efe354277e12d704458af95955201eb4f698d16c6"},"na-land.json":{"bytes":114082,"gzBytes":32375,"sha256":"7b94c9bb4e809c22813da5ae939e1ff6a781fd77a04d9c1585a9a82d2a195388"},"region-names.json":{"bytes":11667,"gzBytes":2235,"sha256":"059662d30b6ee8572c5943096905e05218e5f337e6973a9d43d6b41b7313a9ac"},"rivers.json":{"bytes":6707,"gzBytes":2158,"sha256":"3912508469099b1c37360c5505ea033c4ffa30ce95f7428e668e9d824cb81407"},"us-states.json":{"bytes":23313,"gzBytes":7413,"sha256":"0fe3a8937bc7566192662439f29a7866e8823d687290bcb003433ad5edd86567"},"water-bodies.json":{"bytes":4854,"gzBytes":2123,"sha256":"6d1a407a376c63518329c52189e2887053c4b61062af0597e060050ae8469635"},"world-coarse.json":{"bytes":55436,"gzBytes":18397,"sha256":"5cb42e3c8975dde56504ca5c68ece0a1e71d0929680b5fc8cdab758c8666dbf8"},"world-detail.json":{"bytes":163562,"gzBytes":46767,"sha256":"39f1736eaabe9e21190972be3157822be22ee84fdc41751237f2b516f09a7586"}},"counts":{"countries":175,"gazetteerAliases":8,"gazetteerCities":2119,"mountainRanges":205,"usStates":56,"waterBodies":113},"generatedBy":"scripts/build-map-data.mjs","sourceHashes":{"https://cdn.jsdelivr.net/gh/martynafford/natural-earth-geojson@master/10m/physical/ne_10m_lakes.json":{"bytes":6648697,"sha256":"93c8fdf0e591e113f449d0d466e15c7a9841b9b6571c7afe41f95ba51b322452"},"https://cdn.jsdelivr.net/gh/martynafford/natural-earth-geojson@master/110m/physical/ne_110m_lakes.json":{"bytes":27711,"sha256":"6f315b60488e0cf5da9c360e3ce593babf64c2f44cc21e2820c536f7a2aff606"},"https://cdn.jsdelivr.net/gh/martynafford/natural-earth-geojson@master/110m/physical/ne_110m_rivers_lake_centerlines.json":{"bytes":54146,"sha256":"959e13128e4eb5a6ee530b8270c5017bcee9149ce48a97f6fe7fee1fce600b5d"},"https://cdn.jsdelivr.net/gh/nvkelso/natural-earth-vector@master/geojson/ne_10m_admin_0_countries.geojson":{"bytes":13287234,"sha256":"239eec57ac17f100a11e2536cffc56752c318b50ae765b0918ff7aab4ce8f255"},"https://cdn.jsdelivr.net/gh/nvkelso/natural-earth-vector@master/geojson/ne_10m_geography_regions_polys.geojson":{"bytes":5583870,"sha256":"b7b26e50ea917d3696aec87f932def2bf5f890f5770e441d59c162c6f4c92a77"},"https://cdn.jsdelivr.net/gh/nvkelso/natural-earth-vector@master/geojson/ne_110m_geography_marine_polys.geojson":{"bytes":534055,"sha256":"b9c3f7f557d0ff5217906adc82b66ecdac14aa7438df7e518cf6675d037bceb8"},"https://cdn.jsdelivr.net/gh/nvkelso/natural-earth-vector@master/geojson/ne_50m_geography_marine_polys.geojson":{"bytes":1163418,"sha256":"6fe58083e0cc5c7fad9e396970e28a8580bbd8770cfa4d1d7b5a34423e912f97"},"https://cdn.jsdelivr.net/npm/us-atlas@3.0.1/states-10m.json":{"bytes":114554,"sha256":"d76b391ccfa8bff601d51e3e3da5d43a89fa46cd5caca72ce731b383be5596d0"},"https://cdn.jsdelivr.net/npm/world-atlas@2.0.2/countries-110m.json":{"bytes":107761,"sha256":"2516c915867c7baf18ddec727aec46c315541a07cfb3d79a6559b05d5e94eee8"},"https://cdn.jsdelivr.net/npm/world-atlas@2.0.2/countries-50m.json":{"bytes":756420,"sha256":"04342cdc1e3016bcd7db1630de95684d67b79fe3c8c460321e87aef469502394"},"https://download.geonames.org/export/dump/cities5000.zip":{"bytes":5549002,"sha256":"d20e28b2f610da34c21fd82ff6a8e4d24ebe67eba2dccf65bd2c4332ff0f380a"}},"sources":{"geonames":{"citiesUrl":"https://download.geonames.org/export/dump/cities5000.zip","license":"CC BY 4.0 — https://creativecommons.org/licenses/by/4.0/","modificationDateRange":"2006-01-17..2026-06-02 (filtered subset)"},"lakes":{"url":"https://cdn.jsdelivr.net/gh/martynafford/natural-earth-geojson@master/110m/physical/ne_110m_lakes.json","version":"natural-earth 110m (martynafford snapshot)"},"marineCoarse":{"url":"https://cdn.jsdelivr.net/gh/nvkelso/natural-earth-vector@master/geojson/ne_110m_geography_marine_polys.geojson","version":"natural-earth 110m (nvkelso vector snapshot)"},"marineDetail":{"url":"https://cdn.jsdelivr.net/gh/nvkelso/natural-earth-vector@master/geojson/ne_50m_geography_marine_polys.geojson","version":"natural-earth 50m (nvkelso vector snapshot)"},"mountainRanges":{"url":"https://cdn.jsdelivr.net/gh/nvkelso/natural-earth-vector@master/geojson/ne_10m_geography_regions_polys.geojson","version":"natural-earth 10m (nvkelso vector snapshot)"},"naLakes":{"url":"https://cdn.jsdelivr.net/gh/martynafford/natural-earth-geojson@master/10m/physical/ne_10m_lakes.json","version":"natural-earth 10m (martynafford snapshot)"},"naLand":{"url":"https://cdn.jsdelivr.net/gh/nvkelso/natural-earth-vector@master/geojson/ne_10m_admin_0_countries.geojson","version":"natural-earth 10m (nvkelso vector snapshot)"},"rivers":{"url":"https://cdn.jsdelivr.net/gh/martynafford/natural-earth-geojson@master/110m/physical/ne_110m_rivers_lake_centerlines.json","version":"natural-earth 110m (martynafford snapshot)"},"usAtlas":{"url":"https://cdn.jsdelivr.net/npm/us-atlas@3.0.1/states-10m.json","version":"3.0.1"},"worldCoarse":{"url":"https://cdn.jsdelivr.net/npm/world-atlas@2.0.2/countries-110m.json","version":"2.0.2"},"worldDetail":{"url":"https://cdn.jsdelivr.net/npm/world-atlas@2.0.2/countries-50m.json","version":"2.0.2"}},"tooling":{"mapshaper":"0.7.22"}}

package/src/map/data/README.md

@@ -10,6 +10,10 @@ hand-edit — regenerate from source.
 - `us-states.json` — US states + DC + territories (TopoJSON), keyed by ISO 3166-2.
 - `lakes.json` — major lakes (Natural Earth 110m, TopoJSON), drawn as water over land.
 - `rivers.json` — major river centerlines (Natural Earth 110m, TopoJSON), drawn as thin water lines.
+- `na-land.json` — NA-clipped 10m country land (TopoJSON, ISO-keyed): crisp neighbour context under the albers-usa US view.
+- `na-lakes.json` — NA-clipped 10m major lakes (TopoJSON): the lakes counterpart to `na-land.json` for the US view.
+- `mountain-ranges.json` — notable mountain ranges (Natural Earth 50m geography regions, FEATURECLA "Range/mtn", TopoJSON), drawn as a subtle gradient relief cue when the `relief` directive is on. Optional; single tier (no elevation).
+- `water-bodies.json` — water-body orientation labels (`{ entries: [lat, lon, name, tier, kind] }`) from Natural Earth 110m+50m geography marine polys (oceans/seas/gulfs/bays/straits/channels/sounds; rivers + reefs excluded). Anchors are mapshaper inner points; `tier` is the NE scalerank. Drawn only when the `context-labels` directive is on. Optional.
 - `gazetteer.json` — `{ cities, byName, alt }` city index (see `types.ts`).
   `byName`/`alt` reference `cities` by array index (normalized).
 - `PROVENANCE.json` — source versions + per-asset sha256/sizes + GeoNames date range.
@@ -18,6 +22,8 @@ hand-edit — regenerate from source.
 ## Sources & attribution
 - **Country boundaries:** Natural Earth via `world-atlas@2.0.2` (public domain).
 - **US states:** US Census via `us-atlas@3.0.1` (public domain).
+- **Mountain ranges:** Natural Earth 50m `geography_regions_polys` via `nvkelso/natural-earth-vector` (public domain).
+- **Water bodies:** Natural Earth 110m+50m `geography_marine_polys` via `nvkelso/natural-earth-vector` (public domain). One editorial override applied (`Gulf of Mexico` → `Gulf of America`).
 - **Cities:** Data © **GeoNames**, licensed under **CC BY 4.0**
   (https://creativecommons.org/licenses/by/4.0/) — https://www.geonames.org/.