@caddis/cli 0.4.45 → 0.4.47

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

@@ -4,16 +4,18 @@
 // Run it from a folder that can resolve "playwright" (the project's node_modules). Exit 0: every check passed.
 
 import { createRequire } from "node:module";
+import { isDeepStrictEqual } from "node:util";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { resolve, join } from "node:path";
-import { pathToFileURL } from "node:url";
+import { pageUrl, skippedGroups } from "./lib/check-args.mjs";
 
 const argv = process.argv.slice(2);
 const opt = (name, dflt) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : dflt; };
 const flag = name => argv.includes(name);
 const pageArg = argv[0];
-if (!pageArg || pageArg.startsWith("--")) { console.error("usage: node scripts/check.mjs <page.html> [--out dir] [--viewports WxH,...] [--channel msedge] [--hostile page.html] [--json file] [--skip-perf]"); process.exit(2); }
-const pagePath = resolve(pageArg ?? "");
+if (!pageArg || pageArg.startsWith("--")) { console.error("usage: node scripts/check.mjs <page.html|URL> [--out dir] [--viewports WxH,...] [--channel msedge] [--hostile page.html|URL] [--json file] [--skip-perf] [--skip notes,playback,update,hostile]"); process.exit(2); }
+let skip;
+try { skip = skippedGroups(opt("--skip", "")); } catch (error) { console.error(error.message); process.exit(2); }
 const outDir = resolve(opt("--out", "check-out"));
 const viewports = opt("--viewports", "1600x900,1280x720,820x900").split(",").map(v => v.split("x").map(Number));
 const channel = opt("--channel", undefined);
@@ -21,8 +23,10 @@ const hostilePath = opt("--hostile", undefined);
 mkdirSync(outDir, { recursive: true });
 
 let chromium;
-try { ({ chromium } = createRequire(join(process.cwd(), "x.js"))("playwright")); }
-catch { console.error("Cannot resolve 'playwright'. Run this from a folder whose node_modules has it (npm i -D playwright)."); process.exit(2); }
+for (const base of [process.cwd(), process.env.FLOW_STUDIO_NODE_MODULES && resolve(process.env.FLOW_STUDIO_NODE_MODULES, "..")].filter(Boolean)) {
+  try { ({ chromium } = createRequire(join(base, "x.js"))("playwright")); break; } catch { /* try next location */ }
+}
+if (!chromium) { console.error("Cannot resolve 'playwright'. Run this from a folder whose node_modules has it (npm i -D playwright)."); process.exit(2); }
 
 const results = [];
 const check = (group, name, ok, detail = "") => { results.push({ group, name, ok: !!ok, detail: String(detail) }); console.log(`${ok ? "PASS" : "FAIL"}  [${group}] ${name}${detail ? "  " + detail : ""}`); };
@@ -34,21 +38,28 @@ const inPage = {
     return { view: f.view(), selected: f.selected(), mode: f.mode() };
   },
 };
-const url = p => pathToFileURL(p).href;
+const url = pageUrl;
+const targetUrl = url(pageArg);
+const localOrigin = new URL(targetUrl).protocol.startsWith("http") ? new URL(targetUrl).origin : null;
 
 // ---- model-side helpers (run here, from the model the page reports)
 function modelRules(model) {
   const view = (model.views?.find(v => v.default) ?? model.views?.[0])?.id ?? "all";
   const nodes = new Map(model.nodes.map(n => [n.id, n]));
   const canon = id => nodes.get(id)?.ref ?? id;
-  const nv = (n, v = view) => !n.visibleIn || n.visibleIn.includes(v);
-  const lv = (l, v = view) => (!l.visibleIn || l.visibleIn.includes(v)) && nodes.get(l.from) && nodes.get(l.to) && nv(nodes.get(l.from), v) && nv(nodes.get(l.to), v);
+  const collapsed = new Set(model.nodes.filter(n => n.kind === "group" && n.contains?.length && n.collapsed !== false).map(n => n.id));
+  const owner = id => model.nodes.find(n => n.kind === "group" && n.contains?.includes(id));
+  const nv = (n, v = view) => !!n && (!n.visibleIn || n.visibleIn.includes(v))
+    && (n.kind === "group" && n.contains ? collapsed.has(n.id) : !collapsed.has(owner(n.id)?.id));
+  const endpoint = id => collapsed.has(owner(id)?.id) ? owner(id).id : id;
+  const lv = (l, v = view) => (!l.visibleIn || l.visibleIn.includes(v)) && nodes.get(l.from) && nodes.get(l.to)
+    && nv(nodes.get(endpoint(l.from)), v) && nv(nodes.get(endpoint(l.to)), v) && endpoint(l.from) !== endpoint(l.to);
   const down = (start, v = view) => {
     const s = new Set([canon(start)]); let grew = true;
-    while (grew) { grew = false; for (const l of model.links) { if (!lv(l, v)) continue; const a = canon(l.from), b = canon(l.to); if (s.has(a) && !s.has(b)) { s.add(b); grew = true; } } }
+    while (grew) { grew = false; for (const l of model.links) { if (!lv(l, v)) continue; const a = canon(endpoint(l.from)), b = canon(endpoint(l.to)); if (s.has(a) && !s.has(b)) { s.add(b); grew = true; } } }
     return s;
   };
-  return { view, nodes, canon, nv, lv, down };
+  return { view, nodes, canon, nv, lv, down, collapsed, endpoint };
 }
 
 const browser = await chromium.launch(channel ? { channel } : {});
@@ -61,12 +72,17 @@ for (const [w, h] of viewports) {
   const errors = [], requests = [];
   page.on("pageerror", e => errors.push(String(e)));
   page.on("console", m => { if (m.type() === "error") errors.push(m.text()); });
-  page.on("request", r => { const u = r.url(); if (!u.startsWith("file:") && !u.startsWith("data:")) requests.push(u); });
-  await page.goto(url(pagePath));
+  page.on("request", r => { const u = r.url(); if (!u.startsWith("file:") && !u.startsWith("data:") && (!localOrigin || new URL(u).origin !== localOrigin)) requests.push(u); });
+  await page.goto(targetUrl);
   await page.waitForFunction(() => !!window.FlowStudio, null, { timeout: 10000 });
   await page.waitForTimeout(900);
   const model = await page.evaluate(() => window.FlowStudio.model);
   const R = modelRules(model);
+  const paintedHidden = await page.evaluate(() => [...document.querySelectorAll(".node.off")].filter(d => {
+    const style = getComputedStyle(d);
+    return style.visibility !== "hidden" && Number(style.opacity) > 0;
+  }).map(d => d.id.slice(2)));
+  check("structural", `${tag} hidden nodes are not painted`, paintedHidden.length === 0, paintedHidden.join(","));
   await page.screenshot({ path: join(outDir, `01-fit-${tag}.png`) });
 
   check("safety", `${tag} no page errors`, errors.length === 0, errors.join(" | "));
@@ -101,14 +117,53 @@ for (const [w, h] of viewports) {
     document.querySelectorAll("path.edge:not(.off)").forEach(p => {
       const a = g.nodes[p.dataset.a], b = g.nodes[p.dataset.b], len = p.getTotalLength();
       const s = p.getPointAtLength(0), e = p.getPointAtLength(len);
-      const okA = a && Math.abs(s.x - (a.x + a.w)) <= 2 && s.y >= a.y - 2 && s.y <= a.y + a.h + 2;
-      const okB = b && Math.abs(e.x - (b.x - 1)) <= 2 && e.y >= b.y - 2 && e.y <= b.y + b.h + 2;
+      const loop = p.classList.contains("loop");
+      const okA = loop
+        ? a && Math.abs(s.x - (a.x + a.w / 2)) <= 2 && Math.abs(s.y - (a.y + a.h)) <= 2
+        : a && Math.abs(s.x - (a.x + a.w)) <= 2 && s.y >= a.y - 2 && s.y <= a.y + a.h + 2;
+      const okB = loop
+        ? b && Math.abs(e.x - (b.x + b.w / 2)) <= 2 && Math.abs(e.y - (b.y + b.h)) <= 2
+        : b && Math.abs(e.x - (b.x - 1)) <= 2 && e.y >= b.y - 2 && e.y <= b.y + b.h + 2;
       if (!okA || !okB) bad.push(p.dataset.a + ">" + p.dataset.b);
     });
     return bad;
   });
   check("structural", `${tag} every link end touches its node box (within 2 px)`, ends.length === 0, ends.join(","));
 
+  const crossedLoops = await page.evaluate(() => {
+    const boxes = [...document.querySelectorAll(".node:not(.off)")].map(d => ({
+      id: d.id.slice(2), x: parseFloat(d.style.left), y: parseFloat(d.style.top),
+      w: parseFloat(d.style.width), h: parseFloat(d.style.height),
+    }));
+    const bad = [];
+    document.querySelectorAll("path.edge.loop:not(.off)").forEach(path => {
+      const len = path.getTotalLength();
+      if (!Number.isFinite(len)) { bad.push(`${path.dataset.a}>${path.dataset.b}:nonfinite`); return; }
+      for (const box of boxes) {
+        if (box.id === path.dataset.a || box.id === path.dataset.b) continue;
+        let crossed = false;
+        for (let distance = 0; distance <= len; distance += 2) {
+          const point = path.getPointAtLength(distance);
+          if (point.x > box.x && point.x < box.x + box.w && point.y > box.y && point.y < box.y + box.h) { crossed = true; break; }
+        }
+        if (crossed) bad.push(`${path.dataset.a}>${path.dataset.b}/${box.id}`);
+      }
+    });
+    return bad;
+  });
+  check("structural", `${tag} no loop-back path passes through a visible node`, crossedLoops.length === 0, crossedLoops.join(","));
+
+  const gateways = geo.nodes.filter(n => R.nodes.get(n.id)?.kind === "gateway");
+  if (gateways.length) {
+    const missingPolygons = await page.evaluate(ids => ids.filter(id => !document.getElementById("n_" + id)?.querySelector("svg.gw polygon")), gateways.map(g => g.id));
+    check("structural", `${tag} every visible gateway has a polygon`, missingPolygons.length === 0, missingPolygons.join(","));
+    const missingExitLabels = await page.evaluate(exits => exits.filter(({ i, label }) => {
+      const el = document.querySelector(`.elabel[data-i="${i}"]:not(.off)`);
+      return !label || !el || el.textContent !== label;
+    }).map(({ id }) => id), model.links.map((l, i) => ({ ...l, i })).filter(l => gateways.some(g => g.id === l.from) && R.lv(l)));
+    check("structural", `${tag} every visible gateway exit has a label`, missingExitLabels.length === 0, missingExitLabels.join(","));
+  }
+
   const spill = await page.evaluate(() => {
     const bad = [];
     document.querySelectorAll(".node:not(.off):not(.wide)").forEach(d => {
@@ -121,6 +176,24 @@ for (const [w, h] of viewports) {
     return bad;
   });
   check("structural", `${tag} no text spills out of a card`, spill.length === 0, spill.join(","));
+  const metricProbe = await page.evaluate(() => {
+    const visible = [...document.querySelectorAll(".node:not(.off)")];
+    const badges = visible.flatMap(n => [...n.querySelectorAll(".metric-badge")]);
+    return {
+      badges: badges.length,
+      sparks: visible.reduce((count, n) => count + n.querySelectorAll(".spark").length, 0),
+      overlap: badges.some(b => {
+        const name = b.closest(".node")?.querySelector(".name");
+        if (!name) return false;
+        const a = name.getBoundingClientRect(), c = b.getBoundingClientRect();
+        return a.left < c.right - 1 && c.left < a.right - 1 && a.top < c.bottom - 1 && c.top < a.bottom - 1;
+      }),
+    };
+  });
+  const visibleNodes = geo.nodes.map(n => R.nodes.get(n.id)).filter(Boolean);
+  const metricCount = visibleNodes.filter(n => n.metrics).length;
+  check("structural", `${tag} metric badges show without title overlap`, metricProbe.badges === metricCount && !metricProbe.overlap);
+  check("structural", `${tag} metric series show a sparkline`, metricProbe.sparks === visibleNodes.filter(n => (n.metrics?.series?.length ?? 0) >= 2).length);
 
   const visibleGroups = geo.nodes.length;
   const st0 = await page.evaluate(inPage.state);
@@ -154,6 +227,43 @@ for (const [w, h] of viewports) {
   const expectRows = model.nodes.filter(n => R.nv(n) && n.kind !== "chip").length;
   check("a11y", `${tag} table view lists exactly the visible groups`, tableRows === expectRows, `rows=${tableRows} expected=${expectRows}`);
 
+  const fold = model.nodes.find(n => n.kind === "group" && n.contains?.length);
+  if (fold) {
+    const count = () => page.evaluate(() => document.querySelectorAll(".node:not(.off)").length);
+    const touchErrors = () => page.evaluate(() => {
+      const g = window.FlowStudio.geometry(), bad = [];
+      document.querySelectorAll("path.edge:not(.off)").forEach(p => {
+        const a = g.nodes[p.dataset.a], b = g.nodes[p.dataset.b], len = p.getTotalLength();
+        const s = p.getPointAtLength(0), e = p.getPointAtLength(len), loop = p.classList.contains("loop");
+        const okA = loop ? a && Math.abs(s.x - a.x - a.w / 2) <= 2 && Math.abs(s.y - a.y - a.h) <= 2
+          : a && Math.abs(s.x - a.x - a.w) <= 2 && s.y >= a.y - 2 && s.y <= a.y + a.h + 2;
+        const okB = loop ? b && Math.abs(e.x - b.x - b.w / 2) <= 2 && Math.abs(e.y - b.y - b.h) <= 2
+          : b && Math.abs(e.x - b.x + 1) <= 2 && e.y >= b.y - 2 && e.y <= b.y + b.h + 2;
+        if (!okA || !okB) bad.push(p.dataset.a + ">" + p.dataset.b);
+      });
+      return bad;
+    });
+    const initial = await count();
+    if (R.collapsed.has(fold.id)) {
+      await page.evaluate(id => window.FlowStudio.select(id), fold.id);
+      await page.locator('#inspector [data-toggle-group]').click();
+      check("interaction", `${tag} expanding a group changes visible nodes by contained minus one`, (await count()) - initial === fold.contains.length - 1);
+      check("structural", `${tag} expanded links touch their node boxes`, (await touchErrors()).length === 0);
+      await page.locator('#inspector [data-toggle-group]').click();
+      check("interaction", `${tag} collapsing restores visible nodes`, (await count()) === initial);
+      check("structural", `${tag} collapsed links touch their node boxes`, (await touchErrors()).length === 0);
+    } else {
+      await page.evaluate(id => window.FlowStudio.select(id), fold.contains[0]);
+      await page.locator('#inspector [data-toggle-group]').click();
+      check("interaction", `${tag} collapsing a group changes visible nodes by contained minus one`, initial - (await count()) === fold.contains.length - 1);
+      check("structural", `${tag} collapsed links touch their node boxes`, (await touchErrors()).length === 0);
+      await page.locator('#inspector [data-toggle-group]').click();
+      check("interaction", `${tag} expanding restores visible nodes`, (await count()) === initial);
+      check("structural", `${tag} expanded links touch their node boxes`, (await touchErrors()).length === 0);
+    }
+    await page.keyboard.press("Escape");
+  }
+
   if (w !== 1600) { await ctx.close(); continue; }
 
   // ---------- interaction (1600x900 only)
@@ -186,15 +296,29 @@ for (const [w, h] of viewports) {
   check("interaction", "Ctrl+key combinations do not move the canvas", kBefore.k === kAfter.k && kBefore.x === kAfter.x);
   await page.keyboard.press("1"); await page.waitForTimeout(450);
   const p0 = (await page.evaluate(inPage.state)).view;
-  await page.mouse.move(vp.x + 900, vp.y + 600); await page.mouse.down(); await page.mouse.move(vp.x + 700, vp.y + 520, { steps: 6 }); await page.mouse.up();
+  const dragStart = await page.evaluate(() => {
+    const viewport = document.getElementById("viewport");
+    const r = viewport.getBoundingClientRect();
+    for (const fy of [0.85, 0.7, 0.55, 0.4, 0.25, 0.1]) for (const fx of [0.85, 0.7, 0.55, 0.4, 0.25, 0.1]) {
+      const x = r.left + r.width * fx, y = r.top + r.height * fy;
+      const el = document.elementFromPoint(x, y);
+      if (el && viewport.contains(el) && !el.closest(".node, .bandlabel, .elabel, #tools, #zoomLabel")) return { x, y };
+    }
+    return null;
+  });
+  check("interaction", "an empty canvas point is available for background drag", !!dragStart);
+  const start = dragStart ?? { x: vp.x + vp.width / 2, y: vp.y + vp.height / 2 };
+  const dx = start.x > vp.x + vp.width / 2 ? -200 : 200;
+  const dy = start.y > vp.y + vp.height / 2 ? -80 : 80;
+  await page.mouse.move(start.x, start.y); await page.mouse.down(); await page.mouse.move(start.x + dx, start.y + dy, { steps: 6 }); await page.mouse.up();
   const p1 = (await page.evaluate(inPage.state)).view;
   check("interaction", "dragging the background pans", Math.abs(p1.x - p0.x) > 100, `${p0.x.toFixed(0)} -> ${p1.x.toFixed(0)}`);
   await page.keyboard.press("0"); await page.waitForTimeout(450);
 
   // choose a card with the most links
   const deg = new Map();
-  for (const l of model.links) if (R.lv(l)) { deg.set(R.canon(l.from), (deg.get(R.canon(l.from)) ?? 0) + 1); deg.set(R.canon(l.to), (deg.get(R.canon(l.to)) ?? 0) + 1); }
-  const pick = [...deg.entries()].filter(([id]) => R.nodes.get(id)?.kind !== "chip" && !((R.nodes.get(id)?.colSpan ?? 1) > 1)).sort((a, b) => b[1] - a[1])[0]?.[0];
+  for (const l of model.links) if (R.lv(l)) { deg.set(R.canon(R.endpoint(l.from)), (deg.get(R.canon(R.endpoint(l.from))) ?? 0) + 1); deg.set(R.canon(R.endpoint(l.to)), (deg.get(R.canon(R.endpoint(l.to))) ?? 0) + 1); }
+  const pick = [...deg.entries()].filter(([id]) => R.nv(R.nodes.get(id)) && R.nodes.get(id)?.kind !== "chip" && !((R.nodes.get(id)?.colSpan ?? 1) > 1)).sort((a, b) => b[1] - a[1])[0]?.[0];
   check("interaction", "the model has a selectable card with links", !!pick, pick ?? "none");
   if (pick) {
     await page.keyboard.press("h");
@@ -244,11 +368,18 @@ for (const [w, h] of viewports) {
   }
 
   // search
-  const probe = model.nodes.find(n => n.members?.length && R.nv(n));
+  const probe = model.nodes.find(n => R.nv(n) && (n.members?.some(Boolean) || n.title));
   if (probe) {
-    const term = probe.members[0].slice(0, 6).toLowerCase();
+    const term = (probe.members?.find(Boolean) ?? probe.title).slice(0, 6).toLowerCase();
     await page.fill("#q", term); await page.waitForTimeout(250);
     check("interaction", "search dims the groups that do not match", await page.evaluate(() => document.querySelectorAll(".node.dim").length > 0));
+    const dim0 = await page.evaluate(() => document.querySelectorAll(".node:not(.off).dim").length);
+    const matched = new Set(model.nodes.filter(n => R.nv(n) && (n.title.toLowerCase().includes(term) || (n.members ?? []).some(m => m.toLowerCase().includes(term)))).map(n => n.id));
+    const hasNeighbours = model.links.some(l => R.lv(l) && (matched.has(R.endpoint(l.from)) !== matched.has(R.endpoint(l.to))));
+    await page.selectOption("#hops", "1"); await page.waitForTimeout(100);
+    const dim1 = await page.evaluate(() => document.querySelectorAll(".node:not(.off).dim").length);
+    check("interaction", "search radius +1 lights neighbouring groups", dim1 < dim0 || (dim1 === dim0 && !hasNeighbours), `hops0=${dim0} hops1=${dim1} neighbours=${hasNeighbours}`);
+    await page.selectOption("#hops", "0");
     await page.fill("#q", ""); await page.keyboard.press("Escape");
   }
 
@@ -264,11 +395,43 @@ for (const [w, h] of viewports) {
   }
 
   // notes
-  await page.keyboard.press("n"); await page.waitForTimeout(500);
-  const markers = await page.locator(".marker").count();
-  check("interaction", "notes mode shows numbered markers", (model.notes?.length ?? 0) === 0 || markers > 0, `markers=${markers}`);
-  await page.screenshot({ path: join(outDir, "06-notes.png") });
-  await page.keyboard.press("n");
+  if (!skip.has("notes")) {
+    await page.keyboard.press("n"); await page.waitForTimeout(500);
+    const markers = await page.locator(".marker").count();
+    check("interaction", "notes mode shows numbered markers", (model.notes?.length ?? 0) === 0 || markers > 0, `markers=${markers}`);
+    const flowNotes = await page.evaluate(() => {
+      try { return JSON.parse(document.getElementById("flow-notes")?.textContent || "[]"); }
+      catch { return []; }
+    });
+    const isDemoPack = Array.isArray(flowNotes) && flowNotes.some(n => n.title === "Page frame" && n.anchor === "#title");
+    if (isDemoPack) {
+      // Per note, not by total: a note whose anchor resolves to a visible element must have a
+      // marker; one whose anchor matches nothing (or is hidden) legitimately has none. This mirrors
+      // the placement rules in src/notes.ts.
+      const markerless = await page.evaluate(notes => {
+        const have = new Set([...document.querySelectorAll(".marker")].map(m => m.dataset.n));
+        return notes.filter(n => {
+          let a = null; try { a = document.querySelector(n.anchor); } catch { return false; }
+          if (!a) return false;
+          let r = a.getBoundingClientRect();
+          if (!r.width && !r.height) {
+            let d = a.closest("details");
+            while (d && d.open) d = d.parentElement?.closest("details") ?? null;
+            if (d) r = d.getBoundingClientRect();
+          }
+          if (!r.width && !r.height) return false;
+          if (a.closest("#world")) {
+            const v = document.getElementById("viewport").getBoundingClientRect();
+            if (r.right < v.left || r.left > v.right || r.bottom < v.top || r.top > v.bottom) return false;
+          }
+          return !have.has(String(n.id));
+        }).map(n => n.id);
+      }, flowNotes);
+      check("interaction", "demo pack notes mode shows a marker for each anchored note", markerless.length === 0, `missing=${markerless.join(",")}`);
+    }
+    await page.screenshot({ path: join(outDir, "06-notes.png") });
+    await page.keyboard.press("n");
+  }
 
   // ---------- accessibility (dynamic)
   await page.locator("#viewport").focus();
@@ -307,6 +470,130 @@ for (const [w, h] of viewports) {
   check("a11y", "text contrast is at least 4.5 in the dark theme", cd.min >= 4.5, `min=${cd.min.toFixed(2)} ${cd.worst.join(" | ")}`);
   await page.emulateMedia({ colorScheme: "dark" }); await page.waitForTimeout(200);
   await page.screenshot({ path: join(outDir, "07-dark.png") });
+  if (!skip.has("playback") && model.scenarios?.length) {
+    const playback = await page.evaluate(async () => {
+      const f = window.FlowStudio;
+      f.play(f.model.scenarios[0].id);
+      await new Promise(r => setTimeout(r, 80));
+      const first = document.querySelector("#token").getAttribute("cx");
+      const link = document.querySelector("path.edge.playing")?.dataset.i;
+      await new Promise(r => setTimeout(r, 160));
+      const second = document.querySelector("#token").getAttribute("cx");
+      f.pause(); document.querySelector("#pbReset").click(); f.step(); const a = document.querySelector("path.edge.playing")?.dataset.i;
+      f.step(); const b = document.querySelector("path.edge.playing")?.dataset.i;
+      const branches = document.querySelectorAll("#pbChoices button").length;
+      const suggested = document.querySelectorAll("#pbChoices .suggested").length;
+      document.querySelector("#pbScrub").value = "1000";
+      document.querySelector("#pbScrub").dispatchEvent(new Event("input", { bubbles: true }));
+      const scrub = f.playback().step, scrubLink = document.querySelector("path.edge.playing")?.dataset.i;
+      return { moved: first !== second && getComputedStyle(document.querySelector("#token")).display !== "none", link, a, b, scrub, scrubLink, branches, suggested };
+    });
+    const s0 = model.scenarios[0];
+    const expectedLink0 = String(model.links.findIndex(l => l.id === s0.steps[0]?.link));
+    check("interaction", "Play moves the token along the current link", playback.moved && playback.link === expectedLink0);
+    // A scenario may legally have a single step; comparing a second link needs two of them.
+    if ((s0.steps?.length ?? 0) >= 2) {
+      const expectedLink1 = String(model.links.findIndex(l => l.id === s0.steps[1]?.link));
+      check("interaction", "Step follows scenario link order", playback.a === expectedLink0 && playback.b === expectedLink1);
+    }
+    check("interaction", "scrubber lands on the final scenario link", playback.scrub === s0.steps.length - 1 && playback.scrubLink === String(model.links.findIndex(l => l.id === s0.steps.at(-1)?.link)));
+    const step1Link = model.links.find(l => l.id === s0.steps[1]?.link);
+    const hasBranchAtStep2 = step1Link && model.links.filter(l => l.from === step1Link.to).length > 1;
+    if (hasBranchAtStep2)
+      check("interaction", "branch buttons show at a gateway in step mode", playback.branches > 1 && playback.suggested === 1);
+    const sla = await page.evaluate(() => {
+      const f = window.FlowStudio;
+      const scenarios = f.model.scenarios ?? [];
+      // Prefer the canonical "escalated", else the first scenario whose elapsed time passes the SLA
+      // of a node it lands on. A model without any breach simply skips this check.
+      const breaches = s => (s?.steps ?? []).some(st => {
+        const link = f.model.links.find(l => l.id === st?.link);
+        if (!link) return false;
+        const target = f.model.nodes.find(n => n.id === link.to);
+        const slaOf = f.model.nodes.find(n => n.id === (target?.ref ?? link.to))?.sla;
+        return slaOf !== undefined && (st.at ?? 0) >= slaOf;
+      });
+      const scenario = scenarios.find(s => s.id === "escalated" && breaches(s)) ?? scenarios.find(breaches);
+      if (!scenario) return { found: false, breached: false };
+      f.play(scenario.id); f.pause();
+      for (let i = 0; i < scenario.steps.length; i++) {
+        f.step();
+        if (document.querySelector("#pbCounter")?.classList.contains("breach")) {
+          return { found: true, breached: true };
+        }
+      }
+      return { found: true, breached: document.querySelector("#pbCounter")?.classList.contains("breach") ?? false };
+    });
+    // A model whose SLAs no scenario crosses is valid: the check is skipped. It fails only when a scenario does cross an SLA and the counter never reaches breach.
+    if (sla.found) check("interaction", "an SLA-breaching scenario reaches breach", sla.breached, sla.breached ? "" : "did not reach breach");
+    if (hasBranchAtStep2) {
+      const pausedChoices = await page.evaluate(() => {
+        const f = window.FlowStudio;
+        const visible = sel => [...document.querySelectorAll(sel)].filter(b => b.offsetParent !== null).length;
+        f.play(f.model.scenarios[0].id); f.pause();
+        f.step();
+        // Park the token just inside this step, so play() resumes it instead of rewinding at the plan's end.
+        f.seek(f.playback().t - 1);
+        // Play clears the branch buttons; pausing on this step must bring them back.
+        f.play(); f.pause();
+        return { step: f.playback().step, branches: visible("#pbChoices button"), suggested: visible("#pbChoices .suggested") };
+      });
+      check("interaction", "pausing at a gateway keeps the branch buttons", pausedChoices.branches > 1 && pausedChoices.suggested === 1, `step=${pausedChoices.step} branches=${pausedChoices.branches} suggested=${pausedChoices.suggested}`);
+      const finishedChoices = await page.evaluate(async () => {
+        const f = window.FlowStudio;
+        const visible = sel => [...document.querySelectorAll(sel)].filter(b => b.offsetParent !== null).length;
+        const btn = document.querySelector("#pbChoices button[data-link]");
+        if (!(btn instanceof HTMLButtonElement)) return { finished: false, branches: 0 };
+        btn.click();
+        await new Promise(res => { const t0 = performance.now(); const iv = setInterval(() => { if (!f.playback().playing || performance.now() - t0 > 5000) { clearInterval(iv); res(); } }, 50); });
+        const finished = !f.playback().playing, branches = visible("#pbChoices button");
+        // Leave playback in a state a live update can restore exactly (a manual route lives only in the player).
+        document.querySelector("#pbReset").click();
+        return { finished, branches };
+      });
+      check("interaction", "playback that stops on its own shows the branch buttons", finishedChoices.finished && finishedChoices.branches > 1, finishedChoices.finished ? `branches=${finishedChoices.branches}` : "did not finish");
+    }
+  }
+
+  if (!skip.has("update")) {
+  const updateProbe = await page.evaluate(() => {
+    const f = window.FlowStudio;
+    const m = structuredClone(f.model), first = m.nodes.find(n => !["group", "chip", "gateway"].includes(n.kind)) ?? m.nodes[0], changed = first;
+    f.pause(); f.select(changed.id);
+    const qInput = document.querySelector("#q");
+    if (qInput) {
+      qInput.value = "verify";
+      qInput.dispatchEvent(new Event("input", { bubbles: true }));
+    }
+    const before = { view: f.view(), selected: f.selected(), mode: f.mode(), playback: f.playback(), search: document.querySelector("#q")?.value ?? "" };
+    changed.state = Object.keys(m.states).find(s => s !== changed.state) ?? changed.state;
+    changed.title += " updated";
+    const newId = "check-added-node";
+    const newNode = { ...structuredClone(first), id: newId, title: "Added node", contains: undefined, ref: undefined, metrics: undefined };
+    if (m.layout === "auto") { delete newNode.col; delete newNode.row; }
+    if (m.layout === "columns-lanes") newNode.row = Math.max(...m.nodes.filter(n => n.col === first.col).map(n => n.row ?? 0)) + 2;
+    if (m.layout === "free") newNode.x = Math.max(...m.nodes.map(n => (n.x ?? 0) + (n.w ?? 190))) + 50;
+    m.nodes.push(newNode);
+    m.links.push({ id: "check-added-link", from: first.id, to: newId, state: first.state });
+    const good = f.update(m);
+    const after = { view: f.view(), selected: f.selected(), mode: f.mode(), playback: f.playback(), search: document.querySelector("#q")?.value ?? "" };
+    const updated = document.getElementById("n_" + changed.id)?.classList.contains("updated");
+    const added = !!document.getElementById("n_" + newId);
+    const nodeCount = document.querySelectorAll(".node").length;
+    const edgeCount = document.querySelectorAll("path.edge").length;
+    const invalid = structuredClone(m); invalid.links.push({ id: "bad", from: "missing", to: newId, state: first.state });
+    const bad = f.update(invalid);
+    const unchanged = document.querySelectorAll(".node").length === nodeCount && document.querySelectorAll("path.edge").length === edgeCount;
+    const banner = !document.getElementById("banner").hidden;
+    const recover = f.update(m);
+    return { good: good.ok, bad: !bad.ok, recover: recover.ok, before, after, updated, added, unchanged, banner, hidden: document.getElementById("banner").hidden };
+  });
+  const stateKept = isDeepStrictEqual(updateProbe.before, updateProbe.after);
+  check("interaction", "update keeps view, selection, search and playback", updateProbe.good && stateKept, stateKept ? "" : `before=${JSON.stringify(updateProbe.before)} after=${JSON.stringify(updateProbe.after)}`);
+  check("interaction", "update marks changed and added nodes", updateProbe.updated && updateProbe.added);
+  check("interaction", "invalid update keeps the DOM and shows a banner", updateProbe.bad && updateProbe.unchanged && updateProbe.banner);
+  check("interaction", "valid update clears the failure banner", updateProbe.recover && updateProbe.hidden);
+  }
   await ctx.close();
 }
 
@@ -314,23 +601,28 @@ for (const [w, h] of viewports) {
 {
   const ctx = await browser.newContext({ viewport: { width: 1600, height: 900 }, reducedMotion: "reduce" });
   const page = await ctx.newPage();
-  await page.goto(url(pagePath)); await page.waitForFunction(() => !!window.FlowStudio); await page.waitForTimeout(600);
+  await page.goto(targetUrl); await page.waitForFunction(() => !!window.FlowStudio); await page.waitForTimeout(600);
   const moving = await page.evaluate(() => {
     let n = 0;
     document.querySelectorAll("#viewport *, .tile, .lcell").forEach(e => { const s = getComputedStyle(e); if (s.animationName !== "none" && s.animationDuration !== "0s") n++; if (s.transitionDuration.split(",").some(d => parseFloat(d) > 0)) n++; });
     return n;
   });
   check("a11y", "reduced motion removes every animation and transition", moving === 0, `moving=${moving}`);
+  const reducedToken = await page.evaluate(() => {
+    const token = document.getElementById("token");
+    return !token || getComputedStyle(token).transitionDuration.split(",").every(d => parseFloat(d) === 0);
+  });
+  check("a11y", "reduced motion gives the token no transition", reducedToken);
   await ctx.close();
 }
 
 // ---------- hostile text
-if (hostilePath) {
+if (hostilePath && !skip.has("hostile")) {
   const ctx = await browser.newContext({ viewport: { width: 1600, height: 900 } });
   const page = await ctx.newPage();
   const errors = [];
   page.on("pageerror", e => errors.push(String(e)));
-  await page.goto(url(resolve(hostilePath))); await page.waitForFunction(() => !!window.FlowStudio); await page.waitForTimeout(600);
+  await page.goto(url(hostilePath)); await page.waitForFunction(() => !!window.FlowStudio); await page.waitForTimeout(600);
   const probe = await page.evaluate(() => ({
     pwned: window.__pwned,
     scripts: document.querySelectorAll("script").length,
@@ -350,7 +642,7 @@ if (hostilePath) {
 if (!flag("--skip-perf")) {
   const ctx = await browser.newContext({ viewport: { width: 1600, height: 900 } });
   const page = await ctx.newPage();
-  await page.goto(url(pagePath)); await page.waitForFunction(() => !!window.FlowStudio); await page.waitForTimeout(400);
+  await page.goto(targetUrl); await page.waitForFunction(() => !!window.FlowStudio); await page.waitForTimeout(400);
   const perf = await page.evaluate(() => {
     const base = window.FlowStudio.model;
     const cols = base.columns, lanes = [], nodes = [], links = [];

package/bundles/antigravity-plugin/skills/flow-studio/scripts/default-notes.json

@@ -0,0 +1,67 @@
+[
+  {
+    "anchor": "#title",
+    "title": "Page frame",
+    "text": "Display the main scenario headline, subtitle, and timestamp. Render all text using textContent or esc() to prevent script injection."
+  },
+  {
+    "anchor": "#layerstrip",
+    "title": "Completeness strip",
+    "text": "Show completeness per column with stacked horizontal bars for good, neutral, and gap counts. Render dotted tracks for empty columns."
+  },
+  {
+    "anchor": "#kpis",
+    "title": "Summary tiles",
+    "text": "Show total links, gap count, and upgrade opportunities. Make tiles interactive buttons that filter canvas focus when clicked."
+  },
+  {
+    "anchor": "#modeSwitch",
+    "title": "View switch",
+    "text": "Provide segmented buttons to switch perspectives. Update visible nodes and overridden link states from a single underlying data model."
+  },
+  {
+    "anchor": "#q",
+    "title": "Search and radius",
+    "text": "Filter nodes by name or identifier. Use the hops selector to reveal upstream and downstream connections within N degrees."
+  },
+  {
+    "anchor": "#viewport",
+    "title": "Canvas viewport",
+    "text": "Support smooth pan and zoom around cursor. Fit initial view to width so users see all phases immediately without manual zooming."
+  },
+  {
+    "anchor": "#tools",
+    "title": "Canvas controls",
+    "text": "Provide quick zoom in, zoom out, fit-to-screen, 100% scale, and pan hand controls. Bind standard keyboard shortcuts V, H, +, -, 0, and F."
+  },
+  {
+    "anchor": "#inspector",
+    "title": "Side inspector",
+    "text": "Slide out an inspector card on node selection. Display incoming links, outgoing links, metadata, and what-if simulation buttons."
+  },
+  {
+    "anchor": "#legend",
+    "title": "State legend",
+    "text": "Display color chips and state labels for good, neutral, warning, and critical states. Keep states distinguishable without color alone."
+  },
+  {
+    "anchor": "#ledger",
+    "title": "Change ledger",
+    "text": "List recent schema updates, audit entries, or unverified links beneath the canvas. Render tabular details cleanly."
+  },
+  {
+    "anchor": "#tbl",
+    "title": "Accessible table view",
+    "text": "Provide a collapsible HTML table containing all graph nodes, states, and relations. Ensures screen reader parity with canvas visuals."
+  },
+  {
+    "anchor": "#playbar",
+    "title": "Scenario playback",
+    "text": "Provide play, pause, step-by-step, reset, and scrubbing controls. Animate token flow across links during scenario execution."
+  },
+  {
+    "anchor": "#notesBtn",
+    "title": "Implementation notes",
+    "text": "Toggle developer guidance cards and anchored target markers. Map numeric badges directly to corresponding drawer documentation cards."
+  }
+]

package/bundles/antigravity-plugin/skills/flow-studio/scripts/lib/auto-entry-guard.mjs

@@ -0,0 +1,5 @@
+/** Keep malformed auto models intact so validation reports their actual errors. */
+export function prepareModel(input, autoLayout) {
+  return input?.layout === "auto" && Array.isArray(input.nodes) && Array.isArray(input.links)
+    && Array.isArray(input.columns) && Array.isArray(input.lanes) ? autoLayout(input) : input;
+}

package/bundles/antigravity-plugin/skills/flow-studio/scripts/lib/auto-entry-guard.test.mjs

@@ -0,0 +1,14 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { prepareModel } from "./auto-entry-guard.mjs";
+
+test("auto layout runs only when its four input arrays exist", () => {
+  const model = { layout: "auto", nodes: [], links: [], columns: [], lanes: [] };
+  const laidOut = { ...model, applied: true };
+  const layout = input => { assert.equal(input, model); return laidOut; };
+  assert.equal(prepareModel(model, layout), laidOut);
+  for (const field of ["nodes", "links", "columns", "lanes"]) {
+    assert.equal(prepareModel({ ...model, [field]: null }, () => { throw Error("called"); })[field], null);
+  }
+  assert.equal(prepareModel({ ...model, layout: "free" }, () => { throw Error("called"); }).layout, "free");
+});

package/bundles/antigravity-plugin/skills/flow-studio/scripts/lib/auto-entry.test.mjs

@@ -0,0 +1,31 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const validateScript = fileURLToPath(new URL("../validate.mjs", import.meta.url));
+const buildScript = fileURLToPath(new URL("../build.mjs", import.meta.url));
+
+test("validate and build lay out an auto model before checking it", () => {
+  const dir = mkdtempSync(join(fileURLToPath(new URL(".", import.meta.url)), ".auto-entry-"));
+  try {
+    const modelPath = join(dir, "model.json"), pagePath = join(dir, "page.html");
+    const model = {
+      version: 1, meta: { title: "Auto", help: "", asOf: "", source: "" }, layout: "auto", columns: [], lanes: [],
+      states: { ok: { word: "OK", tone: "ok", border: "solid", edge: "flow", motion: "flow", bucket: "good" } },
+      nodes: ["a", "b"].map(id => ({ id, kind: "card", state: "ok", title: id })),
+      links: [{ id: "ab", from: "a", to: "b", state: "ok" }],
+    };
+    writeFileSync(modelPath, JSON.stringify(model));
+    const run = (script, extra = []) => spawnSync(process.execPath, ["--experimental-strip-types", "--no-warnings", script, modelPath, ...extra], { cwd: dir, encoding: "utf8" });
+    const valid = run(validateScript);
+    assert.equal(valid.status, 0, valid.stdout + valid.stderr);
+    const built = run(buildScript, [pagePath]);
+    assert.equal(built.status, 0, built.stdout + built.stderr);
+    const page = readFileSync(pagePath, "utf8");
+    assert.match(page, /"layout":"auto"/);
+    assert.match(page, /"title":"Stage 2"/);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});