@diagrammo/dgmo 0.30.0 → 0.32.0

package/src/map/renderer.ts

@@ -135,7 +135,8 @@ function coastlineOuterRings(
 ): string[] {
   const paths: string[] = [];
   for (const r of regions) {
-    const rings = parsePathRings(r.d);
+    // Reuse the rings parsed once in layoutMap; fall back for older layouts.
+    const rings = (r.rings as Array<Array<[number, number]>>) ?? parsePathRings(r.d);
     for (let i = 0; i < rings.length; i++) {
       const ring = rings[i]!;
       if (ring.length < 3) continue;
@@ -219,6 +220,15 @@ function appendWaterLines(
   }
 }
 
+// Per-render namespace for SVG def ids (clipPaths, masks, filters, markers, the
+// `<use>`-shared coast path). SVG `url(#id)` / `href="#id"` resolve document-
+// globally to the FIRST matching id, so when several maps are inlined on one
+// page (the docs gallery, an MDX page) shared constant ids made every later map
+// reference the first map's defs — its coast `<use>` ghosted through. A
+// monotonic per-render suffix makes every render's ids unique. NOT reset between
+// renders, so re-renders (legend flips) and same-page siblings never collide.
+let mapInstanceCounter = 0;
+
 /** Render a resolved map into `container` (d3-selection appends an `<svg>`). */
 export function renderMap(
   container: HTMLDivElement,
@@ -283,6 +293,10 @@ export function renderMap(
   // arrowhead up to a giant wedge. The size grows gently with the line width —
   // enough to stay distinct from the stroke — but is firmly capped.
   const defs = svg.append('defs');
+  // Namespace every def id minted below so multiple maps on one page don't share
+  // `url(#…)` targets (see mapInstanceCounter).
+  const uid = mapInstanceCounter++;
+  const nid = (base: string): string => `${base}__m${uid}`;
   // Dampened: ~8px at the thinnest leg, easing toward a 15px cap as legs widen.
   const arrowSize = (w: number): number => Math.min(15, 7 + w * 0.95);
 
@@ -356,8 +370,8 @@ export function renderMap(
   // sub-pixel + low-contrast so the texture stays faint. Decorative — no data attrs.
   if (layout.relief.length && layout.reliefHatch) {
     const h = layout.reliefHatch;
-    const rangeClipId = 'dgmo-relief-clip';
-    const landClipId = 'dgmo-relief-land';
+    const rangeClipId = nid('dgmo-relief-clip');
+    const landClipId = nid('dgmo-relief-land');
     const rangeClip = defs.append('clipPath').attr('id', rangeClipId);
     for (const s of layout.relief) rangeClip.append('path').attr('d', s.d);
     const landClip = defs.append('clipPath').attr('id', landClipId);
@@ -402,7 +416,7 @@ export function renderMap(
   // §24B.2, ADR-1/3/6.
   if (layout.coastlineStyle) {
     const cs = layout.coastlineStyle;
-    const maskId = 'dgmo-map-water-mask';
+    const maskId = nid('dgmo-map-water-mask');
     const mask = defs
       .append('mask')
       .attr('id', maskId)
@@ -472,7 +486,7 @@ export function renderMap(
     appendWaterLines(
       gWater,
       defs,
-      'dgmo-map-coast',
+      nid('dgmo-map-coast'),
       // 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.
@@ -565,7 +579,7 @@ export function renderMap(
     (l) => l.poiId !== undefined && !l.hidden
   );
   if (poiLabels.length) {
-    const patchBlurId = 'dgmo-map-label-patch-blur';
+    const patchBlurId = nid('dgmo-map-label-patch-blur');
     // Soft falloff so the patch dissolves into the surrounding basemap instead of
     // ending on a hard edge. Tuned at the 11px label font. One shared filter for
     // every patch group.
@@ -668,17 +682,27 @@ export function renderMap(
       // label, so the patch is seamless and the only visible change is the
       // vanished line work.
       for (const r of layout.regions) {
-        let minX = Infinity,
-          minY = Infinity,
-          maxX = -Infinity,
+        // bbox is precomputed once in layoutMap (roadmap #2); fall back to
+        // parsing only for layouts predating that field.
+        let minX: number,
+          minY: number,
+          maxX: number,
+          maxY: number;
+        if (r.bbox) {
+          [minX, minY, maxX, maxY] = r.bbox;
+        } else {
+          minX = Infinity;
+          minY = Infinity;
+          maxX = -Infinity;
           maxY = -Infinity;
-        for (const ring of parsePathRings(r.d))
-          for (const [px, py] of ring) {
-            if (px < minX) minX = px;
-            if (px > maxX) maxX = px;
-            if (py < minY) minY = py;
-            if (py > maxY) maxY = py;
-          }
+          for (const ring of parsePathRings(r.d))
+            for (const [px, py] of ring) {
+              if (px < minX) minX = px;
+              if (px > maxX) maxX = px;
+              if (py < minY) minY = py;
+              if (py > maxY) maxY = py;
+            }
+        }
         const hit = blobRects.some(
           (b) => minX <= b.x1 && maxX >= b.x0 && minY <= b.y1 && maxY >= b.y0
         );
@@ -690,7 +714,7 @@ export function renderMap(
       // Always-on patch for labels that are visible at rest (non-cluster members).
       buildPatch(
         poiLabels.filter((l) => l.clusterMember === undefined),
-        'dgmo-map-label-patch'
+        nid('dgmo-map-label-patch')
       );
       // Per-cluster patches, hidden until the fan expands.
       const byCluster = new Map<string, typeof poiLabels>();
@@ -705,11 +729,11 @@ export function renderMap(
       // data-cluster-deco attribute instead.
       let ci = 0;
       for (const [cid, labs] of byCluster)
-        buildPatch(labs, `dgmo-map-label-patch-c${ci++}`, cid);
+        buildPatch(labs, nid(`dgmo-map-label-patch-c${ci++}`), cid);
     } else {
       // Export / `no-cluster-pois`: fan is permanently open → one always-on patch
       // over every POI label.
-      buildPatch(poiLabels, 'dgmo-map-label-patch');
+      buildPatch(poiLabels, nid('dgmo-map-label-patch'));
     }
   }
 
@@ -734,7 +758,7 @@ export function renderMap(
       // Neighbour land (Canada beside Alaska) clipped to this box, behind the
       // state — so a land border reads as land rather than sprouting coast rings.
       if (box.contextLand) {
-        const clipId = `dgmo-map-inset-clip-${bi}`;
+        const clipId = nid(`dgmo-map-inset-clip-${bi}`);
         defs.append('clipPath').attr('id', clipId).append('path').attr('d', d);
         insetG
           .append('path')
@@ -751,7 +775,7 @@ export function renderMap(
     // same way. Inside the inset group so it composites over the box fills.
     if (layout.coastlineStyle) {
       const cs = layout.coastlineStyle;
-      const maskId = 'dgmo-map-inset-water-mask';
+      const maskId = nid('dgmo-map-inset-water-mask');
       const mask = defs
         .append('mask')
         .attr('id', maskId)
@@ -786,7 +810,7 @@ export function renderMap(
             .append('path')
             .attr('d', box.contextLand.d)
             .attr('fill', 'black')
-            .attr('clip-path', `url(#dgmo-map-inset-clip-${bi})`);
+            .attr('clip-path', `url(#${nid(`dgmo-map-inset-clip-${bi}`)})`);
       });
       for (const r of layout.insetRegions)
         if (r.id !== 'lake')
@@ -798,7 +822,7 @@ export function renderMap(
       // which side reads as water, but SVG strokes still extend stroke-width/2
       // past their path, so without this the seaward rings bleed over the box
       // border. Union of all inset quads = one clipPath shared by the group.
-      const clipId = 'dgmo-map-inset-water-clip';
+      const clipId = nid('dgmo-map-inset-water-clip');
       const clip = defs.append('clipPath').attr('id', clipId);
       for (const box of layout.insets) {
         const d =
@@ -820,7 +844,7 @@ export function renderMap(
       appendWaterLines(
         gInsetWater,
         defs,
-        'dgmo-map-inset-coast',
+        nid('dgmo-map-inset-coast'),
         coastlineOuterRings(layout.insetRegions, cs.minExtent),
         cs,
         layout.background
@@ -895,7 +919,7 @@ export function renderMap(
     // stroke is enough for the line widths legs use.
     wireSync(p, leg.lineNumber);
     if (leg.arrow) {
-      const id = `dgmo-map-arrow-${i}`;
+      const id = nid(`dgmo-map-arrow-${i}`);
       const s = arrowSize(leg.width);
       defs
         .append('marker')

package/src/map/resolver.ts

@@ -68,12 +68,44 @@ const POI_ZOOM_FLOOR_DEG = 7;
 // 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;
+// union so it reveals at most `containerOvershoot(cluster)` degrees of container
+// BEYOND the POI cluster on each side: northern Colombia stays for orientation,
+// the empty interior is cropped.
+//
+// For NON-US clusters the overshoot SHRINKS as the cluster grows (tuned
+// 2026-06-19). A tiny cluster has no context of its own, so it keeps the full MAX
+// (8°) — enough to reveal its whole modest container (e.g. a small European
+// country). A LARGE cluster already supplies its own context, so a fixed 8° just
+// padded a huge container with empty land (a Ukraine/Russia strike map framed
+// ~2.4× the cluster, a wide dead band above the dots). Linearly decaying the
+// overshoot to MIN (3°) tightens big clusters (~1.7× cluster) without cropping
+// small ones. The POI_ZOOM_FLOOR_DEG floor still guards the lower bound.
+//
+// US-ORIENTED maps are EXEMPT (keep the flat MAX): the national-vs-regional
+// projection gate (US_NATIONAL_LON_SPAN, albers-usa vs regional Mercator) is
+// calibrated against the 8°-overshoot frame span — a coast-to-Caribbean US cruise
+// route clears the national threshold only because the west overshoot reaches ~8°
+// past Denver. Shrinking it there would silently flip such maps off albers-usa.
+// US containers (a state, CONUS) aren't the huge-empty-container problem anyway.
+const CONTAINER_OVERSHOOT_MAX = 8;
+const CONTAINER_OVERSHOOT_MIN = 3;
+// Degrees of overshoot shed per degree of cluster span (larger span ⇒ less slack).
+const CONTAINER_OVERSHOOT_DECAY = 0.3;
+
+/** Per-cluster container overshoot (deg). US-oriented maps keep the flat MAX (the
+ *  albers-usa national gate is calibrated to it); other maps get full MAX for a
+ *  tight cluster, decaying to MIN for a large one. `span` = the cluster's larger
+ *  lon/lat extent. */
+function containerOvershoot(span: number, usOriented: boolean): number {
+  if (usOriented) return CONTAINER_OVERSHOOT_MAX;
+  return Math.max(
+    CONTAINER_OVERSHOOT_MIN,
+    Math.min(
+      CONTAINER_OVERSHOOT_MAX,
+      CONTAINER_OVERSHOOT_MAX - CONTAINER_OVERSHOOT_DECAY * span
+    )
+  );
+}
 // 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.
@@ -907,7 +939,7 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
     const containerUnion = unionExtent(containerBoxes, points);
     if (containerUnion)
       extent = pad(
-        clampContainerToCluster(containerUnion, points),
+        clampContainerToCluster(containerUnion, points, usOriented),
         PAD_FRACTION
       );
   }
@@ -1079,25 +1111,42 @@ function mostCommonCountry(
 /** 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. */
+ *  extends BEYOND the POI cluster on each side at CONTAINER_OVERSHOOT_DEG, while
+ *  letting a genuinely tighter container edge still bound the frame (so a small
+ *  country shows whole, but a cluster inside a giant one stays on the cluster).
+ *
+ *  Each longitude side clamps independently. A container edge is a usable outer
+ *  bound only when it sits within the normal [-180, 180] range AND on the correct
+ *  side of the cluster; an antimeridian-crossing container (Russia, Fiji, NZ, the
+ *  US via the Aleutians) reports a degenerate east (> 180, or numerically < its
+ *  own west), so that side falls back to cluster ± overshoot instead of skipping
+ *  the clamp entirely (which previously blew a western-Russia cluster out to a
+ *  world frame). Latitude never wraps, so it always clamps. Assumes the POI
+ *  cluster itself does not straddle the seam — true for any regional cluster. */
 function clampContainerToCluster(
   container: GeoExtent,
-  points: Array<[number, number]>
+  points: Array<[number, number]>,
+  usOriented: boolean
 ): 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);
-  }
+  // Overshoot shrinks with cluster size for non-US maps (see containerOvershoot):
+  // a big cluster already orients itself, so it gets less surrounding slack than a
+  // tiny one. US-oriented maps keep the flat MAX (the albers-usa gate needs it).
+  const over = containerOvershoot(
+    Math.max(pEast - pWest, pNorth - pSouth),
+    usOriented
+  );
+  south = Math.max(south, pSouth - over);
+  north = Math.min(north, pNorth + over);
+  const wOver = pWest - over;
+  const eOver = pEast + over;
+  // West edge usable iff in range and not east of the cluster's west.
+  west = west >= -180 && west <= pWest ? Math.max(west, wOver) : wOver;
+  // East edge usable iff in range and not west of the cluster's east.
+  east = east <= 180 && east >= pEast ? Math.min(east, eOver) : eOver;
   return [
     [west, south],
     [east, north],

package/src/mindmap/parser.ts

@@ -3,6 +3,7 @@ import {
   descriptionBareRemovedMessage,
   formatDgmoError,
   makeDgmoError,
+  makeFail,
   METADATA_DIAGNOSTIC_CODES,
   pipeOperatorRemovedMessage,
   suggest,
@@ -16,6 +17,7 @@ import {
   validateTagGroupNames,
   stripDefaultModifier,
   finalizeAutoTagColors,
+  cascadeTagMetadata,
   AUTO_TAG_COLOR_SENTINEL,
 } from '../utils/tag-groups';
 import {
@@ -60,12 +62,7 @@ export function parseMindmap(
     error: null,
   };
 
-  const fail = (line: number, message: string): ParsedMindmap => {
-    const diag = makeDgmoError(line, message);
-    result.diagnostics.push(diag);
-    result.error = formatDgmoError(diag);
-    return result;
-  };
+  const fail = makeFail(result);
 
   const pushError = (line: number, message: string): void => {
     const diag = makeDgmoError(line, message);
@@ -210,7 +207,12 @@ export function parseMindmap(
       const indent = measureIndent(line);
       if (indent > 0) {
         const { text: cleanEntry, isDefault } = stripDefaultModifier(trimmed);
-        const { label, color } = extractColor(cleanEntry, palette);
+        const { label, color } = extractColor(
+          cleanEntry,
+          palette,
+          result.diagnostics,
+          lineNumber
+        );
         // Bare value (no explicit color) → keep it; finalized below.
         if (isDefault) {
           currentTagGroup.defaultValue = label;
@@ -307,6 +309,12 @@ export function parseMindmap(
     collectAll(result.roots);
     validateTagValues(allNodes, result.tagGroups, pushWarning, suggest);
     validateTagGroupNames(result.tagGroups, pushWarning);
+
+    // Cascade explicit tag values down the tree so sub-nodes inherit a tagged
+    // ancestor's value (overridable per-node). Runs after validation (so we
+    // don't double-warn on inherited values) and before the layout's
+    // global-default injection (so an inherited value wins over the default).
+    cascadeTagMetadata(result.roots, result.tagGroups);
   }
 
   // Check for empty mindmap

package/src/mindmap/renderer.ts

@@ -35,9 +35,11 @@ const LABEL_LINE_HEIGHT = 18;
 const DESC_LINE_HEIGHT = 14;
 const NODE_RADIUS = 6;
 const ROOT_STROKE_WIDTH = 2.5;
-const NODE_STROKE_WIDTH = 1.5;
-const EDGE_STROKE_WIDTH = 1.5;
-const COLLAPSE_BAR_HEIGHT = 6;
+import {
+  NODE_STROKE_WIDTH,
+  EDGE_STROKE_WIDTH,
+  COLLAPSE_BAR_HEIGHT,
+} from '../utils/visual-conventions'; // shared (Story 111.1)
 
 function nodeFill(
   palette: PaletteColors,
@@ -147,9 +149,16 @@ export function renderMindmap(
   const availHeight =
     containerHeight - DIAGRAM_PADDING * 2 - legendReserve - titleReserve;
 
-  const ctx = isExport
+  // Fit to BOTH axes so a tall tree shrinks to fit a short canvas instead of
+  // overflowing vertically (export sizes its own canvas, so it stays identity).
+  let ctx = isExport
     ? ScaleContext.identity()
-    : ScaleContext.from(availWidth, layout.width);
+    : ScaleContext.fromBox(
+        availWidth,
+        layout.width,
+        availHeight,
+        layout.height
+      );
 
   let renderLayout = layout;
   if (ctx.factor < 1) {
@@ -159,25 +168,56 @@ export function renderMindmap(
         hiddenCounts.set(n.id, n.hiddenCount);
       }
     }
-    renderLayout = layoutMindmap(parsed, palette, {
-      interactive: !isExport,
-      ...(hiddenCounts.size > 0 && { hiddenCounts }),
-      activeTagGroup: activeTagGroup ?? null,
-      ...(hideDescriptions !== undefined && { hideDescriptions }),
-      ctx,
-    });
+    const relayout = (c: ScaleContext): MindmapLayoutResult =>
+      layoutMindmap(parsed, palette, {
+        interactive: !isExport,
+        ...(hiddenCounts.size > 0 && { hiddenCounts }),
+        activeTagGroup: activeTagGroup ?? null,
+        ...(hideDescriptions !== undefined && { hideDescriptions }),
+        ctx: c,
+      });
+    renderLayout = relayout(ctx);
+    // Scaling is non-linear, so one pass can still overflow. Re-measure the
+    // laid-out result and tighten until it fits both axes or hits the floor.
+    for (let i = 0; i < 3 && !ctx.isBelowFloor; i++) {
+      const refit = Math.min(
+        availWidth / renderLayout.width,
+        availHeight / renderLayout.height
+      );
+      if (refit >= 0.999) break; // already fits
+      ctx = ScaleContext.fromFactor(ctx.factor * refit);
+      renderLayout = relayout(ctx);
+    }
   }
 
-  const offsetX = Math.max(0, (availWidth - renderLayout.width) / 2);
+  // Re-layout keeps text readable but is floor-limited, so a dense tree can
+  // still exceed the canvas. Apply a final uniform scale as a hard guarantee
+  // that the diagram always fits within the canvas (no overflow), regardless
+  // of how small the canvas is. Export sizes its own canvas, so this is a no-op
+  // there (fitScale === 1).
+  const fitScale = isExport
+    ? 1
+    : Math.min(
+        1,
+        renderLayout.width > 0 ? availWidth / renderLayout.width : 1,
+        renderLayout.height > 0 ? availHeight / renderLayout.height : 1
+      );
+  const scaledWidth = renderLayout.width * fitScale;
+  const scaledHeight = renderLayout.height * fitScale;
+
+  const offsetX = Math.max(0, (availWidth - scaledWidth) / 2);
   const offsetY =
     DIAGRAM_PADDING +
     legendReserve +
     titleReserve +
-    Math.max(0, (availHeight - renderLayout.height) / 2);
+    Math.max(0, (availHeight - scaledHeight) / 2);
 
   const mainG = svg
     .append('g')
-    .attr('transform', `translate(${offsetX}, ${offsetY})`);
+    .attr(
+      'transform',
+      `translate(${offsetX}, ${offsetY})${fitScale < 1 ? ` scale(${fitScale})` : ''}`
+    );
 
   if (ctx.isBelowFloor) {
     svg.attr('width', '100%');

package/src/org/parser.ts

@@ -3,6 +3,7 @@ import type { DgmoError } from '../diagnostics';
 import {
   formatDgmoError,
   makeDgmoError,
+  makeFail,
   METADATA_DIAGNOSTIC_CODES,
   pipeOperatorRemovedMessage,
   suggest,
@@ -107,12 +108,7 @@ export function parseOrg(content: string, palette?: PaletteColors): ParsedOrg {
     error: null,
   };
 
-  const fail = (line: number, message: string): ParsedOrg => {
-    const diag = makeDgmoError(line, message);
-    result.diagnostics.push(diag);
-    result.error = formatDgmoError(diag);
-    return result;
-  };
+  const fail = makeFail(result);
 
   /** Push a recoverable error and continue parsing. */
   const pushError = (line: number, message: string): void => {
@@ -261,7 +257,12 @@ export function parseOrg(content: string, palette?: PaletteColors): ParsedOrg {
       const indent = measureIndent(line);
       if (indent > 0) {
         const { text: cleanEntry, isDefault } = stripDefaultModifier(trimmed);
-        const { label, color } = extractColor(cleanEntry, palette);
+        const { label, color } = extractColor(
+          cleanEntry,
+          palette,
+          result.diagnostics,
+          lineNumber
+        );
         // Bare value (no explicit color) → keep it; the post-parse
         // finalize pass assigns a deterministic palette color.
         if (isDefault) {