@caddis/cli 0.4.44 → 0.4.46

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 }); }
+});

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

@@ -0,0 +1,54 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+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();
+  const urls = html.match(/https?:\/\/[^\s"'<>)\\]+/g) ?? [];
+  const external = urls.filter(u => u !== "http://www.w3.org/2000/svg");
+  assert.deepEqual(external, [], "external URL found");
+  assert.ok(!html.includes("/*__CSS__*/") && !html.includes("/*__ENGINE__*/"));
+  assert.equal(html.split("/*__MODEL__*/{}").length - 1, 1);
+  assert.equal(html.split("/*__NOTES__*/[]").length - 1, 1);
+});
+test("the engine bundle cannot end its own script tag", async () => {
+  const html = await buildEngine();
+  const scripts = html.match(/<\/script>/g) ?? [];
+  assert.equal(scripts.length, 3, "exactly the three script tags of the shell");
+});
+test("the committed engine matches the sources", async () => {
+  const fresh = await buildEngine();
+  const committed = normalise(readFileSync(new URL("../../templates/engine.html", import.meta.url), "utf8"));
+  assert.equal(committed, fresh, "run: node --experimental-strip-types scripts/build-engine.mjs");
+});

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

@@ -0,0 +1,135 @@
+// Proves the checks can fail: each fixture is a page with one deliberate defect, and check.mjs must exit 1
+// and name the matching check. Skipped when Playwright cannot be resolved from the current folder.
+// 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, after } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { embedModel } from "./embed.mjs";
+
+const root = resolve(fileURLToPath(import.meta.url), "../../..");
+let hasPlaywright = true;
+try { createRequire(join(process.cwd(), "x.js")).resolve("playwright"); } catch { hasPlaywright = false; }
+const skip = hasPlaywright ? false : "playwright is not resolvable from the current folder";
+
+const engine = readFileSync(join(root, "templates/engine.html"), "utf8");
+const base = JSON.parse(readFileSync(join(root, "examples/lineage.json"), "utf8"));
+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>`);
+  const p = join(dir, name + ".html");
+  writeFileSync(p, html);
+  return p;
+}
+function run(p) {
+  const args = [join(root, "scripts/check.mjs"), p, "--out", join(dir, "shots"), "--viewports", "1600x900", "--skip-perf"];
+  if (process.env.FLOW_STUDIO_CHANNEL) args.push("--channel", process.env.FLOW_STUDIO_CHANNEL);
+  return spawnSync(process.execPath, args, { encoding: "utf8", cwd: process.cwd(), timeout: 120000 });
+}
+const expectFail = (r, pattern) => {
+  assert.equal(r.status, 1, r.stdout + r.stderr);
+  assert.match(r.stdout, new RegExp("FAIL.*" + pattern, "i"), r.stdout);
+};
+
+test("a clean page passes every check", { skip }, () => {
+  const r = run(page("clean"));
+  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
+  const a = m.nodes.find(n => n.id === "J_W47"), b = m.nodes.find(n => n.id === "J_BILL");
+  b.row = a.row; // same column, same row
+  expectFail(run(page("overlap", { model: m })), "zero node-box intersections");
+});
+
+test("a control with no name fails the accessible-name check", { skip }, () => {
+  const inject = `<script>window.addEventListener("load", () => setTimeout(() => { const b = document.querySelector("#tools button"); b.removeAttribute("aria-label"); b.removeAttribute("title"); }, 300));</script>`;
+  expectFail(run(page("noname", { inject })), "accessible name");
+});
+
+test("a remote image fails the no-network check", { skip }, () => {
+  expectFail(run(page("remote", { inject: `<img src="https://example.invalid/x.png" alt="">` })), "no network requests");
+});
+
+test("faint text fails the contrast check", { skip }, () => {
+  expectFail(run(page("faint", { inject: `<style>.node .s, .node .name { color:#d8d8d8 !important; }</style>` })), "contrast");
+});
+
+test("a looping animation under reduced motion fails the reduced-motion check", { skip }, () => {
+  expectFail(run(page("motion", { inject: `<style>@media (prefers-reduced-motion: reduce) { .node { animation: rise 1s infinite !important; } }</style>` })), "reduced motion");
+});
+
+test("a canvas too wide to read fails the first-view check", { skip }, () => {
+  const m = structuredClone(base);
+  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

@@ -0,0 +1,179 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+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) =>
+  spawnSync(process.execPath, ["--experimental-strip-types", "--no-warnings", join(root, "scripts", script), ...args], { encoding: "utf8" });
+
+const good = {
+  version: 1,
+  meta: { title: "T", help: "h", asOf: "2026-01-01", source: "s" },
+  layout: "columns-lanes",
+  columns: [{ id: "c0", title: "A", width: 150 }, { id: "c1", title: "B", width: 150 }],
+  lanes: [{ id: "l1", title: "Lane" }],
+  states: { ok: { word: "OK", tone: "ok", border: "solid", edge: "flow", motion: "flow", bucket: "good" } },
+  nodes: [
+    { id: "a", kind: "card", lane: "l1", col: 0, row: 0, state: "ok", title: "A" },
+    { id: "b", kind: "card", lane: "l1", col: 1, row: 0, state: "ok", title: "B" },
+  ],
+  links: [{ id: "a-b", from: "a", to: "b", state: "ok" }],
+};
+const dir = mkdtempSync(join(tmpdir(), "flow-studio-"));
+const write = (name, value) => { const p = join(dir, name); writeFileSync(p, typeof value === "string" ? value : JSON.stringify(value)); return p; };
+
+test("validate: a good model exits 0 and prints OK", () => {
+  const r = run("validate.mjs", write("good.json", good));
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /OK/);
+});
+test("validate: a missing file exits 2", () => assert.equal(run("validate.mjs", join(dir, "nope.json")).status, 2));
+test("validate: invalid JSON exits 2", () => assert.equal(run("validate.mjs", write("bad.json", "{not json")).status, 2));
+test("validate: a link to a missing node exits 1 and names the link", () => {
+  const m = structuredClone(good);
+  m.links[0].to = "zzz";
+  const r = run("validate.mjs", write("broken.json", m));
+  assert.equal(r.status, 1);
+  assert.match(r.stdout, /links\[a-b\]/);
+});
+test("build: a note file cannot override the numbering and must be an array", () => {
+  const out = join(dir, "out-notes.html");
+  const p = write("notes-model.json", good);
+  const notes = write("notes.json", [{ id: 99, anchor: "#viewport", title: "One", text: "t" }, { anchor: "#tools", title: "Two", text: "t" }]);
+  // the build needs the generated engine; this test only needs it to exist
+  const r = run("build.mjs", p, out, "--notes", notes);
+  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" });
+  assert.equal(run("build.mjs", p, join(dir, "out-bad.html"), "--notes", bad).status, 2);
+});
+test("build: refuses a model with errors and writes nothing", () => {
+  const m = structuredClone(good);
+  m.nodes[0].lane = "nope";
+  const out = join(dir, "out-refused.html");
+  const r = run("build.mjs", write("refused.json", m), out);
+  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);
+});