@caddis/cli 0.4.45 → 0.4.47

package/bundles/codex/.codex/skills/frontend/flow-studio/references/verify.md

@@ -0,0 +1,124 @@
+# Verification harness reference
+
+`scripts/check.mjs` is the automated headless browser testing harness for flow-studio pages. It drives Chromium via Playwright, interrogates page geometry and accessibility trees, tests user interactions, and asserts visual and behavioral invariants.
+
+## 1. CLI usage and options
+
+```bash
+# Run against a local build
+node scripts/check.mjs out/lineage.html
+
+# Run with custom output directory and viewports
+node scripts/check.mjs out/lineage.html --out check-out --viewports 1600x900,1280x720,820x900
+
+# Specify browser channel and skip optional groups
+node scripts/check.mjs out/lineage.html --channel msedge --skip notes,playback,update,hostile
+
+# Test hostile payload safety
+node scripts/check.mjs out/lineage.html --hostile out/hostile.html --json report.json
+
+# Skip performance benchmarking
+node scripts/check.mjs out/lineage.html --skip-perf
+```
+
+### CLI options
+- `<page.html | URL>`: File path or HTTP URL to the target page.
+- `--out <dir>`: Directory where screenshots and failure captures are saved (default: `check-out`).
+- `--viewports <WxH,...>`: Comma-separated list of test viewports (default: `1600x900,1280x720,820x900`).
+- `--channel <name>`: Browser executable channel (e.g. `msedge`, `chrome`).
+- `--skip <groups>`: Comma-separated list of test groups to skip (`notes`, `playback`, `update`, `hostile`). A skipped group is not a pass: skip one only when the page intentionally omits that feature, and record every skip in your verification notes.
+- `--hostile <file.html>`: Path to hostile test page to assert XSS and injection resistance.
+- `--json <file.json>`: Output machine-readable test results to a JSON report.
+- `--skip-perf`: Omit render and zoom frame timing performance assertions.
+
+---
+
+## 2. Check groups and assertions
+
+`scripts/check.mjs` organizes assertions into distinct groups:
+
+### 1. `structural`
+Validates that layout geometry satisfies visual clarity:
+- **Zero node-box intersections:** No two node bounding boxes overlap or intersect.
+- **Node inside lane:** Every node sits completely within its designated swimlane boundaries.
+- **No lane overlap:** Swimlanes do not collide vertically.
+- **Links touch node boxes:** Link start points and end points connect cleanly to their endpoint boxes without gaps or overshoots.
+- **Fit shows every node:** Canvas auto-fit places all nodes fully within the visible viewport bounds.
+- **Hidden nodes not painted:** Collapsed or view-filtered nodes have `visibility: hidden` and `opacity: 0`.
+
+### 2. `interaction`
+Validates user input, navigation, and state machines:
+- **Wheel zoom & pan:** Canvas zooms centered on the mouse position; zoom is clamped between 0.25x and 2.5x.
+- **Key navigation:** `0` fits canvas, arrow keys pan the viewport, `Escape` clears selection and closes the inspector.
+- **Group expansion / collapse:** Clicking expand/collapse buttons toggles child visibility and updates visible node counts.
+- **Node selection:** Clicking a node selects it, highlights connected edges, and slides open `#inspector`.
+- **N-hop search:** Searching terms highlights matches and dims non-matching nodes; increasing hops expands the lit radius.
+- **What-if simulation:** Clicking what-if buttons cascades simulated failure states through downstream dependents.
+- **View switcher:** Toggling views displays only elements specified in `visibleIn`.
+
+### 3. `a11y` (Accessibility)
+Validates compliance with WCAG 2.2 AA standards:
+- **Accessible names:** Every button, input, tab, and control has a non-empty `aria-label` or accessible text name.
+- **Keyboard navigation:** Visible nodes receive focus via Tab; hidden nodes are not reachable via Tab. No keyboard traps.
+- **Focus visibility:** Focused nodes display an active outline.
+- **Contrast ratios:** Normal text has at least 4.5:1 contrast against surface backgrounds in both light and dark themes.
+- **Table view:** An accessible `<table class="sources" id="tbl">` lists all visible graph nodes for screen reader users.
+- **Reduced motion:** `prefers-reduced-motion` disables all transitions and animations, setting edge dashes static.
+
+### 4. `safety`
+Validates security against hostile content and network isolation:
+- **No unhandled page errors:** Zero unhandled JavaScript exceptions in the console.
+- **No external network requests:** Zero external HTTP/HTTPS requests (local and standalone execution).
+- **Hostile string escaping:** Malicious HTML (`</script>`, `<img onerror=...>`, Unicode separators) is rendered as plain text without script execution or DOM injection.
+
+### 5. `performance`
+Validates responsiveness and frame timing:
+- **First render time:** Initial canvas render of all nodes must complete in under 500 ms.
+- **Frame budget:** 95th percentile wheel event handling time must be under 16 ms (60 fps threshold).
+- **Self-contained bundle size:** Generated single-file HTML pages must stay under 300 KB.
+
+### 6. `notes`
+Validates the implementation notes drawer:
+- In notes mode, numbered markers appear for every valid anchor.
+- Hovering and clicking markers coordinates with drawer cards.
+
+### 7. `playback`
+Validates scenario animation:
+- Stepping moves the active token along specified links in sequence.
+- Decision gateways show branch choice buttons in step mode.
+- SLA breaches trigger red counter highlighting and failure flash styling.
+
+### 8. `update`
+Validates live graph data updates:
+- Calling `FlowStudio.update(newModel)` updates topology while preserving pan, zoom, and active selection.
+- Invalid model updates preserve the previous valid DOM state and render `#banner` error notice.
+
+### 9. `hostile`
+Validates adversarial resistance:
+- Ingests `examples/hostile.json` to prove the parser and inspector remain inert against script injection.
+
+---
+
+## 3. Thresholds and limits
+
+| Metric / Check | Threshold | Rationale |
+|---|---|---|
+| First render duration | `< 500 ms` | Fast initial load experience |
+| Wheel event latency (p95) | `< 16 ms` | Smooth 60fps pan and zoom interaction |
+| Zoom range | `0.25` to `2.5` | Prevents disorientation from extreme zoom levels |
+| Contrast ratio | `>= 4.5:1` | WCAG AA readability in light and dark modes |
+| Node count guideline | `8` to `30` initial visible | Avoids visual clutter in default fit |
+| HTML bundle size | `< 300 KB` | Portable, zero-dependency self-contained distribution |
+
+---
+
+## 4. Reading failures and fixing issues
+
+When a check fails, the harness logs:
+```text
+FAIL  [structural] 1600x900 zero node-box intersections  crm-db/cdc-pipe
+```
+1. **Identify the group and viewport:** Here, `structural` at `1600x900`.
+2. **Read the detail payload:** The detail string lists the offending nodes (`crm-db` and `cdc-pipe`).
+3. **Inspect the screenshot:** Open `check-out/01-fit-1600x900.png` to inspect the visual collision.
+4. **Apply the fix:** Adjust the column width or node row/slot positions in `model.json`, then re-run `node scripts/check.mjs`.

package/bundles/codex/.codex/skills/frontend/flow-studio/scripts/build-engine.mjs

@@ -1,8 +1,8 @@
 // Build templates/engine.html from the TypeScript sources.
 //   node --experimental-strip-types scripts/build-engine.mjs           write templates/engine.html
 //   node --experimental-strip-types scripts/build-engine.mjs --check   exit 1 if the committed file is stale
-// esbuild is a dev-time tool. It is looked up in this folder, in the caddis cli folder, then in the
-// current directory. The built page has no dependency on it.
+// esbuild is a dev-time tool. It is looked up in FLOW_STUDIO_NODE_MODULES first, then this folder,
+// the caddis cli folder, and the current directory. The built page has no dependency on it.
 
 import { createRequire } from "node:module";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
@@ -12,13 +12,23 @@ import { fileURLToPath } from "node:url";
 const here = dirname(fileURLToPath(import.meta.url));
 const root = resolve(here, "..");
 
-function loadEsbuild() {
-  const candidates = [join(root, "package.json"), resolve(root, "../../../../cli/package.json"), join(process.cwd(), "package.json")];
-  for (const c of candidates) {
-    if (!existsSync(dirname(c))) continue;
-    try { return createRequire(c)("esbuild"); } catch { /* try the next place */ }
+export function resolveEsbuild(candidateDirs, requireFactory = createRequire) {
+  for (const dir of candidateDirs) {
+    if (!existsSync(dir)) continue;
+    try { return requireFactory(join(dir, "package.json"))("esbuild"); } catch { /* try the next place */ }
   }
-  throw new Error("esbuild was not found. Run `npm i -D esbuild` in the skill folder, or run this from the caddis checkout (cli/node_modules has it).");
+  throw new Error("esbuild was not found. Check FLOW_STUDIO_NODE_MODULES or run `npm i -D esbuild` in the skill folder.");
+}
+
+function loadEsbuild() {
+  const configured = process.env.FLOW_STUDIO_NODE_MODULES;
+  const candidates = [
+    ...(configured ? [configured] : []),
+    root,
+    resolve(root, "../../../../cli"),
+    process.cwd(),
+  ];
+  return resolveEsbuild(candidates);
 }
 
 const normalise = text => text.replace(/\r\n/g, "\n");
@@ -26,7 +36,7 @@ const normalise = text => text.replace(/\r\n/g, "\n");
 export async function buildEngine() {
   const esbuild = loadEsbuild();
   const out = await esbuild.build({
-    entryPoints: [join(root, "src/engine.ts")],
+    entryPoints: [join(root, "src/page.ts")],
     bundle: true, format: "iife", target: "es2022", minify: false, write: false, legalComments: "none", logLevel: "silent",
   });
   const js = out.outputFiles[0].text;
@@ -35,20 +45,50 @@ export async function buildEngine() {
   if (/<\/style/i.test(css)) throw new Error("The stylesheet contains a closing style tag; it would end the page style early.");
   if (css.includes("/*__ENGINE__*/") || css.includes("/*__MODEL__*/") || css.includes("/*__NOTES__*/")) throw new Error("The stylesheet contains a template slot marker.");
   const shell = readFileSync(join(root, "templates/engine.shell.html"), "utf8");
-  for (const slot of ["/*__CSS__*/", "/*__ENGINE__*/", "/*__MODEL__*/{}", "/*__NOTES__*/[]"]) {
+  for (const slot of ["/*__CSS__*/", "/*__SHELL_BODY__*/", "/*__ENGINE__*/", "/*__MODEL__*/{}", "/*__NOTES__*/[]"]) {
     if (!shell.includes(slot)) throw new Error(`The shell is missing the slot ${slot}`);
   }
-  return normalise(shell.replace("/*__CSS__*/", () => css).replace("/*__ENGINE__*/", () => js));
+  const body = readFileSync(join(root, "templates/shell-body.html"), "utf8");
+  return normalise(shell.replace("/*__CSS__*/", () => css).replace("/*__SHELL_BODY__*/", () => body).replace("/*__ENGINE__*/", () => js));
+}
+
+export async function buildLibrary() {
+  const esbuild = loadEsbuild();
+  const out = await esbuild.build({
+    entryPoints: [join(root, "src/lib.ts")], bundle: true, format: "esm", target: "es2022",
+    minify: false, write: false, legalComments: "none", logLevel: "silent",
+  });
+  const marker = JSON.stringify("/*__SHELL_BODY__*/");
+  const bundled = out.outputFiles[0].text;
+  if (bundled.split(marker).length !== 2) throw new Error("The library must contain one shell body slot.");
+  const body = readFileSync(join(root, "templates/shell-body.html"), "utf8");
+  const js = bundled.replace(marker, () => JSON.stringify(body));
+  const css = readFileSync(join(root, "src/styles.css"), "utf8");
+  return { js: normalise(js), css };
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   const target = join(root, "templates/engine.html");
-  const html = await buildEngine();
+  const libTarget = join(root, "templates/flow-studio.lib.mjs");
+  const cssTarget = join(root, "templates/flow-studio.css");
   if (process.argv.includes("--check")) {
+    const html = await buildEngine();
+    const { js, css } = await buildLibrary();
     const have = existsSync(target) ? normalise(readFileSync(target, "utf8")) : "";
-    if (have !== html) { console.error("templates/engine.html is stale. Run: node --experimental-strip-types scripts/build-engine.mjs"); process.exit(1); }
-    console.log("templates/engine.html is up to date");
+    const haveLib = existsSync(libTarget) ? normalise(readFileSync(libTarget, "utf8")) : "";
+    const haveCss = existsSync(cssTarget) ? readFileSync(cssTarget, "utf8") : "";
+    if (have !== html || haveLib !== js || haveCss !== css) {
+      console.error("Generated engine or library files are stale. Run `node --experimental-strip-types scripts/build-engine.mjs` and `node --experimental-strip-types scripts/build-engine.mjs --lib`.");
+      process.exit(1);
+    }
+    console.log("engine and library files are up to date");
+  } else if (process.argv.includes("--lib")) {
+    const { js, css } = await buildLibrary();
+    writeFileSync(libTarget, js, "utf8");
+    writeFileSync(cssTarget, css, "utf8");
+    console.log(`wrote templates/flow-studio.lib.mjs and templates/flow-studio.css`);
   } else {
+    const html = await buildEngine();
     writeFileSync(target, html, "utf8");
     console.log(`wrote templates/engine.html (${html.length} bytes)`);
   }

package/bundles/codex/.codex/skills/frontend/flow-studio/scripts/build.mjs

@@ -1,25 +1,32 @@
 // Build one self-contained HTML page from a model.
-//   node --experimental-strip-types scripts/build.mjs <model.json> <out.html> [--notes notes.json]
+//   node --experimental-strip-types scripts/build.mjs <model.json> <out.html> [--notes notes.json] [--demo-pack]
 // The model is validated first. Any error stops the build (exit 1). Warnings are printed.
 
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { validateModel } from "../src/model.ts";
+import { autoLayout } from "../src/autolayout.ts";
 import { embedModel } from "./lib/embed.mjs";
+import { prepareModel } from "./lib/auto-entry-guard.mjs";
+import { keepDefaultNotes } from "./lib/demo-pack.mjs";
 import { loadModel, report } from "./validate.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const args = process.argv.slice(2);
+const demoPackIndex = args.indexOf("--demo-pack");
+const demoPack = demoPackIndex >= 0;
+if (demoPack) args.splice(demoPackIndex, 1);
 const notesAt = args.indexOf("--notes");
 const notesPath = notesAt >= 0 ? args.splice(notesAt, 2)[1] : null;
 const [modelPath, outPath] = args;
 if (!modelPath || !outPath) {
-  console.error("usage: node --experimental-strip-types scripts/build.mjs <model.json> <out.html> [--notes notes.json]");
+  console.error("usage: node --experimental-strip-types scripts/build.mjs <model.json> <out.html> [--notes notes.json] [--demo-pack]");
   process.exit(2);
 }
 
-const model = loadModel(modelPath);
+const input = loadModel(modelPath);
+const model = prepareModel(input, autoLayout);
 const errors = report(validateModel(model));
 if (errors) {
   console.error(`${errors} error(s): not building.`);
@@ -30,8 +37,18 @@ if (notesPath && !Array.isArray(extra)) {
   console.error(`${notesPath} must be a JSON array of notes.`);
   process.exit(2);
 }
-const notes = [...(Array.isArray(model.notes) ? model.notes : []), ...(Array.isArray(extra) ? extra : [])].map((n, i) => ({ ...n, id: i + 1 }));
+
 const shell = readFileSync(resolve(here, "../templates/engine.html"), "utf8");
+
+let defaultNotes = [];
+if (demoPack) {
+  const defaults = loadModel(resolve(here, "default-notes.json"));
+  if (Array.isArray(defaults)) {
+    defaultNotes = keepDefaultNotes(defaults, model, shell);
+  }
+}
+
+const notes = [...defaultNotes, ...(Array.isArray(model.notes) ? model.notes : []), ...(Array.isArray(extra) ? extra : [])].map((n, i) => ({ ...n, id: i + 1 }));
 mkdirSync(dirname(resolve(outPath)), { recursive: true });
 writeFileSync(outPath, embedModel(shell, model, notes), "utf8");
 console.log(`wrote ${outPath}`);