@diagrammo/dgmo 0.31.0 → 0.32.0

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

@@ -149,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) {
@@ -161,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) {

package/src/org/renderer.ts

@@ -10,7 +10,12 @@ import {
 } from '../utils/export-container';
 import { ScaleContext } from '../utils/scaling';
 import type { PaletteColors } from '../palettes';
-import { contrastText, mix, shapeFill } from '../palettes/color-utils';
+import {
+  contrastText,
+  mix,
+  shapeFill,
+  themeBaseBg,
+} from '../palettes/color-utils';
 import { resolveTagColor } from '../utils/tag-groups';
 import type { ParsedOrg } from './parser';
 import type { OrgLayoutResult } from './layout';
@@ -93,7 +98,7 @@ function containerFill(
   nodeColor?: string
 ): string {
   if (nodeColor) {
-    return mix(nodeColor, isDark ? palette.surface : palette.bg, 10);
+    return mix(nodeColor, themeBaseBg(palette, isDark), 10);
   }
   return mix(palette.surface, palette.bg, 40);
 }
@@ -397,6 +402,13 @@ export function renderOrg(
         .attr('height', iconSize + 6)
         .attr('fill', 'transparent');
 
+      // Use the container's contrast text color so it stays legible on darker
+      // fills, mirroring the node icon.
+      const iconColor = contrastText(
+        fill,
+        palette.textOnFillLight,
+        palette.textOnFillDark
+      );
       const cx = iconSize / 2;
       const cy = iconSize / 2;
       focusG
@@ -405,14 +417,14 @@ export function renderOrg(
         .attr('cy', cy)
         .attr('r', iconSize / 2 - 1)
         .attr('fill', 'none')
-        .attr('stroke', palette.textMuted)
+        .attr('stroke', iconColor)
         .attr('stroke-width', 1.5);
       focusG
         .append('circle')
         .attr('cx', cx)
         .attr('cy', cy)
         .attr('r', 2)
-        .attr('fill', palette.textMuted);
+        .attr('fill', iconColor);
     }
   }
 
@@ -558,7 +570,10 @@ export function renderOrg(
         .attr('height', iconSize + 6)
         .attr('fill', 'transparent');
 
-      // Scope/target icon: outer circle + inner dot
+      // Scope/target icon: outer circle + inner dot. Use the card's contrast
+      // text color so it stays legible on solid-fill dark cards, not just the
+      // light default surface.
+      const iconColor = labelColor;
       const cx = iconSize / 2;
       const cy = iconSize / 2;
       focusG
@@ -567,14 +582,14 @@ export function renderOrg(
         .attr('cy', cy)
         .attr('r', iconSize / 2 - 1)
         .attr('fill', 'none')
-        .attr('stroke', palette.textMuted)
+        .attr('stroke', iconColor)
         .attr('stroke-width', 1.5);
       focusG
         .append('circle')
         .attr('cx', cx)
         .attr('cy', cy)
         .attr('r', 2)
-        .attr('fill', palette.textMuted);
+        .attr('fill', iconColor);
     }
   }
 

package/src/palettes/color-utils.ts

@@ -305,6 +305,16 @@ export function contrastText(
  * `opts.solid` (per `option solid-fill`): bypass the 25% tint and return
  * the raw intent. Opt-in only; default behavior unchanged.
  */
+/**
+ * The theme-aware base background a diagram's tinted shapes blend toward:
+ * `surface` in dark, page `bg` in light. Concentrates the
+ * `isDark ? palette.surface : palette.bg` pick repeated across ~20 renderers
+ * (Story 111.3).
+ */
+export function themeBaseBg(palette: PaletteColors, isDark: boolean): string {
+  return isDark ? palette.surface : palette.bg;
+}
+
 export function shapeFill(
   palette: PaletteColors,
   intent: string,
@@ -312,7 +322,7 @@ export function shapeFill(
   opts?: { solid?: boolean }
 ): string {
   if (opts?.solid) return intent;
-  return mix(intent, isDark ? palette.surface : palette.bg, 25);
+  return mix(intent, themeBaseBg(palette, isDark), 25);
 }
 
 // ============================================================
@@ -408,7 +418,7 @@ export function politicalTints(
   isDark: boolean
 ): string[] {
   if (count <= 0) return [];
-  const base = isDark ? palette.surface : palette.bg;
+  const base = themeBaseBg(palette, isDark);
   const c = palette.colors;
   // Land-first: greens/earth tones lead; water-like blue & cyan trail.
   const swatches = [

package/src/palettes/index.ts

@@ -21,6 +21,7 @@ export {
   getSegmentColors,
   contrastText,
   shapeFill,
+  themeBaseBg,
 } from './color-utils';
 
 // Re-export palette definitions (alphabetical)

package/src/pert/renderer.ts

@@ -33,7 +33,7 @@ import * as d3Selection from 'd3-selection';
 import * as d3Shape from 'd3-shape';
 import { FONT_FAMILY } from '../fonts';
 import type { PaletteColors } from '../palettes';
-import { contrastText, mix, shapeFill } from '../palettes/color-utils';
+import { contrastText, mix, shapeFill, themeBaseBg } from '../palettes/color-utils';
 import { ScaleContext } from '../utils/scaling';
 import {
   measureText,
@@ -108,7 +108,7 @@ function analysisBlockChrome(
   palette: PaletteColors,
   isDark: boolean
 ): { fill: string; stroke: string } {
-  const surfaceBg = isDark ? palette.surface : palette.bg;
+  const surfaceBg = themeBaseBg(palette, isDark);
   return {
     fill: mix(palette.surface, palette.bg, 40),
     stroke: mix(palette.textMuted, surfaceBg, 35),

package/src/pyramid/parser.ts

@@ -4,8 +4,8 @@
 
 import {
   bareDescriptionRemovedMessage,
-  formatDgmoError,
   makeDgmoError,
+  makeFail,
   METADATA_DIAGNOSTIC_CODES,
   pipeOperatorRemovedMessage,
 } from '../diagnostics';
@@ -61,12 +61,7 @@ export function parsePyramid(content: string): ParsedPyramid {
   let headerParsed = false;
   let currentLayer: Writable<PyramidLayer> | null = null;
 
-  const fail = (line: number, message: string): ParsedPyramid => {
-    const diag = makeDgmoError(line, message);
-    result.diagnostics.push(diag);
-    result.error = formatDgmoError(diag);
-    return result;
-  };
+  const fail = makeFail(result);
 
   const warn = (
     line: number,

package/src/quadrant/renderer.ts

@@ -11,7 +11,7 @@ import { ScaleContext } from '../utils/scaling';
 import { initD3Chart, renderChartTitle } from '../utils/d3-helpers';
 import type { ParsedQuadrant, QuadrantLabel } from '../visualizations/types';
 import type { PaletteColors } from '../palettes';
-import { mix } from '../palettes/color-utils';
+import { mix, themeBaseBg } from '../palettes/color-utils';
 
 // Quadrant Chart Renderer
 // ============================================================
@@ -99,7 +99,7 @@ export function renderQuadrant(
     .append('g')
     .attr('transform', `translate(${margin.left}, ${margin.top})`);
 
-  const bg = isDark ? palette.surface : palette.bg;
+  const bg = themeBaseBg(palette, isDark);
 
   // Full palette color for a quadrant (used for border and label tinting)
   const getQuadrantColor = (

package/src/raci/parser.ts

@@ -19,8 +19,8 @@
 // See `docs/dgmo-language-spec.md` § "RACI Matrix".
 
 import {
-  formatDgmoError,
   makeDgmoError,
+  makeFail,
   METADATA_DIAGNOSTIC_CODES,
   pipeOperatorRemovedMessage,
   suggest,
@@ -181,12 +181,7 @@ export function parseRaci(
     error: null,
   };
 
-  const fail = (line: number, message: string): ParsedRaci => {
-    const diag = makeDgmoError(line, message);
-    result.diagnostics.push(diag);
-    result.error = formatDgmoError(diag);
-    return result;
-  };
+  const fail = makeFail(result);
 
   const warn = (line: number, message: string, code?: string): void => {
     result.diagnostics.push(makeDgmoError(line, message, 'warning', code));

package/src/raci/renderer.ts

@@ -30,7 +30,7 @@ import {
   TITLE_FONT_WEIGHT,
   TITLE_Y,
 } from '../utils/title-constants';
-import { contrastText, mix } from '../palettes/color-utils';
+import { contrastText, mix, themeBaseBg } from '../palettes/color-utils';
 import type { PaletteColors } from '../palettes';
 import type { D3ExportDimensions } from '../utils/d3-types';
 import type {
@@ -394,7 +394,7 @@ export function renderRaci(
   if (tasksAll.length === 0 && parsed.phases.length === 0) return;
 
   const solid = parsed.options['solid-fill'] === 'on';
-  const surfaceBg = isDark ? palette.surface : palette.bg;
+  const surfaceBg = themeBaseBg(palette, isDark);
 
   // --- ScaleContext: differential scaling ---
   const roleCount = Math.max(1, parsed.roles.length);
@@ -679,10 +679,10 @@ export function renderRaci(
     // each column has a subtle visual identity instead of every column
     // reading as the same neutral gray.
     const roleColor = parsed.roleColors[i] ?? autoAccent(i, palette);
-    const bodyFill = mix(roleColor, isDark ? palette.surface : palette.bg, 16);
+    const bodyFill = mix(roleColor, themeBaseBg(palette, isDark), 16);
     const headerFill = mix(
       roleColor,
-      isDark ? palette.surface : palette.bg,
+      themeBaseBg(palette, isDark),
       30
     );
     const colG = columnsG

package/src/ring/parser.ts

@@ -4,8 +4,8 @@
 
 import {
   bareDescriptionRemovedMessage,
-  formatDgmoError,
   makeDgmoError,
+  makeFail,
   METADATA_DIAGNOSTIC_CODES,
   pipeOperatorRemovedMessage,
   suggest,
@@ -48,12 +48,7 @@ export function parseRing(content: string): ParsedRing {
   let headerParsed = false;
   let currentLayer: Writable<RingLayer> | null = null;
 
-  const fail = (line: number, message: string): ParsedRing => {
-    const diag = makeDgmoError(line, message);
-    result.diagnostics.push(diag);
-    result.error = formatDgmoError(diag);
-    return result;
-  };
+  const fail = makeFail(result);
 
   const warn = (
     line: number,

package/src/sequence/parser.ts

@@ -10,6 +10,7 @@ import {
   akaRemovedMessage,
   formatDgmoError,
   makeDgmoError,
+  makeFail,
   METADATA_DIAGNOSTIC_CODES,
   NAME_DIAGNOSTIC_CODES,
   nameMergedMessage,
@@ -528,12 +529,7 @@ export function parseSequenceDgmo(
     return nameAliasMap.get(trimmed) ?? trimmed;
   };
 
-  const fail = (line: number, message: string): ParsedSequenceDgmo => {
-    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 => {
@@ -554,6 +550,13 @@ export function parseSequenceDgmo(
   const lines = content.split('\n');
   let hasExplicitChart = false;
   let contentStarted = false;
+  // Whether the message body has begun (first message, section, block, or note).
+  // Unlike `contentStarted` — which any declaration trips to close the
+  // options/tag-group "headers first" window — `bodyStarted` stays false through
+  // the entire declaration preamble so bare and typed participant declarations
+  // can be freely interleaved. It gates bare-name declarations: once real body
+  // content appears, a bare word is treated as a stray line, not a participant.
+  let bodyStarted = false;
   let firstLineIndex = -1; // line index of the `sequence [Title]` first line (to skip in main loop)
 
   // Handle first non-empty, non-comment line for `sequence Title` syntax
@@ -997,6 +1000,7 @@ export function parseSequenceDgmo(
         );
       }
       contentStarted = true;
+      bodyStarted = true;
       const section: SequenceSection = {
         kind: 'section',
         // Capture group 1 guaranteed present after successful match.
@@ -1301,7 +1305,7 @@ export function parseSequenceDgmo(
       if (
         /^\S+$/.test(bareCore) &&
         !ARROW_PATTERN.test(bareCore) &&
-        (inGroup || !contentStarted || bareMeta)
+        (inGroup || !bodyStarted || bareMeta)
       ) {
         contentStarted = true;
         const id = bareCore;
@@ -1369,6 +1373,7 @@ export function parseSequenceDgmo(
     }
     if (labeledArrow) {
       contentStarted = true;
+      bodyStarted = true;
       const { from, to, label: rawLabel, async: isAsync } = labeledArrow;
       const fromKey = addParticipant(resolveAlias(from), lineNumber);
       const toKey = addParticipant(resolveAlias(to), lineNumber);
@@ -1445,6 +1450,7 @@ export function parseSequenceDgmo(
     const bareCall = bareCallSync || bareCallAsync;
     if (bareCall) {
       contentStarted = true;
+      bodyStarted = true;
       // Capture groups 1 and 2 guaranteed present after successful match.
       const from = bareCall[1]!;
       const to = bareCall[2]!;
@@ -1470,6 +1476,7 @@ export function parseSequenceDgmo(
     const ifMatch = trimmed.match(/^if\s+(.+)$/i);
     if (ifMatch) {
       contentStarted = true;
+      bodyStarted = true;
       const block: Writable<SequenceBlock> = {
         kind: 'block',
         type: 'if',
@@ -1488,6 +1495,7 @@ export function parseSequenceDgmo(
     const loopMatch = trimmed.match(/^loop\s+(.+)$/i);
     if (loopMatch) {
       contentStarted = true;
+      bodyStarted = true;
       const block: Writable<SequenceBlock> = {
         kind: 'block',
         type: 'loop',
@@ -1506,6 +1514,7 @@ export function parseSequenceDgmo(
     const parallelMatch = trimmed.match(/^parallel(?:\s+(.+))?$/i);
     if (parallelMatch) {
       contentStarted = true;
+      bodyStarted = true;
       const block: Writable<SequenceBlock> = {
         kind: 'block',
         type: 'parallel',
@@ -1629,6 +1638,7 @@ export function parseSequenceDgmo(
             lineNumber,
             endLineNumber: lineNumber,
           };
+          bodyStarted = true;
           currentContainer().push(note);
           continue;
         }
@@ -1654,6 +1664,7 @@ export function parseSequenceDgmo(
             lineNumber,
             endLineNumber: i + 1, // i has advanced past the body lines (1-based)
           };
+          bodyStarted = true;
           currentContainer().push(note);
           continue;
         }