@caddis/cli 0.4.45 → 0.4.47

package/bundles/antigravity-plugin/skills/flow-studio/scripts/react-proof.mjs

@@ -0,0 +1,92 @@
+// Build and test both React routes in a disposable application.
+// Run from the skill folder: node scripts/react-proof.mjs
+import { spawn, spawnSync } from 'node:child_process';
+import { cpSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createServer } from 'node:net';
+import { stopPreview } from './lib/react-proof-cleanup.mjs';
+import { proofIndexHtml } from './lib/react-proof-page.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const tmp = mkdtempSync(join(tmpdir(), 'flow-studio-react-proof-'));
+let preview;
+let previewClosed;
+
+function run(command, args, cwd = tmp) {
+  const result = spawnSync(command, args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' && command.toLowerCase().endsWith('npm.cmd'), env: process.env, timeout: 600_000 });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${command} ${args.join(' ')} exited ${result.status ?? result.signal}`);
+}
+
+async function freePort() {
+  return new Promise((resolvePort, reject) => {
+    const server = createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      server.close(() => resolvePort(address.port));
+    });
+  });
+}
+
+async function waitFor(url) {
+  for (let i = 0; i < 100; i++) {
+    if (preview.exitCode !== null) throw new Error(`vite preview exited ${preview.exitCode}`);
+    try { if ((await fetch(url)).ok) return; } catch { /* server still starting */ }
+    await new Promise(r => setTimeout(r, 100));
+  }
+  throw new Error(`vite preview did not start at ${url}`);
+}
+
+try {
+  mkdirSync(join(tmp, 'src'));
+  cpSync(join(root, 'react'), join(tmp, 'react'), { recursive: true });
+  // The React files use ../src imports. Keep the real source path in the throwaway app.
+  cpSync(join(root, 'src'), join(tmp, 'src'), { recursive: true });
+  mkdirSync(join(tmp, 'templates'));
+  for (const name of ['flow-studio.lib.mjs', 'flow-studio.lib.d.mts', 'flow-studio.css'])
+    cpSync(join(root, 'templates', name), join(tmp, 'templates', name));
+  mkdirSync(join(tmp, 'examples'));
+  cpSync(join(root, 'examples', 'order-desk.json'), join(tmp, 'examples', 'order-desk.json'));
+  writeFileSync(join(tmp, 'package.json'), JSON.stringify({
+    private: true, type: 'module', scripts: { test: 'vitest run', build: 'tsc --noEmit && vite build' },
+    dependencies: { react: '^18.3.1', 'react-dom': '^18.3.1' },
+    devDependencies: { '@testing-library/react': '^16.0.0', '@types/react': '^18.3.0', '@types/react-dom': '^18.3.0', jsdom: '^26.0.0', playwright: '^1.51.0', typescript: '^5.0.0', vite: '^6.0.0', vitest: '^3.0.0' },
+  }, null, 2));
+  writeFileSync(join(tmp, 'index.html'), proofIndexHtml());
+  writeFileSync(join(tmp, 'tsconfig.json'), JSON.stringify({ compilerOptions: {
+    target: 'ES2022', useDefineForClassFields: true, lib: ['ES2022', 'DOM', 'DOM.Iterable'], module: 'ESNext', skipLibCheck: true,
+    moduleResolution: 'Bundler', allowImportingTsExtensions: true, resolveJsonModule: true, isolatedModules: true,
+    noEmit: true, jsx: 'react-jsx', strict: true, types: ['vitest/globals'],
+  }, include: ['src', 'react', 'templates'], exclude: ['src/**/*.test.ts'] }, null, 2));
+  writeFileSync(join(tmp, 'src', 'App.tsx'), "import { FlowStudioView } from '../react/index.ts';\nimport model from '../examples/order-desk.json';\nimport '../templates/flow-studio.css';\nimport type { Model } from './model.ts';\nexport default function App() { return <FlowStudioView model={model as Model} />; }\n");
+  writeFileSync(join(tmp, 'src', 'main.tsx'), "import { StrictMode } from 'react';\nimport { createRoot } from 'react-dom/client';\nimport App from './App.tsx';\ncreateRoot(document.getElementById('root')!).render(<StrictMode><App /></StrictMode>);\n");
+  console.log(`Proof app: ${tmp}`);
+  // The browser checks launch a real browser. On Windows and when FLOW_STUDIO_CHANNEL is set,
+  // check.mjs uses a system browser (Edge or the named channel), so the Playwright browser
+  // download is skipped there. Everywhere else, let npm fetch Playwright's own browser, or the
+  // checks would fail on a clean machine that never downloaded one.
+  if (process.env.FLOW_STUDIO_CHANNEL || process.platform === 'win32') process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD ??= '1';
+  process.env.npm_config_cache = join(tmp, '.npm-cache');
+  run(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['install', '--no-audit', '--no-fund']);
+  run(process.execPath, [join(tmp, 'node_modules', 'vitest', 'vitest.mjs'), 'run', 'react/FlowStudioView.test.tsx', 'react/native/native.test.tsx', '--environment', 'jsdom']);
+  run(process.execPath, [join(tmp, 'node_modules', 'typescript', 'bin', 'tsc'), '--noEmit']);
+  run(process.execPath, [join(tmp, 'node_modules', 'vite', 'bin', 'vite.js'), 'build']);
+  const port = await freePort();
+  const address = `http://127.0.0.1:${port}/`;
+  preview = spawn(process.execPath, [join(tmp, 'node_modules', 'vite', 'bin', 'vite.js'), 'preview', '--host', '127.0.0.1', '--port', String(port), '--strictPort'], { cwd: tmp, stdio: 'inherit' });
+  previewClosed = new Promise(resolve => preview.once('close', resolve));
+  await waitFor(address);
+  const checkArgs = [join(root, 'scripts', 'check.mjs'), address, '--out', join(tmp, 'check-out'), '--skip', 'hostile'];
+  if (process.env.FLOW_STUDIO_CHANNEL || process.platform === 'win32') checkArgs.push('--channel', process.env.FLOW_STUDIO_CHANNEL ?? 'msedge');
+  run(process.execPath, checkArgs, tmp);
+  console.log('React proof passed.');
+} catch (error) {
+  console.error(`React proof failed: ${error.message}`);
+  process.exitCode = 1;
+} finally {
+  await stopPreview(preview, previewClosed);
+  rmSync(tmp, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+}

package/bundles/antigravity-plugin/skills/flow-studio/scripts/validate.mjs

@@ -4,6 +4,8 @@
 
 import { readFileSync } from "node:fs";
 import { validateModel } from "../src/model.ts";
+import { autoLayout } from "../src/autolayout.ts";
+import { prepareModel } from "./lib/auto-entry-guard.mjs";
 
 export function loadModel(path) {
   let text;
@@ -32,7 +34,9 @@ if (process.argv[1]?.endsWith("validate.mjs")) {
     console.error("usage: node --experimental-strip-types scripts/validate.mjs <model.json>");
     process.exit(2);
   }
-  const errors = report(validateModel(loadModel(path)));
+  const model = loadModel(path);
+  const ready = prepareModel(model, autoLayout);
+  const errors = report(validateModel(ready));
   console.log(errors ? `${errors} error(s)` : "OK");
   process.exit(errors ? 1 : 0);
 }

package/bundles/antigravity-plugin/skills/flow-studio/src/autolayout.test.ts

@@ -0,0 +1,78 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { autoLayout } from "./autolayout.ts";
+import { validateModel, type Model, type NodeDef } from "./model.ts";
+import { computeGeometry } from "./layout.ts";
+
+const node = (id: string, extra: Partial<NodeDef> = {}): NodeDef => ({ id, kind: "card", state: "ok", title: id, ...extra } as NodeDef);
+const model = (ids: string[], pairs: [string, string][]): Model => ({
+  version: 1, meta: { title: "t", help: "", asOf: "", source: "" }, layout: "auto", columns: [], lanes: [],
+  states: { ok: { word: "OK", tone: "ok", border: "solid", edge: "flow", motion: "flow", bucket: "good" } },
+  nodes: ids.map(id => node(id)), links: pairs.map(([from, to], i) => ({ id: `e${i}`, from, to, state: "ok" })),
+});
+const errors = (m: Model) => validateModel(m).filter(i => i.level === "error");
+
+test("chain gets longest path columns and generated stages", () => {
+  const out = autoLayout(model(["a", "b", "c"], [["a", "b"], ["b", "c"]]));
+  assert.deepEqual(out.nodes.map(n => n.col), [0, 1, 2]);
+  assert.deepEqual(out.columns.map(c => c.title), ["Stage 1", "Stage 2", "Stage 3"]);
+  assert.deepEqual(errors(out), []);
+});
+test("fork and join ranks the join after both branches", () => {
+  const out = autoLayout(model(["a", "b", "c", "d"], [["a", "b"], ["a", "c"], ["b", "d"], ["c", "d"]]));
+  assert.equal(out.nodes.find(n => n.id === "d")?.col, 2);
+  assert.equal(out.nodes.find(n => n.id === "b")?.col, 1);
+  assert.equal(out.nodes.find(n => n.id === "c")?.col, 1);
+  assert.deepEqual(errors(out), []);
+});
+test("a three cycle yields exactly one feedback edge and consistent ranks", () => {
+  const out = autoLayout(model(["a", "b", "c"], [["a", "b"], ["b", "c"], ["c", "a"]]));
+  assert.deepEqual(out.links.filter(l => l.kind === "loop-back").map(l => l.id), ["e2"]);
+  assert.deepEqual(out.nodes.map(n => n.col), [0, 1, 2]);
+  assert.deepEqual(errors(out), []);
+});
+test("disconnected parts get synthetic lanes in first appearance order", () => {
+  const out = autoLayout(model(["a", "b", "c", "d"], [["a", "b"], ["c", "d"]]));
+  assert.deepEqual(out.lanes.map(l => l.title), ["Group 1", "Group 2"]);
+  assert.equal(out.nodes[0]?.lane, out.nodes[1]?.lane);
+  assert.equal(out.nodes[2]?.lane, out.nodes[3]?.lane);
+  assert.notEqual(out.nodes[0]?.lane, out.nodes[2]?.lane);
+  const lanes = Object.values(computeGeometry(out).lanes).sort((a, b) => a.y - b.y);
+  assert.ok(lanes[0]!.y + lanes[0]!.h <= lanes[1]!.y);
+});
+test("author fixed column and row stay fixed and successors rank from them", () => {
+  const m = model(["a", "b", "c"], [["a", "b"], ["b", "c"]]);
+  m.nodes[1]!.col = 4; m.nodes[1]!.row = 7;
+  const out = autoLayout(m);
+  assert.equal(out.nodes[1]?.col, 4);
+  assert.equal(out.nodes[1]?.row, 7);
+  assert.equal(out.nodes[2]?.col, 5);
+  assert.equal(out.columns.length, 6);
+  assert.deepEqual(errors(out), []);
+});
+test("ordering lowers crossings on a reversed two-edge example", () => {
+  const m = model(["a", "b", "d", "c"], [["a", "c"], ["b", "d"]]);
+  m.nodes[0]!.col = 0; m.nodes[1]!.col = 0; m.nodes[2]!.col = 1; m.nodes[3]!.col = 1;
+  m.nodes.forEach(n => n.lane = "one"); m.lanes = [{ id: "one", title: "One" }];
+  const out = autoLayout(m), byId = new Map(out.nodes.map(n => [n.id, n]));
+  const crossing = (a: string, b: string, c: string, d: string): boolean =>
+    ((byId.get(a)!.row! - byId.get(c)!.row!) * (byId.get(b)!.row! - byId.get(d)!.row!)) < 0;
+  assert.equal(crossing("a", "c", "b", "d"), false);
+  assert.deepEqual(errors(out), []);
+});
+test("same input gives equal output without changing input", () => {
+  const m = model(["a", "b", "c"], [["a", "b"], ["b", "c"]]);
+  const before = JSON.stringify(m);
+  assert.deepEqual(autoLayout(m), autoLayout(m));
+  assert.equal(JSON.stringify(m), before);
+});
+test("seeded 200 node graph finishes under 300ms and validates", () => {
+  const ids = Array.from({ length: 200 }, (_, i) => `n${i}`);
+  let seed = 39;
+  const rnd = () => { seed = (1664525 * seed + 1013904223) >>> 0; return seed / 0x100000000; };
+  const pairs: [string, string][] = ids.slice(1).map((id, i) => [ids[i]!, id]);
+  for (let i = 0; i < 200; i++) pairs.push([ids[Math.floor(rnd() * ids.length)]!, ids[Math.floor(rnd() * ids.length)]!]);
+  const m = model(ids, pairs), start = performance.now(), out = autoLayout(m);
+  assert.ok(performance.now() - start < 300);
+  assert.deepEqual(errors(out), []);
+});

package/bundles/antigravity-plugin/skills/flow-studio/src/autolayout.ts

@@ -0,0 +1,132 @@
+// Deterministic placement for models without authored grid positions. No DOM and no input mutation.
+import type { Model, NodeDef, LinkDef } from "./model.ts";
+
+export function autoLayout(input: Model): Model {
+  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, [] as LinkDef[]]));
+  const incoming = new Map(nodes.map(n => [n.id, [] as LinkDef[]]));
+  const neighbours = new Map(nodes.map(n => [n.id, [] as string[]]));
+  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);
+  }
+
+  // A gray target is on the active DFS stack. Mark that edge as feedback.
+  const color = new Map<string, number>();
+  const post: string[] = [];
+  for (const root of nodes) {
+    if (color.has(root.id)) continue;
+    color.set(root.id, 1);
+    const stack: { id: string; next: number }[] = [{ 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 }); }
+    }
+  }
+
+  // Reverse finishing order is topological after feedback edges are removed.
+  for (const id of post.reverse()) {
+    const n = byId.get(id)!;
+    if (n.col !== undefined) 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;
+  }
+
+  // Missing lane membership is grouped by weak connection, including feedback edges.
+  const seen = new Set<string>();
+  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;
+  }
+
+  // Start in input order. Four alternating sweeps sort each lane and layer by
+  // neighbour barycentre. Stable input order resolves every tie.
+  const rank = new Map(nodes.map((n, i) => [n.id, i]));
+  const laneOrder = lanes.map(l => l.id);
+  const cells = new Map<string, NodeDef[]>();
+  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: NodeDef): number => {
+        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));
+    }
+  }
+
+  // Place lanes in separate row ranges. A cell can share a row with another
+  // column, but nodes whose column spans intersect need a full row of space.
+  let nextBase = 0;
+  const placed: NodeDef[] = nodes.filter(n => n.row !== undefined);
+  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 = new Map<number, number>();
+    for (const n of ordered) {
+      if (n.row !== undefined) 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 };
+}

package/bundles/antigravity-plugin/skills/flow-studio/src/chrome.ts

@@ -4,7 +4,7 @@
 import { el, on, type Ctx } from "./ctx.ts";
 import { esc } from "./model.ts";
 import { DASH, toneVar, cssId } from "./stateCss.ts";
-import { bucketOf, linkStateId, linkVisible, nodeStateId, nodeVisible } from "./rules.ts";
+import { bucketOf, columnTitle, effectiveLinks, nodeStateId, nodeVisible } from "./rules.ts";
 import { matches } from "./interact.ts";
 
 const DEFAULT_LABELS: Record<string, string> = {
@@ -19,7 +19,7 @@ const DEFAULT_LABELS: Record<string, string> = {
 export function install(ctx: Ctx): void {
   const { els, model } = ctx;
   const label = (k: string): string => model.meta.labels?.[k] ?? DEFAULT_LABELS[k] ?? k;
-  const visible = (id: string): boolean => { const n = ctx.nodes.get(id); return !!n && nodeVisible(model, ctx.mode, n); };
+  const visible = (id: string): boolean => { const n = ctx.nodes.get(id); return !!n && nodeVisible(model, ctx.mode, n, ctx.collapsed); };
 
   function countUp(node: HTMLElement, to: number, ms = 700): void {
     if (ctx.reduced) { node.textContent = String(to); return; }
@@ -34,6 +34,7 @@ export function install(ctx: Ctx): void {
 
   function buildStrip(): void {
     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("");
@@ -43,9 +44,9 @@ export function install(ctx: Ctx): void {
       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; else gap += w;
       }
@@ -64,9 +65,8 @@ export function install(ctx: Ctx): void {
   function buildTiles(): void {
     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++;
     }
     let gaps = 0, upgrades = 0;
@@ -120,7 +120,7 @@ export function install(ctx: Ctx): void {
     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>`;
   }
@@ -157,6 +157,10 @@ export function install(ctx: Ctx): void {
     els.matchinfo.textContent = ctx.query ? `${n} group${n === 1 ? "" : "s"} match` : "";
     if (!ctx.selected) { ctx.fn.trace(null); 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: KeyboardEvent) => {
     if (e.key !== "Enter" || !ctx.query) return;
     const ids = model.nodes.filter(x => visible(x.id) && matches(ctx, x)).map(x => x.id);

package/bundles/antigravity-plugin/skills/flow-studio/src/controls.ts

@@ -69,6 +69,7 @@ export function install(ctx: Ctx): void {
 
   function placeHeaders(): void {
     const cols = els.cols;
+    cols.style.display = model.columns.length ? "" : "none";
     if (!cols.firstChild) {
       model.columns.forEach((c, i) => { const h = el("div", "hd"); h.textContent = (c.short ?? c.title).toUpperCase(); h.title = c.title; h.dataset.i = String(i); cols.appendChild(h); });
       let i = 0;
@@ -209,6 +210,13 @@ export function install(ctx: Ctx): void {
     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 === "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; fit(true); }

package/bundles/antigravity-plugin/skills/flow-studio/src/ctx.ts

@@ -22,6 +22,7 @@ export interface Els {
   ledger: HTMLElement;
   table: HTMLElement;
   q: HTMLInputElement;
+  hops: HTMLSelectElement;
   matchinfo: HTMLElement;
   modeSwitch: HTMLElement;
   drawer: HTMLElement;
@@ -34,6 +35,17 @@ export interface Els {
   readat: HTMLElement;
   help: HTMLElement;
   footer: HTMLElement;
+  playbar: HTMLElement;
+  pbScenario: HTMLSelectElement;
+  pbPlay: HTMLButtonElement;
+  pbStep: HTMLButtonElement;
+  pbReset: HTMLButtonElement;
+  pbSpeed: HTMLSelectElement;
+  pbScrub: HTMLInputElement;
+  pbCaption: HTMLElement;
+  pbCounter: HTMLElement;
+  pbChoices: HTMLElement;
+  banner: HTMLElement;
 }
 
 export type Filter = "gap" | "upgrade" | null;
@@ -62,12 +74,14 @@ export interface Fns {
   placeMarkers(): void;
   escape(): void;
   setMode(id: string): void;
+  toggleGroup(id: string): void;
 }
 
 export interface Ctx {
   model: Model;
   root: ParentNode;
   els: Els;
+  onSelect?: (id: string | null) => void;
   notes: NoteDef[];
   nodes: Map<string, NodeDef>;
   links: LinkDef[];
@@ -75,9 +89,11 @@ export interface Ctx {
   view: View;
   reduced: boolean;
   mode: string;
+  collapsed: Set<string>;
   selected: string | null;
   hl: string | null;
   query: string;
+  hops: number;
   filter: Filter;
   tool: "select" | "hand";
   spaceDown: boolean;

package/bundles/antigravity-plugin/skills/flow-studio/src/diff.test.ts

@@ -0,0 +1,31 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { diffModels } from "./diff.ts";
+import type { Model } from "./model.ts";
+
+const base = { nodes: [{ id: "a", state: "ok", title: "A", kind: "card", sla: 30 }, { id: "b", state: "ok", title: "B", kind: "card" }] } as Model;
+test("diff reports added, removed, and specified field changes", () => {
+  const next = { nodes: [{ ...base.nodes[0], metrics: { value: 2 } }, { id: "c", state: "ok", title: "C", kind: "card" }] } as Model;
+  assert.deepEqual(diffModels(base, next), { added: ["c"], removed: ["b"], changed: ["a"] });
+  assert.deepEqual(diffModels(base, structuredClone(base)), { added: [], removed: [], changed: [] });
+});
+test("diff detects change in sla", () => {
+  const next = { nodes: [{ ...base.nodes[0], sla: 60 }, base.nodes[1]] } as Model;
+  assert.deepEqual(diffModels(base, next), { added: [], removed: [], changed: ["a"] });
+});
+test("diff is invariant to key order in objects", () => {
+  const m1 = { nodes: [{ id: "a", state: "ok", title: "A", kind: "card", metrics: { value: 10, unit: "ms", label: "latency" } }] } as Model;
+  const m2 = { nodes: [{ id: "a", state: "ok", title: "A", kind: "card", metrics: { label: "latency", unit: "ms", value: 10 } }] } as Model;
+  assert.deepEqual(diffModels(m1, m2), { added: [], removed: [], changed: [] });
+});
+test("an undefined-valued property counts as absent (a model comes from JSON, which cannot hold one)", () => {
+  const m1 = { nodes: [{ id: "a", state: "ok", title: "A", kind: "card", metrics: { value: 1, unit: undefined } }] } as unknown as Model;
+  const m2 = { nodes: [{ id: "a", state: "ok", title: "A", kind: "card", metrics: { value: 1 } }] } as Model;
+  assert.deepEqual(diffModels(m1, m2), { added: [], removed: [], changed: [] });
+});
+test("null, undefined and NaN stay distinct values in a diff", () => {
+  const mk = (metrics: unknown) => ({ nodes: [{ id: "a", state: "ok", title: "A", kind: "card", metrics }] }) as unknown as Model;
+  assert.deepEqual(diffModels(mk({ value: 1, series: [null] }), mk({ value: 1, series: [undefined] })).changed, ["a"]);
+  assert.deepEqual(diffModels(mk({ value: NaN }), mk({ value: null })).changed, ["a"]);
+  assert.deepEqual(diffModels(mk({ value: NaN }), mk({ value: NaN })).changed, []);
+});

package/bundles/antigravity-plugin/skills/flow-studio/src/diff.ts

@@ -0,0 +1,34 @@
+import type { Model, NodeDef } from "./model.ts";
+
+const fields: Array<keyof NodeDef> = ["state", "stateIn", "title", "subtitle", "weight", "metrics", "visibleIn", "lane", "sla"];
+
+// A stable serializer for the diff. Unlike JSON.stringify it never returns undefined, and values
+// JSON cannot hold stay distinct: undefined, NaN and Infinity each get their own text, so a real
+// change between them cannot be hidden by "null" conflation.
+function stableStringify(val: unknown): string {
+  if (val === undefined) 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(",")}]`;
+    // A model comes from JSON, which cannot hold an undefined property, so an explicit one counts as absent.
+    const rec = val as Record<string, unknown>;
+    const keys = Object.keys(rec).filter(k => rec[k] !== undefined).sort();
+    return `{${keys.map(k => `${JSON.stringify(k)}:${stableStringify(rec[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(val) ?? "undefined";
+}
+
+export function diffModels(a: Model, b: Model): { added: string[]; removed: string[]; changed: string[] } {
+  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),
+  };
+}