@caddis/cli 0.4.45 → 0.4.46

package/bundles/antigravity-plugin/skills/flow-studio/templates/engine.html

@@ -84,15 +84,21 @@
   .bandlabel b { font-size:13px; } .bandlabel .bd { font-size:10.5px; font-weight:700; padding:0 6px; border:1px solid currentColor; color:var(--muted); letter-spacing:.03em; text-transform:uppercase; }
   .bandlabel .bd.t-ok { color:var(--ok); } .bandlabel .bd.t-warn { color:var(--warn); } .bandlabel .bn { font-size:11.5px; color:var(--muted); }
   .node { position:absolute; background:var(--panel); border:1px solid var(--edge); border-radius:8px; padding:5px 10px 7px; box-shadow:var(--shadow); transition:opacity .35s, transform .35s, box-shadow .2s, border-color .2s; cursor:pointer; z-index:2; }
+  .node.gateway { border:0; background:transparent; box-shadow:none; padding:0; border-radius:0; display:flex; align-items:center; justify-content:center; }
+  .node.gateway svg.gw { position:absolute; inset:0; width:100%; height:100%; overflow:visible; }
+  .node.gateway polygon { stroke-width:2; vector-effect:non-scaling-stroke; }
+  .node.gateway .gw-title { position:relative; width:58%; text-align:center; font-size:11px; font-weight:600; line-height:1.2; color:var(--fg); overflow:hidden; display:-webkit-box; -webkit-line-clamp:2; -webkit-box-orient:vertical; overflow-wrap:anywhere; }
+  .node.gateway:hover, .node.gateway.lit, .node.gateway.sel { filter:drop-shadow(0 0 7px var(--accent)); }
   .node.wide { overflow:hidden; }
   .node:hover { border-color:var(--accent); box-shadow:0 0 0 3px var(--glow), var(--shadow); }
   .node .t { display:flex; gap:4px; align-items:flex-start; font-weight:600; line-height:1.25; font-size:13px; }
   .node .t .name { overflow-wrap:anywhere; display:-webkit-box; -webkit-line-clamp:2; -webkit-box-orient:vertical; overflow:hidden; }
+  .node .fold { flex:none; color:var(--accent); font-size:11px; }
   .node .s { color:var(--muted); font-size:12px; line-height:1.3; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
   .ev { font-size:10.5px; font-weight:700; letter-spacing:.03em; }
   .node.wide .t { font-weight:500; } .node.wide .s { white-space:normal; }
-  .node.ref { padding:4px 9px; border-style:dashed; box-shadow:none; background:color-mix(in srgb, var(--panel) 70%, transparent); } .node.ref .t { font-size:12px; } .node.ref .s { font-size:11px; }
-  .node.sel { outline:2px solid var(--accent); outline-offset:2px; } .node.dim { opacity:.28; } .node.off { opacity:0; transform:translateY(8px); pointer-events:none; }
+  .node.ref { padding:4px 9px; border-style:dashed; box-shadow:none; background:color-mix(in srgb, var(--panel) 70%, transparent); } .node.ref .t { font-size:12px; } .node.ref .t .name { display:block; min-width:0; white-space:nowrap; text-overflow:ellipsis; } .node.ref .s { font-size:11px; }
+  .node.sel { outline:2px solid var(--accent); outline-offset:2px; } .node.dim { opacity:.28; } .node.off { opacity:0; visibility:hidden; transform:translateY(8px); pointer-events:none; }
   .node .bar { position:absolute; left:0; right:0; bottom:0; display:flex; height:4px; overflow:hidden; border-radius:0 0 7px 7px; background:var(--panel2); } .node .bar i { display:block; height:100%; } .bar .good { background:var(--ok); } .bar .neutral { background:var(--muted); } .bar .gap { background:var(--warn); }
   .newdot { display:none; width:7px; height:7px; border-radius:50%; background:var(--accent); margin:5px 4px 0 0; flex:none; } body.alt .node.isnew .newdot { display:inline-block; }
   body.alt .node.isnew.pulse { animation:newring 1.8s ease-out 1; }
@@ -169,6 +175,33 @@
   @keyframes beat { 0%{box-shadow:0 0 0 0 color-mix(in srgb, var(--ok) 60%, transparent);} 70%,100%{box-shadow:0 0 0 9px transparent;} }
   @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation:none !important; transition:none !important; } path.edge.hot { stroke-dasharray:none; } }
   @media (max-width: 1100px) { .summary { grid-template-columns:1fr; } .workspace { height:auto; } .workspace .canvaswrap { height:75vh; } .insp { width:min(340px, 92%); } #drawer { width:100%; } .layerstrip { grid-template-columns:repeat(3,1fr) !important; } }
+  #banner:not([hidden]) { margin:0 14px 10px; padding:8px 12px; color:var(--crit); background:var(--crit-bg); border:1px solid var(--crit); font-size:12px; }
+  #playbar:not([hidden]) { display:flex; flex-wrap:wrap; align-items:center; gap:7px; padding:7px 12px; border-top:1px solid var(--rule); background:var(--panel); font-size:12px; }
+  #playbar select, #playbar button { font-size:11px; }
+  #pbScrub { flex:1 1 140px; min-width:90px; }
+  #pbCaption { flex:1 1 100%; color:var(--fg); }
+  #pbCounter { font:11px var(--mono); color:var(--fg); }
+  #pbCounter.warn { color:var(--warn); } #pbCounter.breach { color:var(--crit); font-weight:700; }
+  #pbChoices { display:flex; gap:5px; flex-wrap:wrap; } #pbChoices:empty { display:none; }
+  #pbChoices .suggested { border-color:var(--accent); box-shadow:inset 0 -2px 0 var(--accent); }
+  circle.token { fill:var(--accent); stroke:var(--panel); stroke-width:2; filter:drop-shadow(0 0 5px var(--accent)); pointer-events:none; }
+  path.edge.playing { stroke:var(--accent); stroke-width:3; filter:drop-shadow(0 0 5px var(--accent)); opacity:1; }
+  path.edge.visited { stroke:var(--accent); opacity:.7; }
+  .node.playing { outline:2px solid var(--accent); outline-offset:2px; }
+  /* The pulse runs only while the player really plays; a paused step keeps the plain outline. */
+  body.playing .node.playing { animation:selpulse 1.8s ease-out infinite; }
+  .node.visited::after { content:"✓"; position:absolute; right:3px; bottom:1px; color:var(--accent); font-size:11px; }
+  .node.updated { animation:newring 1.2s ease-out 1; }
+  .node.added { animation:rise 1.2s ease-out 1; }
+  .node .t .name { min-width:0; flex:1 1 auto; }
+  .node .metric-badge { flex:none; max-width:72px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; position:relative; padding-bottom:3px; text-align:right; font:11px var(--mono); color:var(--accent); }
+  .node .metric-badge i { display:block; height:2px; position:absolute; bottom:0; left:0; background:var(--accent); }
+  .node .s.has-spark { padding-right:60px; }
+  .node .spark { position:absolute; right:6px; bottom:4px; overflow:visible; }
+  .node.gateway .metric-badge { position:absolute; right:9px; top:18px; }
+  .node.gateway:has(.metric-badge) .gw-title, .node.gateway.has-metrics .gw-title { width:45%; margin-right:42px; }
+  .node .spark polyline, .metrics polyline { fill:none; stroke:var(--accent); stroke-width:1.5; }
+  .metrics svg { max-width:100%; margin-top:8px; } .metric-range { display:flex; justify-content:space-between; width:300px; max-width:100%; font:10px var(--mono); color:var(--muted); }
 </style>
 </head>
 <body>
@@ -181,23 +214,34 @@
 <main>
   <div class="titlerow"><h1 id="title"></h1><span class="readline" id="readat"></span></div>
   <p class="help" id="help"></p>
+  <div id="banner" role="alert" hidden></div>
 
   <section class="summary"><div class="layerstrip" id="layerstrip" aria-label="Completeness by column"></div><div class="tiles" id="kpis" aria-label="Summary"></div></section>
 
   <div class="toolbar">
     <div class="seggrp" role="tablist" aria-label="View" id="modeSwitch"></div>
     <input id="q" type="search" placeholder="Find a group or member…  ( / )" aria-label="Find a group or member">
+    <select id="hops" aria-label="Search radius"><option value="0">This group</option><option value="1">+1 hop</option><option value="2">+2 hops</option><option value="3">+3 hops</option></select>
     <span id="matchinfo" class="note" style="margin:0"></span>
   </div>
 
   <div class="workspace" id="workspace">
     <section class="canvaswrap">
       <div id="viewport" tabindex="0" role="application" aria-label="Flow canvas. Scroll to zoom, drag to pan. Keys: V select, H hand, plus and minus zoom, 0 fit, 1 actual size, F zoom to selection, arrows pan.">
-        <div id="world"><svg id="edges" aria-hidden="true"><defs><marker id="arr" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="0"><path d="M0 0 L8 4 L0 8 z" fill="context-stroke"/></marker></defs><g id="edgeLayer"></g></svg></div>
+        <div id="world"><svg id="edges" aria-hidden="true"><defs><marker id="arr" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path d="M0 0 L8 4 L0 8 z" fill="context-stroke"/></marker></defs><g id="edgeLayer"></g></svg></div>
         <div id="cols" aria-hidden="true"></div>
         <div id="tools" role="toolbar" aria-label="Canvas controls" aria-orientation="vertical"></div>
         <div id="zoomLabel" aria-hidden="true">100%</div>
       </div>
+      <div id="playbar" hidden aria-label="Scenario playback">
+        <select id="pbScenario" aria-label="Scenario"></select>
+        <button id="pbPlay" type="button" aria-label="Play">▶</button>
+        <button id="pbStep" type="button" aria-label="Step">Step</button>
+        <button id="pbReset" type="button" aria-label="Reset">Reset</button>
+        <select id="pbSpeed" aria-label="Speed"><option value="0.5">0.5x</option><option value="1" selected>1x</option><option value="2">2x</option></select>
+        <input id="pbScrub" type="range" min="0" max="1000" value="0" aria-label="Playback position" aria-valuetext="Step 1 of 1">
+        <span id="pbCaption"></span><span id="pbCounter"></span><span id="pbChoices"></span>
+      </div>
       <div class="keyline" id="legend" aria-label="Legend"></div>
       <aside class="insp" id="inspector" aria-label="Inspector" aria-hidden="true"></aside>
     </section>
@@ -211,11 +255,13 @@
 <footer id="footer"></footer>
 <aside id="drawer" aria-label="Implementation notes"><h2>Implementation notes</h2><p class="note">Numbered markers on the page match these cards. Hover a card to find its place; click a marker to jump to its card.</p><div id="notelist"></div></aside>
 
+
 <script type="application/json" id="flow-model">/*__MODEL__*/{}</script>
 <script type="application/json" id="flow-notes">/*__NOTES__*/[]</script>
 <script>"use strict";
 (() => {
   // src/model.ts
+  var NODE_HEIGHT = { card: 54, group: 54, gateway: 64, placeholder: 54, chip: 40, start: 40, end: 40, event: 40, note: 40 };
   var TONES = ["ok", "warn", "crit", "info", "muted", "accent"];
   var BORDERS = ["solid", "dashed", "dotted"];
   var EDGES = ["flow", "dash", "dash-short", "dot"];
@@ -234,9 +280,9 @@
     }
     const m = input;
     if (m.version !== 1) add("error", "model-version", "version", "version must be 1.");
-    if (m.layout !== "columns-lanes") add("error", "layout-unsupported", "layout", `layout ${String(m.layout)} is not supported yet: use "columns-lanes" ("free" and "auto" arrive in a later stage).`);
-    if (!Array.isArray(m.columns) || m.columns.length === 0) add("error", "columns-missing", "columns", "At least one column is required.");
-    if (!Array.isArray(m.lanes) || m.lanes.length === 0) add("error", "lanes-missing", "lanes", "At least one lane is required.");
+    if (!["columns-lanes", "free", "auto"].includes(m.layout)) add("error", "layout-unsupported", "layout", `layout ${String(m.layout)} is not supported: use "columns-lanes", "free", or "auto".`);
+    if (!Array.isArray(m.columns) || m.layout === "columns-lanes" && m.columns.length === 0) add("error", "columns-missing", "columns", "Columns are required for columns-lanes layout.");
+    if (!Array.isArray(m.lanes) || m.layout !== "auto" && m.lanes.length === 0) add("error", "lanes-missing", "lanes", "At least one lane is required.");
     if (!m.states || typeof m.states !== "object" || Object.keys(m.states).length === 0) add("error", "states-missing", "states", "At least one state is required.");
     const columns = Array.isArray(m.columns) ? m.columns : [];
     const lanes = Array.isArray(m.lanes) ? m.lanes : [];
@@ -266,15 +312,36 @@
       const w = `nodes[${n.id}]`;
       if (nodeIds.has(n.id)) add("error", "node-duplicate", w, `Duplicate node id ${n.id}.`);
       nodeIds.add(n.id);
-      if (!laneIds.has(n.lane)) add("error", "lane-undefined", w, `Lane ${n.lane} is not defined.`);
+      if ((m.layout !== "auto" || n.lane !== void 0) && !laneIds.has(n.lane ?? "")) add("error", "lane-undefined", w, `Lane ${n.lane} is not defined.`);
       for (const s of [n.state, ...Object.values(n.stateIn ?? {})]) if (!stateIds.has(s)) add("error", "state-undefined", w, `State ${s} is not defined.`);
-      if (typeof n.row !== "number" || !Number.isFinite(n.row)) add("error", "row-invalid", w, `Node ${n.id} needs a finite number for row (it sets the vertical position).`);
+      if (m.layout === "columns-lanes" && (typeof n.row !== "number" || !Number.isFinite(n.row))) add("error", "row-invalid", w, `Node ${n.id} needs a finite number for row (it sets the vertical position).`);
       const span = n.colSpan ?? 1;
-      if (!Number.isInteger(n.col) || n.col < 0 || n.col + span > ncols) add("error", "column-range", w, `Column ${n.col} with span ${span} is outside 0..${ncols - 1}.`);
+      if (m.layout === "columns-lanes" && (!Number.isInteger(n.col) || (n.col ?? -1) < 0 || (n.col ?? 0) + span > ncols)) add("error", "column-range", w, `Column ${n.col} with span ${span} is outside 0..${ncols - 1}.`);
+      if (m.layout === "free") {
+        if (!Number.isFinite(n.x) || !Number.isFinite(n.y)) add("error", "position-invalid", w, `Node ${n.id} needs finite x and y.`);
+        if (n.w !== void 0 && (!Number.isFinite(n.w) || n.w <= 0) || n.h !== void 0 && (!Number.isFinite(n.h) || n.h <= 0)) add("error", "size-invalid", w, `Node ${n.id} needs positive finite width and height.`);
+      }
+      const metric = n.metrics;
+      const invalidSeries = metric?.series !== void 0 && (!Array.isArray(metric.series) || metric.series.length > 60 || metric.series.some((v) => !Number.isFinite(v)));
+      if (metric !== void 0 && (!metric || !Number.isFinite(metric.value) || metric.max != null && !Number.isFinite(metric.max) || invalidSeries)) add("error", "metric-invalid", w, "Metrics need finite values and at most 60 finite series points.");
+      if (n.sla !== void 0 && (!Number.isFinite(n.sla) || n.sla <= 0)) add("error", "sla-invalid", w, "SLA must be a positive finite number of seconds.");
     }
     for (const n of nodes) {
       if (n.kind === "chip" && (!n.ref || !nodeIds.has(n.ref))) add("error", "chip-ref", `nodes[${n.id}]`, `A chip must point at a real node (ref ${n.ref}).`);
     }
+    const owner = /* @__PURE__ */ new Map();
+    for (const group of nodes.filter((n) => n.contains !== void 0)) {
+      if (group.kind !== "group" || !Array.isArray(group.contains)) {
+        add("error", "contains-shape", `nodes[${group.id}]`, "Only a group may contain a list of node ids.");
+        continue;
+      }
+      for (const id of group.contains) {
+        if (id === group.id) add("error", "contains-self", `nodes[${group.id}]`, `Group ${group.id} cannot contain itself.`);
+        else if (!nodeIds.has(id)) add("error", "contains-undefined", `nodes[${group.id}]`, `Contained node ${id} does not exist.`);
+        else if (owner.has(id)) add("error", "contains-duplicate", `nodes[${group.id}]`, `Node ${id} is already contained by ${owner.get(id)}.`);
+        else owner.set(id, group.id);
+      }
+    }
     const linkIds = /* @__PURE__ */ new Set();
     const linked = /* @__PURE__ */ new Set();
     for (const l of links) {
@@ -286,23 +353,68 @@
         linked.add(l.from);
         linked.add(l.to);
         const a = nodes.find((n) => n.id === l.from), b = nodes.find((n) => n.id === l.to);
-        if (b.col <= a.col + (a.colSpan ?? 1) - 1) {
-          add("warn", "link-direction", w, `Link ${l.id} does not run left to right (column ${a.col} to ${b.col}); it will look wrong until loop-back links arrive.`);
+        if (m.layout !== "free" && a.col !== void 0 && b.col !== void 0) {
+          const forward = b.col > a.col + (a.colSpan ?? 1) - 1;
+          if (!forward && l.kind !== "loop-back") add("warn", "link-direction", w, `Link ${l.id} does not run left to right (column ${a.col} to ${b.col}); mark it loop-back if it returns to an earlier stage.`);
+          if (forward && l.kind === "loop-back") add("warn", "loop-back-forward", w, `Link ${l.id} is marked loop-back but runs forward.`);
         }
       }
       for (const s of [l.state, ...Object.values(l.stateIn ?? {})]) if (!stateIds.has(s)) add("error", "state-undefined", w, `State ${s} is not defined.`);
     }
+    const scenarioIds = /* @__PURE__ */ new Set();
+    for (const [i, scenario] of (Array.isArray(m.scenarios) ? m.scenarios : []).entries()) {
+      const w = `scenarios[${i}]`;
+      if (!scenario || typeof scenario.id !== "string" || typeof scenario.label !== "string" || !Array.isArray(scenario.steps)) {
+        add("error", "scenario-shape", w, "A scenario needs an id, label and steps.");
+        continue;
+      }
+      if (scenarioIds.has(scenario.id)) add("error", "scenario-duplicate", w, `Duplicate scenario id ${scenario.id}.`);
+      scenarioIds.add(scenario.id);
+      if (!scenario.steps.length) add("error", "scenario-empty", w, "A scenario needs at least one step.");
+      const timed = scenario.steps.filter((s) => s && s.at !== void 0).length;
+      if (timed && timed !== scenario.steps.length) add("error", "scenario-at-partial", w, "Give every step an at time or none.");
+      let prev, previousAt = -Infinity;
+      for (const [j, step] of scenario.steps.entries()) {
+        const sw = `${w}.steps[${j}]`;
+        const link = links.find((l) => l.id === step?.link);
+        if (!link) add("error", "scenario-link", sw, `Unknown link ${step?.link}.`);
+        if (step?.at !== void 0) {
+          if (!Number.isFinite(step.at) || step.at < 0 || step.at < previousAt) add("error", "scenario-at-order", sw, "Step times must be finite, nonnegative and nondecreasing.");
+          if (Number.isFinite(step.at) && step.at >= 0 && step.at >= previousAt) previousAt = step.at;
+        }
+        if (step?.dur !== void 0 && (!Number.isFinite(step.dur) || step.dur <= 0)) add("error", "scenario-duration", sw, "Duration must be positive and finite.");
+        if (prev && link) {
+          const previousTo = prev.to;
+          if ((nodes.find((n) => n.id === previousTo)?.ref ?? previousTo) !== (nodes.find((n) => n.id === link.from)?.ref ?? link.from)) add("warn", "scenario-gap", sw, "This step does not start at the previous step's target.");
+        }
+        if (link) prev = link;
+      }
+    }
     for (const n of nodes) {
-      if (!linked.has(n.id) && !n.allowIsolated && n.kind !== "note") {
+      if (n.kind !== "gateway") continue;
+      const exits = links.filter((l) => l.from === n.id);
+      if (exits.length === 0) add("warn", "gateway-no-exit", `nodes[${n.id}]`, `Gateway ${n.id} has no exit.`);
+      else if (exits.length > 1 && exits.some((l) => !l.label?.trim())) add("warn", "gateway-exit-label", `nodes[${n.id}]`, `Every exit from gateway ${n.id} needs a label.`);
+    }
+    for (const n of nodes) {
+      if (!linked.has(n.id) && !n.allowIsolated && n.kind !== "note" && !(n.kind === "group" && n.contains?.length)) {
         add("error", "orphan", `nodes[${n.id}]`, `Node ${n.id} has no links. Add a link, a placeholder neighbour, or set allowIsolated.`);
       }
     }
     for (let i = 0; i < nodes.length; i++) {
       for (let j = i + 1; j < nodes.length; j++) {
         const a = nodes[i], b = nodes[j];
-        const ax2 = a.col + (a.colSpan ?? 1), bx2 = b.col + (b.colSpan ?? 1);
-        if (a.col < bx2 && b.col < ax2 && Math.abs(a.row - b.row) < 1) {
-          add("error", "cell-overlap", `nodes[${a.id}]`, `Nodes ${a.id} and ${b.id} overlap (same columns, rows less than 1 apart).`);
+        if (a.contains?.includes(b.id) || b.contains?.includes(a.id)) continue;
+        if (m.layout === "free") {
+          const aw = a.w ?? 190, ah = a.h ?? NODE_HEIGHT[a.kind] ?? 54, bw = b.w ?? 190, bh = b.h ?? NODE_HEIGHT[b.kind] ?? 54;
+          if ([a.x, a.y, b.x, b.y, aw, ah, bw, bh].every((v) => typeof v === "number" && Number.isFinite(v)) && a.x < b.x + bw && b.x < a.x + aw && a.y < b.y + bh && b.y < a.y + ah) {
+            add("error", "rect-overlap", `nodes[${a.id}]`, `Nodes ${a.id} and ${b.id} overlap.`);
+          }
+        } else if (a.col !== void 0 && b.col !== void 0 && a.row !== void 0 && b.row !== void 0) {
+          const ax2 = a.col + (a.colSpan ?? 1), bx2 = b.col + (b.colSpan ?? 1);
+          if (a.col < bx2 && b.col < ax2 && Math.abs(a.row - b.row) < 1) {
+            add("error", "cell-overlap", `nodes[${a.id}]`, `Nodes ${a.id} and ${b.id} overlap (same columns, rows less than 1 apart).`);
+          }
         }
       }
     }
@@ -311,6 +423,133 @@
     return out;
   }
 
+  // src/autolayout.ts
+  function autoLayout(input) {
+    const nodes = input.nodes.map((n) => ({ ...n }));
+    const links = input.links.map((l) => ({ ...l }));
+    const columns = input.columns.map((c) => ({ ...c }));
+    const lanes = input.lanes.map((l) => ({ ...l }));
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const index = new Map(nodes.map((n, i) => [n.id, i]));
+    const outgoing = new Map(nodes.map((n) => [n.id, []]));
+    const incoming = new Map(nodes.map((n) => [n.id, []]));
+    const neighbours = new Map(nodes.map((n) => [n.id, []]));
+    for (const link of links) {
+      if (!byId.has(link.from) || !byId.has(link.to)) continue;
+      outgoing.get(link.from).push(link);
+      incoming.get(link.to).push(link);
+      neighbours.get(link.from).push(link.to);
+      neighbours.get(link.to).push(link.from);
+    }
+    const color = /* @__PURE__ */ new Map();
+    const post = [];
+    for (const root of nodes) {
+      if (color.has(root.id)) continue;
+      color.set(root.id, 1);
+      const stack = [{ id: root.id, next: 0 }];
+      while (stack.length) {
+        const frame = stack[stack.length - 1];
+        const edges = outgoing.get(frame.id);
+        if (frame.next >= edges.length) {
+          color.set(frame.id, 2);
+          post.push(frame.id);
+          stack.pop();
+          continue;
+        }
+        const link = edges[frame.next++];
+        if (link.kind === "loop-back") continue;
+        const state = color.get(link.to) ?? 0;
+        if (state === 1) link.kind = "loop-back";
+        else if (state === 0) {
+          color.set(link.to, 1);
+          stack.push({ id: link.to, next: 0 });
+        }
+      }
+    }
+    for (const id of post.reverse()) {
+      const n = byId.get(id);
+      if (n.col !== void 0) continue;
+      let col = 0;
+      for (const edge of incoming.get(id)) {
+        if (edge.kind === "loop-back") continue;
+        const parent = byId.get(edge.from);
+        col = Math.max(col, (parent.col ?? 0) + (parent.colSpan ?? 1));
+      }
+      n.col = col;
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const usedLaneIds = new Set(lanes.map((l) => l.id));
+    let group = 0;
+    for (const first of nodes) {
+      if (seen.has(first.id)) continue;
+      const queue = [first.id];
+      seen.add(first.id);
+      for (let q = 0; q < queue.length; q++) {
+        for (const id of neighbours.get(queue[q])) if (!seen.has(id)) {
+          seen.add(id);
+          queue.push(id);
+        }
+      }
+      const missing = queue.map((id) => byId.get(id)).filter((n) => !n.lane);
+      if (!missing.length) continue;
+      group++;
+      let laneId = `group-${group}`;
+      while (usedLaneIds.has(laneId)) laneId += "-auto";
+      usedLaneIds.add(laneId);
+      lanes.push({ id: laneId, title: `Group ${group}` });
+      for (const n of missing) n.lane = laneId;
+    }
+    const rank = new Map(nodes.map((n, i) => [n.id, i]));
+    const laneOrder = lanes.map((l) => l.id);
+    const cells = /* @__PURE__ */ new Map();
+    for (const n of nodes) {
+      const key = `${n.lane}\0${n.col}`;
+      if (!cells.has(key)) cells.set(key, []);
+      cells.get(key).push(n);
+    }
+    const maxCol = Math.max(0, ...nodes.map((n) => (n.col ?? 0) + (n.colSpan ?? 1) - 1));
+    for (let sweep = 0; sweep < 4; sweep++) {
+      const forward = sweep % 2 === 0;
+      const layers = Array.from({ length: maxCol + 1 }, (_, i) => forward ? i : maxCol - i);
+      for (const lane of laneOrder) for (const col of layers) {
+        const groupNodes = cells.get(`${lane}\0${col}`);
+        if (!groupNodes || groupNodes.length < 2) continue;
+        const score = (n) => {
+          const edges = forward ? incoming.get(n.id) : outgoing.get(n.id);
+          const ns = edges.filter((e) => e.kind !== "loop-back").map((e) => forward ? e.from : e.to);
+          return ns.length ? ns.reduce((sum, id) => sum + (rank.get(id) ?? 0), 0) / ns.length : rank.get(n.id) ?? 0;
+        };
+        groupNodes.sort((a, b) => score(a) - score(b) || index.get(a.id) - index.get(b.id));
+        groupNodes.forEach((n, i) => rank.set(n.id, i));
+      }
+    }
+    let nextBase = 0;
+    const placed = nodes.filter((n) => n.row !== void 0);
+    for (const lane of laneOrder) {
+      const members = nodes.filter((n) => n.lane === lane);
+      if (!members.length) continue;
+      const ordered = [...members].sort((a, b) => (a.col ?? 0) - (b.col ?? 0) || (rank.get(a.id) ?? 0) - (rank.get(b.id) ?? 0) || index.get(a.id) - index.get(b.id));
+      const rowAtCol = /* @__PURE__ */ new Map();
+      for (const n of ordered) {
+        if (n.row !== void 0) continue;
+        let row = Math.max(nextBase, rowAtCol.get(n.col ?? 0) ?? nextBase);
+        while (placed.some((p) => (n.col ?? 0) < (p.col ?? 0) + (p.colSpan ?? 1) && (p.col ?? 0) < (n.col ?? 0) + (n.colSpan ?? 1) && Math.abs(row - (p.row ?? 0)) < 1)) row += 1;
+        n.row = row;
+        placed.push(n);
+        rowAtCol.set(n.col ?? 0, row + 1);
+      }
+      const last = Math.max(nextBase - 1, ...members.map((n) => n.row ?? 0));
+      const loops = links.filter((l) => l.kind === "loop-back" && byId.get(l.from)?.lane === lane && byId.get(l.to)?.lane === lane).length;
+      nextBase = last + 1.75 + loops * 0.35;
+    }
+    const needed = Math.max(0, ...nodes.map((n) => (n.col ?? 0) + (n.colSpan ?? 1)));
+    while (columns.length < needed) {
+      const i = columns.length + 1;
+      columns.push({ id: `stage-${i}`, title: `Stage ${i}`, width: 190 });
+    }
+    return { ...input, nodes, links, columns, lanes };
+  }
+
   // src/stateCss.ts
   var cssId = (id) => id.replace(/[^A-Za-z0-9_-]/g, "_");
   var TONES2 = { ok: "var(--ok)", warn: "var(--warn)", crit: "var(--crit)", info: "var(--up)", muted: "var(--muted)", accent: "var(--accent)" };
@@ -330,6 +569,7 @@
         const glow = s.bucket === "good" ? ` box-shadow:0 0 14px -4px color-mix(in srgb, ${T} 55%, transparent), var(--shadow);` : "";
         out.push(`.node.st-${c} { border-left:4px ${s.border} ${T};${glow} --breath:${T}; }`);
       }
+      out.push(`.node.st-${c}.gateway polygon { stroke:${T}; fill:color-mix(in srgb, ${T} 10%, var(--panel)); }`);
       out.push(`.ev.st-${c} { color:${T}; }`);
       if (s.motion === "breathe") out.push(`.node.st-${c}:not(.dim) { animation:breathe 3.2s ease-in-out infinite; }`);
       const edge = Object.hasOwn(DASH, s.edge) ? s.edge : "dash";
@@ -349,14 +589,32 @@
   // src/rules.ts
   var baselineView = (m) => m.views?.[0]?.id ?? "all";
   var defaultView = (m) => (m.views?.find((v) => v.default) ?? m.views?.[0])?.id ?? "all";
-  var nodeVisible = (_m, view, n) => !n.visibleIn || n.visibleIn.includes(view);
-  var nodeStateId = (_m, view, n) => n.stateIn?.[view] ?? n.state;
-  function linkVisible(m, view, l, nodes) {
-    if (l.visibleIn && !l.visibleIn.includes(view)) return false;
-    const a = nodes.get(l.from);
-    const b = nodes.get(l.to);
-    return !!a && !!b && nodeVisible(m, view, a) && nodeVisible(m, view, b);
+  var initialCollapsed = (m) => new Set(m.nodes.filter((n) => n.kind === "group" && n.contains && n.collapsed !== false).map((n) => n.id));
+  var columnTitle = (m, n) => n.col === void 0 ? "" : m.columns[n.col]?.title ?? "";
+  function groupFor(m, nodeId) {
+    return m.nodes.find((n) => n.kind === "group" && n.contains?.includes(nodeId));
+  }
+  var nodeVisible = (m, view, n, collapsed) => {
+    if (n.visibleIn && !n.visibleIn.includes(view)) return false;
+    if (!collapsed) return true;
+    if (n.kind === "group" && n.contains) return collapsed.has(n.id);
+    const owner = groupFor(m, n.id);
+    return !owner || !collapsed.has(owner.id);
+  };
+  function toggleGroupState(m, view, collapsed, id) {
+    const group = m.nodes.find((n) => n.id === id && n.kind === "group" && n.contains?.length);
+    if (!group) return null;
+    const next = new Set(collapsed);
+    const expanding = next.has(id);
+    if (expanding) next.delete(id);
+    else next.add(id);
+    const selected = expanding ? group.contains?.find((child) => {
+      const n = m.nodes.find((candidate) => candidate.id === child);
+      return !!n && nodeVisible(m, view, n, next);
+    }) ?? null : id;
+    return { collapsed: next, selected, expanding };
   }
+  var nodeStateId = (_m, view, n) => n.stateIn?.[view] ?? n.state;
   var linkStateId = (_m, view, l) => l.stateIn?.[view] ?? l.state;
   var bucketOf = (m, stateId) => m.states[stateId]?.bucket ?? "gap";
   var isNew = (m, view, n) => view !== baselineView(m) && nodeVisible(m, view, n) && !nodeVisible(m, baselineView(m), n);
@@ -365,6 +623,27 @@
     return view !== base && nodeVisible(m, base, n) && bucketOf(m, nodeStateId(m, base, n)) === "gap" && bucketOf(m, nodeStateId(m, view, n)) !== "gap";
   };
   var canonOf = (nodes, id) => nodes.get(id)?.ref ?? id;
+  function effectiveLinks(m, view, collapsed, nodes) {
+    const byPair = /* @__PURE__ */ new Map();
+    const rank = { good: 0, neutral: 1, gap: 2 };
+    for (const link of m.links) {
+      if (link.visibleIn && !link.visibleIn.includes(view)) continue;
+      const a = nodes.get(link.from), b = nodes.get(link.to);
+      if (!a || !b || a.visibleIn && !a.visibleIn.includes(view) || b.visibleIn && !b.visibleIn.includes(view)) continue;
+      const groupA = groupFor(m, a.id), groupB = groupFor(m, b.id);
+      const from = groupA && collapsed.has(groupA.id) ? groupA.id : a.id;
+      const to = groupB && collapsed.has(groupB.id) ? groupB.id : b.id;
+      if (from === to) continue;
+      const fromNode = nodes.get(from), toNode = nodes.get(to);
+      if (!fromNode || !toNode || !nodeVisible(m, view, fromNode, collapsed) || !nodeVisible(m, view, toNode, collapsed)) continue;
+      const state = linkStateId(m, view, link);
+      const key = JSON.stringify([from, to]);
+      const prev = byPair.get(key);
+      if (!prev) byPair.set(key, { ...link, from, to, state, stateIn: void 0 });
+      else if (rank[bucketOf(m, state)] > rank[bucketOf(m, prev.state)]) prev.state = state;
+    }
+    return [...byPair.values()];
+  }
 
   // src/trace.ts
   function relatives(edges, canonOf2, start, dir) {
@@ -390,6 +669,33 @@
   function connected(edges, canonOf2, start) {
     return /* @__PURE__ */ new Set([...relatives(edges, canonOf2, start, "up"), ...relatives(edges, canonOf2, start, "down")]);
   }
+  function withinHops(edges, canonOf2, starts, n) {
+    const found = new Set(starts.map(canonOf2));
+    const radius = Number.isFinite(n) ? Math.max(0, Math.floor(n)) : 0;
+    let frontier = [...found];
+    for (let hop = 0; hop < radius && frontier.length; hop++) {
+      const next = [];
+      const current = new Set(frontier);
+      for (const edge of edges) {
+        const a = canonOf2(edge.from), b = canonOf2(edge.to);
+        if (current.has(a) && !found.has(b)) {
+          found.add(b);
+          next.push(b);
+        }
+        if (current.has(b) && !found.has(a)) {
+          found.add(a);
+          next.push(a);
+        }
+      }
+      frontier = next;
+    }
+    return found;
+  }
+
+  // src/selection.ts
+  function notifySelection(previous, next, onSelect) {
+    if (previous !== next) onSelect?.(next);
+  }
 
   // src/interact.ts
   function relationsOf(ctx) {
@@ -403,7 +709,7 @@
     ];
   }
   function visibleEdges(ctx) {
-    return ctx.links.filter((l) => linkVisible(ctx.model, ctx.mode, l, ctx.nodes)).map((l) => ({ from: l.from, to: l.to }));
+    return effectiveLinks(ctx.model, ctx.mode, ctx.collapsed, ctx.nodes).map((l) => ({ from: l.from, to: l.to }));
   }
   function relationSet(ctx, rel, start) {
     const canon = (id) => canonOf(ctx.nodes, id);
@@ -424,7 +730,7 @@
   function install(ctx) {
     const { els, model } = ctx;
     const canon = (id) => canonOf(ctx.nodes, id);
-    const visibleNodes = () => model.nodes.filter((n) => nodeVisible(model, ctx.mode, n));
+    const visibleNodes = () => model.nodes.filter((n) => nodeVisible(model, ctx.mode, n, ctx.collapsed));
     const inspInset = () => els.inspector.classList.contains("open") ? 340 : 0;
     function activeSet(id) {
       const edges = visibleEdges(ctx);
@@ -441,7 +747,7 @@
           return ctx.filter === "gap" ? b === "gap" : !!n.upgrade && b !== "good";
         }).map((n) => canon(n.id)));
       }
-      if (ctx.query) return new Set(visibleNodes().filter((n) => matches(ctx, n)).map((n) => canon(n.id)));
+      if (ctx.query) return withinHops(edges, canon, visibleNodes().filter((n) => matches(ctx, n)).map((n) => n.id), ctx.hops);
       return null;
     }
     function trace(id) {
@@ -465,6 +771,7 @@
     }
     function select(id) {
       clearSim();
+      const previous = ctx.selected;
       ctx.selected = id ? canon(id) : null;
       ctx.hl = null;
       ctx.dismissed = false;
@@ -473,6 +780,7 @@
       ctx.fn.renderInspector();
       drawTrail();
       if (ctx.selected) revealNode(ctx.selected);
+      notifySelection(previous, ctx.selected, ctx.onSelect);
     }
     function overlay(edge, cls, delay, dur) {
       const o = edge.cloneNode(false);
@@ -565,7 +873,7 @@
       }
     }
     function rectOf(ids) {
-      const ps = ids.map((i) => ctx.geom.nodes[i]).filter((p) => !!p && !!ctx.nodes.get(p.id) && nodeVisible(model, ctx.mode, ctx.nodes.get(p.id)));
+      const ps = ids.map((i) => ctx.geom.nodes[i]).filter((p) => !!p && !!ctx.nodes.get(p.id) && nodeVisible(model, ctx.mode, ctx.nodes.get(p.id), ctx.collapsed));
       if (!ps.length) return null;
       const x1 = Math.min(...ps.map((p) => p.x)), y1 = Math.min(...ps.map((p) => p.y));
       const x2 = Math.max(...ps.map((p) => p.x + p.w)), y2 = Math.max(...ps.map((p) => p.y + p.h));
@@ -606,11 +914,11 @@
       clearSim();
       ctx.mode = id;
       const sel = ctx.selected && ctx.nodes.get(ctx.selected);
-      if (sel && !nodeVisible(model, id, sel)) select(null);
+      if (sel && !nodeVisible(model, id, sel, ctx.collapsed)) select(null);
       ctx.fn.paint(true);
       ctx.userMoved = false;
       ctx.fn.fitWidth(true);
-      const added = model.nodes.filter((n) => nodeVisible(model, id, n) && !nodeVisible(model, model.views?.[0]?.id ?? "all", n)).length;
+      const added = model.nodes.filter((n) => nodeVisible(model, id, n, ctx.collapsed) && !nodeVisible(model, model.views?.[0]?.id ?? "all", n, ctx.collapsed)).length;
       ctx.fn.announce(added ? `${model.views?.find((v) => v.id === id)?.label ?? id} view: ${added} groups added.` : `${model.views?.find((v) => v.id === id)?.label ?? id} view.`);
     }
     ctx.fn.trace = trace;
@@ -623,6 +931,16 @@
     ctx.fn.zoomToBand = zoomToBand;
     ctx.fn.escape = escape;
     ctx.fn.setMode = setMode;
+    ctx.fn.toggleGroup = (id) => {
+      const group = model.nodes.find((n) => n.id === id && n.kind === "group" && n.contains?.length);
+      if (!group) return;
+      const change = toggleGroupState(model, ctx.mode, ctx.collapsed, id);
+      if (!change) return;
+      ctx.collapsed = change.collapsed;
+      ctx.fn.paint();
+      ctx.fn.select(change.selected);
+      ctx.fn.announce(change.expanding ? `Expanded ${group.title}.` : `Collapsed into ${group.title}.`);
+    };
     ctx.fn.announce = (t) => {
       els.live.textContent = t;
     };
@@ -648,7 +966,6 @@
 
   // src/layout.ts
   var DEFAULTS = { pitch: 62, top: 64, gap: 34, padX: 24, visible: () => true };
-  var HEIGHT = { card: 54, group: 54, gateway: 54, placeholder: 54, chip: 34, start: 40, end: 40, event: 40, note: 40 };
   var LANE_PAD_TOP = 38;
   var LANE_PAD_BOTTOM = 14;
   function computeGeometry(m, opt = {}) {
@@ -662,20 +979,53 @@
     const world = { w: Math.max(1, x - o.gap + o.padX), h: 1 };
     const nodes = {};
     for (const n of m.nodes) {
-      const h = HEIGHT[n.kind] ?? 54;
-      const first = Math.min(Math.max(0, n.col), m.columns.length - 1);
+      const h = NODE_HEIGHT[n.kind] ?? 54;
+      if (m.layout === "free") {
+        nodes[n.id] = { id: n.id, x: n.x ?? 0, y: n.y ?? 0, w: n.w ?? 190, h: n.h ?? h };
+        continue;
+      }
+      const first = Math.min(Math.max(0, n.col ?? 0), m.columns.length - 1);
       const last = Math.min(m.columns.length - 1, first + (n.colSpan ?? 1) - 1);
       const x0 = xs[first] ?? o.padX;
       const x1 = (xs[last] ?? x0) + (m.columns[last]?.width ?? 0);
-      nodes[n.id] = { id: n.id, x: x0, y: o.top + 40 + n.row * o.pitch - h / 2, w: Math.max(1, x1 - x0), h };
+      nodes[n.id] = { id: n.id, x: x0, y: o.top + 40 + (n.row ?? 0) * o.pitch - h / 2, w: Math.max(1, x1 - x0), h };
     }
+    if (m.layout === "free") world.w = Math.max(world.w, ...Object.values(nodes).map((p) => p.x + p.w + o.padX), 1);
+    const loops = {};
     const lanes = {};
-    for (const l of m.lanes) {
-      const mem = m.nodes.filter((n) => n.lane === l.id && o.visible(n.id)).map((n) => nodes[n.id]);
-      if (!mem.length) continue;
-      const y1 = Math.min(...mem.map((p) => p.y)) - LANE_PAD_TOP;
-      const y2 = Math.max(...mem.map((p) => p.y + p.h)) + LANE_PAD_BOTTOM;
+    const visibleMembers = (id) => m.nodes.filter((n) => n.lane === id && o.visible(n.id)).map((n) => nodes[n.id]);
+    const ordered = m.lanes.map((l) => ({ l, mem: visibleMembers(l.id) })).filter((x2) => x2.mem.length).sort((a, b) => Math.min(...a.mem.map((p) => p.y)) - Math.min(...b.mem.map((p) => p.y)));
+    let previousBottom = -Infinity;
+    for (const { l, mem } of ordered) {
+      const top = Math.min(...mem.map((p) => p.y)) - LANE_PAD_TOP;
+      const shift = m.layout === "free" ? 0 : Math.max(0, previousBottom + 8 - top);
+      if (shift) for (const p of mem) p.y += shift;
+      const y1 = top + shift;
+      const laneNodeIds = new Set(mem.map((p) => p.id));
+      const possibleLoops = m.links.filter((link) => link.kind === "loop-back" && o.visible(link.from) && o.visible(link.to) && (laneNodeIds.has(link.from) || laneNodeIds.has(link.to))).length;
+      const bottom = Math.max(...mem.map((p) => p.y + p.h));
+      const y2 = bottom + (possibleLoops ? 10 + 8 * (possibleLoops - 1) : 0) + LANE_PAD_BOTTOM;
       lanes[l.id] = { x: 8, y: y1, w: world.w - 16, h: y2 - y1 };
+      previousBottom = y2;
+    }
+    const channelCounts = /* @__PURE__ */ new Map();
+    for (const link of m.links) {
+      if (link.kind !== "loop-back" || !o.visible(link.from) || !o.visible(link.to)) continue;
+      const a = nodes[link.from], b = nodes[link.to];
+      if (!a || !b) continue;
+      const lower = a.y + a.h >= b.y + b.h ? a : b;
+      const laneId = m.nodes.find((n) => n.id === lower.id)?.lane;
+      if (!laneId || !lanes[laneId]) continue;
+      const left = Math.min(a.x + a.w / 2, b.x + b.w / 2);
+      const right = Math.max(a.x + a.w / 2, b.x + b.w / 2);
+      const laneMembers = visibleMembers(laneId);
+      const crossed = laneMembers.filter((p) => p.x < right && p.x + p.w > left);
+      const lowestBottom = Math.max(a.y + a.h, b.y + b.h, ...crossed.map((p) => p.y + p.h));
+      const index = channelCounts.get(laneId) ?? 0;
+      loops[link.id] = { channelY: lowestBottom + 10 + 8 * index };
+      channelCounts.set(laneId, index + 1);
+      const lane = lanes[laneId];
+      lane.h = Math.max(lane.h, loops[link.id].channelY + LANE_PAD_BOTTOM - lane.y);
     }
     const all = Object.values(lanes);
     let bounds = { x: 0, y: 0, w: world.w, h: 1 };
@@ -684,7 +1034,7 @@
       bounds = { x: 8, y: top, w: world.w - 16, h: Math.max(...all.map((r) => r.y + r.h)) - top };
     }
     world.h = Math.max(1, bounds.y + bounds.h + 70);
-    return { xs, nodes, lanes, bounds, world };
+    return { xs, nodes, lanes, loops, bounds, world };
   }
 
   // src/routing.ts
@@ -695,14 +1045,85 @@
     const dir = y2 > y1 ? 1 : -1;
     return `M${x1},${y1} H${tx - r} Q${tx},${y1} ${tx},${y1 + dir * r} V${y2 - dir * r} Q${tx},${y2} ${tx + r},${y2} H${x2}`;
   }
+  function loopBack(x1, y1, x2, y2, channelY, detour = {}) {
+    x1 = Number.isFinite(x1) ? x1 : 0;
+    x2 = Number.isFinite(x2) ? x2 : 0;
+    y1 = Number.isFinite(y1) ? y1 : 0;
+    y2 = Number.isFinite(y2) ? y2 : 0;
+    channelY = Number.isFinite(channelY) ? channelY : Math.max(y1, y2) + 10;
+    channelY = Math.max(channelY, y1, y2);
+    const from = detour.from, to = detour.to;
+    const startX = from?.x ?? x1, endX = to?.x ?? x2;
+    const start = from ? `M${x1},${y1} V${from.y} H${startX}` : `M${x1},${y1}`;
+    const finish = to ? ` V${to.y} H${x2} V${y2}` : ` V${y2}`;
+    if (from || to) {
+      const dir2 = endX >= startX ? 1 : -1;
+      const r2 = Math.max(0, Math.min(8, Math.abs(endX - startX) / 2, (channelY - (from?.y ?? y1)) / 2, (channelY - (to?.y ?? y2)) / 2));
+      return `${start} V${channelY - r2} Q${startX},${channelY} ${startX + dir2 * r2},${channelY} H${endX - dir2 * r2} Q${endX},${channelY} ${endX},${channelY - r2}${finish}`;
+    }
+    const dx = x2 - x1;
+    const dir = dx >= 0 ? 1 : -1;
+    const run = Math.abs(dx) || 32;
+    const radius = Math.min(8, run / 2, (channelY - y1) / 2, (channelY - y2) / 2);
+    const r = Math.max(0, radius);
+    if (dx === 0) {
+      return `M${x1},${y1} V${channelY - r} Q${x1},${channelY} ${x1 + r},${channelY} H${x1 + 16} H${x1 - r} Q${x1},${channelY} ${x1},${channelY - r} V${y2}`;
+    }
+    return `M${x1},${y1} V${channelY - r} Q${x1},${channelY} ${x1 + dir * r},${channelY} H${x2 - dir * r} Q${x2},${channelY} ${x2},${channelY - r} V${y2}`;
+  }
+
+  // src/metrics.ts
+  function sparklinePoints(series, width, height) {
+    if (!Array.isArray(series) || series.length < 2 || series.some((v) => !Number.isFinite(v))) return "";
+    const min = Math.min(...series), max = Math.max(...series), span = max - min;
+    return series.map((v, i) => `${Math.round(i / (series.length - 1) * width * 100) / 100},${Math.round((span ? 1 - (v - min) / span : 0.5) * height * 100) / 100}`).join(" ");
+  }
+  function metricBadge(metric) {
+    if (!metric) return "";
+    const label = metric.label ?? "Metric";
+    const valStr = esc(String(metric.value));
+    const unitStr = metric.unit ? " " + esc(metric.unit) : "";
+    const title = `${esc(label)}: ${valStr}${unitStr}`;
+    const hasMax = metric.max != null && Number.isFinite(metric.max) && metric.max > 0;
+    const pct = hasMax && Number.isFinite(metric.value) ? Math.max(0, Math.min(100, metric.value / metric.max * 100)) : 0;
+    const bar = hasMax ? `<i style="width:${pct}%"></i>` : "";
+    return `<span class="metric-badge" title="${title}">${valStr}${unitStr}${bar}</span>`;
+  }
+  function sparkline(metric, width = 56, height = 12) {
+    if (!metric?.series || metric.series.length < 2) return "";
+    const points = sparklinePoints(metric.series, width, height);
+    if (!points) return "";
+    return `<svg class="spark" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" aria-hidden="true"><polyline points="${points}"/></svg>`;
+  }
 
   // src/render.ts
+  function loopRoute(ctx, fromId, toId, from, to, channel) {
+    const detourFor = (end, other) => {
+      const center = end.x + end.w / 2, bottom = end.y + end.h;
+      const blocker = ctx.model.nodes.filter((n) => n.id !== fromId && n.id !== toId && nodeVisible(ctx.model, ctx.mode, n, ctx.collapsed)).map((n) => ctx.geom.nodes[n.id]).filter((p) => !!p && p.x < center && center < p.x + p.w && p.y > bottom && p.y < channel).sort((a, b) => a.y - b.y)[0];
+      if (!blocker) return void 0;
+      return { x: other.x + other.w / 2 < center ? blocker.x - 10 : blocker.x + blocker.w + 10, y: (bottom + blocker.y) / 2 };
+    };
+    return loopBack(
+      from.x + from.w / 2,
+      from.y + from.h,
+      to.x + to.w / 2,
+      to.y + to.h,
+      channel,
+      { from: detourFor(from, to), to: detourFor(to, from) }
+    );
+  }
   function nodeHtml(ctx, n) {
+    const badge = metricBadge(n.metrics);
+    const spark = sparkline(n.metrics, 56, 12);
+    if (n.kind === "gateway") {
+      return `<svg class="gw" viewBox="0 0 100 100" preserveAspectRatio="none" aria-hidden="true"><polygon points="50,0 100,50 50,100 0,50"></polygon></svg><span class="gw-title">${esc(n.title)}</span>${badge}${spark}`;
+    }
     const m = ctx.model;
     const sid = nodeStateId(m, ctx.mode, n);
     const word = m.states[sid]?.word ?? sid;
     const bucket = bucketOf(m, sid);
-    const sub = n.subtitle ?? m.columns[n.col]?.title ?? "";
+    const sub = n.subtitle ?? m.columns[n.col ?? 0]?.title ?? "";
     const weight = Math.max(1, n.weight ?? 1);
     const showWord = n.kind !== "placeholder" && n.kind !== "note";
     const bar = weight > 1 && n.kind !== "chip" ? `<div class="bar"><i class="${["good", "neutral", "gap"].includes(bucket) ? bucket : "gap"}" style="width:100%"></i></div>` : "";
@@ -710,7 +1131,8 @@
     const upgrade = n.upgrade && bucket !== "good" ? `<span class="cor meas" title="${esc("Can improve: " + n.upgrade)}">\u2197</span>` : "";
     const arrow = n.kind === "chip" ? '<span aria-hidden="true">\u2191 </span>' : "";
     const lead = showWord ? `<b class="ev st-${cssId(sid)}">${esc(word)}</b> \xB7 ` : "";
-    return `<div class="t"><span class="newdot" title="Added in this view"></span><span class="name">${arrow}${esc(n.title)}</span></div><div class="s" title="${esc(sub)}">${lead}${esc(sub)}</div>${bar}${improved}${upgrade}`;
+    const fold = n.kind === "group" && n.contains?.length ? `<span class="fold">\u25B8 ${n.contains.length}</span>` : "";
+    return `<div class="t"><span class="newdot" title="Added in this view"></span><span class="name">${arrow}${esc(n.title)}</span>${fold}${badge}</div><div class="s${spark ? " has-spark" : ""}" title="${esc(sub)}">${lead}${esc(sub)}</div>${spark}${bar}${improved}${upgrade}`;
   }
   function build(ctx) {
     const { model, els } = ctx;
@@ -749,7 +1171,7 @@
       d.id = "n_" + n.id;
       d.tabIndex = 0;
       d.setAttribute("role", "button");
-      d.style.setProperty("--c", String(n.col));
+      d.style.setProperty("--c", String(n.col ?? 0));
       d.style.left = p.x + "px";
       d.style.top = p.y + "px";
       d.style.width = p.w + "px";
@@ -784,7 +1206,10 @@
         return;
       }
       const x1 = A.x + A.w, y1 = A.y + A.h / 2, x2 = B.x, y2 = B.y + B.h / 2, tx = x1 + gap / 2;
-      const path = sv("path", { d: elbow(x1, y1, x2 - 1, y2, tx), class: "edge", "data-i": String(i), "data-a": l.from, "data-b": l.to, "marker-end": "url(#arr)" });
+      const loop = l.kind === "loop-back";
+      const channel = ctx.geom.loops[l.id]?.channelY ?? Math.max(A.y + A.h, B.y + B.h) + 10;
+      const d = loop ? loopRoute(ctx, l.from, l.to, A, B, channel) : elbow(x1, y1, x2 - 1, y2, tx);
+      const path = sv("path", { d, class: "edge" + (loop ? " loop" : ""), "data-i": String(i), "data-a": l.from, "data-b": l.to, "marker-end": "url(#arr)" });
       els.layer.appendChild(path);
       ctx.edgeEls[i] = path;
       if (l.label) {
@@ -792,8 +1217,8 @@
         lab.dataset.i = String(i);
         lab.dataset.a = l.from;
         lab.dataset.b = l.to;
-        lab.style.left = (Math.abs(y2 - y1) < 1 ? (x1 + x2) / 2 : tx) + "px";
-        lab.style.top = (y1 + y2) / 2 + "px";
+        lab.style.left = (loop ? (A.x + A.w / 2 + B.x + B.w / 2) / 2 : Math.abs(y2 - y1) < 1 ? (x1 + x2) / 2 : tx) + "px";
+        lab.style.top = (loop ? ctx.geom.loops[l.id]?.channelY ?? Math.max(A.y + A.h, B.y + B.h) + 10 : (y1 + y2) / 2) + "px";
         els.world.appendChild(lab);
         ctx.labelEls[i] = lab;
       }
@@ -802,28 +1227,37 @@
   function paint(ctx, fromSwitch = false) {
     const { model } = ctx;
     const mode = ctx.mode;
-    ctx.geom = computeGeometry(model, { visible: (id) => {
+    const effective = effectiveLinks(model, mode, ctx.collapsed, ctx.nodes);
+    const effectiveById = new Map(effective.map((l) => [l.id, l]));
+    ctx.geom = computeGeometry({ ...model, links: effective }, { visible: (id) => {
       const n = ctx.nodes.get(id);
-      return !!n && nodeVisible(model, mode, n);
+      return !!n && nodeVisible(model, mode, n, ctx.collapsed);
     } });
+    ctx.els.world.style.height = ctx.geom.world.h + "px";
+    ctx.els.svg.setAttribute("height", String(ctx.geom.world.h));
     document.body.classList.toggle("alt", !!model.views && mode !== baselineView(model));
     for (const n of model.nodes) {
       const d = ctx.nodeEls.get(n.id);
       if (!d) continue;
+      const rect = ctx.geom.nodes[n.id];
+      if (rect) {
+        d.style.left = rect.x + "px";
+        d.style.top = rect.y + "px";
+      }
       const sid = nodeStateId(model, mode, n);
-      const show = nodeVisible(model, mode, n);
+      const show = nodeVisible(model, mode, n, ctx.collapsed);
       const bucket = bucketOf(model, sid);
       const cors = (isImproved(model, mode, n) ? 1 : 0) + (n.upgrade && bucket !== "good" ? 1 : 0);
       const fresh = isNew(model, mode, n);
-      d.className = "node st-" + cssId(sid) + (n.kind === "chip" ? " ref" : "") + ((n.colSpan ?? 1) > 1 ? " wide" : "") + (n.kind === "placeholder" ? " placeholder" : "") + (show ? "" : " off") + (fresh ? " isnew" : "") + (cors ? cors > 1 ? " hascor2" : " hascor" : "") + (ctx.selected && canonOf(ctx.nodes, n.id) === ctx.selected ? " sel" : "");
+      d.className = "node st-" + cssId(sid) + (n.kind === "chip" ? " ref" : "") + (n.kind === "gateway" ? " gateway" : "") + ((n.colSpan ?? 1) > 1 ? " wide" : "") + (n.kind === "placeholder" ? " placeholder" : "") + (show ? "" : " off") + (fresh ? " isnew" : "") + (cors ? cors > 1 ? " hascor2" : " hascor" : "") + (ctx.selected && canonOf(ctx.nodes, n.id) === ctx.selected ? " sel" : "") + (metricBadge(n.metrics) ? " has-metrics" : "");
       d.innerHTML = nodeHtml(ctx, n);
       d.setAttribute("aria-hidden", show ? "false" : "true");
       d.tabIndex = show ? 0 : -1;
       const word = model.states[sid]?.word ?? sid;
       const lane = model.lanes.find((l) => l.id === n.lane)?.title ?? n.lane;
-      d.setAttribute("aria-label", n.kind === "chip" ? `${n.title}: a reference to the node in the ${lane} lane. Press Enter to select it.` : `${n.title}. ${n.subtitle ?? model.columns[n.col]?.title ?? ""}, ${word}. Press Enter to inspect.`);
+      d.setAttribute("aria-label", n.kind === "chip" ? `${n.title}: a reference to the node in the ${lane} lane. Press Enter to select it.` : `${n.title}. ${n.subtitle ?? model.columns[n.col ?? 0]?.title ?? ""}, ${word}. Press Enter to inspect.`);
       if (fromSwitch && fresh && !ctx.reduced) {
-        d.style.transitionDelay = n.col * 60 + "ms";
+        d.style.transitionDelay = (n.col ?? 0) * 60 + "ms";
         d.classList.add("pulse");
         window.setTimeout(() => {
           d.style.transitionDelay = "";
@@ -836,8 +1270,24 @@
     ctx.links.forEach((l, i) => {
       const p = ctx.edgeEls[i];
       if (!p) return;
-      const vis = linkVisible(model, mode, l, ctx.nodes);
-      p.setAttribute("class", "edge st-" + cssId(linkStateId(model, mode, l)) + (vis ? "" : " off"));
+      const edge = effectiveById.get(l.id);
+      const vis = !!edge;
+      const a = edge && ctx.geom.nodes[edge.from], b = edge && ctx.geom.nodes[edge.to];
+      const loop = edge?.kind === "loop-back";
+      if (a && b) {
+        p.dataset.a = edge.from;
+        p.dataset.b = edge.to;
+        const channel = ctx.geom.loops[edge.id]?.channelY ?? Math.max(a.y + a.h, b.y + b.h) + 10;
+        p.setAttribute("d", loop ? loopRoute(ctx, edge.from, edge.to, a, b, channel) : elbow(a.x + a.w, a.y + a.h / 2, b.x - 1, b.y + b.h / 2, a.x + a.w + DEFAULTS.gap / 2));
+        const lab = ctx.labelEls[i];
+        if (lab) {
+          lab.dataset.a = edge.from;
+          lab.dataset.b = edge.to;
+          lab.style.left = (loop ? (a.x + a.w / 2 + b.x + b.w / 2) / 2 : Math.abs(b.y + b.h / 2 - a.y - a.h / 2) < 1 ? (a.x + a.w + b.x) / 2 : a.x + a.w + DEFAULTS.gap / 2) + "px";
+          lab.style.top = (loop ? channel : (a.y + a.h / 2 + b.y + b.h / 2) / 2) + "px";
+        }
+      }
+      p.setAttribute("class", "edge st-" + cssId(edge?.state ?? linkStateId(model, mode, l)) + (loop ? " loop" : "") + (vis ? "" : " off"));
       ctx.labelEls[i]?.classList.toggle("off", !vis);
     });
     for (const l of model.lanes) {
@@ -960,6 +1410,7 @@
     }
     function placeHeaders() {
       const cols = els.cols;
+      cols.style.display = model.columns.length ? "" : "none";
       if (!cols.firstChild) {
         model.columns.forEach((c, i2) => {
           const h = el("div", "hd");
@@ -1165,7 +1616,13 @@
       } else if (k === "n" || k === "N") ctx.fn.toggleNotes();
       else if (k === "v" || k === "V") setTool("select");
       else if (k === "h" || k === "H") setTool("hand");
-      else if (k === "+" || k === "=") zoomBy(1.25);
+      else if (k === "e" || k === "E") {
+        const selected = ctx.selected && ctx.nodes.get(ctx.selected);
+        if (selected) {
+          const group = selected.kind === "group" ? selected : ctx.model.nodes.find((n) => n.kind === "group" && n.contains?.includes(selected.id));
+          if (group) ctx.fn.toggleGroup(group.id);
+        }
+      } else if (k === "+" || k === "=") zoomBy(1.25);
       else if (k === "-" || k === "_") zoomBy(1 / 1.25);
       else if (k === "0") {
         ctx.userMoved = false;
@@ -1219,6 +1676,7 @@
         ctx.fn.zoomToPath();
       }));
       box.querySelectorAll("[data-act]").forEach((b) => b.addEventListener("click", () => ctx.fn.simulate(b.dataset.act ?? "")));
+      box.querySelectorAll("[data-toggle-group]").forEach((b) => b.addEventListener("click", () => ctx.fn.toggleGroup(b.dataset.toggleGroup ?? "")));
       box.querySelector("#simReset")?.addEventListener("click", () => {
         ctx.fn.clearSim();
         ctx.fn.renderInspector();
@@ -1227,7 +1685,7 @@
       box.querySelector("#zPath")?.addEventListener("click", () => ctx.fn.zoomToPath());
       box.querySelector("#zBand")?.addEventListener("click", () => {
         const n = ctx.selected ? ctx.nodes.get(ctx.selected) : void 0;
-        if (n) ctx.fn.zoomToBand(n.lane);
+        if (n?.lane) ctx.fn.zoomToBand(n.lane);
       });
     }
     function renderInspector() {
@@ -1235,7 +1693,7 @@
       const sel = ctx.selected ? ctx.nodes.get(ctx.selected) : void 0;
       const head = `<div class="insp-h"><span>Inspector</span><button type="button" id="hideInsp" aria-label="Close the inspector">Close \u2715</button></div>`;
       if (!sel) {
-        const found = ctx.query && !ctx.dismissed ? model.nodes.filter((n) => nodeVisible(model, ctx.mode, n) && matches(ctx, n)) : [];
+        const found = ctx.query && !ctx.dismissed ? model.nodes.filter((n) => nodeVisible(model, ctx.mode, n, ctx.collapsed) && matches(ctx, n)) : [];
         const open = found.length > 0;
         box.classList.toggle("open", open);
         ws.classList.toggle("inspopen", open);
@@ -1244,7 +1702,7 @@
         const rows = found.map((f) => {
           const b = bucketOf(model, nodeStateId(model, ctx.mode, f));
           const hits = (f.members ?? []).filter((m) => m.toLowerCase().includes(ctx.query)).length;
-          return `<button type="button" class="dr" data-g="${esc(f.id)}"><span class="dbar" style="background:var(--${BUCKET_COLOR[b]})"></span><span class="dtx"><span class="dn">${esc(f.title)}</span><span class="dk">${hits} match \xB7 ${esc(model.columns[f.col]?.title ?? "")}</span></span></button>`;
+          return `<button type="button" class="dr" data-g="${esc(f.id)}"><span class="dbar" style="background:var(--${BUCKET_COLOR[b]})"></span><span class="dtx"><span class="dn">${esc(f.title)}</span><span class="dk">${hits} match \xB7 ${esc(model.columns[f.col ?? 0]?.title ?? "")}</span></span></button>`;
         }).join("");
         box.innerHTML = head + `<div class="insp-b"><div class="insp-sec"><b>${found.length}</b> group${found.length === 1 ? "" : "s"} match \u201C${esc(ctx.query)}\u201D</div><div class="drill">${rows}</div></div>`;
         wire(box);
@@ -1273,10 +1731,23 @@
       const pills = `<span class="pill ${PILL[st?.tone ?? "muted"]}">${esc(st?.word ?? sid)}</span>` + (isImproved(model, ctx.mode, sel) ? '<span class="pill info">gap filled</span>' : "") + (isNew(model, ctx.mode, sel) ? '<span class="pill muted">new in this view</span>' : "");
       const actions = (model.inspector?.actions ?? []).map((a) => `<button type="button" class="danger" data-act="${esc(a.id)}">\u25B6 ${esc(a.label)}</button>`).join("");
       const members = sel.members ?? [];
+      const owner = groupFor(model, sel.id);
+      const foldAction = sel.kind === "group" && sel.contains?.length && ctx.collapsed.has(sel.id) ? `<button type="button" data-toggle-group="${esc(sel.id)}">Expand group</button>` : owner && !ctx.collapsed.has(owner.id) ? `<button type="button" data-toggle-group="${esc(owner.id)}">Collapse into ${esc(owner.title)}</button>` : "";
+      const exits = sel.kind === "gateway" ? effectiveLinks(model, ctx.mode, ctx.collapsed, ctx.nodes).filter((l) => l.from === sel.id).map((l) => {
+        const target = ctx.nodes.get(l.to);
+        return `<div class="dr"><span class="dtx"><span class="dn">${esc(l.label ?? "Unlabelled")}</span><span class="dk">${esc(target?.title ?? l.to)}</span></span></div>`;
+      }).join("") : "";
+      const metric = sel.metrics;
+      const series = metric?.series ?? [];
+      const points = sparklinePoints(series, 300, 40);
+      const metricHtml = metric ? `<div class="insp-sec metrics"><b>Metrics</b><table class="meta"><tr><th>label</th><td>${esc(metric.label ?? "Metric")}</td></tr><tr><th>value</th><td>${esc(String(metric.value))} ${esc(metric.unit ?? "")}</td></tr>${metric.max != null ? `<tr><th>max</th><td>${esc(String(metric.max))} ${esc(metric.unit ?? "")}</td></tr>` : ""}</table>${points ? `<svg width="300" height="40" viewBox="0 0 300 40" role="img" aria-label="Metric trend"><polyline points="${points}"/></svg><div class="metric-range"><span>${esc(String(Math.min(...series)))}</span><span>${esc(String(Math.max(...series)))}</span></div>` : ""}</div>` : "";
       box.innerHTML = head + `<div class="counts">${counts}</div>
-      <div class="insp-b"><div class="insp-sec"><p class="nname">${esc(sel.title)}</p><div class="nkind">${esc(model.columns[sel.col]?.title ?? "")} \xB7 ${esc(lane?.title ?? sel.lane)}</div><div class="pillrow">${pills}</div>${sel.subtitle ? `<p class="note">${esc(sel.subtitle)}</p>` : ""}</div>
+      <div class="insp-b"><div class="insp-sec"><p class="nname">${esc(sel.title)}</p><div class="nkind">${esc(model.columns[sel.col ?? 0]?.title ?? "")} \xB7 ${esc(lane?.title ?? sel.lane)}</div><div class="pillrow">${pills}</div>${sel.subtitle ? `<p class="note">${esc(sel.subtitle)}</p>` : ""}</div>
       <div class="insp-sec"><b>Details</b><table class="meta"><tr><th>state</th><td>${esc(st?.word ?? sid)}</td></tr><tr><th>members</th><td>${Math.max(1, sel.weight ?? 1)}</td></tr><tr><th>lane</th><td>${esc(lane?.title ?? sel.lane)}${lane?.badge ? ` (${esc(lane.badge)})` : ""}</td></tr>${sel.upgrade && bucket !== "good" ? `<tr><th>can improve</th><td>${esc(sel.upgrade)}</td></tr>` : ""}</table></div>
+      ${metricHtml}
+      ${sel.kind === "gateway" ? `<div class="insp-sec"><b>Exits</b><div class="drill">${exits}</div></div>` : ""}
       ${members.length ? `<div class="insp-sec"><b>Members</b> (${Math.max(members.length, sel.weight ?? 0)})<input id="mq" type="search" placeholder="Filter ${members.length} members\u2026" aria-label="Filter members"><div class="drill" id="mlist"></div><p class="drill-hint" id="mcount"></p></div>` : `<div class="insp-sec"><p class="note">No member names are recorded for this group.</p></div>`}
+      ${foldAction ? `<div class="acts">${foldAction}</div>` : ""}
       <div class="acts"><button type="button" id="zPath">Zoom to path</button><button type="button" id="zBand">Go to lane</button></div>
       ${actions ? `<div class="acts">${actions}<button type="button" id="simReset"${ctx.simActive ? "" : " hidden"}>Reset</button></div>` : ""}</div>`;
       wire(box);
@@ -1312,7 +1783,7 @@
     const label = (k) => model.meta.labels?.[k] ?? DEFAULT_LABELS[k] ?? k;
     const visible = (id) => {
       const n = ctx.nodes.get(id);
-      return !!n && nodeVisible(model, ctx.mode, n);
+      return !!n && nodeVisible(model, ctx.mode, n, ctx.collapsed);
     };
     function countUp(node, to, ms = 700) {
       if (ctx.reduced) {
@@ -1329,6 +1800,7 @@
     }
     function buildStrip() {
       const box = els.strip;
+      box.style.display = model.columns.length ? "" : "none";
       box.style.gridTemplateColumns = `repeat(${Math.max(1, model.columns.length)}, minmax(0, 1fr))`;
       if (!box.firstChild) {
         box.innerHTML = model.columns.map((c) => `<div class="lcell"><div class="ln">${esc(c.title)}</div><div class="lb"><i class="good"></i><i class="neutral"></i><i class="gap"></i></div><div class="lv"></div></div>`).join("");
@@ -1338,9 +1810,9 @@
         let tot = 0, good = 0, neutral = 0, gap = 0;
         for (const n of model.nodes) {
           if (n.col !== i || n.kind === "chip") continue;
+          if (!visible(n.id)) continue;
           const w = Math.max(1, n.weight ?? 1);
           tot += w;
-          if (!visible(n.id)) continue;
           const b = bucketOf(model, nodeStateId(model, ctx.mode, n));
           if (b === "good") good += w;
           else if (b === "neutral") neutral += w;
@@ -1360,9 +1832,8 @@
     function buildTiles() {
       const k = els.tiles;
       let good = 0, neutral = 0;
-      for (const l of ctx.links) {
-        if (!linkVisible(model, ctx.mode, l, ctx.nodes)) continue;
-        const b = bucketOf(model, linkStateId(model, ctx.mode, l));
+      for (const l of effectiveLinks(model, ctx.mode, ctx.collapsed, ctx.nodes)) {
+        const b = bucketOf(model, l.state);
         if (b === "good") good++;
         else if (b === "neutral") neutral++;
       }
@@ -1418,7 +1889,7 @@
       const rows = model.nodes.filter((n) => visible(n.id) && n.kind !== "chip").map((n) => {
         const sid = nodeStateId(model, ctx.mode, n);
         const lane = model.lanes.find((l) => l.id === n.lane)?.title ?? n.lane;
-        return `<tr><th scope="row">${esc(model.columns[n.col]?.title ?? "")}</th><td>${esc(lane)}</td><td>${esc(n.title)}</td><td>${esc(model.states[sid]?.word ?? sid)}</td><td>${Math.max(1, n.weight ?? 1)}</td><td>${esc(n.subtitle ?? "")}</td><td>${esc(n.upgrade ?? "")}</td></tr>`;
+        return `<tr><th scope="row">${esc(columnTitle(model, n))}</th><td>${esc(lane)}</td><td>${esc(n.title)}</td><td>${esc(model.states[sid]?.word ?? sid)}</td><td>${Math.max(1, n.weight ?? 1)}</td><td>${esc(n.subtitle ?? "")}</td><td>${esc(n.upgrade ?? "")}</td></tr>`;
       }).join("");
       els.table.innerHTML = `<thead><tr><th scope="col">Column</th><th scope="col">Lane</th><th scope="col">Group</th><th scope="col">State</th><th scope="col">Members</th><th scope="col">Detail</th><th scope="col">Can improve</th></tr></thead><tbody>${rows}</tbody>`;
     }
@@ -1460,6 +1931,10 @@
         ctx.fn.renderInspector();
       }
     });
+    on(ctx, els.hops, "change", () => {
+      ctx.hops = Number(els.hops.value);
+      ctx.fn.trace(ctx.selected);
+    });
     on(ctx, els.q, "keydown", (e) => {
       if (e.key !== "Enter" || !ctx.query) return;
       const ids = model.nodes.filter((x) => visible(x.id) && matches(ctx, x)).map((x) => x.id);
@@ -1499,6 +1974,11 @@
         const a = anchorOf(n.anchor);
         if (!a) continue;
         let r = a.getBoundingClientRect();
+        if (!r.width && !r.height) {
+          let d = a.closest("details");
+          while (d && d.open) d = d.parentElement?.closest("details") ?? null;
+          if (d) r = d.getBoundingClientRect();
+        }
         if (!r.width && !r.height) continue;
         if (a.id === "inspector" && !a.classList.contains("open")) {
           const vr = els.vp.getBoundingClientRect();
@@ -1588,6 +2068,365 @@
     ctx.fn.placeMarkers = placeMarkers;
   }
 
+  // src/playback.ts
+  function planScenario(model, scenario) {
+    const source = scenario.steps ?? [];
+    const mode = source.some((s) => s?.at !== void 0) ? "elapsed" : "none";
+    const start = source[0]?.at ?? 0;
+    const scale = mode === "elapsed" ? Math.max(1, ...source.slice(1).map((s, i) => {
+      const gap = ((s?.at ?? 0) - (source[i]?.at ?? 0)) * 1e3;
+      return gap > 0 ? (source[i]?.dur ?? 900) / gap : 1;
+    })) : 1;
+    const steps = [];
+    for (let i = 0; i < source.length; i++) {
+      const s = source[i];
+      if (!s || typeof s !== "object") continue;
+      const link = model.links.find((l) => l.id === s.link);
+      if (!link) continue;
+      const from = model.nodes.find((n) => n.id === link.from);
+      const to = model.nodes.find((n) => n.id === link.to);
+      const dur = Number.isFinite(s.dur) && (s.dur ?? 0) > 0 ? s.dur : 900;
+      const proposed = mode === "elapsed" ? Math.max(0, ((s.at ?? 0) - start) * 1e3 * scale) : 0;
+      const at = steps.length === 0 ? 0 : Math.max(proposed, steps.at(-1).at + steps.at(-1).dur);
+      steps.push({ link: s.link, from: from?.ref ?? link.from, to: to?.ref ?? link.to, at, dur, caption: s.caption ?? `${from?.title ?? link.from} to ${to?.title ?? link.to}`, index: i });
+    }
+    return { steps, mode, totalMs: steps.length ? steps.at(-1).at + steps.at(-1).dur : 0 };
+  }
+  function positionAt(plan, tMs) {
+    if (!plan.steps.length) return { stepIndex: -1, progress: 0, done: true };
+    const t = Number.isNaN(tMs) ? 0 : Math.max(0, tMs);
+    if (t >= plan.totalMs) return { stepIndex: plan.steps.length - 1, progress: 1, done: true };
+    let i = plan.steps.length - 1;
+    while (i > 0 && t < plan.steps[i].at) i--;
+    const s = plan.steps[i];
+    return { stepIndex: i, progress: Math.max(0, Math.min(1, (t - s.at) / s.dur)), done: false };
+  }
+  function slaState(elapsedSec, sla) {
+    if (elapsedSec >= sla) return "breach";
+    return elapsedSec >= sla * 0.8 ? "warn" : "ok";
+  }
+  function formatElapsed(sec) {
+    const n = Math.max(0, Math.round(Number.isFinite(sec) ? sec : 0));
+    const m = Math.floor(n / 60), s = String(n % 60).padStart(2, "0");
+    return n < 3600 ? `${m}:${s}` : `${Math.floor(n / 3600)}:${String(m % 60).padStart(2, "0")}:${s}`;
+  }
+  function exitsOf(model, nodeId) {
+    const canon = (id) => model.nodes.find((n) => n.id === id)?.ref ?? id;
+    return model.links.filter((l) => canon(l.from) === canon(nodeId));
+  }
+  function suggestedExit(exits, nextLink) {
+    return exits.find((l) => l.id === nextLink);
+  }
+  function buildManualRoute(model, choiceLink) {
+    const route = [choiceLink];
+    const seen = /* @__PURE__ */ new Set([choiceLink.id]);
+    let at = choiceLink.to;
+    while (exitsOf(model, at).length === 1) {
+      const next = exitsOf(model, at)[0];
+      if (seen.has(next.id)) break;
+      route.push(next);
+      seen.add(next.id);
+      at = next.to;
+    }
+    return route;
+  }
+  function extendScenarioWithRoute(scenario, plan, stepIndex, route) {
+    const isElapsed = plan.mode === "elapsed" || scenario.steps.some((s) => s?.at !== void 0);
+    const prefix = scenario.steps.slice(0, stepIndex + 1).map((s) => ({ ...s }));
+    for (let i = prefix.length; i <= stepIndex && i < plan.steps.length; i++) {
+      const ps = plan.steps[i];
+      prefix.push({ link: ps.link, dur: ps.dur, caption: ps.caption });
+    }
+    let lastAt = 0;
+    if (isElapsed) {
+      const lastWithAt = [...prefix].reverse().find((s) => s?.at !== void 0);
+      lastAt = lastWithAt?.at ?? 0;
+    }
+    const newSteps = route.map((l) => {
+      const step = { link: l.id };
+      if (isElapsed) {
+        lastAt += 1;
+        step.at = lastAt;
+      }
+      return step;
+    });
+    return {
+      ...scenario,
+      steps: [...prefix, ...newSteps]
+    };
+  }
+
+  // src/playbackui.ts
+  function install7(ctx) {
+    const e = ctx.els;
+    const scenarios = ctx.model.scenarios ?? [];
+    e.playbar.hidden = !scenarios.length;
+    e.pbScenario.replaceChildren(...scenarios.map((s) => {
+      const o = document.createElement("option");
+      o.value = s.id;
+      o.textContent = s.label;
+      return o;
+    }));
+    let scenario = scenarios[0];
+    let plan = scenario ? planScenario(ctx.model, scenario) : { steps: [], mode: "none", totalMs: 0 };
+    let t = 0, idx = -1, playing = false, frame = 0, timer = 0, stamp = 0, choicesKey = "";
+    let markedEdges = [];
+    let markedNodes = [];
+    const token = sv("circle", { id: "token", class: "token", r: "6" });
+    e.layer.appendChild(token);
+    const pathOf = (link) => ctx.edgeEls[ctx.links.findIndex((l) => l.id === link)];
+    const nodeOf = (id) => ctx.nodeEls.get(id);
+    const clearMarks = () => {
+      for (const p of markedEdges) p.classList.remove("playing", "visited");
+      for (const n of markedNodes) n.classList.remove("playing", "visited");
+      markedEdges = [];
+      markedNodes = [];
+    };
+    function stop() {
+      playing = false;
+      cancelAnimationFrame(frame);
+      clearTimeout(timer);
+      document.body.classList.remove("playing");
+      e.pbPlay.setAttribute("aria-label", "Play");
+      e.pbPlay.textContent = "\u25B6";
+    }
+    function pause() {
+      if (!playing) return;
+      stop();
+      const p = positionAt(plan, t);
+      draw(p.stepIndex, ctx.reduced ? 1 : p.progress);
+    }
+    function choices(step2) {
+      if (playing || !step2) {
+        if (choicesKey !== "") {
+          e.pbChoices.replaceChildren();
+          choicesKey = "";
+        }
+        return;
+      }
+      const key = `${scenario?.id ?? ""}|${idx}|${plan.steps.length}|${plan.steps[idx + 1]?.link ?? ""}`;
+      if (key === choicesKey) return;
+      choicesKey = key;
+      e.pbChoices.replaceChildren();
+      const exits = exitsOf(ctx.model, step2.to);
+      if (exits.length < 2) return;
+      const suggested = suggestedExit(exits, plan.steps[idx + 1]?.link);
+      for (const link of exits) {
+        const b = document.createElement("button");
+        b.type = "button";
+        b.textContent = link.label ?? ctx.nodes.get(link.to)?.title ?? link.to;
+        b.dataset.link = link.id;
+        if (link.id === suggested?.id) b.classList.add("suggested");
+        b.addEventListener("click", () => {
+          if (!scenario) return;
+          const route = buildManualRoute(ctx.model, link);
+          scenario = extendScenarioWithRoute(scenario, plan, idx, route);
+          plan = planScenario(ctx.model, scenario);
+          t = plan.steps[idx + 1]?.at ?? 0;
+          play();
+        });
+        e.pbChoices.appendChild(b);
+      }
+    }
+    function draw(stepIndex, progress) {
+      const step2 = plan.steps[stepIndex];
+      clearMarks();
+      if (!step2) {
+        token.style.display = "none";
+        return;
+      }
+      token.style.display = "";
+      for (let i = 0; i < stepIndex; i++) {
+        const s = plan.steps[i];
+        const p = pathOf(s.link);
+        if (p) {
+          p.classList.add("visited");
+          markedEdges.push(p);
+        }
+        const n = nodeOf(s.to);
+        if (n) {
+          n.classList.add("visited");
+          markedNodes.push(n);
+        }
+      }
+      const path = pathOf(step2.link);
+      if (path) {
+        path.classList.add("playing");
+        markedEdges.push(path);
+      }
+      const node = nodeOf(step2.to);
+      if (node) {
+        node.classList.add("playing");
+        markedNodes.push(node);
+      }
+      if (path && !path.classList.contains("off")) {
+        const p = path.getPointAtLength(path.getTotalLength() * progress);
+        token.setAttribute("cx", String(p.x));
+        token.setAttribute("cy", String(p.y));
+      } else token.style.display = "none";
+      e.pbCaption.textContent = step2.caption;
+      e.pbScrub.value = String(plan.totalMs ? Math.round(t / plan.totalMs * 1e3) : 0);
+      e.pbScrub.setAttribute("aria-valuetext", `Step ${stepIndex + 1} of ${plan.steps.length}: ${step2.caption}`);
+      e.pbCounter.className = "";
+      e.pbCounter.hidden = plan.mode === "none";
+      if (plan.mode === "elapsed") {
+        const sec = scenario?.steps[step2.index]?.at ?? 0;
+        const sla = ctx.nodes.get(step2.to)?.sla;
+        e.pbCounter.textContent = sla === void 0 ? formatElapsed(sec) : `${formatElapsed(sec)} / ${formatElapsed(sla)}`;
+        if (sla !== void 0) e.pbCounter.classList.add(slaState(sec, sla));
+      }
+      if (idx !== stepIndex) ctx.fn.announce(step2.caption);
+      idx = stepIndex;
+      choices(step2);
+    }
+    function rewind() {
+      stop();
+      t = 0;
+      idx = -1;
+      clearMarks();
+      choicesKey = "";
+      e.pbCaption.textContent = "";
+      e.pbCounter.hidden = true;
+      e.pbCounter.className = "";
+      e.pbChoices.replaceChildren();
+      token.style.display = "none";
+      e.pbScrub.value = "0";
+      e.pbScrub.setAttribute("aria-valuetext", "");
+    }
+    function select(id) {
+      scenario = scenarios.find((s) => s.id === id) ?? scenarios[0];
+      plan = scenario ? planScenario(ctx.model, scenario) : { steps: [], mode: "none", totalMs: 0 };
+      e.pbScenario.value = scenario?.id ?? "";
+      rewind();
+    }
+    function seek(value) {
+      stop();
+      t = Math.max(0, Math.min(plan.totalMs, Number.isFinite(value) ? value : 0));
+      const p = positionAt(plan, t);
+      draw(p.stepIndex, ctx.reduced ? 1 : p.progress);
+    }
+    function tick(now) {
+      if (!playing) return;
+      if (!stamp) stamp = now;
+      const delta = (now - stamp) * Number(e.pbSpeed.value || 1);
+      stamp = now;
+      t = Math.min(plan.totalMs, t + delta);
+      const p = positionAt(plan, t);
+      if (p.done) {
+        stop();
+        draw(p.stepIndex, 1);
+        return;
+      }
+      draw(p.stepIndex, p.progress);
+      frame = requestAnimationFrame(tick);
+    }
+    function reducedStep() {
+      if (!playing) return;
+      const next = Math.min(plan.steps.length - 1, idx + 1);
+      if (next < 0) {
+        stop();
+        return;
+      }
+      t = plan.steps[next].at + plan.steps[next].dur;
+      if (next === plan.steps.length - 1) stop();
+      draw(next, 1);
+      if (playing) timer = window.setTimeout(reducedStep, 1e3 / Number(e.pbSpeed.value || 1));
+    }
+    function play(id) {
+      if (id && id !== scenario?.id) select(id);
+      stop();
+      if (!plan.steps.length) return;
+      if (t >= plan.totalMs) {
+        t = 0;
+        idx = -1;
+      }
+      playing = true;
+      document.body.classList.add("playing");
+      e.pbPlay.setAttribute("aria-label", "Pause");
+      e.pbPlay.textContent = "\u275A\u275A";
+      e.pbChoices.replaceChildren();
+      choicesKey = "";
+      if (ctx.reduced) reducedStep();
+      else {
+        stamp = 0;
+        frame = requestAnimationFrame(tick);
+      }
+    }
+    function step() {
+      stop();
+      const next = Math.min(idx + 1, plan.steps.length - 1);
+      if (next < 0) return;
+      t = plan.steps[next].at + plan.steps[next].dur;
+      draw(next, 1);
+    }
+    on(ctx, e.pbScenario, "change", () => select(e.pbScenario.value));
+    on(ctx, e.pbPlay, "click", () => playing ? pause() : play());
+    on(ctx, e.pbStep, "click", step);
+    on(ctx, e.pbReset, "click", () => rewind());
+    on(ctx, e.pbScrub, "input", () => seek(Number(e.pbScrub.value) / 1e3 * plan.totalMs));
+    on(ctx, document, "keydown", (event) => {
+      if (event.ctrlKey || event.metaKey || event.altKey || event.target instanceof HTMLElement && (event.target.isContentEditable || /INPUT|TEXTAREA|SELECT/.test(event.target.tagName))) return;
+      if (event.key.toLowerCase() === "p") {
+        event.preventDefault();
+        playing ? pause() : play();
+      }
+      if (event.key === ".") {
+        event.preventDefault();
+        step();
+      }
+    });
+    ctx.disposers.push(() => {
+      stop();
+      token.remove();
+    });
+    select(scenario?.id ?? "");
+    return {
+      play,
+      pause,
+      step,
+      seek,
+      playback: () => ({ scenario: scenario?.id ?? null, step: idx, playing, t }),
+      restore: (state) => {
+        if (!state.scenario || !scenarios.some((s) => s.id === state.scenario)) return;
+        select(state.scenario);
+        const current = plan.steps[state.step];
+        if (!current) return;
+        t = Math.max(current.at, Math.min(current.at + current.dur, state.t));
+        draw(state.step, ctx.reduced ? 1 : current.dur > 0 ? (t - current.at) / current.dur : 1);
+        if (state.playing) play();
+      },
+      reset: () => rewind()
+    };
+  }
+
+  // src/diff.ts
+  var fields = ["state", "stateIn", "title", "subtitle", "weight", "metrics", "visibleIn", "lane", "sla"];
+  function stableStringify(val) {
+    if (val === void 0) return "undefined";
+    if (val === null) return "null";
+    if (typeof val === "number") return Number.isFinite(val) ? JSON.stringify(val) : String(val);
+    if (typeof val === "bigint") return String(val);
+    if (typeof val === "object") {
+      if (Array.isArray(val)) return `[${val.map(stableStringify).join(",")}]`;
+      const rec = val;
+      const keys = Object.keys(rec).filter((k) => rec[k] !== void 0).sort();
+      return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(rec[k])}`).join(",")}}`;
+    }
+    return JSON.stringify(val) ?? "undefined";
+  }
+  function diffModels(a, b) {
+    const old = new Map(a.nodes.map((n) => [n.id, n]));
+    const now = new Map(b.nodes.map((n) => [n.id, n]));
+    return {
+      added: b.nodes.filter((n) => !old.has(n.id)).map((n) => n.id),
+      removed: a.nodes.filter((n) => !now.has(n.id)).map((n) => n.id),
+      changed: b.nodes.filter((n) => {
+        const prev = old.get(n.id);
+        return prev && fields.some((k) => stableStringify(prev[k]) !== stableStringify(n[k]));
+      }).map((n) => n.id)
+    };
+  }
+
   // src/engine.ts
   var IDS = {
     vp: "viewport",
@@ -1606,6 +2445,7 @@
     ledger: "ledger",
     table: "tbl",
     q: "q",
+    hops: "hops",
     matchinfo: "matchinfo",
     modeSwitch: "modeSwitch",
     drawer: "drawer",
@@ -1617,7 +2457,18 @@
     title: "title",
     readat: "readat",
     help: "help",
-    footer: "footer"
+    footer: "footer",
+    playbar: "playbar",
+    pbScenario: "pbScenario",
+    pbPlay: "pbPlay",
+    pbStep: "pbStep",
+    pbReset: "pbReset",
+    pbSpeed: "pbSpeed",
+    pbScrub: "pbScrub",
+    pbCaption: "pbCaption",
+    pbCounter: "pbCounter",
+    pbChoices: "pbChoices",
+    banner: "banner"
   };
   function findEls(root) {
     const out = {};
@@ -1632,6 +2483,7 @@
     if (!model || !Array.isArray(model.columns) || !Array.isArray(model.lanes) || !Array.isArray(model.nodes) || !Array.isArray(model.links) || !model.states) {
       throw new Error("flow-studio: the model needs columns, lanes, states, nodes and links");
     }
+    if (model.layout === "auto") model = autoLayout(model);
     const els = findEls(root);
     const issues = validateModel(model);
     const errors = issues.filter((i) => i.level === "error");
@@ -1642,17 +2494,20 @@
       model,
       root,
       els,
+      onSelect: opts.onSelect,
       notes: opts.notes && opts.notes.length ? opts.notes : model.notes ?? [],
       nodes: new Map(model.nodes.map((n) => [n.id, n])),
       links: model.links,
-      geom: { xs: [], nodes: {}, lanes: {}, bounds: { x: 0, y: 0, w: 1, h: 1 }, world: { w: 1, h: 1 } },
+      geom: { xs: [], nodes: {}, lanes: {}, loops: {}, bounds: { x: 0, y: 0, w: 1, h: 1 }, world: { w: 1, h: 1 } },
       view: { x: 0, y: 0, k: 1 },
       reduced: rm.matches,
-      mode: defaultView(model),
-      selected: null,
+      mode: opts.restore && (model.views?.some((v) => v.id === opts.restore.mode) || !model.views?.length && opts.restore.mode === "all") ? opts.restore.mode : defaultView(model),
+      collapsed: opts.restore ? new Set(model.nodes.filter((n) => n.kind === "group" && n.contains && (opts.restore.collapsed.has(n.id) || !opts.restore.knownGroups.has(n.id) && n.collapsed !== false)).map((n) => n.id)) : initialCollapsed(model),
+      selected: opts.restore?.selected && model.nodes.some((n) => n.id === opts.restore.selected) ? opts.restore.selected : null,
       hl: null,
-      query: "",
-      filter: null,
+      query: opts.restore?.query ?? "",
+      hops: opts.restore?.hops ?? 0,
+      filter: opts.restore?.filter ?? null,
       tool: "select",
       spaceDown: false,
       userMoved: false,
@@ -1686,12 +2541,38 @@
     install4(ctx);
     install5(ctx);
     install6(ctx);
-    document.body.classList.add("intro");
-    window.setTimeout(() => document.body.classList.remove("intro"), 2100);
+    els.q.value = ctx.query;
+    els.hops.value = String(ctx.hops);
     ctx.fn.buildWorld();
     ctx.fn.paint(false);
-    ctx.fn.fitWidth(false);
-    window.setTimeout(() => ctx.fn.fitWidth(false), 120);
+    const playback = install7(ctx);
+    if (opts.restore) {
+      ctx.userMoved = true;
+      ctx.fn.setView(opts.restore.view, false);
+      playback.restore(opts.restore.playback);
+      if (opts.restore.inspectorOpen) {
+        els.inspector.classList.add("open");
+        els.workspace.classList.add("inspopen");
+        els.inspector.setAttribute("aria-hidden", "false");
+        ctx.fn.renderInspector();
+      } else {
+        els.inspector.classList.remove("open");
+        els.workspace.classList.remove("inspopen");
+        els.inspector.setAttribute("aria-hidden", "true");
+      }
+    } else {
+      document.body.classList.add("intro");
+      const introTimer = window.setTimeout(() => document.body.classList.remove("intro"), 2100);
+      ctx.disposers.push(() => {
+        window.clearTimeout(introTimer);
+        document.body.classList.remove("intro");
+      });
+      ctx.fn.fitWidth(false);
+      const fitTimer = window.setTimeout(() => {
+        if (!ctx.userMoved) ctx.fn.fitWidth(false);
+      }, 120);
+      ctx.disposers.push(() => window.clearTimeout(fitTimer));
+    }
     const api = {
       model,
       geometry: () => ctx.geom,
@@ -1710,17 +2591,48 @@
         ctx.fn.clearSim();
         ctx.fn.renderInspector();
       },
+      play: (id) => playback.play(id),
+      pause: () => playback.pause(),
+      step: () => playback.step(),
+      seek: (t) => playback.seek(t),
+      playback: () => playback.playback(),
+      update: (nextModel, updateOpts) => {
+        const prepared = nextModel.layout === "auto" ? autoLayout(nextModel) : nextModel;
+        const nextIssues = validateModel(prepared);
+        const count = nextIssues.filter((i) => i.level === "error").length;
+        if (count) {
+          els.banner.textContent = `Update failed: ${count} errors. Showing the last good graph.`;
+          els.banner.hidden = false;
+          return { ok: false, issues: nextIssues };
+        }
+        const changes = diffModels(ctx.model, prepared);
+        const saved = { view: { ...ctx.view }, mode: ctx.mode, selected: ctx.selected, inspectorOpen: els.inspector.classList.contains("open"), query: ctx.query, hops: ctx.hops, filter: ctx.filter, collapsed: new Set(ctx.collapsed), knownGroups: new Set(ctx.model.nodes.filter((n) => n.kind === "group").map((n) => n.id)), playback: playback.playback() };
+        api.destroy();
+        const replacement = mount(root, prepared, { notes: opts.notes, onSelect: opts.onSelect, restore: saved });
+        notifySelection(saved.selected, replacement.selected(), opts.onSelect);
+        Object.assign(api, replacement);
+        window.FlowStudio = api;
+        els.banner.hidden = true;
+        els.banner.textContent = "";
+        if (updateOpts?.animate !== false && !ctx.reduced) {
+          for (const id of changes.changed) root.querySelector(`#n_${CSS.escape(id)}`)?.classList.add("updated");
+          for (const id of changes.added) root.querySelector(`#n_${CSS.escape(id)}`)?.classList.add("added");
+        }
+        return { ok: true, issues: nextIssues };
+      },
       destroy: () => {
         ctx.fn.clearSim();
         ctx.disposers.forEach((d) => d());
         ctx.disposers = [];
         style?.remove();
-        if (window.FlowStudio === api) delete window.FlowStudio;
+        if (window.FlowStudio === api || window.FlowStudio?.model === api.model) delete window.FlowStudio;
       }
     };
     window.FlowStudio = api;
     return api;
   }
+
+  // src/page.ts
   function auto() {
     const m = document.getElementById("flow-model");
     if (!m) return;