@caddis/cli 0.4.45 → 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

@@ -4,17 +4,36 @@
 import { el, sv, on, type Ctx } from "./ctx.ts";
 import { esc } from "./model.ts";
 import type { NodeDef } from "./model.ts";
-import { computeGeometry, DEFAULTS } from "./layout.ts";
-import { elbow } from "./routing.ts";
+import { computeGeometry, DEFAULTS, type Placed } from "./layout.ts";
+import { elbow, loopBack } from "./routing.ts";
 import { cssId } from "./stateCss.ts";
-import { baselineView, bucketOf, canonOf, isImproved, isNew, linkStateId, linkVisible, nodeStateId, nodeVisible } from "./rules.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]?.title ?? "";
+  const sub = n.subtitle ?? m.columns[n.col ?? 0]?.title ?? "";
   const weight = Math.max(1, n.weight ?? 1);
   const showWord = n.kind !== "placeholder" && n.kind !== "note";
   const bar = weight > 1 && n.kind !== "chip"
@@ -24,8 +43,9 @@ function nodeHtml(ctx: Ctx, n: NodeDef): string {
   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> · ` : "";
-  return `<div class="t"><span class="newdot" title="Added in this view"></span><span class="name">${arrow}${esc(n.title)}</span></div>`
-    + `<div class="s" title="${esc(sub)}">${lead}${esc(sub)}</div>${bar}${improved}${upgrade}`;
+  const fold = n.kind === "group" && n.contains?.length ? `<span class="fold">▸ ${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 {
@@ -59,7 +79,7 @@ function build(ctx: Ctx): void {
     d.id = "n_" + n.id;
     d.tabIndex = 0;
     d.setAttribute("role", "button");
-    d.style.setProperty("--c", String(n.col));
+    d.style.setProperty("--c", String(n.col ?? 0));
     d.style.left = p.x + "px"; d.style.top = p.y + "px"; d.style.width = p.w + "px"; 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(); });
@@ -77,14 +97,19 @@ function build(ctx: Ctx): void {
     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 path = sv("path", { d: elbow(x1, y1, x2 - 1, y2, tx), class: "edge", "data-i": String(i), "data-a": l.from, "data-b": l.to, "marker-end": "url(#arr)" }) as SVGPathElement;
+    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 = (Math.abs(y2 - y1) < 1 ? (x1 + x2) / 2 : tx) + "px";
-      lab.style.top = (y1 + y2) / 2 + "px";
+      lab.style.left = (loop ? (A.x + A.w / 2 + B.x + B.w / 2) / 2 : Math.abs(y2 - y1) < 1 ? (x1 + x2) / 2 : tx) + "px";
+      lab.style.top = (loop ? ctx.geom.loops[l.id]?.channelY ?? Math.max(A.y + A.h, B.y + B.h) + 10 : (y1 + y2) / 2) + "px";
       els.world.appendChild(lab);
       ctx.labelEls[i] = lab;
     }
@@ -94,21 +119,28 @@ function build(ctx: Ctx): void {
 function paint(ctx: Ctx, fromSwitch = false): void {
   const { model } = ctx;
   const mode = ctx.mode;
-  ctx.geom = computeGeometry(model, { visible: id => { const n = ctx.nodes.get(id); return !!n && nodeVisible(model, mode, n); } });
+  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);
+    const show = nodeVisible(model, mode, n, ctx.collapsed);
     const bucket = bucketOf(model, sid);
     const cors = (isImproved(model, mode, n) ? 1 : 0) + (n.upgrade && bucket !== "good" ? 1 : 0);
     const fresh = isNew(model, mode, n);
     d.className = "node st-" + cssId(sid)
-      + (n.kind === "chip" ? " ref" : "") + ((n.colSpan ?? 1) > 1 ? " wide" : "") + (n.kind === "placeholder" ? " placeholder" : "")
+      + (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" : "");
+      + (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;
@@ -116,9 +148,9 @@ function paint(ctx: Ctx, fromSwitch = false): void {
     const lane = model.lanes.find(l => l.id === n.lane)?.title ?? n.lane;
     d.setAttribute("aria-label", n.kind === "chip"
       ? `${n.title}: a reference to the node in the ${lane} lane. Press Enter to select it.`
-      : `${n.title}. ${n.subtitle ?? model.columns[n.col]?.title ?? ""}, ${word}. Press Enter to inspect.`);
+      : `${n.title}. ${n.subtitle ?? model.columns[n.col ?? 0]?.title ?? ""}, ${word}. Press Enter to inspect.`);
     if (fromSwitch && fresh && !ctx.reduced) {
-      d.style.transitionDelay = n.col * 60 + "ms";
+      d.style.transitionDelay = (n.col ?? 0) * 60 + "ms";
       d.classList.add("pulse");
       window.setTimeout(() => { d.style.transitionDelay = ""; d.classList.remove("pulse"); }, 2200);
     } else {
@@ -129,8 +161,24 @@ function paint(ctx: Ctx, fromSwitch = false): void {
   ctx.links.forEach((l, i) => {
     const p = ctx.edgeEls[i];
     if (!p) return;
-    const vis = linkVisible(model, mode, l, ctx.nodes);
-    p.setAttribute("class", "edge st-" + cssId(linkStateId(model, mode, l)) + (vis ? "" : " off"));
+    const edge = effectiveById.get(l.id);
+    const vis = !!edge;
+    const a = edge && ctx.geom.nodes[edge.from], b = edge && ctx.geom.nodes[edge.to];
+    const loop = edge?.kind === "loop-back";
+    if (a && b) {
+      p.dataset.a = edge!.from; p.dataset.b = edge!.to;
+      const channel = ctx.geom.loops[edge!.id]?.channelY ?? Math.max(a.y + a.h, b.y + b.h) + 10;
+      p.setAttribute("d", loop
+        ? loopRoute(ctx, edge!.from, edge!.to, a, b, channel)
+        : elbow(a.x + a.w, a.y + a.h / 2, b.x - 1, b.y + b.h / 2, a.x + a.w + DEFAULTS.gap / 2));
+      const lab = ctx.labelEls[i];
+      if (lab) {
+        lab.dataset.a = edge!.from; lab.dataset.b = edge!.to;
+        lab.style.left = (loop ? (a.x + a.w / 2 + b.x + b.w / 2) / 2 : Math.abs(b.y + b.h / 2 - a.y - a.h / 2) < 1 ? (a.x + a.w + b.x) / 2 : a.x + a.w + DEFAULTS.gap / 2) + "px";
+        lab.style.top = (loop ? channel : (a.y + a.h / 2 + b.y + b.h / 2) / 2) + "px";
+      }
+    }
+    p.setAttribute("class", "edge st-" + cssId(edge?.state ?? linkStateId(model, mode, l)) + (loop ? " loop" : "") + (vis ? "" : " off"));
     ctx.labelEls[i]?.classList.toggle("off", !vis);
   });
 

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

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { elbow } from "./routing.ts";
+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"));
@@ -11,3 +11,23 @@ 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

@@ -9,3 +9,35 @@ export function elbow(x1: number, y1: number, x2: number, y2: number, tx: number
   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

@@ -1,7 +1,7 @@
 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 } from "./rules.ts";
+import { baselineView, defaultView, nodeVisible, nodeStateId, linkVisible, linkStateId, isNew, isImproved, bucketOf, canonOf, effectiveLinks, initialCollapsed, columnTitle, toggleGroupState } from "./rules.ts";
 
 const m = (): Model => ({
   version: 1,
@@ -86,3 +86,50 @@ test("canonOf maps a chip to its real node and leaves others alone", () => {
   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);
+});

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

@@ -7,7 +7,35 @@ import type { Model, NodeDef, LinkDef, Bucket } from "./model.ts";
 export const baselineView = (m: Model): string => m.views?.[0]?.id ?? "all";
 export const defaultView = (m: Model): string => (m.views?.find(v => v.default) ?? m.views?.[0])?.id ?? "all";
 
-export const nodeVisible = (_m: Model, view: string, n: NodeDef): boolean => !n.visibleIn || n.visibleIn.includes(view);
+/** A group that contains nodes starts folded unless it explicitly opts out. */
+export const initialCollapsed = (m: Model): Set<string> => new Set(m.nodes
+  .filter(n => n.kind === "group" && n.contains && n.collapsed !== false).map(n => n.id));
+export const columnTitle = (m: Model, n: NodeDef): string => n.col === undefined ? "" : m.columns[n.col]?.title ?? "";
+
+export function groupFor(m: Model, nodeId: string): NodeDef | undefined {
+  return m.nodes.find(n => n.kind === "group" && n.contains?.includes(nodeId));
+}
+
+export const nodeVisible = (m: Model, view: string, n: NodeDef, collapsed?: Set<string>): boolean => {
+  if (n.visibleIn && !n.visibleIn.includes(view)) return false;
+  if (!collapsed) return true;
+  if (n.kind === "group" && n.contains) return collapsed.has(n.id);
+  const owner = groupFor(m, n.id);
+  return !owner || !collapsed.has(owner.id);
+};
+export function toggleGroupState(m: Model, view: string, collapsed: Set<string>, id: string):
+  { collapsed: Set<string>; selected: string | null; expanding: boolean } | null {
+  const group = m.nodes.find(n => n.id === id && n.kind === "group" && n.contains?.length);
+  if (!group) return null;
+  const next = new Set(collapsed);
+  const expanding = next.has(id);
+  if (expanding) next.delete(id); else next.add(id);
+  const selected = expanding ? group.contains?.find(child => {
+    const n = m.nodes.find(candidate => candidate.id === child);
+    return !!n && nodeVisible(m, view, n, next);
+  }) ?? null : id;
+  return { collapsed: next, selected, expanding };
+}
 export const nodeStateId = (_m: Model, view: string, n: NodeDef): string => n.stateIn?.[view] ?? n.state;
 
 export function linkVisible(m: Model, view: string, l: LinkDef, nodes: Map<string, NodeDef>): boolean {
@@ -33,3 +61,26 @@ export const isImproved = (m: Model, view: string, n: NodeDef): boolean => {
 
 /** A portal chip is an alias of the node it points at. */
 export const canonOf = (nodes: Map<string, NodeDef>, id: string): string => nodes.get(id)?.ref ?? id;
+
+/** Map hidden members to their visible group and merge parallel effective links. */
+export function effectiveLinks(m: Model, view: string, collapsed: Set<string>, nodes: Map<string, NodeDef>): LinkDef[] {
+  const byPair = new Map<string, LinkDef>();
+  const rank = { good: 0, neutral: 1, gap: 2 };
+  for (const link of m.links) {
+    if (link.visibleIn && !link.visibleIn.includes(view)) continue;
+    const a = nodes.get(link.from), b = nodes.get(link.to);
+    if (!a || !b || (a.visibleIn && !a.visibleIn.includes(view)) || (b.visibleIn && !b.visibleIn.includes(view))) continue;
+    const groupA = groupFor(m, a.id), groupB = groupFor(m, b.id);
+    const from = groupA && collapsed.has(groupA.id) ? groupA.id : a.id;
+    const to = groupB && collapsed.has(groupB.id) ? groupB.id : b.id;
+    if (from === to) continue;
+    const fromNode = nodes.get(from), toNode = nodes.get(to);
+    if (!fromNode || !toNode || !nodeVisible(m, view, fromNode, collapsed) || !nodeVisible(m, view, toNode, collapsed)) continue;
+    const state = linkStateId(m, view, link);
+    const key = JSON.stringify([from, to]);
+    const prev = byPair.get(key);
+    if (!prev) byPair.set(key, { ...link, from, to, state, stateIn: undefined });
+    else if (rank[bucketOf(m, state)] > rank[bucketOf(m, prev.state)]) prev.state = state;
+  }
+  return [...byPair.values()];
+}

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

@@ -0,0 +1,12 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { notifySelection } from "./selection.ts";
+
+test("selection callback reports changes and clears once", () => {
+  const seen: Array<string | null> = [];
+  const notify = (id: string | null) => seen.push(id);
+  notifySelection(null, "a", notify);
+  notifySelection("a", "a", notify);
+  notifySelection("a", null, notify);
+  assert.deepEqual(seen, ["a", null]);
+});

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

@@ -0,0 +1,4 @@
+/** Report only a real selection change. */
+export function notifySelection(previous: string | null, next: string | null, onSelect?: (id: string | null) => void): void {
+  if (previous !== next) onSelect?.(next);
+}

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

@@ -21,6 +21,13 @@ test("each state gets a node rule, a word rule and an edge rule", () => {
     assert.ok(css.includes(`path.edge.st-${id}`), `edge ${id}`);
   }
 });
+test("gateway polygons receive each state's stroke and tint", () => {
+  const css = stateCss(states);
+  for (const id of Object.keys(states)) {
+    assert.match(css, new RegExp(`\\.node\\.st-${id}\\.gateway polygon \\{[^}]*stroke:var\\(--`));
+    assert.match(css, new RegExp(`\\.node\\.st-${id}\\.gateway polygon \\{[^}]*fill:color-mix\\(`));
+  }
+});
 test("a dotted state is a tinted card with a dotted border", () => {
   const css = stateCss(states);
   assert.match(css, /\.node\.st-gap\s*\{[^}]*dotted/);

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

@@ -26,6 +26,7 @@ export function stateCss(states: Model["states"]): string {
       const glow = s.bucket === "good" ? ` box-shadow:0 0 14px -4px color-mix(in srgb, ${T} 55%, transparent), var(--shadow);` : "";
       out.push(`.node.st-${c} { border-left:4px ${s.border} ${T};${glow} --breath:${T}; }`);
     }
+    out.push(`.node.st-${c}.gateway polygon { stroke:${T}; fill:color-mix(in srgb, ${T} 10%, var(--panel)); }`);
     out.push(`.ev.st-${c} { color:${T}; }`);
     if (s.motion === "breathe") out.push(`.node.st-${c}:not(.dim) { animation:breathe 3.2s ease-in-out infinite; }`);