@diagrammo/dgmo 0.33.0 → 0.35.0

package/src/map/layout.ts

@@ -41,7 +41,7 @@ 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';
+import { mapLegendBand, mapLegendBox } from './legend-band';
 import type { MapLayoutLegend } from './types';
 import type { DgmoError } from '../diagnostics';
 import type { BoundaryTopology } from './data/types';
@@ -811,41 +811,50 @@ export function countryLabelPositions(args: {
   };
   const dist2ToCentre = (c: Cell): number =>
     (c.sx - cx) ** 2 + (c.sy - cy) ** 2;
-  // Most-interior cell leads (tie → nearest the visible centroid).
-  const pool = [...kept];
-  pool.sort((a, b) => {
-    const d = interiorness(b) - interiorness(a);
-    return d !== 0 ? d : dist2ToCentre(a) - dist2ToCentre(b);
-  });
-  // grid ordering: best cell, then greedy max-min spread of the rest.
-  const ordered: Cell[] = [pool.shift()!];
-  while (ordered.length < MAX_COUNTRY_POSITIONS && pool.length) {
-    let bestIdx = 0;
-    let bestMin = -1;
-    for (let k = 0; k < pool.length; k++) {
-      const c = pool[k]!;
-      let minD = Infinity;
-      for (const o of ordered) {
-        const d = (c.sx - o.sx) ** 2 + (c.sy - o.sy) ** 2;
-        if (d < minD) minD = d;
-      }
-      if (minD > bestMin) {
-        bestMin = minD;
-        bestIdx = k;
-      }
-    }
-    ordered.push(pool.splice(bestIdx, 1)[0]!);
-  }
-  const grid = ordered.map((c) => ({
-    lonLat: [c.lon, c.lat] as [number, number],
-    screen: [c.sx, c.sy] as [number, number],
-  }));
-  // Curated anchor (D13): forced to slot 0; grid cells fill the rest.
+  // Center on the visible region FIRST (what a human does): the label's home is
+  // the centroid of the country's in-frame land. The caller tries positions in
+  // order and commits the first that clears every obstacle, so a well-centred
+  // anchor that's clear wins outright, and only an awkward case (a POI or the
+  // legend sitting on the centroid) falls back to the on-land grid cells — which
+  // are interior-first, NOT scattered to far corners. The centroid leads ONLY
+  // when it actually sits on the country's own land (so the on-land invariant
+  // holds); a concave country whose centroid lands off its body falls straight
+  // to the grid.
+  const centreLon = kept.reduce((s, c) => s + c.lon, 0) / kept.length;
+  const centreLat = kept.reduce((s, c) => s + c.lat, 0) / kept.length;
+  const centreScreen = project(centreLon, centreLat);
+  const lead =
+    pointInGeometry(geometry, centreLon, centreLat) &&
+    centreScreen &&
+    Number.isFinite(centreScreen[0]) &&
+    Number.isFinite(centreScreen[1]) &&
+    centreScreen[0] >= 0 &&
+    centreScreen[0] <= width &&
+    centreScreen[1] >= 0 &&
+    centreScreen[1] <= height
+      ? [
+          {
+            lonLat: [centreLon, centreLat] as [number, number],
+            screen: [centreScreen[0], centreScreen[1]] as [number, number],
+          },
+        ]
+      : [];
+  // On-land grid cells, most-interior first (tie → nearest the visible centroid).
+  const grid = [...kept]
+    .sort(
+      (a, b) =>
+        interiorness(b) - interiorness(a) || dist2ToCentre(a) - dist2ToCentre(b)
+    )
+    .map((c) => ({
+      lonLat: [c.lon, c.lat] as [number, number],
+      screen: [c.sx, c.sy] as [number, number],
+    }));
+  // Curated anchor (D13): forced to slot 0 when present (a trusted mainland
+  // point, e.g. Russia → European Russia).
   const curatedPos = curated
     ? mkCurated(curated, project)
     : ([] as { lonLat: [number, number]; screen: [number, number] }[]);
-  const out = [...curatedPos, ...grid].slice(0, MAX_COUNTRY_POSITIONS);
-  return out;
+  return [...curatedPos, ...lead, ...grid].slice(0, MAX_COUNTRY_POSITIONS);
 }
 
 /** Project a single curated lon/lat into the position-list shape (or [] when it
@@ -1484,6 +1493,40 @@ export function layoutMap(
         : FOREIGN_TINT_LIGHT
   );
 
+  // One muted, contrast-floored tone for every BACKDROP place name — orientation
+  // regions (Minnesota, Texas) AND unreferenced context countries (Canada) — plus
+  // one for water. Subordination is by MUTING (start from textMuted / a muted
+  // blue-gray), never by lowering contrast: blend toward palette.text until the
+  // tone clears the WCAG-AA floor against the substrate it sits on, so a backdrop
+  // name is always legible WITHOUT a halo. This replaces the old fade-toward-bg,
+  // which washed a grown name to ~background (Minnesota rendered at ~#dddfe0 over
+  // ~#e9ece9 land — contrast ≈ 1).
+  // Floored against EVERY light substrate a backdrop name may touch — its own
+  // neutral land AND open water — so the no-halo label stays legible even where a
+  // big country name (Florida, Chile) spills off its coast onto the sea. (The
+  // placement gate below still keeps these names off the only substrate the tone
+  // can't clear: a saturated foreign DATA fill.)
+  const contrastFloorTone = (tone: string, ...substrates: string[]): string => {
+    const clears = (t: string): boolean =>
+      substrates.every((s) => contrastRatio(t, s) >= REGION_LABEL_HALO_RATIO);
+    if (clears(tone)) return tone;
+    for (let s = 10; s <= 100; s += 10) {
+      const t = mix(palette.text, tone, s);
+      if (clears(t)) return t;
+    }
+    return palette.text;
+  };
+  const backdropLandTone = contrastFloorTone(
+    palette.textMuted,
+    neutralFill,
+    water
+  );
+  const backdropWaterTone = contrastFloorTone(
+    mix(palette.colors.blue, palette.textMuted, 50),
+    water,
+    neutralFill
+  );
+
   // -- Colorize: content-inferred distinct political fills (§24B) --
   // Colorize is the DEFAULT dress for any map that is NOT colouring regions by
   // data. The things that turn it off: (1) a data dimension exists on a
@@ -1695,6 +1738,43 @@ export function layoutMap(
     hasSubtitle: Boolean(resolved.subtitle),
   });
   if (legendBand > topPad) topPad = legendBand;
+  // The title and legend are foreground overlays in the top band. Capture their
+  // actual centred boxes so EVERY on-map label (region, data, context) treats
+  // them as obstacles and dodges to clear space — otherwise a neighbour name
+  // creeps up under the title (Canada on a US map). These are centred boxes, NOT
+  // the full-width band, so a label can still sit in a clear top corner (a water
+  // name, or Canada beside the title) rather than being shoved off its own land.
+  const topReserved: LabelRect[] = [];
+  if (shownTitle) {
+    const lines = resolved.subtitle ? 2 : 1;
+    const tw =
+      Math.max(
+        measureLegendText(shownTitle, TITLE_FONT_SIZE),
+        resolved.subtitle
+          ? measureLegendText(resolved.subtitle, TITLE_FONT_SIZE)
+          : 0
+      ) +
+      2 * TITLE_FONT_SIZE; // breathing room around the centred banner
+    topReserved.push({
+      x: width / 2 - tw / 2,
+      y: TITLE_Y - TITLE_FONT_SIZE,
+      w: tw,
+      h: TITLE_FONT_SIZE * (lines + 0.5),
+    });
+  }
+  const legendBox = mapLegendBox(legend, {
+    width,
+    mode: opts.legendMode ?? 'preview',
+    hasTitle: Boolean(shownTitle),
+    hasSubtitle: Boolean(resolved.subtitle),
+  });
+  if (legendBox)
+    topReserved.push({
+      x: legendBox.x,
+      y: legendBox.y,
+      w: legendBox.width,
+      h: legendBox.height,
+    });
   // 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.
@@ -2892,6 +2972,30 @@ export function layoutMap(
     const by = b.cy - ((b.cy - py) / tb) * trimB;
     return `M${ax},${ay}Q${px},${py} ${bx},${by}`;
   };
+  // Where a leg's label sits: the MIDPOINT OF THE DRAWN PATH, nudged a few px to
+  // the bow side so the text rides just off the line. A straight leg's midpoint is
+  // the chord midpoint; an arc is a quadratic Q whose t=0.5 point is
+  // chord-mid + ½·normal·bow — so a long bowed arc (a trans-Atlantic route) must
+  // follow the CURVE, else the label floats in open space far below the line.
+  const legLabelPoint = (
+    a: { cx: number; cy: number; r: number },
+    b: { cx: number; cy: number; r: number },
+    curved: boolean,
+    offset: number
+  ): { x: number; y: number } => {
+    const mx = (a.cx + b.cx) / 2;
+    const my = (a.cy + b.cy) / 2;
+    if (!curved && offset === 0) return { x: mx, y: my - 4 };
+    const dx = b.cx - a.cx;
+    const dy = b.cy - a.cy;
+    const len = Math.hypot(dx, dy) || 1;
+    const nx = -dy / len;
+    const ny = dx / len;
+    const bow = offset !== 0 ? offset : len * ARC_CURVE_FRAC;
+    // arc apex (½·bow) + a small lift further out so the text clears the stroke.
+    const off = bow * 0.5 + Math.sign(bow || 1) * 8;
+    return { x: mx + nx * off, y: my + ny * off };
+  };
 
   // Routes: each leg is an edge (fromId → toId) carrying its own label,
   // value→thickness, and arc shape. Loop-closing legs are explicit in `rt.legs`;
@@ -2912,13 +3016,12 @@ export function layoutMap(
       const a = poiScreen.get(leg.fromId);
       const b = poiScreen.get(leg.toId);
       if (!a || !b) continue;
-      const mx = (a.cx + b.cx) / 2;
-      const my = (a.cy + b.cy) / 2;
+      const lp = legLabelPoint(a, b, leg.style === 'arc', 0);
       const bow = {
         curved: leg.style === 'arc',
         offset: 0,
-        labelX: mx,
-        labelY: my - 4,
+        labelX: lp.x,
+        labelY: lp.y,
       };
       const routeLabelStyle =
         leg.label !== undefined
@@ -2972,13 +3075,13 @@ export function layoutMap(
       const b = poiScreen.get(e.toId);
       if (!a || !b) return;
       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 curved = e.style === 'arc' || n > 1;
+      const lp = legLabelPoint(a, b, curved, fanOffset);
       const bow = {
-        curved: e.style === 'arc' || n > 1,
+        curved,
         offset: fanOffset,
-        labelX: mx,
-        labelY: my - 4,
+        labelX: lp.x,
+        labelY: lp.y,
       };
       const edgeLabelStyle =
         e.label !== undefined
@@ -3007,7 +3110,9 @@ export function layoutMap(
 
   // -- Labels: regions + POIs with escalation (AR5) --
   const labels: PlacedLabel[] = [];
-  const obstacles: LabelRect[] = [];
+  // Seed with the title + legend boxes so every label (region, POI, context)
+  // collides against them and never lands under the title/legend overlay.
+  const obstacles: LabelRect[] = [...topReserved];
   // 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
@@ -3066,6 +3171,14 @@ export function layoutMap(
   // ocean. At the compact breakpoint (decision D2) the abbreviation is preferred
   // FIRST for US states.
   const showRegionLabels = resolved.directives.noRegionLabels !== true;
+  // Ids of regions that won a static on-map label in the region pass. The
+  // unreferenced-country / framed-state context pass below excludes these so a
+  // region named once is never named twice: the layout `regions` list carries
+  // auto-added poiFrameContainers (e.g. Canada framing northern POIs) that are
+  // NOT in `regionById` (which holds only user-referenced `resolved.regions`),
+  // so `regionById.has(iso)` alone misses them and the context pass would
+  // re-label the same country at a different anchor (the "double-Canada" bug).
+  const labeledRegionIds = new Set<string>();
   // 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
@@ -3128,7 +3241,12 @@ export function layoutMap(
   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
+  // A valueless SUBJECT (referenced, no metric) grows up to this ceiling in-shape;
+  // if it can't host its name at least at the prominence FLOOR inside its own fill
+  // (a thin ribbon like Chile), it leaders into the open space instead.
+  const SUBJECT_FONT_MAX = 18; // px ceiling for a prominent in-shape subject name
+  const SUBJECT_MIN_PROMINENCE = 13; // px floor below which a subject leaders out
+  const SUBJECT_LEADER_FONT = 15; // px for a leadered subject chip (Chile in the sea)
   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;
@@ -3149,7 +3267,7 @@ export function layoutMap(
     lineNumber: number,
     valueLine?: string,
     fontSize: number = FONT,
-    fade: number = 0
+    colorOverride?: string
   ): 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
@@ -3162,9 +3280,12 @@ export function layoutMap(
     // fills: if any extreme lands on a fill other than the region's own, the
     // label overflows and earns a halo.
     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;
+    // A backdrop label passes an explicit muted, contrast-floored tone
+    // (`backdropLandTone`); subordination is by muting, NOT by fading toward bg
+    // (which destroyed contrast — the old REGION_FADE_ORIENT washed Minnesota to
+    // ~background). Data labels pass no override and keep the contrast-picked-
+    // vs-fill colour.
+    const color = colorOverride ?? 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.
@@ -3183,7 +3304,11 @@ export function layoutMap(
       text,
       anchor: 'middle',
       color,
-      halo: overflows,
+      // A backdrop label (colorOverride) NEVER haloes: the placement gate above
+      // guarantees it sits on a floored-readable substrate (own fill, neutral
+      // land, foreign land, or water), so a halo is pure noise. Data labels keep
+      // the containment-gated halo until the role-tier pass (Phase 3).
+      halo: colorOverride ? false : overflows,
       haloColor,
       ...(fontSize !== FONT && { fontSize }),
       ...(valueLine !== undefined && { valueLine }),
@@ -3263,7 +3388,9 @@ 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[] = [];
+    // Seed with the title + legend boxes (via fitsRegions) so region/data labels
+    // dodge the overlay the same way context labels do (through `obstacles`).
+    const placedRegionRects: LabelRect[] = [...topReserved];
     // Leaders already drawn (region short-hop callouts). A new short-hop leader
     // that would cross any of these is rejected — crossing leaders read as
     // spaghetti, so the label is dropped instead (the shading + legend + hover
@@ -3316,15 +3443,18 @@ export function layoutMap(
       cy: number,
       fill: string,
       name: string,
-      value: string | undefined
+      value: string | undefined,
+      font: number = FONT,
+      gap: number = HOP_GAP,
+      maxLen: number = SHORT_HOP_MAX
     ): {
       x: number;
       y: number;
       rect: LabelRect;
       leader: [number, number, number, number];
     } | null => {
-      const chipW = stackW(name, value);
-      const chipH = stackH(value !== undefined);
+      const chipW = stackW(name, value, font);
+      const chipH = stackH(value !== undefined, font);
       const dirs: Array<[number, number]> = [
         [0, -1], // north (over Canada)
         [0, 1], // south (over Mexico / Gulf)
@@ -3344,7 +3474,7 @@ export function layoutMap(
         let ex = cx;
         let ey = cy;
         let steps = 0;
-        const maxSteps = Math.ceil(SHORT_HOP_MAX / STEP) + 1;
+        const maxSteps = Math.ceil(maxLen / STEP) + 1;
         while (steps < maxSteps && fillAt(ex, ey) === fill) {
           ex += dx * STEP;
           ey += dy * STEP;
@@ -3353,8 +3483,8 @@ export function layoutMap(
         if (fillAt(ex, ey) === fill) continue; // never left the region in reach
         // Chip centre sits a gap + half-extent beyond the border along the dir.
         const halfAlong = (Math.abs(dx) * chipW + Math.abs(dy) * chipH) / 2;
-        const ccx = ex + dx * (HOP_GAP + halfAlong);
-        const ccy = ey + dy * (HOP_GAP + halfAlong);
+        const ccx = ex + dx * (gap + halfAlong);
+        const ccy = ey + dy * (gap + halfAlong);
         const rect: LabelRect = {
           x: ccx - chipW / 2,
           y: ccy - chipH / 2,
@@ -3390,7 +3520,7 @@ export function layoutMap(
         const innerX = ccx - dx * (chipW / 2);
         const innerY = ccy - dy * (chipH / 2);
         const len = Math.hypot(innerX - cx, innerY - cy);
-        if (len > SHORT_HOP_MAX) continue;
+        if (len > maxLen) continue;
         if (
           placedLeaders.some((l) =>
             segmentsCross(cx, cy, innerX, innerY, l[0], l[1], l[2], l[3])
@@ -3418,6 +3548,117 @@ export function layoutMap(
     };
     for (const { r, c, boxW, boxH, candidates } of entries) {
       const valStr = regionValueStr(r.value);
+      // vs other placed REGION labels (full stack) / vs POI obstacles (name only)
+      // — defined up here so the subject pre-pass below can reuse them.
+      const fitsRegions = (rect: LabelRect): boolean =>
+        !placedRegionRects.some((p) => rectsOverlap(rect, p));
+      const fitsPois = (rect: LabelRect): boolean =>
+        !poiObstacles.some((o) => rectsOverlap(rect, o));
+      // A SUBJECT is a user-referenced region (the thing the map is ABOUT —
+      // `regionById` holds only `resolved.regions`, so an auto-added
+      // poiFrameContainer is NOT a subject). A subject must read prominently and
+      // NEVER drop: a thin ribbon (Chile) whose centroid sits on a sliver doesn't
+      // stamp a cramped name there — it leaders into the open space beside it.
+      const isSubject = regionById.has(r.id);
+      // Both horizontal extremes of `text` (centred at ax,ay, base font) land on
+      // the region's own fill — true in-shape containment. Gates a DATA label's
+      // in-place placement so a name that would spill off its own choropleth fill
+      // onto a neighbour (where its fill-picked colour is illegible) leaders out
+      // instead — which is what lets the data label drop its halo (it can no
+      // longer overflow, so `overflows` is false and no rescue stroke is drawn).
+      const extremesOnFill = (
+        ax: number,
+        ay: number,
+        text: string
+      ): boolean => {
+        const halfW = measureLegendText(text, FONT) / 2;
+        return (
+          fillAt(ax - halfW, ay) === r.fill && fillAt(ax + halfW, ay) === r.fill
+        );
+      };
+      // ── Valueless SUBJECT: prominent in-shape, else leader (the Chile case) ──
+      // A user-referenced region with no metric is the map's point and must read
+      // PROMINENTLY. Find the largest font (up to a cap) whose full name sits
+      // wholly inside the region's own fill at the centroid AND clears every
+      // obstacle (other labels, POI markers, route arcs). If that best size meets
+      // the prominence floor, place it there in full contrast. If the shape is too
+      // thin/small to host a prominent name even at the floor — a ribbon like Chile
+      // whose centroid is a sliver — fall through to a leader that carries the
+      // full name into the open space beside it. A subject NEVER drops.
+      if (isSubject && valStr === undefined && r.label !== undefined) {
+        const name = candidates[0]!; // subjects use the full name, never an abbrev
+        let best = -1;
+        for (let f = SUBJECT_FONT_MAX; f >= FONT; f--) {
+          if (measureLegendText(name, f) > boxW || f + 2 * LABEL_PADY > boxH)
+            continue;
+          const rect = regionLabelRect(c[0], c[1], name, undefined, f);
+          if (!fitsRegions(rect) || !fitsPois(rect) || collides(rect)) continue;
+          const halfW = measureLegendText(name, f) / 2;
+          if (
+            fillAt(c[0] - halfW, c[1]) !== r.fill ||
+            fillAt(c[0] + halfW, c[1]) !== r.fill
+          )
+            continue;
+          best = f;
+          break;
+        }
+        if (best >= SUBJECT_MIN_PROMINENCE) {
+          const rect = regionLabelRect(c[0], c[1], name, undefined, best);
+          placedRegionRects.push(rect);
+          pushRegionLabel(
+            c[0],
+            c[1],
+            name,
+            r.fill,
+            r.lineNumber,
+            undefined,
+            best
+          );
+          labeledRegionIds.add(r.id);
+          regionLabelGuards.push({ label: labels[labels.length - 1]!, rect });
+        } else {
+          // The shape can't host a prominent name (Chile's ribbon) → leader the
+          // name into the open space beside it at a PROMINENT size, pushed well
+          // clear of the coast (a larger gap + reach) so it reads as the subject,
+          // not a cramped afterthought.
+          const hop = tryShortHopCallout(
+            c[0],
+            c[1],
+            r.fill,
+            r.label,
+            undefined,
+            SUBJECT_LEADER_FONT,
+            HOP_GAP + SUBJECT_LEADER_FONT,
+            SHORT_HOP_MAX * 2.2
+          );
+          if (hop) {
+            placedRegionRects.push(hop.rect);
+            placedLeaders.push(hop.leader);
+            const dark = mix(r.fill, palette.text, 60);
+            labels.push({
+              x: hop.x,
+              y: hop.y,
+              text: r.label,
+              anchor: 'middle',
+              color: palette.text,
+              halo: false,
+              haloColor: palette.bg,
+              fontSize: SUBJECT_LEADER_FONT,
+              leader: {
+                x1: hop.leader[0],
+                y1: hop.leader[1],
+                x2: hop.leader[2],
+                y2: hop.leader[3],
+              },
+              leaderColor: dark,
+              calloutDot: { x: c[0], y: c[1], color: dark },
+              lineNumber: r.lineNumber,
+            });
+            labeledRegionIds.add(r.id);
+          }
+        }
+        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;
@@ -3434,10 +3675,6 @@ export function layoutMap(
       //    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
@@ -3473,13 +3710,23 @@ export function layoutMap(
           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)) {
+            if (
+              fitsRegions(stackRect) &&
+              fitsPois(nameRect) &&
+              extremesOnFill(a.x, a.y, t)
+            ) {
               chosen = { text: t, valueLine: valStr, ax: a.x, ay: a.y };
               break;
             }
           }
           if (labelW(t) <= boxW && labelH <= boxH) {
-            if (fitsRegions(nameRect) && fitsPois(nameRect)) {
+            // A data label must sit inside its own choropleth fill (so it can drop
+            // the halo); a context/container label keeps the looser bbox fit.
+            if (
+              fitsRegions(nameRect) &&
+              fitsPois(nameRect) &&
+              (valStr === undefined || extremesOnFill(a.x, a.y, t))
+            ) {
               chosen = { text: t, ax: a.x, ay: a.y };
               break;
             }
@@ -3487,22 +3734,23 @@ export function layoutMap(
         }
         if (chosen) break;
       }
-      if (chosen === undefined && valStr && r.label !== undefined) {
-        // A VALUED region whose name won't fit in place (even abbreviated). Rather
-        // than overflow onto neighbours (illegible) or fire a long leader to a
-        // margin column (spaghetti), nudge the FULL name+value chip a short hop
-        // into the open space right beside it — north over Canada, south over
-        // Mexico, out to sea — joined by a tiny non-crossing leader. If no
-        // direction has clean adjacent room within reach, the region simply gets
-        // no static label: the choropleth shading + legend carry it and hover
-        // reveals the name+value. A readable blank beats a crammed tangle.
+      if (chosen === undefined && r.label !== undefined && isSubject) {
+        // A SUBJECT whose name won't sit inside its own shape — a thin ribbon
+        // (Chile) or a small valued region crowded by a POI. Rather than overflow
+        // onto neighbours (illegible) or fire a long leader to a margin column
+        // (spaghetti), nudge the FULL name(+value) chip a short hop into the open
+        // space right beside it — out to sea, north over Canada, south over Mexico
+        // — joined by a tiny non-crossing leader. A subject is the map's point, so
+        // it gets this leader whether or not it carries a value. If no direction
+        // has clean adjacent room within reach, the region gets no static label
+        // (the shading/legend + hover carry it); a readable blank beats a tangle.
         const hop = tryShortHopCallout(c[0], c[1], r.fill, r.label, valStr);
         if (hop) {
           placedRegionRects.push(hop.rect);
           placedLeaders.push(hop.leader);
-          // Chip sits on base land / water of unpredictable tone → palette text
-          // + halo (matches the old column chips). The leader/dot are tinted from
-          // the region's own fill (darkened for contrast) to tie line to region.
+          // Chip sits on empty land / water (the callout only seats on isEmptyFill)
+          // → palette text, NO halo (full-contrast dark/light text reads cleanly on
+          // the light basemap; the leader + dot tie the line back to the region).
           const dark = mix(r.fill, palette.text, 60);
           labels.push({
             x: hop.x,
@@ -3510,9 +3758,9 @@ export function layoutMap(
             text: r.label,
             anchor: 'middle',
             color: palette.text,
-            halo: true,
+            halo: false,
             haloColor: palette.bg,
-            valueLine: valStr,
+            ...(valStr !== undefined && { valueLine: valStr }),
             leader: {
               x1: hop.leader[0],
               y1: hop.leader[1],
@@ -3523,6 +3771,7 @@ export function layoutMap(
             calloutDot: { x: c[0], y: c[1], color: dark },
             lineNumber: r.lineNumber,
           });
+          labeledRegionIds.add(r.id);
         }
         continue;
       }
@@ -3538,19 +3787,31 @@ export function layoutMap(
       // 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.
+        // A backdrop name carries NO halo, so it must sit cleanly at whatever size
+        // it takes. Try the desired (footprint-grown) size DOWN TO the base font;
+        // at each, the name must fit the box, clear neighbours/POIs/route arcs
+        // (`collides` adds the arc segments `fitsPois` misses), AND have both
+        // horizontal extremes on a floored-readable substrate — its own fill, or
+        // empty land/water (neutral/foreign/sea). The only thing it must NOT cross
+        // is a saturated foreign DATA fill, where the muted floored tone is
+        // illegible and there's no halo to rescue it. If nothing — not even the
+        // base font — sits clean, the label is DROPPED (the basemap shading +
+        // hover carry the region); a readable blank beats an unreadable name.
+        const extremesClean = (f: number): boolean => {
+          const halfW = measureLegendText(chosen.text, f) / 2;
+          return [chosen.ax - halfW, chosen.ax + halfW].every((sx) => {
+            const fAt = fillAt(sx, chosen.ay);
+            return fAt === r.fill || isEmptyFill(fAt);
+          });
+        };
+        let fit = -1;
+        for (let f = desiredFont; f >= FONT; f--) {
           if (
             stackW(chosen.text, chosen.valueLine, f) > boxW ||
             stackH(hasVal, f) > boxH
@@ -3570,17 +3831,24 @@ export function layoutMap(
             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
-          )
+          if (!fitsRegions(gRect) || !fitsPois(gName) || collides(gName))
             continue;
-          font = f;
+          if (!extremesClean(f)) continue;
+          fit = f;
           break;
         }
-        fade = font > FONT ? Math.round(growT * REGION_FADE_ORIENT) : 0;
+        if (fit < 0) {
+          // A POI-frame CONTAINER is the map's subject (its headline name) — it
+          // must never drop, so it falls back to the base font even when no size
+          // sits perfectly clean (the floored tone keeps it legible). A mere
+          // backdrop NEIGHBOUR with no clean placement is dropped: the basemap
+          // shading + hover carry it, and a readable blank beats a name crammed
+          // onto an arc or a foreign data fill.
+          if (!frameContainers.has(r.id)) continue;
+          font = FONT;
+        } else {
+          font = fit;
+        }
       }
       const rRect = regionLabelRect(
         chosen.ax,
@@ -3598,8 +3866,9 @@ export function layoutMap(
         r.lineNumber,
         chosen.valueLine,
         font,
-        fade
+        isOrient ? backdropLandTone : undefined
       );
+      labeledRegionIds.add(r.id);
       // Guard so a POI label landing here later makes this label yield (below).
       regionLabelGuards.push({
         label: labels[labels.length - 1]!,
@@ -3620,6 +3889,7 @@ export function layoutMap(
         seed.lineNumber,
         valStr
       );
+      labeledRegionIds.add(seed.iso);
       regionLabelGuards.push({
         label: labels[labels.length - 1]!,
         rect: regionLabelRect(seed.x, seed.y, text, valStr),
@@ -4329,17 +4599,39 @@ export function layoutMap(
       const nx = -dy / len;
       const ny = dx / len; // unit normal to the chord
       const perp = labelH + 2;
-      // Stay ON the line first (slide along the chord), then escalate to a
-      // perpendicular hop — growing — so a label on a SHORT leg between two close
-      // dots (where every on-chord slot straddles an endpoint) can still escape
-      // clear above or below the line.
+      // Walk the ACTUAL DRAWN PATH, not the chord: parse the leg's `d` (the
+      // trimmed `M…Q…` arc or `M…L…` line) and sample the curve at each t, so a
+      // label rides its own bowed line instead of floating at the chord midpoint
+      // out in open space (the trans-Atlantic arc case). The perpendicular hop
+      // uses the chord normal, which is close enough to nudge a label clear.
+      const pm =
+        /^M(-?[\d.]+),(-?[\d.]+)(?:L(-?[\d.]+),(-?[\d.]+)|Q(-?[\d.]+),(-?[\d.]+) (-?[\d.]+),(-?[\d.]+))$/.exec(
+          lg.d
+        );
+      const pointAt = (t: number): [number, number] => {
+        if (pm?.[5] !== undefined) {
+          const u = 1 - t;
+          return [
+            u * u * +pm[1]! + 2 * u * t * +pm[5]! + t * t * +pm[7]!,
+            u * u * +pm[2]! + 2 * u * t * +pm[6]! + t * t * +pm[8]!,
+          ];
+        }
+        if (pm?.[3] !== undefined)
+          return [
+            +pm[1]! + (+pm[3]! - +pm[1]!) * t,
+            +pm[2]! + (+pm[4]! - +pm[2]!) * t,
+          ];
+        return [a.cx + dx * t, a.cy + dy * t];
+      };
+      // Stay ON the line first (slide along it), then escalate to a perpendicular
+      // hop — growing — so a label on a SHORT leg between two close dots (where
+      // every on-line slot straddles an endpoint) can still escape above or below.
       const candidates: Array<[number, number]> = [];
       for (const off of [0, perp, -perp, 2 * perp, -2 * perp])
-        for (const t of T_LIST)
-          candidates.push([
-            a.cx + dx * t + nx * off,
-            a.cy + dy * t + ny * off - 4,
-          ]);
+        for (const t of T_LIST) {
+          const [bx, by] = pointAt(t);
+          candidates.push([bx + nx * off, by + ny * off - 4]);
+        }
       const clean = ([cx, cy]: [number, number]): boolean => {
         const rect = { x: cx - w / 2, y: cy - labelH / 2, w, h: labelH };
         if (
@@ -4354,10 +4646,8 @@ export function layoutMap(
         if (placedEdge.some((o) => rectsOverlap(o, rect))) return false;
         return true;
       };
-      const [cx, cy] = candidates.find(clean) ?? [
-        a.cx + dx * 0.5,
-        a.cy + dy * 0.5 - 4,
-      ];
+      const mid = pointAt(0.5);
+      const [cx, cy] = candidates.find(clean) ?? [mid[0], mid[1] - 4];
       const style = labelOnFill(fillAt(cx, cy));
       // MapLayoutLeg fields are readonly — replace the entry with an updated copy.
       legs[i] = {
@@ -4419,7 +4709,7 @@ export function layoutMap(
     const rawCountries: RawCountry[] = [];
     for (const f of worldLayer.values()) {
       const iso = typeof f.id === 'string' ? f.id : String(f.id ?? '');
-      if (!iso || regionById.has(iso)) continue;
+      if (!iso || regionById.has(iso) || labeledRegionIds.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.
@@ -4536,7 +4826,7 @@ export function layoutMap(
     );
     if (usLayer && framedStateContainers) {
       for (const [iso, f] of usLayer) {
-        if (regionById.has(iso)) continue;
+        if (regionById.has(iso) || labeledRegionIds.has(iso)) continue;
         const viewF = cullFeatureToView(f);
         if (!viewF) continue; // not in frame
         const b = path.bounds(viewF as never) as [
@@ -4563,6 +4853,11 @@ export function layoutMap(
       waterBodies: data.waterBodies,
       countries: countryCandidates,
       palette,
+      // One muted, contrast-floored tone shared with the orientation backdrop
+      // (region pass) so a context country (Canada) and an orientation region
+      // (Minnesota) read identically — never below the WCAG-AA floor, no fade.
+      countryTone: backdropLandTone,
+      waterTone: backdropWaterTone,
       project,
       collides,
       contentPoints,