@caddis/cli 0.4.44 → 0.4.46

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/embed.mjs

@@ -0,0 +1,24 @@
+// Safe embedding of a model into the engine template.
+// JSON placed inside a <script> tag must not be able to close it or start markup, so the
+// characters < > & and the two Unicode line separators are written as \u escapes. The result is
+// still valid JSON and parses back to the same value.
+
+export function escapeJson(value) {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+const MODEL_SLOT = "/*__MODEL__*/{}";
+const NOTES_SLOT = "/*__NOTES__*/[]";
+
+export function embedModel(shell, model, notes = []) {
+  if (!shell.includes(MODEL_SLOT) || !shell.includes(NOTES_SLOT)) {
+    throw new Error("The shell is missing a model slot or a notes slot.");
+  }
+  // Replacer functions: a "$" in the data must never act as a replacement pattern.
+  return shell.replace(MODEL_SLOT, () => escapeJson(model)).replace(NOTES_SLOT, () => escapeJson(notes));
+}

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

@@ -0,0 +1,29 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { escapeJson, embedModel } from "./embed.mjs";
+
+const hostile = { t: "</script><script>window.pwned=1</script>", u: "<img src=x onerror=alert(1)>", q: `"'&`, ls: "a\u2028b\u2029c" };
+
+test("escapeJson leaves no markup characters and round-trips", () => {
+  const s = escapeJson(hostile);
+  assert.ok(!/[<>&\u2028\u2029]/.test(s));
+  assert.deepEqual(JSON.parse(s), hostile);
+});
+
+test("embedModel fills both slots and adds no script tag", () => {
+  const shell = `<script id="m" type="application/json">/*__MODEL__*/{}</script><script id="n" type="application/json">/*__NOTES__*/[]</script>`;
+  const out = embedModel(shell, hostile, [{ anchor: "#x", title: "<b>", text: "</script>" }]);
+  assert.equal((out.match(/<\/script>/g) ?? []).length, 2);
+  assert.equal((out.match(/<script/g) ?? []).length, 2);
+  assert.ok(!out.includes("/*__MODEL__*/") && !out.includes("/*__NOTES__*/"));
+});
+
+test("a dollar sign in the model is not treated as a replacement pattern", () => {
+  const shell = `<script>/*__MODEL__*/{}</script><script>/*__NOTES__*/[]</script>`;
+  const out = embedModel(shell, { p: "$1 and $$ and $` and $'" }, []);
+  assert.ok(out.includes("$1 and $$ and $` and $'"));
+});
+
+test("embedModel refuses a shell without the slots", () => {
+  assert.throws(() => embedModel("<html></html>", {}, []), /slot/i);
+});

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/react-proof.mjs

@@ -0,0 +1,92 @@
+// Build and test both React routes in a disposable application.
+// Run from the skill folder: node scripts/react-proof.mjs
+import { spawn, spawnSync } from 'node:child_process';
+import { cpSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createServer } from 'node:net';
+import { stopPreview } from './lib/react-proof-cleanup.mjs';
+import { proofIndexHtml } from './lib/react-proof-page.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const tmp = mkdtempSync(join(tmpdir(), 'flow-studio-react-proof-'));
+let preview;
+let previewClosed;
+
+function run(command, args, cwd = tmp) {
+  const result = spawnSync(command, args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' && command.toLowerCase().endsWith('npm.cmd'), env: process.env, timeout: 600_000 });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${command} ${args.join(' ')} exited ${result.status ?? result.signal}`);
+}
+
+async function freePort() {
+  return new Promise((resolvePort, reject) => {
+    const server = createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      server.close(() => resolvePort(address.port));
+    });
+  });
+}
+
+async function waitFor(url) {
+  for (let i = 0; i < 100; i++) {
+    if (preview.exitCode !== null) throw new Error(`vite preview exited ${preview.exitCode}`);
+    try { if ((await fetch(url)).ok) return; } catch { /* server still starting */ }
+    await new Promise(r => setTimeout(r, 100));
+  }
+  throw new Error(`vite preview did not start at ${url}`);
+}
+
+try {
+  mkdirSync(join(tmp, 'src'));
+  cpSync(join(root, 'react'), join(tmp, 'react'), { recursive: true });
+  // The React files use ../src imports. Keep the real source path in the throwaway app.
+  cpSync(join(root, 'src'), join(tmp, 'src'), { recursive: true });
+  mkdirSync(join(tmp, 'templates'));
+  for (const name of ['flow-studio.lib.mjs', 'flow-studio.lib.d.mts', 'flow-studio.css'])
+    cpSync(join(root, 'templates', name), join(tmp, 'templates', name));
+  mkdirSync(join(tmp, 'examples'));
+  cpSync(join(root, 'examples', 'order-desk.json'), join(tmp, 'examples', 'order-desk.json'));
+  writeFileSync(join(tmp, 'package.json'), JSON.stringify({
+    private: true, type: 'module', scripts: { test: 'vitest run', build: 'tsc --noEmit && vite build' },
+    dependencies: { react: '^18.3.1', 'react-dom': '^18.3.1' },
+    devDependencies: { '@testing-library/react': '^16.0.0', '@types/react': '^18.3.0', '@types/react-dom': '^18.3.0', jsdom: '^26.0.0', playwright: '^1.51.0', typescript: '^5.0.0', vite: '^6.0.0', vitest: '^3.0.0' },
+  }, null, 2));
+  writeFileSync(join(tmp, 'index.html'), proofIndexHtml());
+  writeFileSync(join(tmp, 'tsconfig.json'), JSON.stringify({ compilerOptions: {
+    target: 'ES2022', useDefineForClassFields: true, lib: ['ES2022', 'DOM', 'DOM.Iterable'], module: 'ESNext', skipLibCheck: true,
+    moduleResolution: 'Bundler', allowImportingTsExtensions: true, resolveJsonModule: true, isolatedModules: true,
+    noEmit: true, jsx: 'react-jsx', strict: true, types: ['vitest/globals'],
+  }, include: ['src', 'react', 'templates'], exclude: ['src/**/*.test.ts'] }, null, 2));
+  writeFileSync(join(tmp, 'src', 'App.tsx'), "import { FlowStudioView } from '../react/index.ts';\nimport model from '../examples/order-desk.json';\nimport '../templates/flow-studio.css';\nimport type { Model } from './model.ts';\nexport default function App() { return <FlowStudioView model={model as Model} />; }\n");
+  writeFileSync(join(tmp, 'src', 'main.tsx'), "import { StrictMode } from 'react';\nimport { createRoot } from 'react-dom/client';\nimport App from './App.tsx';\ncreateRoot(document.getElementById('root')!).render(<StrictMode><App /></StrictMode>);\n");
+  console.log(`Proof app: ${tmp}`);
+  // The browser checks launch a real browser. On Windows and when FLOW_STUDIO_CHANNEL is set,
+  // check.mjs uses a system browser (Edge or the named channel), so the Playwright browser
+  // download is skipped there. Everywhere else, let npm fetch Playwright's own browser, or the
+  // checks would fail on a clean machine that never downloaded one.
+  if (process.env.FLOW_STUDIO_CHANNEL || process.platform === 'win32') process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD ??= '1';
+  process.env.npm_config_cache = join(tmp, '.npm-cache');
+  run(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['install', '--no-audit', '--no-fund']);
+  run(process.execPath, [join(tmp, 'node_modules', 'vitest', 'vitest.mjs'), 'run', 'react/FlowStudioView.test.tsx', 'react/native/native.test.tsx', '--environment', 'jsdom']);
+  run(process.execPath, [join(tmp, 'node_modules', 'typescript', 'bin', 'tsc'), '--noEmit']);
+  run(process.execPath, [join(tmp, 'node_modules', 'vite', 'bin', 'vite.js'), 'build']);
+  const port = await freePort();
+  const address = `http://127.0.0.1:${port}/`;
+  preview = spawn(process.execPath, [join(tmp, 'node_modules', 'vite', 'bin', 'vite.js'), 'preview', '--host', '127.0.0.1', '--port', String(port), '--strictPort'], { cwd: tmp, stdio: 'inherit' });
+  previewClosed = new Promise(resolve => preview.once('close', resolve));
+  await waitFor(address);
+  const checkArgs = [join(root, 'scripts', 'check.mjs'), address, '--out', join(tmp, 'check-out'), '--skip', 'hostile'];
+  if (process.env.FLOW_STUDIO_CHANNEL || process.platform === 'win32') checkArgs.push('--channel', process.env.FLOW_STUDIO_CHANNEL ?? 'msedge');
+  run(process.execPath, checkArgs, tmp);
+  console.log('React proof passed.');
+} catch (error) {
+  console.error(`React proof failed: ${error.message}`);
+  process.exitCode = 1;
+} finally {
+  await stopPreview(preview, previewClosed);
+  rmSync(tmp, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+}

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

@@ -0,0 +1,42 @@
+// Validate a flow-studio model.
+//   node --experimental-strip-types scripts/validate.mjs <model.json>
+// Exit 0: no errors (warnings are printed). Exit 1: at least one error. Exit 2: cannot read the file.
+
+import { readFileSync } from "node:fs";
+import { validateModel } from "../src/model.ts";
+import { autoLayout } from "../src/autolayout.ts";
+import { prepareModel } from "./lib/auto-entry-guard.mjs";
+
+export function loadModel(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    console.error(`cannot read ${path}: ${e.message}`);
+    process.exit(2);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    console.error(`${path} is not valid JSON: ${e.message}`);
+    process.exit(2);
+  }
+}
+
+export function report(issues) {
+  for (const i of issues) console.log(`${i.level.toUpperCase().padEnd(5)} ${i.code.padEnd(16)} ${i.where}: ${i.message}`);
+  return issues.filter(i => i.level === "error").length;
+}
+
+if (process.argv[1]?.endsWith("validate.mjs")) {
+  const path = process.argv[2];
+  if (!path) {
+    console.error("usage: node --experimental-strip-types scripts/validate.mjs <model.json>");
+    process.exit(2);
+  }
+  const model = loadModel(path);
+  const ready = prepareModel(model, autoLayout);
+  const errors = report(validateModel(ready));
+  console.log(errors ? `${errors} error(s)` : "OK");
+  process.exit(errors ? 1 : 0);
+}

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

@@ -0,0 +1,78 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { autoLayout } from "./autolayout.ts";
+import { validateModel, type Model, type NodeDef } from "./model.ts";
+import { computeGeometry } from "./layout.ts";
+
+const node = (id: string, extra: Partial<NodeDef> = {}): NodeDef => ({ id, kind: "card", state: "ok", title: id, ...extra } as NodeDef);
+const model = (ids: string[], pairs: [string, string][]): Model => ({
+  version: 1, meta: { title: "t", help: "", asOf: "", source: "" }, layout: "auto", columns: [], lanes: [],
+  states: { ok: { word: "OK", tone: "ok", border: "solid", edge: "flow", motion: "flow", bucket: "good" } },
+  nodes: ids.map(id => node(id)), links: pairs.map(([from, to], i) => ({ id: `e${i}`, from, to, state: "ok" })),
+});
+const errors = (m: Model) => validateModel(m).filter(i => i.level === "error");
+
+test("chain gets longest path columns and generated stages", () => {
+  const out = autoLayout(model(["a", "b", "c"], [["a", "b"], ["b", "c"]]));
+  assert.deepEqual(out.nodes.map(n => n.col), [0, 1, 2]);
+  assert.deepEqual(out.columns.map(c => c.title), ["Stage 1", "Stage 2", "Stage 3"]);
+  assert.deepEqual(errors(out), []);
+});
+test("fork and join ranks the join after both branches", () => {
+  const out = autoLayout(model(["a", "b", "c", "d"], [["a", "b"], ["a", "c"], ["b", "d"], ["c", "d"]]));
+  assert.equal(out.nodes.find(n => n.id === "d")?.col, 2);
+  assert.equal(out.nodes.find(n => n.id === "b")?.col, 1);
+  assert.equal(out.nodes.find(n => n.id === "c")?.col, 1);
+  assert.deepEqual(errors(out), []);
+});
+test("a three cycle yields exactly one feedback edge and consistent ranks", () => {
+  const out = autoLayout(model(["a", "b", "c"], [["a", "b"], ["b", "c"], ["c", "a"]]));
+  assert.deepEqual(out.links.filter(l => l.kind === "loop-back").map(l => l.id), ["e2"]);
+  assert.deepEqual(out.nodes.map(n => n.col), [0, 1, 2]);
+  assert.deepEqual(errors(out), []);
+});
+test("disconnected parts get synthetic lanes in first appearance order", () => {
+  const out = autoLayout(model(["a", "b", "c", "d"], [["a", "b"], ["c", "d"]]));
+  assert.deepEqual(out.lanes.map(l => l.title), ["Group 1", "Group 2"]);
+  assert.equal(out.nodes[0]?.lane, out.nodes[1]?.lane);
+  assert.equal(out.nodes[2]?.lane, out.nodes[3]?.lane);
+  assert.notEqual(out.nodes[0]?.lane, out.nodes[2]?.lane);
+  const lanes = Object.values(computeGeometry(out).lanes).sort((a, b) => a.y - b.y);
+  assert.ok(lanes[0]!.y + lanes[0]!.h <= lanes[1]!.y);
+});
+test("author fixed column and row stay fixed and successors rank from them", () => {
+  const m = model(["a", "b", "c"], [["a", "b"], ["b", "c"]]);
+  m.nodes[1]!.col = 4; m.nodes[1]!.row = 7;
+  const out = autoLayout(m);
+  assert.equal(out.nodes[1]?.col, 4);
+  assert.equal(out.nodes[1]?.row, 7);
+  assert.equal(out.nodes[2]?.col, 5);
+  assert.equal(out.columns.length, 6);
+  assert.deepEqual(errors(out), []);
+});
+test("ordering lowers crossings on a reversed two-edge example", () => {
+  const m = model(["a", "b", "d", "c"], [["a", "c"], ["b", "d"]]);
+  m.nodes[0]!.col = 0; m.nodes[1]!.col = 0; m.nodes[2]!.col = 1; m.nodes[3]!.col = 1;
+  m.nodes.forEach(n => n.lane = "one"); m.lanes = [{ id: "one", title: "One" }];
+  const out = autoLayout(m), byId = new Map(out.nodes.map(n => [n.id, n]));
+  const crossing = (a: string, b: string, c: string, d: string): boolean =>
+    ((byId.get(a)!.row! - byId.get(c)!.row!) * (byId.get(b)!.row! - byId.get(d)!.row!)) < 0;
+  assert.equal(crossing("a", "c", "b", "d"), false);
+  assert.deepEqual(errors(out), []);
+});
+test("same input gives equal output without changing input", () => {
+  const m = model(["a", "b", "c"], [["a", "b"], ["b", "c"]]);
+  const before = JSON.stringify(m);
+  assert.deepEqual(autoLayout(m), autoLayout(m));
+  assert.equal(JSON.stringify(m), before);
+});
+test("seeded 200 node graph finishes under 300ms and validates", () => {
+  const ids = Array.from({ length: 200 }, (_, i) => `n${i}`);
+  let seed = 39;
+  const rnd = () => { seed = (1664525 * seed + 1013904223) >>> 0; return seed / 0x100000000; };
+  const pairs: [string, string][] = ids.slice(1).map((id, i) => [ids[i]!, id]);
+  for (let i = 0; i < 200; i++) pairs.push([ids[Math.floor(rnd() * ids.length)]!, ids[Math.floor(rnd() * ids.length)]!]);
+  const m = model(ids, pairs), start = performance.now(), out = autoLayout(m);
+  assert.ok(performance.now() - start < 300);
+  assert.deepEqual(errors(out), []);
+});

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

@@ -0,0 +1,132 @@
+// Deterministic placement for models without authored grid positions. No DOM and no input mutation.
+import type { Model, NodeDef, LinkDef } from "./model.ts";
+
+export function autoLayout(input: Model): Model {
+  const nodes = input.nodes.map(n => ({ ...n }));
+  const links = input.links.map(l => ({ ...l }));
+  const columns = input.columns.map(c => ({ ...c }));
+  const lanes = input.lanes.map(l => ({ ...l }));
+  const byId = new Map(nodes.map(n => [n.id, n]));
+  const index = new Map(nodes.map((n, i) => [n.id, i]));
+  const outgoing = new Map(nodes.map(n => [n.id, [] as LinkDef[]]));
+  const incoming = new Map(nodes.map(n => [n.id, [] as LinkDef[]]));
+  const neighbours = new Map(nodes.map(n => [n.id, [] as string[]]));
+  for (const link of links) {
+    if (!byId.has(link.from) || !byId.has(link.to)) continue;
+    outgoing.get(link.from)!.push(link);
+    incoming.get(link.to)!.push(link);
+    neighbours.get(link.from)!.push(link.to);
+    neighbours.get(link.to)!.push(link.from);
+  }
+
+  // A gray target is on the active DFS stack. Mark that edge as feedback.
+  const color = new Map<string, number>();
+  const post: string[] = [];
+  for (const root of nodes) {
+    if (color.has(root.id)) continue;
+    color.set(root.id, 1);
+    const stack: { id: string; next: number }[] = [{ id: root.id, next: 0 }];
+    while (stack.length) {
+      const frame = stack[stack.length - 1]!;
+      const edges = outgoing.get(frame.id)!;
+      if (frame.next >= edges.length) {
+        color.set(frame.id, 2); post.push(frame.id); stack.pop(); continue;
+      }
+      const link = edges[frame.next++]!;
+      if (link.kind === "loop-back") continue;
+      const state = color.get(link.to) ?? 0;
+      if (state === 1) link.kind = "loop-back";
+      else if (state === 0) { color.set(link.to, 1); stack.push({ id: link.to, next: 0 }); }
+    }
+  }
+
+  // Reverse finishing order is topological after feedback edges are removed.
+  for (const id of post.reverse()) {
+    const n = byId.get(id)!;
+    if (n.col !== undefined) continue;
+    let col = 0;
+    for (const edge of incoming.get(id)!) {
+      if (edge.kind === "loop-back") continue;
+      const parent = byId.get(edge.from)!;
+      col = Math.max(col, (parent.col ?? 0) + (parent.colSpan ?? 1));
+    }
+    n.col = col;
+  }
+
+  // Missing lane membership is grouped by weak connection, including feedback edges.
+  const seen = new Set<string>();
+  const usedLaneIds = new Set(lanes.map(l => l.id));
+  let group = 0;
+  for (const first of nodes) {
+    if (seen.has(first.id)) continue;
+    const queue = [first.id]; seen.add(first.id);
+    for (let q = 0; q < queue.length; q++) {
+      for (const id of neighbours.get(queue[q]!)!) if (!seen.has(id)) { seen.add(id); queue.push(id); }
+    }
+    const missing = queue.map(id => byId.get(id)!).filter(n => !n.lane);
+    if (!missing.length) continue;
+    group++;
+    let laneId = `group-${group}`;
+    while (usedLaneIds.has(laneId)) laneId += "-auto";
+    usedLaneIds.add(laneId);
+    lanes.push({ id: laneId, title: `Group ${group}` });
+    for (const n of missing) n.lane = laneId;
+  }
+
+  // Start in input order. Four alternating sweeps sort each lane and layer by
+  // neighbour barycentre. Stable input order resolves every tie.
+  const rank = new Map(nodes.map((n, i) => [n.id, i]));
+  const laneOrder = lanes.map(l => l.id);
+  const cells = new Map<string, NodeDef[]>();
+  for (const n of nodes) {
+    const key = `${n.lane}\0${n.col}`;
+    if (!cells.has(key)) cells.set(key, []);
+    cells.get(key)!.push(n);
+  }
+  const maxCol = Math.max(0, ...nodes.map(n => (n.col ?? 0) + (n.colSpan ?? 1) - 1));
+  for (let sweep = 0; sweep < 4; sweep++) {
+    const forward = sweep % 2 === 0;
+    const layers = Array.from({ length: maxCol + 1 }, (_, i) => forward ? i : maxCol - i);
+    for (const lane of laneOrder) for (const col of layers) {
+      const groupNodes = cells.get(`${lane}\0${col}`);
+      if (!groupNodes || groupNodes.length < 2) continue;
+      const score = (n: NodeDef): number => {
+        const edges = forward ? incoming.get(n.id)! : outgoing.get(n.id)!;
+        const ns = edges.filter(e => e.kind !== "loop-back").map(e => forward ? e.from : e.to);
+        return ns.length ? ns.reduce((sum, id) => sum + (rank.get(id) ?? 0), 0) / ns.length : (rank.get(n.id) ?? 0);
+      };
+      groupNodes.sort((a, b) => score(a) - score(b) || (index.get(a.id)! - index.get(b.id)!));
+      groupNodes.forEach((n, i) => rank.set(n.id, i));
+    }
+  }
+
+  // Place lanes in separate row ranges. A cell can share a row with another
+  // column, but nodes whose column spans intersect need a full row of space.
+  let nextBase = 0;
+  const placed: NodeDef[] = nodes.filter(n => n.row !== undefined);
+  for (const lane of laneOrder) {
+    const members = nodes.filter(n => n.lane === lane);
+    if (!members.length) continue;
+    const ordered = [...members].sort((a, b) => (a.col ?? 0) - (b.col ?? 0) || (rank.get(a.id) ?? 0) - (rank.get(b.id) ?? 0) || index.get(a.id)! - index.get(b.id)!);
+    const rowAtCol = new Map<number, number>();
+    for (const n of ordered) {
+      if (n.row !== undefined) continue;
+      let row = Math.max(nextBase, rowAtCol.get(n.col ?? 0) ?? nextBase);
+      while (placed.some(p => (n.col ?? 0) < (p.col ?? 0) + (p.colSpan ?? 1)
+        && (p.col ?? 0) < (n.col ?? 0) + (n.colSpan ?? 1) && Math.abs(row - (p.row ?? 0)) < 1)) row += 1;
+      n.row = row;
+      placed.push(n);
+      rowAtCol.set(n.col ?? 0, row + 1);
+    }
+    const last = Math.max(nextBase - 1, ...members.map(n => n.row ?? 0));
+    const loops = links.filter(l => l.kind === "loop-back" && byId.get(l.from)?.lane === lane && byId.get(l.to)?.lane === lane).length;
+    nextBase = last + 1.75 + loops * 0.35;
+  }
+
+  const needed = Math.max(0, ...nodes.map(n => (n.col ?? 0) + (n.colSpan ?? 1)));
+  while (columns.length < needed) {
+    const i = columns.length + 1;
+    columns.push({ id: `stage-${i}`, title: `Stage ${i}`, width: 190 });
+  }
+  return { ...input, nodes, links, columns, lanes };
+}