@diagrammo/dgmo 0.21.1 → 0.22.0

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/types.ts

@@ -50,6 +50,40 @@ export interface Gazetteer {
   alt: Record<string, number>;
 }
 
+/** Water-feature class (Natural Earth `featurecla`, rivers/reefs excluded). */
+export type WaterKind =
+  | 'ocean'
+  | 'sea'
+  | 'gulf'
+  | 'bay'
+  | 'strait'
+  | 'channel'
+  | 'sound';
+
+/**
+ * A water-body label entry: `[lat, lon, name, tier, kind, alt?]`.
+ * - `lat`/`lon` — label anchor (Natural Earth inner point), rounded to 3 decimals.
+ * - `name` — full display name (no abbreviation exists for water bodies).
+ * - `tier` — Natural Earth `scalerank` (0 = most prominent → orientation priority).
+ * - `kind` — feature class (drives styling/priority bucketing).
+ * - `alt` — optional extra anchor points `[lat, lon][]`; the layout picks the
+ *   one nearest the viewport center (Decision 5 multi-anchor seam). Absent today.
+ */
+export type WaterBodyEntry = [
+  lat: number,
+  lon: number,
+  name: string,
+  tier: number,
+  kind: WaterKind,
+  alt?: ReadonlyArray<readonly [number, number]>,
+];
+
+export interface WaterBodies {
+  /** Deterministically ordered (tier, then name). Generated from Natural Earth
+   *  marine polys by scripts/build-map-data.mjs into `water-bodies.json`. */
+  readonly entries: readonly WaterBodyEntry[];
+}
+
 /** A fill-able region (country or US state) — the display name + its ISO id +
  *  layer. Powers region-name autocomplete (completion-only; the renderer derives
  *  names from the topology directly). Extracted from the topologies by

package/src/map/data/water-bodies.json

@@ -0,0 +1 @@
+{"entries":[[85.078,21.558,"Arctic Ocean",0,"ocean"],[-26.746,83.424,"Indian Ocean",0,"ocean"],[39.898,-30.68,"North Atlantic Ocean",0,"ocean",[[40,-55],[30,-45],[50,-25],[15,-45]]],[24.49,-136.445,"North Pacific Ocean",0,"ocean",[[36,-126],[47,-131],[55,-143],[35,160],[15,165]]],[-34.311,-18.311,"South Atlantic Ocean",0,"ocean",[[-25,-35],[-40,-15],[-10,-20]]],[-30.137,-126.822,"South Pacific Ocean",0,"ocean",[[-20,-110],[-40,-95],[-15,170],[-35,170]]],[-65.892,-18.447,"Southern Ocean",0,"ocean"],[13.692,63.675,"Arabian Sea",1,"sea"],[72.951,-66.643,"Baffin Bay",1,"bay"],[13.118,86.757,"Bay of Bengal",1,"bay"],[71.997,-136.388,"Beaufort Sea",1,"sea"],[43.547,31.292,"Black Sea",1,"sea"],[13.754,-78.235,"Caribbean Sea",1,"sea"],[41.954,50.61,"Caspian Sea",1,"sea"],[-18.886,157.126,"Coral Sea",1,"sea"],[58.108,-149.198,"Gulf of Alaska",1,"gulf"],[25.319,-90.053,"Gulf of America",1,"gulf"],[59.246,-85.292,"Hudson Bay",1,"bay"],[55.979,-52.602,"Labrador Sea",1,"sea"],[34.341,17.988,"Mediterranean Sea",1,"sea"],[25.683,52.866,"Persian Gulf",1,"gulf"],[17.263,133.481,"Philippine Sea",1,"sea"],[19.579,38.751,"Red Sea",1,"sea"],[-77.493,-169.96,"Ross Sea",1,"sea"],[40.613,136.423,"Sea of Japan",1,"sea"],[52.851,149.205,"Sea of Okhotsk",1,"sea"],[13.781,114.703,"South China Sea",1,"sea"],[-40.358,160.682,"Tasman Sea",1,"sea"],[-75.66,-53.473,"Weddell Sea",1,"sea"],[-73.979,-106.379,"Amundsen Sea",2,"sea"],[10.878,95.492,"Andaman Sea",2,"sea"],[-9.347,135.278,"Arafura Sea",2,"sea"],[19.67,-93.559,"Bahía de Campeche",2,"bay"],[56.024,19.234,"Baltic Sea",2,"sea"],[-5.658,126.23,"Banda Sea",2,"sea"],[74.604,43.063,"Barents Sea",2,"sea"],[45.627,-4.33,"Bay of Biscay",2,"bay"],[-72.084,-82.745,"Bellingshausen Sea",2,"sea"],[56.349,-171.512,"Bering Sea",2,"sea"],[3.571,122.574,"Celebes Sea",2,"sea"],[68.633,-169.418,"Chukchi Sea",2,"sea"],[64.549,-57.848,"Davis Strait",2,"strait"],[-66.686,-68.017,"Drake Passage",2,"channel"],[28.854,125.37,"East China Sea",2,"sea"],[76.558,-8.516,"Greenland Sea",2,"sea"],[3.294,2.903,"Gulf of Guinea",2,"gulf"],[9.545,101.832,"Gulf of Thailand",2,"gulf"],[53.543,-5.35,"Irish Sea",2,"sea"],[-5.2,112.569,"Java Sea",2,"sea"],[76.92,73.103,"Kara Sea",2,"sea"],[5.871,75.234,"Laccadive Sea",2,"sea"],[75.961,120.379,"Laptev Sea",2,"sea"],[22.073,120.87,"Luzon Strait",2,"strait"],[-20.03,40.414,"Mozambique Channel",2,"channel"],[56.502,2.655,"North Sea",2,"sea"],[66.883,1.329,"Norwegian Sea",2,"sea"],[27.646,-59.716,"Sargasso Sea",2,"sea"],[-61.149,-54.893,"Scotia Sea",2,"sea"],[8.392,120.208,"Sulu Sea",2,"sea"],[-10.978,127.712,"Timor Sea",2,"sea"],[35.164,123.956,"Yellow Sea",2,"sea"],[42.81,15.327,"Adriatic Sea",3,"sea"],[49.707,-2.894,"English Channel",3,"channel"],[26.35,-110.53,"Golfo de California",3,"gulf"],[-35.41,131.682,"Great Australian Bight",3,"gulf"],[12.621,48.305,"Gulf of Aden",3,"gulf"],[61.904,19.763,"Gulf of Bothnia",3,"gulf"],[-14.387,139.215,"Gulf of Carpentaria",3,"gulf"],[16.3,-88.001,"Gulf of Honduras",3,"gulf"],[24.54,58.766,"Gulf of Oman",3,"gulf"],[63.3,-73.224,"Hudson Strait",3,"strait"],[53.746,-80.255,"James Bay",3,"bay"],[39.863,12.144,"Tyrrhenian Sea",3,"sea"],[65.418,38.854,"White Sea",3,"sea"],[38.899,24.994,"Aegean Sea",4,"sea"],[70.531,-120.687,"Amundsen Gulf",4,"gulf"],[40.132,1.619,"Balearic Sea",4,"sea"],[44.909,-66.051,"Bay of Fundy",4,"bay"],[-37.489,176.808,"Bay of Plenty",4,"bay"],[-3.776,147.903,"Bismarck Sea",4,"sea"],[38.756,120.053,"Bo Hai",4,"sea"],[57.651,-160.179,"Bristol Bay",4,"bay"],[51.086,-5.339,"Bristol Channel",4,"channel"],[-2.412,131.169,"Ceram Sea",4,"sea"],[37.829,-76.031,"Chesapeake Bay",4,"bay"],[59.657,-152.312,"Cook Inlet",4,"bay"],[42.981,3.976,"Golfe du Lion",4,"gulf"],[-46.117,-66.587,"Golfo San Jorge",4,"gulf"],[8.18,-79.211,"Golfo de Panamá",4,"gulf"],[59.969,26.987,"Gulf of Finland",4,"gulf"],[22.57,69.333,"Gulf of Kutch",4,"gulf"],[43.368,-68.504,"Gulf of Maine",4,"gulf"],[8.43,78.962,"Gulf of Mannar",4,"gulf"],[48.615,-60.525,"Gulf of Saint Lawrence",4,"gulf"],[19.791,107.611,"Gulf of Tonkin",4,"gulf"],[33.956,132.471,"Inner Sea",4,"sea"],[56.267,-7.03,"Inner Seas",4,"sea"],[38.178,18.626,"Ionian Sea",4,"sea"],[33.799,128.392,"Korea Strait",4,"strait"],[-1.86,118.021,"Makassar Strait",4,"strait"],[75.523,-61.147,"Melville Bay",4,"bay"],[0.591,126.128,"Molucca Sea",4,"sea"],[-35.469,-56.554,"Río de la Plata",4,"gulf"],[59.897,157.821,"Shelikhova Gulf",4,"gulf"],[-9.247,155.069,"Solomon Sea",4,"sea"],[35.783,-5.919,"Strait of Gibraltar",4,"strait"],[5.586,99.038,"Strait of Malacca",4,"strait"],[1.193,103.68,"Strait of Singapore",4,"strait"],[25.571,-79.276,"Straits of Florida",4,"strait"],[24.166,119.387,"Taiwan Strait",4,"strait"],[70.288,-99.272,"The North Western Passages",4,"channel"],[59.341,-67.41,"Ungava Bay",4,"bay"],[73.851,-109.102,"Viscount Melville Sound",4,"sound"]]}

package/src/map/dimensions.ts

@@ -0,0 +1,117 @@
+// 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;
+// 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
+): MapExportDimensions {
+  const raw = mapContentAspect(resolved, data);
+  const clamped = Math.max(ASPECT_MIN, Math.min(ASPECT_MAX, raw));
+  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.
+  const preferContain = clamped !== raw || floored;
+  return { width, height, preferContain };
+}