@diagrammo/dgmo 0.21.0 → 0.22.0

package/src/map/layout.ts

@@ -8,6 +8,7 @@
 import {
   geoPath,
   geoNaturalEarth1,
+  geoEqualEarth,
   geoEquirectangular,
   geoConicEqualArea,
   geoMercator,
@@ -17,7 +18,15 @@ import {
   type GeoPath,
 } from 'd3-geo';
 import { feature } from 'topojson-client';
-import { mix, contrastText } from '../palettes/color-utils';
+import {
+  mix,
+  contrastRatio,
+  relativeLuminance,
+  politicalTints,
+} from '../palettes/color-utils';
+import { buildAdjacency } from './geo';
+import { assignColors } from './colorize';
+import { resolveColor } from '../colors';
 import type { PaletteColors } from '../palettes/types';
 import {
   rectsOverlap,
@@ -27,6 +36,7 @@ import {
 import type { LabelRect, PointCircle } from '../label-layout';
 import { measureLegendText } from '../utils/legend-constants';
 import { TITLE_FONT_SIZE, TITLE_Y } from '../utils/title-constants';
+import type { DgmoError } from '../diagnostics';
 import type { BoundaryTopology } from './data/types';
 import type {
   MapData,
@@ -35,6 +45,8 @@ import type {
   ResolvedEdge,
   ProjectionFamily,
 } from './resolved-types';
+import { placeContextLabels } from './context-labels';
+import type { CountryCandidate } from './context-labels';
 
 // Minimal GeoJSON shapes (avoid a hard @types/geojson dep; cast at d3 calls).
 interface GeoFeature {
@@ -57,39 +69,108 @@ const R_MAX = 22;
 const W_MIN = 1.25; // edge stroke width
 const W_MAX = 8;
 const FONT = 11; // on-map label font px
-const COLO_EPS = 1.5; // px: POIs closer than this are "co-located"
-// % palette-yellow of bg for unscored land. Higher on dark so the soft palette
-// yellow reads as yellow rather than muddying toward tan against the dark bg.
-const LAND_TINT_LIGHT = 58;
-const LAND_TINT_DARK = 75;
+// POI-cluster hover-only gate (Decision #1). A ≥2-member cluster's callout
+// column falls back to hover-only labels when it would sprawl or overflow:
+//  - MAX_CLUSTER_EXTENT_FACTOR × min(width,height) = the px diagonal beyond which
+//    a cluster is a sprawling chain (its leaders would fan across the map), not a
+//    tight blob. Resolution-relative so the decision is stable across zoom — the
+//    px threshold is computed per-render, NOT a constant.
+//  - MAX_COLUMN_ROWS = the most rows a single column can stack readably.
+// Exported for tests to drive the boundaries directly.
+export const MAX_CLUSTER_EXTENT_FACTOR = 0.18;
+export const MAX_COLUMN_ROWS = 7;
+// WCAG ratio below which a region label needs a halo to read on its own fill.
+// 4.5 = AA for normal text; mid-tone choropleth fills fall below this and get
+// the rescue halo, while saturated/pastel fills (Texas, light land) clear it.
+const REGION_LABEL_HALO_RATIO = 4.5;
+// % palette-green of bg for unscored land — a VERY faded green so every map
+// (plain reference OR data-coloured) wears the same subtle dress and the green
+// never competes with saturated tag/score tints. Dark lifts a touch off the
+// near-black surface so the faint green stays legible.
+const LAND_TINT_LIGHT = 12;
+const LAND_TINT_DARK = 24;
 // Categorical (tag) region fill: a flat, fairly saturated tint of the tag
 // colour so a tagged region reads as its CATEGORY against the tinted land base
 // — the generic 25% shape tint washes out and lets the olive land dominate.
 const TAG_TINT_LIGHT = 60;
 const TAG_TINT_DARK = 68;
-const WATER_TINT = 55; // % palette-blue of bg for the ocean / backdrop
+// % palette-blue of bg for the ocean / backdrop — a faded blue, kept light
+// enough not to compete with saturated blue/green data hues but distinctly
+// bluer than the land so the sea reads as water rather than blank canvas.
+const WATER_TINT_LIGHT = 24;
+const WATER_TINT_DARK = 24;
 const RIVER_WIDTH = 1.3; // px stroke width for river lines
+// Compact breakpoint (decision D2): below this effective render width a wide
+// extent reads as zoomed-out — prefer abbreviated region labels and suppress
+// relief, regardless of geographic extent.
+const COMPACT_WIDTH_PX = 480;
+// Relief (mountain-range shading). A projected range below this px² area is
+// dropped (no confetti slivers at world zoom).
+const RELIEF_MIN_AREA = 12; // px²
+// Each projected bbox side must clear this — drop near-degenerate slivers.
+const RELIEF_MIN_DIM = 2; // px
+// Relief = horizontal hachure lines clipped to each range: a subtle
+// dark-on-light / light-on-dark texture that reads as "mountains here". Spacing
+// is SCREEN-space so density is constant regardless of zoom (geo-space spacing
+// would collapse a small range to 1–2 lines and read as a glitch). Kept FAINT:
+// thin sub-pixel lines drawn with a non-scaling stroke (constant device width at
+// any zoom/DPR) and low-contrast colour. NOT crispEdges — that snaps the stroke
+// to a solid ~1px in WebKit and reads far too heavy; plain AA keeps them whisper-thin.
+const RELIEF_HATCH_SPACING = 2; // px between lines
+const RELIEF_HATCH_WIDTH = 0.15; // px stroke
+// % of the DARK reference (palette.bg on dark themes, palette.text on light)
+// blended into the land colour — so the lines read DARKER than the land in both
+// themes (palette.text alone flips to light on dark themes).
+const RELIEF_HATCH_STRENGTH = 32;
+// Coastline water-lines (opt-in `coastline`, §24B.2). N equal-width coast-parallel
+// rings on the water side, evenly spaced and FADING seaward — the antique
+// nautical-chart depth-contour look. Offshore distances + thickness are
+// SCREEN-space FRACTIONS of min(w,h) so the rings stay a constant fraction of the
+// canvas at ANY export size and ANY geographic extent (a decorative screen-space
+// cue, not a geographic offset — ADR-3). Tuned faint, water-toned, low-contrast.
+// minExtent = per-subpath degenerate-ring floor. Kept just above zero so EVERY
+// island — down to the smallest specks — grows coast rings; it only drops
+// sub-pixel/degenerate subpaths that would render nothing (R11). (Earlier it
+// culled small islands to de-noise world maps, but every island should carry the
+// nautical hashing, so the floor is now a bare degenerate guard.)
+// INVARIANT (load-bearing): COASTLINE_STEP > COASTLINE_THICKNESS — i.e. every
+// ring's d_k + thickness < d_(k+1). The renderer draws outer→inner; ring k's
+// colour band reaches radius d_k+thickness and its flat-water overdraw reaches
+// d_k. If a ring's band reached the next ring out, the inner overdraw would erase
+// it. Keep step > thickness; a layout test pins it (map-layout.test.ts).
+const COASTLINE_RING_COUNT = 5; // discrete coast-parallel rings
+const COASTLINE_D0 = 0.0016; // innermost ring offshore distance (frac of min dim)
+const COASTLINE_STEP = 0.0028; // spacing between rings (frac of min dim)
+const COASTLINE_THICKNESS = 0.0014; // ring width — SAME for every ring (frac)
+const COASTLINE_OPACITY_NEAR = 0.5; // innermost ring opacity
+const COASTLINE_OPACITY_FAR = 0.1; // outermost ring opacity (gradual fade)
+const COASTLINE_MIN_EXTENT = 0.0006; // degenerate-ring floor (frac of min dim)
+const COASTLINE_MIN_EXTENT_GLOBAL = 0.0006; // same at world zoom — ring every island
+// Water-line tone: mix regionStroke into water. LESS water than `lakeStroke`
+// (mix 45) so the offshore lines carry a touch MORE contrast than the existing
+// coast stroke and stay distinguishable from it (R10/F14).
+const COASTLINE_STROKE_MIX = 32;
 // % palette-gray of bg for non-US neighbour land. Higher on dark so it reads as
 // a clear gray rather than sinking into the dark background.
 const FOREIGN_TINT_LIGHT = 30;
 const FOREIGN_TINT_DARK = 62;
 // MUTED basemap — used when a colouring dimension (score ramp or a tag group) is
-// active. The data hues may themselves be blue or green (e.g. `Core blue`,
-// `Growth teal`), which collide with the decorative blue-water / green-land
-// dress: a blue region vanishes into the ocean, a green one into the land. So
-// when regions carry the data signal the basemap RECEDES to neutral grays —
-// water and unscored/neighbour land become low-saturation gray, leaving the data
-// fills as the only saturated thing on the map (the cartographic norm for a
-// choropleth). Plain reference maps with no data keep the blue/green dress.
-// Light land is left at the page bg (cleanest white ground for the data hues);
-// dark land lifts off the near-black surface so dark-mixed tints stay legible.
-const MUTED_WATER_LIGHT = 14; // % gray of bg — pale sea
-const MUTED_WATER_DARK = 10;
-const MUTED_FOREIGN_LIGHT = 28; // neighbour land — grayer than the sea
+// active. The subject water + land are ALWAYS the same faded blue/green dress
+// (WATER_TINT_* / LAND_TINT_*); muted only pushes NEIGHBOUR land to a recessive
+// gray so the subject country reads as the subject and the data fills own the
+// saturation. Plain reference maps keep neighbour land at the fuller gray tint.
+const MUTED_FOREIGN_LIGHT = 28; // neighbour land — recessive gray, not green
 const MUTED_FOREIGN_DARK = 16;
-const MUTED_LAND_DARK = 24; // subject land on dark (light land = palette.bg)
-const COLO_R = 9; // spiderfy radius
+const COLO_R = 9; // spiderfy ring radius floor (px)
 const GOLDEN_ANGLE = 2.399963229728653; // rad (137.5deg) -- even spiral, no random
+// Coincident-POI spiderfy (stacks): two dots "stack" when their centre distance is
+// below (rA+rB)*STACK_OVERLAP — i.e. the markers visibly overlap. A ≥2-member stack
+// collapses to a single ringed `+N` badge at rest and fans out on click; export
+// renders the expanded fan directly (all labels visible). Distinct-but-dense
+// clusters (centres farther than combined radii) are untouched — current behavior.
+const STACK_OVERLAP = 1.0; // overlap factor for the coincidence threshold
+const STACK_RING_MAX = 8; // ≤ this many → even circle; more → golden-angle spiral
+const STACK_RING_GAP = 4; // px min gap between adjacent expanded dots
 const FAN_STEP = 16; // px perpendicular offset between parallel edges
 const ARC_CURVE_FRAC = 0.18; // default arc bow as a fraction of leg length
 
@@ -98,6 +179,9 @@ export interface MapLayoutRegion {
   readonly d: string; // SVG path data
   readonly fill: string;
   readonly stroke: string;
+  /** Human-readable display name (e.g. "France", "California"). Set for EVERY
+   *  region — authored and base/context alike — and emitted as
+   *  `data-region-name` so the app can show it on hover. */
   readonly label?: string;
   readonly lineNumber: number;
   readonly layer: 'base' | 'country' | 'us-state';
@@ -121,6 +205,30 @@ export interface MapLayoutInset {
   readonly w: number;
   readonly h: number;
   readonly points: ReadonlyArray<readonly [number, number]>;
+  /** The FITTED inset projection (fit to this frame's screen box inside
+   *  `placeInset`). Load-bearing for pixel↔lonLat over the AK/HI insets: the
+   *  un-fitted `alaskaProjection()`/`hawaiiProjection()` factories would invert
+   *  to garbage, so the geo-query inverts against THIS instance. */
+  readonly projection: GeoProjection;
+  /** Neighbour land (e.g. Canada beside Alaska) projected with this inset's
+   *  fitted projection and clipped to the box — drawn BEHIND the state so a land
+   *  border reads as land, not coast. Without it the state's outer ring buffers
+   *  outward over open box-ocean and the land border sprouts coastline rings.
+   *  `undefined` when no neighbour land falls inside the box. */
+  readonly contextLand?: { readonly d: string; readonly fill: string };
+}
+
+/** Post-projection non-uniform stretch applied to GLOBAL fits (fill-the-canvas).
+ *  `null` for regional fits. The geo-query applies the forward form when
+ *  projecting and the inverse before `projection.invert`. Mirrors the `stretch`
+ *  closure used for the path stream:  px = ox + (x - bx0) * sx. */
+export interface MapLayoutStretch {
+  readonly sx: number;
+  readonly sy: number;
+  readonly ox: number;
+  readonly oy: number;
+  readonly bx0: number;
+  readonly by0: number;
 }
 
 export interface MapLayoutPoi {
@@ -137,6 +245,38 @@ export interface MapLayoutPoi {
   /** Tag values keyed by lowercased group name — emitted as `data-tag-<group>`
    *  so the app can spotlight markers on legend-entry hover (mirrors regions). */
   readonly tags?: Readonly<Record<string, string>>;
+  /** Set when this marker is a member of a coincident stack (spiderfy). Its
+   *  `cx/cy` is the EXPANDED ring position (the source-of-truth used by export +
+   *  the no-JS default); the app collapses the stack to a single badge at rest
+   *  via `data-cluster-member`. */
+  readonly clusterId?: string;
+}
+
+/** A coincident POI stack (≥2 markers whose dots overlap). Laid out EXPANDED
+ *  (members fanned onto a ring/spiral with legs to the centroid) — that geometry
+ *  is the source of truth: a static export shows every member + label with no
+ *  special-casing. The renderer ALSO emits a collapsed `+N`-style badge (a neutral
+ *  dot ringed with the bare count) at the centroid, hidden by default; the app
+ *  collapses each stack at rest (hide members, show badge) and expands on click. */
+export interface MapLayoutCluster {
+  /** Stable id (the first member's POI id). Mirrored on member dots/labels/legs as
+   *  `data-cluster-member` and on the badge as `data-cluster`. */
+  readonly id: string;
+  /** Centroid (collapsed badge position + spider-leg hub). */
+  readonly cx: number;
+  readonly cy: number;
+  /** Member count = badge text (bare `N`, RQ1). */
+  readonly count: number;
+  /** Radius of the transparent pointer hit-area centred on the centroid — covers
+   *  the collapsed badge AND the expanded dot ring so a hover/click anywhere over
+   *  the stack drives the spiderfy controller. */
+  readonly hitR: number;
+  /** Spider legs: centroid → each expanded member dot (member's own colour). */
+  readonly legs: ReadonlyArray<{
+    readonly x2: number;
+    readonly y2: number;
+    readonly color: string;
+  }>;
 }
 
 /** A drawn connector -- an edge or a route leg (same geometry contract). */
@@ -148,6 +288,17 @@ export interface MapLayoutLeg {
   readonly label?: string;
   readonly labelX?: number;
   readonly labelY?: number;
+  /** Text colour for the label — contrast-picked against the background fill the
+   *  label sits on (the choropleth/tag region under it, or land/water), so a
+   *  freight tag over a dark scored country reads light, over pale land reads
+   *  dark. Absent ⇒ renderer falls back to the muted default. */
+  readonly labelColor?: string;
+  /** Whether the label needs a halo. Only set when the chosen text colour's
+   *  contrast against the underlying fill is marginal (mid-tone fills); clear
+   *  fills get no ghost. */
+  readonly labelHalo?: boolean;
+  /** Halo colour (opposite lightness of `labelColor`) when {@link labelHalo}. */
+  readonly labelHaloColor?: string;
   readonly lineNumber: number;
 }
 
@@ -168,6 +319,24 @@ export interface PlacedLabel {
   /** The POI this label belongs to (POI labels only) — emitted as `data-poi` on
    *  the label + leader so the app can spotlight the dot on label hover. */
   readonly poiId?: string;
+  /** Cartographic italic (context-label water names, §24B). Default upright. */
+  readonly italic?: boolean;
+  /** Cartographic letter-spacing in px (context-label water names). Default 0. */
+  readonly letterSpacing?: number;
+  /** Pre-wrapped display lines (context-label water names — §24B). When present
+   *  the renderer stacks these as centred tspans instead of `text`; `text` keeps
+   *  the single-string form for hit-testing/measurement. Absent ⇒ single line. */
+  readonly lines?: readonly string[];
+  /** Hover-only label: emitted invisible (opacity 0 + `data-poi-hidden`) in the
+   *  preview and revealed on POI/label hover; OMITTED entirely from static
+   *  export. Set when a POI cluster can't place its labels cleanly (see the
+   *  extent/count/clean gate in the POI-label block). Default-undefined =
+   *  visible. Hidden labels are NOT pushed into `obstacles`. */
+  readonly hidden?: boolean;
+  /** Set when this label belongs to a coincident-stack member (spiderfy). Emitted
+   *  visible (export + expanded view) but tagged `data-cluster-member` so the app
+   *  hides it when the stack is collapsed to its badge. */
+  readonly clusterMember?: string;
   readonly lineNumber: number;
 }
 
@@ -194,6 +363,44 @@ export interface MapLayoutRiver {
   readonly width: number;
 }
 
+/** A drawn mountain-range relief shape — a projected polygon path. The renderer
+ *  unions these into one clip and rules horizontal hachure lines through them. */
+export interface MapLayoutRelief {
+  readonly d: string;
+}
+
+/** The shared hachure style for the relief lines. `null` when relief is off or
+ *  no range survives the gates. */
+export interface MapLayoutReliefHatch {
+  /** Line stroke — palette.text mixed into the land colour (so it's dark-on-
+   *  light and light-on-dark automatically as palette.text flips with theme). */
+  readonly color: string;
+  /** Vertical gap between lines in SCREEN px (constant density, zoom-stable). */
+  readonly spacing: number;
+  readonly width: number;
+}
+
+/** Style object for the opt-in coastline water-lines (`coastline`, §24B.2).
+ *  `null` when the flag is off. Carries only STYLE — no geometry; the renderer
+ *  buffers the existing region paths (`layout.regions[].d`) and masks them to the
+ *  water side. `d`/`thickness` are absolute SCREEN px (already resolved from a
+ *  fraction of the fitted canvas, so they stay proportional across export sizes —
+ *  ADR-3). */
+export interface MapLayoutCoastlineStyle {
+  /** Water-toned line colour (a touch more contrast than `lakeStroke`). */
+  readonly color: string;
+  /** The 2 coast-parallel lines, inner→outer. `d` = offshore distance,
+   *  `thickness` = ring width (both screen px), `opacity` fades seaward. */
+  readonly lines: ReadonlyArray<{
+    readonly d: number;
+    readonly thickness: number;
+    readonly opacity: number;
+  }>;
+  /** Per-subpath bbox-extent floor (screen px): rings smaller than this are
+   *  dropped (de-noise tiny islands, bound the stroke cost — R5/R11). */
+  readonly minExtent: number;
+}
+
 export interface MapLayout {
   readonly width: number;
   readonly height: number;
@@ -204,8 +411,21 @@ export interface MapLayout {
   readonly regions: readonly MapLayoutRegion[];
   /** Major river centerlines, drawn over land/lakes and under POIs/edges. */
   readonly rivers: readonly MapLayoutRiver[];
+  /** Mountain-range relief shapes (empty unless `relief` is on + the asset is
+   *  present); the renderer clips horizontal hachure lines to their union,
+   *  drawn over base land, under rivers/POIs/data fills. */
+  readonly relief: readonly MapLayoutRelief[];
+  /** Hachure style for the relief lines (null = relief off / none survived). */
+  readonly reliefHatch: MapLayoutReliefHatch | null;
+  /** Style for the opt-in coastline water-lines (null = `coastline` off). The
+   *  renderer buffers `regions[]`/`insetRegions[]` paths against this style and
+   *  masks them to the water side. */
+  readonly coastlineStyle: MapLayoutCoastlineStyle | null;
   readonly legs: readonly MapLayoutLeg[];
   readonly pois: readonly MapLayoutPoi[];
+  /** Coincident POI stacks (spiderfy). Empty when no ≥2-member overlap exists.
+   *  The renderer draws a collapsed badge per stack; the app collapses/expands. */
+  readonly clusters: readonly MapLayoutCluster[];
   readonly labels: readonly PlacedLabel[];
   readonly legend: MapLayoutLegend | null;
   /** Framed AK/HI inset cutouts (albers-usa only; empty otherwise). */
@@ -213,6 +433,16 @@ export interface MapLayout {
   /** AK/HI region paths drawn inside the inset boxes (foreground, over an
    *  opaque ocean fill). Paired positionally with `insets`. */
   readonly insetRegions: readonly MapLayoutRegion[];
+  /** The fitted MAIN projection (the conus conic for albers-usa). Exposed for
+   *  the geo-query's pixel↔lonLat inversion — the app NEVER reconstructs it from
+   *  metadata; it binds to this exact instance. */
+  readonly projection: GeoProjection;
+  /** Non-uniform stretch applied for GLOBAL fits (null for regional fits). */
+  readonly stretch: MapLayoutStretch | null;
+  /** Generic layout-time diagnostics channel — currently has no producers, so it
+   *  is always empty. Kept wired up because callers merge it with the resolver's
+   *  diagnostics for the editor lint channel. */
+  readonly diagnostics: readonly DgmoError[];
 }
 
 export interface LayoutOptions {
@@ -224,6 +454,11 @@ export interface LayoutOptions {
    *  selects the choropleth ramp, a tag-group name selects that group, `'none'`
    *  / `null` clears it. `undefined` = not provided (use the directive/default). */
   readonly activeGroup?: string | null;
+  /** Export-only: when true, suppress the global stretch-fill and contain-fit
+   *  (letterbox) instead. Set by `mapExportDimensions` when it clamps/floors the
+   *  canvas away from the content aspect, so the off-aspect canvas doesn't
+   *  re-distort. The in-app preview pane leaves this unset (keeps stretch-fill). */
+  readonly preferContain?: boolean;
 }
 
 interface Size {
@@ -239,13 +474,57 @@ function geomObject(topo: BoundaryTopology): {
   return topo.objects[key]!;
 }
 
-/** Decode every feature of a topology into GeoJSON, keyed by ISO id. */
+// Cache the (expensive) topojson→GeoJSON decode by topology object identity. The
+// MapData topology objects are stable within a session, so the same layer is
+// decoded once even though the export path now builds the projection twice (once
+// for dimension sizing, once for layout). Keyed by object identity (WeakMap), so
+// it never holds stale data across a data reload. CALLERS MUST TREAT THE RESULT AS
+// IMMUTABLE — `buildMapProjection` copies the world layer before its crisp-upgrade
+// `.set()` so the cached map is never mutated.
+const decodeCache = new WeakMap<BoundaryTopology, Map<string, GeoFeature>>();
+
+/** Combine two decoded features that share an ISO id into one MultiPolygon — so a
+ *  country split across multiple topology geometries (e.g. na-land's `FR`) draws
+ *  all its parts rather than only the last. Polygon/MultiPolygon coordinates are
+ *  flattened into a single MultiPolygon ring list; a feature whose geometry is
+ *  neither is returned unchanged (nothing sensible to merge). */
+function mergeFeatures(a: GeoFeature, b: GeoFeature): GeoFeature {
+  const polysOf = (f: GeoFeature): number[][][][] | null => {
+    const g = f.geometry as { type?: string; coordinates?: unknown } | null;
+    if (!g) return null;
+    if (g.type === 'Polygon') return [g.coordinates as number[][][]];
+    if (g.type === 'MultiPolygon') return g.coordinates as number[][][][];
+    return null;
+  };
+  const pa = polysOf(a);
+  const pb = polysOf(b);
+  if (!pa || !pb) return a; // can't merge non-polygonal geometry — keep the first
+  return {
+    ...a,
+    geometry: { type: 'MultiPolygon', coordinates: [...pa, ...pb] },
+  };
+}
+
+/** Decode every feature of a topology into GeoJSON, keyed by ISO id. Memoized by
+ *  topology identity — the returned map is shared, so do NOT mutate it (copy first
+ *  if you need to). Natural-Earth source carries hazards this guards against: a
+ *  null-geometry sovereignty stub tagged with a real ISO code (e.g. "Ashmore and
+ *  Cartier Is." shares `AU` with Australia) would otherwise CLOBBER the real
+ *  country's geometry — `set` keeps the last write. So null geometries are
+ *  skipped, and a genuine duplicate id (two real geometries, e.g. na-land `FR`)
+ *  is MERGED into one MultiPolygon instead of one part overwriting the other. */
 function decodeLayer(topo: BoundaryTopology): Map<string, GeoFeature> {
+  const cached = decodeCache.get(topo);
+  if (cached) return cached;
   const out = new Map<string, GeoFeature>();
   for (const g of geomObject(topo).geometries) {
     const f = feature(topo as never, g as never) as unknown as GeoFeature;
-    out.set(g.id, { ...f, id: g.id });
+    if (!f.geometry) continue; // null-geometry stub — never renders, must not clobber
+    const tagged = { ...f, id: g.id };
+    const existing = out.get(g.id);
+    out.set(g.id, existing ? mergeFeatures(existing, tagged) : tagged);
   }
+  decodeCache.set(topo, out);
   return out;
 }
 
@@ -266,21 +545,55 @@ function projectionFor(family: ProjectionFamily): GeoProjection {
       return usConusProjection();
     case 'mercator':
       return geoMercator();
+    case 'equal-earth':
+      // Equal-area pseudocylindrical: areas stay honest so a choropleth's shading
+      // isn't distorted by projection (the default for *data* world maps).
+      return geoEqualEarth();
+    case 'equirectangular':
+      // Plate carrée: straight lat/lon grid, fully rectangular frame. The default
+      // for dataless *reference* world maps — a clean conventional wall-map look.
+      return geoEquirectangular();
     case 'natural-earth':
+      // Curved pseudocylindrical compromise. Retained for completeness; areas are
+      // only approximately preserved.
       return geoNaturalEarth1();
-    case 'equirectangular':
     default:
-      // Plate carrée: x = λ, y = -φ. Cylindrical, so the extent's four CORNERS
-      // are its projected extremes — fitExtent frames it edge-to-edge with no
-      // bulge overflow (unlike naturalEarth, whose curved sides overrun a
-      // corner fit and clip the continents). Fills the rectangle: no rounded
-      // gray corners, no split landmass at the frame edge.
       return geoEquirectangular();
   }
 }
 
 /** US state ISO codes that render as insets (drawn off the conus). */
 const INSET_STATES = new Set(['US-AK', 'US-HI']);
+// Rough bboxes deciding whether a point sits in Alaska / Hawaii — the AK/HI
+// insets render only when the map references that state (§24B.2). Alaska's
+// Aleutians cross the antimeridian, so its longitude test is two-sided.
+const inAlaska = (lon: number, lat: number): boolean =>
+  lat >= 51 && (lon <= -129 || lon >= 172);
+const inHawaii = (lon: number, lat: number): boolean =>
+  lat >= 18 && lat <= 23 && lon >= -161 && lon <= -154;
+/** US states that visually abut a foreign country (Canada `CA` / Mexico `MX`) in
+ *  the drawn map — a fixed, extent-independent geographic fact. Used ONLY by the
+ *  colorize pass to bridge the US-states and world topologies (which share no
+ *  TopoJSON arcs) so a border state never shares a hue with the country it touches
+ *  (§24B colorize). Great-Lakes water-gap states (OH/PA) are excluded — they don't
+ *  visually touch Canada's drawn polygon. */
+const FOREIGN_BORDER: Readonly<Record<string, readonly string[]>> = {
+  CA: [
+    'US-AK',
+    'US-WA',
+    'US-ID',
+    'US-MT',
+    'US-ND',
+    'US-MN',
+    'US-MI',
+    'US-NY',
+    'US-VT',
+    'US-NH',
+    'US-ME',
+  ],
+  MX: ['US-CA', 'US-AZ', 'US-NM', 'US-TX'],
+};
+
 /** US territories excluded from the contiguous-US fit frame. */
 const US_NON_CONUS = new Set([
   'US-AK',
@@ -294,37 +607,34 @@ const US_NON_CONUS = new Set([
 
 /** The map's water / backdrop colour for a palette — the single source of truth
  *  shared by the renderer's `<rect>` fill and any host wrapper that needs to
- *  match it (so letterbox gaps around the SVG don't show a stray band). When
- *  `dataActive` (a score ramp or tag group is colouring regions) the sea recedes
- *  to a pale neutral so blue/green data hues don't blend into it. */
+ *  match it (so letterbox gaps around the SVG don't show a stray band). Always a
+ *  VERY faded blue — uniform whether or not a colouring dimension is active — so
+ *  it reads as water without competing with saturated blue/green data hues.
+ *  `_dataActive` is retained for signature stability (the sea no longer changes
+ *  with data; only neighbour land recedes — see layout's `foreignFill`). */
 export function mapBackgroundColor(
   palette: PaletteColors,
   isDark = false,
-  dataActive = false
+  _dataActive = false
 ): string {
-  if (dataActive)
-    return mix(
-      palette.colors.gray,
-      palette.bg,
-      isDark ? MUTED_WATER_DARK : MUTED_WATER_LIGHT
-    );
-  return mix(palette.colors.blue, palette.bg, WATER_TINT);
+  return mix(
+    palette.colors.blue,
+    palette.bg,
+    isDark ? WATER_TINT_DARK : WATER_TINT_LIGHT
+  );
 }
 
 /** The map's neutral (unscored/untagged) LAND colour — the base every region
  *  blends from. Exported so a host can DIM a region to plain land (rather than
  *  lowering opacity, which would let the water show through and make the shape
- *  read as ocean). Matches the layout's `neutralFill`. Green reference dress by
- *  default; neutral (page bg on light, lifted gray on dark) when `dataActive`. */
+ *  read as ocean). Matches the layout's `neutralFill`. Always a VERY faded green
+ *  — uniform whether or not data is active — so saturated tag/score tints read
+ *  clearly against it. `_dataActive` is retained for signature stability. */
 export function mapNeutralLandColor(
   palette: PaletteColors,
   isDark: boolean,
-  dataActive = false
+  _dataActive = false
 ): string {
-  if (dataActive)
-    return isDark
-      ? mix(palette.colors.gray, palette.bg, MUTED_LAND_DARK)
-      : palette.bg;
   return mix(
     palette.colors.green,
     palette.bg,
@@ -332,54 +642,223 @@ export function mapNeutralLandColor(
   );
 }
 
-export function layoutMap(
-  resolved: ResolvedMap,
-  data: MapData,
-  size: Size,
-  opts: LayoutOptions
-): MapLayout {
-  const { palette, isDark } = opts;
-  const { width, height } = size;
+/** Result of {@link buildMapProjection}: the (fresh, un-fitted) projection, fit
+ *  target, global/regional classification, and decoded basemap layers — all
+ *  derived from `(resolved, data)` alone (NOT canvas-size dependent). `layoutMap`
+ *  consumes these then does the size-dependent `fitExtent` + stretch/clip;
+ *  `mapContentAspect` consumes `projection`/`fitTarget` (+ the layers, for the
+ *  contain-fit ink bounds). MUST be rebuilt per call — d3 projections are mutated
+ *  in place by `fitExtent`/`clipExtent`, so the instance is never shared. */
+export interface MapProjectionBuild {
+  readonly projection: GeoProjection;
+  readonly fitTarget: GeoFC;
+  /** ≥270° lon or ≥130° lat span ⇒ global (stretch-fill) vs regional (contain). */
+  readonly fitIsGlobal: boolean;
+  readonly worldLayer: Map<string, GeoFeature>;
+  readonly usLayer: Map<string, GeoFeature> | null;
+  readonly usCrisp: boolean;
+  readonly wantsUsStates: boolean;
+  /** The RAW world topology `worldLayer` derives from (coarse vs detail). Carried
+   *  out so the colorize pass can build arc-adjacency on the same source the
+   *  drawn countries came from — memoized on this stable asset object. */
+  readonly worldTopo: BoundaryTopology;
+}
 
+/** Build the projection, fit target, and decoded basemap layers for a resolved
+ *  map. Extracted from `layoutMap` so the export-dimension helper
+ *  (`mapContentAspect`) frames the canvas with the IDENTICAL projection + fit
+ *  target the renderer draws with — divergence here would mismatch the canvas
+ *  aspect against the geometry. The returned projection has `.rotate` applied but
+ *  NOT `.fitExtent` (that is canvas-size dependent and stays in `layoutMap`). */
+export function buildMapProjection(
+  resolved: ResolvedMap,
+  data: MapData
+): MapProjectionBuild {
   // -- Basemap decode --
   const wantsUsStates = resolved.basemaps.subdivisions.includes('us-states');
   // In a US (albers-usa + us-states) view the surrounding land was world-atlas
   // 50m/110m — visibly coarser than the 10m states. When the NA-clipped 10m
   // assets are present, swap them in so neighbours (Canada/Mexico) and the Great
   // Lakes match the states' resolution. Falls back to the world tiers otherwise.
+  // Crisp NA assets apply to BOTH the national albers-usa view AND a regional
+  // US mercator view (POI-only region framing — e.g. a single state). A
+  // US-oriented mercator frame is sub-world and entirely within North America by
+  // construction, so the NA-clipped 10m land/lakes fit it; the bbox guard below
+  // still keeps non-NA countries on world geometry. Excludes equirectangular
+  // (a world US-states choropleth) where the NA clip would crop the globe.
   const usCrisp =
-    resolved.projection === 'albers-usa' && wantsUsStates && !!data.naLand;
+    (resolved.projection === 'albers-usa' ||
+      resolved.projection === 'mercator') &&
+    wantsUsStates &&
+    !!data.naLand;
   // Base world layer. In a US view use the DETAIL tier (full global coverage) so
   // distant context — South America, northern Canada, etc. — is present and can
-  // draw when it falls inside the frame. (`naLand` alone is bbox-clipped to lon
-  // -140..-52 / lat 10..66, so it has no S. America and a truncated Canada; using
-  // it as the base would leave ocean where that land belongs.)
+  // draw when it falls inside the frame.
   const worldTopo = usCrisp
     ? data.worldDetail
     : resolved.basemaps.world === 'detail'
       ? data.worldDetail
       : data.worldCoarse;
-  const worldLayer = decodeLayer(worldTopo);
-  // Crisp upgrade: `naLand` is 10m country land (vs the base's 50m) but clipped to
-  // a North-America bbox. Swap a country's geometry to the crisp version ONLY when
-  // its full (base) bounds lie inside that clip box — so contained neighbours
-  // (Mexico, Central America, the Caribbean) sharpen to match the 10m states,
-  // while countries the clip would truncate (Canada, Greenland) keep their full
-  // base shape. Coast off-frame still bleeds; nothing is lost.
+  // Copy the cached decode — the crisp-upgrade below mutates `worldLayer` via
+  // `.set()`, which must not poison the shared `decodeLayer` cache.
+  const worldLayer = new Map(decodeLayer(worldTopo));
+  // Crisp upgrade: swap a country's geometry to the 10m `naLand` version ONLY
+  // when its full (base) bounds lie inside the NA clip box.
   if (usCrisp && data.naLand) {
-    // NA clip bbox from the data build (scripts/build-map-data.mjs NA_BBOX).
     const [nbW, nbS, nbE, nbN] = [-140, 10, -52, 66];
     const crisp = decodeLayer(data.naLand);
     for (const [iso, cf] of crisp) {
       const base = worldLayer.get(iso);
       if (!base) continue; // crisp-only id with no base → skip (avoid orphans)
       const [[bw, bs], [be, bn]] = geoBounds(base as never);
+      // Keep the base feature's `properties` (the country name) — the crisp
+      // `naLand` geometry carries none, and the context-label layer reads the
+      // name from here. Without this the label falls back to the bare ISO code.
       if (bw >= nbW && be <= nbE && bs >= nbS && bn <= nbN)
-        worldLayer.set(iso, cf);
+        worldLayer.set(iso, { ...cf, properties: base.properties });
     }
   }
   const usLayer = wantsUsStates ? decodeLayer(data.usStates) : null;
 
+  // -- Projection + fit (AR2) --
+  // The extent outline sampled as a MultiPoint (NOT a Polygon — a hand-built
+  // lat/lon rectangle's spherical winding is ambiguous to d3-geo). Sampled ALONG
+  // the four edges so a curved projection (natural-earth) is framed at its bulge.
+  const extentOutline = (): GeoFeature => {
+    const [[w, s], [e, n]] = resolved.extent;
+    const N = 16;
+    const coords: Array<[number, number]> = [];
+    for (let i = 0; i <= N; i++) {
+      const t = i / N;
+      const lon = w + (e - w) * t;
+      const lat = s + (n - s) * t;
+      coords.push([lon, s], [lon, n], [w, lat], [e, lat]);
+    }
+    return {
+      type: 'Feature',
+      properties: {},
+      geometry: { type: 'MultiPoint', coordinates: coords },
+    };
+  };
+
+  let fitFeatures: GeoFeature[];
+  if (resolved.projection === 'albers-usa' && usLayer) {
+    // Frame the contiguous 48 + DC (insets/territories excluded). The conic
+    // projects everything else around it.
+    fitFeatures = [...usLayer.entries()]
+      .filter(([iso]) => !US_NON_CONUS.has(iso))
+      .map(([, f]) => f);
+    // Expand the frame to include referenced Canada/Mexico content so a
+    // near-border neighbour (e.g. Toronto) is visible rather than bleeding off
+    // the canvas edge. Only CA/MX content can reach this branch (the resolver's
+    // NA rule), so the frame can only grow toward those neighbours. AK/HI POIs
+    // stay insets — excluded here. Content-driven: a neighbour POI adds only its
+    // point (US barely shrinks); a neighbour country fill adds its full geometry.
+    const neighborPoints: Array<[number, number]> = resolved.pois
+      .filter((p) => !inAlaska(p.lon, p.lat) && !inHawaii(p.lon, p.lat))
+      .map((p) => [p.lon, p.lat]);
+    if (neighborPoints.length > 0) {
+      fitFeatures.push({
+        type: 'Feature',
+        properties: {},
+        geometry: { type: 'MultiPoint', coordinates: neighborPoints },
+      });
+    }
+    for (const r of resolved.regions) {
+      if (r.layer === 'country' && (r.iso === 'CA' || r.iso === 'MX')) {
+        const cf = worldLayer.get(r.iso);
+        if (cf) fitFeatures.push(cf);
+      }
+    }
+  } else {
+    fitFeatures = [extentOutline()];
+  }
+  const fitTarget: GeoFC = { type: 'FeatureCollection', features: fitFeatures };
+
+  const projection = projectionFor(resolved.projection);
+  // mercator / natural-earth: rotate to the extent's center longitude BEFORE
+  // fitting (rotate changes the bounds fitExtent measures). albers-usa is a
+  // US-only composite with NO .rotate -- never call it (AR2).
+  if (resolved.projection !== 'albers-usa') {
+    let centerLon = (resolved.extent[0][0] + resolved.extent[1][0]) / 2;
+    if (centerLon > 180) centerLon -= 360;
+    projection.rotate([-centerLon, 0]);
+  }
+
+  // Global vs regional classification (drives stretch-fill vs contain-fit).
+  const fitGB = geoBounds(fitTarget as never) as [
+    [number, number],
+    [number, number],
+  ];
+  const fitIsGlobal =
+    fitGB[1][0] - fitGB[0][0] >= 270 || fitGB[1][1] - fitGB[0][1] >= 130;
+
+  return {
+    projection,
+    fitTarget,
+    fitIsGlobal,
+    worldLayer,
+    usLayer,
+    usCrisp,
+    wantsUsStates,
+    worldTopo,
+  };
+}
+
+/** Split a projected geoPath `d` into its subpath rings (point arrays). geoPath
+ *  emits polygons as straight `M`/`L`/`Z` segments (no curves), so a flat parse
+ *  is exact. Each ring is one subpath (an outer boundary OR a hole); classify
+ *  outer-vs-hole downstream (e.g. via containment depth or signed area). Used by
+ *  fill hit-testing here and by the renderer's coastline water-lines. */
+export function parsePathRings(d: string): Array<Array<[number, number]>> {
+  const rings: Array<Array<[number, number]>> = [];
+  let cur: Array<[number, number]> = [];
+  const re = /([MLZ])([^MLZ]*)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(d))) {
+    if (m[1] === 'Z') {
+      if (cur.length) rings.push(cur);
+      cur = [];
+      continue;
+    }
+    if (m[1] === 'M' && cur.length) {
+      rings.push(cur);
+      cur = [];
+    }
+    const nums = m[2]!.split(/[ ,]+/).map(Number);
+    for (let i = 0; i + 1 < nums.length; i += 2) {
+      const x = nums[i]!;
+      const y = nums[i + 1]!;
+      if (Number.isFinite(x) && Number.isFinite(y)) cur.push([x, y]);
+    }
+  }
+  if (cur.length) rings.push(cur);
+  return rings;
+}
+
+export function layoutMap(
+  resolved: ResolvedMap,
+  data: MapData,
+  size: Size,
+  opts: LayoutOptions
+): MapLayout {
+  const { palette, isDark } = opts;
+  const { width, height } = size;
+
+  // -- Projection, fit target & basemap decode (shared with mapContentAspect so
+  // the export canvas aspect matches the drawn geometry — see buildMapProjection).
+  // The projection here has .rotate applied but NOT .fitExtent (done below, as it
+  // depends on canvas width/height). --
+  const {
+    projection,
+    fitTarget,
+    fitIsGlobal,
+    worldLayer,
+    usLayer,
+    usCrisp,
+    worldTopo,
+  } = buildMapProjection(resolved, data);
+
   const usContext = usLayer !== null;
   // Basemap fills (`water` / `neutralFill` / `foreignFill`) depend on whether a
   // colouring dimension is active — defined below, once `activeGroup` is known.
@@ -389,17 +868,33 @@ export function layoutMap(
   const regionStroke = isDark
     ? mix(palette.bg, palette.text, 78) // dark theme: near-bg dark outline
     : mix(palette.text, palette.bg, 78); // light theme: near-text dark outline
+  // Lake shoreline. Lakes are painted as water OVER the land and the region
+  // borders, so without an edge they read as a featureless patch that simply
+  // erases whatever state/country border ran beneath them (worst in muted/data
+  // mode, where the water is a pale gray barely distinct from the land). A soft
+  // coastline — between the border colour and the water, not a hard black line —
+  // gives the lake a defined edge; that edge legitimately REPLACES the border
+  // running through it (real choropleths carve lakes out of the land, so the
+  // shoreline IS the boundary at the water). Defined here; `water` is below.
 
   // -- Region fill model (choropleth + categorical; AR4/AR6) --
   const values = resolved.regions
     .filter((r) => r.value !== undefined)
     .map((r) => r.value!);
-  const scaleOverride = resolved.directives.scale;
-  const rampMin = scaleOverride ? scaleOverride.min : Math.min(...values);
-  const rampMax = scaleOverride ? scaleOverride.max : Math.max(...values);
-  // Value ramp is red so valued regions stand out against the blue water
-  // (palette.primary is a blue in most palettes and would blend in).
-  const rampHue = palette.colors.red;
+  // Ramp auto-fits (the `scale` directive is gone). For all-non-negative data the
+  // low end anchors at 0 so every such choropleth shares a 0 baseline (decision
+  // C); mixed-sign data fits data-min→data-max. Only the LOW end is shared —
+  // different maxes still differ at the high end (cross-map comparability is not
+  // recovered, by design).
+  const allNonNegative = values.length > 0 && values.every((v) => v >= 0);
+  const rampMin = allNonNegative ? 0 : Math.min(...values);
+  const rampMax = Math.max(...values);
+  // Value ramp defaults to red so valued regions stand out against the blue
+  // water (palette.primary is a blue in most palettes and would blend in). A
+  // trailing color on `region-metric` (§24B.3) overrides the hue idiomatically.
+  const rampHue =
+    resolveColor(resolved.directives.regionMetricColor ?? '', palette) ??
+    palette.colors.red;
   const hasRamp = values.length > 0;
 
   // Colouring dimension (AR4, bivariate): the value ramp and each tag group are
@@ -433,22 +928,17 @@ export function layoutMap(
   }
   const activeIsScore = VALUE_NAME !== null && activeGroup === VALUE_NAME;
 
-  // Basemap dress. When a colouring dimension is active the regions carry the
-  // signal, so the sea/land recede to neutral grays (the data hues — which may be
-  // blue or green — would otherwise blend into a blue ocean / green land). A
-  // plain reference map (no score, no tag → activeGroup null) keeps the blue
-  // water + green land. The bare `muted` / `natural` flags force either dress
-  // regardless (so two maps in a deck can match); absent → this auto rule. In a
-  // US view the surrounding world layer is always recessive gray so the US reads
-  // as the subject.
-  const mutedBasemap =
-    resolved.directives.basemapStyle === 'muted'
-      ? true
-      : resolved.directives.basemapStyle === 'natural'
-        ? false
-        : activeGroup !== null;
+  // Basemap dress (fixed automatic aesthetic — no directive). Subject water +
+  // land always wear the SAME faded blue/green dress (subtle enough that
+  // saturated tag/score tints never blend into it), so every map looks
+  // consistent. `mutedBasemap` governs only the NEIGHBOUR land: when a colouring
+  // dimension is active the surrounding world recedes to a paler gray so the
+  // subject + its data fills dominate; a plain reference map keeps neighbour
+  // land at the fuller gray.
+  const mutedBasemap = activeGroup !== null;
   const neutralFill = mapNeutralLandColor(palette, isDark, mutedBasemap);
   const water = mapBackgroundColor(palette, isDark, mutedBasemap);
+  const lakeStroke = mix(regionStroke, water, 45); // soft coastline (see above)
   const foreignFill = mix(
     palette.colors.gray,
     palette.bg,
@@ -461,6 +951,70 @@ export function layoutMap(
         : FOREIGN_TINT_LIGHT
   );
 
+  // -- Colorize: content-inferred distinct political fills (§24B) --
+  // Colorize is the DEFAULT dress for any map that is NOT colouring regions by
+  // data. The ONLY two things that turn it off: (1) a data dimension exists on a
+  // region (any `value:` or tag group) — data owns the saturation, so the basemap
+  // recedes to the gray choropleth/categorical dress; or (2) the `no-colorize`
+  // opt-out. Everything else — bare `map`, POI/route-only maps, named regions
+  // without data — gets distinct political pastels (markers/routes draw on top).
+  // Data EXISTENCE (not which dimension is *active*) is the discriminator, so a
+  // tag map viewed with `active-tag none` still keeps its neutral data dress; and
+  // the live-preview `California` → `California value: 92` edit transitions
+  // colorized → choropleth cleanly.
+  const colorizeActive =
+    resolved.directives.noColorize !== true &&
+    !hasRamp &&
+    resolved.tagGroups.length === 0;
+  // Hue per ISO over ONE UNIFIED graph spanning every drawn topology, so no two
+  // bordering regions share a hue — INCLUDING across the international seam. The
+  // world and us-states topologies share no TopoJSON arcs, so neighbors() is blind
+  // to the US↔Canada/Mexico border; those edges are fixed geographic facts (FOREIGN
+  // _BORDER) added explicitly. Coloring is global (whole topologies, not the drawn
+  // subset) and country codes sort before `US-XX`, so a country's colour is decided
+  // before any state is visited → extent-independent (France identical at any width
+  // and in an inset; AC10) and the same whether or not states are drawn. Every drawn
+  // ISO is in the graph, so the lookup never misses → no green leak (F14).
+  const colorByIso = new Map<string, string>();
+  if (colorizeActive) {
+    const adjacency = new Map<string, string[]>();
+    const addEdges = (src: ReadonlyMap<string, readonly string[]>): void => {
+      for (const [iso, ns] of src) {
+        const cur = adjacency.get(iso);
+        if (cur) cur.push(...ns);
+        else adjacency.set(iso, [...ns]);
+      }
+    };
+    addEdges(buildAdjacency(worldTopo)); // countries
+    if (usLayer) {
+      addEdges(buildAdjacency(data.usStates)); // US states
+      // International border seam (US states ↔ Canada/Mexico), both directions —
+      // the two topologies don't share arcs, so this is the only place the seam
+      // is expressible. Skip any endpoint not in the graph (defensive).
+      for (const [country, states] of Object.entries(FOREIGN_BORDER)) {
+        const cn = adjacency.get(country);
+        if (!cn) continue;
+        for (const st of states) {
+          const sn = adjacency.get(st);
+          if (!sn) continue;
+          cn.push(st);
+          sn.push(country);
+        }
+      }
+    }
+    const { byIso, huesNeeded } = assignColors(
+      [...adjacency.keys()],
+      adjacency
+    );
+    const tints = politicalTints(palette, huesNeeded, isDark);
+    for (const [iso, idx] of byIso) colorByIso.set(iso, tints[idx]!);
+  }
+  /** Per-region boundary stroke under colorize. Distinct FILLS aren't enough —
+   *  the boundary sells the separation (F10). Darken per-region toward the
+   *  palette text so the outline tracks each pastel; width stays the renderer
+   *  constant (the darker tone, not weight, does the work — AC12). */
+  const colorizeStroke = (fill: string): string => mix(fill, palette.text, 35);
+
   // Score ramp base: a NEUTRAL tint of the page, NOT the (green) land colour —
   // blending red toward green produced muddy brown mid-tones that blurred into
   // the unscored land. Anchored to a neutral, the ramp is a clean single-hue red
@@ -503,77 +1057,42 @@ export function layoutMap(
     );
   };
 
-  /** A region's fill under the ACTIVE colouring dimension (AR4, bivariate):
-   *  value-active → ramp for valued regions, neutral otherwise; a tag group
-   *  active → that group's tag colour, neutral otherwise (value ignored). */
+  /** A §1.5 trailing-token color on a region/POI → flat categorical fill, the
+   *  same saturated tint a tag entry gets (so direct colors and tag colors read
+   *  alike). Resolves the NAME against the active palette; null if unrecognized. */
+  const directFill = (name: string | undefined): string | null => {
+    const hex = name ? resolveColor(name, palette) : null;
+    if (!hex) return null;
+    return mix(hex, palette.bg, isDark ? TAG_TINT_DARK : TAG_TINT_LIGHT);
+  };
+
+  /** A region's fill. A direct trailing color (§24B.4) is a flat override that
+   *  paints regardless of the active dimension (no legend entry). Otherwise the
+   *  ACTIVE colouring dimension (AR4, bivariate): value-active → ramp for valued
+   *  regions, neutral otherwise; a tag group active → that group's tag colour,
+   *  neutral otherwise (value ignored). */
   const regionFill = (r: {
+    iso?: string;
     value?: number;
+    color?: string;
     tags: Readonly<Record<string, string>>;
   }): string => {
+    const direct = directFill(r.color);
+    if (direct) return direct; // §24B.4 direct color wins over colorize (F4)
     if (activeIsScore) {
       return r.value !== undefined ? fillForValue(r.value) : neutralFill;
     }
+    // Under colorize (activeGroup === null ⇒ not score) the terminal neutralFill
+    // is replaced by the region's political pastel; the value-path above is dead
+    // here (activeIsScore is false). Data/tag maps are untouched.
+    if (colorizeActive) return (r.iso && colorByIso.get(r.iso)) ?? neutralFill;
     return tagFill(r.tags, activeGroup) ?? neutralFill;
   };
 
   const regionById = new Map(resolved.regions.map((r) => [r.iso, r]));
 
-  // -- Projection + fit (AR2, refined) --
-  // For world projections we fit to the resolver's (padded, never-degenerate)
-  // extent box — fitting to raw drawn points would collapse to a zero-size
-  // target (single/coincident POIs → Infinity scale → NaN). albers-usa fits to
-  // its own conus features (below).
-  //
-  // The extent outline sampled as a MultiPoint — NOT a Polygon. A hand-built
-  // lat/lon rectangle's spherical winding is ambiguous to d3-geo, which can
-  // read it as the whole-globe complement (→ tiny content framed on a world
-  // map). Points have no interior/winding ambiguity, so fitExtent frames the
-  // box exactly. We sample ALONG the four edges (not just the corners) because
-  // a curved projection (natural-earth) bulges between corners — its widest x
-  // is at the equator and its lowest/highest y at the central meridian, neither
-  // of which is a corner. Fitting only corners under-frames the curve, so the
-  // continents at the frame's top/bottom/sides spill off and clip (S. Africa,
-  // Argentina, N. Russia). Equirectangular/mercator are linear, so the extra
-  // samples are redundant-but-harmless there.
-  const extentOutline = (): GeoFeature => {
-    const [[w, s], [e, n]] = resolved.extent;
-    const N = 16;
-    const coords: Array<[number, number]> = [];
-    for (let i = 0; i <= N; i++) {
-      const t = i / N;
-      const lon = w + (e - w) * t;
-      const lat = s + (n - s) * t;
-      coords.push([lon, s], [lon, n], [w, lat], [e, lat]);
-    }
-    return {
-      type: 'Feature',
-      properties: {},
-      geometry: { type: 'MultiPoint', coordinates: coords },
-    };
-  };
-
-  let fitFeatures: GeoFeature[];
-  if (resolved.projection === 'albers-usa' && usLayer) {
-    // Frame the contiguous 48 + DC (insets/territories excluded). The conic
-    // projects everything else — Canada, Mexico — around it, bleeding off the
-    // canvas edges so there's no empty water band and no hard clip line.
-    fitFeatures = [...usLayer.entries()]
-      .filter(([iso]) => !US_NON_CONUS.has(iso))
-      .map(([, f]) => f);
-  } else {
-    fitFeatures = [extentOutline()];
-  }
-  const fitTarget: GeoFC = { type: 'FeatureCollection', features: fitFeatures };
-
-  const projection = projectionFor(resolved.projection);
-  // mercator / natural-earth: rotate to the extent's center longitude BEFORE
-  // fitting (rotate changes the bounds fitExtent measures). albers-usa is a
-  // US-only composite with NO .rotate -- never call it (AR2).
-  if (resolved.projection !== 'albers-usa') {
-    let centerLon = (resolved.extent[0][0] + resolved.extent[1][0]) / 2;
-    if (centerLon > 180) centerLon -= 360;
-    projection.rotate([-centerLon, 0]);
-  }
+  // -- Fit the projection to the canvas (size-dependent; the projection + fit
+  // target themselves came from buildMapProjection above). --
   // Reserve top padding for the title/subtitle banner ONLY when there are POIs,
   // so their markers/labels don't project up under the title (which renders in
   // the foreground). A POI-less choropleth needs no reserve — the land fills to
@@ -603,15 +1122,19 @@ export function layoutMap(
   // a full canvas), but POI radii + label font sizes are applied in the renderer
   // (NOT here), so markers stay round and text stays un-squashed. Regional views
   // keep contain-fit: no distortion, neighbour land not cropped.
-  const fitGB = geoBounds(fitTarget as never) as [
-    [number, number],
-    [number, number],
-  ];
-  const fitIsGlobal =
-    fitGB[1][0] - fitGB[0][0] >= 270 || fitGB[1][1] - fitGB[0][1] >= 130;
+  //
+  // `preferContain` (set by the export-dimension helper when it clamps/floors the
+  // canvas away from the content aspect) suppresses the stretch even for a global
+  // extent: the canvas was intentionally sized off-aspect, so stretching would
+  // re-introduce the very distortion the content-aware sizing removes. We then
+  // contain-fit (letterbox over water) instead. The in-app preview pane never
+  // sets preferContain, so it keeps stretch-filling the pane. (`fitIsGlobal` comes
+  // from buildMapProjection.)
   let path: GeoPath;
   let project: (lon: number, lat: number) => [number, number] | null;
-  if (fitIsGlobal) {
+  // Captured for the geo-query (null unless this is a global stretch fit).
+  let stretchParams: MapLayoutStretch | null = null;
+  if (fitIsGlobal && !opts.preferContain) {
     const cb = geoPath(projection).bounds(fitTarget as never);
     const bx0 = cb[0][0];
     const by0 = cb[0][1];
@@ -621,6 +1144,7 @@ export function layoutMap(
     const oy = fitBox[0][1];
     const sx = cw > 0 ? (fitBox[1][0] - ox) / cw : 1;
     const sy = ch > 0 ? (fitBox[1][1] - oy) / ch : 1;
+    stretchParams = { sx, sy, ox, oy, bx0, by0 };
     const stretch = (x: number, y: number): [number, number] => [
       ox + (x - bx0) * sx,
       oy + (y - by0) * sy,
@@ -681,7 +1205,16 @@ export function layoutMap(
     name: string;
     lineNumber: number;
   }[] = [];
-  if (resolved.projection === 'albers-usa' && usLayer) {
+  // AK/HI insets are inferred (no directive): draw a state's inset only when the
+  // map references it (a valued/tagged state or a POI inside it). An all-US map
+  // that names neither frames the contiguous states alone (§24B.2).
+  const akRef =
+    resolved.regions.some((r) => r.iso === 'US-AK') ||
+    resolved.pois.some((p) => inAlaska(p.lon, p.lat));
+  const hiRef =
+    resolved.regions.some((r) => r.iso === 'US-HI') ||
+    resolved.pois.some((p) => inHawaii(p.lon, p.lat));
+  if (resolved.projection === 'albers-usa' && usLayer && (akRef || hiRef)) {
     const PAD = 8;
     const GAP = 12; // px the top edge rides below the coast
     const yB = height - FIT_PAD; // lowest a box may reach (canvas bottom pad)
@@ -719,53 +1252,20 @@ export function layoutMap(
       }
       return y;
     };
-    // Top edge for a box over [x0, xr]: a straight line PARALLEL to the local
-    // coast (least-squares over the land samples), pushed down so it clears every
-    // land sample by GAP. Parallel → uniform, maximal clearance for how close it
-    // sits, tilting the way the coast tilts. Open-ocean samples are skipped, so a
-    // box reaching past the coast isn't dragged down by water. Falls back to a
-    // flat line just under the lowest land if the fit is underdetermined.
-    const coastTop = (x0: number, xr: number): ((x: number) => number) => {
+    // Lowest the coast reaches across [x0, xr], or -Infinity over open ocean.
+    const coastFloor = (x0: number, xr: number): number => {
       const n = 24;
-      const pts: Array<[number, number]> = [];
       let maxY = -Infinity;
       for (let i = 0; i <= n; i++) {
-        const x = x0 + ((xr - x0) * i) / n;
-        const y = at(x);
-        if (y > -Infinity) {
-          pts.push([x, y]);
-          if (y > maxY) maxY = y;
-        }
-      }
-      if (pts.length === 0) return () => yB - height * 0.42; // all ocean
-      let m = 0;
-      if (pts.length >= 2) {
-        let sx = 0,
-          sy = 0,
-          sxx = 0,
-          sxy = 0;
-        for (const [x, y] of pts) {
-          sx += x;
-          sy += y;
-          sxx += x * x;
-          sxy += x * y;
-        }
-        const den = pts.length * sxx - sx * sx;
-        if (den !== 0) m = (pts.length * sxy - sx * sy) / den;
+        const y = at(x0 + ((xr - x0) * i) / n);
+        if (y > maxY) maxY = y;
       }
-      // Cap the tilt so a steep coast (e.g. California's) doesn't turn the box
-      // into a tall triangle — keep it a compact, gently-angled quad.
-      m = Math.max(-0.35, Math.min(0.35, m));
-      let c = -Infinity; // raise the line until it clears every land sample + GAP
-      for (const [x, y] of pts) {
-        const need = y - m * x + GAP;
-        if (need > c) c = need;
-      }
-      return (x: number) => m * x + c;
+      return maxY;
     };
     // A snug floating box that just contains the state, tucked up under the coast
-    // with a coast-parallel slanted top. `iwReq` is the requested inner width.
-    // Returns the box's right edge so the next inset can sit beside it.
+    // with a flat top sitting GAP below the lowest the coast reaches over its
+    // span. `iwReq` is the requested inner width. Returns the box's right edge so
+    // the next inset can sit beside it.
     const placeInset = (
       iso: string,
       proj: GeoProjection,
@@ -779,23 +1279,19 @@ export function layoutMap(
       const iw = Math.min(iwReq, width - FIT_PAD - x0 - 2 * PAD);
       if (iw < 24) return boxX; // canvas truly too narrow for another inset
       const xr = x0 + iw + 2 * PAD;
-      const top = coastTop(x0, xr);
-      const yL = top(x0);
-      const yR = top(xr);
+      const floor = coastFloor(x0, xr);
+      const topGuess = floor > -Infinity ? floor + GAP : yB - height * 0.42;
       // Learn the state's height at this width, then size the box to just hold it.
       proj.fitWidth(iw, f as never);
       const bb = geoPath(proj).bounds(f as never);
       const sh = Number.isFinite(bb[0][0]) ? bb[1][1] - bb[0][1] : iw;
-      // State sits below the lower top corner. If the coast runs so low the state
-      // wouldn't fit above yB, raise the top (the corner stays over ocean) — the
-      // box must never collapse and vanish.
+      // Flat top sits just under the coast. If the coast runs so low the state
+      // wouldn't fit above yB, raise the top (it stays over ocean) — the box must
+      // never collapse and vanish.
       const needH = sh + 2 * PAD;
-      let topFit = Math.max(yL, yR);
+      let topFit = topGuess;
       const bottom = Math.min(topFit + needH, yB);
       if (bottom - topFit < needH) topFit = bottom - needH;
-      const lift = topFit - Math.max(yL, yR); // keep the slanted top straight
-      const topL = yL + lift;
-      const topR = yR + lift;
       proj.fitExtent(
         [
           [x0 + PAD, topFit + PAD],
@@ -805,8 +1301,28 @@ export function layoutMap(
       );
       const d = geoPath(proj)(f as never) ?? '';
       if (!d) return xr;
+      // Neighbour land projected with this same fitted projection, clipped to the
+      // box. Alaska's only land neighbour is Canada; drawing it behind AK turns
+      // the eastern AK/Canada border into a land boundary so it grows no coastline
+      // rings (and fills the box's upper-right corner with recessive context).
+      let contextLand: { d: string; fill: string } | undefined;
+      if (iso === 'US-AK') {
+        const can = worldLayer.get('CA');
+        const cd = can ? (geoPath(proj)(can as never) ?? '') : '';
+        if (cd)
+          contextLand = {
+            d: cd,
+            fill: colorizeActive
+              ? (colorByIso.get('CA') ?? foreignFill)
+              : foreignFill,
+          };
+      }
       const r = regionById.get(iso);
-      let fill = neutralFill;
+      // Inset land reads the SAME colorByIso as the main frame → AK/HI identical
+      // to their main-frame colour (extent-independent; AC10/AC11).
+      let fill = colorizeActive
+        ? (colorByIso.get(iso) ?? neutralFill)
+        : neutralFill;
       let lineNumber = -1;
       if (r?.layer === 'us-state') {
         fill = regionFill(r);
@@ -814,21 +1330,25 @@ export function layoutMap(
       }
       insets.push({
         x: x0,
-        y: Math.min(topL, topR),
+        y: topFit,
         w: xr - x0,
-        h: bottom - Math.min(topL, topR),
+        h: bottom - topFit,
         points: [
-          [x0, topL],
-          [xr, topR],
+          [x0, topFit],
+          [xr, topFit],
           [xr, bottom],
           [x0, bottom],
         ],
+        // The FITTED inset projection (just fit to this box) — captured so the
+        // geo-query can invert pixels inside the frame back to AK/HI coords.
+        projection: proj,
+        ...(contextLand && { contextLand }),
       });
       insetRegions.push({
         id: iso,
         d,
         fill,
-        stroke: regionStroke,
+        stroke: colorizeActive ? colorizeStroke(fill) : regionStroke,
         lineNumber,
         layer: 'us-state',
         ...(r?.value !== undefined && { value: r.value }),
@@ -842,13 +1362,17 @@ export function layoutMap(
       return xr;
     };
     // AK is the larger state; HI a small island group tucked to its right.
-    const akRight = placeInset(
-      'US-AK',
-      alaskaProjection(),
-      FIT_PAD,
-      width * 0.15
-    );
-    placeInset('US-HI', hawaiiProjection(), akRight + 24, width * 0.1);
+    // Each draws only when referenced; HI slides left to FIT_PAD if AK is absent.
+    let akRight = FIT_PAD;
+    if (akRef)
+      akRight = placeInset('US-AK', alaskaProjection(), FIT_PAD, width * 0.15);
+    if (hiRef)
+      placeInset(
+        'US-HI',
+        hawaiiProjection(),
+        akRef ? akRight + 24 : FIT_PAD,
+        width * 0.1
+      );
   }
 
   // -- Basemap culling --
@@ -904,15 +1428,31 @@ export function layoutMap(
       loMax = -Infinity,
       rawMin = Infinity,
       rawMax = -Infinity;
+    const lons: number[] = [];
     for (const [rawLon] of ring) {
       const lon = normLon(rawLon);
+      lons.push(lon);
       if (lon < loMin) loMin = lon;
       if (lon > loMax) loMax = lon;
       if (rawLon < rawMin) rawMin = rawLon;
       if (rawLon > rawMax) rawMax = rawLon;
     }
-    if (loMax - loMin > 270) return false; // circumpolar/polar-wrap garbage
-    if (rawMax - rawMin > 180 && loMax - loMin < 90) return false; // seam sliver
+    // OCCUPIED longitude arc (complement of the largest empty gap), NOT the raw
+    // min→max span: a landmass crossing the antimeridian (Russia: points near
+    // −180° AND +180° via Chukotka) has a ~360° min→max span but only a ~171°
+    // occupied arc. The naive `loMax−loMin > 270` test mistook Russia for
+    // circumpolar garbage and dropped all of mainland Russia from regional views.
+    // A truly pole-wrapping ring occupies ~360° (no large gap) and is still
+    // dropped. (#russia-cull)
+    lons.sort((a, b) => a - b);
+    let maxGap = 0;
+    for (let i = 1; i < lons.length; i++)
+      maxGap = Math.max(maxGap, lons[i]! - lons[i - 1]!);
+    if (lons.length > 1)
+      maxGap = Math.max(maxGap, lons[0]! + 360 - lons[lons.length - 1]!);
+    const occupiedArc = 360 - maxGap;
+    if (occupiedArc > 270) return false; // circumpolar/polar-wrap garbage
+    if (rawMax - rawMin > 180 && occupiedArc < 90) return false; // seam sliver
     // Projected-bbox ∩ canvas. project() honours the active projection (and
     // ignores clipExtent, so positions are true), so this is exactly "does any
     // of this ring fall on the canvas".
@@ -961,7 +1501,7 @@ export function layoutMap(
 
   // View-INDEPENDENT frame-fill guard. An antimeridian-crossing ring whose true
   // occupied longitude arc is small (e.g. Fiji: islands at 177°E and 178°W, a
-  // ~5° arc straddling the seam) projects under equirectangular to two slivers
+  // ~5° arc straddling the seam) projects under a world projection to two slivers
   // at opposite frame edges; the fill between them inverts to paint the WHOLE
   // ocean as land. `cullFeatureToView` drops these in a regional view, but a
   // global/world view skips culling — so they must be dropped here regardless.
@@ -1023,7 +1563,14 @@ export function layoutMap(
     for (const [iso, f] of layerFeatures) {
       // Alaska/Hawaii are drawn as insets under albers-usa — skip them in the
       // main conus layer (the conic would otherwise place them far off-frame).
-      if (layerKind === 'us-state' && usContext && INSET_STATES.has(iso))
+      // Only albers-usa relocates them to insets; on a world/regional projection
+      // they have no inset and must draw in place from the us-states layer.
+      if (
+        layerKind === 'us-state' &&
+        usContext &&
+        resolved.projection === 'albers-usa' &&
+        INSET_STATES.has(iso)
+      )
         continue;
       // In a US view the us-states layer paints the whole country — drop the
       // redundant US country polygon underneath it (it only adds a coarser base
@@ -1046,7 +1593,12 @@ export function layoutMap(
       const isThisLayer = r?.layer === layerKind;
       // Non-US neighbour land in a US view is gray context, not yellow land.
       const isForeign = layerKind === 'country' && usContext && iso !== 'US';
-      let fill = isForeign ? foreignFill : neutralFill;
+      // Under colorize EVERY drawn political region — referenced, context, or
+      // neighbour — gets its pastel, so the whole visible set reads as one map
+      // (foreignFill/neutralFill bypassed; F9). The referenced branch below routes
+      // through regionFill (direct color still wins).
+      const baseFill = isForeign ? foreignFill : neutralFill;
+      let fill = colorizeActive ? (colorByIso.get(iso) ?? baseFill) : baseFill;
       let label: string | undefined;
       let lineNumber = -1;
       let layer: MapLayoutRegion['layer'] = 'base';
@@ -1056,12 +1608,17 @@ export function layoutMap(
         lineNumber = r.lineNumber;
         layer = layerKind;
         label = r.name;
+      } else {
+        // Base/context land (not authored): still carry the display name so the
+        // app can show it on hover. Names live on the geo feature's properties
+        // (the same source the resolver/inset/context-label layers read).
+        label = (f.properties as { name?: string } | null)?.name;
       }
       regions.push({
         id: iso,
         d,
         fill,
-        stroke: regionStroke,
+        stroke: colorizeActive ? colorizeStroke(fill) : regionStroke,
         lineNumber,
         layer,
         ...(label !== undefined && { label }),
@@ -1098,17 +1655,179 @@ export function layoutMap(
         id: 'lake',
         d,
         fill: water,
-        stroke: 'none',
+        stroke: lakeStroke,
         lineNumber: -1,
         layer: 'base',
       });
     }
   }
 
-  // Rivers (Amazon, Nile, Mississippi, …) as thin water lines over the land,
-  // the SAME blue as the ocean/lakes so a river reads as continuous with the
-  // water it drains into. Open paths: stroked, no fill; under POIs/edges/labels.
-  const riverColor = water;
+  // -- Background-fill hit-testing (for connector-label contrast) --
+  // A freight/edge label floats over whatever region the route crosses — a dark
+  // scored country, pale land, or open water. To pick a legible text shade (and
+  // skip the ghost halo when not needed) we need the fill UNDER the label point.
+  // Test in SCREEN space against the already-drawn region paths: that sidesteps
+  // every projection wrinkle (global stretch, antimeridian, AK/HI insets) because
+  // the geometry is already projected (see module-level `parsePathRings`).
+  // Even-odd ray cast across ALL of a feature's rings at once, so polygons with
+  // holes (a ring inside a ring) toggle correctly.
+  const pointInRings = (
+    px: number,
+    py: number,
+    rings: Array<Array<[number, number]>>
+  ): boolean => {
+    let inside = false;
+    for (const ring of rings) {
+      for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+        const [xi, yi] = ring[i]!;
+        const [xj, yj] = ring[j]!;
+        if (
+          yi > py !== yj > py &&
+          px < ((xj - xi) * (py - yi)) / (yj - yi) + xi
+        )
+          inside = !inside;
+      }
+    }
+    return inside;
+  };
+  // Precompute hit targets once (regions are drawn in array order, so the LAST
+  // containing one is topmost). Insets paint over neighbour land in their own box.
+  const fillHitTargets = [...regions, ...insetRegions].map((r) => ({
+    fill: r.fill,
+    rings: parsePathRings(r.d),
+  }));
+  const fillAt = (x: number, y: number): string => {
+    let hit = water; // open ocean / canvas backdrop when over no land
+    for (const t of fillHitTargets)
+      if (pointInRings(x, y, t.rings)) hit = t.fill;
+    return hit;
+  };
+  // Contrast-pick text colour for a label sitting ON `fill` (shared by region
+  // labels and connector labels): the genuinely higher-contrast of the palette's
+  // light/dark on-fill text, with a halo only when that contrast is marginal
+  // (mid-tone fills), so clear fills carry no ghost.
+  const labelOnFill = (
+    fill: string
+  ): { color: string; halo: boolean; haloColor: string } => {
+    const color =
+      contrastRatio(fill, palette.textOnFillDark) >=
+      contrastRatio(fill, palette.textOnFillLight)
+        ? palette.textOnFillDark
+        : palette.textOnFillLight;
+    const haloColor =
+      color === palette.textOnFillLight
+        ? palette.textOnFillDark
+        : palette.textOnFillLight;
+    return {
+      color,
+      halo: contrastRatio(fill, color) < REGION_LABEL_HALO_RATIO,
+      haloColor,
+    };
+  };
+
+  // Relief (notable mountain ranges) — horizontal hachure lines clipped to each
+  // range, drawn over the base land and under rivers/POIs/data fills. Opt-in via
+  // the `relief` flag; needs the optional `mountainRanges` asset. Each surviving
+  // range is projected to a polygon path; the renderer unions them into a clip
+  // and rules screen-spaced horizontal lines through it — a distinct texture
+  // that reads as "mountains here" without elevation data. Ranges below a min
+  // projected area/dimension are dropped (no slivers). Data-region suppression
+  // (ADR-2) is handled at the RENDER clip — relief is clipped to land MINUS the
+  // data-coloured regions, so a range that crosses a valued state still shows on
+  // the un-valued land around it (a bbox drop here would nuke the whole range).
+  // Relief is ALWAYS on; only the `no-relief` directive turns it off. It renders
+  // on data maps too (the renderer lays the hachure ATOP the choropleth/tag fills
+  // and the hatch tone flips to stay visible over muted land), at every zoom, and
+  // at every width. The only remaining filters are per-range quality guards below
+  // (sub-min-area / sub-min-dimension slivers are skipped so a range never draws
+  // as a sub-pixel smudge) — those drop individual ranges, never the feature.
+  const reliefAllowed = resolved.directives.noRelief !== true;
+  const relief: MapLayoutRelief[] = [];
+  let reliefHatch: MapLayoutReliefHatch | null = null;
+  if (reliefAllowed && data.mountainRanges) {
+    for (const [, f] of decodeLayer(data.mountainRanges)) {
+      const viewF = isGlobalView ? dropFrameFillers(f) : cullFeatureToView(f);
+      if (!viewF) continue;
+      const area = path.area(viewF as never);
+      if (!Number.isFinite(area) || area < RELIEF_MIN_AREA) continue;
+      const box = path.bounds(viewF as never) as [
+        [number, number],
+        [number, number],
+      ];
+      if (
+        box[1][0] - box[0][0] < RELIEF_MIN_DIM ||
+        box[1][1] - box[0][1] < RELIEF_MIN_DIM
+      )
+        continue;
+      const d = path(viewF as never) ?? '';
+      if (!d) continue;
+      relief.push({ d });
+    }
+    if (relief.length) {
+      // Prefer DARK hachure (blend land toward the dark tone — bg on dark
+      // themes, text on light). But on a muted/data map the un-valued land is
+      // already near-black, so darkness can't show: if the dark tone barely
+      // differs from the land, flip to the light tone so the lines stay visible.
+      const darkTone = isDark ? palette.bg : palette.text;
+      const lightTone = isDark ? palette.text : palette.bg;
+      // Relief is ONE global clipped layer with a single colour (renderer.ts) —
+      // a per-region hatch tone over varied pastels would need a renderer
+      // rearchitecture (out of scope; v2). Under colorize the political tints are
+      // pale washes sitting near the surface/bg, so referencing that base picks a
+      // fixed mid-contrast hatch tone that reads over all of them (AC15/G2).
+      const reliefLandRef = colorizeActive
+        ? isDark
+          ? palette.surface
+          : palette.bg
+        : neutralFill;
+      const landLum = relativeLuminance(reliefLandRef);
+      const tone =
+        Math.abs(landLum - relativeLuminance(darkTone)) > 0.04
+          ? darkTone
+          : lightTone;
+      reliefHatch = {
+        color: mix(tone, reliefLandRef, RELIEF_HATCH_STRENGTH),
+        spacing: RELIEF_HATCH_SPACING,
+        width: RELIEF_HATCH_WIDTH,
+      };
+    }
+  }
+
+  // Coastline water-lines style (opt-in `coastline`, §24B.2). No geometry/asset:
+  // the renderer derives the lines from the already-drawn region paths and masks
+  // them to the water side. We only resolve the proportional screen-space style
+  // here (fractions of min(w,h) → absolute px, so the offshore distance stays a
+  // constant fraction of the canvas at any export size — ADR-3). Differs from
+  // relief: a touch more contrast than `lakeStroke` so the offshore lines read as
+  // distinct from the coast stroke (R10/F14).
+  let coastlineStyle: MapLayoutCoastlineStyle | null = null;
+  if (resolved.directives.noCoastline !== true) {
+    const minDim = Math.min(width, height);
+    coastlineStyle = {
+      color: mix(regionStroke, water, COASTLINE_STROKE_MIX),
+      // N equal-width rings: distance steps outward by COASTLINE_STEP; opacity
+      // fades linearly from NEAR (innermost) to FAR (outermost).
+      lines: Array.from({ length: COASTLINE_RING_COUNT }, (_, k) => ({
+        d: (COASTLINE_D0 + k * COASTLINE_STEP) * minDim,
+        thickness: COASTLINE_THICKNESS * minDim,
+        opacity:
+          COASTLINE_OPACITY_NEAR +
+          ((COASTLINE_OPACITY_FAR - COASTLINE_OPACITY_NEAR) * k) /
+            (COASTLINE_RING_COUNT - 1),
+      })),
+      minExtent:
+        (isGlobalView ? COASTLINE_MIN_EXTENT_GLOBAL : COASTLINE_MIN_EXTENT) *
+        minDim,
+    };
+  }
+
+  // Rivers (Amazon, Nile, Mississippi, …) as thin water lines over the land.
+  // A deliberate water-blue — a more saturated cousin of the body-of-water
+  // `water` tone (which is a very faded blue, §mapBackgroundColor) so the line
+  // reads clearly as a water course, not a dark gap where it crosses a border.
+  // Mixing toward the border tone instead reads as a broken boundary in
+  // muted/data mode. Open paths: stroked, no fill; under POIs/edges/labels.
+  const riverColor = mix(palette.colors.blue, water, 32);
   const rivers: MapLayoutRiver[] = [];
   if (data.rivers) {
     for (const [, f] of decodeLayer(data.rivers)) {
@@ -1138,8 +1857,12 @@ export function layoutMap(
     return R_MIN + Math.max(0, Math.min(1, t)) * (R_MAX - R_MIN);
   };
 
-  // POI tag color: FIRST declared group for which the POI has a value (AR4).
+  // POI fill precedence (§24B.5): a direct §1.5 trailing color wins, then the
+  // FIRST declared tag group for which the POI has a value (AR4), then orange.
   const poiFill = (p: ResolvedPoi): { fill: string; stroke: string } => {
+    const directHex = p.color ? resolveColor(p.color, palette) : null;
+    if (directHex)
+      return { fill: directHex, stroke: mix(directHex, palette.text, 18) };
     for (const group of resolved.tagGroups) {
       const val = p.tags[group.name.toLowerCase()];
       if (!val) continue;
@@ -1183,38 +1906,136 @@ export function layoutMap(
     const xy = project(p.lon, p.lat);
     if (xy) projected.push({ p, xy });
   }
-  const coloGroups = new Map<string, Proj[]>();
+  const placePoi = (
+    e: Proj,
+    cx: number,
+    cy: number,
+    clusterId?: string
+  ): void => {
+    const { fill, stroke } = poiFill(e.p);
+    poiScreen.set(e.p.id, { cx, cy, r: radiusFor(e.p) });
+    const num = routeNumberById.get(e.p.id);
+    pois.push({
+      id: e.p.id,
+      cx,
+      cy,
+      r: radiusFor(e.p),
+      fill,
+      stroke,
+      lineNumber: e.p.lineNumber,
+      implicit: !!e.p.implicit,
+      isOrigin: originIds.has(e.p.id),
+      ...(num !== undefined && { routeNumber: num }),
+      ...(Object.keys(e.p.tags).length > 0 && { tags: e.p.tags }),
+      ...(clusterId !== undefined && { clusterId }),
+    });
+  };
+
+  // -- Coincident-POI spiderfy (stacks). Two dots "stack" when they visibly
+  // overlap (centre distance < combined radii × STACK_OVERLAP). A ≥2-member stack
+  // is laid out EXPANDED — members fanned onto a ring (golden-angle spiral past
+  // STACK_RING_MAX), legs back to the centroid — which is the source of truth for
+  // export + the no-JS default; the app collapses it to one ringed `+N` badge at
+  // rest and expands on click. POIs that anchor an edge or route leg are EXCLUDED
+  // (kept at true position; collapsing a connector endpoint is out of v1 scope).
+  // Distinct-but-dense clusters never overlap at the combined-radii threshold, so
+  // they keep today's true-position + leader/column behavior.
+  const clusters: MapLayoutCluster[] = [];
+  const connected = new Set<string>();
+  for (const e of resolved.edges) {
+    connected.add(e.fromId);
+    connected.add(e.toId);
+  }
+  for (const rt of resolved.routes) {
+    rt.stopIds.forEach((id) => connected.add(id));
+  }
+  const radiusOf = (e: Proj): number => radiusFor(e.p);
+  // Connected endpoints: always true position.
   for (const e of projected) {
-    const key = `${Math.round(e.xy[0] / COLO_EPS)},${Math.round(e.xy[1] / COLO_EPS)}`;
-    const arr = coloGroups.get(key);
-    if (arr) arr.push(e);
-    else coloGroups.set(key, [e]);
+    if (connected.has(e.p.id)) placePoi(e, e.xy[0], e.xy[1]);
+  }
+  // Distance-based transitive grouping among stackable POIs (first-matching-group
+  // heuristic, matching the GROUP_R label-column grouping below).
+  const groups: Proj[][] = [];
+  for (const e of projected) {
+    if (connected.has(e.p.id)) continue;
+    const r = radiusOf(e);
+    const near = groups.find((g) =>
+      g.some(
+        (q) =>
+          Math.hypot(q.xy[0] - e.xy[0], q.xy[1] - e.xy[1]) <
+          (r + radiusOf(q)) * STACK_OVERLAP
+      )
+    );
+    if (near) near.push(e);
+    else groups.push([e]);
   }
-  for (const group of coloGroups.values()) {
-    group.forEach((e, i) => {
-      let cx = e.xy[0];
-      let cy = e.xy[1];
-      if (group.length > 1) {
-        const ang = i * GOLDEN_ANGLE;
-        cx += Math.cos(ang) * COLO_R;
-        cy += Math.sin(ang) * COLO_R;
+  for (const g of groups) {
+    if (g.length === 1) {
+      placePoi(g[0]!, g[0]!.xy[0], g[0]!.xy[1]);
+      continue;
+    }
+    const clusterId = g[0]!.p.id; // line-number-ordered first member → stable
+    const cx0 = g.reduce((s, e) => s + e.xy[0], 0) / g.length;
+    const cy0 = g.reduce((s, e) => s + e.xy[1], 0) / g.length;
+    const maxR = Math.max(...g.map(radiusOf));
+    // Ring radius so adjacent expanded dots clear each other by STACK_RING_GAP.
+    const sep = 2 * maxR + STACK_RING_GAP;
+    const ringR = Math.max(
+      COLO_R,
+      sep / (2 * Math.sin(Math.PI / Math.max(g.length, 2)))
+    );
+    const positions = g.map((e, i) => {
+      if (g.length <= STACK_RING_MAX) {
+        const ang = -Math.PI / 2 + (i * 2 * Math.PI) / g.length;
+        return {
+          e,
+          mx: cx0 + Math.cos(ang) * ringR,
+          my: cy0 + Math.sin(ang) * ringR,
+        };
       }
-      const { fill, stroke } = poiFill(e.p);
-      poiScreen.set(e.p.id, { cx, cy, r: radiusFor(e.p) });
-      const num = routeNumberById.get(e.p.id);
-      pois.push({
-        id: e.p.id,
-        cx,
-        cy,
-        r: radiusFor(e.p),
-        fill,
-        stroke,
-        lineNumber: e.p.lineNumber,
-        implicit: !!e.p.implicit,
-        isOrigin: originIds.has(e.p.id),
-        ...(num !== undefined && { routeNumber: num }),
-        ...(Object.keys(e.p.tags).length > 0 && { tags: e.p.tags }),
-      });
+      const ang = i * GOLDEN_ANGLE;
+      const rr = ringR * Math.sqrt((i + 1) / g.length);
+      return { e, mx: cx0 + Math.cos(ang) * rr, my: cy0 + Math.sin(ang) * rr };
+    });
+    // Off-canvas guard: translate the whole fan (centroid + members together) so
+    // every DOT stays on-canvas. A pure shift preserves the spider geometry AND
+    // keeps the collapsed badge honest — the ring is small, so the badge barely
+    // moves off the true centroid. (Labels are NOT folded into this box: a label
+    // is wide enough that shifting to fit it would drag the badge far from the
+    // real location — a geographic lie. Instead the label block below flips each
+    // member's radial label to the side that fits and clamps it to the frame.)
+    let minX = cx0 - maxR;
+    let maxX = cx0 + maxR;
+    let minY = cy0 - maxR;
+    let maxY = cy0 + maxR;
+    for (const { mx, my, e } of positions) {
+      const r = radiusOf(e);
+      minX = Math.min(minX, mx - r);
+      maxX = Math.max(maxX, mx + r);
+      minY = Math.min(minY, my - r);
+      maxY = Math.max(maxY, my + r);
+    }
+    let dx = 0;
+    let dy = 0;
+    if (minX + dx < 2) dx = 2 - minX;
+    if (maxX + dx > width - 2) dx = width - 2 - maxX;
+    if (minY + dy < 2) dy = 2 - minY;
+    if (maxY + dy > height - 2) dy = height - 2 - maxY;
+    const legsOut: Array<{ x2: number; y2: number; color: string }> = [];
+    for (const { e, mx, my } of positions) {
+      const fx = mx + dx;
+      const fy = my + dy;
+      placePoi(e, fx, fy, clusterId);
+      legsOut.push({ x2: fx, y2: fy, color: poiFill(e.p).fill });
+    }
+    clusters.push({
+      id: clusterId,
+      cx: cx0 + dx,
+      cy: cy0 + dy,
+      count: g.length,
+      hitR: ringR + maxR + 6,
+      legs: legsOut,
     });
   }
 
@@ -1283,16 +2104,29 @@ export function layoutMap(
       if (!a || !b) continue;
       const mx = (a.cx + b.cx) / 2;
       const my = (a.cy + b.cy) / 2;
+      const bow = {
+        curved: leg.style === 'arc',
+        offset: 0,
+        labelX: mx,
+        labelY: my - 4,
+      };
+      const routeLabelStyle =
+        leg.label !== undefined
+          ? labelOnFill(fillAt(bow.labelX, bow.labelY))
+          : undefined;
       legs.push({
-        d: legPath(a, b, leg.style === 'arc', 0),
+        d: legPath(a, b, bow.curved, bow.offset),
         width: routeWidthFor(Number(leg.value)),
         color: mix(palette.text, palette.bg, 72),
         arrow: true,
         lineNumber: leg.lineNumber,
         ...(leg.label !== undefined && {
           label: leg.label,
-          labelX: mx,
-          labelY: my - 4,
+          labelX: bow.labelX,
+          labelY: bow.labelY,
+          labelColor: routeLabelStyle!.color,
+          labelHalo: routeLabelStyle!.halo,
+          labelHaloColor: routeLabelStyle!.haloColor,
         }),
       });
     }
@@ -1324,20 +2158,32 @@ export function layoutMap(
       const a = poiScreen.get(e.fromId);
       const b = poiScreen.get(e.toId);
       if (!a || !b) return;
-      const curved = e.style === 'arc' || n > 1;
-      const offset = n > 1 ? (i - (n - 1) / 2) * FAN_STEP : 0;
+      const fanOffset = n > 1 ? (i - (n - 1) / 2) * FAN_STEP : 0;
       const mx = (a.cx + b.cx) / 2;
       const my = (a.cy + b.cy) / 2;
+      const bow = {
+        curved: e.style === 'arc' || n > 1,
+        offset: fanOffset,
+        labelX: mx,
+        labelY: my - 4,
+      };
+      const edgeLabelStyle =
+        e.label !== undefined
+          ? labelOnFill(fillAt(bow.labelX, bow.labelY))
+          : undefined;
       legs.push({
-        d: legPath(a, b, curved, offset),
+        d: legPath(a, b, bow.curved, bow.offset),
         width: widthFor(e),
         color: mix(palette.text, palette.bg, 66),
         arrow: e.directed,
         lineNumber: e.lineNumber,
         ...(e.label !== undefined && {
           label: e.label,
-          labelX: mx,
-          labelY: my - 4,
+          labelX: bow.labelX,
+          labelY: bow.labelY,
+          labelColor: edgeLabelStyle!.color,
+          labelHalo: edgeLabelStyle!.halo,
+          labelHaloColor: edgeLabelStyle!.haloColor,
         }),
       });
     });
@@ -1389,14 +2235,17 @@ export function layoutMap(
     obstacles.some((o) => rectsOverlap(rect, o)) ||
     legSegments.some((s) => segmentRectOverlap(s[0], s[1], s[2], s[3], rect));
 
-  // Region labels (default off). Rendered as haloed text — NO pill — so the
-  // choropleth fill (which encodes the data) stays fully visible. The text
-  // colour is contrast-picked against each region's OWN fill (dark on
-  // pastel/unscored land, light on saturated fills) with an opposite-lightness
-  // paint-order halo, the same convention POI labels use. A label is shown only
-  // when its (padded) footprint fits inside the region, so small states like the
-  // NE cluster auto-hide rather than overlap / spill onto the ocean.
-  const regionLabelMode = resolved.directives.regionLabels ?? 'off';
+  // Region labels (default ON; `no-region-labels` suppresses). Rendered as plain
+  // text — NO pill, NO halo — so the choropleth fill (which encodes the data)
+  // stays fully visible. The text colour is contrast-picked against each region's
+  // OWN fill. Auto-fit cascade full → abbrev → hide (decision A): the full name
+  // shows when it fits its footprint; otherwise a US-state 2-letter abbreviation
+  // is tried (countries have no abbrev source, so they degrade full → hide); if
+  // nothing fits the label is hidden rather than overlapping / spilling onto the
+  // ocean. At the compact breakpoint (decision D2) the abbreviation is preferred
+  // FIRST for US states.
+  const showRegionLabels = resolved.directives.noRegionLabels !== true;
+  const isCompact = width < COMPACT_WIDTH_PX;
   const LABEL_PADX = 6;
   const LABEL_PADY = 3;
   const labelW = (text: string): number =>
@@ -1409,22 +2258,28 @@ export function layoutMap(
     fill: string,
     lineNumber: number
   ): void => {
-    const color = contrastText(
-      fill,
-      palette.textOnFillLight,
-      palette.textOnFillDark
+    // Colour is contrast-picked against the region's own fill (see labelOnFill).
+    // The halo, though, is gated by CONTAINMENT — not fill tone. A label that
+    // sits wholly within its own fill reads against a single known colour, so
+    // the picked shade suffices and a halo is just noise (big states: TX, CA).
+    // But when the glyphs spill past the region — a narrow shape (FL peninsula),
+    // a tiny state (MD), or a small inset island (HI) — the text crosses onto
+    // ocean / neighbour land whose tone we can't predict, so it needs the halo
+    // to stay legible. Sample the label's screen footprint against the drawn
+    // fills: if any extreme lands on a fill other than the region's own, the
+    // label overflows and earns a halo.
+    const { color, haloColor } = labelOnFill(fill);
+    const halfW = measureLegendText(text, FONT) / 2;
+    const overflows = [y - FONT * 0.55, y - FONT * 0.1].some(
+      (sy) => fillAt(x - halfW, sy) !== fill || fillAt(x + halfW, sy) !== fill
     );
-    const haloColor =
-      color === palette.textOnFillLight
-        ? palette.textOnFillDark
-        : palette.textOnFillLight;
     labels.push({
       x,
       y,
       text,
       anchor: 'middle',
       color,
-      halo: true,
+      halo: overflows,
       haloColor,
       lineNumber,
     });
@@ -1435,29 +2290,92 @@ export function layoutMap(
   const WORLD_LABEL_ANCHORS: Record<string, [number, number]> = {
     US: [-98.5, 39.5], // CONUS geographic centre (near Lebanon, Kansas)
   };
-  if (regionLabelMode === 'full' || regionLabelMode === 'abbrev') {
-    for (const r of regions) {
-      if (r.layer === 'base' || r.label === undefined) continue;
-      const f =
-        r.layer === 'us-state' ? usLayer?.get(r.id) : worldLayer.get(r.id);
-      if (!f) continue;
-      const [[x0, y0], [x1, y1]] = path.bounds(f as never);
-      const text =
-        regionLabelMode === 'abbrev' ? r.id.replace(/^US-/, '') : r.label;
-      // Hide if the label wouldn't fit inside the region's footprint.
-      if (labelW(text) > x1 - x0 || labelH > y1 - y0) continue;
-      const anchor =
-        r.layer !== 'us-state' ? WORLD_LABEL_ANCHORS[r.id] : undefined;
-      const c = anchor
-        ? project(anchor[0], anchor[1])
-        : path.centroid(f as never);
-      if (!c || !Number.isFinite(c[0])) continue;
+  // A region label's screen footprint, middle-anchored on its centroid, used to
+  // keep two region labels from overlapping (a small gap adds breathing room).
+  const REGION_LABEL_GAP = 2;
+  const regionLabelRect = (cx: number, cy: number, text: string): LabelRect => {
+    const w = measureLegendText(text, FONT) + 2 * REGION_LABEL_GAP;
+    return { x: cx - w / 2, y: cy - FONT / 2, w, h: FONT };
+  };
+  if (showRegionLabels) {
+    // Gather the placeable region labels, then commit them largest-footprint
+    // first. Two adjacent regions can sit too close to both carry a label at the
+    // current scale (Spain + Portugal on a whole-world view collapse to ~32px
+    // apart). Rather than overlap, the bigger region keeps its label and the
+    // smaller one yields; zoom in and the footprints separate, no collision
+    // fires, and both labels show. Order is by projected box AREA (visual claim)
+    // so the result is scale-driven, not source-order-driven.
+    // POI-only region framing: the region(s) CONTAINING the POIs are labelled
+    // prominently even though they carry no data (layer 'base'). Neighbour land
+    // gets the muted context-label treatment further down.
+    const frameContainers = new Set(resolved.poiFrameContainers);
+    const entries = regions
+      .map((r) => {
+        const isContainer = frameContainers.has(r.id);
+        if ((r.layer === 'base' && !isContainer) || r.label === undefined)
+          return null;
+        // A container state carries layer 'base', so key off the id shape too.
+        const isUsState = r.layer === 'us-state' || r.id.startsWith('US-');
+        const f = isUsState ? usLayer?.get(r.id) : worldLayer.get(r.id);
+        if (!f) return null;
+        const [[x0, y0], [x1, y1]] = path.bounds(f as never);
+        const boxW = x1 - x0;
+        const boxH = y1 - y0;
+        // full → abbrev → hide. Abbrev exists only for US states; at the compact
+        // breakpoint abbrev is tried first.
+        const abbrev = isUsState ? r.id.replace(/^US-/, '') : undefined;
+        const candidates =
+          abbrev !== undefined
+            ? isCompact
+              ? [abbrev, r.label]
+              : [r.label, abbrev]
+            : [r.label];
+        const anchor = !isUsState ? WORLD_LABEL_ANCHORS[r.id] : undefined;
+        const c = anchor
+          ? project(anchor[0], anchor[1])
+          : path.centroid(f as never);
+        if (!c || !Number.isFinite(c[0])) return null;
+        return { r, c, boxW, boxH, area: boxW * boxH, candidates };
+      })
+      .filter((e): e is NonNullable<typeof e> => e !== null)
+      .sort((a, b) => b.area - a.area || a.r.lineNumber - b.r.lineNumber);
+    const placedRegionRects: LabelRect[] = [];
+    // POI markers are obstacles for region labels: a region whose centroid sits on
+    // a POI (e.g. Colorado's centroid under the "Core POP" dot in Denver) must NOT
+    // stamp its name there — the POI's own label owns that spot, and two names by
+    // one dot is ambiguous. The dot rect is padded to also keep the region name
+    // clear of the POI's adjacent label. Region labels with no nearby POI (a
+    // container whose POIs cluster in one corner, or an empty neighbour state) are
+    // unaffected. POI markers are positioned above; their labels place further
+    // down, so dot-proximity is the signal available here.
+    const POI_LABEL_PAD = 14; // px — rough room for the POI's own hugging label
+    const poiObstacles: LabelRect[] = pois.map((p) => ({
+      x: p.cx - p.r - POI_LABEL_PAD,
+      y: p.cy - p.r - POI_LABEL_PAD,
+      w: 2 * (p.r + POI_LABEL_PAD),
+      h: 2 * (p.r + POI_LABEL_PAD),
+    }));
+    for (const { r, c, boxW, boxH, candidates } of entries) {
+      // The first candidate that BOTH fits its own footprint AND clears every
+      // already-placed region label AND every POI marker wins; none qualifies →
+      // the label is hidden (a country has no abbrev, so it degrades full → hide;
+      // a US state may fall back to its 2-letter code before hiding).
+      const text = candidates.find((t) => {
+        if (labelW(t) > boxW || labelH > boxH) return false;
+        const rect = regionLabelRect(c[0], c[1], t);
+        return (
+          !placedRegionRects.some((p) => rectsOverlap(rect, p)) &&
+          !poiObstacles.some((o) => rectsOverlap(rect, o))
+        );
+      });
+      if (text === undefined) continue;
+      placedRegionRects.push(regionLabelRect(c[0], c[1], text));
       pushRegionLabel(c[0], c[1], text, r.fill, r.lineNumber);
     }
-    // AK/HI labels live in their insets (own projection centroids).
+    // AK/HI labels live in their insets (own projection centroids). Insets are
+    // tiny, so prefer the abbreviation when the canvas is compact.
     for (const seed of insetLabelSeeds) {
-      const text =
-        regionLabelMode === 'abbrev' ? seed.iso.replace(/^US-/, '') : seed.name;
+      const text = isCompact ? seed.iso.replace(/^US-/, '') : seed.name;
       const src = regionById.get(seed.iso);
       pushRegionLabel(
         seed.x,
@@ -1469,12 +2387,13 @@ export function layoutMap(
     }
   }
 
-  // POI labels (default auto; off -> none; all -> every POI).
-  const poiLabelMode = resolved.directives.poiLabels ?? 'auto';
-  if (poiLabelMode !== 'off') {
-    const ordered = [...pois].sort(
-      (a, b) => a.lineNumber - b.lineNumber || (a.id < b.id ? -1 : 1)
-    );
+  // POI labels: default-on, collision-managed auto. `no-poi-labels` suppresses.
+  if (resolved.directives.noPoiLabels !== true) {
+    // Cluster (stack) members are laid out + labelled by the spiderfy block; keep
+    // them out of the singleton/proximity-column placement here.
+    const ordered = [...pois]
+      .filter((p) => p.clusterId === undefined)
+      .sort((a, b) => a.lineNumber - b.lineNumber || (a.id < b.id ? -1 : 1));
     const poiById = new Map(resolved.pois.map((q) => [q.id, q]));
     const labelText = (p: MapLayoutPoi): string => {
       const src = poiById.get(p.id);
@@ -1491,6 +2410,18 @@ export function layoutMap(
     // from the east AND west — Boulder in the route-cluster gauntlet).
     type Side = 'right' | 'left' | 'above' | 'below';
     const GAP = 3;
+    // Coincident-stack members (spiderfy) are labelled via a tidy leader-lined
+    // COLUMN beside the cluster (see the cluster-column pass after the column
+    // helpers below) — NOT radial inline labels, which pile up unreadably when
+    // the ring is tight. Group the members here; the pass commits them once the
+    // column machinery is defined.
+    const clusterMembersById = new Map<string, MapLayoutPoi[]>();
+    for (const p of pois) {
+      if (p.clusterId === undefined) continue;
+      const arr = clusterMembersById.get(p.clusterId);
+      if (arr) arr.push(p);
+      else clusterMembersById.set(p.clusterId, [p]);
+    }
     const inlineRect = (p: MapLayoutPoi, w: number, side: Side): LabelRect => {
       switch (side) {
         case 'right':
@@ -1530,7 +2461,7 @@ export function layoutMap(
         text,
         anchor,
         color: palette.text,
-        halo: true,
+        halo: false,
         haloColor: palette.bg,
         poiId: p.id,
         lineNumber: p.lineNumber,
@@ -1567,39 +2498,89 @@ export function layoutMap(
     const ROW_GAP = 3;
     const step = poiLabH + ROW_GAP;
     const COL_GAP = 16;
-    const placeColumn = (group: MapLayoutPoi[]): void => {
-      const items = group
+    type ColItem = { p: MapLayoutPoi; text: string; w: number };
+    const makeItems = (group: MapLayoutPoi[]): ColItem[] =>
+      group
         .map((p) => ({ p, ...labelInfo(p) }))
         .sort((a, b) => a.p.cy - b.p.cy || (a.text < b.text ? -1 : 1));
+    // The column's per-row layout (side, colX, clamped startY, each row's rect).
+    // Shared by the clean-check gate and the commit path so they never diverge.
+    const columnRows = (
+      items: ColItem[],
+      side: 'right' | 'left'
+    ): Array<{ o: ColItem; colX: number; rowCy: number; rect: LabelRect }> => {
       const left = Math.min(...items.map((o) => o.p.cx - o.p.r));
       const right = Math.max(...items.map((o) => o.p.cx + o.p.r));
+      const maxW = Math.max(...items.map((o) => o.w));
       const cyMid =
         (Math.min(...items.map((o) => o.p.cy)) +
           Math.max(...items.map((o) => o.p.cy))) /
         2;
-      const maxW = Math.max(...items.map((o) => o.w));
-      // Prefer the right of the cluster; fall to the left if it runs off-canvas.
-      const side: 'right' | 'left' =
-        right + COL_GAP + maxW <= width - 2 ? 'right' : 'left';
-      const colX = side === 'right' ? right + COL_GAP : left - COL_GAP;
+      // Column anchor x, clamped so the widest row's text box stays on-canvas.
+      // (No-op for the clean callers; matters when a fallback column — e.g. a
+      // second spider cluster boxed out of its preferred side — would otherwise
+      // run a label off the frame.) A right column anchors its text start at
+      // colX; a left column anchors its end at colX (text spans colX-maxW..colX).
+      const colX =
+        side === 'right'
+          ? Math.min(right + COL_GAP, width - 2 - maxW)
+          : Math.max(left - COL_GAP, 2 + maxW);
       const totalH = items.length * step;
       let startY = cyMid - totalH / 2;
       startY = Math.max(2, Math.min(startY, height - totalH - 2));
-      items.forEach((o, i) => {
+      return items.map((o, i) => {
         const rowCy = startY + i * step + step / 2;
-        obstacles.push({
-          x: side === 'right' ? colX : colX - o.w,
-          y: rowCy - poiLabH / 2,
-          w: o.w,
-          h: poiLabH,
-        });
+        return {
+          o,
+          colX,
+          rowCy,
+          rect: {
+            x: side === 'right' ? colX : colX - o.w,
+            y: rowCy - poiLabH / 2,
+            w: o.w,
+            h: poiLabH,
+          },
+        };
+      });
+    };
+    // Pure gate (NO mutation): every row on-canvas AND collision-free, at the
+    // post-startY-clamp positions the commit path will use.
+    const wouldColumnBeClean = (
+      items: ColItem[],
+      side: 'right' | 'left'
+    ): boolean =>
+      columnRows(items, side).every(
+        ({ rect }) =>
+          rect.x >= 0 &&
+          rect.x + rect.w <= width &&
+          rect.y >= 0 &&
+          rect.y + rect.h <= height &&
+          !collides(rect)
+      );
+    // Today's side heuristic — used only for ungated singleton callouts.
+    const defaultColumnSide = (items: ColItem[]): 'right' | 'left' => {
+      const right = Math.max(...items.map((o) => o.p.cx + o.p.r));
+      const maxW = Math.max(...items.map((o) => o.w));
+      return right + COL_GAP + maxW <= width - 2 ? 'right' : 'left';
+    };
+    // Commit a visible callout column on the GIVEN side (no re-deriving the
+    // side — the caller has already validated it). When `clusterId` is set the
+    // rows are tagged `clusterMember` so the app shows/hides them (text AND
+    // leader) with the collapsed-stack badge.
+    const commitColumn = (
+      items: ColItem[],
+      side: 'right' | 'left',
+      clusterId?: string
+    ): void => {
+      for (const { o, colX, rowCy, rect } of columnRows(items, side)) {
+        obstacles.push(rect);
         labels.push({
           x: colX,
           y: rowCy + FONT / 3,
           text: o.text,
           anchor: side === 'right' ? 'start' : 'end',
           color: palette.text,
-          halo: true,
+          halo: false,
           haloColor: palette.bg,
           leader: {
             x1: o.p.cx,
@@ -1610,26 +2591,207 @@ export function layoutMap(
           leaderColor: o.p.fill,
           poiId: o.p.id,
           lineNumber: o.p.lineNumber,
+          ...(clusterId !== undefined && { clusterMember: clusterId }),
         });
+      }
+    };
+    // Hover-only fallback: a single inline label beside the dot (no leader),
+    // emitted invisible and revealed on hover. NOT added to obstacles (it's
+    // invisible and must not displace visible labels). y is clamped on-canvas
+    // because we skip the inlineFits four-edge check (F8).
+    const pushHidden = (p: MapLayoutPoi): void => {
+      const { text, w } = labelInfo(p);
+      let x = p.cx + p.r + GAP;
+      let anchor: 'start' | 'end' = 'start';
+      if (x + w > width) {
+        x = p.cx - p.r - GAP - w;
+        anchor = 'end';
+      }
+      const y = Math.max(0, Math.min(p.cy - poiLabH / 2, height - poiLabH));
+      labels.push({
+        x: anchor === 'start' ? x : x + w,
+        y: y + poiLabH / 2 + FONT / 3,
+        text,
+        anchor,
+        color: palette.text,
+        halo: false,
+        haloColor: palette.bg,
+        poiId: p.id,
+        hidden: true,
+        lineNumber: p.lineNumber,
       });
     };
 
+    // Spiderfy clusters: label every member in a tidy leader-lined column beside
+    // the ring (collision-free by row spacing), tagged `clusterMember` so the app
+    // toggles them with the badge. Committed FIRST so the singleton/group passes
+    // route around the column. The dots/legs/badge keep their true location — only
+    // the labels move out to the column, which the startY-clamp keeps on-canvas.
+    for (const [clusterId, members] of clusterMembersById) {
+      if (members.length === 0) continue;
+      const items = makeItems(members);
+      // Prefer a clean (on-canvas, collision-free) side; fall back to the side
+      // with more horizontal room. Cluster labels are always placed (never
+      // hover-only) — readability beats the odd overlap with a faint basemap.
+      const side = wouldColumnBeClean(items, 'right')
+        ? 'right'
+        : wouldColumnBeClean(items, 'left')
+          ? 'left'
+          : defaultColumnSide(items);
+      commitColumn(items, side, clusterId);
+    }
+
+    // Per-render extent threshold (resolution-relative; Decision #1, F9).
+    const maxExtent = MAX_CLUSTER_EXTENT_FACTOR * Math.min(width, height);
+    // Pass 1: place singletons (unchanged); for ≥2 clusters resolve gate
+    // (a)/(a2) — sprawl/overflow → hover-only. These hides push NOTHING to
+    // obstacles, so doing them first decouples the gate-(b) clean-checks below
+    // from commit order (F4). Surviving clusters defer to pass 2.
+    const clusterPending: ColItem[][] = [];
     for (const g of groups) {
-      // Singleton that fits inline → inline; everything else → callout column
-      // (the whole cluster, or a lone POI boxed in by legs/edges).
+      const items = makeItems(g);
       if (g.length === 1) {
-        const p = g[0]!;
-        const { text, w } = labelInfo(p);
+        // Singleton: inline if it fits, else today's single-row callout —
+        // always placed, never hover-only (Decision #2 / AC9).
+        const { p, text, w } = items[0]!;
         const side = (['right', 'left', 'above', 'below'] as const).find((s) =>
           inlineFits(p, w, s)
         );
-        if (side) {
-          pushInline(p, text, w, side);
-          continue;
+        if (side) pushInline(p, text, w, side);
+        else commitColumn(items, defaultColumnSide(items));
+        continue;
+      }
+      // Gate (a): bounding-box diagonal over marker extents — a sprawling chain
+      // whose column leaders would fan across the map. Gate (a2): too many rows
+      // to stack readably. Either → whole cluster hover-only.
+      const left = Math.min(...items.map((o) => o.p.cx - o.p.r));
+      const right = Math.max(...items.map((o) => o.p.cx + o.p.r));
+      const minCy = Math.min(...items.map((o) => o.p.cy));
+      const maxCy = Math.max(...items.map((o) => o.p.cy));
+      const diag = Math.hypot(right - left, maxCy - minCy);
+      if (diag > maxExtent || items.length > MAX_COLUMN_ROWS) {
+        items.forEach((o) => pushHidden(o.p));
+      } else {
+        clusterPending.push(items);
+      }
+    }
+    // Pass 2: gate (b) — a surviving cluster shows its column only if a right-
+    // or left-side column places fully clean; commit on that exact side, else
+    // the whole cluster goes hover-only.
+    for (const items of clusterPending) {
+      const side = (['right', 'left'] as const).find((s) =>
+        wouldColumnBeClean(items, s)
+      );
+      if (side) commitColumn(items, side);
+      else items.forEach((o) => pushHidden(o.p));
+    }
+  }
+
+  // -- Context labels (orientation backdrop, §24B). Placed DEAD LAST so they
+  // only fill leftover space and never displace a data/region/POI label
+  // (Decision 7). Off by default; gated on the directive so it costs nothing. --
+  if (resolved.directives.noContextLabels !== true) {
+    // F1: context labels must dodge EVERY committed label (region/inset/POI/
+    // route), not just the POI-label rects already in `obstacles`. Region
+    // labels go into `labels` but never into `obstacles`, so add a footprint
+    // rect for each committed label here (POI rects are already present —
+    // duplicates are harmless). This upholds Decision 7's "never displace a
+    // data/region/POI label" against the live `collides` closure.
+    for (const l of labels) {
+      // Hidden (hover-only) labels are invisible — context labels must not
+      // reserve space around them (Decision #7).
+      if (l.hidden) continue;
+      const w = labelW(l.text);
+      const x =
+        l.anchor === 'start' ? l.x : l.anchor === 'end' ? l.x - w : l.x - w / 2;
+      obstacles.push({ x, y: l.y - labelH / 2, w, h: labelH });
+    }
+    // Under albers-usa the AK/HI inset frames occupy the lower-left; a context
+    // label must never sit on one (the original Decision 8 hazard). Feed each
+    // inset box into the collision set so the placement dodges them.
+    for (const box of insets)
+      obstacles.push({ x: box.x, y: box.y, w: box.w, h: box.h });
+    // Unreferenced notable countries: the FULL decoded country set (worldLayer
+    // holds every country in the chosen tier — crisp `.set()` upgrades never
+    // delete), minus any already labelled by region-labels (Decision 1). Geo
+    // work (bbox/anchor) stays here; area-rank + fit + collision live in the
+    // pure module so the strict density invariants (AC7) are unit-testable.
+    const countryCandidates: CountryCandidate[] = [];
+    for (const f of worldLayer.values()) {
+      const iso = typeof f.id === 'string' ? f.id : String(f.id ?? '');
+      if (!iso || regionById.has(iso)) continue;
+      // F3: skip a country whose SUBDIVISIONS are the referenced data (e.g. a
+      // US-states choropleth on a world projection) — the states ARE the data,
+      // so don't slap a redundant "United States" context label over them.
+      let hasReferencedSub = false;
+      for (const k of regionById.keys())
+        if (k.startsWith(iso + '-')) {
+          hasReferencedSub = true;
+          break;
         }
+      if (hasReferencedSub) continue;
+      const b = path.bounds(f as never) as [[number, number], [number, number]];
+      const [x0, y0] = b[0];
+      const [x1, y1] = b[1];
+      if (!Number.isFinite(x0) || !Number.isFinite(x1)) continue;
+      const anchorLngLat = WORLD_LABEL_ANCHORS[iso];
+      const a = anchorLngLat
+        ? project(anchorLngLat[0], anchorLngLat[1])
+        : (path.centroid(f as never) as [number, number]);
+      countryCandidates.push({
+        name: (f.properties as { name?: string } | undefined)?.name ?? iso,
+        bbox: [x0, y0, x1, y1],
+        anchor: a && Number.isFinite(a[0]) ? [a[0], a[1]] : null,
+      });
+    }
+    // Neighbour US states (POI-only region framing): when the frame is snapped to
+    // a US-state container (e.g. California), label the surrounding in-frame states
+    // (Nevada, Oregon, Arizona…) in the muted context style for orientation. They
+    // are NOT containers and NOT data, so the region-label pass skipped them.
+    // Anchor each to the centroid of its VISIBLE (culled) geometry so a state only
+    // partly in frame (a sliver of Oregon at the top) still anchors on-screen
+    // rather than at an off-frame centroid that `insideViewport` would reject.
+    const framedStateContainers = (resolved.poiFrameContainers ?? []).some(
+      (id) => id.startsWith('US-')
+    );
+    if (usLayer && framedStateContainers) {
+      const containerSet = new Set(resolved.poiFrameContainers);
+      for (const [iso, f] of usLayer) {
+        if (containerSet.has(iso) || regionById.has(iso)) continue;
+        const viewF = cullFeatureToView(f);
+        if (!viewF) continue; // not in frame
+        const b = path.bounds(viewF as never) as [
+          [number, number],
+          [number, number],
+        ];
+        const [x0, y0] = b[0];
+        const [x1, y1] = b[1];
+        if (!Number.isFinite(x0) || !Number.isFinite(x1)) continue;
+        const a = path.centroid(viewF as never) as [number, number];
+        countryCandidates.push({
+          name: (f.properties as { name?: string } | undefined)?.name ?? iso,
+          bbox: [x0, y0, x1, y1],
+          anchor: a && Number.isFinite(a[0]) ? [a[0], a[1]] : null,
+        });
       }
-      placeColumn(g);
     }
+    const contextLabels = placeContextLabels({
+      projection: resolved.projection,
+      dLonSpan,
+      dLatSpan,
+      width,
+      height,
+      waterBodies: data.waterBodies,
+      countries: countryCandidates,
+      palette,
+      project,
+      collides,
+      // Water labels must stay over open water — `fillAt` returns the ocean
+      // backdrop colour off-land and a region fill on-land (lakes/states count
+      // as land here, which is the safe side for an ocean name).
+      overLand: (x, y) => fillAt(x, y) !== water,
+    });
+    labels.push(...contextLabels);
   }
 
   // -- Legend model (AR1: categorical via renderer's renderLegendD3) --
@@ -1671,11 +2833,18 @@ export function layoutMap(
     ...(resolved.caption !== undefined && { caption: resolved.caption }),
     regions,
     rivers,
+    relief,
+    reliefHatch,
+    coastlineStyle,
     legs,
     pois,
+    clusters,
     labels,
     legend,
     insets,
     insetRegions,
+    projection,
+    stretch: stretchParams,
+    diagnostics: [],
   };
 }