@caddis/cli 0.4.45 → 0.4.47

package/bundles/codex/.codex/skills/frontend/flow-studio/src/engine.ts

@@ -2,17 +2,22 @@
 // a small API (also placed on window.FlowStudio for the check harness). The generated demo page calls mount() itself.
 
 import { validateModel, type Model, type NoteDef } from "./model.ts";
+import { autoLayout } from "./autolayout.ts";
 import type { Ctx, Els } from "./ctx.ts";
 import type { View } from "./viewport.ts";
 import type { Geometry } from "./layout.ts";
 import { stateCss } from "./stateCss.ts";
-import { defaultView } from "./rules.ts";
+import { defaultView, initialCollapsed } from "./rules.ts";
 import { install as installInteract } from "./interact.ts";
 import { install as installRender } from "./render.ts";
 import { install as installControls } from "./controls.ts";
 import { install as installInspector } from "./inspector.ts";
 import { install as installChrome } from "./chrome.ts";
 import { install as installNotes } from "./notes.ts";
+import { install as installPlayback, type PlaybackController } from "./playbackui.ts";
+import { diffModels } from "./diff.ts";
+import { notifySelection } from "./selection.ts";
+import type { Issue } from "./model.ts";
 
 export interface FlowStudio {
   model: Model;
@@ -26,6 +31,12 @@ export interface FlowStudio {
   setMode(id: string): void;
   simulate(actionId: string): void;
   resetSimulation(): void;
+  play(scenarioId?: string): void;
+  pause(): void;
+  step(): void;
+  seek(tMs: number): void;
+  playback(): { scenario: string | null; step: number; playing: boolean; t: number };
+  update(model: Model, opts?: { animate?: boolean }): { ok: boolean; issues: Issue[] };
   destroy(): void;
 }
 
@@ -36,9 +47,11 @@ declare global {
 const IDS: Record<keyof Els, string> = {
   vp: "viewport", world: "world", svg: "edges", layer: "edgeLayer", cols: "cols", tools: "tools", zoom: "zoomLabel",
   inspector: "inspector", workspace: "workspace", live: "live", strip: "layerstrip", tiles: "kpis", legend: "legend",
-  ledger: "ledger", table: "tbl", q: "q", matchinfo: "matchinfo", modeSwitch: "modeSwitch", drawer: "drawer",
+  ledger: "ledger", table: "tbl", q: "q", hops: "hops", matchinfo: "matchinfo", modeSwitch: "modeSwitch", drawer: "drawer",
   notelist: "notelist", notesBtn: "notesBtn", theme: "theme", specbody: "specbody", spec: "spec", title: "title",
-  readat: "readat", help: "help", footer: "footer",
+  readat: "readat", help: "help", 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: ParentNode): Els {
@@ -51,10 +64,12 @@ function findEls(root: ParentNode): Els {
   return out as unknown as Els;
 }
 
-export function mount(root: ParentNode, model: Model, opts: { notes?: NoteDef[] } = {}): FlowStudio {
+interface SavedState { view: View; mode: string; selected: string | null; inspectorOpen: boolean; query: string; hops: number; filter: Ctx["filter"]; collapsed: Set<string>; knownGroups: Set<string>; playback: ReturnType<PlaybackController["playback"]> }
+export function mount(root: ParentNode, model: Model, opts: { notes?: NoteDef[]; onSelect?: (id: string | null) => void; restore?: SavedState } = {}): FlowStudio {
   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");
@@ -63,15 +78,17 @@ export function mount(root: ParentNode, model: Model, opts: { notes?: NoteDef[]
 
   const rm = matchMedia("(prefers-reduced-motion: reduce)");
   const ctx: Ctx = {
-    model, root, els,
+    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, hl: null, query: "", filter: null, tool: "select",
+    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: opts.restore?.query ?? "", hops: opts.restore?.hops ?? 0, filter: opts.restore?.filter ?? null, tool: "select",
     spaceDown: false, userMoved: false, dismissed: false, simActive: false, moved: 0,
     nodeEls: new Map(), laneEls: new Map(), edgeEls: [], labelEls: [], overlays: [], simTimers: [], disposers: [],
     fn: {} as Ctx["fn"],
@@ -90,13 +107,36 @@ export function mount(root: ParentNode, model: Model, opts: { notes?: NoteDef[]
   installInspector(ctx);
   installChrome(ctx);
   installNotes(ctx);
+  els.q.value = ctx.query;
+  els.hops.value = String(ctx.hops);
 
-  document.body.classList.add("intro");
-  window.setTimeout(() => document.body.classList.remove("intro"), 2100);
   ctx.fn.buildWorld();
   ctx.fn.paint(false);
-  ctx.fn.fitWidth(false);
-  window.setTimeout(() => ctx.fn.fitWidth(false), 120);
+  const playback = installPlayback(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 {
+    // The entrance animation is for the first mount only; a live update restores and must not replay it.
+    document.body.classList.add("intro");
+    const introTimer = window.setTimeout(() => document.body.classList.remove("intro"), 2100);
+    // destroy() clears these timers, so an update inside the window cannot fire the old instance's callbacks.
+    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: FlowStudio = {
     model,
@@ -110,33 +150,44 @@ export function mount(root: ParentNode, model: Model, opts: { notes?: NoteDef[]
     setMode: id => ctx.fn.setMode(id),
     simulate: id => ctx.fn.simulate(id),
     resetSimulation: () => { 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: SavedState = { 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);
+      // Refresh this api in place: callers keep their reference and window.FlowStudio stays this
+      // instance, so an update can never overwrite a different mounted engine.
+      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<HTMLElement>(`#n_${CSS.escape(id)}`)?.classList.add("updated");
+        for (const id of changes.added) root.querySelector<HTMLElement>(`#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;
 }
-
-function auto(): void {
-  const m = document.getElementById("flow-model");
-  if (!m) return;
-  try {
-    const model = JSON.parse(m.textContent ?? "{}") as Model;
-    const n = document.getElementById("flow-notes");
-    const notes = n ? (JSON.parse(n.textContent ?? "[]") as NoteDef[]) : undefined;
-    mount(document, model, { notes });
-  } catch (e) {
-    console.error(e);
-    const h = document.getElementById("help");
-    if (h) h.textContent = "This page could not be drawn: " + (e instanceof Error ? e.message : String(e));
-  }
-}
-
-window.flowStudioMount = mount;
-if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", auto);
-else auto();

package/bundles/codex/.codex/skills/frontend/flow-studio/src/inspector.ts

@@ -5,8 +5,9 @@
 import type { Ctx } from "./ctx.ts";
 import { esc } from "./model.ts";
 import type { NodeDef, RelationDef } from "./model.ts";
-import { bucketOf, isImproved, isNew, nodeStateId, nodeVisible } from "./rules.ts";
+import { bucketOf, effectiveLinks, groupFor, isImproved, isNew, nodeStateId, nodeVisible } from "./rules.ts";
 import { matches, relationSet, relationsOf } from "./interact.ts";
+import { sparklinePoints } from "./metrics.ts";
 
 const BUCKET_COLOR = { good: "ok", neutral: "muted", gap: "warn" } as const;
 const PILL = { ok: "ok", warn: "warn", crit: "warn", info: "info", accent: "info", muted: "muted" } as const;
@@ -29,9 +30,10 @@ export function install(ctx: Ctx): void {
     }));
     box.querySelectorAll<HTMLElement>("[data-g]").forEach(b => b.addEventListener("click", () => { ctx.fn.select(b.dataset.g ?? null); ctx.fn.zoomToPath(); }));
     box.querySelectorAll<HTMLElement>("[data-act]").forEach(b => b.addEventListener("click", () => ctx.fn.simulate(b.dataset.act ?? "")));
+    box.querySelectorAll<HTMLElement>("[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(); ctx.fn.announce("Simulation reset."); });
     box.querySelector("#zPath")?.addEventListener("click", () => ctx.fn.zoomToPath());
-    box.querySelector("#zBand")?.addEventListener("click", () => { const n = ctx.selected ? ctx.nodes.get(ctx.selected) : undefined; if (n) ctx.fn.zoomToBand(n.lane); });
+    box.querySelector("#zBand")?.addEventListener("click", () => { const n = ctx.selected ? ctx.nodes.get(ctx.selected) : undefined; if (n?.lane) ctx.fn.zoomToBand(n.lane); });
   }
 
   function renderInspector(): void {
@@ -40,7 +42,7 @@ export function install(ctx: Ctx): void {
     const head = `<div class="insp-h"><span>Inspector</span><button type="button" id="hideInsp" aria-label="Close the inspector">Close ✕</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);
@@ -49,7 +51,7 @@ export function install(ctx: Ctx): void {
       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 · ${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 · ${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 “${esc(ctx.query)}”</div><div class="drill">${rows}</div></div>`;
       wire(box);
@@ -82,11 +84,27 @@ export function install(ctx: Ctx): void {
       + (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)}">▶ ${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 ?? "")} · ${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 ?? "")} · ${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…" 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);

package/bundles/codex/.codex/skills/frontend/flow-studio/src/interact.ts

@@ -3,8 +3,9 @@
 import type { Ctx } from "./ctx.ts";
 import type { NodeDef, RelationDef } from "./model.ts";
 import type { Rect } from "./viewport.ts";
-import { connected, relatives, type Edge } from "./trace.ts";
-import { bucketOf, canonOf, linkVisible, nodeStateId, nodeVisible } from "./rules.ts";
+import { connected, relatives, withinHops, type Edge } from "./trace.ts";
+import { bucketOf, canonOf, effectiveLinks, nodeStateId, nodeVisible, toggleGroupState } from "./rules.ts";
+import { notifySelection } from "./selection.ts";
 
 export function relationsOf(ctx: Ctx): RelationDef[] {
   const given = ctx.model.inspector?.relations;
@@ -18,7 +19,7 @@ export function relationsOf(ctx: Ctx): RelationDef[] {
 }
 
 export function visibleEdges(ctx: Ctx): Edge[] {
-  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 }));
 }
 
 export function relationSet(ctx: Ctx, rel: RelationDef, start: string): Set<string> {
@@ -42,7 +43,7 @@ export function matches(ctx: Ctx, n: NodeDef): boolean {
 export function install(ctx: Ctx): void {
   const { els, model } = ctx;
   const canon = (id: string) => 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: string | null): Set<string> | null {
@@ -60,7 +61,7 @@ export function install(ctx: Ctx): void {
         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;
   }
 
@@ -84,6 +85,7 @@ export function install(ctx: Ctx): void {
 
   function select(id: string | null): void {
     clearSim();
+    const previous = ctx.selected;
     ctx.selected = id ? canon(id) : null;
     ctx.hl = null;
     ctx.dismissed = false;
@@ -92,6 +94,7 @@ export function install(ctx: Ctx): void {
     ctx.fn.renderInspector();
     drawTrail();
     if (ctx.selected) revealNode(ctx.selected);
+    notifySelection(previous, ctx.selected, ctx.onSelect);
   }
 
   /** An overlay is a copy of one link drawn on top. pathLength=1 makes the draw-in independent of zoom. */
@@ -180,7 +183,7 @@ export function install(ctx: Ctx): void {
   }
 
   function rectOf(ids: string[]): Rect | null {
-    const ps = ids.map(i => ctx.geom.nodes[i]).filter((p): p is NonNullable<typeof p> => !!p && !!ctx.nodes.get(p.id) && nodeVisible(model, ctx.mode, ctx.nodes.get(p.id) as NodeDef));
+    const ps = ids.map(i => ctx.geom.nodes[i]).filter((p): p is NonNullable<typeof p> => !!p && !!ctx.nodes.get(p.id) && nodeVisible(model, ctx.mode, ctx.nodes.get(p.id) as NodeDef, 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));
@@ -218,11 +221,11 @@ export function install(ctx: Ctx): void {
     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.`);
   }
 
@@ -236,5 +239,15 @@ export function install(ctx: Ctx): void {
   ctx.fn.zoomToBand = zoomToBand;
   ctx.fn.escape = escape;
   ctx.fn.setMode = setMode;
+  ctx.fn.toggleGroup = (id: string) => {
+    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: string) => { els.live.textContent = t; };
 }

package/bundles/codex/.codex/skills/frontend/flow-studio/src/layout.test.ts

@@ -67,3 +67,78 @@ test("a node whose column is out of range does not produce NaN", () => {
   const g = computeGeometry(mm);
   assert.ok(Object.values(g.nodes).every(n => [n.x, n.y, n.w, n.h].every(Number.isFinite)));
 });
+test("a gateway has a 64 px diamond box", () => {
+  const mm = m(); mm.nodes[0]!.kind = "gateway";
+  assert.equal(computeGeometry(mm).nodes.a!.h, 64);
+});
+test("loop-back channels stay below nodes, inside their lane, and separate from the next lane", () => {
+  const mm = m();
+  mm.links.push({ id: "return", from: "b", to: "a", state: "ok", kind: "loop-back" });
+  mm.links.push({ id: "again", from: "b", to: "a", state: "ok", kind: "loop-back" });
+  const g = computeGeometry(mm);
+  const y = g.loops.return!.channelY;
+  assert.ok(y >= g.nodes.a!.y + g.nodes.a!.h + 10);
+  assert.ok(y >= g.nodes.b!.y + g.nodes.b!.h + 10);
+  assert.equal(g.loops.again!.channelY, y + 8);
+  assert.ok(g.lanes.l1!.y + g.lanes.l1!.h > g.loops.again!.channelY);
+  assert.ok(g.lanes.l1!.y + g.lanes.l1!.h <= g.lanes.l2!.y);
+});
+
+test("a loop clears a lower node within its horizontal span", () => {
+  const mm = m();
+  mm.columns.push({ id: "c2", title: "C", width: 150 });
+  mm.nodes.find(n => n.id === "b")!.col = 2;
+  mm.nodes.push({ id: "middle", kind: "card", lane: "l1", col: 1, row: 1, state: "ok", title: "Middle" });
+  mm.links.push({ id: "return", from: "b", to: "a", state: "ok", kind: "loop-back" });
+  const g = computeGeometry(mm);
+  assert.equal(g.loops.return!.channelY, g.nodes.middle!.y + g.nodes.middle!.h + 10);
+  assert.ok(g.lanes.l1!.y + g.lanes.l1!.h <= g.lanes.l2!.y);
+});
+
+test("a lower node outside the loop span does not lower its channel", () => {
+  const mm = m();
+  mm.columns.push({ id: "c2", title: "C", width: 150 });
+  mm.nodes.push({ id: "outside", kind: "card", lane: "l1", col: 2, row: 1, state: "ok", title: "Outside" });
+  mm.links.push({ id: "return", from: "b", to: "a", state: "ok", kind: "loop-back" });
+  const g = computeGeometry(mm);
+  assert.equal(g.loops.return!.channelY, g.nodes.a!.y + g.nodes.a!.h + 10);
+});
+
+test("interleaved lanes calculate channels after all endpoint shifts", () => {
+  const mm = m();
+  mm.nodes = [
+    { id: "a", kind: "card", lane: "l1", col: 0, row: 0, state: "ok", title: "A" },
+    { id: "deep", kind: "card", lane: "l1", col: 1, row: 5, state: "ok", title: "Deep" },
+    { id: "b", kind: "card", lane: "l2", col: 0, row: 1, state: "ok", title: "B" },
+  ];
+  mm.links = [{ id: "return", from: "deep", to: "b", state: "ok", kind: "loop-back" }];
+  const g = computeGeometry(mm);
+  assert.ok(g.loops.return!.channelY >= g.nodes.b!.y + g.nodes.b!.h + 10);
+  assert.ok(g.lanes.l1!.y + g.lanes.l1!.h <= g.lanes.l2!.y);
+  assert.ok(Object.values(g.nodes).every(n => [n.x, n.y, n.w, n.h].every(Number.isFinite)));
+  assert.ok(Object.values(g.loops).every(l => Number.isFinite(l.channelY)));
+});
+
+test("free layout uses explicit world rectangles and works without columns", () => {
+  const mm = m();
+  mm.layout = "free"; mm.columns = [];
+  mm.nodes = [
+    { id: "a", kind: "card", lane: "l1", x: 18, y: 70, w: 121, h: 47, state: "ok", title: "A" },
+    { id: "b", kind: "card", lane: "l2", x: 250, y: 300, state: "ok", title: "B" },
+  ];
+  const g = computeGeometry(mm);
+  assert.deepEqual(g.xs, []);
+  assert.deepEqual(g.nodes.a, { id: "a", x: 18, y: 70, w: 121, h: 47 });
+  assert.equal(g.nodes.b?.w, 190);
+  assert.ok(g.world.w >= 440);
+  assert.ok(g.lanes.l1 && g.lanes.l2);
+});
+
+test("free layout preserves finite negative node coordinates", () => {
+  const mm = m(); mm.layout = "free"; mm.columns = [];
+  mm.nodes = [{ id: "a", kind: "card", lane: "l1", x: -80, y: -40, w: 60, h: 30, state: "ok", title: "A" }];
+  const g = computeGeometry(mm);
+  assert.equal(g.nodes.a!.x, -80);
+  assert.equal(g.nodes.a!.y, -40);
+  assert.ok([g.bounds.x, g.bounds.y, g.bounds.w, g.bounds.h, g.world.w, g.world.h].every(Number.isFinite));
+});

package/bundles/codex/.codex/skills/frontend/flow-studio/src/layout.ts

@@ -1,7 +1,7 @@
 // Geometry from a model: where every node, lane and column sits in world units. Pure, no DOM.
 // Node sizes are fixed per kind, so layout never depends on fonts or text measurement.
 
-import type { Model, Kind } from "./model.ts";
+import { NODE_HEIGHT, type Model } from "./model.ts";
 import type { Rect, Size } from "./viewport.ts";
 
 export interface Placed extends Rect { id: string }
@@ -9,6 +9,7 @@ export interface Geometry {
   xs: number[];
   nodes: Record<string, Placed>;
   lanes: Record<string, Rect>;
+  loops: Record<string, { channelY: number }>;
   bounds: Rect;
   world: Size;
 }
@@ -16,7 +17,6 @@ export interface LayoutOptions { pitch: number; top: number; gap: number; padX:
 
 export const DEFAULTS: LayoutOptions = { pitch: 62, top: 64, gap: 34, padX: 24, visible: () => true };
 
-const HEIGHT: Record<Kind, number> = { card: 54, group: 54, gateway: 54, placeholder: 54, chip: 34, start: 40, end: 40, event: 40, note: 40 };
 const LANE_PAD_TOP = 38; // room for the lane title
 const LANE_PAD_BOTTOM = 14;
 
@@ -29,21 +29,59 @@ export function computeGeometry(m: Model, opt: Partial<LayoutOptions> = {}): Geo
 
   const nodes: Record<string, Placed> = {};
   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: Geometry["loops"] = {};
   const lanes: Record<string, Rect> = {};
-  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: string) => 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(x => x.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));
+    // Reserve channel space before shifting the following lane. The exact channel
+    // positions are calculated only after every lane has reached its final y.
+    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 = new Map<string, number>();
+  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);
@@ -53,5 +91,5 @@ export function computeGeometry(m: Model, opt: Partial<LayoutOptions> = {}): Geo
     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 };
 }

package/bundles/codex/.codex/skills/frontend/flow-studio/src/lib.ts

@@ -0,0 +1,20 @@
+/** Replaced with the shared template at library build time. */
+export const SHELL_BODY_HTML = "/*__SHELL_BODY__*/";
+export { mount, type FlowStudio } from "./engine.ts";
+export * from "./model.ts";
+export { autoLayout } from "./autolayout.ts";
+export { computeGeometry } from "./layout.ts";
+export type { Geometry, LayoutOptions, Placed } from "./layout.ts";
+export * from "./viewport.ts";
+export * from "./routing.ts";
+export * from "./trace.ts";
+export * from "./rules.ts";
+export * from "./playback.ts";
+export * from "./diff.ts";
+export * as viewport from "./viewport.ts";
+export * as routing from "./routing.ts";
+export * as trace from "./trace.ts";
+export * as rules from "./rules.ts";
+export * as playback from "./playback.ts";
+export * as diff from "./diff.ts";
+export { stateCss } from "./stateCss.ts";

package/bundles/codex/.codex/skills/frontend/flow-studio/src/metrics.test.ts

@@ -0,0 +1,57 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { sparklinePoints, metricBadge, sparkline } from "./metrics.ts";
+
+test("sparkline handles flat, missing and varied series", () => {
+  assert.equal(sparklinePoints([], 56, 12), "");
+  assert.equal(sparklinePoints([4, 4], 56, 12), "0,6 56,6");
+  assert.equal(sparklinePoints([0, 10], 56, 12), "0,12 56,0");
+});
+
+test("metricBadge renders value, unit, and consistent title", () => {
+  assert.equal(metricBadge(undefined), "");
+  const badge1 = metricBadge({ value: 92, unit: "ms", label: "Hit rate" });
+  assert.ok(badge1.includes('title="Hit rate: 92 ms"'), "Title includes label, value and unit");
+  assert.ok(badge1.includes(">92 ms"), "Badge body includes value and unit");
+  assert.ok(!badge1.includes("<i"), "No fill bar when max is omitted");
+});
+
+test("metricBadge renders clamped fill bar when max is valid, ignores invalid max", () => {
+  const withMax = metricBadge({ value: 50, max: 100, label: "CPU" });
+  assert.ok(withMax.includes('<i style="width:50%"></i>'));
+
+  const clamped = metricBadge({ value: 150, max: 100 });
+  assert.ok(clamped.includes('<i style="width:100%"></i>'));
+
+  const negativeVal = metricBadge({ value: -10, max: 100 });
+  assert.ok(negativeVal.includes('<i style="width:0%"></i>'));
+
+  const nullMax = metricBadge({ value: 50, max: null as any });
+  assert.ok(!nullMax.includes("<i"), "null max produces no bar");
+
+  const zeroMax = metricBadge({ value: 50, max: 0 });
+  assert.ok(!zeroMax.includes("<i"), "zero max produces no bar");
+});
+
+test("metricBadge escapes special HTML characters", () => {
+  const hostile = metricBadge({ value: 1, unit: '<script>"&', label: '<tag>&"' });
+  assert.ok(!hostile.includes("<script>"));
+  assert.ok(!hostile.includes("<tag>"));
+  assert.ok(hostile.includes("&lt;script&gt;"));
+  assert.ok(hostile.includes("&lt;tag&gt;"));
+});
+test("metricBadge escapes quotes so nothing can break out of the title attribute", () => {
+  // label and unit land inside title="…": a raw quote there would open attacker-controlled attributes.
+  const hostile = metricBadge({ value: 1, unit: '">&x', label: 'y" onmouseover="z' });
+  assert.ok(hostile.includes('title="y&quot; onmouseover=&quot;z: 1 &quot;&gt;&amp;x"'));
+});
+
+test("sparkline renders accessible SVG with aria-hidden", () => {
+  assert.equal(sparkline(undefined), "");
+  assert.equal(sparkline({ value: 10 }), "");
+  assert.equal(sparkline({ value: 10, series: [1] }), "");
+
+  const svg = sparkline({ value: 10, series: [2, 8] }, 56, 12);
+  assert.ok(svg.startsWith('<svg class="spark" width="56" height="12" viewBox="0 0 56 12" aria-hidden="true">'));
+  assert.ok(svg.includes('<polyline points="0,12 56,0"/>'));
+});