@diagrammo/dgmo 0.22.0 → 0.23.0

package/src/map/layout.ts

@@ -69,6 +69,16 @@ const R_MAX = 22;
 const W_MIN = 1.25; // edge stroke width
 const W_MAX = 8;
 const FONT = 11; // on-map label font px
+
+// A few countries have far-flung territory that drags the area-weighted centroid
+// off the mainland (US → Alaska pulls it up into Canada). Anchor their world-layer
+// label/hover point to a mainland [lon, lat] instead. Antimeridian crossers whose
+// body dominates by area (Russia) are NOT listed — their area-weighted centroid
+// already lands on the mainland; only the naive bounding-box centre (which the app
+// previously used for hover) mistook the wrapped sliver for half the shape.
+const WORLD_LABEL_ANCHORS: Record<string, [number, number]> = {
+  US: [-98.5, 39.5], // CONUS geographic centre (near Lebanon, Kansas)
+};
 // POI-cluster hover-only gate (Decision #1). A ≥2-member cluster's callout
 // column falls back to hover-only labels when it would sprawl or overflow:
 //  - MAX_CLUSTER_EXTENT_FACTOR × min(width,height) = the px diagonal beyond which
@@ -112,16 +122,21 @@ const RELIEF_MIN_DIM = 2; // px
 // Relief = horizontal hachure lines clipped to each range: a subtle
 // dark-on-light / light-on-dark texture that reads as "mountains here". Spacing
 // is SCREEN-space so density is constant regardless of zoom (geo-space spacing
-// would collapse a small range to 1–2 lines and read as a glitch). Kept FAINT:
-// thin sub-pixel lines drawn with a non-scaling stroke (constant device width at
-// any zoom/DPR) and low-contrast colour. NOT crispEdges — that snaps the stroke
-// to a solid ~1px in WebKit and reads far too heavy; plain AA keeps them whisper-thin.
-const RELIEF_HATCH_SPACING = 2; // px between lines
-const RELIEF_HATCH_WIDTH = 0.15; // px stroke
+// would collapse a small range to 1–2 lines and read as a glitch). Drawn with a
+// non-scaling stroke (constant device width at any zoom/DPR) and a low-contrast
+// colour so it reads as faint, fine terrain hachure — dense thin lines that are
+// almost indistinguishable as individual strokes (a whisper of texture, not
+// stripes). NOT crispEdges — that snaps the stroke to a solid ~1px in WebKit and
+// reads too heavy; plain AA keeps the lines soft. The width is kept just ABOVE
+// sub-pixel: at ~0.15px the AA fuzz spreads each line to ~1px and tight spacing
+// merges them into a flat grey wash (a "blob"). 0.25px every 1.5px stays a fine,
+// faint hatch on both zoomed-out world maps and zoomed-in regional views.
+const RELIEF_HATCH_SPACING = 1.5; // px between lines
+const RELIEF_HATCH_WIDTH = 0.2; // px stroke
 // % of the DARK reference (palette.bg on dark themes, palette.text on light)
 // blended into the land colour — so the lines read DARKER than the land in both
 // themes (palette.text alone flips to light on dark themes).
-const RELIEF_HATCH_STRENGTH = 32;
+const RELIEF_HATCH_STRENGTH = 26;
 // Coastline water-lines (opt-in `coastline`, §24B.2). N equal-width coast-parallel
 // rings on the water side, evenly spaced and FADING seaward — the antique
 // nautical-chart depth-contour look. Offshore distances + thickness are
@@ -191,6 +206,14 @@ export interface MapLayoutRegion {
   /** The region's tag values keyed by group (lowercased) — emitted as
    *  `data-tag-<group>` so the app can highlight on legend-entry hover. */
   readonly tags?: Readonly<Record<string, string>>;
+  /** Area-weighted screen centroid (px) of the DRAWN geometry — emitted as
+   *  `data-label-x`/`data-label-y` so the app can anchor the hover label here
+   *  instead of the path's bounding-box centre. The bbox centre breaks for
+   *  antimeridian crossers (Russia's wrapped Chukotka sliver pins the box's left
+   *  edge to the far side of the map, dropping the centre into the Atlantic); the
+   *  area-weighted centroid stays on the body. Honours WORLD_LABEL_ANCHORS. */
+  readonly labelX?: number;
+  readonly labelY?: number;
 }
 
 /** A framed inset "cutout" (albers-usa AK/HI), in screen px. The frame is a
@@ -836,6 +859,60 @@ export function parsePathRings(d: string): Array<Array<[number, number]>> {
   return rings;
 }
 
+/** Drop antimeridian wrap-slivers from a GLOBAL-view region path. A landmass that
+ *  crosses ±180° (Russia's Chukotka, the western Aleutians, Fiji…) is clipped into
+ *  fragments; the far one is a small sliver pinned to the OPPOSITE vertical frame
+ *  edge — it reads as a stray island floating beside its true continent (e.g. the
+ *  "island left of Alaska"). We drop any ring that (a) has an edge collinear with
+ *  the LEFT or RIGHT canvas edge AND (b) is small AND (c) isn't the region's
+ *  largest ring. The mainland (large, on its own edge) and interior islands (not
+ *  frame-cut) are kept. Vertical edges only — a ring cut by the top/bottom lat
+ *  crop is real content, not a wrap. Global-only: regional clipExtent cuts ARE
+ *  real land at the viewport edge and must survive. */
+function dropAntimeridianWrapSlivers(
+  d: string,
+  width: number,
+  height: number
+): string {
+  const rings = parsePathRings(d);
+  if (rings.length <= 1) return d;
+  const eps = 0.75;
+  const minArea = 0.003 * width * height; // 0.3% of canvas
+  const ringArea = (r: ReadonlyArray<[number, number]>): number => {
+    let s = 0;
+    for (let i = 0; i < r.length; i++) {
+      const a = r[i]!;
+      const b = r[(i + 1) % r.length]!;
+      s += a[0] * b[1] - b[0] * a[1];
+    }
+    return Math.abs(s) / 2;
+  };
+  const areas = rings.map(ringArea);
+  const maxArea = Math.max(...areas);
+  const onVEdge = (
+    a: readonly [number, number],
+    b: readonly [number, number]
+  ): boolean =>
+    (Math.abs(a[0]) <= eps && Math.abs(b[0]) <= eps) ||
+    (Math.abs(a[0] - width) <= eps && Math.abs(b[0] - width) <= eps);
+  let dropped = false;
+  const kept = rings.filter((r, idx) => {
+    if (areas[idx]! >= maxArea || areas[idx]! >= minArea) return true;
+    const touches = r.some((p, i) => onVEdge(p, r[(i + 1) % r.length]!));
+    if (touches) {
+      dropped = true;
+      return false;
+    }
+    return true;
+  });
+  if (!dropped) return d;
+  return kept
+    .map(
+      (r) => r.map((p, i) => (i ? 'L' : 'M') + p[0] + ',' + p[1]).join('') + 'Z'
+    )
+    .join('');
+}
+
 export function layoutMap(
   resolved: ResolvedMap,
   data: MapData,
@@ -1140,10 +1217,17 @@ export function layoutMap(
     const by0 = cb[0][1];
     const cw = cb[1][0] - bx0;
     const ch = cb[1][1] - by0;
-    const ox = fitBox[0][0];
-    const oy = fitBox[0][1];
-    const sx = cw > 0 ? (fitBox[1][0] - ox) / cw : 1;
-    const sy = ch > 0 ? (fitBox[1][1] - oy) / ch : 1;
+    // A global stretch-fill runs the world to EVERY edge of the canvas — no
+    // FIT_PAD inset. The equirectangular rectangle is the map, so its edges ARE
+    // the render-area edges (the antimeridian sits exactly on the left/right
+    // edge, not 24px short of it with a coastline ringing the gap). The title
+    // overlays the top; we reserve a top band only when POIs are present (so
+    // their markers don't project up under the foreground title banner).
+    const topReserve = resolved.title && resolved.pois.length > 0 ? topPad : 0;
+    const ox = 0;
+    const oy = topReserve;
+    const sx = cw > 0 ? width / cw : 1;
+    const sy = ch > 0 ? (height - topReserve) / ch : 1;
     stretchParams = { sx, sy, ox, oy, bx0, by0 };
     const stretch = (x: number, y: number): [number, number] => [
       ox + (x - bx0) * sx,
@@ -1588,7 +1672,12 @@ export function layoutMap(
       // but still drop antimeridian frame-fillers (Fiji et al.).
       const viewF = shouldCull ? cullFeatureToView(f) : dropFrameFillers(f);
       if (!viewF) continue;
-      const d = path(viewF as never) ?? '';
+      const raw = path(viewF as never) ?? '';
+      // Global views: strip the wrap-sliver a crossing landmass leaves pinned to
+      // the far edge (Russia's Chukotka beside Alaska). Regional cuts are real.
+      const d = fitIsGlobal
+        ? dropAntimeridianWrapSlivers(raw, width, height)
+        : raw;
       if (!d) continue;
       const isThisLayer = r?.layer === layerKind;
       // Non-US neighbour land in a US view is gray context, not yellow land.
@@ -1614,6 +1703,15 @@ export function layoutMap(
         // (the same source the resolver/inset/context-label layers read).
         label = (f.properties as { name?: string } | null)?.name;
       }
+      // Label/hover anchor: a hardcoded mainland anchor when far-flung territory
+      // would skew it, else the area-weighted screen centroid of the drawn shape.
+      // The latter (unlike a bounding-box centre) survives antimeridian crossers.
+      const labelAnchor = WORLD_LABEL_ANCHORS[iso];
+      const c = labelAnchor
+        ? project(labelAnchor[0], labelAnchor[1])
+        : path.centroid(viewF as never);
+      const hasCentroid =
+        c != null && Number.isFinite(c[0]) && Number.isFinite(c[1]);
       regions.push({
         id: iso,
         d,
@@ -1622,6 +1720,7 @@ export function layoutMap(
         lineNumber,
         layer,
         ...(label !== undefined && { label }),
+        ...(hasCentroid && { labelX: c[0], labelY: c[1] }),
         ...(isThisLayer && r.value !== undefined && { value: r.value }),
         ...(isThisLayer && Object.keys(r.tags).length > 0 && { tags: r.tags }),
       });
@@ -2284,12 +2383,6 @@ export function layoutMap(
       lineNumber,
     });
   };
-  // A few countries have far-flung territory that drags the area-weighted
-  // centroid off the mainland (US → Alaska pulls it up into Canada). Anchor
-  // their world-layer label to a mainland [lon, lat] instead.
-  const WORLD_LABEL_ANCHORS: Record<string, [number, number]> = {
-    US: [-98.5, 39.5], // CONUS geographic centre (near Lebanon, Kansas)
-  };
   // A region label's screen footprint, middle-anchored on its centroid, used to
   // keep two region labels from overlapping (a small gap adds breathing room).
   const REGION_LABEL_GAP = 2;

package/src/map/renderer.ts

@@ -57,6 +57,70 @@ function ringToPath(ring: ReadonlyArray<[number, number]>): string {
   return d + 'Z';
 }
 
+/** Open SVG polyline (`M…L…`, no `Z`) from a run of points. */
+function polylineToPath(pts: ReadonlyArray<[number, number]>): string {
+  let d = '';
+  for (let i = 0; i < pts.length; i++)
+    d += (i ? 'L' : 'M') + pts[i]![0] + ',' + pts[i]![1];
+  return d;
+}
+
+/** Coast subpaths for one ring, dropping any edge that runs ALONG a canvas edge.
+ *  A region clipped to the viewport (the antimeridian on a world map, or a
+ *  regional clipExtent cut) gains a synthetic straight edge collinear with the
+ *  frame — that edge is NOT a real coast and must not be buffered into a coast
+ *  band (which would ring the cut with water-lines short of the edge). Without a
+ *  `frame` the ring is returned closed (`M…Z`) as before. With one, the ring is
+ *  split at every frame-collinear edge into open coast arcs (`M…L…`), so the land
+ *  runs cleanly to the edge and only true coastline gets a water-line. */
+function ringToCoastPaths(
+  ring: ReadonlyArray<[number, number]>,
+  frame?: { w: number; h: number }
+): string[] {
+  if (!frame) return [ringToPath(ring)];
+  const n = ring.length;
+  const eps = 0.75;
+  const onL = (x: number): boolean => Math.abs(x) <= eps;
+  const onR = (x: number): boolean => Math.abs(x - frame.w) <= eps;
+  const onT = (y: number): boolean => Math.abs(y) <= eps;
+  const onB = (y: number): boolean => Math.abs(y - frame.h) <= eps;
+  const isFrameEdge = (
+    a: readonly [number, number],
+    b: readonly [number, number]
+  ): boolean =>
+    (onL(a[0]) && onL(b[0])) ||
+    (onR(a[0]) && onR(b[0])) ||
+    (onT(a[1]) && onT(b[1])) ||
+    (onB(a[1]) && onB(b[1]));
+  // No frame-collinear edge anywhere → ordinary interior coastline (closed).
+  let firstBreak = -1;
+  for (let i = 0; i < n; i++)
+    if (isFrameEdge(ring[i]!, ring[(i + 1) % n]!)) {
+      firstBreak = i;
+      break;
+    }
+  if (firstBreak === -1) return [ringToPath(ring)];
+  // Walk the loop from just after the first cut, accumulating runs of real-coast
+  // edges into open polylines and breaking at each frame-collinear edge.
+  const paths: string[] = [];
+  let cur: Array<[number, number]> = [];
+  const start = (firstBreak + 1) % n;
+  for (let k = 0; k < n; k++) {
+    const i = (start + k) % n;
+    const a = ring[i]!;
+    const b = ring[(i + 1) % n]!;
+    if (isFrameEdge(a, b)) {
+      if (cur.length >= 2) paths.push(polylineToPath(cur));
+      cur = [];
+      continue;
+    }
+    if (cur.length === 0) cur.push(a);
+    cur.push(b);
+  }
+  if (cur.length >= 2) paths.push(polylineToPath(cur));
+  return paths;
+}
+
 /** Coast outlines to buffer: every region's OUTER rings whose bbox extent clears
  *  `minExtent`. Holes/enclaves are skipped via containment depth (even depth =
  *  outer landmass boundary, odd = a hole) so an enclave (Lesotho) or a lake-hole
@@ -64,7 +128,8 @@ function ringToPath(ring: ReadonlyArray<[number, number]>): string {
  *  degenerate-ring floor now — every island, however small, grows coast rings. */
 function coastlineOuterRings(
   regions: readonly MapLayoutRegion[],
-  minExtent: number
+  minExtent: number,
+  frame?: { w: number; h: number }
 ): string[] {
   const paths: string[] = [];
   for (const r of regions) {
@@ -88,7 +153,7 @@ function coastlineOuterRings(
       for (let j = 0; j < rings.length; j++)
         if (j !== i && pointInRing(fx, fy, rings[j]!)) depth++;
       if (depth % 2 === 1) continue; // hole/enclave — skip
-      paths.push(ringToPath(ring));
+      paths.push(...ringToCoastPaths(ring, frame));
     }
   }
   return paths;
@@ -229,6 +294,16 @@ export function renderMap(
     // Display name on EVERY region (authored + base/context) so the app can
     // surface it on hover — decorative metadata, no visible text drawn here.
     if (r.label) p.attr('data-region-name', r.label);
+    // ISO id on EVERY political region (authored + base/context + inset states),
+    // so the Inspect tool can resolve a reverse-geocoded `{iso}` to its drawn path
+    // and outline it. Distinct from `data-region` (data-layer-only, legend hover):
+    // this lands on base/context land too. Lakes carry no iso (not a place).
+    if (r.id && r.id !== 'lake') p.attr('data-iso', r.id);
+    // Area-weighted centroid (px) the app anchors the hover label to — robust to
+    // antimeridian crossers where a bounding-box centre lands in open ocean.
+    if (r.labelX !== undefined && r.labelY !== undefined) {
+      p.attr('data-label-x', r.labelX).attr('data-label-y', r.labelY);
+    }
     // Data layer? Tag it so the app can highlight on legend hover / gradient
     // scrub. `data-value` for ramp-proximity, `data-tag-<group>` per tag value
     // (both lowercased to match the lowercased legend-entry attributes).
@@ -276,6 +351,10 @@ export function renderMap(
     const gRelief = svg
       .append('g')
       .attr('clip-path', `url(#${landClipId})`) // outer: land only
+      // Decorative texture — never a pointer target, so region hover (the app's
+      // name-on-hover) always reaches the region path beneath. WebKit hit-tests
+      // masked/clipped overlays unlike Chromium, so this must be explicit.
+      .style('pointer-events', 'none')
       .append('g')
       .attr('class', 'dgmo-map-relief')
       .attr('clip-path', `url(#${rangeClipId})`) // inner: ∩ ranges
@@ -370,10 +449,20 @@ export function renderMap(
       .append('g')
       .attr('class', 'dgmo-map-water-lines')
       .attr('fill', 'none')
+      // Decorative nautical lines — never a pointer target. Without this the wide
+      // pre-mask coastal ring bands swallow region hover over coastal countries in
+      // WebKit (which hit-tests masked content unlike Chromium); e.g. Portugal.
+      .style('pointer-events', 'none')
       .attr('mask', `url(#${maskId})`);
     appendWaterLines(
       gWater,
-      coastlineOuterRings(layout.regions, cs.minExtent),
+      // Pass the canvas frame so edges collinear with it (the antimeridian on a
+      // world map, regional clipExtent cuts) don't get ringed as fake coast —
+      // land runs cleanly to the render-area edge.
+      coastlineOuterRings(layout.regions, cs.minExtent, {
+        w: width,
+        h: height,
+      }),
       cs,
       layout.background
     );
@@ -407,7 +496,8 @@ export function renderMap(
     const gRivers = svg
       .append('g')
       .attr('class', 'dgmo-map-rivers')
-      .attr('fill', 'none');
+      .attr('fill', 'none')
+      .style('pointer-events', 'none'); // decorative — pass hover to regions below
     for (const r of layout.rivers) {
       gRivers
         .append('path')
@@ -509,6 +599,7 @@ export function renderMap(
         .append('g')
         .attr('class', 'dgmo-map-inset-water-lines')
         .attr('fill', 'none')
+        .style('pointer-events', 'none') // decorative — pass hover to inset regions
         .attr('mask', `url(#${maskId})`);
       appendWaterLines(
         gInsetWater,

package/src/utils/reserved-key-registry.ts

@@ -148,12 +148,14 @@ export const PERT_REGISTRY: ReservedKeyRegistry = staticRegistry([
   'collapsed',
 ]);
 
+// `width`/`split`/`fanout` were copy-pasted from an infra-flavored template
+// during the §1.4 metadata migration but boxes-and-lines never read them
+// (split/fanout are infra-only edge-flow keys, consumed in src/infra/*). Removed
+// 2026-06-03 — only `value` (the numeric ramp) is a real BL data channel.
 export const BOXES_AND_LINES_REGISTRY: ReservedKeyRegistry = staticRegistry([
   'color',
   'description',
-  'width',
-  'split',
-  'fanout',
+  'value',
 ]);
 
 export const TIMELINE_REGISTRY: ReservedKeyRegistry = staticRegistry([