@caddis/cli 0.4.44 → 0.4.46

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

@@ -0,0 +1,193 @@
+import { on, sv, type Ctx } from "./ctx.ts";
+import { buildManualRoute, extendScenarioWithRoute, exitsOf, formatElapsed, planScenario, positionAt, slaState, suggestedExit, type Plan, type PlannedStep } from "./playback.ts";
+import type { ScenarioDef } from "./model.ts";
+
+export interface PlaybackController {
+  play(id?: string): void;
+  pause(): void;
+  step(): void;
+  seek(t: number): void;
+  playback(): { scenario: string | null; step: number; playing: boolean; t: number };
+  restore(state: ReturnType<PlaybackController["playback"]>): void;
+  reset(): void;
+}
+
+export function install(ctx: Ctx): PlaybackController {
+  const e = ctx.els;
+  const scenarios = ctx.model.scenarios ?? [];
+  e.playbar.hidden = !scenarios.length;
+  e.pbScenario.replaceChildren(...scenarios.map(s => { const o = document.createElement("option"); o.value = s.id; o.textContent = s.label; return o; }));
+  let scenario: ScenarioDef | undefined = scenarios[0];
+  let plan: Plan = scenario ? planScenario(ctx.model, scenario) : { steps: [], mode: "none", totalMs: 0 };
+  let t = 0, idx = -1, playing = false, frame = 0, timer = 0, stamp = 0, choicesKey = "";
+  // Only the elements marked in the last draw are cleared again, so a frame does not walk the whole graph.
+  let markedEdges: SVGPathElement[] = [];
+  let markedNodes: HTMLElement[] = [];
+  const token = sv("circle", { id: "token", class: "token", r: "6" }) as SVGCircleElement;
+  e.layer.appendChild(token);
+  const pathOf = (link: string): SVGPathElement | undefined => ctx.edgeEls[ctx.links.findIndex(l => l.id === link)];
+  const nodeOf = (id: string) => ctx.nodeEls.get(id);
+  const clearMarks = () => {
+    for (const p of markedEdges) p.classList.remove("playing", "visited");
+    for (const n of markedNodes) n.classList.remove("playing", "visited");
+    markedEdges = []; markedNodes = [];
+  };
+  function stop(): void {
+    playing = false; cancelAnimationFrame(frame); clearTimeout(timer);
+    document.body.classList.remove("playing");
+    e.pbPlay.setAttribute("aria-label", "Play"); e.pbPlay.textContent = "▶";
+  }
+  function pause(): void {
+    if (!playing) return;
+    stop();
+    // Redraw with playing false, so the branch buttons of the step we paused on come back.
+    const p = positionAt(plan, t);
+    draw(p.stepIndex, ctx.reduced ? 1 : p.progress);
+  }
+  function choices(step: PlannedStep | undefined): void {
+    if (playing || !step) {
+      // Hidden while playing; clear once, then leave the container alone for the rest of the frames.
+      if (choicesKey !== "") { e.pbChoices.replaceChildren(); choicesKey = ""; }
+      return;
+    }
+    const key = `${scenario?.id ?? ""}|${idx}|${plan.steps.length}|${plan.steps[idx + 1]?.link ?? ""}`;
+    if (key === choicesKey) return;
+    choicesKey = key;
+    e.pbChoices.replaceChildren();
+    const exits = exitsOf(ctx.model, step.to);
+    if (exits.length < 2) return;
+    const suggested = suggestedExit(exits, plan.steps[idx + 1]?.link);
+    for (const link of exits) {
+      const b = document.createElement("button"); b.type = "button";
+      b.textContent = link.label ?? ctx.nodes.get(link.to)?.title ?? link.to;
+      b.dataset.link = link.id;
+      if (link.id === suggested?.id) b.classList.add("suggested");
+      b.addEventListener("click", () => {
+        // A plan step exists only when a scenario does, so scenario is set here.
+        if (!scenario) return;
+        const route = buildManualRoute(ctx.model, link);
+        scenario = extendScenarioWithRoute(scenario, plan, idx, route);
+        plan = planScenario(ctx.model, scenario);
+        t = plan.steps[idx + 1]?.at ?? 0;
+        play();
+      });
+      e.pbChoices.appendChild(b);
+    }
+  }
+  function draw(stepIndex: number, progress: number): void {
+    const step = plan.steps[stepIndex];
+    clearMarks();
+    if (!step) { token.style.display = "none"; return; }
+    token.style.display = "";
+    for (let i = 0; i < stepIndex; i++) {
+      const s = plan.steps[i]!;
+      const p = pathOf(s.link);
+      if (p) { p.classList.add("visited"); markedEdges.push(p); }
+      const n = nodeOf(s.to);
+      if (n) { n.classList.add("visited"); markedNodes.push(n); }
+    }
+    const path = pathOf(step.link);
+    if (path) { path.classList.add("playing"); markedEdges.push(path); }
+    const node = nodeOf(step.to);
+    if (node) { node.classList.add("playing"); markedNodes.push(node); }
+    if (path && !path.classList.contains("off")) {
+      const p = path.getPointAtLength(path.getTotalLength() * progress);
+      token.setAttribute("cx", String(p.x)); token.setAttribute("cy", String(p.y));
+    } else token.style.display = "none";
+    e.pbCaption.textContent = step.caption;
+    e.pbScrub.value = String(plan.totalMs ? Math.round(t / plan.totalMs * 1000) : 0);
+    e.pbScrub.setAttribute("aria-valuetext", `Step ${stepIndex + 1} of ${plan.steps.length}: ${step.caption}`);
+    e.pbCounter.className = "";
+    e.pbCounter.hidden = plan.mode === "none";
+    if (plan.mode === "elapsed") {
+      const sec = scenario?.steps[step.index]?.at ?? 0;
+      const sla = ctx.nodes.get(step.to)?.sla;
+      e.pbCounter.textContent = sla === undefined ? formatElapsed(sec) : `${formatElapsed(sec)} / ${formatElapsed(sla)}`;
+      if (sla !== undefined) e.pbCounter.classList.add(slaState(sec, sla));
+    }
+    if (idx !== stepIndex) ctx.fn.announce(step.caption);
+    idx = stepIndex;
+    choices(step);
+  }
+  function rewind(): void {
+    stop(); t = 0; idx = -1; clearMarks(); choicesKey = "";
+    e.pbCaption.textContent = "";
+    e.pbCounter.hidden = true; e.pbCounter.className = "";
+    e.pbChoices.replaceChildren();
+    token.style.display = "none";
+    e.pbScrub.value = "0"; e.pbScrub.setAttribute("aria-valuetext", "");
+  }
+  function select(id: string): void {
+    scenario = scenarios.find(s => s.id === id) ?? scenarios[0];
+    plan = scenario ? planScenario(ctx.model, scenario) : { steps: [], mode: "none", totalMs: 0 };
+    e.pbScenario.value = scenario?.id ?? "";
+    rewind();
+  }
+  function seek(value: number): void {
+    stop(); t = Math.max(0, Math.min(plan.totalMs, Number.isFinite(value) ? value : 0));
+    const p = positionAt(plan, t); draw(p.stepIndex, ctx.reduced ? 1 : p.progress);
+  }
+  function tick(now: number): void {
+    if (!playing) return;
+    if (!stamp) stamp = now;
+    const delta = (now - stamp) * Number(e.pbSpeed.value || 1); stamp = now;
+    t = Math.min(plan.totalMs, t + delta);
+    const p = positionAt(plan, t);
+    if (p.done) { stop(); draw(p.stepIndex, 1); return; }
+    draw(p.stepIndex, p.progress);
+    frame = requestAnimationFrame(tick);
+  }
+  function reducedStep(): void {
+    if (!playing) return;
+    const next = Math.min(plan.steps.length - 1, idx + 1);
+    if (next < 0) { stop(); return; }
+    t = plan.steps[next]!.at + plan.steps[next]!.dur;
+    // Stop before the last draw so the branch buttons of the final step are built.
+    if (next === plan.steps.length - 1) stop();
+    draw(next, 1);
+    if (playing) timer = window.setTimeout(reducedStep, 1000 / Number(e.pbSpeed.value || 1));
+  }
+  function play(id?: string): void {
+    if (id && id !== scenario?.id) select(id);
+    // Cancel any loop already running, or two frames would advance t together.
+    stop();
+    if (!plan.steps.length) return;
+    if (t >= plan.totalMs) { t = 0; idx = -1; }
+    playing = true;
+    document.body.classList.add("playing");
+    e.pbPlay.setAttribute("aria-label", "Pause"); e.pbPlay.textContent = "❚❚";
+    e.pbChoices.replaceChildren(); choicesKey = "";
+    if (ctx.reduced) reducedStep(); else { stamp = 0; frame = requestAnimationFrame(tick); }
+  }
+  function step(): void {
+    stop();
+    const next = Math.min(idx + 1, plan.steps.length - 1);
+    if (next < 0) return;
+    t = plan.steps[next]!.at + plan.steps[next]!.dur;
+    draw(next, 1);
+  }
+  on(ctx, e.pbScenario, "change", () => select(e.pbScenario.value));
+  on(ctx, e.pbPlay, "click", () => playing ? pause() : play());
+  on(ctx, e.pbStep, "click", step);
+  // Reset rewinds the current plan (a manual branch stays); picking from the scenario list starts over.
+  on(ctx, e.pbReset, "click", () => rewind());
+  on(ctx, e.pbScrub, "input", () => seek(Number(e.pbScrub.value) / 1000 * plan.totalMs));
+  on(ctx, document, "keydown", (event: KeyboardEvent) => {
+    if (event.ctrlKey || event.metaKey || event.altKey || (event.target instanceof HTMLElement && (event.target.isContentEditable || /INPUT|TEXTAREA|SELECT/.test(event.target.tagName)))) return;
+    if (event.key.toLowerCase() === "p") { event.preventDefault(); playing ? pause() : play(); }
+    if (event.key === ".") { event.preventDefault(); step(); }
+  });
+  ctx.disposers.push(() => { stop(); token.remove(); });
+  select(scenario?.id ?? "");
+  return { play, pause, step, seek, playback: () => ({ scenario: scenario?.id ?? null, step: idx, playing, t }),
+    restore: state => {
+      if (!state.scenario || !scenarios.some(s => s.id === state.scenario)) return;
+      select(state.scenario);
+      const current = plan.steps[state.step];
+      if (!current) return;
+      t = Math.max(current.at, Math.min(current.at + current.dur, state.t));
+      draw(state.step, ctx.reduced ? 1 : current.dur > 0 ? (t - current.at) / current.dur : 1);
+      if (state.playing) play();
+    },
+    reset: () => rewind() };
+}

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

@@ -0,0 +1,203 @@
+// Builds the world (lanes, nodes, links) once, and paints it for the current view.
+// Every model string goes through esc(), so a hostile title cannot become markup.
+
+import { el, sv, on, type Ctx } from "./ctx.ts";
+import { esc } from "./model.ts";
+import type { NodeDef } from "./model.ts";
+import { computeGeometry, DEFAULTS, type Placed } from "./layout.ts";
+import { elbow, loopBack } from "./routing.ts";
+import { cssId } from "./stateCss.ts";
+import { baselineView, bucketOf, canonOf, effectiveLinks, isImproved, isNew, linkStateId, nodeStateId, nodeVisible } from "./rules.ts";
+import { metricBadge, sparkline } from "./metrics.ts";
+
+function loopRoute(ctx: Ctx, fromId: string, toId: string, from: Placed, to: Placed, channel: number): string {
+  const detourFor = (end: Placed, other: Placed) => {
+    const center = end.x + end.w / 2, bottom = end.y + end.h;
+    const blocker = ctx.model.nodes.filter(n => n.id !== fromId && n.id !== toId && nodeVisible(ctx.model, ctx.mode, n, ctx.collapsed))
+      .map(n => ctx.geom.nodes[n.id]).filter((p): p is Placed => !!p && p.x < center && center < p.x + p.w && p.y > bottom && p.y < channel)
+      .sort((a, b) => a.y - b.y)[0];
+    if (!blocker) return undefined;
+    return { x: other.x + other.w / 2 < center ? blocker.x - 10 : blocker.x + blocker.w + 10, y: (bottom + blocker.y) / 2 };
+  };
+  return loopBack(from.x + from.w / 2, from.y + from.h, to.x + to.w / 2, to.y + to.h, channel,
+    { from: detourFor(from, to), to: detourFor(to, from) });
+}
+
+function nodeHtml(ctx: Ctx, n: NodeDef): string {
+  const badge = metricBadge(n.metrics);
+  const spark = sparkline(n.metrics, 56, 12);
+  if (n.kind === "gateway") {
+    return `<svg class="gw" viewBox="0 0 100 100" preserveAspectRatio="none" aria-hidden="true"><polygon points="50,0 100,50 50,100 0,50"></polygon></svg><span class="gw-title">${esc(n.title)}</span>${badge}${spark}`;
+  }
+  const m = ctx.model;
+  const sid = nodeStateId(m, ctx.mode, n);
+  const word = m.states[sid]?.word ?? sid;
+  const bucket = bucketOf(m, sid);
+  const sub = n.subtitle ?? m.columns[n.col ?? 0]?.title ?? "";
+  const weight = Math.max(1, n.weight ?? 1);
+  const showWord = n.kind !== "placeholder" && n.kind !== "note";
+  const bar = weight > 1 && n.kind !== "chip"
+    ? `<div class="bar"><i class="${["good", "neutral", "gap"].includes(bucket) ? bucket : "gap"}" style="width:100%"></i></div>`
+    : "";
+  const improved = isImproved(m, ctx.mode, n) ? '<span class="cor up" title="Gap filled in this view">▲</span>' : "";
+  const upgrade = n.upgrade && bucket !== "good" ? `<span class="cor meas" title="${esc("Can improve: " + n.upgrade)}">↗</span>` : "";
+  const arrow = n.kind === "chip" ? '<span aria-hidden="true">↑ </span>' : "";
+  const lead = showWord ? `<b class="ev st-${cssId(sid)}">${esc(word)}</b> · ` : "";
+  const fold = n.kind === "group" && n.contains?.length ? `<span class="fold">▸ ${n.contains.length}</span>` : "";
+  return `<div class="t"><span class="newdot" title="Added in this view"></span><span class="name">${arrow}${esc(n.title)}</span>${fold}${badge}</div>`
+    + `<div class="s${spark ? " has-spark" : ""}" title="${esc(sub)}">${lead}${esc(sub)}</div>${spark}${bar}${improved}${upgrade}`;
+}
+
+function build(ctx: Ctx): void {
+  const { model, els } = ctx;
+  ctx.geom = computeGeometry(model);
+  els.world.style.width = ctx.geom.world.w + "px";
+  els.world.style.height = ctx.geom.world.h + "px";
+  els.svg.setAttribute("width", String(ctx.geom.world.w));
+  els.svg.setAttribute("height", String(ctx.geom.world.h));
+  els.world.querySelectorAll(".node, .band, .elabel").forEach(n => n.remove());
+  els.layer.innerHTML = "";
+  ctx.nodeEls.clear(); ctx.laneEls.clear(); ctx.edgeEls = []; ctx.labelEls = [];
+
+  for (const l of model.lanes) {
+    const d = el("div", "band" + (l.gap ? " gap" : ""));
+    d.id = "lane_" + l.id;
+    const badge = l.badge ? `<span class="bd t-${["ok", "warn", "muted"].includes(l.badgeTone ?? "") ? l.badgeTone : "muted"}">${esc(l.badge)}</span>` : "";
+    const note = l.note ? `<span class="bn">${esc(l.note)}</span>` : "";
+    d.innerHTML = `<div class="bandlabel" role="button" tabindex="0" aria-label="${esc("Zoom to the lane " + l.title)}"><b>${esc(l.title)}</b>${badge}${note}</div>`;
+    const label = d.firstElementChild as HTMLElement;
+    on(ctx, label, "click", (e: Event) => { e.stopPropagation(); ctx.fn.zoomToBand(l.id); });
+    on(ctx, label, "keydown", (e: KeyboardEvent) => { if (e.key === "Enter") ctx.fn.zoomToBand(l.id); });
+    els.world.insertBefore(d, els.svg.parentElement === els.world ? els.svg : null);
+    ctx.laneEls.set(l.id, d);
+  }
+
+  for (const n of model.nodes) {
+    const p = ctx.geom.nodes[n.id];
+    if (!p) continue;
+    const d = el("div", "node" + (n.kind === "chip" ? " ref" : "") + ((n.colSpan ?? 1) > 1 ? " wide" : ""));
+    d.id = "n_" + n.id;
+    d.tabIndex = 0;
+    d.setAttribute("role", "button");
+    d.style.setProperty("--c", String(n.col ?? 0));
+    d.style.left = p.x + "px"; d.style.top = p.y + "px"; d.style.width = p.w + "px"; d.style.height = p.h + "px";
+    on(ctx, d, "click", () => { if (ctx.moved > 4) return; ctx.fn.select(canonOf(ctx.nodes, n.id)); });
+    on(ctx, d, "dblclick", (e: Event) => { e.stopPropagation(); ctx.fn.select(canonOf(ctx.nodes, n.id)); ctx.fn.zoomToPath(); });
+    on(ctx, d, "keydown", (e: KeyboardEvent) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); ctx.fn.select(canonOf(ctx.nodes, n.id)); } });
+    on(ctx, d, "mouseenter", () => ctx.fn.trace(n.id));
+    on(ctx, d, "mouseleave", () => ctx.fn.trace(ctx.selected));
+    on(ctx, d, "focus", () => ctx.fn.trace(n.id));
+    on(ctx, d, "blur", () => ctx.fn.trace(ctx.selected));
+    els.world.appendChild(d);
+    ctx.nodeEls.set(n.id, d);
+  }
+
+  const gap = DEFAULTS.gap;
+  ctx.links.forEach((l, i) => {
+    const A = ctx.geom.nodes[l.from], B = ctx.geom.nodes[l.to];
+    if (!A || !B) { console.warn(`flow-studio: link ${l.id} skipped (an end is missing)`); return; }
+    const x1 = A.x + A.w, y1 = A.y + A.h / 2, x2 = B.x, y2 = B.y + B.h / 2, tx = x1 + gap / 2;
+    const loop = l.kind === "loop-back";
+    const channel = ctx.geom.loops[l.id]?.channelY ?? Math.max(A.y + A.h, B.y + B.h) + 10;
+    const d = loop
+      ? loopRoute(ctx, l.from, l.to, A, B, channel)
+      : elbow(x1, y1, x2 - 1, y2, tx);
+    const path = sv("path", { d, class: "edge" + (loop ? " loop" : ""), "data-i": String(i), "data-a": l.from, "data-b": l.to, "marker-end": "url(#arr)" }) as SVGPathElement;
+    els.layer.appendChild(path);
+    ctx.edgeEls[i] = path;
+    if (l.label) {
+      const lab = el("div", "elabel", esc(l.label));
+      lab.dataset.i = String(i); lab.dataset.a = l.from; lab.dataset.b = l.to;
+      lab.style.left = (loop ? (A.x + A.w / 2 + B.x + B.w / 2) / 2 : Math.abs(y2 - y1) < 1 ? (x1 + x2) / 2 : tx) + "px";
+      lab.style.top = (loop ? ctx.geom.loops[l.id]?.channelY ?? Math.max(A.y + A.h, B.y + B.h) + 10 : (y1 + y2) / 2) + "px";
+      els.world.appendChild(lab);
+      ctx.labelEls[i] = lab;
+    }
+  });
+}
+
+function paint(ctx: Ctx, fromSwitch = false): void {
+  const { model } = ctx;
+  const mode = ctx.mode;
+  const effective = effectiveLinks(model, mode, ctx.collapsed, ctx.nodes);
+  const effectiveById = new Map(effective.map(l => [l.id, l]));
+  ctx.geom = computeGeometry({ ...model, links: effective }, { visible: id => { const n = ctx.nodes.get(id); return !!n && nodeVisible(model, mode, n, ctx.collapsed); } });
+  ctx.els.world.style.height = ctx.geom.world.h + "px";
+  ctx.els.svg.setAttribute("height", String(ctx.geom.world.h));
+  document.body.classList.toggle("alt", !!model.views && mode !== baselineView(model));
+
+  for (const n of model.nodes) {
+    const d = ctx.nodeEls.get(n.id);
+    if (!d) continue;
+    const rect = ctx.geom.nodes[n.id];
+    if (rect) { d.style.left = rect.x + "px"; d.style.top = rect.y + "px"; }
+    const sid = nodeStateId(model, mode, n);
+    const show = nodeVisible(model, mode, n, ctx.collapsed);
+    const bucket = bucketOf(model, sid);
+    const cors = (isImproved(model, mode, n) ? 1 : 0) + (n.upgrade && bucket !== "good" ? 1 : 0);
+    const fresh = isNew(model, mode, n);
+    d.className = "node st-" + cssId(sid)
+      + (n.kind === "chip" ? " ref" : "") + (n.kind === "gateway" ? " gateway" : "") + ((n.colSpan ?? 1) > 1 ? " wide" : "") + (n.kind === "placeholder" ? " placeholder" : "")
+      + (show ? "" : " off") + (fresh ? " isnew" : "") + (cors ? (cors > 1 ? " hascor2" : " hascor") : "")
+      + (ctx.selected && canonOf(ctx.nodes, n.id) === ctx.selected ? " sel" : "")
+      + (metricBadge(n.metrics) ? " has-metrics" : "");
+    d.innerHTML = nodeHtml(ctx, n);
+    d.setAttribute("aria-hidden", show ? "false" : "true");
+    d.tabIndex = show ? 0 : -1;
+    const word = model.states[sid]?.word ?? sid;
+    const lane = model.lanes.find(l => l.id === n.lane)?.title ?? n.lane;
+    d.setAttribute("aria-label", n.kind === "chip"
+      ? `${n.title}: a reference to the node in the ${lane} lane. Press Enter to select it.`
+      : `${n.title}. ${n.subtitle ?? model.columns[n.col ?? 0]?.title ?? ""}, ${word}. Press Enter to inspect.`);
+    if (fromSwitch && fresh && !ctx.reduced) {
+      d.style.transitionDelay = (n.col ?? 0) * 60 + "ms";
+      d.classList.add("pulse");
+      window.setTimeout(() => { d.style.transitionDelay = ""; d.classList.remove("pulse"); }, 2200);
+    } else {
+      d.style.transitionDelay = "";
+    }
+  }
+
+  ctx.links.forEach((l, i) => {
+    const p = ctx.edgeEls[i];
+    if (!p) return;
+    const edge = effectiveById.get(l.id);
+    const vis = !!edge;
+    const a = edge && ctx.geom.nodes[edge.from], b = edge && ctx.geom.nodes[edge.to];
+    const loop = edge?.kind === "loop-back";
+    if (a && b) {
+      p.dataset.a = edge!.from; p.dataset.b = edge!.to;
+      const channel = ctx.geom.loops[edge!.id]?.channelY ?? Math.max(a.y + a.h, b.y + b.h) + 10;
+      p.setAttribute("d", loop
+        ? loopRoute(ctx, edge!.from, edge!.to, a, b, channel)
+        : elbow(a.x + a.w, a.y + a.h / 2, b.x - 1, b.y + b.h / 2, a.x + a.w + DEFAULTS.gap / 2));
+      const lab = ctx.labelEls[i];
+      if (lab) {
+        lab.dataset.a = edge!.from; lab.dataset.b = edge!.to;
+        lab.style.left = (loop ? (a.x + a.w / 2 + b.x + b.w / 2) / 2 : Math.abs(b.y + b.h / 2 - a.y - a.h / 2) < 1 ? (a.x + a.w + b.x) / 2 : a.x + a.w + DEFAULTS.gap / 2) + "px";
+        lab.style.top = (loop ? channel : (a.y + a.h / 2 + b.y + b.h / 2) / 2) + "px";
+      }
+    }
+    p.setAttribute("class", "edge st-" + cssId(edge?.state ?? linkStateId(model, mode, l)) + (loop ? " loop" : "") + (vis ? "" : " off"));
+    ctx.labelEls[i]?.classList.toggle("off", !vis);
+  });
+
+  for (const l of model.lanes) {
+    const d = ctx.laneEls.get(l.id);
+    const r = ctx.geom.lanes[l.id];
+    if (!d) continue;
+    d.classList.toggle("off", !r);
+    if (r) { d.style.left = r.x + "px"; d.style.top = r.y + "px"; d.style.width = r.w + "px"; d.style.height = r.h + "px"; }
+  }
+
+  ctx.fn.buildChrome();
+  ctx.fn.trace(ctx.selected);
+  ctx.fn.renderInspector();
+  ctx.fn.stickLabels();
+  ctx.fn.placeHeaders();
+}
+
+export function install(ctx: Ctx): void {
+  ctx.fn.buildWorld = () => build(ctx);
+  ctx.fn.paint = (fromSwitch?: boolean) => paint(ctx, fromSwitch);
+}

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

@@ -0,0 +1,33 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { elbow, loopBack } from "./routing.ts";
+
+test("same height is a straight line", () => assert.equal(elbow(0, 50, 100, 50, 50), "M0,50 H100"));
+test("a small vertical step is a gentle S curve", () => assert.equal(elbow(0, 50, 100, 60, 50), "M0,50 C50,50 50,60 100,60"));
+test("a large step is an elbow with a trunk at tx and rounded corners", () => {
+  assert.equal(elbow(0, 50, 100, 150, 40), "M0,50 H32 Q40,50 40,58 V142 Q40,150 48,150 H100");
+});
+test("going up mirrors the corners", () => {
+  assert.equal(elbow(0, 150, 100, 50, 40), "M0,150 H32 Q40,150 40,142 V58 Q40,50 48,50 H100");
+});
+test("every number in a path is finite", () => assert.ok(!/NaN|Infinity/.test(elbow(0, 0, 10, 300, 5))));
+test("loop-back leaves and enters bottom edges for either horizontal direction", () => {
+  for (const [x1, x2] of [[100, 20], [20, 100], [20, 20]]) {
+    const p = loopBack(x1, 40, x2, 50, 90);
+    assert.match(p, new RegExp(`^M${x1},40\\b`));
+    assert.match(p, new RegExp(`50$`));
+    assert.ok(!/NaN|Infinity/.test(p));
+    assert.match(p, /Q/);
+  }
+});
+test("loop-back clamps its corner radius for short channels", () => {
+  const p = loopBack(10, 20, 10, 20, 23);
+  assert.ok(!/NaN|Infinity/.test(p));
+  assert.match(p, /^M10,20/);
+});
+test("a loop-back can detour around a node below its source", () => {
+  const path = loopBack(100, 50, 20, 50, 120, { from: { x: 60, y: 54 } });
+  assert.match(path, /^M100,50 V54 H60 V/);
+  assert.match(path, /V50$/);
+  assert.ok(!/NaN|Infinity/.test(path));
+});

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

@@ -0,0 +1,43 @@
+// Link routing. A link leaves the right side of a node, runs to a vertical trunk at tx (half way
+// across the column gap), and enters the left side of the next node. It is horizontal where it
+// touches a node, so every arrowhead points right and the links of one node share one trunk.
+
+export function elbow(x1: number, y1: number, x2: number, y2: number, tx: number): string {
+  const r = 8;
+  if (Math.abs(y2 - y1) < 1) return `M${x1},${y1} H${x2}`;
+  if (Math.abs(y2 - y1) < 2 * r + 2) return `M${x1},${y1} C${tx},${y1} ${tx},${y2} ${x2},${y2}`;
+  const dir = y2 > y1 ? 1 : -1;
+  return `M${x1},${y1} H${tx - r} Q${tx},${y1} ${tx},${y1 + dir * r} V${y2 - dir * r} Q${tx},${y2} ${tx + r},${y2} H${x2}`;
+}
+
+/** A return path leaves and enters the bottom of its nodes. The last segment points up. */
+export function loopBack(x1: number, y1: number, x2: number, y2: number, channelY: number,
+  detour: { from?: { x: number; y: number }; to?: { x: number; y: number } } = {}): string {
+  // Validated models supply finite positions. Guard the pure helper too so malformed input never
+  // produces a path containing NaN or Infinity.
+  x1 = Number.isFinite(x1) ? x1 : 0;
+  x2 = Number.isFinite(x2) ? x2 : 0;
+  y1 = Number.isFinite(y1) ? y1 : 0;
+  y2 = Number.isFinite(y2) ? y2 : 0;
+  channelY = Number.isFinite(channelY) ? channelY : Math.max(y1, y2) + 10;
+  channelY = Math.max(channelY, y1, y2);
+  const from = detour.from, to = detour.to;
+  const startX = from?.x ?? x1, endX = to?.x ?? x2;
+  const start = from ? `M${x1},${y1} V${from.y} H${startX}` : `M${x1},${y1}`;
+  const finish = to ? ` V${to.y} H${x2} V${y2}` : ` V${y2}`;
+  if (from || to) {
+    const dir = endX >= startX ? 1 : -1;
+    const r = Math.max(0, Math.min(8, Math.abs(endX - startX) / 2, (channelY - (from?.y ?? y1)) / 2, (channelY - (to?.y ?? y2)) / 2));
+    return `${start} V${channelY - r} Q${startX},${channelY} ${startX + dir * r},${channelY} H${endX - dir * r} Q${endX},${channelY} ${endX},${channelY - r}${finish}`;
+  }
+  const dx = x2 - x1;
+  const dir = dx >= 0 ? 1 : -1;
+  const run = Math.abs(dx) || 32;
+  const radius = Math.min(8, run / 2, (channelY - y1) / 2, (channelY - y2) / 2);
+  const r = Math.max(0, radius);
+  if (dx === 0) {
+    // Two gentle opposite turns give a finite return even for vertically aligned boxes.
+    return `M${x1},${y1} V${channelY - r} Q${x1},${channelY} ${x1 + r},${channelY} H${x1 + 16} H${x1 - r} Q${x1},${channelY} ${x1},${channelY - r} V${y2}`;
+  }
+  return `M${x1},${y1} V${channelY - r} Q${x1},${channelY} ${x1 + dir * r},${channelY} H${x2 - dir * r} Q${x2},${channelY} ${x2},${channelY - r} V${y2}`;
+}

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

@@ -0,0 +1,135 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { Model } from "./model.ts";
+import { baselineView, defaultView, nodeVisible, nodeStateId, linkVisible, linkStateId, isNew, isImproved, bucketOf, canonOf, effectiveLinks, initialCollapsed, columnTitle, toggleGroupState } from "./rules.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: 150 }],
+  lanes: [{ id: "l1", title: "L" }],
+  states: {
+    good: { word: "GOOD", tone: "ok", border: "solid", edge: "flow", motion: "flow", bucket: "good" },
+    gap: { word: "GAP", tone: "warn", border: "dotted", edge: "dot", motion: "breathe", bucket: "gap" },
+  },
+  views: [{ id: "today", label: "Today" }, { id: "full", label: "Full", default: true }],
+  nodes: [
+    { id: "a", kind: "card", lane: "l1", col: 0, row: 0, state: "good", title: "A" },
+    { id: "b", kind: "card", lane: "l1", col: 1, row: 0, state: "good", stateIn: { today: "gap" }, title: "B" },
+    { id: "c", kind: "card", lane: "l1", col: 1, row: 1.8, state: "good", visibleIn: ["full"], title: "C" },
+    { id: "k", kind: "chip", lane: "l1", col: 0, row: 3.6, state: "good", ref: "a", title: "k" },
+  ],
+  links: [
+    { id: "a-b", from: "a", to: "b", state: "good" },
+    { id: "a-c", from: "a", to: "c", state: "good", stateIn: { today: "gap" } },
+    { id: "only-today", from: "a", to: "b", state: "gap", visibleIn: ["today"] },
+  ],
+});
+const byId = (mm: Model) => new Map(mm.nodes.map(n => [n.id, n]));
+
+test("the baseline is the first view and the default is the marked one", () => {
+  assert.equal(baselineView(m()), "today");
+  assert.equal(defaultView(m()), "full");
+});
+test("a model with no views has one implicit view", () => {
+  const mm = m(); delete mm.views;
+  assert.equal(baselineView(mm), "all");
+  assert.equal(defaultView(mm), "all");
+  assert.equal(nodeVisible(mm, "all", mm.nodes[0]!), true);
+});
+test("visibleIn hides a node in other views", () => {
+  const mm = m();
+  assert.equal(nodeVisible(mm, "today", mm.nodes[2]!), false);
+  assert.equal(nodeVisible(mm, "full", mm.nodes[2]!), true);
+});
+test("stateIn overrides the state in that view only", () => {
+  const mm = m();
+  assert.equal(nodeStateId(mm, "today", mm.nodes[1]!), "gap");
+  assert.equal(nodeStateId(mm, "full", mm.nodes[1]!), "good");
+});
+test("a link is hidden when an end is hidden", () => {
+  const mm = m(), nodes = byId(mm);
+  assert.equal(linkVisible(mm, "today", mm.links[1]!, nodes), false);
+  assert.equal(linkVisible(mm, "full", mm.links[1]!, nodes), true);
+});
+test("visibleIn on a link restricts it to those views", () => {
+  const mm = m(), nodes = byId(mm);
+  assert.equal(linkVisible(mm, "today", mm.links[2]!, nodes), true);
+  assert.equal(linkVisible(mm, "full", mm.links[2]!, nodes), false);
+});
+test("a link state can differ per view", () => {
+  const mm = m();
+  assert.equal(linkStateId(mm, "today", mm.links[1]!), "gap");
+  assert.equal(linkStateId(mm, "full", mm.links[1]!), "good");
+});
+test("isNew: visible now, not in the baseline view", () => {
+  const mm = m();
+  assert.equal(isNew(mm, "full", mm.nodes[2]!), true);
+  assert.equal(isNew(mm, "today", mm.nodes[2]!), false);
+  assert.equal(isNew(mm, "full", mm.nodes[0]!), false);
+});
+test("isImproved: a gap in the baseline that is not a gap now", () => {
+  const mm = m();
+  assert.equal(isImproved(mm, "full", mm.nodes[1]!), true);
+  assert.equal(isImproved(mm, "today", mm.nodes[1]!), false);
+  assert.equal(isImproved(mm, "full", mm.nodes[0]!), false);
+});
+test("bucketOf reads the bucket of a state, and an unknown state is a gap (never a good)", () => {
+  const mm = m();
+  assert.equal(bucketOf(mm, "good"), "good");
+  assert.equal(bucketOf(mm, "nope"), "gap");
+});
+test("canonOf maps a chip to its real node and leaves others alone", () => {
+  const mm = m(), nodes = byId(mm);
+  assert.equal(canonOf(nodes, "k"), "a");
+  assert.equal(canonOf(nodes, "b"), "b");
+  assert.equal(canonOf(nodes, "missing"), "missing");
+});
+test("collapsed groups replace members and merge duplicate links with the worst state", () => {
+  const mm = m();
+  mm.nodes.push({ id: "group", kind: "group", lane: "l1", col: 0, row: 5, state: "good", title: "Group", contains: ["a", "b"] });
+  mm.links.push({ id: "b-c", from: "b", to: "c", state: "gap" });
+  mm.links.push({ id: "a-b", from: "a", to: "b", state: "good" });
+  const collapsed = new Set(["group"]), nodes = byId(mm);
+  assert.equal(nodeVisible(mm, "full", mm.nodes.find(n => n.id === "a")!, collapsed), false);
+  assert.equal(nodeVisible(mm, "full", mm.nodes.find(n => n.id === "group")!, collapsed), true);
+  const links = effectiveLinks(mm, "full", collapsed, nodes);
+  assert.equal(links.filter(l => l.from === "group" && l.to === "c").length, 1);
+  assert.equal(links.find(l => l.from === "group" && l.to === "c")?.state, "gap");
+  assert.ok(!links.some(l => l.from === l.to));
+  collapsed.clear();
+  assert.equal(nodeVisible(mm, "full", mm.nodes.find(n => n.id === "a")!, collapsed), true);
+  assert.equal(nodeVisible(mm, "full", mm.nodes.find(n => n.id === "group")!, collapsed), false);
+});
+
+test("groups with contains start collapsed unless collapsed is false", () => {
+  const mm = m();
+  mm.nodes.push({ id: "default", kind: "group", lane: "l1", state: "good", title: "Default", contains: ["a"] });
+  mm.nodes.push({ id: "expanded", kind: "group", lane: "l1", state: "good", title: "Expanded", contains: ["b"], collapsed: false });
+  const collapsed = initialCollapsed(mm);
+  assert.deepEqual([...collapsed], ["default"]);
+  assert.equal(nodeVisible(mm, "full", mm.nodes.find(n => n.id === "a")!, collapsed), false);
+  assert.equal(nodeVisible(mm, "full", mm.nodes.find(n => n.id === "b")!, collapsed), true);
+});
+test("a free node with no column has an empty table column", () => {
+  const mm = m(); mm.layout = "free";
+  delete mm.nodes[0]!.col;
+  assert.equal(columnTitle(mm, mm.nodes[0]!), "");
+  assert.equal(columnTitle(mm, mm.nodes[1]!), "B");
+});
+test("toggleGroup selects a visible child on expansion and its group on collapse", () => {
+  const mm = m();
+  mm.nodes.push({ id: "group", kind: "group", lane: "l1", state: "good", title: "Group", contains: ["a", "b"] });
+  const starting = new Set(["group"]);
+  const expanded = toggleGroupState(mm, "full", starting, "group")!;
+  assert.equal(expanded.expanding, true);
+  assert.equal(expanded.selected, "a");
+  assert.equal(expanded.collapsed.has("group"), false);
+  assert.equal(starting.has("group"), true);
+  const folded = toggleGroupState(mm, "full", expanded.collapsed, "group")!;
+  assert.equal(folded.expanding, false);
+  assert.equal(folded.selected, "group");
+  assert.equal(folded.collapsed.has("group"), true);
+  assert.equal(toggleGroupState(mm, "full", starting, "missing"), null);
+});