@caddis/cli 0.4.44 → 0.4.45

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

@@ -0,0 +1,142 @@
+// flow-studio engine entry. mount() draws a model into a page that has the shell's element ids and returns
+// 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 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 { 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";
+
+export interface FlowStudio {
+  model: Model;
+  geometry(): Geometry;
+  view(): View;
+  setView(v: View, animate?: boolean): void;
+  fit(animate?: boolean): void;
+  select(id: string | null): void;
+  selected(): string | null;
+  mode(): string;
+  setMode(id: string): void;
+  simulate(actionId: string): void;
+  resetSimulation(): void;
+  destroy(): void;
+}
+
+declare global {
+  interface Window { FlowStudio?: FlowStudio; flowStudioMount?: typeof mount }
+}
+
+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",
+  notelist: "notelist", notesBtn: "notesBtn", theme: "theme", specbody: "specbody", spec: "spec", title: "title",
+  readat: "readat", help: "help", footer: "footer",
+};
+
+function findEls(root: ParentNode): Els {
+  const out = {} as Record<string, Element>;
+  for (const [key, id] of Object.entries(IDS)) {
+    const e = root.querySelector("#" + id);
+    if (!e) throw new Error(`flow-studio: the page has no element #${id}`);
+    out[key] = e;
+  }
+  return out as unknown as Els;
+}
+
+export function mount(root: ParentNode, model: Model, opts: { notes?: NoteDef[] } = {}): 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");
+  }
+  const els = findEls(root);
+  const issues = validateModel(model);
+  const errors = issues.filter(i => i.level === "error");
+  for (const i of issues) (i.level === "error" ? console.error : console.warn)(`flow-studio ${i.code} ${i.where}: ${i.message}`);
+  if (errors.length) els.help.textContent = `${errors.length} model error(s). See the console. The page shows what it can.`;
+
+  const rm = matchMedia("(prefers-reduced-motion: reduce)");
+  const ctx: Ctx = {
+    model, root, els,
+    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 } },
+    view: { x: 0, y: 0, k: 1 },
+    reduced: rm.matches,
+    mode: defaultView(model),
+    selected: null, hl: null, query: "", 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"],
+  };
+  const onRm = (e: MediaQueryListEvent) => { ctx.reduced = e.matches; };
+  rm.addEventListener("change", onRm);
+  ctx.disposers.push(() => rm.removeEventListener("change", onRm));
+
+  let style = document.getElementById("state-css") as HTMLStyleElement | null;
+  if (!style) { style = document.createElement("style"); style.id = "state-css"; document.head.prepend(style); }
+  style.textContent = stateCss(model.states);
+
+  installInteract(ctx);
+  installRender(ctx);
+  installControls(ctx);
+  installInspector(ctx);
+  installChrome(ctx);
+  installNotes(ctx);
+
+  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 api: FlowStudio = {
+    model,
+    geometry: () => ctx.geom,
+    view: () => ({ ...ctx.view }),
+    setView: (v, animate) => ctx.fn.setView(v, animate),
+    fit: animate => { ctx.userMoved = false; ctx.fn.fit(animate); },
+    select: id => ctx.fn.select(id),
+    selected: () => ctx.selected,
+    mode: () => ctx.mode,
+    setMode: id => ctx.fn.setMode(id),
+    simulate: id => ctx.fn.simulate(id),
+    resetSimulation: () => { ctx.fn.clearSim(); ctx.fn.renderInspector(); },
+    destroy: () => {
+      ctx.fn.clearSim();
+      ctx.disposers.forEach(d => d());
+      ctx.disposers = [];
+      style?.remove();
+      if (window.FlowStudio === api) 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/antigravity-plugin/skills/flow-studio/src/inspector.ts

@@ -0,0 +1,108 @@
+// The slide-in inspector. It uses the markup and class names of the host app's own inspector
+// (.insp, .insp-h, .counts .cbtn, .insp-b, .drill, .pill, .meta), so it looks native when the page lives in an app.
+// It is closed until a click, and it also opens to list search matches when nothing is selected.
+
+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 { matches, relationSet, relationsOf } from "./interact.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;
+
+export function install(ctx: Ctx): void {
+  const { els, model } = ctx;
+
+  const matchesFilter = (n: NodeDef, f: RelationDef["filter"]): boolean =>
+    !f || ((f.col === undefined || n.col === f.col) && (f.kind === undefined || n.kind === f.kind));
+
+  function wire(box: HTMLElement): void {
+    box.querySelector("#hideInsp")?.addEventListener("click", () => {
+      if (ctx.selected) ctx.fn.select(null);
+      else { ctx.dismissed = true; ctx.fn.renderInspector(); }
+    });
+    box.querySelectorAll<HTMLElement>("[data-hl]").forEach(b => b.addEventListener("click", () => {
+      ctx.hl = ctx.hl === b.dataset.hl ? null : (b.dataset.hl ?? null);
+      ctx.fn.trace(ctx.selected);
+      ctx.fn.renderInspector();
+    }));
+    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.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); });
+  }
+
+  function renderInspector(): void {
+    const box = els.inspector, ws = els.workspace;
+    const sel = ctx.selected ? ctx.nodes.get(ctx.selected) : undefined;
+    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 open = found.length > 0;
+      box.classList.toggle("open", open);
+      ws.classList.toggle("inspopen", open);
+      box.setAttribute("aria-hidden", String(!open));
+      if (!open) return;
+      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>`;
+      }).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);
+      return;
+    }
+
+    box.classList.add("open");
+    ws.classList.add("inspopen");
+    box.setAttribute("aria-hidden", "false");
+
+    const sid = nodeStateId(model, ctx.mode, sel);
+    const st = model.states[sid];
+    const bucket = bucketOf(model, sid);
+    const lane = model.lanes.find(l => l.id === sel.lane);
+    const counts = relationsOf(ctx).slice(0, 3).map(r => {
+      const set = relationSet(ctx, r, sel.id);
+      let n = 0;
+      for (const id of set) {
+        const x = ctx.nodes.get(id);
+        if (!x) continue;
+        if (r.filter) { if (matchesFilter(x, r.filter)) n += Math.max(1, x.weight ?? 1); }
+        else if (id !== sel.id) n += 1;
+      }
+      const cls = r.id === "up" ? "cn--up" : r.id === "down" ? "cn--down" : "";
+      return `<button class="cbtn" data-hl="${esc(r.id)}" aria-pressed="${ctx.hl === r.id}"><span class="cn ${cls}">${n}</span><span class="cl">${esc(r.label)}</span></button>`;
+    }).join("");
+
+    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)}">▶ ${esc(a.label)}</button>`).join("");
+    const members = sel.members ?? [];
+
+    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-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>
+      ${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>`}
+      <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);
+
+    const mq = box.querySelector<HTMLInputElement>("#mq");
+    const draw = () => {
+      const f = (mq?.value ?? "").toLowerCase();
+      const rows = members.filter(m => m.toLowerCase().includes(f));
+      const list = box.querySelector<HTMLElement>("#mlist");
+      if (list) list.innerHTML = rows.slice(0, 14).map(m => `<div class="dr"><span class="dbar" style="background:var(--${BUCKET_COLOR[bucket]})"></span><span class="dtx"><span class="dn mono" style="font-size:12px">${esc(m)}</span></span></div>`).join("");
+      const cnt = box.querySelector<HTMLElement>("#mcount");
+      const weight = sel.weight ?? 0;
+      if (cnt) cnt.textContent = `${Math.min(14, rows.length)} of ${rows.length}${weight > members.length ? ` named (${weight} members in all)` : ""}`;
+    };
+    if (mq) { mq.addEventListener("input", draw); draw(); }
+  }
+
+  ctx.fn.renderInspector = renderInspector;
+}

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

@@ -0,0 +1,240 @@
+// Interaction: tracing a path, selecting, the draw-in trail, the what-if action, zooming to a path or lane.
+
+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";
+
+export function relationsOf(ctx: Ctx): RelationDef[] {
+  const given = ctx.model.inspector?.relations;
+  if (given && given.length) return given;
+  const last = Math.max(0, ctx.model.columns.length - 1);
+  return [
+    { id: "up", label: "Upstream", dir: "up" },
+    { id: "down", label: "Downstream", dir: "down" },
+    { id: "end", label: "At the end", dir: "down", filter: { col: last } },
+  ];
+}
+
+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 }));
+}
+
+export function relationSet(ctx: Ctx, rel: RelationDef, start: string): Set<string> {
+  const canon = (id: string) => canonOf(ctx.nodes, id);
+  const set = relatives(visibleEdges(ctx), canon, start, rel.dir);
+  if (!rel.filter) return set;
+  const out = new Set<string>([canon(start)]);
+  for (const id of set) {
+    const n = ctx.nodes.get(id);
+    if (!n) continue;
+    if ((rel.filter.col === undefined || n.col === rel.filter.col) && (rel.filter.kind === undefined || n.kind === rel.filter.kind)) out.add(id);
+  }
+  return out;
+}
+
+export function matches(ctx: Ctx, n: NodeDef): boolean {
+  const q = ctx.query;
+  return !!q && (n.title.toLowerCase().includes(q) || (n.members ?? []).some(m => m.toLowerCase().includes(q)));
+}
+
+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 inspInset = () => (els.inspector.classList.contains("open") ? 340 : 0);
+
+  function activeSet(id: string | null): Set<string> | null {
+    const edges = visibleEdges(ctx);
+    if (id) {
+      if (id === ctx.selected && ctx.hl) {
+        const rel = relationsOf(ctx).find(r => r.id === ctx.hl);
+        if (rel) return relationSet(ctx, rel, id);
+      }
+      return connected(edges, canon, id);
+    }
+    if (ctx.filter) {
+      return new Set(visibleNodes().filter(n => {
+        const b = bucketOf(model, nodeStateId(model, ctx.mode, n));
+        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)));
+    return null;
+  }
+
+  function trace(id: string | null): void {
+    const set = activeSet(id);
+    const lit = !!id && !!set;
+    for (const n of model.nodes) {
+      const d = ctx.nodeEls.get(n.id);
+      if (!d) continue;
+      d.classList.toggle("dim", !!set && !set.has(canon(n.id)));
+      d.classList.toggle("lit", lit && !!set && set.has(canon(n.id)));
+    }
+    ctx.edgeEls.forEach(p => {
+      if (!p) return;
+      const inSet = !!set && set.has(canon(p.dataset.a ?? "")) && set.has(canon(p.dataset.b ?? ""));
+      p.classList.toggle("dim", !!set && !inSet);
+      p.classList.toggle("hot", lit && inSet);
+    });
+    ctx.labelEls.forEach(l => { if (l) l.classList.toggle("show", lit && !!set && set.has(canon(l.dataset.a ?? "")) && set.has(canon(l.dataset.b ?? ""))); });
+  }
+
+  function select(id: string | null): void {
+    clearSim();
+    ctx.selected = id ? canon(id) : null;
+    ctx.hl = null;
+    ctx.dismissed = false;
+    for (const n of model.nodes) ctx.nodeEls.get(n.id)?.classList.toggle("sel", !!ctx.selected && canon(n.id) === ctx.selected);
+    trace(ctx.selected);
+    ctx.fn.renderInspector();
+    drawTrail();
+    if (ctx.selected) revealNode(ctx.selected);
+  }
+
+  /** An overlay is a copy of one link drawn on top. pathLength=1 makes the draw-in independent of zoom. */
+  function overlay(edge: SVGPathElement, cls: string, delay: number, dur: number): SVGPathElement {
+    const o = edge.cloneNode(false) as SVGPathElement;
+    o.setAttribute("class", cls);
+    o.setAttribute("pathLength", "1");
+    o.removeAttribute("data-i");
+    els.layer.appendChild(o);
+    ctx.overlays.push(o);
+    if (ctx.reduced) return o;
+    o.style.strokeDasharray = "1 1";
+    o.style.strokeDashoffset = "1";
+    o.getBoundingClientRect();
+    o.style.transition = `stroke-dashoffset ${dur}s ${delay}s ease-out`;
+    o.style.strokeDashoffset = "0";
+    return o;
+  }
+  function dropOverlays(cls: string): void {
+    ctx.overlays.filter(o => o.classList.contains(cls)).forEach(o => o.remove());
+    ctx.overlays = ctx.overlays.filter(o => o.isConnected);
+  }
+  function drawTrail(): void {
+    dropOverlays("trail");
+    if (!ctx.selected || ctx.reduced) return;
+    const set = connected(visibleEdges(ctx), canon, ctx.selected);
+    const c0 = ctx.nodes.get(ctx.selected)?.col ?? 0;
+    for (const p of ctx.edgeEls) {
+      if (!p || p.classList.contains("off")) continue;
+      const a = canon(p.dataset.a ?? ""), b = canon(p.dataset.b ?? "");
+      if (!(set.has(a) && set.has(b))) continue;
+      const delay = Math.min(Math.abs((ctx.nodes.get(a)?.col ?? 0) - c0), Math.abs((ctx.nodes.get(b)?.col ?? 0) - c0)) * 0.09;
+      const o = overlay(p, "trail", delay, 0.55);
+      window.setTimeout(() => { o.style.transition = "opacity .6s"; o.style.opacity = "0"; window.setTimeout(() => o.remove(), 650); }, (delay + 0.55) * 1000 + 150);
+    }
+  }
+
+  function simulate(actionId: string): void {
+    clearSim();
+    if (!ctx.selected) return;
+    const action = model.inspector?.actions?.find(a => a.id === actionId);
+    const stale = action?.staleText ?? "potentially stale";
+    ctx.simActive = true;
+    const down = relatives(visibleEdges(ctx), canon, ctx.selected, "down");
+    const c0 = ctx.nodes.get(ctx.selected)?.col ?? 0;
+    for (const p of ctx.edgeEls) {
+      if (!p || p.classList.contains("off")) continue;
+      const a = canon(p.dataset.a ?? ""), b = canon(p.dataset.b ?? "");
+      if (down.has(a) && down.has(b)) overlay(p, "ripple", Math.abs((ctx.nodes.get(a)?.col ?? 0) - c0) * 0.11, 0.5);
+    }
+    down.forEach(id => {
+      if (id === ctx.selected) return;
+      const d = ctx.nodeEls.get(id);
+      if (!d) return;
+      const delay = ctx.reduced ? 0 : Math.abs((ctx.nodes.get(id)?.col ?? 0) - c0) * 110 + 450;
+      ctx.simTimers.push(window.setTimeout(() => {
+        d.classList.add("fail");
+        const sub = d.querySelector(".s");
+        if (sub) { d.dataset.s = sub.innerHTML; sub.textContent = stale; }
+      }, delay));
+    });
+    ctx.fn.announce(`Simulation: ${down.size - 1} groups downstream of ${ctx.nodes.get(ctx.selected)?.title ?? ""} would be ${stale}.`);
+    ctx.fn.renderInspector();
+  }
+  function clearSim(): void {
+    ctx.simTimers.forEach(t => clearTimeout(t));
+    ctx.simTimers = [];
+    dropOverlays("ripple");
+    document.querySelectorAll<HTMLElement>(".node.fail").forEach(d => {
+      d.classList.remove("fail");
+      const sub = d.querySelector(".s");
+      if (sub && d.dataset.s !== undefined) { sub.innerHTML = d.dataset.s; delete d.dataset.s; }
+    });
+    ctx.simActive = false;
+  }
+
+  /** The inspector covers the right 340 px. If the group would sit under it, glide the view left. */
+  function revealNode(id: string): void {
+    const d = ctx.nodeEls.get(id);
+    if (!d) return;
+    const r = d.getBoundingClientRect(), v = els.vp.getBoundingClientRect(), edge = v.right - 340 - 24;
+    if (r.right > edge) {
+      ctx.userMoved = true;
+      ctx.fn.setView({ k: ctx.view.k, x: ctx.view.x + Math.max(edge - r.right, v.left + 60 - r.left), y: ctx.view.y }, true);
+    }
+  }
+
+  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));
+    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));
+    return { x: x1 - 20, y: y1 - 20, w: x2 - x1 + 40, h: y2 - y1 + 40 };
+  }
+  function zoomToPath(): void {
+    if (!ctx.selected) return;
+    const ids = [...connected(visibleEdges(ctx), canon, ctx.selected)];
+    ids.push(...model.nodes.filter(n => n.ref && ids.includes(n.ref)).map(n => n.id));
+    const r = rectOf(ids);
+    if (r) { ctx.userMoved = true; ctx.fn.fit(true, r, inspInset()); ctx.fn.announce(`Zoomed to the path of ${ctx.nodes.get(ctx.selected)?.title ?? ""}`); }
+  }
+  function zoomToBand(id: string): void {
+    const r = ctx.geom.lanes[id];
+    if (!r) return;
+    ctx.userMoved = true;
+    ctx.fn.fit(true, { x: r.x - 10, y: r.y - 10, w: r.w + 20, h: r.h + 20 }, inspInset());
+    ctx.fn.announce(`Zoomed to the lane ${model.lanes.find(l => l.id === id)?.title ?? id}`);
+  }
+
+  function escape(): void {
+    clearSim();
+    select(null);
+    ctx.filter = null;
+    ctx.query = "";
+    els.q.value = "";
+    els.matchinfo.textContent = "";
+    ctx.fn.buildChrome();
+    trace(null);
+    ctx.fn.toggleNotes(false);
+  }
+  function setMode(id: string): void {
+    if (ctx.mode === id) return;
+    document.body.classList.remove("intro");
+    clearSim();
+    ctx.mode = id;
+    const sel = ctx.selected && ctx.nodes.get(ctx.selected);
+    if (sel && !nodeVisible(model, id, sel)) 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;
+    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;
+  ctx.fn.select = select;
+  ctx.fn.drawTrail = drawTrail;
+  ctx.fn.simulate = simulate;
+  ctx.fn.clearSim = clearSim;
+  ctx.fn.rectOf = rectOf;
+  ctx.fn.zoomToPath = zoomToPath;
+  ctx.fn.zoomToBand = zoomToBand;
+  ctx.fn.escape = escape;
+  ctx.fn.setMode = setMode;
+  ctx.fn.announce = (t: string) => { els.live.textContent = t; };
+}

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

@@ -0,0 +1,69 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { computeGeometry } from "./layout.ts";
+import type { Model } from "./model.ts";
+
+const m = (): Model => ({
+  version: 1,
+  meta: { title: "t", help: "", asOf: "", source: "" },
+  layout: "columns-lanes",
+  columns: [{ id: "c0", title: "A", width: 150 }, { id: "c1", title: "B", width: 200 }],
+  lanes: [{ id: "l1", title: "One" }, { id: "l2", title: "Two" }],
+  states: { ok: { word: "OK", tone: "ok", border: "solid", edge: "flow", motion: "flow", bucket: "good" } },
+  nodes: [
+    { id: "a", kind: "card", lane: "l1", col: 0, row: 0, state: "ok", title: "A" },
+    { id: "b", kind: "card", lane: "l1", col: 1, row: 0, state: "ok", title: "B" },
+    { id: "c", kind: "card", lane: "l2", col: 0, row: 1.8, state: "ok", title: "C" },
+    { id: "w", kind: "placeholder", lane: "l2", col: 0, colSpan: 2, row: 2.8, state: "ok", title: "W" },
+  ],
+  links: [{ id: "a-b", from: "a", to: "b", state: "ok" }],
+});
+
+test("columns are laid out left to right with the gap", () => {
+  const g = computeGeometry(m());
+  assert.equal(g.xs[0], 24);
+  assert.equal(g.xs[1], 24 + 150 + 34);
+});
+test("a node sits at its column and its row", () => {
+  const g = computeGeometry(m());
+  assert.equal(g.nodes.a!.x, 24);
+  assert.equal(g.nodes.a!.w, 150);
+  assert.ok(g.nodes.c!.y > g.nodes.a!.y);
+});
+test("a wide node spans its columns", () => {
+  const g = computeGeometry(m());
+  assert.equal(g.nodes.w!.w, 150 + 34 + 200);
+});
+test("a chip is shorter than a card", () => {
+  const mm = m();
+  mm.nodes.push({ id: "k", kind: "chip", lane: "l1", col: 0, row: 3.8, state: "ok", title: "k", ref: "a" });
+  const g = computeGeometry(mm);
+  assert.ok(g.nodes.k!.h < g.nodes.a!.h);
+});
+test("lane rectangles are computed from their nodes and do not overlap", () => {
+  const g = computeGeometry(m());
+  const a = g.lanes.l1!, b = g.lanes.l2!;
+  assert.ok(a.y + a.h <= b.y, `${a.y + a.h} <= ${b.y}`);
+});
+test("a lane without visible nodes has no rectangle", () => {
+  const g = computeGeometry(m(), { visible: id => id !== "c" && id !== "w" });
+  assert.equal(g.lanes.l2, undefined);
+});
+test("bounds cover every lane and the world is finite", () => {
+  const g = computeGeometry(m());
+  assert.ok(Object.values(g.lanes).every(l => l.y >= g.bounds.y && l.y + l.h <= g.bounds.y + g.bounds.h + 1e-6));
+  assert.ok(Number.isFinite(g.world.w) && Number.isFinite(g.world.h));
+});
+test("an empty model has a finite, empty geometry (review focus 2)", () => {
+  const mm = m();
+  mm.nodes = [];
+  mm.links = [];
+  const g = computeGeometry(mm);
+  assert.ok(Number.isFinite(g.bounds.w) && Number.isFinite(g.bounds.h) && Number.isFinite(g.world.h));
+});
+test("a node whose column is out of range does not produce NaN", () => {
+  const mm = m();
+  mm.nodes[0]!.col = 9;
+  const g = computeGeometry(mm);
+  assert.ok(Object.values(g.nodes).every(n => [n.x, n.y, n.w, n.h].every(Number.isFinite)));
+});

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

@@ -0,0 +1,57 @@
+// 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 type { Rect, Size } from "./viewport.ts";
+
+export interface Placed extends Rect { id: string }
+export interface Geometry {
+  xs: number[];
+  nodes: Record<string, Placed>;
+  lanes: Record<string, Rect>;
+  bounds: Rect;
+  world: Size;
+}
+export interface LayoutOptions { pitch: number; top: number; gap: number; padX: number; visible: (id: string) => boolean }
+
+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;
+
+export function computeGeometry(m: Model, opt: Partial<LayoutOptions> = {}): Geometry {
+  const o: LayoutOptions = { ...DEFAULTS, ...opt };
+  const xs: number[] = [];
+  let x = o.padX;
+  for (const c of m.columns) { xs.push(x); x += c.width + o.gap; }
+  const world: Size = { w: Math.max(1, x - o.gap + o.padX), h: 1 };
+
+  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 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 };
+  }
+
+  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;
+    lanes[l.id] = { x: 8, y: y1, w: world.w - 16, h: y2 - y1 };
+  }
+
+  const all = Object.values(lanes);
+  let bounds: Rect = { x: 0, y: 0, w: world.w, h: 1 };
+  if (all.length) {
+    const top = Math.min(...all.map(r => r.y));
+    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 };
+}