@diagrammo/dgmo 0.47.0 → 0.48.0

package/src/map/context-labels.ts

@@ -1,609 +0,0 @@
-// 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;
-  /** True when `anchor` came from a curated WORLD_LABEL_ANCHORS entry (a trusted
-   *  mainland point) rather than the area-weighted centroid. Such a country
-   *  bypasses the both-axes smear gate (its full-canvas bbox is an antimeridian
-   *  artifact, not a real footprint, so the unreliable-centroid concern is moot). */
-  readonly curatedAnchor?: boolean;
-  /** True for a sovereign NATION touching the viewport (Canada, Mexico) — as
-   *  opposed to a state/subdivision. Nations are labeled UNCONDITIONALLY and
-   *  OUTSIDE the budget so orientation is symmetric (a US view shows Canada AND
-   *  Mexico together, never one-arbitrarily). States/subdivisions leave this
-   *  absent and compete for the rationed budget. */
-  readonly bordering?: boolean;
-  /** Ordered interior placement positions (screen coords), best-first: the commit
-   *  loop tries each in turn and places at the first that clears all collisions, so
-   *  a country can dodge a data cluster onto open ground on its own land
-   *  (map-context-neighbor-labels, D7/D12). INVARIANT: either ABSENT or NON-EMPTY,
-   *  and `anchor === positions[0]` always (an empty array is illegal — F7).
-   *  Absent ⇒ single-anchor behaviour (`positions ?? [anchor]`). */
-  readonly positions?: readonly (readonly [number, number])[];
-}
-
-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[];
-  /** Muted, contrast-floored land tone for country labels — computed in layout
-   *  against the neutral basemap and shared with the orientation backdrop so a
-   *  context country and an orientation region read identically. Absent ⇒ the
-   *  legacy `palette.textMuted`. */
-  readonly countryTone?: string | undefined;
-  /** Muted, contrast-floored tone for water labels (against the water fill).
-   *  Absent ⇒ the legacy `mix(blue, textMuted, 50)`. */
-  readonly waterTone?: string | undefined;
-  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
-
-// Country labels scale with their projected footprint: a big landmass (Canada,
-// Mexico on a US view) reads as a larger backdrop name; a small one stays at the
-// base font. Size metric is the footprint's linear extent (√bbox-area) as a
-// fraction of the canvas's linear extent (√canvas-area), so the ramp is
-// resolution-independent. Below MIN ⇒ base font; at/above MAX ⇒ max font; linear
-// between. Colour does NOT change with size — subordination is by muting (the
-// contrast-floored tone) + size only, never by fading toward bg (Phase 1).
-const COUNTRY_FONT_MAX = 22; // px ceiling for the largest footprint
-const COUNTRY_SIZE_FRAC_MIN = 0.06; // footprint linear-frac at base font
-const COUNTRY_SIZE_FRAC_MAX = 0.32; // footprint linear-frac at max font
-
-// Multi-position country dodging (map-context-neighbor-labels). A country gets
-// several interior on-its-own-land positions so its label can dodge a colliding
-// data cluster into open space instead of being dropped. Layout generates the
-// positions (geo work stays in layout); the commit loop below walks them
-// best-first and places at the first that clears all collisions.
-export const MAX_COUNTRY_POSITIONS = 4; // ordered positions per country (cap; D7/D15)
-export const COUNTRY_POS_GRID = 5; // lon/lat sampling grid resolution N (N×N cells; D9)
-export const COUNTRY_POS_TOPN_MARGIN = 3; // generate positions for top budget+margin (D15)
-
-// 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: 10,
-    continental: 9,
-    regional: 7,
-    local: 6,
-  };
-  // Area divisor lowered 150→105 (map-context-neighbor-labels, budget knob): the
-  // old budget was so thin a regional view spent every slot on a couple of giant
-  // landmasses, leaving the countries that ring the story unlabeled. The lower
-  // divisor + raised band caps roughly +50% the slots so the proximity rank has
-  // room to surface the neighbourhood. Still floors to ~1 on a thumbnail / 0 on a
-  // tiny canvas (AC9).
-  const area = Math.floor(Math.sqrt(Math.max(0, width * height)) / 105);
-  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,
-  font: number = FONT
-): 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,
-  font: number = FONT
-): LabelRect {
-  const lineHeight = font + 2; // MUST match the renderer's per-line stride
-  const w = Math.max(...lines.map((l) => labelWidth(l, letterSpacing, font)));
-  const h = (lines.length - 1) * lineHeight + 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,
-    countryTone,
-    waterTone,
-    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. Both are muted but CONTRAST-FLOORED in the
-  // caller (layout) against the substrate they sit on, and shared with the
-  // orientation backdrop so a context country and an orientation region match.
-  // Water stays the blue-gray italic convention; country = the muted land tone.
-  // Fallbacks keep the pre-floor behaviour for unit tests that omit the tones.
-  const waterColor =
-    waterTone ?? mix(palette.colors.blue, palette.textMuted, 50);
-  const countryColor = countryTone ?? palette.textMuted;
-  const haloColor = palette.bg;
-
-  type Candidate = {
-    text: string;
-    lines: string[];
-    cx: number;
-    cy: number;
-    italic: boolean;
-    letterSpacing: number;
-    color: string;
-    fontSize: number;
-    sort: number; // priority key (lower first)
-    // A sovereign nation (Canada/Mexico): committed unconditionally, outside the
-    // budget (Option A symmetric orientation). Absent on water + states.
-    bordering?: boolean;
-    // Ordered dodge positions (screen coords), best-first. Absent on water (single
-    // anchor); on a country, mirrors CountryCandidate.positions (anchor === [0]).
-    positions?: readonly (readonly [number, number])[];
-  };
-  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,
-      fontSize: FONT, // water names keep the base font (no footprint to scale on)
-      // Orientation-value bands (lower = earlier): MAJOR water (oceans + major
-      // seas, tier ≤ 1) leads at `tier*10+kind` (0..~16); MINOR water (tier ≥ 2:
-      // smaller seas, bays, gulfs, straits) drops to band 2 (2000+) — BELOW the
-      // country band (1000+), so a big country outranks a minor basin.
-      sort: (tier <= 1 ? 0 : 2000) + tier * 10 + KIND_ORDER[kind],
-    });
-  }
-
-  // -- Country candidates (unreferenced) --
-  // Rank by biggest-area-first — a deterministic, position-independent order (no
-  // proximity-to-POI weighting, which read as arbitrary: near-identical neighbours
-  // like Wyoming vs Texas won or lost a slot on a hair of distance). Nations are
-  // pulled out of the budget entirely at commit; among the budgeted states, the
-  // largest in-frame footprints win the rationed slots. Area also drives the
-  // font/fade ramp and the smear gate below.
-  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);
-  // Canvas linear extent — the denominator for the footprint size ramp below.
-  const canvasLinear = Math.sqrt(Math.max(1, width * height));
-  let ci = 0;
-  for (const r of ranked) {
-    const { c, w, h, area } = r;
-    // F2: an antimeridian-crossing / global-smear country fills the canvas in
-    // BOTH dimensions while its real landmass is split — the `path.centroid`
-    // anchor is then unreliable (mid-map, wrong basin). Reject only that
-    // both-axes canvas-smear: a country that is merely wide-but-short (Canada
-    // hugging the top of a US frame) or tall-but-narrow (Chile) is a legitimate
-    // landmass whose clipExtent-clipped centroid still lands over its own ground,
-    // so it must NOT be dropped for footprint shape alone. A `curatedAnchor`
-    // (WORLD_LABEL_ANCHORS, e.g. Russia → European Russia) is trustworthy by
-    // construction — the smear concern is moot, so it bypasses this gate (the
-    // `insideViewport` check below still drops an anchor that projects off-frame).
-    if (!c.curatedAnchor && w > width * 0.66 && h > height * 0.66) continue;
-    if (!insideViewport(c.anchor, width, height)) continue;
-    // Footprint-driven scale (Decision: big landmass = large, faded backdrop
-    // name). t∈[0,1] over the [MIN,MAX] linear-fraction band; font ramps up and
-    // ink rises in lockstep, so a bigger name reads as a large, softly-inked
-    // backdrop. A curated-anchor giant (Russia) keeps the standard big-country
-    // styling — its full-canvas bbox lands at the top of the ramp (font/ink like
-    // any large in-frame country), which is the intended subdued-backdrop look.
-    const sizeFrac = Math.sqrt(area) / canvasLinear;
-    const t = Math.min(
-      1,
-      Math.max(
-        0,
-        (sizeFrac - COUNTRY_SIZE_FRAC_MIN) /
-          (COUNTRY_SIZE_FRAC_MAX - COUNTRY_SIZE_FRAC_MIN)
-      )
-    );
-    const fontSize = Math.round(FONT + t * (COUNTRY_FONT_MAX - FONT));
-    // No fade. Subordination is by MUTING (the floored tone) + smaller size, not
-    // by fading toward bg — fading a floored tone toward the background would
-    // re-break the contrast it was floored to guarantee (the old behaviour washed
-    // big names like Canada toward illegibility). Footprint still drives font size.
-    const color = countryColor;
-    // 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, fontSize);
-    // Approximate fit (Decision 4): the (scaled) name fits inside the footprint
-    // bbox. NOT true point-in-polygon — cartographic labels routinely overrun
-    // coastlines. The bigger the font, the bigger the box it must clear.
-    if (tw > w || fontSize + 2 * PADY > h) continue;
-    candidates.push({
-      text,
-      lines: [text],
-      cx: c.anchor[0],
-      cy: c.anchor[1],
-      italic: false,
-      letterSpacing: 0,
-      color,
-      fontSize,
-      ...(c.bordering ? { bordering: true } : {}),
-      // Multi-position dodging: carry the ordered interior positions through to the
-      // commit loop. Invariant anchor === positions[0], so `cx/cy` is positions[0].
-      ...(c.positions ? { positions: c.positions } : {}),
-      // Band 1 (orientation-value ranking): above MINOR water (band 2, 2000+) but
-      // below MAJOR water — oceans + major seas (band 0, ≤~16). So a big country
-      // (US, Canada, Russia) outranks a minor sea/bay (Sargasso, Bahía de
-      // Campeche) yet never displaces an ocean. Larger area = earlier within the
-      // band (`ci` is the area-desc rank index).
-      sort: 1000 + 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[] = [];
-  // Guarantee state room: water can otherwise monopolise a small budget (a coastal
-  // view borders many oceans/seas), so reserve up to 2 slots for STATES whenever
-  // any state candidate exists. Nations don't draw from the budget (committed in
-  // pass 1 below), so they're excluded from this count. No effect on pure-water
-  // views (`stateCount` 0 ⇒ cap = budget).
-  const stateCount = candidates.reduce(
-    (n, c) => n + (!c.italic && !c.bordering ? 1 : 0),
-    0
-  );
-  const waterCap = budget - Math.min(2, stateCount);
-  let waterPlaced = 0;
-  let budgetUsed = 0;
-  // Test one trial position for a candidate against every gate (fit, water-on-land,
-  // committed-obstacle collision, context-overlap). Returns the placed rect when the
-  // position clears, else null. Country candidates carry several ordered positions
-  // (map-context-neighbor-labels); we walk them best-first and commit the first that
-  // clears, so a label dodges a colliding cluster instead of being dropped. Water
-  // candidates have a single position, so behaviour is unchanged for them.
-  const gateAt = (
-    cx: number,
-    cy: number,
-    cand: Candidate
-  ): LabelRect | null => {
-    const rect = rectAround(
-      cx,
-      cy,
-      cand.lines,
-      cand.letterSpacing,
-      cand.fontSize
-    );
-    if (!rectFits(rect, width, height)) return null;
-    // 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 = cy - ((cand.lines.length - 1) / 2) * LINE_HEIGHT;
-      const touchesLand = cand.lines.some((line, li) => {
-        const lw = labelWidth(line, cand.letterSpacing);
-        const x0 = cx - lw / 2 + inset;
-        const x1 = cx + lw / 2 - inset;
-        const xs = [x0, (x0 + cx) / 2, cx, (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) return null;
-    }
-    if (collides(rect)) return null;
-    if (placedRects.some((r) => overlapsPadded(rect, r, CONTEXT_PAD)))
-      return null;
-    return rect;
-  };
-  // Walk a candidate's ordered positions best-first; commit at the first that
-  // clears every gate. F8: `positions ?? [[cx,cy]]` keeps single-anchor (water +
-  // non-top-N country) behaviour identical. If none clears → drop (no halo, no
-  // overlap — D16). Returns true when the label was placed.
-  const tryPlace = (cand: Candidate): boolean => {
-    const positions = cand.positions ?? [[cand.cx, cand.cy]];
-    for (const [px, py] of positions) {
-      const rect = gateAt(px!, py!, cand);
-      if (!rect) continue;
-      placedRects.push(rect);
-      placed.push({
-        x: px!,
-        y: py!,
-        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,
-        fontSize: cand.fontSize,
-        italic: cand.italic,
-        letterSpacing: cand.letterSpacing,
-        ...(cand.lines.length > 1 ? { lines: cand.lines } : {}),
-        lineNumber: 0,
-      });
-      return true;
-    }
-    return false;
-  };
-
-  // Pass 1 — sovereign NATIONS touching the viewport, labeled UNCONDITIONALLY and
-  // OUTSIDE the budget (Option A: symmetric orientation — a US view shows Canada
-  // AND Mexico together, never one arbitrarily). Still gated on fit/collision, so a
-  // nation label never lands on data or off-canvas; it just isn't rationed. Placed
-  // FIRST so nations claim their ground before states/water fill the leftover.
-  for (const cand of candidates) if (cand.bordering) tryPlace(cand);
-
-  // Pass 2 — water + states, rationed by the budget (the nations placed above do
-  // not count against it).
-  for (const cand of candidates) {
-    if (cand.bordering) continue;
-    if (budgetUsed >= budget) break;
-    if (cand.italic && waterPlaced >= waterCap) continue;
-    if (tryPlace(cand)) {
-      budgetUsed++;
-      if (cand.italic) waterPlaced++;
-    }
-  }
-  return placed;
-}

package/src/map/data/PROVENANCE.json

@@ -1 +0,0 @@
-{"assets":{"airport-collisions.json":{"bytes":29,"gzBytes":49,"sha256":"a7d0107c5fcc6d787e010ea100ce1946bb724f7ae1a79eb1b862a8cf822ed1d8"},"airports.json":{"bytes":104083,"gzBytes":38159,"sha256":"c17294d4e3fd259e02c63c49c36c02d9ff34f4462103ff54516d29e93667cd76"},"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":{"airportCollisions":2,"airports":1565,"countries":175,"gazetteerAliases":8,"gazetteerCities":2119,"mountainRanges":205,"usStates":56,"waterBodies":113},"generatedBy":"scripts/build-map-data.mjs","sourceHashes":{"file:scripts/airports-snapshot.csv":{"bytes":308536,"sha256":"58b6e45bb91045c2897f1e7e14430aecc3b5eca911bcb389855495ff66ab9599"},"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)"},"ourairports":{"license":"Public Domain — https://ourairports.com/data/","note":"Lean committed slice (scheduled_service=yes + 3-letter iata_code). Regenerate is a deliberate, reviewed bump (ADR-4).","snapshot":"scripts/airports-snapshot.csv","source":"https://davidmegginson.github.io/ourairports-data/airports.csv"},"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

@@ -1,40 +0,0 @@
-# map chart-type data assets
-
-Generated by `scripts/build-map-data.mjs` (run `pnpm build:map-data`). These
-committed JSON files are the runtime artifacts for the `map` chart type. Do not
-hand-edit — regenerate from source.
-
-## Files
-- `world-coarse.json` / `world-detail.json` — world country boundaries (TopoJSON),
-  keyed by ISO 3166-1 alpha-2. Coarse = world-scale; detail = regional/zoom.
-- `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.
-- `types.ts` — the typed data contract consumed by the parser/resolver/renderer.
-
-## 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/.
-
-## Determinism & GeoNames drift
-Geometry assets are byte-reproducible from the pinned atlas versions (same machine
-+ `mapshaper@0.7.22`). The GeoNames dump is **rebuilt daily and has no pinnable
-snapshot**, so the committed `gazetteer.json` is the source of truth; a regenerate
-may pick up upstream city changes. `PROVENANCE.json` is the audit trail. The
-modification-date range it reports is over the *filtered* (kept) city subset.
-
-## Regenerate
-```
-pnpm build:map-data
-```

package/src/map/data/airport-collisions.json

@@ -1 +0,0 @@
-{"collisions":["aba","ufa"]}