@xdelivered/emberflow 0.2.0

package/src/globals.css

@@ -0,0 +1,147 @@
+@import 'tailwindcss';
+@import 'tw-animate-css';
+
+@theme inline {
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-tertiary: var(--tertiary);
+  --color-tertiary-active: var(--tertiary-active);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-highlight: var(--highlight);
+  --color-highlight-foreground: var(--highlight-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-success: var(--success);
+  --color-warn: var(--warn);
+  --font-sans: 'Inter Variable', 'Inter', ui-sans-serif, system-ui, sans-serif;
+  --font-mono: 'IBM Plex Mono', 'SF Mono', ui-monospace, Menlo, monospace;
+}
+
+/* Superset desktop "ember" theme (dark default) — tokens verbatim from
+   apps/desktop/src/renderer/globals.css in superset-sh/superset. */
+:root {
+  color-scheme: dark;
+  --background: #151110;
+  --foreground: #eae8e6;
+  --card: #201e1c;
+  --card-foreground: #eae8e6;
+  --popover: #201e1c;
+  --popover-foreground: #eae8e6;
+  --primary: #eae8e6;
+  --primary-foreground: #151110;
+  --secondary: #2a2827;
+  --secondary-foreground: #eae8e6;
+  --muted: #2a2827;
+  --muted-foreground: #a8a5a3;
+  --accent: #2a2827;
+  --accent-foreground: #eae8e6;
+  --tertiary: #1a1716;
+  --tertiary-active: #252220;
+  --destructive: #cc4444;
+  --destructive-foreground: #ffcccc;
+  --border: #2a2827;
+  --input: #2a2827;
+  --ring: #3a3837;
+  --radius: 0.625rem;
+  --sidebar: #1a1716;
+  --sidebar-foreground: #eae8e6;
+  --sidebar-primary: #e07850;
+  --sidebar-primary-foreground: #151110;
+  --sidebar-accent: #252220;
+  --sidebar-accent-foreground: #eae8e6;
+  --sidebar-border: #2a2827;
+  --sidebar-ring: #3a3837;
+  --highlight: #e07850;
+  --highlight-foreground: #151110;
+  --success: #50a878;
+  --warn: #d9a441;
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground font-sans text-[13px] antialiased;
+  }
+  ::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+  }
+  ::-webkit-scrollbar-thumb {
+    background: rgb(63 63 70 / 0.5);
+    border-radius: 6px;
+  }
+  ::-webkit-scrollbar-track {
+    background: transparent;
+  }
+}
+
+/* ── App shell ── */
+
+#root { height: 100vh; }
+
+/* Runbook step-active breathing: an ember pulse scaled down for the 9px inline
+   status square that marks the step currently being revealed. */
+.ember-step-active {
+  animation: ember-step-pulse 1.3s ease-in-out infinite;
+}
+@keyframes ember-step-pulse {
+  0%,
+  100% {
+    box-shadow:
+      0 0 0 1px rgb(224 120 80 / 0.6),
+      0 0 6px rgb(224 120 80 / 0.35);
+  }
+  50% {
+    box-shadow:
+      0 0 0 2px rgb(224 120 80 / 0.4),
+      0 0 10px rgb(224 120 80 / 0.6);
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .ember-step-active {
+    animation: none;
+    box-shadow:
+      0 0 0 2px rgb(224 120 80 / 0.5),
+      0 0 8px rgb(224 120 80 / 0.4);
+  }
+}
+
+/* Panel choreography: layout panels (sidebar toggle, dock, inspector) ease
+   into their new sizes instead of snapping. Suspended while a resize handle
+   is actively dragged so the pointer never lags, and under reduced motion. */
+[data-panel-group]:not(:has([data-resize-handle-state='drag'])) > [data-panel] {
+  transition: flex-grow 280ms cubic-bezier(0.22, 1, 0.36, 1);
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-panel-group] > [data-panel] {
+    transition: none;
+  }
+}

package/src/lib/pathParams.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { parsePathParams } from './pathParams';
+
+// The Run-guard semantics that used to live here (missingPathParams) moved to
+// src/engine/diagnostics.ts as the `missing-param-default` diagnostic; its
+// behavior contract is covered by src/engine/diagnostics.test.ts.
+
+describe('parsePathParams', () => {
+  it('extracts a single param', () => {
+    expect(parsePathParams('/api/channels/:id/approvals')).toEqual(['id']);
+  });
+
+  it('extracts multiple params in order', () => {
+    expect(parsePathParams('/api/channels/:id/approvals/:approvalId')).toEqual(['id', 'approvalId']);
+  });
+
+  it('returns empty array when there are no colon segments', () => {
+    expect(parsePathParams('/api/channels')).toEqual([]);
+  });
+
+  it('ignores standalone colons that do not start a param name', () => {
+    expect(parsePathParams('/api/channels/id')).toEqual([]);
+  });
+});

package/src/lib/pathParams.ts

@@ -0,0 +1,6 @@
+/** Extract `:name` path-param segments from an HTTP path, in order, e.g.
+ *  `/api/channels/:id/approvals/:approvalId` → `['id', 'approvalId']`. */
+export function parsePathParams(path: string): string[] {
+  const matches = path.match(/:([A-Za-z0-9_]+)/g) ?? [];
+  return matches.map((m) => m.slice(1));
+}

package/src/lib/registerLens.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { filterLogs, firstSentence, formatDuration, keyValueRows, payloadOpenByDefault, simpleNodeDescription } from './registerLens';
+import type { LogLine } from '../engine';
+
+const line = (level: LogLine['level'], message: string): LogLine => ({
+  timestamp: '2026-07-04T00:00:00Z', level, runId: 'r1', nodeId: 'n1', nodeLabel: 'N', message,
+});
+
+describe('filterLogs', () => {
+  const logs = [line('debug', '#1 ▶ execute'), line('info', 'ok'), line('warn', 'careful'), line('error', 'boom')];
+  it('simple drops debug only — warn/error always survive', () => {
+    expect(filterLogs(logs, 'simple').map((l) => l.level)).toEqual(['info', 'warn', 'error']);
+  });
+  it('technical keeps everything', () => {
+    expect(filterLogs(logs, 'technical')).toHaveLength(4);
+  });
+});
+
+describe('formatDuration', () => {
+  it('simple rounds calm', () => {
+    expect(formatDuration(337, 'simple')).toBe('340ms');
+    expect(formatDuration(4636, 'simple')).toBe('4.6s');
+    expect(formatDuration(4, 'simple')).toBe('<10ms');
+    expect(formatDuration(997, 'simple')).toBe('1.0s');
+  });
+  it('technical stays exact', () => {
+    expect(formatDuration(337, 'technical')).toBe('337ms');
+    expect(formatDuration(4636, 'technical')).toBe('4.64s');
+  });
+});
+
+describe('payloadOpenByDefault', () => {
+  it('simple collapsed, technical open', () => {
+    expect(payloadOpenByDefault('simple')).toBe(false);
+    expect(payloadOpenByDefault('technical')).toBe(true);
+  });
+});
+
+describe('keyValueRows', () => {
+  it('primitives, truncation, and shape summaries', () => {
+    const rows = keyValueRows({
+      surplus: 2500, ok: true, note: 'x'.repeat(150),
+      series: [1, 2, 3], nested: { a: 1, b: 2 },
+    });
+    expect(rows[0]).toEqual({ key: 'surplus', display: '2500', complex: false });
+    expect(rows[1]).toEqual({ key: 'ok', display: 'true', complex: false });
+    expect(rows[2].display.endsWith('…')).toBe(true);
+    expect(rows[2].display.length).toBe(121);
+    expect(rows[3]).toEqual({ key: 'series', display: '[3 items]', complex: true });
+    expect(rows[4]).toEqual({ key: 'nested', display: '{2 keys}', complex: true });
+  });
+  it('non-object input yields empty list', () => {
+    expect(keyValueRows(null)).toEqual([]);
+    expect(keyValueRows('str')).toEqual([]);
+  });
+});
+
+describe('firstSentence', () => {
+  it('takes the text before the first period', () => {
+    expect(firstSentence('Loads the thing. PORT NOTE: mechanism detail.')).toBe('Loads the thing');
+  });
+  it('empty input yields empty output', () => {
+    expect(firstSentence('')).toBe('');
+  });
+});
+
+describe('simpleNodeDescription', () => {
+  it('prefers an authored simpleDescription over the technical one', () => {
+    expect(simpleNodeDescription({ description: 'Verbatim port of X. Mechanism.', simpleDescription: 'Does the thing' })).toBe(
+      'Does the thing',
+    );
+  });
+  it('falls back to the first sentence of description when absent', () => {
+    expect(simpleNodeDescription({ description: 'Does the thing. Mechanism detail.' })).toBe('Does the thing');
+  });
+  it('is empty for an undefined definition', () => {
+    expect(simpleNodeDescription(undefined)).toBe('');
+  });
+});

package/src/lib/registerLens.ts

@@ -0,0 +1,59 @@
+import type { LogLine } from '../engine';
+
+/**
+ * The register lens: every simple-vs-technical presentation decision lives
+ * here, so the run console, dock, and Inspector cannot drift apart. One event
+ * stream, two projections — simple hides mechanism (debug receipts, exact
+ * timings, raw payload walls), never consequence (warn/error lines, effects,
+ * environment state are identical in both registers).
+ */
+export type ViewRegister = 'simple' | 'technical';
+
+export function filterLogs(logs: LogLine[], register: ViewRegister): LogLine[] {
+  if (register === 'technical') return logs;
+  return logs.filter((l) => l.level !== 'debug');
+}
+
+export function formatDuration(ms: number, register: ViewRegister): string {
+  if (register === 'technical') {
+    return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(2)}s`;
+  }
+  if (ms < 10) return '<10ms';
+  if (ms < 1000) {
+    // 995–999 round up to 1000 — hand those to the seconds branch so the
+    // display never reads '1000ms' beside '1.0s'.
+    const rounded = Math.round(ms / 10) * 10;
+    return rounded >= 1000 ? `${(rounded / 1000).toFixed(1)}s` : `${rounded}ms`;
+  }
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+export function payloadOpenByDefault(register: ViewRegister): boolean {
+  return register === 'technical';
+}
+
+/** The first sentence of a node description — a cheap plain-reading fallback
+ * for nodes that haven't been given a `simpleDescription` yet. */
+export function firstSentence(text: string): string {
+  return text ? text.split('.')[0].trim() : '';
+}
+
+/** Simple-register description line for a node: its authored plain-language
+ * one-liner, or the first sentence of the technical description, honest empty
+ * string when neither exists. */
+export function simpleNodeDescription(definition: { description?: string; simpleDescription?: string } | undefined): string {
+  return definition?.simpleDescription ?? firstSentence(definition?.description ?? '');
+}
+
+export function keyValueRows(value: unknown): Array<{ key: string; display: string; complex: boolean }> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return [];
+  return Object.entries(value as Record<string, unknown>).map(([key, v]) => {
+    if (Array.isArray(v)) return { key, display: `[${v.length} items]`, complex: true };
+    if (v !== null && typeof v === 'object') {
+      return { key, display: `{${Object.keys(v).length} keys}`, complex: true };
+    }
+    const raw = String(v);
+    const display = raw.length > 120 ? `${raw.slice(0, 120)}…` : raw;
+    return { key, display, complex: false };
+  });
+}

package/src/lib/runbookModel.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { buildRunbook } from './runbookModel';
+import { createPradarFlows } from '../flows/pradar-flows';
+import { createDefaultRegistry } from '../nodes';
+
+const registry = createDefaultRegistry();
+const flow = (id: string) =>
+  [...createPradarFlows()].find((f) => f.id === id)!;
+
+function flat(items: any[], out: any[] = []): any[] {
+  for (const it of items) { out.push(it); if (it.items) flat(it.items, out); }
+  return out;
+}
+
+describe('buildRunbook', () => {
+  it('covers every node exactly once (steps + loop headers), Collect excluded', () => {
+    for (const id of ['ev-evaluate-cycle']) {
+      const f = flow(id);
+      const doc = buildRunbook(f, registry);
+      const all = flat(doc.items);
+      const stepIds = all.filter((i) => i.kind === 'step').map((i) => i.nodeId);
+      const loopHeads = all.filter((i) => i.kind === 'loop');
+      const collectIds = loopHeads.map((l) => l.collectId);
+      const forEachIds = loopHeads.map((l) => l.forEachId);
+      const expected = f.nodes.map((n) => n.id).filter((id2) => !collectIds.includes(id2) && !forEachIds.includes(id2));
+      expect([...stepIds].sort()).toEqual([...expected].sort());
+      expect(new Set(stepIds).size).toBe(stepIds.length);
+    }
+  });
+
+  it('ev-evaluate-cycle: night-window work is nested under the off arm, not a sibling of solar work', () => {
+    const doc = buildRunbook(flow('ev-evaluate-cycle'), registry);
+    const all = flat(doc.items);
+    const night = all.find((i) => i.kind === 'step' && i.nodeId === 'subflowNight');
+    const surplus = all.find((i) => i.kind === 'step' && i.nodeId === 'surplus');
+    expect(night.depth).toBeGreaterThan(0);
+    expect(surplus.depth).toBeGreaterThan(0);
+    // they sit under DIFFERENT arms of condSolar
+    const nightGuards = doc.guards.get('subflowNight')!.map((g) => `${g.ownerId}:${g.arm}`);
+    const surplusGuards = doc.guards.get('surplus')!.map((g) => `${g.ownerId}:${g.arm}`);
+    expect(nightGuards.some((g) => g.startsWith('condSolar:'))).toBe(true);
+    expect(surplusGuards.some((g) => g.startsWith('condSolar:'))).toBe(true);
+    expect(nightGuards.find((g) => g.startsWith('condSolar:'))).not.toBe(
+      surplusGuards.find((g) => g.startsWith('condSolar:')));
+  });
+
+  it('numbers are hierarchical and unique', () => {
+    const doc = buildRunbook(flow('ev-evaluate-cycle'), registry);
+    const nums = flat(doc.items).map((i) => i.number);
+    expect(new Set(nums).size).toBe(nums.length);
+    expect(nums.some((n) => /^\d+\.\d+$/.test(n))).toBe(true);
+  });
+
+  it('Subflow steps carry subflowId; mutation steps carry mutation flag', () => {
+    const doc = buildRunbook(flow('ev-evaluate-cycle'), registry);
+    const all = flat(doc.items);
+    const sub = all.find((i) => i.kind === 'step' && i.subflow);
+    expect(sub.subflowId).toBe('ev-night-charge');
+    expect(all.some((i) => i.kind === 'step' && i.mutation)).toBe(true);
+  });
+});

package/src/lib/runbookModel.ts

@@ -0,0 +1,290 @@
+import type { WorkflowDefinition, WorkflowEdge } from '../engine';
+import { computeLoopRegions, topoSort, type LoopRegion } from '../engine';
+import type { NodeRegistry } from '../engine';
+import { firstSentence, simpleNodeDescription } from './registerLens';
+
+export interface RunbookStep {
+  kind: 'step';
+  nodeId: string;
+  number: string; // "3" or "3.2" or "3.2.1"
+  depth: number; // 0 = root
+  label: string; // node.label
+  typeName: string; // node.type
+  description: string; // registry definition.description first sentence, '' if unknown type
+  simpleDescription: string; // definition.simpleDescription, else same as `description`
+  traceKind?: 'db' | 'http' | 'llm' | 'compute'; // definition.traceKind, for the technical register badge
+  mutation: boolean; // definition.effects === 'mutation'
+  subflow: boolean; // node.type === 'Subflow'
+  subflowId?: string; // config.workflowId when subflow
+  decisionArms?: string[]; // outgoing sourceHandles when this node branches but arms are rendered as groups elsewhere
+}
+
+export interface RunbookBranchGroup {
+  kind: 'branch';
+  ownerId: string; // the branching node
+  arm: string; // sourceHandle name
+  number: string;
+  depth: number;
+  items: RunbookItem[];
+}
+
+export interface RunbookLoopGroup {
+  kind: 'loop';
+  forEachId: string;
+  collectId: string;
+  number: string;
+  depth: number;
+  items: RunbookItem[]; // body steps (Collect excluded; ForEach is the header)
+  label: string; // ForEach node label
+}
+
+export type RunbookItem = RunbookStep | RunbookBranchGroup | RunbookLoopGroup;
+
+export interface RunbookDoc {
+  items: RunbookItem[];
+  /** nodeId -> the (ownerId, arm) guards that gate it; used by projection for taken/dim state. */
+  guards: Map<string, Array<{ ownerId: string; arm: string }>>;
+  /** every (ownerId, arm) pair that exists in the flow, for coverage math. */
+  arms: Array<{ ownerId: string; arm: string }>;
+}
+
+interface GuardEntry {
+  ownerId: string;
+  arm: string;
+}
+
+/**
+ * Builds the guard set for every node in `nodeIds`, walking `order` (already
+ * topologically valid for this subset) and intersecting incoming guard sets —
+ * a node reached via two different arms of the same owner is a join and
+ * carries neither arm (see executor.isReachable for the same branch-guard
+ * semantics, mirrored here for grouping instead of execution).
+ */
+function buildGuardMap(
+  nodeIds: Set<string>,
+  order: string[],
+  edges: WorkflowEdge[],
+): Map<string, Set<string>> {
+  const incoming = new Map<string, WorkflowEdge[]>();
+  for (const e of edges) {
+    if (!nodeIds.has(e.source) || !nodeIds.has(e.target)) continue;
+    if (!incoming.has(e.target)) incoming.set(e.target, []);
+    incoming.get(e.target)!.push(e);
+  }
+  const guardMap = new Map<string, Set<string>>();
+  for (const id of order) {
+    const inc = incoming.get(id) ?? [];
+    if (inc.length === 0) {
+      guardMap.set(id, new Set());
+      continue;
+    }
+    // Each edge contributes guardSet(source) ∪ {source::handle if branch
+    // edge}. Edges that carry no gating information at all (no handle AND an
+    // unguarded source, e.g. a data edge straight from "input") are excluded
+    // from the intersection — they must not smuggle a node out of its branch.
+    // But an unguarded-looking plain edge whose SOURCE inherited guards does
+    // participate: a join fed by arm X directly and arm Y through a chain
+    // intersects {X} ∩ {Y} = ∅ and correctly carries neither. If every edge
+    // is information-free the guard set is ∅.
+    let result: Set<string> | undefined;
+    for (const e of inc) {
+      const base = guardMap.get(e.source) ?? new Set<string>();
+      if (!e.sourceHandle && base.size === 0) continue; // information-free
+      const g = new Set(base);
+      if (e.sourceHandle) g.add(`${e.source}::${e.sourceHandle}`);
+      result = result === undefined ? g : new Set([...result].filter((x) => g.has(x)));
+    }
+    guardMap.set(id, result ?? new Set());
+  }
+  return guardMap;
+}
+
+function guardPath(id: string, guardMap: Map<string, Set<string>>, order: string[]): GuardEntry[] {
+  const set = guardMap.get(id) ?? new Set<string>();
+  const indexOf = (nodeId: string) => order.indexOf(nodeId);
+  return [...set]
+    .map((s): GuardEntry => {
+      const idx = s.indexOf('::');
+      return { ownerId: s.slice(0, idx), arm: s.slice(idx + 2) };
+    })
+    .sort((a, b) => indexOf(a.ownerId) - indexOf(b.ownerId));
+}
+
+function sameGuard(a: GuardEntry, b: GuardEntry): boolean {
+  return a.ownerId === b.ownerId && a.arm === b.arm;
+}
+
+/** Distinct outgoing sourceHandles of `id`, in the order they first appear in flow.edges. */
+function distinctArms(edges: WorkflowEdge[], id: string): string[] {
+  const seen = new Set<string>();
+  const arms: string[] = [];
+  for (const e of edges) {
+    if (e.source === id && e.sourceHandle && !seen.has(e.sourceHandle)) {
+      seen.add(e.sourceHandle);
+      arms.push(e.sourceHandle);
+    }
+  }
+  return arms;
+}
+
+export function buildRunbook(flow: WorkflowDefinition, registry: NodeRegistry): RunbookDoc {
+  const order = topoSort(flow);
+  const regions = computeLoopRegions(flow);
+
+  const bodyNodeIds = new Set<string>(regions.flatMap((r) => r.bodyIds));
+  const collectIds = new Set<string>(regions.map((r) => r.collectId));
+  const regionByForEach = new Map<string, LoopRegion>(regions.map((r) => [r.forEachId, r]));
+
+  // ── root scope: everything except loop-body-internal nodes ──
+  const extendedNodeIds = new Set<string>(flow.nodes.map((n) => n.id).filter((id) => !bodyNodeIds.has(id)));
+  const syntheticEdges: WorkflowEdge[] = regions.map((r) => ({
+    id: `synthetic-${r.forEachId}`,
+    source: r.forEachId,
+    target: r.collectId,
+  }));
+  const rootEdges: WorkflowEdge[] = [
+    ...flow.edges.filter(
+      (e) => extendedNodeIds.has(e.source) && extendedNodeIds.has(e.target) && !collectIds.has(e.target),
+    ),
+    ...syntheticEdges,
+  ];
+  const rootOrder = order.filter((id) => extendedNodeIds.has(id));
+  const rootGuardMap = buildGuardMap(extendedNodeIds, rootOrder, rootEdges);
+  const rootPool = order.filter((id) => !bodyNodeIds.has(id) && !collectIds.has(id));
+
+  // ── per-region body scope: guards computed relative to the body's own node set ──
+  const bodyScopes = new Map<
+    string,
+    { bodySet: Set<string>; bodyOrder: string[]; bodyGuardMap: Map<string, Set<string>> }
+  >();
+  for (const region of regions) {
+    const bodySet = new Set(region.bodyIds);
+    const bodyEdges = flow.edges.filter((e) => bodySet.has(e.source) && bodySet.has(e.target));
+    const bodyOrder = order.filter((id) => bodySet.has(id));
+    const bodyGuardMap = buildGuardMap(bodySet, bodyOrder, bodyEdges);
+    bodyScopes.set(region.forEachId, { bodySet, bodyOrder, bodyGuardMap });
+  }
+
+  function buildStep(id: string): RunbookStep {
+    const node = flow.nodes.find((n) => n.id === id)!;
+    const registered = registry.has(node.type) ? registry.get(node.type) : undefined;
+    const description = firstSentence(registered?.definition.description ?? '');
+    const simpleDescription = simpleNodeDescription(registered?.definition);
+    const mutation = registered?.definition.effects === 'mutation';
+    const subflow = node.type === 'Subflow';
+    const step: RunbookStep = {
+      kind: 'step',
+      nodeId: id,
+      number: '',
+      depth: 0,
+      label: node.label,
+      typeName: node.type,
+      description,
+      simpleDescription,
+      mutation,
+      subflow,
+    };
+    if (registered?.definition.traceKind) step.traceKind = registered.definition.traceKind;
+    if (subflow) step.subflowId = node.config.workflowId as string;
+    return step;
+  }
+
+  function buildLoopGroup(region: LoopRegion): RunbookLoopGroup {
+    const scope = bodyScopes.get(region.forEachId)!;
+    const items = buildLevel(scope.bodyOrder, [], scope.bodyGuardMap);
+    const forEachNode = flow.nodes.find((n) => n.id === region.forEachId)!;
+    return {
+      kind: 'loop',
+      forEachId: region.forEachId,
+      collectId: region.collectId,
+      number: '',
+      depth: 0,
+      items,
+      label: forEachNode.label,
+    };
+  }
+
+  /**
+   * Builds the item list for one level of nesting. `pool` holds every node
+   * id whose guard path (in `guardMap`) has `context` as a prefix — nodes
+   * further nested are deferred to the recursive call triggered by their
+   * governing branch owner, encountered later in this same loop.
+   */
+  function buildLevel(
+    pool: string[],
+    context: GuardEntry[],
+    guardMap: Map<string, Set<string>>,
+  ): RunbookItem[] {
+    const items: RunbookItem[] = [];
+    for (const id of pool) {
+      const gp = guardPath(id, guardMap, order);
+      if (gp.length !== context.length) continue; // belongs to a deeper level; handled via its owner below
+
+      const region = regionByForEach.get(id);
+      if (region) {
+        items.push(buildLoopGroup(region));
+        continue;
+      }
+
+      const step = buildStep(id);
+      items.push(step);
+
+      const arms = distinctArms(flow.edges, id);
+      if (arms.length === 0) continue;
+
+      const leftover: string[] = [];
+      for (const arm of arms) {
+        const entry: GuardEntry = { ownerId: id, arm };
+        const childPool = pool.filter((pid) => {
+          const pgp = guardPath(pid, guardMap, order);
+          return pgp.length > context.length && sameGuard(pgp[context.length], entry);
+        });
+        if (childPool.length === 0) {
+          leftover.push(arm);
+          continue;
+        }
+        const childItems = buildLevel(childPool, [...context, entry], guardMap);
+        items.push({ kind: 'branch', ownerId: id, arm, number: '', depth: 0, items: childItems });
+      }
+      if (leftover.length > 0) step.decisionArms = leftover;
+    }
+    return items;
+  }
+
+  const rootItems = buildLevel(rootPool, [], rootGuardMap);
+
+  function numberItems(items: RunbookItem[], prefix: string, depth: number): void {
+    items.forEach((item, i) => {
+      const number = prefix ? `${prefix}.${i + 1}` : `${i + 1}`;
+      item.number = number;
+      item.depth = depth;
+      if (item.kind !== 'step') numberItems(item.items, number, depth + 1);
+    });
+  }
+  numberItems(rootItems, '', 0);
+
+  // ── guards: every node's full guard chain, for projection's taken/dim math ──
+  const guards = new Map<string, Array<{ ownerId: string; arm: string }>>();
+  for (const id of extendedNodeIds) {
+    guards.set(id, guardPath(id, rootGuardMap, rootOrder));
+  }
+  for (const region of regions) {
+    const scope = bodyScopes.get(region.forEachId)!;
+    for (const id of region.bodyIds) {
+      guards.set(id, guardPath(id, scope.bodyGuardMap, scope.bodyOrder));
+    }
+  }
+
+  // ── arms: every (ownerId, arm) pair declared anywhere in the flow ──
+  const armsSeen = new Set<string>();
+  const arms: Array<{ ownerId: string; arm: string }> = [];
+  for (const e of flow.edges) {
+    if (!e.sourceHandle) continue;
+    const key = `${e.source}::${e.sourceHandle}`;
+    if (armsSeen.has(key)) continue;
+    armsSeen.add(key);
+    arms.push({ ownerId: e.source, arm: e.sourceHandle });
+  }
+
+  return { items: rootItems, guards, arms };
+}