@diagrammo/dgmo 0.30.0 → 0.32.0

package/src/map/context-labels.ts

@@ -34,6 +34,13 @@ export interface CountryCandidate {
    *  bypasses the both-axes smear gate (its full-canvas bbox is an antimeridian
    *  artifact, not a real footprint, so the unreliable-centroid concern is moot). */
   readonly curatedAnchor?: boolean;
+  /** Ordered interior placement positions (screen coords), best-first: the commit
+   *  loop tries each in turn and places at the first that clears all collisions, so
+   *  a country can dodge a data cluster onto open ground on its own land
+   *  (map-context-neighbor-labels, D7/D12). INVARIANT: either ABSENT or NON-EMPTY,
+   *  and `anchor === positions[0]` always (an empty array is illegal — F7).
+   *  Absent ⇒ single-anchor behaviour (`positions ?? [anchor]`). */
+  readonly positions?: readonly (readonly [number, number])[];
 }
 
 export interface ContextLabelArgs {
@@ -48,6 +55,13 @@ export interface ContextLabelArgs {
   readonly project: (lon: number, lat: number) => [number, number] | null;
   /** Collision test against every committed data/region/POI/route obstacle. */
   readonly collides: (rect: LabelRect) => boolean;
+  /** Screen positions of the diagram's CONTENT (POI markers / data points). When
+   *  non-empty, country candidates rank by proximity to the NEAREST point (not a
+   *  centroid — a centroid is dragged off by outlying POIs and pulls in irrelevant
+   *  giants) so a thin budget labels the countries adjacent to the story (Belarus,
+   *  Poland) rather than far-corner giants (Kazakhstan). Empty/absent ⇒ the legacy
+   *  area-descending rank (map-context-neighbor-labels, proximity knob). */
+  readonly contentPoints?: readonly (readonly [number, number])[] | undefined;
   /** True when the screen point sits over LAND (a country/state fill) rather than
    *  open water. WATER labels are rejected when their footprint touches land — an
    *  ocean name belongs over the ocean (they're optional orientation aids, so drop
@@ -76,6 +90,15 @@ const COUNTRY_SIZE_FRAC_MIN = 0.06; // footprint linear-frac at base font
 const COUNTRY_SIZE_FRAC_MAX = 0.32; // footprint linear-frac at max font
 const COUNTRY_FADE_MAX = 45; // % blend toward bg at max font (subdue big names)
 
+// Multi-position country dodging (map-context-neighbor-labels). A country gets
+// several interior on-its-own-land positions so its label can dodge a colliding
+// data cluster into open space instead of being dropped. Layout generates the
+// positions (geo work stays in layout); the commit loop below walks them
+// best-first and places at the first that clears all collisions.
+export const MAX_COUNTRY_POSITIONS = 4; // ordered positions per country (cap; D7/D15)
+export const COUNTRY_POS_GRID = 5; // lon/lat sampling grid resolution N (N×N cells; D9)
+export const COUNTRY_POS_TOPN_MARGIN = 3; // generate positions for top budget+margin (D15)
+
 // Water-kind priority within a tier (oceans first, then seas, then the rest) so
 // a thin budget always spends on the highest-orientation-value names.
 const KIND_ORDER: Record<WaterKind, number> = {
@@ -107,12 +130,18 @@ export function labelBudget(
   band: TierBand
 ): number {
   const bandCap: Record<TierBand, number> = {
-    world: 7,
-    continental: 6,
-    regional: 5,
-    local: 4,
+    world: 10,
+    continental: 9,
+    regional: 7,
+    local: 6,
   };
-  const area = Math.floor(Math.sqrt(Math.max(0, width * height)) / 150);
+  // Area divisor lowered 150→105 (map-context-neighbor-labels, budget knob): the
+  // old budget was so thin a regional view spent every slot on a couple of giant
+  // landmasses, leaving the countries that ring the story unlabeled. The lower
+  // divisor + raised band caps roughly +50% the slots so the proximity rank has
+  // room to surface the neighbourhood. Still floors to ~1 on a thumbnail / 0 on a
+  // tiny canvas (AC9).
+  const area = Math.floor(Math.sqrt(Math.max(0, width * height)) / 105);
   return Math.max(0, Math.min(area, bandCap[band]));
 }
 
@@ -217,6 +246,22 @@ function rectAround(
   return { x: cx - w / 2, y: cy - h / 2, w, h };
 }
 
+/** Squared distance from point (px,py) to an axis-aligned bbox [x0,y0,x1,y1]; 0
+ *  when the point is inside. Used to rank country candidates by how close their
+ *  footprint reaches to the diagram's content centre (proximity knob). */
+function rectDist2(
+  px: number,
+  py: number,
+  x0: number,
+  y0: number,
+  x1: number,
+  y1: number
+): number {
+  const dx = Math.max(x0 - px, 0, px - x1);
+  const dy = Math.max(y0 - py, 0, py - y1);
+  return dx * dx + dy * dy;
+}
+
 function rectFits(r: LabelRect, width: number, height: number): boolean {
   return r.x >= 0 && r.y >= 0 && r.x + r.w <= width && r.y + r.h <= height;
 }
@@ -244,6 +289,7 @@ export function placeContextLabels(args: ContextLabelArgs): PlacedLabel[] {
     palette,
     project,
     collides,
+    contentPoints,
     overLand,
   } = args;
 
@@ -276,6 +322,9 @@ export function placeContextLabels(args: ContextLabelArgs): PlacedLabel[] {
     color: string;
     fontSize: number;
     sort: number; // priority key (lower first)
+    // Ordered dodge positions (screen coords), best-first. Absent on water (single
+    // anchor); on a country, mirrors CountryCandidate.positions (anchor === [0]).
+    positions?: readonly (readonly [number, number])[];
   };
   const candidates: Candidate[] = [];
 
@@ -360,18 +409,39 @@ export function placeContextLabels(args: ContextLabelArgs): PlacedLabel[] {
     });
   }
 
-  // -- Country candidates (unreferenced; biggest projected area first) --
-  // Rank by screen bbox area; keep only those whose name fits the footprint
-  // (width-fit, like region-labels) and whose anchor projects inside the view.
+  // -- Country candidates (unreferenced) --
+  // Rank PROXIMITY-FIRST when a content centre is known: the countries that ring
+  // the diagram's story should win the thin budget, not whichever giants happen to
+  // be biggest in frame (Kazakhstan/Sweden on a Ukraine map). The rank's anchor is
+  // the candidate's primary position (`positions[0]` === `anchor`). Without a
+  // content centre, fall back to the legacy biggest-area-first rank. Area is still
+  // computed (it drives the font/fade ramp and the smear gate below).
   const ranked = countries
     .map((c) => {
       const [x0, y0, x1, y1] = c.bbox;
       const w = x1 - x0;
       const h = y1 - y0;
-      return { c, w, h, area: w * h };
+      // Distance from the NEAREST content point to the country's FOOTPRINT (0 if a
+      // point is inside the bbox, else squared distance to the nearest edge). Edge
+      // distance — not centroid distance — so a large neighbour that REACHES toward
+      // the action (Poland) outranks a tiny country merely near a point (the
+      // Baltics), with no size-weighting constant; nearest-point — not a single
+      // centroid — so an outlying POI doesn't drag the rank toward distant giants.
+      let dist = Infinity;
+      if (contentPoints?.length) {
+        for (const p of contentPoints) {
+          const d = rectDist2(p[0], p[1], x0, y0, x1, y1);
+          if (d < dist) dist = d;
+        }
+      }
+      return { c, w, h, area: w * h, dist };
     })
     .filter((r) => Number.isFinite(r.area) && r.area > 0)
-    .sort((a, b) => b.area - a.area);
+    .sort((a, b) =>
+      contentPoints?.length
+        ? a.dist - b.dist || b.area - a.area // nearest the story first; area breaks ties
+        : b.area - a.area
+    );
   // Canvas linear extent — the denominator for the footprint size ramp below.
   const canvasLinear = Math.sqrt(Math.max(1, width * height));
   let ci = 0;
@@ -406,7 +476,14 @@ export function placeContextLabels(args: ContextLabelArgs): PlacedLabel[] {
     );
     const fontSize = Math.round(FONT + t * (COUNTRY_FONT_MAX - FONT));
     const fade = Math.round(t * COUNTRY_FADE_MAX);
-    const color = fade > 0 ? mix(countryColor, palette.bg, fade) : countryColor;
+    // Blend `fade`% TOWARD the bg (subdue big names). `mix(a,b,pct)` weights `a` by
+    // `pct`, so the bg fraction must be `100 - fade` — i.e. a small country (fade≈0)
+    // stays fully muted/dark and only a big landmass fades to a soft backdrop. (The
+    // earlier `mix(countryColor, bg, fade)` was inverted: it lightened the SMALL
+    // names toward white instead, which read as illegible once proximity started
+    // surfacing small neighbours like Belarus/Georgia.)
+    const color =
+      fade > 0 ? mix(countryColor, palette.bg, 100 - fade) : countryColor;
     // Always the full country name — never an ISO abbreviation. If the name
     // doesn't fit the footprint, drop the label rather than abbreviate.
     const text = c.name;
@@ -424,6 +501,9 @@ export function placeContextLabels(args: ContextLabelArgs): PlacedLabel[] {
       letterSpacing: 0,
       color,
       fontSize,
+      // Multi-position dodging: carry the ordered interior positions through to the
+      // commit loop. Invariant anchor === positions[0], so `cx/cy` is positions[0].
+      ...(c.positions ? { positions: c.positions } : {}),
       // Band 1 (orientation-value ranking): above MINOR water (band 2, 2000+) but
       // below MAJOR water — oceans + major seas (band 0, ≤~16). So a big country
       // (US, Canada, Russia) outranks a minor sea/bay (Sargasso, Bahía de
@@ -445,17 +525,25 @@ export function placeContextLabels(args: ContextLabelArgs): PlacedLabel[] {
   const countryCount = candidates.reduce((n, c) => n + (c.italic ? 0 : 1), 0);
   const waterCap = budget - Math.min(2, countryCount);
   let waterPlaced = 0;
-  for (const cand of candidates) {
-    if (placed.length >= budget) break;
-    if (cand.italic && waterPlaced >= waterCap) continue;
+  // Test one trial position for a candidate against every gate (fit, water-on-land,
+  // committed-obstacle collision, context-overlap). Returns the placed rect when the
+  // position clears, else null. Country candidates carry several ordered positions
+  // (map-context-neighbor-labels); we walk them best-first and commit the first that
+  // clears, so a label dodges a colliding cluster instead of being dropped. Water
+  // candidates have a single position, so behaviour is unchanged for them.
+  const gateAt = (
+    cx: number,
+    cy: number,
+    cand: Candidate
+  ): LabelRect | null => {
     const rect = rectAround(
-      cand.cx,
-      cand.cy,
+      cx,
+      cy,
       cand.lines,
       cand.letterSpacing,
       cand.fontSize
     );
-    if (!rectFits(rect, width, height)) continue;
+    if (!rectFits(rect, width, height)) return null;
     // Water labels must sit over OPEN WATER and NEVER touch land — sample a grid
     // over every wrapped line (each line's own horizontal extent at five points);
     // drop the whole label if ANY sample hits land (Decision: optional orientation
@@ -463,12 +551,12 @@ export function placeContextLabels(args: ContextLabelArgs): PlacedLabel[] {
     // exempt — they belong on their country.
     if (cand.italic && overLand) {
       const inset = 2;
-      const top = cand.cy - ((cand.lines.length - 1) / 2) * LINE_HEIGHT;
+      const top = cy - ((cand.lines.length - 1) / 2) * LINE_HEIGHT;
       const touchesLand = cand.lines.some((line, li) => {
         const lw = labelWidth(line, cand.letterSpacing);
-        const x0 = cand.cx - lw / 2 + inset;
-        const x1 = cand.cx + lw / 2 - inset;
-        const xs = [x0, (x0 + cand.cx) / 2, cand.cx, (cand.cx + x1) / 2, x1];
+        const x0 = cx - lw / 2 + inset;
+        const x1 = cx + lw / 2 - inset;
+        const xs = [x0, (x0 + cx) / 2, cx, (cx + x1) / 2, x1];
         const base = top + li * LINE_HEIGHT;
         // Sample the glyph body top→baseline (text rises above the baseline) so a
         // label whose ascenders clip a coastline is rejected, not just one whose
@@ -477,15 +565,34 @@ export function placeContextLabels(args: ContextLabelArgs): PlacedLabel[] {
           xs.some((x) => overLand(x, y))
         );
       });
-      if (touchesLand) continue;
+      if (touchesLand) return null;
+    }
+    if (collides(rect)) return null;
+    if (placedRects.some((r) => overlapsPadded(rect, r, CONTEXT_PAD)))
+      return null;
+    return rect;
+  };
+  for (const cand of candidates) {
+    if (placed.length >= budget) break;
+    if (cand.italic && waterPlaced >= waterCap) continue;
+    // Walk positions best-first; commit at the first that clears every gate. F8:
+    // `positions ?? [[cx,cy]]` keeps single-anchor (water + non-top-N country)
+    // behaviour identical. If none clears → drop (no halo, no overlap — D16).
+    const positions = cand.positions ?? [[cand.cx, cand.cy]];
+    let chosen: { x: number; y: number; rect: LabelRect } | null = null;
+    for (const [px, py] of positions) {
+      const rect = gateAt(px!, py!, cand);
+      if (rect) {
+        chosen = { x: px!, y: py!, rect };
+        break;
+      }
     }
-    if (collides(rect)) continue;
-    if (placedRects.some((r) => overlapsPadded(rect, r, CONTEXT_PAD))) continue;
-    placedRects.push(rect);
+    if (!chosen) continue;
+    placedRects.push(chosen.rect);
     if (cand.italic) waterPlaced++;
     placed.push({
-      x: cand.cx,
-      y: cand.cy,
+      x: chosen.x,
+      y: chosen.y,
       text: cand.text,
       anchor: 'middle',
       color: cand.color,

package/src/map/geo.ts

@@ -171,8 +171,16 @@ function pointOnRingEdge(
 }
 
 /** Point-in-polygon for a Polygon/MultiPolygon geometry (outer ring minus holes).
- *  A point on the outer boundary counts as inside (deterministic border handling). */
-function pointInGeometry(geometry: unknown, lon: number, lat: number): boolean {
+ *  A point on the outer boundary counts as inside (deterministic border handling).
+ *  Exported so layout's context-label dodge-position generation can validate that
+ *  a candidate interior point sits on the country's OWN rendered geometry —
+ *  holes-aware, so enclaves and neighbours are both rejected (map-context-neighbor
+ *  -labels D8). */
+export function pointInGeometry(
+  geometry: unknown,
+  lon: number,
+  lat: number
+): boolean {
   const g = geometry as {
     type: string;
     coordinates: number[][][] | number[][][][];

package/src/map/layout.ts

@@ -25,7 +25,7 @@ import {
   politicalTints,
   valueRampColor,
 } from '../palettes/color-utils';
-import { buildAdjacency, featureBboxPrimary } from './geo';
+import { buildAdjacency, featureBboxPrimary, pointInGeometry } from './geo';
 import { assignColors } from './colorize';
 import { resolveColor } from '../colors';
 import type { PaletteColors } from '../palettes/types';
@@ -52,7 +52,14 @@ import type {
   ProjectionFamily,
   GeoExtent,
 } from './resolved-types';
-import { placeContextLabels } from './context-labels';
+import {
+  placeContextLabels,
+  tierBand,
+  labelBudget,
+  MAX_COUNTRY_POSITIONS,
+  COUNTRY_POS_GRID,
+  COUNTRY_POS_TOPN_MARGIN,
+} from './context-labels';
 import type { CountryCandidate } from './context-labels';
 
 // Minimal GeoJSON shapes (avoid a hard @types/geojson dep; cast at d3 calls).
@@ -316,6 +323,17 @@ export interface MapLayoutRegion {
    *  area-weighted centroid stays on the body. Honours WORLD_LABEL_ANCHORS. */
   readonly labelX?: number;
   readonly labelY?: number;
+  /** Screen-space bounding box `[minX, minY, maxX, maxY]` of the drawn path,
+   *  computed once in `layoutMap` (reusing the `fillAt` hit-target parse) so the
+   *  renderer's per-POI-label region cull doesn't re-parse every path string per
+   *  label blob. Absent only if the layout was built before this field existed —
+   *  the renderer falls back to parsing `d`. */
+  bbox?: readonly [number, number, number, number];
+  /** Parsed screen-space rings of `d`, computed once in `layoutMap` (the same
+   *  `fillAt` hit-target parse as `bbox`) so the renderer's coastline buffering
+   *  doesn't re-parse every region path on every render. Absent only for layouts
+   *  predating this field — callers fall back to `parsePathRings(d)`. */
+  rings?: ReadonlyArray<ReadonlyArray<readonly [number, number]>>;
 }
 
 /** A framed inset "cutout" (albers-usa AK/HI), in screen px. The frame is a
@@ -708,6 +726,139 @@ function decodeLayer(topo: BoundaryTopology): Map<string, GeoFeature> {
   return out;
 }
 
+/** Generate ordered interior label positions for a country, screen-projected and
+ *  best-first, so its context label can DODGE a colliding data cluster onto open
+ *  ground on its own land (map-context-neighbor-labels, Opt F). PURE +
+ *  DETERMINISTIC — the geo work that the pure context-labels module must not do.
+ *
+ *  Algorithm (D8/D9): lay a `COUNTRY_POS_GRID²` lon/lat grid over the feature's
+ *  geographic bbox; keep cells that are (a) on the country's OWN rendered geometry
+ *  (`pointInGeometry` — holes-aware, so neighbours AND enclaves are rejected) and
+ *  (b) project to a finite point inside the viewport (its visible lobe). Order the
+ *  kept cells: the most-interior cell (most on-land 8-grid-neighbours, tie-broken
+ *  by proximity to the visible centroid) leads, then a greedy max-min spread of the
+ *  rest so fallbacks actually dodge. A `curated` lon/lat (WORLD_LABEL_ANCHORS) is
+ *  forced to slot 0 with grid cells filling the rest (D13).
+ *
+ *  Returns `{ lonLat, screen }[]` (≤ MAX_COUNTRY_POSITIONS), or `[]` when the
+ *  geometry yields no valid in-frame position (caller falls back to the single
+ *  centroid anchor, D11). The `lonLat` is exposed so tests can verify on-own-land
+ *  containment with an INDEPENDENT oracle (not a re-call of the acceptance test). */
+export function countryLabelPositions(args: {
+  geometry: unknown;
+  bounds: readonly [readonly [number, number], readonly [number, number]];
+  project: (lon: number, lat: number) => [number, number] | null;
+  width: number;
+  height: number;
+  curated?: readonly [number, number] | null;
+}): { lonLat: [number, number]; screen: [number, number] }[] {
+  const { geometry, bounds, project, width, height, curated } = args;
+  const w0 = bounds[0][0];
+  const s0 = bounds[0][1];
+  const e0 = bounds[1][0];
+  const n0 = bounds[1][1];
+  // Bail on non-finite, antimeridian-wrapping (e0 < w0 — NE crossers ship seam-split,
+  // but a feature whose own bbox still wraps falls back to the single anchor), or
+  // degenerate (zero-span) bboxes — the grid math needs a positive lon/lat span. `<=`
+  // makes the zero-span case explicit rather than relying on downstream emptiness
+  // (D9/D11).
+  if (![w0, s0, e0, n0].every(Number.isFinite) || e0 <= w0 || n0 <= s0) {
+    return mkCurated(curated, project);
+  }
+  const N = COUNTRY_POS_GRID;
+  // onLand[i][j]: cell centre is on the country's own geometry (for interiorness).
+  const onLand: boolean[][] = [];
+  type Cell = {
+    i: number;
+    j: number;
+    lon: number;
+    lat: number;
+    sx: number;
+    sy: number;
+  };
+  const kept: Cell[] = [];
+  for (let i = 0; i < N; i++) {
+    onLand[i] = [];
+    const lon = w0 + ((i + 0.5) / N) * (e0 - w0);
+    for (let j = 0; j < N; j++) {
+      const lat = s0 + ((j + 0.5) / N) * (n0 - s0);
+      const land = pointInGeometry(geometry, lon, lat);
+      onLand[i]![j] = land;
+      if (!land) continue;
+      const p = project(lon, lat);
+      if (!p || !Number.isFinite(p[0]) || !Number.isFinite(p[1])) continue;
+      // Only the visible lobe: an off-frame cell can never host a fitting label.
+      if (p[0] < 0 || p[0] > width || p[1] < 0 || p[1] > height) continue;
+      kept.push({ i, j, lon, lat, sx: p[0], sy: p[1] });
+    }
+  }
+  if (!kept.length) return mkCurated(curated, project);
+  // Visible centroid (mean of kept screen points) — tie-breaks interiorness toward
+  // the country's in-frame mass.
+  const cx = kept.reduce((s, c) => s + c.sx, 0) / kept.length;
+  const cy = kept.reduce((s, c) => s + c.sy, 0) / kept.length;
+  const interiorness = (c: Cell): number => {
+    let n = 0;
+    for (let di = -1; di <= 1; di++)
+      for (let dj = -1; dj <= 1; dj++) {
+        if (di === 0 && dj === 0) continue;
+        const ni = c.i + di;
+        const nj = c.j + dj;
+        if (ni >= 0 && ni < N && nj >= 0 && nj < N && onLand[ni]![nj]) n++;
+      }
+    return n;
+  };
+  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.
+  const curatedPos = curated
+    ? mkCurated(curated, project)
+    : ([] as { lonLat: [number, number]; screen: [number, number] }[]);
+  const out = [...curatedPos, ...grid].slice(0, MAX_COUNTRY_POSITIONS);
+  return out;
+}
+
+/** Project a single curated lon/lat into the position-list shape (or [] when it
+ *  doesn't project finitely). Helper for `countryLabelPositions`. */
+function mkCurated(
+  curated: readonly [number, number] | null | undefined,
+  project: (lon: number, lat: number) => [number, number] | null
+): { lonLat: [number, number]; screen: [number, number] }[] {
+  if (!curated) return [];
+  const p = project(curated[0], curated[1]);
+  if (!p || !Number.isFinite(p[0]) || !Number.isFinite(p[1])) return [];
+  return [{ lonLat: [curated[0], curated[1]], screen: [p[0], p[1]] }];
+}
+
 // Our own US map (replaces d3 geoAlbersUsa, whose fixed composite clips
 // Canada/Mexico to hard lines and bakes in inset boxes we can't control). A
 // plain Albers conic for the contiguous 48 — it does NOT clip, so neighbour land
@@ -2312,6 +2463,20 @@ export function layoutMap(
         if (p[1] < minY) minY = p[1];
         if (p[1] > maxY) maxY = p[1];
       }
+    // Stash the bbox + parsed rings on the region so the renderer's per-POI-label
+    // cull (bbox) and coastline buffering (rings) reuse this parse instead of
+    // re-parsing `d` (roadmap #2/#4).
+    (
+      r as {
+        bbox?: readonly [number, number, number, number];
+        rings?: ReadonlyArray<ReadonlyArray<readonly [number, number]>>;
+      }
+    ).bbox = [minX, minY, maxX, maxY];
+    (
+      r as {
+        rings?: ReadonlyArray<ReadonlyArray<readonly [number, number]>>;
+      }
+    ).rings = rings;
     return { fill: r.fill, rings, minX, minY, maxX, maxY };
   });
   const fillAt = (x: number, y: number): string => {
@@ -4238,6 +4403,19 @@ export function layoutMap(
     // work (bbox/anchor) stays here; area-rank + fit + collision live in the
     // pure module so the strict density invariants (AC7) are unit-testable.
     const countryCandidates: CountryCandidate[] = [];
+    // Pass 1: collect the raw country records (feature + screen bbox/anchor),
+    // carrying `f` so pass 2 can generate dodge positions from the SAME rendered
+    // geometry (D14 — no re-decode).
+    type RawCountry = {
+      f: GeoFeature;
+      iso: string;
+      name: string;
+      bbox: [number, number, number, number];
+      anchor: [number, number] | null;
+      curatedLngLat: readonly [number, number] | null;
+      area: number;
+    };
+    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;
@@ -4259,11 +4437,87 @@ export function layoutMap(
       const a = anchorLngLat
         ? project(anchorLngLat[0], anchorLngLat[1])
         : (path.centroid(f as never) as [number, number]);
-      countryCandidates.push({
+      rawCountries.push({
+        f,
+        iso,
         name: (f.properties as { name?: string } | undefined)?.name ?? iso,
         bbox: [x0, y0, x1, y1],
         anchor: a && Number.isFinite(a[0]) ? [a[0], a[1]] : null,
-        curatedAnchor: !!anchorLngLat,
+        curatedLngLat: anchorLngLat ?? null,
+        area: (x1 - x0) * (y1 - y0),
+      });
+    }
+    // Pass 2: generate multi-position dodge candidates EAGERLY for the top
+    // `budget + margin` area-ranked countries only — only that many can win a slot,
+    // so generating for all ~45 in-view countries is wasted PiP work (D15). The
+    // band/budget helpers live in the pure module; compute them here since layout
+    // doesn't otherwise hold them. Positions[0] becomes the anchor so the
+    // single-anchor `anchor === positions[0]` invariant (D12) holds.
+    const cBand = tierBand(Math.max(dLonSpan, dLatSpan));
+    const cBudget = labelBudget(width, height, cBand);
+    // Content points = the POI markers (the diagram's story). Drive BOTH the
+    // proximity rank in placeContextLabels AND which countries get dodge positions
+    // generated here, so the near-action winners are equipped to dodge
+    // (map-context-neighbor-labels, proximity knob). Empty ⇒ legacy area rank.
+    const contentPoints: [number, number][] = markers.map((m) => [m.cx, m.cy]);
+    // Generate dodge positions for the top `budget + margin` candidates ranked the
+    // SAME way placeContextLabels will pick winners — by proximity to the nearest
+    // content point when known, else by area. (Generating for all ~45 in-view
+    // countries is wasted PiP work; D15.) The +MARGIN slack covers the rank skew
+    // from the module's extra fit/viewport filtering, so the eventual winner still
+    // carries dodge positions.
+    const topN = cBudget + COUNTRY_POS_TOPN_MARGIN;
+    const rankOrder = rawCountries
+      .map((r, idx) => {
+        // Match placeContextLabels' rank: distance from the NEAREST content point to
+        // the country's footprint bbox (0 if inside, else nearest-edge), so the same
+        // near-the-action winners get dodge positions generated.
+        let dist = Infinity;
+        const [x0, y0, x1, y1] = r.bbox;
+        for (const [px, py] of contentPoints) {
+          const dx = Math.max(x0 - px, 0, px - x1);
+          const dy = Math.max(y0 - py, 0, py - y1);
+          const d = dx * dx + dy * dy;
+          if (d < dist) dist = d;
+        }
+        return { idx, area: r.area, dist };
+      })
+      .filter((r) => Number.isFinite(r.area) && r.area > 0)
+      .sort((a, b) =>
+        contentPoints.length
+          ? a.dist - b.dist || b.area - a.area
+          : b.area - a.area
+      )
+      .slice(0, topN);
+    const genIdx = new Set(rankOrder.map((r) => r.idx));
+    for (let i = 0; i < rawCountries.length; i++) {
+      const r = rawCountries[i]!;
+      let anchor = r.anchor;
+      let positions: readonly (readonly [number, number])[] | undefined;
+      if (genIdx.has(i) && anchor) {
+        const gb = geoBounds(r.f as never) as [
+          [number, number],
+          [number, number],
+        ];
+        const gen = countryLabelPositions({
+          geometry: r.f.geometry,
+          bounds: gb,
+          project,
+          width,
+          height,
+          curated: r.curatedLngLat,
+        });
+        if (gen.length) {
+          positions = gen.map((p) => p.screen);
+          anchor = positions[0] as [number, number]; // D12: anchor === positions[0]
+        }
+      }
+      countryCandidates.push({
+        name: r.name,
+        bbox: r.bbox,
+        anchor,
+        curatedAnchor: !!r.curatedLngLat,
+        ...(positions ? { positions } : {}),
       });
     }
     // Framed US states (POI-only region framing): when the frame is snapped to a
@@ -4310,6 +4564,7 @@ export function layoutMap(
       palette,
       project,
       collides,
+      contentPoints,
       // Water labels must stay over open water — `fillAt` returns the ocean
       // backdrop colour off-land and a region fill on-land (lakes/states count
       // as land here, which is the safe side for an ocean name).

package/src/map/parser.ts

@@ -102,6 +102,8 @@ export function parseMap(content: string, palette?: PaletteColors): ParsedMap {
     diagnostics.push(makeDgmoError(line, message, 'error', code));
     result.error ??= formatDgmoError(diagnostics[diagnostics.length - 1]!);
   };
+  // Bespoke (not the shared makeFail, Story 111.4): map delegates to pushError,
+  // which is first-error-wins (`??=`) and carries an optional diagnostic code.
   const fail = (line: number, message: string): ParsedMap => {
     pushError(line, message);
     return result;