@caddis/cli 0.4.45 → 0.4.47

package/bundles/antigravity-plugin/skills/flow-studio/scripts/lib/build-engine.test.mjs

@@ -1,9 +1,37 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { buildEngine } from "../build-engine.mjs";
+import { readFileSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildEngine, resolveEsbuild } from "../build-engine.mjs";
 
 const normalise = t => t.replace(/\r\n/g, "\n");
+test("esbuild resolution chooses the first candidate and respects order", () => {
+  const dir = mkdtempSync(new URL("./flow-studio-esbuild-", import.meta.url));
+  try {
+    const candidates = [join(dir, "first"), join(dir, "second")];
+    for (const [i, candidate] of candidates.entries()) {
+      const pkg = join(candidate, "node_modules", "esbuild");
+      mkdirSync(pkg, { recursive: true });
+      writeFileSync(join(pkg, "package.json"), JSON.stringify({ name: "esbuild", main: "index.js" }));
+      writeFileSync(join(pkg, "index.js"), `module.exports = { source: ${JSON.stringify(i)} };`);
+    }
+    assert.equal(resolveEsbuild(candidates).source, 0);
+    assert.equal(resolveEsbuild(candidates.toReversed()).source, 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("empty candidate folders give an actionable esbuild error", () => {
+  const dir = mkdtempSync(new URL("./flow-studio-esbuild-", import.meta.url));
+  try {
+    const empty = [join(dir, "one"), join(dir, "two")];
+    empty.forEach(p => mkdirSync(p));
+    assert.throws(() => resolveEsbuild(empty), /FLOW_STUDIO_NODE_MODULES.*npm i -D esbuild/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
 
 test("the generated engine has no external URL and keeps only the model and notes slots", async () => {
   const html = await buildEngine();

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

@@ -0,0 +1,18 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const allowed = new Set(['notes', 'playback', 'update', 'hostile']);
+
+export function pageUrl(input) {
+  // try/catch, not URL.canParse: canParse needs Node 18.17+ and this skill runs on older tooling too.
+  let parsed = null;
+  try { parsed = new URL(input); } catch { /* not an absolute URL; treat the input as a local path */ }
+  if (parsed?.protocol === 'http:' || parsed?.protocol === 'https:' || parsed?.protocol === 'file:') return parsed.href;
+  return pathToFileURL(resolve(input)).href;
+}
+
+export function skippedGroups(value = '') {
+  const groups = value ? value.split(',').map(s => s.trim()) : [];
+  for (const group of groups) if (!allowed.has(group)) throw new Error(`unknown skip group: ${group}`);
+  return new Set(groups);
+}

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

@@ -0,0 +1,15 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { pageUrl, skippedGroups } from './check-args.mjs';
+
+test('pageUrl accepts served pages and local files', () => {
+  assert.equal(pageUrl('http://127.0.0.1:8123/path'), 'http://127.0.0.1:8123/path');
+  assert.equal(pageUrl('https://example.test/flow'), 'https://example.test/flow');
+  assert.equal(pageUrl('file:///tmp/page.html'), 'file:///tmp/page.html');
+  assert.match(pageUrl('page.html'), /^file:\/\//);
+});
+
+test('skip parser accepts only known groups', () => {
+  assert.deepEqual([...skippedGroups('notes,playback,update,hostile')], ['notes', 'playback', 'update', 'hostile']);
+  assert.throws(() => skippedGroups('safety'), /unknown skip group/);
+});

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

@@ -3,12 +3,11 @@
 // Run it from a folder that has Playwright, for example:
 //   FLOW_STUDIO_CHANNEL=msedge node --test <skill>/scripts/lib/check-selftest.test.mjs
 
-import { test } from "node:test";
+import { test, after } from "node:test";
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { embedModel } from "./embed.mjs";
@@ -20,7 +19,9 @@ const skip = hasPlaywright ? false : "playwright is not resolvable from the curr
 
 const engine = readFileSync(join(root, "templates/engine.html"), "utf8");
 const base = JSON.parse(readFileSync(join(root, "examples/lineage.json"), "utf8"));
-const dir = mkdtempSync(join(tmpdir(), "flow-selftest-"));
+const order = JSON.parse(readFileSync(join(root, "examples/order-desk.json"), "utf8"));
+const dir = mkdtempSync(join(root, ".flow-selftest-"));
+after(() => rmSync(dir, { recursive: true, force: true }));
 
 function page(name, { model = base, inject = "" } = {}) {
   const html = embedModel(engine, model, []).replace("</body>", `${inject}</body>`);
@@ -43,6 +44,11 @@ test("a clean page passes every check", { skip }, () => {
   assert.equal(r.status, 0, r.stdout + r.stderr);
 });
 
+test("a clean page with a metric on a collapsed child passes every check", { skip }, () => {
+  const r = run(page("clean-order-desk", { model: order }));
+  assert.equal(r.status, 0, r.stdout + r.stderr);
+});
+
 test("two nodes in one place fail the intersection check", { skip }, () => {
   const m = structuredClone(base);
   m.nodes.find(n => n.id === "T_WH").row = m.nodes.find(n => n.id === "D_WH").row; // same row, other column: move it onto a neighbour
@@ -73,3 +79,57 @@ test("a canvas too wide to read fails the first-view check", { skip }, () => {
   m.columns.forEach(c => { c.width = 700; });
   expectFail(run(page("wide", { model: m })), "first view is readable");
 });
+test("a moved loop path fails the link-endpoint check", { skip }, () => {
+  const m = structuredClone(base);
+  const link = m.links[0];
+  link.from = "H_DB1";
+  link.to = "ORD";
+  link.kind = "loop-back";
+  const inject = `<script>window.addEventListener("load", () => setTimeout(() => { document.querySelector("path.edge.loop")?.setAttribute("d", "M0,0 H10"); }, 300));</script>`;
+  expectFail(run(page("moved-loop", { model: m, inject })), "every link end touches its node box");
+});
+test("a node moved onto a loop path fails the loop clearance check", { skip }, () => {
+  const m = structuredClone(base);
+  m.links.push({ id: "return-check", from: "H_DB1", to: "ORD", state: m.links[0].state, kind: "loop-back" });
+  const inject = `<script>window.addEventListener("load", () => setTimeout(() => {
+    const path = [...document.querySelectorAll("path.edge.loop")].find(p => !p.classList.contains("off"));
+    const node = [...document.querySelectorAll(".node:not(.off)")].find(n => n.id !== "n_" + path?.dataset.a && n.id !== "n_" + path?.dataset.b);
+    if (path && node) { const point = path.getPointAtLength(path.getTotalLength() / 2);
+      node.style.left = (point.x - 20) + "px"; node.style.top = (point.y - 20) + "px"; }
+  }, 300));</script>`;
+  expectFail(run(page("blocked-loop", { model: m, inject })), "no loop-back path passes through a visible node");
+});
+test("a gateway without its diamond fails the gateway check", { skip }, () => {
+  const m = structuredClone(base);
+  const gate = m.nodes.find(n => n.id === "H_DB1");
+  gate.kind = "gateway";
+  const inject = `<script>window.addEventListener("load", () => setTimeout(() => { document.querySelector(".node.gateway polygon")?.remove(); }, 300));</script>`;
+  expectFail(run(page("no-gateway-polygon", { model: m, inject })), "gateway.*polygon");
+});
+
+test("a hidden playback token fails the movement check", { skip }, () => {
+  expectFail(run(page("hidden-token", { model: order, inject: `<style>#token { display:none !important; }</style>` })), "Play moves the token");
+});
+
+test("an update that does nothing fails the live update check", { skip }, () => {
+  const inject = `<script>window.addEventListener("load", () => setTimeout(() => { window.FlowStudio.update = () => ({ ok:true, issues:[] }); }, 300));</script>`;
+  expectFail(run(page("noop-update", { model: order, inject })), "update marks changed and added nodes");
+});
+
+test("a first scenario with a single step still passes every check", { skip }, () => {
+  const m = structuredClone(order);
+  m.scenarios[0].steps = m.scenarios[0].steps.slice(0, 1); // one step is legal (minItems 1)
+  const r = run(page("one-step", { model: m }));
+  assert.equal(r.status, 0, r.stdout + r.stderr);
+});
+
+test("an SLA breach is found without a scenario named escalated", { skip }, () => {
+  const m = structuredClone(order);
+  m.scenarios.find(s => s.id === "escalated").id = "surged";
+  const r = run(page("renamed-escalated", { model: m }));
+  assert.equal(r.status, 0, r.stdout + r.stderr);
+});
+
+test("hidden branch buttons fail the branch-button checks", { skip }, () => {
+  expectFail(run(page("hidden-choices", { model: order, inject: `<style>#pbChoices { display:none !important; }</style>` })), "keeps the branch buttons");
+});

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

@@ -5,6 +5,7 @@ import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { keepDefaultNotes } from "./demo-pack.mjs";
 
 const root = resolve(fileURLToPath(import.meta.url), "../../..");
 const run = (script, ...args) =>
@@ -49,6 +50,7 @@ test("build: a note file cannot override the numbering and must be an array", ()
   assert.equal(r.status, 0, r.stderr);
   const html = readFileSync(out, "utf8");
   const m = html.match(/id="flow-notes">(.*?)<\/script>/s);
+  assert.ok(m, "the embedded notes script tag is present");
   const parsed = JSON.parse(m[1]);
   assert.deepEqual(parsed.map(n => n.id), [1, 2]);
   const bad = write("notes-bad.json", { not: "an array" });
@@ -62,3 +64,116 @@ test("build: refuses a model with errors and writes nothing", () => {
   assert.equal(r.status, 1);
   assert.equal(existsSync(out), false);
 });
+
+test("build --demo-pack: order and numbering (default first, model second, extra third)", () => {
+  const m = structuredClone(good);
+  m.notes = [{ anchor: "#viewport", title: "Model Note", text: "model" }];
+  const p = write("demo-pack-model.json", m);
+  const extra = write("demo-pack-extra.json", [{ anchor: "#kpis", title: "Extra Note", text: "extra" }]);
+  const out = join(dir, "out-demo-pack-order.html");
+  const r = run("build.mjs", p, out, "--demo-pack", "--notes", extra);
+  assert.equal(r.status, 0, r.stderr);
+  const html = readFileSync(out, "utf8");
+  const match = html.match(/id="flow-notes">(.*?)<\/script>/s);
+  assert.ok(match, "the embedded notes script tag is present");
+  const parsed = JSON.parse(match[1]);
+
+  // Numbering 1..n
+  assert.deepEqual(parsed.map(n => n.id), Array.from({ length: parsed.length }, (_, i) => i + 1));
+
+  // Default notes come first (e.g. Page frame)
+  assert.equal(parsed[0].title, "Page frame");
+
+  // Model notes come second
+  const modelIdx = parsed.findIndex(n => n.title === "Model Note");
+  assert.ok(modelIdx > 0, "model note should be present");
+
+  // Extra notes come third
+  const extraIdx = parsed.findIndex(n => n.title === "Extra Note");
+  assert.equal(extraIdx, parsed.length - 1);
+  assert.ok(modelIdx < extraIdx, "model notes come before extra notes");
+});
+
+test("build --demo-pack: drops #playbar without scenarios and #modeSwitch with < 2 views", () => {
+  const m = structuredClone(good); // no scenarios, no views
+  const p = write("demo-pack-drop.json", m);
+  const out = join(dir, "out-demo-pack-drop.html");
+  const r = run("build.mjs", p, out, "--demo-pack");
+  assert.equal(r.status, 0, r.stderr);
+  const html = readFileSync(out, "utf8");
+  const match = html.match(/id="flow-notes">(.*?)<\/script>/s);
+  assert.ok(match, "the embedded notes script tag is present");
+  const parsed = JSON.parse(match[1]);
+  assert.equal(parsed.some(n => n.anchor === "#playbar"), false, "should drop playbar note");
+  assert.equal(parsed.some(n => n.anchor === "#modeSwitch"), false, "should drop modeSwitch note");
+});
+
+test("build --demo-pack: keeps #playbar with scenarios and #modeSwitch with 2+ views", () => {
+  const m = structuredClone(good);
+  m.views = [
+    { id: "v1", title: "View 1" },
+    { id: "v2", title: "View 2" },
+  ];
+  m.scenarios = [
+    { id: "s1", label: "Scenario 1", steps: [{ link: "a-b" }] },
+  ];
+  const p = write("demo-pack-keep.json", m);
+  const out = join(dir, "out-demo-pack-keep.html");
+  const r = run("build.mjs", p, out, "--demo-pack");
+  assert.equal(r.status, 0, r.stderr);
+  const html = readFileSync(out, "utf8");
+  const match = html.match(/id="flow-notes">(.*?)<\/script>/s);
+  assert.ok(match, "the embedded notes script tag is present");
+  const parsed = JSON.parse(match[1]);
+  assert.equal(parsed.some(n => n.anchor === "#playbar"), true, "should keep playbar note");
+  assert.equal(parsed.some(n => n.anchor === "#modeSwitch"), true, "should keep modeSwitch note");
+});
+
+test("build: hostile anchors in model notes are preserved safely", () => {
+  const m = structuredClone(good);
+  m.notes = [
+    { anchor: "<script>alert('xss')</script>", title: "Hostile Tag", text: "t" },
+    { anchor: "[invalid:css(selector", title: "Invalid Selector", text: "t" },
+    { anchor: "\"></script><script>alert(1)</script>", title: "Breakout", text: "t" },
+  ];
+  const p = write("hostile-notes.json", m);
+  const out = join(dir, "out-hostile-notes.html");
+  const r = run("build.mjs", p, out);
+  assert.equal(r.status, 0, r.stderr);
+  const html = readFileSync(out, "utf8");
+  const match = html.match(/id="flow-notes">(.*?)<\/script>/s);
+  assert.ok(match, "notes script tag should be present and intact");
+  const parsed = JSON.parse(match[1]);
+  assert.equal(parsed.length, 3);
+  assert.equal(parsed[0].anchor, "<script>alert('xss')</script>");
+  assert.equal(parsed[1].anchor, "[invalid:css(selector");
+  assert.equal(parsed[2].anchor, "\"></script><script>alert(1)</script>");
+});
+
+test("build --demo-pack: examples/lineage.json gets kept defaults first, then its own model notes", () => {
+  // Expectations come from the example and the shared filter, so the test does not break when
+  // the example changes. The filter's own logic is pinned by demo-pack.test.mjs.
+  const lineage = JSON.parse(readFileSync(join(root, "examples", "lineage.json"), "utf8"));
+  const defaults = JSON.parse(readFileSync(join(root, "scripts", "default-notes.json"), "utf8"));
+  const shell = readFileSync(join(root, "templates", "engine.html"), "utf8");
+  const kept = keepDefaultNotes(defaults, lineage, shell);
+  const expected = kept.length + (lineage.notes?.length ?? 0);
+  const outPack = join(dir, "out-lineage-pack.html"); // temp folder: the build must not leave repo artifacts
+  const r = run("build.mjs", join(root, "examples", "lineage.json"), outPack, "--demo-pack");
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(existsSync(outPack), true);
+  const html = readFileSync(outPack, "utf8");
+  const match = html.match(/id="flow-notes">(.*?)<\/script>/s);
+  assert.ok(match, "the embedded notes script tag is present");
+  const parsed = JSON.parse(match[1]);
+  assert.equal(parsed.length, expected, `expected ${expected} notes, got ${parsed.length}`);
+  for (let i = 0; i < kept.length; i++) {
+    assert.equal(parsed[i].anchor, kept[i].anchor, `note ${i + 1} should be the kept default ${kept[i].anchor}`);
+  }
+  if (lineage.notes?.length) {
+    assert.equal(parsed[kept.length].anchor, lineage.notes[0].anchor, "the first model note follows the kept defaults");
+    assert.equal(parsed[kept.length].title, lineage.notes[0].title, "the first model note follows the kept defaults");
+  }
+  assert.deepEqual(parsed.map(n => n.id), Array.from({ length: expected }, (_, i) => i + 1));
+});
+

package/bundles/antigravity-plugin/skills/flow-studio/scripts/lib/demo-pack.mjs

@@ -0,0 +1,23 @@
+// Which default demo-pack notes survive for one model and one built shell. Shared by build.mjs
+// and its tests. Only default notes are filtered here: notes from the model and from --notes are
+// appended unfiltered (at runtime a note whose selector matches nothing simply gets no marker).
+
+// An exact attribute match, not a pattern: an id with regex metacharacters must never match a
+// different id, and a data-id="..." substring must not count as an id.
+const hasId = (shell, id) => shell.includes(` id="${id}"`) || shell.includes(` id='${id}'`);
+
+export function keepDefaultNotes(defaults, model, shell) {
+  return defaults.filter(n => {
+    if (n.anchor === "#playbar" && (!Array.isArray(model.scenarios) || model.scenarios.length === 0)) {
+      return false;
+    }
+    if (n.anchor === "#modeSwitch" && (!Array.isArray(model.views) || model.views.length < 2)) {
+      return false;
+    }
+    if (typeof n.anchor === "string" && n.anchor.startsWith("#")) {
+      const id = n.anchor.slice(1);
+      if (!hasId(shell, id)) return false;
+    }
+    return true;
+  });
+}

package/bundles/antigravity-plugin/skills/flow-studio/scripts/lib/demo-pack.test.mjs

@@ -0,0 +1,34 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { keepDefaultNotes } from "./demo-pack.mjs";
+
+// The shell here is a fixture, not the real engine.html: the filter only reads id attributes.
+const shell = '<div id="q"></div><span data-id="title"></span><i id="qxy"></i><section id="playbar"></section><nav id="modeSwitch"></nav>';
+const note = anchor => ({ anchor, title: anchor, text: "t" });
+
+test("demo-pack: keeps a default note whose id exists in the shell", () => {
+  assert.equal(keepDefaultNotes([note("#q")], {}, shell).length, 1);
+});
+
+test("demo-pack: drops a default note whose id is missing; a data-id substring is not an id", () => {
+  assert.deepEqual(keepDefaultNotes([note("#title")], {}, shell), []);
+});
+
+test("demo-pack: does not treat regex metacharacters in an id as a pattern", () => {
+  // "qx+y" read as a regular expression would match the shell's id="qxy"; read as an id it must not.
+  assert.deepEqual(keepDefaultNotes([note("#qx+y")], {}, shell), []);
+});
+
+test("demo-pack: drops #playbar without scenarios and keeps it with at least one", () => {
+  assert.deepEqual(keepDefaultNotes([note("#playbar")], {}, shell), []);
+  assert.equal(keepDefaultNotes([note("#playbar")], { scenarios: [{ id: "s1", steps: [{ link: "l1" }] }] }, shell).length, 1);
+});
+
+test("demo-pack: drops #modeSwitch with fewer than two views and keeps it with two", () => {
+  assert.deepEqual(keepDefaultNotes([note("#modeSwitch")], { views: [{ id: "v1", label: "V" }] }, shell), []);
+  assert.equal(keepDefaultNotes([note("#modeSwitch")], { views: [{ id: "v1", label: "V" }, { id: "v2", label: "W" }] }, shell).length, 1);
+});
+
+test("demo-pack: leaves anchors that are not ids (class and attribute selectors) unfiltered", () => {
+  assert.equal(keepDefaultNotes([note(".anything"), note("[data-x='y']")], {}, shell).length, 2);
+});

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

@@ -0,0 +1,128 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "../..");
+
+test("docs: (1) every property in model.schema.json appears in references/model-schema.md", () => {
+  const schemaPath = join(root, "model.schema.json");
+  const docPath = join(root, "references", "model-schema.md");
+  assert.ok(existsSync(schemaPath), "model.schema.json exists");
+  assert.ok(existsSync(docPath), "references/model-schema.md exists");
+
+  const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+  const doc = readFileSync(docPath, "utf8");
+
+  function collectProperties(obj, props = new Set()) {
+    if (!obj || typeof obj !== "object") return props;
+    if (obj.properties && typeof obj.properties === "object") {
+      for (const p of Object.keys(obj.properties)) {
+        props.add(p);
+        collectProperties(obj.properties[p], props);
+      }
+    }
+    // tuple-style schemas put subschemas in an items array
+    if (Array.isArray(obj.items)) obj.items.forEach(x => collectProperties(x, props));
+    else if (obj.items) collectProperties(obj.items, props);
+    // definitions/$defs are name->schema maps: walk the schemas, never the names
+    if (obj.definitions) for (const def of Object.values(obj.definitions)) collectProperties(def, props);
+    if (obj.$defs) for (const def of Object.values(obj.$defs)) collectProperties(def, props);
+    if (Array.isArray(obj.allOf)) obj.allOf.forEach(x => collectProperties(x, props));
+    if (Array.isArray(obj.anyOf)) obj.anyOf.forEach(x => collectProperties(x, props));
+    if (Array.isArray(obj.oneOf)) obj.oneOf.forEach(x => collectProperties(x, props));
+    return props;
+  }
+
+  // a whole word, not a substring: `id` must not be satisfied by `identifier`
+  const wordIn = (text, word) =>
+    new RegExp(`(?<![A-Za-z0-9_$-])${word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![A-Za-z0-9_$-])`).test(text);
+
+  const allProps = Array.from(collectProperties(schema));
+  const missing = allProps.filter(p => !wordIn(doc, p));
+  assert.deepEqual(missing, [], `Schema properties missing from model-schema.md: ${missing.join(", ")}`);
+});
+
+test("docs: (2) every example in examples/ is listed in examples/README.md", () => {
+  const examplesDir = join(root, "examples");
+  const readmePath = join(examplesDir, "README.md");
+  assert.ok(existsSync(readmePath), "examples/README.md exists");
+
+  const examples = readdirSync(examplesDir).filter(f => f.endsWith(".json"));
+  const readme = readFileSync(readmePath, "utf8");
+  const missing = examples.filter(e => !readme.includes(e));
+  assert.deepEqual(missing, [], `Examples missing from examples/README.md: ${missing.join(", ")}`);
+});
+
+test("docs: (3) every check group name used in scripts/check.mjs appears in references/verify.md", () => {
+  const checkScript = join(root, "scripts", "check.mjs");
+  const verifyDoc = join(root, "references", "verify.md");
+  assert.ok(existsSync(checkScript), "scripts/check.mjs exists");
+  assert.ok(existsSync(verifyDoc), "references/verify.md exists");
+
+  const checkCode = readFileSync(checkScript, "utf8");
+  const docText = readFileSync(verifyDoc, "utf8");
+
+  const groups = new Set();
+  for (const m of checkCode.matchAll(/\bcheck\(\s*["\x27]([^"\x27]+)["\x27]/g)) {
+    groups.add(m[1]);
+  }
+  const allGroups = Array.from(groups);
+  const missing = allGroups.filter(g => !docText.includes(g));
+  assert.deepEqual(missing, [], `Check groups missing from references/verify.md: ${missing.join(", ")}`);
+});
+
+test("docs: (4) SKILL.md frontmatter has name and description, name is flow-studio, under 220 lines", () => {
+  const skillPath = join(root, "SKILL.md");
+  assert.ok(existsSync(skillPath), "SKILL.md exists");
+
+  const content = readFileSync(skillPath, "utf8");
+  const lines = content.split(/\r?\n/);
+  if (lines.length && lines[lines.length - 1] === "") lines.pop(); // a trailing newline is not a line
+  assert.ok(lines.length < 220, `SKILL.md has ${lines.length} lines, must be under 220`);
+
+  const fmM = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  assert.ok(fmM, "SKILL.md has valid frontmatter block");
+  const fm = fmM[1];
+  assert.match(fm, /^name:\s*flow-studio\s*$/m, "frontmatter name is flow-studio");
+  assert.match(fm, /^description:\s*.+$/m, "frontmatter description is present");
+});
+
+test("docs: (5) every relative path in backticks starting with scripts/, src/, references/, examples/, templates/ exists", () => {
+  const refDir = join(root, "references");
+  const files = [
+    join(root, "SKILL.md"),
+    ...readdirSync(refDir).map(f => join(refDir, f))
+  ];
+  const prefixes = ["scripts/", "src/", "references/", "examples/", "templates/"];
+  const missing = [];
+
+  for (const file of files) {
+    const rawContent = readFileSync(file, "utf8");
+    // Strip fenced code blocks so we only check inline backtick code references
+    const stripped = rawContent.replace(/```[\s\S]*?```/g, "");
+    const matches = stripped.match(/`([^`\r\n]+)`/g) || [];
+
+    for (const m of matches) {
+      const token = m.slice(1, -1).trim();
+      // A span may hold a command (`scripts/check.mjs --json`) or a line reference
+      // (`scripts/check.mjs:23`), so check each whitespace-separated part, stripped of
+      // surrounding punctuation and a trailing :line suffix.
+      for (const part of token.split(/\s+/)) {
+        const candidate = part.replace(/^[("']+/, "").replace(/[.,;:)"']+$/, "").replace(/:\d+$/, "");
+        for (const prefix of prefixes) {
+          if (candidate.startsWith(prefix)) {
+            const resolved = resolve(root, candidate);
+            if (!existsSync(resolved)) {
+              missing.push({ file: file.replace(root, ""), path: candidate });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  assert.deepEqual(missing, [], `Referenced paths do not exist: ${JSON.stringify(missing)}`);
+});

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

@@ -0,0 +1,26 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { buildLibrary, buildEngine } from "../build-engine.mjs";
+
+test("the library bundle imports without page auto-start", async () => {
+  const { js, css } = await buildLibrary();
+  assert.doesNotMatch(js, /addEventListener\(["']DOMContentLoaded["']/);
+  assert.doesNotMatch(js, /window\.flowStudioMount\s*=/);
+  assert.match(js, /SHELL_BODY_HTML/);
+  assert.equal(css, readFileSync(new URL("../../src/styles.css", import.meta.url), "utf8"));
+  const lib = await import("data:text/javascript," + encodeURIComponent(js));
+  assert.equal(typeof lib.mount, "function");
+  assert.equal(typeof lib.validateModel, "function");
+  assert.equal(typeof lib.zoomAt, "function");
+  assert.equal(typeof lib.elbow, "function");
+  assert.match(lib.SHELL_BODY_HTML, /id="viewport"/);
+});
+
+test("page build includes the shared shell body once", async () => {
+  const normalise = text => text.replace(/\r\n/g, "\n");
+  const body = readFileSync(new URL("../../templates/shell-body.html", import.meta.url), "utf8");
+  const page = await buildEngine();
+  assert.ok(normalise(page).includes(normalise(body)));
+  assert.equal(page.split('id="viewport"').length - 1, 1);
+});

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

@@ -0,0 +1,12 @@
+// On Windows, killing a child does not release its open files until it closes.
+export async function stopPreview(preview, closed, graceMs = 5000) {
+  if (!preview) return;
+  if (preview.exitCode === null && preview.signalCode === null && !preview.kill())
+    throw new Error('Could not stop vite preview');
+  // A child that ignores the term signal must not block the teardown forever: force-kill it.
+  const finished = await Promise.race([closed.then(() => true), new Promise(resolve => setTimeout(resolve, graceMs, false))]);
+  if (!finished) {
+    preview.kill('SIGKILL');
+    await closed;
+  }
+}

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

@@ -0,0 +1,45 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { stopPreview } from './react-proof-cleanup.mjs';
+
+test('stopPreview waits for process closure before temporary files can be removed', async () => {
+  const preview = new EventEmitter();
+  preview.exitCode = null;
+  preview.signalCode = null;
+  preview.kill = () => true;
+  const closed = new Promise(resolve => preview.once('close', resolve));
+  let stopped = false;
+  const stopping = stopPreview(preview, closed).then(() => { stopped = true; });
+  await Promise.resolve();
+  assert.equal(stopped, false);
+  preview.emit('close', 0);
+  await stopping;
+  assert.equal(stopped, true);
+});
+
+test('stopPreview waits for close after process exit', async () => {
+  const preview = new EventEmitter();
+  preview.exitCode = 0;
+  preview.signalCode = null;
+  preview.kill = () => { throw new Error('already exited'); };
+  const closed = new Promise(resolve => preview.once('close', resolve));
+  let stopped = false;
+  const stopping = stopPreview(preview, closed).then(() => { stopped = true; });
+  await Promise.resolve();
+  assert.equal(stopped, false);
+  preview.emit('close', 0);
+  await stopping;
+  assert.equal(stopped, true);
+});
+
+test('stopPreview force-kills a child that ignores the first kill', async () => {
+  const preview = new EventEmitter();
+  preview.exitCode = null;
+  preview.signalCode = null;
+  const kills = [];
+  preview.kill = signal => { kills.push(signal); if (signal === 'SIGKILL') preview.emit('close'); return true; };
+  const closed = new Promise(resolve => preview.once('close', resolve));
+  await stopPreview(preview, closed, 10);
+  assert.deepEqual(kills, [undefined, 'SIGKILL']);
+});

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

@@ -0,0 +1,3 @@
+export function proofIndexHtml() {
+  return '<!doctype html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><link rel="icon" href="data:,"></head><body><div id="root"></div><script type="module" src="/src/main.tsx"></script></body></html>';
+}

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

@@ -0,0 +1,9 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { proofIndexHtml } from './react-proof-page.mjs';
+
+test('proof page supplies an inline favicon so the browser makes no missing-file request', () => {
+  const html = proofIndexHtml();
+  assert.match(html, /<link rel="icon" href="data:,">/);
+  assert.match(html, /<script type="module" src="\/src\/main\.tsx"><\/script>/);
+});

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

@@ -0,0 +1,37 @@
+// The canvas look is part of the skill's contract: thin lines and a dotted background, both set by tokens
+// an app can override. These tests pin the defaults so a later edit cannot quietly bring back the grid.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const css = readFileSync(join(root, "src/styles.css"), "utf8");
+
+test("the canvas background is dots, not grid lines", () => {
+  assert.match(css, /#viewport[\s\S]*radial-gradient\(circle, var\(--dot\) var\(--dot-size\)/);
+  assert.doesNotMatch(css, /linear-gradient\(var\(--grid\)/, "grid lines must not come back");
+});
+
+test("dots are set by tokens: size, spacing and a colour for light and dark", () => {
+  assert.match(css, /--dot-size:\s*1\.2px/);
+  assert.match(css, /--dot-gap:\s*24px/);
+  const colours = css.match(/--dot:\s*rgba\([^)]*\)/g) ?? [];
+  assert.ok(colours.length >= 3, "a dot colour for light, dark by media query and dark by attribute");
+});
+
+test("links are thin by default and every width comes from a token", () => {
+  assert.match(css, /--edge-w:\s*1\.1px/);
+  assert.match(css, /path\.edge \{ fill:none; stroke-width:var\(--edge-w\)/);
+  assert.match(css, /path\.edge\.hot \{[^}]*stroke-width:var\(--edge-w-hot\)/);
+  assert.match(css, /path\.trail \{[^}]*stroke-width:calc\(var\(--trail-w\)/);
+  assert.match(css, /path\.ripple \{[^}]*stroke-width:calc\(var\(--ripple-w\)/);
+  // Thin means at most 1.5 px for a plain link and 2 px for the highlighted one.
+  const w = (name) => Number(css.match(new RegExp(`${name}:\s*([0-9.]+)px`))[1]);
+  assert.ok(w("--edge-w") <= 1.5 && w("--edge-w-hot") <= 2 && w("--ripple-w") <= 2.5 && w("--trail-w") <= 2.5);
+});
+
+test("forced-colours mode drops the dot pattern", () => {
+  assert.match(css, /@media \(forced-colors: active\) \{ #viewport \{ background: Canvas; \} \}/);
+});