@diagrammo/dgmo 0.25.5 → 0.27.0

package/src/map/layout.ts

@@ -23,8 +23,9 @@ import {
   contrastRatio,
   relativeLuminance,
   politicalTints,
+  valueRampColor,
 } from '../palettes/color-utils';
-import { buildAdjacency } from './geo';
+import { buildAdjacency, featureBboxPrimary } from './geo';
 import { assignColors } from './colorize';
 import { resolveColor } from '../colors';
 import type { PaletteColors } from '../palettes/types';
@@ -35,6 +36,7 @@ import {
 } from '../label-layout';
 import type { LabelRect, PointCircle } from '../label-layout';
 import { measureLegendText } from '../utils/legend-constants';
+import { compactNumber } from '../utils/number-format';
 import { TITLE_FONT_SIZE, TITLE_Y } from '../utils/title-constants';
 import type { LegendMode } from '../utils/legend-types';
 import { mapLegendBand } from './legend-band';
@@ -47,6 +49,7 @@ import type {
   ResolvedPoi,
   ResolvedEdge,
   ProjectionFamily,
+  GeoExtent,
 } from './resolved-types';
 import { placeContextLabels } from './context-labels';
 import type { CountryCandidate } from './context-labels';
@@ -65,10 +68,85 @@ interface GeoFC {
 
 // -- Tunable constants (deterministic; no magic at call sites) --
 const FIT_PAD = 24; // px padding inside the viewport
+// Fractional digits for projected path `d` coordinates. d3-geo defaults to 3
+// (sub-micropixel at our canvas scale) — full-world detail geometry then emits
+// multi-MB SVGs that bloat the page and overflow downstream HTML reparsers.
+// One decimal is 0.1px: visually identical, ~half the coordinate bytes.
+const PATH_DIGITS = 1;
+
+// Screen-space vertex tolerance for thinning (px). Projected points within this
+// distance of the previously kept point are dropped. Sub-pixel, so invisible.
+const THIN_TOL = 0.6;
+
+interface ThinStream {
+  stream: {
+    point(x: number, y: number): void;
+    lineStart(): void;
+    lineEnd(): void;
+  };
+  _has?: boolean;
+  _pending?: boolean;
+  _ex?: number;
+  _ey?: number;
+  _lx?: number;
+  _ly?: number;
+}
+
+/**
+ * A geoTransform that thins projected vertices in screen space: it forwards a
+ * point only when it lies more than THIN_TOL px from the last forwarded point.
+ * Inserted just before the path serializer so it sees final screen coordinates,
+ * it is scale-aware by construction — at world scale the dense 50m coastline
+ * collapses to a few px-spaced vertices (the multi-MB bloat that overflows the
+ * SSG HTML reparse), while a regional zoom spreads the same coastline over many
+ * px so almost nothing is dropped (full detail preserved). The last vertex of
+ * every ring is always emitted so polygon fills stay gap-free.
+ */
+function geoThin(): ReturnType<typeof geoTransform> {
+  const tol2 = THIN_TOL * THIN_TOL;
+  return geoTransform({
+    lineStart(this: unknown) {
+      const t = this as ThinStream;
+      t._has = false;
+      t._pending = false;
+      t.stream.lineStart();
+    },
+    point(this: unknown, x: number, y: number) {
+      const t = this as ThinStream;
+      t._lx = x;
+      t._ly = y;
+      if (t._has) {
+        const dx = x - (t._ex as number);
+        const dy = y - (t._ey as number);
+        if (dx * dx + dy * dy < tol2) {
+          t._pending = true;
+          return;
+        }
+      }
+      t.stream.point(x, y);
+      t._ex = x;
+      t._ey = y;
+      t._has = true;
+      t._pending = false;
+    },
+    lineEnd(this: unknown) {
+      const t = this as ThinStream;
+      if (t._pending) t.stream.point(t._lx as number, t._ly as number);
+      t._pending = false;
+      t.stream.lineEnd();
+    },
+  });
+}
 const RAMP_FLOOR = 15; // % tint floor so min still reads as "low, present" (24B.3)
 const R_DEFAULT = 6; // POI radius without size:
 const R_MIN = 4;
 const R_MAX = 22;
+// Larger POIs fade their FILL so big bubbles read as light/airy instead of heavy
+// solid slabs (overlaps stay legible); the stroke stays fully opaque so every
+// marker keeps a crisp edge regardless of size. Gentle so the largest (= most
+// important) marker still reads. Linear in radius over [R_MIN, R_MAX].
+const POI_FILL_OPACITY_MAX = 0.92; // at R_MIN (smallest)
+const POI_FILL_OPACITY_MIN = 0.55; // at R_MAX (largest)
 const W_MIN = 1.25; // edge stroke width
 const W_MAX = 8;
 const FONT = 11; // on-map label font px
@@ -263,6 +341,9 @@ export interface MapLayoutPoi {
   readonly cy: number;
   readonly r: number;
   readonly fill: string;
+  /** Fill opacity scaled by radius — larger bubbles fade so they read as light
+   *  rather than heavy. Stroke stays fully opaque (crisp edge at every size). */
+  readonly fillOpacity: number;
   readonly stroke: string;
   readonly lineNumber: number;
   readonly implicit: boolean;
@@ -311,6 +392,15 @@ export interface MapLayoutLeg {
   readonly width: number;
   readonly color: string;
   readonly arrow: boolean;
+  /** Endpoint POI ids (resolved `fromId`/`toId`), emitted as `data-from-id` /
+   *  `data-to-id`. Lets an interactive preview co-highlight a leg's two endpoint
+   *  POIs when the leg is focused (§17 sync). */
+  readonly fromId: string;
+  readonly toId: string;
+  /** Tag values (keyed by lowercased group name) — emitted as `data-tag-*`, like
+   *  POI markers, so a legend-entry hover spotlights only the matching lines
+   *  (§24B.6). Omitted when the leg carries no tag. */
+  readonly tags?: Readonly<Record<string, string>>;
   readonly label?: string;
   readonly labelX?: number;
   readonly labelY?: number;
@@ -345,6 +435,11 @@ 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;
+  /** Per-label font size in px. Set on context COUNTRY labels, which scale up with
+   *  their projected footprint (a big country reads as a faded backdrop name, a
+   *  small one stays at the base label font). Absent ⇒ the renderer's default
+   *  LABEL_FONT, so every other label type renders byte-identically. */
+  readonly fontSize?: number;
   /** Cartographic italic (context-label water names, §24B). Default upright. */
   readonly italic?: boolean;
   /** Cartographic letter-spacing in px (context-label water names). Default 0. */
@@ -363,6 +458,16 @@ export interface PlacedLabel {
    *  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;
+  /** A choropleth region's metric VALUE (already compact-formatted, e.g. `39.5M`),
+   *  drawn as a smaller, dimmer second line UNDER `text` (the region name). Set
+   *  only on region labels of a `region-metric` map when `no-region-value` is off.
+   *  The renderer stacks it as a sub-line; absent ⇒ single name line. */
+  readonly valueLine?: string;
+  /** A region too small to carry its name+value stack in place gets a leader-lined
+   *  callout in a margin column; this marks the region's true centroid so the
+   *  renderer draws a small anchor dot there (the leader runs dot → chip). The
+   *  colour is the region's fill, tying the dot/leader/chip together. */
+  readonly calloutDot?: { x: number; y: number; color: string };
   readonly lineNumber: number;
 }
 
@@ -372,6 +477,15 @@ export interface PlacedLabel {
 // value-imports mapLegendBand from ./legend-band).
 export type { MapLayoutLegend };
 
+/** A subtle gazetteer city dot for basemap orientation (§24B `no-cities`). Just
+ *  a position + radius; the renderer paints it muted/low-opacity. No label, no
+ *  interactivity — purely decorative context. */
+export interface MapLayoutCityDot {
+  readonly cx: number;
+  readonly cy: number;
+  readonly r: number;
+}
+
 /** A drawn river centerline — an open stroked path (no fill). */
 export interface MapLayoutRiver {
   readonly d: string;
@@ -439,6 +553,9 @@ export interface MapLayout {
   readonly coastlineStyle: MapLayoutCoastlineStyle | null;
   readonly legs: readonly MapLayoutLeg[];
   readonly pois: readonly MapLayoutPoi[];
+  /** Subtle gazetteer city dots for orientation (empty when `no-cities` or no
+   *  cities fall on-canvas). Drawn over the basemap, under connectors/POIs. */
+  readonly cityDots: readonly MapLayoutCityDot[];
   /** 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[];
@@ -479,6 +596,28 @@ export interface LayoutOptions {
    *  `'preview'` keeps inactive pills. Used to size the reserved legend band so
    *  the projected land starts below the legend. Defaults to `'preview'`. */
   readonly legendMode?: LegendMode;
+  /** INTERNAL (set by layoutMap's own second pass — do not pass in). When tiny
+   *  valued regions need margin callouts, the first pass measures them and
+   *  re-runs with reserved bands: the projection fits into the canvas MINUS these
+   *  bands so the data shrinks/shifts inward, opening label room. A cluster on
+   *  EACH side reserves its own band (px), so tiny regions on both coasts each get
+   *  a column. An absent side reserves nothing there. Also carries the POI
+   *  edge-clearance bands (any of the four sides) measured by the POI-label pass
+   *  (same fit-box mechanism). Region callouts only ever set left/right. */
+  readonly _calloutReserve?: {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+  };
+  /** INTERNAL (set by layoutMap's own POI-clearance pass — do not pass in). After
+   *  POI-label placement, any POI dot/label crossing the edge-clearance band
+   *  triggers a re-fit that ADDS the residual intrusion to the reserved band on
+   *  that side, sliding the data inward. Re-measured each pass and accumulated
+   *  until nothing intrudes (or the pass cap), so a tight cluster on a small canvas
+   *  converges instead of giving up after one under-shoot. This counts the passes
+   *  taken to bound the recursion. */
+  readonly _poiClearancePass?: number;
 }
 
 interface Size {
@@ -559,10 +698,23 @@ const alaskaProjection = (): GeoProjection =>
   geoConicEqualArea().rotate([154, 0]).center([-2, 58.5]).parallels([55, 65]);
 const hawaiiProjection = (): GeoProjection => geoMercator();
 
-function projectionFor(family: ProjectionFamily): GeoProjection {
+function projectionFor(
+  family: ProjectionFamily,
+  extent: GeoExtent
+): GeoProjection {
   switch (family) {
     case 'albers-usa':
       return usConusProjection();
+    case 'conic-equal-area': {
+      // Albers for a single continent: standard parallels at 1/6 and 5/6 of the
+      // extent's latitude band (distortion-minimizing), centered on the band's
+      // mid-latitude. Longitude centering is handled by the shared .rotate below.
+      const s = extent[0][1];
+      const n = extent[1][1];
+      return geoConicEqualArea()
+        .parallels([s + (n - s) / 6, s + ((n - s) * 5) / 6])
+        .center([0, (s + n) / 2]);
+    }
     case 'mercator':
       return geoMercator();
     case 'equal-earth':
@@ -700,8 +852,9 @@ export function buildMapProjection(
   // 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
+  // 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 — OR a compact
+  // region/choropleth that auto-zooms; map-us-subnational-zoom, both mercator). 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
@@ -795,7 +948,7 @@ export function buildMapProjection(
   }
   const fitTarget: GeoFC = { type: 'FeatureCollection', features: fitFeatures };
 
-  const projection = projectionFor(resolved.projection);
+  const projection = projectionFor(resolved.projection, resolved.extent);
   // 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).
@@ -936,11 +1089,14 @@ export function layoutMap(
   const usContext = usLayer !== null;
   // Basemap fills (`water` / `neutralFill` / `foreignFill`) depend on whether a
   // colouring dimension is active — defined below, once `activeGroup` is known.
-  // Region borders: a clearly dark outline in BOTH themes. palette.text flips
-  // (dark on light, light on dark), so mix toward whichever of text/bg is the
-  // dark one — never a light hairline over the land fills.
+  // Region borders. Light theme: a near-text dark outline (a dark hairline
+  // reads well over the pale ground). Dark theme: a near-bg dark outline
+  // vanishes against the deep ground, so instead lean on the palette's
+  // dedicated `border` grid-line token (tuned to pop against that ground) and
+  // nudge it toward `text` for a touch more lift — a visible boundary that
+  // still reads as a line, not a glaring white seam over the land fills.
   const regionStroke = isDark
-    ? mix(palette.bg, palette.text, 78) // dark theme: near-bg dark outline
+    ? mix(palette.border, palette.text, 65) // dark theme: lifted grid-line
     : 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
@@ -955,13 +1111,14 @@ export function layoutMap(
   const values = resolved.regions
     .filter((r) => r.value !== undefined)
     .map((r) => r.value!);
-  // 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);
+  // Ramp auto-fits (the `scale` directive is gone) to data-min→data-max — the
+  // low end anchors at the lowest value, not 0. This maximises within-map
+  // dynamic range and matches the size/thickness metric ramps (poi-metric,
+  // flow-metric), which already floor at their data minimum. Cross-map low-end
+  // comparability (the old 0-anchor, "decision C") is intentionally dropped: a
+  // shared baseline only helped side-by-side maps and flattened single-map
+  // contrast. Equal-value data (rampMin === rampMax) falls back to t = 1 below.
+  const rampMin = values.length > 0 ? Math.min(...values) : 0;
   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
@@ -969,6 +1126,13 @@ export function layoutMap(
   const rampHue =
     resolveColor(resolved.directives.regionMetricColor ?? '', palette) ??
     palette.colors.red;
+  // Explicit LOW endpoint (`region-metric Sales green red`). Only the 11
+  // recognized names peel, so resolveColor always succeeds when a name is
+  // present; absent ⇒ single-colour behaviour (neutral low). §24B.3.
+  const rampLow = resolved.directives.regionMetricLowColor
+    ? (resolveColor(resolved.directives.regionMetricLowColor, palette) ??
+      undefined)
+    : undefined;
   const hasRamp = values.length > 0;
 
   // Colouring dimension (AR4, bivariate): the value ramp and each tag group are
@@ -987,6 +1151,21 @@ export function layoutMap(
     const tg = resolved.tagGroups.find((g) => g.name.toLowerCase() === lv);
     return tg ? tg.name : v; // unknown name passes through → renders neutral
   };
+  // A tag group is a "fill group" only if its alias actually lands on a region
+  // or a POI. A group used solely on connector lines (§24B.6) colours edges,
+  // never the basemap — so it must not drive the region/active-tag dress or
+  // suppress colorize.
+  const fillGroupNames = new Set<string>();
+  for (const g of resolved.tagGroups) {
+    const k = g.name.toLowerCase();
+    if (
+      resolved.regions.some((r) => r.tags[k]) ||
+      resolved.pois.some((p) => p.tags[k])
+    )
+      fillGroupNames.add(g.name);
+  }
+  const firstFillGroup =
+    resolved.tagGroups.find((g) => fillGroupNames.has(g.name))?.name ?? null;
   const override = opts.activeGroup; // string | null | undefined
   let activeGroup: string | null;
   if (override !== undefined) {
@@ -995,21 +1174,25 @@ export function layoutMap(
     activeGroup = matchColorGroup(resolved.directives.activeTag);
   } else {
     // Default: colour by the value ramp when values exist, else the first
-    // declared tag group.
+    // declared tag group that fills a region/POI. When the only groups are
+    // edge/leg groups (no fill group), fall back to the first declared group so
+    // the legend still renders it as a line-colour KEY — but it won't mute the
+    // basemap (see mutedBasemap below) since it fills no region.
     activeGroup =
-      VALUE_NAME ??
-      (resolved.tagGroups.length > 0 ? resolved.tagGroups[0]!.name : null);
+      VALUE_NAME ?? firstFillGroup ?? resolved.tagGroups[0]?.name ?? null;
   }
   const activeIsScore = VALUE_NAME !== null && activeGroup === VALUE_NAME;
 
   // 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;
+  // consistent. `mutedBasemap` governs only the NEIGHBOUR land: when a REGION-
+  // filling dimension is active the surrounding world recedes to a paler gray so
+  // the subject + its data fills dominate; a plain reference map — or one whose
+  // only tag group colours connector LINES (§24B.6), not regions — keeps
+  // neighbour land at the fuller gray.
+  const mutedBasemap =
+    activeIsScore || (activeGroup !== null && fillGroupNames.has(activeGroup));
   const neutralFill = mapNeutralLandColor(palette, isDark, mutedBasemap);
   const water = mapBackgroundColor(palette, isDark, mutedBasemap);
   const lakeStroke = mix(regionStroke, water, 45); // soft coastline (see above)
@@ -1043,7 +1226,7 @@ export function layoutMap(
     resolved.directives.noColorize !== true &&
     !hasRamp &&
     !hasDirectColor &&
-    resolved.tagGroups.length === 0;
+    fillGroupNames.size === 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
@@ -1100,8 +1283,16 @@ export function layoutMap(
   // off the near-black surface so the lowest scores read as a clear muted red
   // rather than sinking to maroon-black.
   const rampBase = isDark ? mix(palette.surface, palette.text, 28) : palette.bg;
+  // Floored neutral the single-colour ramp blends up from — also the LOW
+  // endpoint the legend shows when no explicit low colour was given.
+  const rampLowFloor = mix(rampHue, rampBase, RAMP_FLOOR);
   const fillForValue = (s: number): string => {
     const t = rampMax > rampMin ? (s - rampMin) / (rampMax - rampMin) : 1;
+    // Two-colour ramp: shared low→high interpolation (direct or via midpoint).
+    if (rampLow !== undefined)
+      return valueRampColor(rampLow, rampHue, t, { isDark });
+    // Single/zero-colour ramp: byte-identical to pre-change output — feed `mix`
+    // the SAME numeric pct (NO float round-trip, which could drift a channel).
     const pct = RAMP_FLOOR + Math.max(0, Math.min(1, t)) * (100 - RAMP_FLOOR);
     return mix(rampHue, rampBase, pct);
   };
@@ -1190,8 +1381,8 @@ export function layoutMap(
             }),
             min: rampMin,
             max: rampMax,
-            hue: rampHue,
-            base: rampBase,
+            low: rampLow ?? rampLowFloor,
+            high: rampHue,
           },
         }),
       };
@@ -1228,15 +1419,70 @@ export function layoutMap(
     hasSubtitle: Boolean(resolved.subtitle),
   });
   if (legendBand > topPad) topPad = legendBand;
+  // Reserve a side band for margin callouts (second pass only): the projection
+  // fits into the canvas MINUS this band, so the data shrinks and slides away
+  // from that edge, opening room for the callout chips + leaders.
+  const reserve = opts._calloutReserve;
+  const fitLeft = FIT_PAD + (reserve?.left ?? 0);
+  const fitRight = width - FIT_PAD - (reserve?.right ?? 0);
+  const fitTop = topPad + (reserve?.top ?? 0);
+  const fitBottom = height - FIT_PAD - (reserve?.bottom ?? 0);
   const fitBox: [[number, number], [number, number]] = [
-    [FIT_PAD, topPad],
-    [
-      Math.max(FIT_PAD + 1, width - FIT_PAD),
-      Math.max(topPad + 1, height - FIT_PAD),
-    ],
+    [fitLeft, fitTop],
+    [Math.max(fitLeft + 1, fitRight), Math.max(fitTop + 1, fitBottom)],
   ];
   projection.fitExtent(fitBox, fitTarget as never);
 
+  // Data-centered vertical fit (regional region-maps only). `fitExtent` centers
+  // the EXTENT rectangle in the box; when a choropleth's data clusters away from
+  // that rectangle's vertical center it lands off-center — e.g. a Europe map's
+  // colored countries are mostly central/southern, but Sweden drags the extent's
+  // north edge into empty Arctic, so the data sits low under a band of ocean.
+  // Shift the projection vertically so the data's vertical SPAN is centered in the
+  // fit box, CLAMPED so the data still fits inside the box (we never push a colored
+  // region off-frame). The span comes from each region's PRIMARY landmass bbox
+  // (featureBboxPrimary) — NOT the full feature, whose detached overseas
+  // territories (French Guiana, the Canaries, the Dutch Caribbean) would project
+  // far off-frame and wreck the bounds. POI-only regional frames are already
+  // cluster-centered (container + zoom floor) and the albers-usa composite frames
+  // the nation itself — both skip this.
+  if (
+    !fitIsGlobal &&
+    resolved.projection !== 'albers-usa' &&
+    resolved.regions.length > 0
+  ) {
+    let yMin = Infinity;
+    let yMax = -Infinity;
+    for (const r of resolved.regions) {
+      const bb = r.iso ? featureBboxPrimary(data.worldCoarse, r.iso) : null;
+      if (!bb) continue;
+      for (const lon of [bb[0][0], bb[1][0]]) {
+        for (const lat of [bb[0][1], bb[1][1]]) {
+          const p = projection([lon, lat]);
+          if (p && Number.isFinite(p[1])) {
+            if (p[1] < yMin) yMin = p[1];
+            if (p[1] > yMax) yMax = p[1];
+          }
+        }
+      }
+    }
+    if (yMin < yMax) {
+      const boxTop = fitTop;
+      const boxBottom = fitBottom;
+      // Center the data's vertical span; the bbox midpoint balances the northern
+      // and southern extremes evenly (an area-weighted centroid would skew toward
+      // the larger landmasses and over-shoot the frame).
+      let dy = (boxTop + boxBottom) / 2 - (yMin + yMax) / 2;
+      // Clamp so the data span stays within [boxTop, boxBottom]; if it is taller
+      // than the box, the midpoint target already gives symmetric overflow.
+      const minDy = boxTop - yMin;
+      const maxDy = boxBottom - yMax;
+      if (minDy <= maxDy) dy = Math.max(minDy, Math.min(maxDy, dy));
+      const [tx, ty] = projection.translate();
+      projection.translate([tx, ty + dy]);
+    }
+  }
+
   // Global views stretch-fill the canvas. A whole-world map is ~2:1 but the
   // preview pane is often near-square, so the honest contain-fit letterboxes it
   // with large water bands. For GLOBAL extents we stretch the PROJECTED geometry
@@ -1292,12 +1538,15 @@ export function layoutMap(
         ).stream.point(px, py);
       },
     });
+    const thin = geoThin();
     path = geoPath({
       stream: (s: never) =>
         baseProjection.stream(
-          (tx as unknown as { stream: (d: never) => never }).stream(s)
+          (tx as unknown as { stream: (d: never) => never }).stream(
+            (thin as unknown as { stream: (d: never) => never }).stream(s)
+          )
         ),
-    } as never);
+    } as never).digits(PATH_DIGITS);
     project = (lon, lat) => {
       const p = baseProjection([lon, lat]);
       return p ? stretch(p[0], p[1]) : null;
@@ -1316,7 +1565,13 @@ export function layoutMap(
       [0, 0],
       [width, height],
     ]);
-    path = geoPath(projection);
+    const thin = geoThin();
+    path = geoPath({
+      stream: (s: never) =>
+        projection.stream(
+          (thin as unknown as { stream: (d: never) => never }).stream(s)
+        ),
+    } as never).digits(PATH_DIGITS);
     project = (lon, lat) => projection([lon, lat]) ?? null;
   }
 
@@ -1431,7 +1686,8 @@ export function layoutMap(
         ],
         f as never
       );
-      const d = geoPath(proj)(f as never) ?? '';
+      const insetPath = geoPath(proj).digits(PATH_DIGITS);
+      const d = insetPath(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
@@ -1440,7 +1696,7 @@ export function layoutMap(
       let contextLand: { d: string; fill: string } | undefined;
       if (iso === 'US-AK') {
         const can = worldLayer.get('CA');
-        const cd = can ? (geoPath(proj)(can as never) ?? '') : '';
+        const cd = can ? (insetPath(can as never) ?? '') : '';
         if (cd)
           contextLand = {
             d: cd,
@@ -2003,6 +2259,13 @@ export function layoutMap(
         : 1;
     return R_MIN + Math.max(0, Math.min(1, t)) * (R_MAX - R_MIN);
   };
+  // Fade the fill as the bubble grows (stroke handled separately at render).
+  const fillOpacityFor = (r: number): number => {
+    const t = Math.max(0, Math.min(1, (r - R_MIN) / (R_MAX - R_MIN)));
+    return (
+      POI_FILL_OPACITY_MAX - t * (POI_FILL_OPACITY_MAX - POI_FILL_OPACITY_MIN)
+    );
+  };
 
   // 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.
@@ -2028,6 +2291,21 @@ export function layoutMap(
     };
   };
 
+  // Connector colour (§24B.6): a tag on the edge/leg LINE colours the line. Walk
+  // the declared tag groups (first match wins, like poiFill) and return its hex,
+  // or null → caller falls back to the neutral connector mix.
+  const lineColor = (tags: Readonly<Record<string, string>>): string | null => {
+    for (const group of resolved.tagGroups) {
+      const val = tags[group.name.toLowerCase()];
+      if (!val) continue;
+      const entry = group.entries.find(
+        (e) => e.value.toLowerCase() === val.toLowerCase()
+      );
+      if (entry?.color) return entry.color; // already hex (parser-resolved)
+    }
+    return null;
+  };
+
   // Route metadata first so POIs know origin/number.
   const routeNumberById = new Map<string, number>();
   const originIds = new Set<string>();
@@ -2060,14 +2338,16 @@ export function layoutMap(
     clusterId?: string
   ): void => {
     const { fill, stroke } = poiFill(e.p);
-    poiScreen.set(e.p.id, { cx, cy, r: radiusFor(e.p) });
+    const r = radiusFor(e.p);
+    poiScreen.set(e.p.id, { cx, cy, r });
     const num = routeNumberById.get(e.p.id);
     pois.push({
       id: e.p.id,
       cx,
       cy,
-      r: radiusFor(e.p),
+      r,
       fill,
+      fillOpacity: fillOpacityFor(r),
       stroke,
       lineNumber: e.p.lineNumber,
       implicit: !!e.p.implicit,
@@ -2264,8 +2544,11 @@ export function layoutMap(
       legs.push({
         d: legPath(a, b, bow.curved, bow.offset),
         width: routeWidthFor(Number(leg.value)),
-        color: mix(palette.text, palette.bg, 72),
+        color: lineColor(leg.tags) ?? mix(palette.text, palette.bg, 72),
         arrow: true,
+        fromId: leg.fromId,
+        toId: leg.toId,
+        ...(Object.keys(leg.tags).length > 0 && { tags: leg.tags }),
         lineNumber: leg.lineNumber,
         ...(leg.label !== undefined && {
           label: leg.label,
@@ -2321,8 +2604,11 @@ export function layoutMap(
       legs.push({
         d: legPath(a, b, bow.curved, bow.offset),
         width: widthFor(e),
-        color: mix(palette.text, palette.bg, 66),
+        color: lineColor(e.tags) ?? mix(palette.text, palette.bg, 66),
         arrow: e.directed,
+        fromId: e.fromId,
+        toId: e.toId,
+        ...(Object.keys(e.tags).length > 0 && { tags: e.tags }),
         lineNumber: e.lineNumber,
         ...(e.label !== undefined && {
           label: e.label,
@@ -2339,6 +2625,11 @@ export function layoutMap(
   // -- Labels: regions + POIs with escalation (AR5) --
   const labels: PlacedLabel[] = [];
   const obstacles: LabelRect[] = [];
+  // Region/orientation labels are the frame; POI labels are the subject. The
+  // region pass runs first (can't yet see where POI labels land), so each region
+  // label registers a guard here; after POI placement any guard a POI label
+  // overlaps yields — the region label is removed rather than crammed.
+  const regionLabelGuards: Array<{ label: PlacedLabel; rect: LabelRect }> = [];
   const markers: PointCircle[] = pois.map((p) => ({
     cx: p.cx,
     cy: p.cy,
@@ -2392,18 +2683,91 @@ export function layoutMap(
   // ocean. At the compact breakpoint (decision D2) the abbreviation is preferred
   // FIRST for US states.
   const showRegionLabels = resolved.directives.noRegionLabels !== true;
+  // Metric value shown UNDER each data region's name (`no-region-value` opts out).
+  // The value line is rendered smaller + dimmer than the name; see the renderer.
+  // Scoped to a `region-metric` choropleth: only when the SCORE ramp is the active
+  // colouring dimension (not a tag-coloured / categorical map) is the numeric
+  // value the data on display, so that's the only case it's surfaced.
+  const showRegionValues =
+    resolved.directives.noRegionValue !== true && activeIsScore;
+  // Compact value string for a region, or undefined when there's nothing to show
+  // (no value, or the feature is off). Shared formatter so it matches the legend.
+  const regionValueStr = (value: number | undefined): string | undefined =>
+    showRegionValues && value !== undefined ? compactNumber(value) : undefined;
   const isCompact = width < COMPACT_WIDTH_PX;
+  // Zoomed sub-national US choropleth (map-us-subnational-zoom): a US-states
+  // mercator view with the score ramp active. Here a cramped state (NH, RI, CT,
+  // NJ, DE) should NOT degrade to its 2-letter abbreviation — the user reads the
+  // abbreviation poorly and a stray hover-name then steps on it. Instead it keeps
+  // its FULL name and, if that won't fit in place, takes a leader-lined margin
+  // callout (full name + value). Only a handful of states are in frame at this
+  // zoom, so the callout column stays short. National (albers) maps keep the
+  // abbreviation cascade — 50 full-name callouts would be unreadable.
+  const usChoroplethZoom =
+    resolved.projection === 'mercator' &&
+    resolved.basemaps.subdivisions.includes('us-states') &&
+    activeIsScore;
   const LABEL_PADX = 6;
   const LABEL_PADY = 3;
-  const labelW = (text: string): number =>
-    measureLegendText(text, FONT) + 2 * LABEL_PADX;
+  // The value line is ~0.82× the name size; a hair of vertical gap separates them.
+  const VALUE_FONT = Math.round(FONT * 0.82);
+  const VALUE_GAP = 1;
+  const labelW = (text: string, font: number = FONT): number =>
+    measureLegendText(text, font) + 2 * LABEL_PADX;
   const labelH = FONT + 2 * LABEL_PADY;
+  // Footprint of a name (+optional value) stack used for the box-fit cascade.
+  // `font` defaults to the base size (every existing call is byte-identical);
+  // the post-placement growth pass passes a larger size to test an upscaled fit.
+  const stackW = (
+    text: string,
+    valueText?: string,
+    font: number = FONT
+  ): number =>
+    Math.max(
+      labelW(text, font),
+      valueText
+        ? measureLegendText(valueText, Math.round(font * 0.82)) + 2 * LABEL_PADX
+        : 0
+    );
+  const stackH = (hasValue: boolean, font: number = FONT): number => {
+    const lh = font + 2 * LABEL_PADY;
+    return hasValue ? lh + VALUE_GAP + Math.round(font * 0.82) : lh;
+  };
+  // Footprint-driven label growth (size-up + fade), gradual + resolution-free.
+  // Applies to ORIENTATION backdrop names ONLY (neighbour land / frame
+  // containers with no data value): a big one reads as a large, gently-faded
+  // backdrop, a small one stays at the base font. DATA labels are deliberately
+  // EXCLUDED — fading a choropleth value washes it lighter than its own fill and
+  // a loose bbox overran irregular regions. Size scales with the region's
+  // projected footprint as a fraction of the canvas's linear extent. Growth runs
+  // AFTER the base-font fit cascade picks the text+anchor, and only while the
+  // larger glyphs still fit the box, clear neighbours/POIs, and stay inside the
+  // region's own fill.
+  const REGION_FONT_MAX_ORIENT = 22; // px ceiling, backdrop names
+  const REGION_SIZE_FRAC_MIN = 0.06; // footprint linear-frac at base font
+  const REGION_SIZE_FRAC_MAX = 0.32; // footprint linear-frac at max font
+  const REGION_FADE_ORIENT = 45; // % toward bg at max size, backdrop
+  const canvasLinear = Math.sqrt(Math.max(1, width * height));
+  const sizeT = (boxW: number, boxH: number): number => {
+    const frac = Math.sqrt(Math.max(0, boxW * boxH)) / canvasLinear;
+    return Math.min(
+      1,
+      Math.max(
+        0,
+        (frac - REGION_SIZE_FRAC_MIN) /
+          (REGION_SIZE_FRAC_MAX - REGION_SIZE_FRAC_MIN)
+      )
+    );
+  };
   const pushRegionLabel = (
     x: number,
     y: number,
     text: string,
     fill: string,
-    lineNumber: number
+    lineNumber: number,
+    valueLine?: string,
+    fontSize: number = FONT,
+    fade: number = 0
   ): void => {
     // 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
@@ -2415,9 +2779,20 @@ export function layoutMap(
     // 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(
+    const { color: baseColor, haloColor } = labelOnFill(fill);
+    // Subdue a grown label toward the background — gentle on data (value stays
+    // readable), stronger on orientation backdrop. Zero fade ⇒ exact base color.
+    const color = fade > 0 ? mix(baseColor, palette.bg, fade) : baseColor;
+    // Widest of name / value drives the overflow sample (the value line can be
+    // the wider of the two, e.g. a short name over a long number). Scales with
+    // the actual (possibly grown) font so the halo gate matches what's drawn.
+    const vf = Math.round(fontSize * 0.82);
+    const halfW =
+      Math.max(
+        measureLegendText(text, fontSize),
+        valueLine ? measureLegendText(valueLine, vf) : 0
+      ) / 2;
+    const overflows = [y - fontSize * 0.55, y - fontSize * 0.1].some(
       (sy) => fillAt(x - halfW, sy) !== fill || fillAt(x + halfW, sy) !== fill
     );
     labels.push({
@@ -2428,15 +2803,31 @@ export function layoutMap(
       color,
       halo: overflows,
       haloColor,
+      ...(fontSize !== FONT && { fontSize }),
+      ...(valueLine !== undefined && { valueLine }),
       lineNumber,
     });
   };
   // 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).
+  // With a value line the box grows to the taller two-line stack.
   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 };
+  const regionLabelRect = (
+    cx: number,
+    cy: number,
+    text: string,
+    valueText?: string,
+    font: number = FONT
+  ): LabelRect => {
+    const vf = Math.round(font * 0.82);
+    const w =
+      Math.max(
+        measureLegendText(text, font),
+        valueText ? measureLegendText(valueText, vf) : 0
+      ) +
+      2 * REGION_LABEL_GAP;
+    const h = valueText ? font + VALUE_GAP + vf : font;
+    return { x: cx - w / 2, y: cy - h / 2, w, h };
   };
   if (showRegionLabels) {
     // Gather the placeable region labels, then commit them largest-footprint
@@ -2463,13 +2854,23 @@ export function layoutMap(
         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;
+        // breakpoint abbrev is tried first. A POI-frame CONTAINER (e.g. the
+        // "California" framing a US cloud-regions map) never degrades to the
+        // 2-letter code to squeeze past its own POIs — it stays full or yields
+        // entirely (the post-POI guard below hides it on collision).
+        // On a zoomed US choropleth, drop the abbreviation entirely (full name or
+        // a leader callout — never "NH"). Elsewhere the full → abbrev → hide
+        // cascade stands (compact tries abbrev first; a POI container never
+        // abbreviates).
+        const abbrev =
+          isUsState && !usChoroplethZoom ? r.id.replace(/^US-/, '') : undefined;
         const candidates =
           abbrev !== undefined
             ? isCompact
               ? [abbrev, r.label]
-              : [r.label, abbrev]
+              : isContainer
+                ? [r.label]
+                : [r.label, abbrev]
             : [r.label];
         const anchor = !isUsState ? WORLD_LABEL_ANCHORS[r.id] : undefined;
         const c = anchor
@@ -2481,6 +2882,18 @@ export function layoutMap(
       .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[] = [];
+    // Valued regions too small to carry their name+value stack in place — gathered
+    // here and laid out as a margin callout column after the in-place pass.
+    const regionCallouts: Array<{
+      name: string;
+      value: string;
+      cx: number;
+      cy: number;
+      bw: number;
+      bh: number;
+      fill: string;
+      lineNumber: number;
+    }> = [];
     // 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
@@ -2496,35 +2909,394 @@ export function layoutMap(
       w: 2 * (p.r + POI_LABEL_PAD),
       h: 2 * (p.r + POI_LABEL_PAD),
     }));
+    // Ocean side of the frame (zoomed US choropleth callouts column there). Sample
+    // a vertical strip just inside each side edge; the side with more open water
+    // hosts the callout column, so leaders run over sea, not across the interior.
+    const waterSideOf = (): 'left' | 'right' => {
+      let leftHits = 0;
+      let rightHits = 0;
+      const lx = width * 0.06;
+      const rx = width * 0.94;
+      for (let i = 1; i < 12; i++) {
+        const y = topPad + ((height - topPad) * i) / 12;
+        if (fillAt(lx, y) === water) leftHits++;
+        if (fillAt(rx, y) === water) rightHits++;
+      }
+      return rightHits >= leftHits ? 'right' : 'left';
+    };
+    const calloutSide = usChoroplethZoom ? waterSideOf() : undefined;
     for (const { r, c, boxW, boxH, candidates } of entries) {
+      const valStr = regionValueStr(r.value);
+      // A region hugs a canvas edge if it sits within a short leader's reach of
+      // it — only such a region may use a margin callout column, so the leader is
+      // always SHORT (no cross-map lines for a centred region).
+      const maxLeader = Math.min(width * 0.26, 300);
+      // "Near an edge" is measured against the LAND-facing edge of each reserved
+      // band when a reserve is active (second pass) — the map has shrunk away from
+      // that side, so the cluster now sits at the band's inner edge, not the raw
+      // canvas edge. Without a reserve (first pass) this is just the canvas edge.
+      const rsv = opts._calloutReserve;
+      const rEdge = rsv?.right ? width - rsv.right : width;
+      const lEdge = rsv?.left ?? 0;
+      // On a zoomed US choropleth a cramped state always takes a margin callout (a
+      // full-name + value chip in the ocean-side column, leader from its centroid)
+      // rather than degrading to an abbreviation — only a handful of states are in
+      // frame, so the column stays short. Otherwise a callout is reserved for
+      // edge-hugging regions so no leader runs across a wide view.
+      const nearEdge =
+        usChoroplethZoom ||
+        c[0] >= rEdge - maxLeader ||
+        c[0] <= lEdge + maxLeader;
+      // A tiny region hugging a canvas edge — one whose FULL name won't fit its
+      // own box (RI/CT/NH/MA on a US map) — goes straight to a clean margin
+      // column: a tidy full-name list reads far better than crammed 2-letter
+      // abbreviations piled on the cluster, and the edge keeps the leader short. A
+      // region whose full name DOES fit labels in place as usual; an interior tiny
+      // region (a centred world-map country) is handled by the on-land overflow
+      // below — never a long cross-map leader.
+      if (
+        valStr &&
+        nearEdge &&
+        r.label !== undefined &&
+        (labelW(r.label) > boxW || labelH > boxH)
+      ) {
+        regionCallouts.push({
+          name: r.label,
+          value: valStr,
+          cx: c[0],
+          cy: c[1],
+          bw: boxW,
+          bh: boxH,
+          fill: r.fill,
+          lineNumber: r.lineNumber,
+        });
+        continue;
+      }
       // 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))
+      // When the region carries a metric value, the name+value STACK is tried
+      // first; if the stack won't fit (a smaller state), it degrades to the bare
+      // name (today's behaviour) so adding values never costs an existing label.
+      //
+      // Two collision tests, deliberately different footprints:
+      //  - vs other REGION labels: use the FULL stack rect (two stacks must not
+      //    overlap).
+      //  - vs POI obstacles: use only the NAME rect. A POI obstacle exists to keep
+      //    the region NAME off a POI's dot/label; the (shorter, dimmer) value line
+      //    hanging below a name that already clears the dot is fine. Testing the
+      //    taller stack here made a region with a nearby POI (Texas under the big
+      //    Dallas marker) silently drop its value even though the name fit.
+      const fitsRegions = (rect: LabelRect): boolean =>
+        !placedRegionRects.some((p) => rectsOverlap(rect, p));
+      const fitsPois = (rect: LabelRect): boolean =>
+        !poiObstacles.some((o) => rectsOverlap(rect, o));
+      // Try the centroid first (existing placement — unchanged when it fits),
+      // then a ring of offsets WITHIN the region's box so a label blocked at the
+      // centroid (typically a POI marker sitting on it — Dallas on Texas) is
+      // re-seated on open land of the SAME region rather than exiled to a far
+      // callout column. Off-centroid anchors are kept on the region's own fill
+      // (fillAt) so the label never drifts onto a neighbour or the sea.
+      // Centroid is always tried. The off-centroid re-seat ring is added ONLY for
+      // a region that carries a value — the point of seeking is to not lose the
+      // region's VALUE to a POI on its centroid. A valueless frame container
+      // (e.g. the state hosting a POI hub) keeps the old behaviour: it yields the
+      // spot to the POI rather than sprouting a re-seated name near the hub.
+      const seekAnchors: Array<{ x: number; y: number; guard: boolean }> = [
+        { x: c[0], y: c[1], guard: false },
+      ];
+      if (valStr) {
+        seekAnchors.push(
+          { x: c[0], y: c[1] + boxH * 0.26, guard: true },
+          { x: c[0], y: c[1] - boxH * 0.26, guard: true },
+          { x: c[0] + boxW * 0.26, y: c[1], guard: true },
+          { x: c[0] - boxW * 0.26, y: c[1], guard: true },
+          { x: c[0] + boxW * 0.22, y: c[1] + boxH * 0.22, guard: true },
+          { x: c[0] - boxW * 0.22, y: c[1] + boxH * 0.22, guard: true },
+          { x: c[0] + boxW * 0.22, y: c[1] - boxH * 0.22, guard: true },
+          { x: c[0] - boxW * 0.22, y: c[1] - boxH * 0.22, guard: true }
         );
+      }
+      let chosen:
+        | { text: string; valueLine?: string; ax: number; ay: number }
+        | undefined;
+      for (const a of seekAnchors) {
+        if (a.guard && fillAt(a.x, a.y) !== r.fill) continue;
+        for (const t of candidates) {
+          const nameRect = regionLabelRect(a.x, a.y, t);
+          if (valStr && stackW(t, valStr) <= boxW && stackH(true) <= boxH) {
+            const stackRect = regionLabelRect(a.x, a.y, t, valStr);
+            if (fitsRegions(stackRect) && fitsPois(nameRect)) {
+              chosen = { text: t, valueLine: valStr, ax: a.x, ay: a.y };
+              break;
+            }
+          }
+          if (labelW(t) <= boxW && labelH <= boxH) {
+            if (fitsRegions(nameRect) && fitsPois(nameRect)) {
+              chosen = { text: t, ax: a.x, ay: a.y };
+              break;
+            }
+          }
+        }
+        if (chosen) break;
+      }
+      if (chosen === undefined && valStr) {
+        // A VALUED region not placed in-box, and not an edge-hugging tiny region
+        // (those columned above). Label it ON its own land, letting the name
+        // OVERFLOW its small box onto neighbours/ocean (the halo keeps it legible),
+        // as long as it clears already-placed labels + POIs. This keeps a country
+        // on a world choropleth (Germany, France) labelled in place instead of
+        // exiled to a far margin. If even that collides, the label simply drops —
+        // never a long cross-map leader. Gated to valued regions so a valueless
+        // POI-frame container keeps its old behaviour (yield rather than overflow).
+        for (const a of seekAnchors) {
+          if (fillAt(a.x, a.y) !== r.fill) continue;
+          for (const t of candidates) {
+            const nameRect = regionLabelRect(a.x, a.y, t);
+            if (
+              valStr &&
+              fitsRegions(regionLabelRect(a.x, a.y, t, valStr)) &&
+              fitsPois(nameRect)
+            ) {
+              chosen = { text: t, valueLine: valStr, ax: a.x, ay: a.y };
+              break;
+            }
+            if (fitsRegions(nameRect) && fitsPois(nameRect)) {
+              chosen = { text: t, ax: a.x, ay: a.y };
+              break;
+            }
+          }
+          if (chosen) break;
+        }
+      }
+      // Nothing placed (a valueless region that didn't fit, or a valued region
+      // whose overflow also collided) → drop, leaving the map clean.
+      if (chosen === undefined) continue;
+      // Footprint-driven growth applies ONLY to orientation backdrop names — a
+      // data-less neighbour/frame region (Canada framing a POI, foreign land).
+      // DATA labels (a choropleth value) keep the base font + full contrast and
+      // the existing fit-inside cascade UNCHANGED: fading a value washed it
+      // lighter than its own region fill, and a loose bbox let a wide name
+      // ("United States of America") spill past its region. Orientation names sit
+      // on neutral basemap land where a larger, gently-faded backdrop reads well.
+      const isOrient = r.value === undefined && r.layer === 'base';
+      let font = FONT;
+      let fade = 0;
+      if (isOrient) {
+        const growT = sizeT(boxW, boxH);
+        const desiredFont = Math.round(
+          FONT + growT * (REGION_FONT_MAX_ORIENT - FONT)
+        );
+        const hasVal = chosen.valueLine !== undefined;
+        for (let f = desiredFont; f > FONT; f--) {
+          // Fit the footprint box, clear neighbours/POIs, AND — the real guard —
+          // stay INSIDE the region's own fill at the bigger size. The bbox is far
+          // too loose for an irregular shape (Alaska blows up the US bbox), so
+          // sample the grown name's horizontal extremes against `fillAt`: if
+          // either leaves this region's fill, don't grow that far.
+          if (
+            stackW(chosen.text, chosen.valueLine, f) > boxW ||
+            stackH(hasVal, f) > boxH
+          )
+            continue;
+          const gRect = regionLabelRect(
+            chosen.ax,
+            chosen.ay,
+            chosen.text,
+            chosen.valueLine,
+            f
+          );
+          const gName = regionLabelRect(
+            chosen.ax,
+            chosen.ay,
+            chosen.text,
+            undefined,
+            f
+          );
+          if (!fitsRegions(gRect) || !fitsPois(gName)) continue;
+          const halfW = measureLegendText(chosen.text, f) / 2;
+          if (
+            fillAt(chosen.ax - halfW, chosen.ay) !== r.fill ||
+            fillAt(chosen.ax + halfW, chosen.ay) !== r.fill
+          )
+            continue;
+          font = f;
+          break;
+        }
+        fade = font > FONT ? Math.round(growT * REGION_FADE_ORIENT) : 0;
+      }
+      const rRect = regionLabelRect(
+        chosen.ax,
+        chosen.ay,
+        chosen.text,
+        chosen.valueLine,
+        font
+      );
+      placedRegionRects.push(rRect);
+      pushRegionLabel(
+        chosen.ax,
+        chosen.ay,
+        chosen.text,
+        r.fill,
+        r.lineNumber,
+        chosen.valueLine,
+        font,
+        fade
+      );
+      // Guard so a POI label landing here later makes this label yield (below).
+      regionLabelGuards.push({
+        label: labels[labels.length - 1]!,
+        rect: rRect,
       });
-      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). Insets are
     // tiny, so prefer the abbreviation when the canvas is compact.
     for (const seed of insetLabelSeeds) {
       const text = isCompact ? seed.iso.replace(/^US-/, '') : seed.name;
       const src = regionById.get(seed.iso);
+      const valStr = regionValueStr(src?.value);
       pushRegionLabel(
         seed.x,
         seed.y,
         text,
         src ? regionFill(src) : neutralFill,
-        seed.lineNumber
+        seed.lineNumber,
+        valStr
       );
+      regionLabelGuards.push({
+        label: labels[labels.length - 1]!,
+        rect: regionLabelRect(seed.x, seed.y, text, valStr),
+      });
+    }
+
+    // Zoom-out reserve (first pass → re-run): tiny valued regions need margin
+    // callouts, and the map currently fills the canvas with no room for them.
+    // Measure them, reserve a band on the side the cluster leans toward, and
+    // re-run the whole layout fitted into the canvas MINUS that band — the map
+    // shrinks/shifts away from that edge and the callouts get real room. Guarded
+    // by `_calloutReserve` so it recurses exactly once.
+    if (regionCallouts.length > 0 && !opts._calloutReserve) {
+      // Split the callouts by the side of the canvas they fall on — a cluster on
+      // each coast gets its own reserved band + column. Band = widest chip in the
+      // group + a leader run + edge padding, clamped so one stray callout never
+      // over-shrinks the map nor a long name starves it.
+      const bandFor = (group: typeof regionCallouts): number | undefined => {
+        if (group.length === 0) return undefined;
+        const maxChipW = group.reduce(
+          (m, rc) =>
+            Math.max(
+              m,
+              measureLegendText(rc.name, FONT),
+              measureLegendText(rc.value, VALUE_FONT)
+            ),
+          0
+        );
+        return Math.max(130, Math.min(maxChipW + 96, Math.floor(width * 0.3)));
+      };
+      // On a zoomed US choropleth all callouts share the ocean-side column (leaders
+      // over sea, never across the interior); elsewhere split by the side each
+      // region leans toward.
+      const right =
+        calloutSide === 'right'
+          ? regionCallouts
+          : calloutSide === 'left'
+            ? []
+            : regionCallouts.filter((rc) => rc.cx >= width / 2);
+      const left =
+        calloutSide === 'left'
+          ? regionCallouts
+          : calloutSide === 'right'
+            ? []
+            : regionCallouts.filter((rc) => rc.cx < width / 2);
+      const leftPx = bandFor(left);
+      const rightPx = bandFor(right);
+      return layoutMap(resolved, data, size, {
+        ...opts,
+        _calloutReserve: {
+          ...(leftPx !== undefined && { left: leftPx }),
+          ...(rightPx !== undefined && { right: rightPx }),
+        },
+      });
+    }
+
+    // ── Radial callouts for valued regions too small to label in place ──
+    // Each gathered region gets a leader-lined chip (its name over the metric
+    // value, same stack as an in-place label) placed in the OPEN SPACE around the
+    // cluster: the chip marches OUTWARD from the cluster centre along its own
+    // angle (so a dense cluster fans its labels out in all directions — east into
+    // the ocean, north over Canada, etc.) until it clears the data regions, the
+    // in-place labels, and the other chips. A small dot marks the region's true
+    // centroid; the leader runs dot → chip. Chips may overlay unvalued base land
+    // (e.g. Canada) but never a VALUED region's fill (keep the choropleth clean).
+    if (regionCallouts.length > 0) {
+      // Tidy callout column(s) in the reserved margin(s) the zoom-out pass opened.
+      // Each chip is a name+value stack anchored just inside the band; a leader
+      // runs from the region's centroid dot to the chip's inner edge. Rows are
+      // ordered top→bottom by screen latitude so the column reads geographically
+      // and the leaders stay short and roughly parallel. A cluster on each side of
+      // the canvas gets its own column in its own reserved band.
+      const reserveInfo = opts._calloutReserve;
+      const EDGE = 28;
+      const COL_GAP = 16; // chip inset from the land-facing edge of the band
+      const chipH = FONT + VALUE_GAP + VALUE_FONT;
+      const ROW = chipH + 10;
+      const placeColumn = (
+        group: typeof regionCallouts,
+        side: 'left' | 'right',
+        bandPx: number
+      ): void => {
+        if (group.length === 0) return;
+        const anchor: PlacedLabel['anchor'] =
+          side === 'right' ? 'start' : 'end';
+        const colX =
+          side === 'right' ? width - bandPx + COL_GAP : bandPx - COL_GAP;
+        const rows = [...group].sort((a, b) => a.cy - b.cy);
+        const meanCy = rows.reduce((s, rc) => s + rc.cy, 0) / rows.length;
+        const totalH = rows.length * ROW;
+        const minTop = topPad + 6 + ROW / 2;
+        const maxTop = Math.max(minTop, height - EDGE - totalH + ROW / 2);
+        const startY = Math.max(
+          minTop,
+          Math.min(meanCy - totalH / 2 + ROW / 2, maxTop)
+        );
+        rows.forEach((rc, i) => {
+          const ry = startY + i * ROW;
+          const innerX = side === 'right' ? colX - 4 : colX + 4;
+          // Darken the region's hue toward the text colour for leader/dot contrast
+          // (a pale low-value fill on its own is near-invisible) while still tying
+          // the line to its region by colour.
+          const dark = mix(rc.fill, palette.text, 60);
+          labels.push({
+            x: colX,
+            y: ry,
+            text: rc.name,
+            anchor,
+            color: palette.text,
+            halo: true,
+            haloColor: palette.bg,
+            valueLine: rc.value,
+            leader: { x1: rc.cx, y1: rc.cy, x2: innerX, y2: ry },
+            leaderColor: dark,
+            calloutDot: { x: rc.cx, y: rc.cy, color: dark },
+            lineNumber: rc.lineNumber,
+          });
+        });
+      };
+      const right =
+        calloutSide === 'right'
+          ? regionCallouts
+          : calloutSide === 'left'
+            ? []
+            : regionCallouts.filter((rc) => rc.cx >= width / 2);
+      const left =
+        calloutSide === 'left'
+          ? regionCallouts
+          : calloutSide === 'right'
+            ? []
+            : regionCallouts.filter((rc) => rc.cx < width / 2);
+      placeColumn(right, 'right', reserveInfo?.right ?? 150);
+      placeColumn(left, 'left', reserveInfo?.left ?? 150);
     }
   }
 
@@ -2551,6 +3323,16 @@ export function layoutMap(
     // from the east AND west — Boulder in the route-cluster gauntlet).
     type Side = 'right' | 'left' | 'above' | 'below';
     const GAP = 3;
+    // Comfort buffer between any dot/label and the canvas edge — canvas-proportional
+    // (≈3% of the shorter axis, floored) so a big preview pane breathes more than a
+    // thumbnail. Used BOTH by the leader-column clamp (so a column never seats hard
+    // against the frame) and by the edge-clearance re-fit below (dots + inline
+    // labels). Keeping the two in sync is what stops the re-fit from fighting a
+    // column that would otherwise re-clamp to the edge each pass.
+    const POI_EDGE_CLEAR = Math.max(
+      20,
+      Math.round(Math.min(width, height) * 0.03)
+    );
     // 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
@@ -2589,7 +3371,8 @@ export function layoutMap(
       p: MapLayoutPoi,
       text: string,
       w: number,
-      side: Side
+      side: Side,
+      clusterId?: string
     ): void => {
       const rect = inlineRect(p, w, side);
       obstacles.push(rect);
@@ -2606,6 +3389,7 @@ export function layoutMap(
         haloColor: palette.bg,
         poiId: p.id,
         lineNumber: p.lineNumber,
+        ...(clusterId !== undefined && { clusterMember: clusterId }),
       });
     };
     const inlineFits = (p: MapLayoutPoi, w: number, side: Side): boolean => {
@@ -2664,11 +3448,14 @@ export function layoutMap(
       // 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);
+          ? Math.min(right + COL_GAP, width - POI_EDGE_CLEAR - maxW)
+          : Math.max(left - COL_GAP, POI_EDGE_CLEAR + maxW);
       const totalH = items.length * step;
       let startY = cyMid - totalH / 2;
-      startY = Math.max(2, Math.min(startY, height - totalH - 2));
+      startY = Math.max(
+        POI_EDGE_CLEAR,
+        Math.min(startY, height - totalH - POI_EDGE_CLEAR)
+      );
       return items.map((o, i) => {
         const rowCy = startY + i * step + step / 2;
         return {
@@ -2698,12 +3485,50 @@ export function layoutMap(
           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';
+    // Open-space score for a candidate label rect (higher = better). Cartographic
+    // convention: a coastal point throws its label out over the water, never back
+    // across the land it sits on. So a side whose label footprint lands over open
+    // water dominates; among equally-wet (or equally-dry) sides, the one with more
+    // clearance to the canvas edge wins. Sampled at a fixed 3×2 grid → deterministic.
+    const WATER_PREF = 1000; // a water-facing side beats any land-facing side
+    const openness = (rect: LabelRect): number => {
+      const xs = [
+        rect.x + rect.w * 0.15,
+        rect.x + rect.w * 0.5,
+        rect.x + rect.w * 0.85,
+      ];
+      const ys = [rect.y + rect.h * 0.25, rect.y + rect.h * 0.75];
+      let waterHits = 0;
+      for (const x of xs)
+        for (const y of ys) if (fillAt(x, y) === water) waterHits++;
+      const waterFrac = waterHits / (xs.length * ys.length);
+      const edgeClear = Math.max(
+        0,
+        Math.min(
+          rect.x,
+          width - (rect.x + rect.w),
+          rect.y,
+          height - (rect.y + rect.h)
+        )
+      );
+      // edgeClear scaled to ~0..30 so it only breaks ties, never overrides water.
+      return WATER_PREF * waterFrac + edgeClear * 0.1;
     };
+    // A column side's openness = mean openness over its rows' label rects.
+    const columnSideScore = (
+      items: ColItem[],
+      side: 'right' | 'left'
+    ): number => {
+      const rows = columnRows(items, side);
+      if (rows.length === 0) return -Infinity;
+      return rows.reduce((s, { rect }) => s + openness(rect), 0) / rows.length;
+    };
+    // Side heuristic for ungated callouts: prefer the more open (water-facing,
+    // then roomier) flank rather than blindly seating the column on the right.
+    const defaultColumnSide = (items: ColItem[]): 'right' | 'left' =>
+      columnSideScore(items, 'right') >= columnSideScore(items, 'left')
+        ? '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
@@ -2763,22 +3588,83 @@ export function layoutMap(
       });
     };
 
-    // 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.
+    // A small coincident stack reads best with each member's label hugging its
+    // OWN fanned dot on the side it fans toward — the fan already seats the dots
+    // radially (member 0 due North, the next due South for a pair, …), so a top
+    // dot takes its label ABOVE and a bottom dot takes it BELOW. Compact and
+    // symmetric, and — unlike a one-sided leader column — it never overruns the
+    // frame when the stack sits hard against a coast (the San Jose case). The
+    // labels carry `clusterMember` so the app still toggles them with the badge.
+    const STACK_RADIAL_MAX = 4; // above/below/left/right — one slot per member
+    const radialSide = (p: MapLayoutPoi, cx: number, cy: number): Side => {
+      const dx = p.cx - cx;
+      const dy = p.cy - cy;
+      return Math.abs(dy) >= Math.abs(dx)
+        ? dy <= 0
+          ? 'above'
+          : 'below'
+        : dx < 0
+          ? 'left'
+          : 'right';
+    };
+    // Seat every member radially (preferred side first, then the rest), each new
+    // label blocking the next. All-or-nothing: if any member can't seat on-canvas
+    // and clean, bail so the caller falls back to the leader-lined column.
+    const tryStackRadial = (items: ColItem[], clusterId: string): boolean => {
+      const cluster = clusters.find((c) => c.id === clusterId);
+      if (!cluster || items.length > STACK_RADIAL_MAX) return false;
+      const temp: LabelRect[] = [];
+      const seated: Array<{
+        p: MapLayoutPoi;
+        text: string;
+        w: number;
+        side: Side;
+      }> = [];
+      for (const { p, text, w } of items) {
+        const pref = radialSide(p, cluster.cx, cluster.cy);
+        const order: Side[] = [
+          pref,
+          ...(['above', 'below', 'right', 'left'] as Side[]).filter(
+            (s) => s !== pref
+          ),
+        ];
+        const side = order.find((s) => {
+          const rect = inlineRect(p, w, s);
+          return (
+            rect.x >= 0 &&
+            rect.x + rect.w <= width &&
+            rect.y >= 0 &&
+            rect.y + rect.h <= height &&
+            !collides(rect) &&
+            !temp.some((t) => rectsOverlap(t, rect))
+          );
+        });
+        if (side === undefined) return false;
+        temp.push(inlineRect(p, w, side));
+        seated.push({ p, text, w, side });
+      }
+      for (const { p, text, w, side } of seated)
+        pushInline(p, text, w, side, clusterId);
+      return true;
+    };
+    // Spiderfy clusters: committed FIRST so the singleton/group passes route
+    // around them. Try the compact radial layout; only a stack too big (or too
+    // boxed-in) for cardinal slots falls back to a tidy leader-lined column,
+    // thrown to the cleaner/seaward flank.
     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);
+      if (tryStackRadial(items, clusterId)) continue;
+      const cleanR = wouldColumnBeClean(items, 'right');
+      const cleanL = wouldColumnBeClean(items, 'left');
+      const side =
+        cleanR && cleanL
+          ? defaultColumnSide(items)
+          : cleanR
+            ? 'right'
+            : cleanL
+              ? 'left'
+              : defaultColumnSide(items);
       commitColumn(items, side, clusterId);
     }
 
@@ -2795,11 +3681,25 @@ export function layoutMap(
         // 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)
+        const fits = (['right', 'left', 'above', 'below'] as const).filter(
+          (s) => inlineFits(p, w, s)
         );
-        if (side) pushInline(p, text, w, side);
-        else commitColumn(items, defaultColumnSide(items));
+        if (fits.length === 0) {
+          commitColumn(items, defaultColumnSide(items));
+          continue;
+        }
+        // Horizontal sides read best; fall to vertical only if neither flank
+        // fits. Among the pool, divert to a water-facing side when one exists
+        // (seaward coastal label); otherwise keep the right-first reading order.
+        const horiz = fits.filter((s) => s === 'right' || s === 'left');
+        const pool = horiz.length > 0 ? horiz : fits;
+        const score = (s: Side): number => openness(inlineRect(p, w, s));
+        const wet = pool.filter((s) => score(s) >= WATER_PREF * 0.5);
+        const side =
+          wet.length > 0
+            ? wet.reduce((b, s) => (score(s) > score(b) ? s : b))
+            : pool[0]!;
+        pushInline(p, text, w, side);
         continue;
       }
       // Gate (a): bounding-box diagonal over marker extents — a sprawling chain
@@ -2820,12 +3720,154 @@ export function layoutMap(
     // 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) =>
+      const cleanSides = (['right', 'left'] as const).filter((s) =>
         wouldColumnBeClean(items, s)
       );
+      const side =
+        cleanSides.length > 1
+          ? defaultColumnSide(items) // both clean → most open flank
+          : cleanSides[0];
       if (side) commitColumn(items, side);
       else items.forEach((o) => pushHidden(o.p));
     }
+
+    // ── Edge clearance (re-fit, first pass → re-run) ──
+    // The tight fit (FIT_PAD = 24px) can seat a POI — or its label (inline OR
+    // leader column) — hard against a side, off-canvas, or demoted to hover-only.
+    // Measure how far every POI dot AND every POI label crosses a comfort
+    // clearance line on each of the four sides, reserve the deepest intrusion per
+    // side as a band, and re-fit the whole map into the canvas MINUS those bands —
+    // the data (dots and labels together) slides inward so nothing hugs the frame.
+    // The clearance scales with the canvas (≈3% of the shorter axis, floored) so a
+    // big preview pane gets proportionally more breathing room than a thumbnail.
+    // Asymmetric and "just enough": only the crowded sides zoom out, the rest stay
+    // tight. A committed label's box is reconstructed from its baseline/anchor; a
+    // still-hidden (hover-only) label is measured at its IDEAL seaward position
+    // (its stored rect is clamped on-canvas and would read as no intrusion).
+    // Re-measured and accumulated each pass until nothing intrudes, capped at
+    // `MAX_CLEARANCE_PASSES` so a pathologically small canvas can't loop forever.
+    const clearancePass = opts._poiClearancePass ?? 0;
+    const MAX_CLEARANCE_PASSES = 4;
+    if (clearancePass < MAX_CLEARANCE_PASSES && pois.length > 0) {
+      const EDGE_CLEAR = POI_EDGE_CLEAR; // shared with the leader-column clamp
+      const capH = Math.floor(width * 0.3); // never starve the map for one wide name
+      const capV = Math.floor(height * 0.3);
+      const poiById2 = new Map(pois.map((p) => [p.id, p]));
+      let needLeft = 0;
+      let needRight = 0;
+      let needTop = 0;
+      let needBottom = 0;
+      // Dots first: a marker itself must clear every edge by the buffer, so a
+      // corner cluster is pulled bodily inward (its labels ride along).
+      // Top is measured against the canvas edge (y=0), NOT topPad: the title band
+      // (topPad) already separates content from the top, so a dot/label just under
+      // it is not "hugging the edge" — referencing topPad would shove every POI map
+      // down by the buffer for no reason.
+      for (const p of pois) {
+        needLeft = Math.max(needLeft, EDGE_CLEAR - (p.cx - p.r));
+        needRight = Math.max(needRight, p.cx + p.r + EDGE_CLEAR - width);
+        needTop = Math.max(needTop, EDGE_CLEAR - (p.cy - p.r));
+        needBottom = Math.max(needBottom, p.cy + p.r + EDGE_CLEAR - height);
+      }
+      for (const l of labels) {
+        if (l.poiId === undefined) continue;
+        const p = poiById2.get(l.poiId);
+        if (!p) continue;
+        // A leader-lined COLUMN (visible) or a hover-only HIDDEN label both want a
+        // seaward column beside the dot. Measuring their CLAMPED rect is useless —
+        // a column self-clamps to the edge (so it reads as no intrusion yet sits on
+        // the dots), and a hidden label's stored rect is clamped too. Instead
+        // reserve from the DOT so the column fits at its NATURAL seat (dot edge +
+        // COL_GAP + label width + buffer). This is dot-based, so it CONVERGES as
+        // the data slides in — unlike measuring the self-clamped label, which would
+        // never move off the edge. The column then seats beside the dots (no clamp,
+        // no overlap) and shows. COL_GAP matches the column layout's own gap.
+        if (l.hidden || l.leader) {
+          const lw = l.hidden
+            ? labelInfo(p).w
+            : measureLegendText(l.text, FONT);
+          const reach = p.r + COL_GAP + lw + EDGE_CLEAR;
+          if (p.cx >= width / 2)
+            needRight = Math.max(needRight, p.cx + reach - width);
+          else needLeft = Math.max(needLeft, reach - p.cx);
+          continue;
+        }
+        // Visible inline label: reconstruct its box from baseline + anchor and
+        // measure how far it crosses each clearance line (negative = inside).
+        const w = measureLegendText(l.text, FONT);
+        const boxLeft =
+          l.anchor === 'start'
+            ? l.x
+            : l.anchor === 'end'
+              ? l.x - w
+              : l.x - w / 2;
+        const boxTop = l.y - FONT / 3 - poiLabH / 2;
+        const boxRight = boxLeft + w;
+        const boxBottom = boxTop + poiLabH;
+        needLeft = Math.max(needLeft, EDGE_CLEAR - boxLeft);
+        needRight = Math.max(needRight, boxRight + EDGE_CLEAR - width);
+        needTop = Math.max(needTop, EDGE_CLEAR - boxTop);
+        needBottom = Math.max(needBottom, boxBottom + EDGE_CLEAR - height);
+      }
+      needLeft = Math.min(Math.max(0, Math.ceil(needLeft)), capH);
+      needRight = Math.min(Math.max(0, Math.ceil(needRight)), capH);
+      needTop = Math.min(Math.max(0, Math.ceil(needTop)), capV);
+      needBottom = Math.min(Math.max(0, Math.ceil(needBottom)), capV);
+      if (needLeft >= 1 || needRight >= 1 || needTop >= 1 || needBottom >= 1) {
+        // ADD the residual intrusion to the band already reserved (the measured
+        // positions already reflect prior bands, so `need` is what's still over the
+        // line) and re-fit. Accumulating — not max — is what makes a too-tight
+        // first shift converge on the next pass instead of stalling.
+        const prev = opts._calloutReserve;
+        const left = Math.min((prev?.left ?? 0) + needLeft, capH);
+        const right = Math.min((prev?.right ?? 0) + needRight, capH);
+        const top = Math.min((prev?.top ?? 0) + needTop, capV);
+        const bottom = Math.min((prev?.bottom ?? 0) + needBottom, capV);
+        return layoutMap(resolved, data, size, {
+          ...opts,
+          _poiClearancePass: clearancePass + 1,
+          _calloutReserve: {
+            ...(left > 0 && { left }),
+            ...(right > 0 && { right }),
+            ...(top > 0 && { top }),
+            ...(bottom > 0 && { bottom }),
+          },
+        });
+      }
+    }
+  }
+
+  // Region/orientation labels yield to POI labels (the subject). A region label
+  // whose footprint a visible POI label now overlaps is removed — the POI data
+  // owns that spot, and the region label is orientation that reads fine absent
+  // here (vs. crammed atop a dot). Done after POI placement because the region
+  // pass runs first and couldn't see where the POI labels would land. POI label
+  // rects are padded a touch so a near-touch also triggers the yield.
+  if (regionLabelGuards.length > 0) {
+    const PAD = 2;
+    const poiRects = labels
+      .filter((l) => l.poiId !== undefined && l.hidden !== true)
+      .map((l) => {
+        const w = measureLegendText(l.text, FONT);
+        const x =
+          l.anchor === 'start'
+            ? l.x
+            : l.anchor === 'end'
+              ? l.x - w
+              : l.x - w / 2;
+        return {
+          x: x - PAD,
+          y: l.y - FONT,
+          w: w + 2 * PAD,
+          h: FONT * 1.4 + 2 * PAD,
+        };
+      });
+    for (const g of regionLabelGuards) {
+      if (poiRects.some((pr) => rectsOverlap(pr, g.rect))) {
+        const i = labels.indexOf(g.label);
+        if (i >= 0) labels.splice(i, 1);
+      }
+    }
   }
 
   // -- Context labels (orientation backdrop, §24B). Placed DEAD LAST so they
@@ -2935,6 +3977,69 @@ export function layoutMap(
     labels.push(...contextLabels);
   }
 
+  // ── Subtle city dots (basemap orientation, §24B `no-cities`) ──
+  // A faint scatter of gazetteer cities for geographic context. Population-ranked
+  // and spacing-thinned: the min-pixel gap makes density adapt to zoom for free —
+  // at world scale only the biggest of a dense cluster (Europe) survive; zoomed
+  // into one country the same cities spread apart and more local ones fill in.
+  // Explicit POIs always win — a city dot never sits under a referenced marker.
+  //
+  // The ON-CANVAS projected-pixel test is the ONLY cull — NOT a lon/lat extent
+  // box. `resolved.extent` wraps the antimeridian for albers-usa whenever AK/HI
+  // are referenced (west lon > east lon), which a naive `lon<w||lon>e` box reads
+  // as "reject every mainland city" → an all-blank US map. The pixel test is
+  // projection-agnostic and antimeridian-safe, and it naturally includes the
+  // near-border neighbour cities the viewport actually shows.
+  const cityDots: MapLayoutCityDot[] = [];
+  if (resolved.directives.noCities !== true) {
+    const CITY_DOT_SPACING = 12; // min px between two dots (and dot↔POI)
+    const CITY_DOT_CAP = 220;
+    const SPACING_SQ = CITY_DOT_SPACING * CITY_DOT_SPACING;
+    // Radius scales with population on a log axis (pop spans ~50k → 37M, so a
+    // linear map would collapse everything but the megacities to one size). A
+    // metropolis reads as a slightly fatter dot; a small town stays a faint
+    // speck. Still decorative — the range is deliberately tight so the layer
+    // never competes with POIs.
+    const CITY_DOT_R_MIN = 0.7;
+    const CITY_DOT_R_MAX = 2.6;
+    const CITY_POP_MIN = 50_000; // ≤ this → R_MIN
+    const CITY_POP_MAX = 15_000_000; // ≥ this → R_MAX
+    const LOG_MIN = Math.log10(CITY_POP_MIN);
+    const LOG_SPAN = Math.log10(CITY_POP_MAX) - LOG_MIN;
+    const cityDotRadius = (pop: number): number => {
+      if (!(pop > CITY_POP_MIN)) return CITY_DOT_R_MIN;
+      const t = Math.min(1, (Math.log10(pop) - LOG_MIN) / LOG_SPAN);
+      return CITY_DOT_R_MIN + t * (CITY_DOT_R_MAX - CITY_DOT_R_MIN);
+    };
+    // Seed the occupancy set with explicit POI positions so dots dodge markers.
+    const placed: { x: number; y: number }[] = pois.map((p) => ({
+      x: p.cx,
+      y: p.cy,
+    }));
+    const sorted = [...data.gazetteer.cities].sort((a, b) => b[3] - a[3]);
+    for (const c of sorted) {
+      if (cityDots.length >= CITY_DOT_CAP) break;
+      const lat = c[0];
+      const lon = c[1];
+      const p = project(lon, lat);
+      if (!p) continue;
+      const [px, py] = p;
+      if (px < 0 || px > width || py < 0 || py > height) continue;
+      let tooClose = false;
+      for (const q of placed) {
+        const dx = q.x - px;
+        const dy = q.y - py;
+        if (dx * dx + dy * dy < SPACING_SQ) {
+          tooClose = true;
+          break;
+        }
+      }
+      if (tooClose) continue;
+      placed.push({ x: px, y: py });
+      cityDots.push({ cx: px, cy: py, r: cityDotRadius(c[3]) });
+    }
+  }
+
   return {
     width,
     height,
@@ -2949,6 +4054,7 @@ export function layoutMap(
     coastlineStyle,
     legs,
     pois,
+    cityDots,
     clusters,
     labels,
     legend,