@diagrammo/dgmo 0.22.0 → 0.24.0

package/src/map/renderer.ts

@@ -14,6 +14,7 @@ import {
 import { mix } from '../palettes/color-utils';
 import { renderLegendD3 } from '../utils/legend-d3';
 import type { LegendConfig, LegendState } from '../utils/legend-types';
+import { mapLegendConfig, mapLegendGroups } from './legend-band';
 import type { PaletteColors } from '../palettes/types';
 import type { D3ExportDimensions } from '../utils/d3-types';
 import type { MapData, ResolvedMap } from './resolved-types';
@@ -57,6 +58,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 +129,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 +154,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;
@@ -171,6 +237,9 @@ export function renderMap(
       // stretch-distorting. The in-app preview pane passes no exportDims → unset →
       // keeps the global stretch-fill.
       preferContain: exportDims?.preferContain ?? false,
+      // Reserve the legend band for the mode actually drawn below (export shows
+      // only the active group; preview keeps the inactive pills).
+      legendMode: exportDims ? 'export' : 'preview',
       ...(activeGroupOverride !== undefined && {
         activeGroup: activeGroupOverride,
       }),
@@ -229,6 +298,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 +355,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 +453,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 +500,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 +603,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,
@@ -821,36 +916,14 @@ export function renderMap(
       .attr('transform', `translate(0, ${legendY})`);
     // The value ramp is a selectable colouring group alongside the tag groups
     // (the user flips between them); its capsule renders the gradient inline.
-    // Reserved name "Value" when no region-metric label is set — must match
-    // VALUE_NAME in layout.ts so the resolved activeGroup selects it.
-    const ramp = layout.legend.ramp;
-    const scoreGroup = ramp
-      ? {
-          name: ramp.metric?.trim() || 'Value',
-          entries: [],
-          gradient: {
-            min: ramp.min,
-            max: ramp.max,
-            hue: ramp.hue,
-            base: ramp.base,
-          },
-        }
-      : null;
-    const tagGroups = layout.legend.tagGroups
-      .filter((g) => g.entries.length > 0)
-      .map((g) => ({ name: g.name, entries: [...g.entries] }));
-    const groups = [...(scoreGroup ? [scoreGroup] : []), ...tagGroups];
+    // Built from the shared helper so the drawn legend matches the band the
+    // layout reserved for it (see legend-band.ts).
+    const groups = mapLegendGroups(layout.legend);
     if (groups.length > 0) {
-      const config: LegendConfig = {
+      const config: LegendConfig = mapLegendConfig(
         groups,
-        position: { placement: 'top-center', titleRelation: 'below-title' },
-        mode: exportDims ? 'export' : 'preview',
-        showEmptyGroups: false,
-        // Keep inactive siblings visible as pills so the user can click to flip
-        // the active colouring dimension (preview only — export shows just the
-        // active group).
-        showInactivePills: true,
-      };
+        exportDims ? 'export' : 'preview'
+      );
       const state: LegendState = { activeGroup: layout.legend.activeGroup };
       renderLegendD3(legendG, config, state, palette, isDark, undefined, width);
     }

package/src/map/resolver.ts

@@ -64,6 +64,16 @@ const WORLD_LAT_NORTH = 78;
 // the dots. A tight cluster (e.g. Bay Area cities) therefore frames as ≈ its
 // home state + neighbours rather than the whole nation. Tunable.
 const POI_ZOOM_FLOOR_DEG = 7;
+// POI-only container framing reveals the region(s) that CONTAIN the dots, but a
+// single POI near the edge of a tall/wide country (e.g. Cartagena at the north
+// tip of Colombia) would otherwise drag the frame to that country's far edge —
+// all the way to the Amazon, ~15° below the southernmost dot. Clamp the container
+// union so it reveals at most this many degrees of container BEYOND the POI
+// cluster on each side: northern Colombia stays for orientation, the empty
+// interior is cropped. Sized so an edge cluster still reaches across a US
+// state-scale container (a Bay-Area cluster sits on the coast, ~8° from the
+// Nevada border, and must still show the whole of California). Tunable.
+const CONTAINER_OVERSHOOT_DEG = 8;
 // Above this longitudinal span a US POI-only extent is "national" — use the
 // albers-usa composite (CONUS conic + AK/HI insets) instead of regional Mercator.
 // CONUS spans ≈58° lon; 48° is "most of the country". Tunable.
@@ -798,7 +808,11 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
       if (bb && !isWholeSphere(bb)) containerBoxes.push(bb);
     }
     const containerUnion = unionExtent(containerBoxes, points);
-    if (containerUnion) extent = pad(containerUnion, PAD_FRACTION);
+    if (containerUnion)
+      extent = pad(
+        clampContainerToCluster(containerUnion, points),
+        PAD_FRACTION
+      );
   }
 
   // POI-only fit-to-cluster zoom floor. With region framing above, the extent is
@@ -934,6 +948,34 @@ function mostCommonCountry(
   return best;
 }
 
+/** Asymmetric container clamp (R-poi-region overshoot guard). Container framing
+ *  reveals the region(s) holding the POIs, but one POI at the edge of a tall/wide
+ *  country drags the frame to that country's far edge. Cap how far the frame
+ *  extends BEYOND the POI cluster on each side at CONTAINER_OVERSHOOT_DEG. Latitude
+ *  always clamps; longitude clamps only when neither extent crosses the
+ *  antimeridian seam (a wrapped extent carries east > 180), where naive min/max
+ *  would be wrong. Never tightens past the cluster itself, so the dots stay
+ *  framed, and never widens it — the container edge is still the outer bound. */
+function clampContainerToCluster(
+  container: GeoExtent,
+  points: Array<[number, number]>
+): GeoExtent {
+  const poi = unionExtent([], points);
+  if (!poi) return container;
+  let [[west, south], [east, north]] = container;
+  const [[pWest, pSouth], [pEast, pNorth]] = poi;
+  south = Math.max(south, pSouth - CONTAINER_OVERSHOOT_DEG);
+  north = Math.min(north, pNorth + CONTAINER_OVERSHOOT_DEG);
+  if (east <= 180 && pEast <= 180) {
+    west = Math.max(west, pWest - CONTAINER_OVERSHOOT_DEG);
+    east = Math.min(east, pEast + CONTAINER_OVERSHOOT_DEG);
+  }
+  return [
+    [west, south],
+    [east, north],
+  ];
+}
+
 function pad(e: GeoExtent, frac: number): GeoExtent {
   const dLon = (e[1][0] - e[0][0]) * frac || 1;
   const dLat = (e[1][1] - e[0][1]) * frac || 1;

package/src/map/types.ts

@@ -142,3 +142,23 @@ export interface ParsedMap {
   readonly diagnostics: readonly DgmoError[];
   readonly error: string | null;
 }
+
+/** Legend descriptor for a rendered map (a layout-stage output, re-exported from
+ *  `layout.ts`). It lives here so the `legend-band` helper can consume it without
+ *  importing `layout` — `layout` already value-imports `mapLegendBand`, so the
+ *  reverse type import would form a layout↔legend-band cycle. */
+export interface MapLayoutLegend {
+  readonly tagGroups: ReadonlyArray<{
+    name: string;
+    entries: ReadonlyArray<{ value: string; color: string }>;
+  }>;
+  readonly activeGroup: string | null;
+  readonly ramp?: {
+    metric?: string;
+    min: number;
+    max: number;
+    hue: string;
+    /** Low end of the ramp gradient (the land colour the fills blend from). */
+    base: string;
+  };
+}

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([

package/src/utils/svg-embed.ts

@@ -0,0 +1,193 @@
+/**
+ * Make an SVG produced by `@diagrammo/dgmo`'s static `render()` suitable for
+ * responsive inline embedding in any host (Obsidian, remark/markdown, web
+ * pages):
+ *
+ * - dgmo renders diagrams inside a fixed export canvas (e.g.
+ *   `viewBox="0 0 1200 800"`), with content often occupying only a fraction
+ *   of it. We compute a tight content bounding box from element coordinates
+ *   and set the root `viewBox` to bbox+padding, so the diagram's intrinsic
+ *   aspect ratio matches its CONTENT — no dead space above/below or beside it.
+ * - Ensure the root `<svg>` has a `viewBox` so it scales responsively.
+ * - Strip fixed `width="N"` / `height="N"` so CSS (e.g. `width:100%;
+ *   height:auto`, or an aspect-ratio derived from the tight viewBox) controls
+ *   sizing.
+ * - Remove any inline `background:` from the root style so the page
+ *   background shows through.
+ *
+ * This is intentionally a string transform, not a DOM `getBBox()` step: dgmo
+ * can dual-render light/dark SVGs where one is hidden by color-mode CSS, and
+ * `getBBox()` returns 0 for the hidden copy. Parsing coordinates from the
+ * markup measures both copies reliably and works server-side (Node).
+ */
+export function normalizeSvgForEmbed(input: string): string {
+  let svg = input;
+  const rootMatch = svg.match(/<svg[^>]*>/);
+  const rootTag = rootMatch?.[0] ?? '';
+  if (rootTag && !rootTag.includes('viewBox')) {
+    const wh = rootTag.match(/width="(\d+)"[^>]*height="(\d+)"/);
+    if (wh) {
+      svg = svg.replace(/<svg/, `<svg viewBox="0 0 ${wh[1]} ${wh[2]}"`);
+    }
+  }
+
+  const tight = computeBBox(svg);
+  if (tight && tight.width > 0 && tight.height > 0) {
+    const pad = 16;
+    const vb = `${tight.x - pad} ${tight.y - pad} ${tight.width + pad * 2} ${tight.height + pad * 2}`;
+    svg = svg.replace(/(<svg[^>]*?)viewBox="[^"]*"/, `$1viewBox="${vb}"`);
+  }
+
+  svg = svg.replace(/(<svg[^>]*?) width="[^"]*"/g, '$1');
+  svg = svg.replace(/(<svg[^>]*?) height="[^"]*"/g, '$1');
+  svg = svg.replace(/(<svg[^>]*?style="[^"]*?)background:[^;"]*;?\s*/g, '$1');
+  svg = svg.replace(/<svg\s{2,}/g, '<svg ');
+  return svg;
+}
+
+/**
+ * Parse the content bounding box of a normalized embed SVG, if one can be
+ * derived. Returns `null` when no usable coordinates are found (e.g. an empty
+ * diagram). Useful for hosts that want to set an explicit `aspect-ratio` from
+ * the tight viewBox.
+ */
+export function getEmbedSvgViewBox(
+  svg: string
+): { x: number; y: number; width: number; height: number } | null {
+  const tight = computeBBox(svg);
+  if (!tight || tight.width <= 0 || tight.height <= 0) return null;
+  const pad = 16;
+  return {
+    x: tight.x - pad,
+    y: tight.y - pad,
+    width: tight.width + pad * 2,
+    height: tight.height + pad * 2,
+  };
+}
+
+/**
+ * Compute an approximate content bounding box from raw element coordinates.
+ *
+ * This is a regex walk, not a real SVG layout — it ignores `transform`
+ * attributes and uses a heuristic for text widths. dgmo's renderers mostly use
+ * absolute coordinates within their viewBox, so the approximation is close
+ * enough that the rendered output reliably fills the visible area.
+ */
+function computeBBox(
+  svg: string
+): { x: number; y: number; width: number; height: number } | null {
+  const xs: number[] = [];
+  const ys: number[] = [];
+
+  function push(x: number, y: number): void {
+    if (Number.isFinite(x) && Number.isFinite(y)) {
+      xs.push(x);
+      ys.push(y);
+    }
+  }
+
+  function attr(tag: string, name: string): number | null {
+    const m = tag.match(new RegExp(`\\b${name}="([^"]*)"`));
+    if (!m) return null;
+    const n = parseFloat(m[1]!);
+    return Number.isFinite(n) ? n : null;
+  }
+
+  // <rect x y width height>
+  for (const m of svg.matchAll(/<rect\b[^>]*?\/?>/g)) {
+    const tag = m[0];
+    const x = attr(tag, 'x');
+    const y = attr(tag, 'y');
+    const w = attr(tag, 'width');
+    const h = attr(tag, 'height');
+    if (x !== null && y !== null && w !== null && h !== null) {
+      push(x, y);
+      push(x + w, y + h);
+    }
+  }
+
+  // <line x1 y1 x2 y2>
+  for (const m of svg.matchAll(/<line\b[^>]*?\/?>/g)) {
+    const tag = m[0];
+    const x1 = attr(tag, 'x1');
+    const y1 = attr(tag, 'y1');
+    const x2 = attr(tag, 'x2');
+    const y2 = attr(tag, 'y2');
+    if (x1 !== null && y1 !== null && x2 !== null && y2 !== null) {
+      push(x1, y1);
+      push(x2, y2);
+    }
+  }
+
+  // <circle cx cy r>
+  for (const m of svg.matchAll(/<circle\b[^>]*?\/?>/g)) {
+    const tag = m[0];
+    const cx = attr(tag, 'cx');
+    const cy = attr(tag, 'cy');
+    const r = attr(tag, 'r');
+    if (cx !== null && cy !== null && r !== null) {
+      push(cx - r, cy - r);
+      push(cx + r, cy + r);
+    }
+  }
+
+  // <ellipse cx cy rx ry>
+  for (const m of svg.matchAll(/<ellipse\b[^>]*?\/?>/g)) {
+    const tag = m[0];
+    const cx = attr(tag, 'cx');
+    const cy = attr(tag, 'cy');
+    const rx = attr(tag, 'rx');
+    const ry = attr(tag, 'ry');
+    if (cx !== null && cy !== null && rx !== null && ry !== null) {
+      push(cx - rx, cy - ry);
+      push(cx + rx, cy + ry);
+    }
+  }
+
+  // <text x y>some content</text>
+  // Approximate width: text content length × an empirical font width factor.
+  // dgmo uses Inter ~14px by default; ~7px per character is a usable rough
+  // estimate that won't drastically under- or over-count.
+  for (const m of svg.matchAll(/<text\b([^>]*?)>([\s\S]*?)<\/text>/g)) {
+    const tag = `<text${m[1]}>`;
+    const text = m[2]!.replace(/<[^>]+>/g, ''); // strip inner tags (tspan, etc.)
+    const x = attr(tag, 'x');
+    const y = attr(tag, 'y');
+    if (x !== null && y !== null) {
+      const w = text.length * 7;
+      // text-anchor may be start/middle/end; assume worst case (middle).
+      push(x - w / 2, y - 14);
+      push(x + w / 2, y + 4);
+    }
+  }
+
+  // <path d="..."> — pull every coordinate pair out of the d attribute.
+  for (const m of svg.matchAll(/<path\b[^>]*?\bd="([^"]+)"/g)) {
+    const d = m[1]!;
+    const nums = d.match(/-?\d+(?:\.\d+)?/g);
+    if (!nums) continue;
+    for (let i = 0; i + 1 < nums.length; i += 2) {
+      push(parseFloat(nums[i]!), parseFloat(nums[i + 1]!));
+    }
+  }
+
+  // <polygon points="x,y x,y ..."> and <polyline>
+  for (const m of svg.matchAll(
+    /<(?:polygon|polyline)\b[^>]*?\bpoints="([^"]+)"/g
+  )) {
+    const nums = m[1]!.match(/-?\d+(?:\.\d+)?/g);
+    if (!nums) continue;
+    for (let i = 0; i + 1 < nums.length; i += 2) {
+      push(parseFloat(nums[i]!), parseFloat(nums[i + 1]!));
+    }
+  }
+
+  if (xs.length === 0 || ys.length === 0) return null;
+
+  const minX = Math.min(...xs);
+  const maxX = Math.max(...xs);
+  const minY = Math.min(...ys);
+  const maxY = Math.max(...ys);
+
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}