lecodes-cli 0.8.2 → 0.9.0

package/dist/index.js

@@ -2007,7 +2007,7 @@ var require_main = __commonJS((exports, module) => {
 // package.json
 var package_default = {
   name: "lecodes-cli",
-  version: "0.8.2",
+  version: "0.9.0",
   description: "Clone, edit and push LeCodes projects from your machine.",
   type: "module",
   license: "MIT",
@@ -2037,11 +2037,11 @@ var package_default = {
     prepublishOnly: "bun run sync-peers && bun run build"
   },
   dependencies: {
-    "@letary/chisel": "^0.4.1"
+    "@letary/chisel": "^0.4.2"
   },
   peerDependencies: {
     "lecodes-design": "^0.3.2",
-    "lecodes-renderer": "^0.6.2",
+    "lecodes-renderer": "^0.7.0",
     "lecodes-3d-editor": "^0.1.0"
   },
   peerDependenciesMeta: {
@@ -4866,15 +4866,8 @@ var browserLogin = async (webBase, timeoutMs = 5 * 60 * 1000, open = openBrowser
   }
 };
 
-// src/commands/designTemplates.ts
-var META_JSON = `{
-  "screens": {
-    "home": { "pos": [0, 0], "desc": "Example screen — replace me", "role": "list" }
-  },
-  "edges": []
-}
-`;
-var SPEC_MD = `# Concept
+// ../lecodes-design/src/core/concept.ts
+var SPEC_TEMPLATE = `# Concept
 
 The narrative half of this design. \`meta.json\` + the canvas hold the *visual/flow* half (screens,
 positions, edges); this file holds what never renders as a screen — the data model, the actors, and
@@ -4908,6 +4901,16 @@ which is the screen's *kind* — list, detail, form…)
 Behaviour that isn't visible in a single screen — validation, permissions, notifications, edge
 cases — and the decisions you've made and why, so they aren't re-litigated later.
 `;
+
+// ../lecodes-design/src/templates.ts
+var SPEC_MD = SPEC_TEMPLATE;
+var META_JSON = `{
+  "screens": {
+    "home": { "pos": [0, 0], "desc": "Example screen — replace me", "role": "list" }
+  },
+  "edges": []
+}
+`;
 var TOKENS_TS = `// Design tokens shared by every screen. Colors are hex strings (the engine parses hex only).
 // App font: one theme() call here sets the default text font everywhere. font("id") installs a
 // registry family (vendored at compile time) and returns its name — no loading code needed.
@@ -5070,6 +5073,26 @@ positions or descriptions.
   \`lecodes design check\` lists screens still untagged (never blocking). *(A screen's **states** are
   a separate thing — declared in the source, not meta; see "Screen states" below.)*
 
+## The design is testable — names carry into the app
+
+Every edge with an \`activator\` doubles as a **flow test** for the real app: \`lecodes test\` (run
+at the project root once the app exists) walks the graph from the start screen, taps each edge's
+activator, and expects to land on a screen named like the edge's target. The design stays a living
+contract instead of a discarded sketch — but only if the app build keeps the wiring:
+
+- **Keep the design's \`name\`s** when translating a screen to app code — every element an edge's
+  \`activator\` references keeps its \`name\` (\`.style({ name: "submit" })\`).
+- **Name each app screen's root with its design screen id** — \`UIScreen([ … ]).style({ name:
+  "login" })\` — that's how the runner knows where a tap landed.
+- Edges with no activator (backend/system-driven) and \`@state\` edges are reported as *not
+  machine-verifiable* — cover the important ones with hand-written \`tests/*.flow.json\` scenarios
+  (same step schema as \`lecodes render --script\`; tab-bar navigation needs these too, since the
+  bar draws no edges).
+
+Names also appear in every headless render (JSON snapshots, the board's live elements), so they
+double as stable selectors for any scripted interaction — naming interactive elements is never
+wasted work.
+
 ## The concept — spec.md
 
 \`meta.json\` + the canvas are the *visual/flow* half of the design; \`spec.md\` is the *narrative*
@@ -5291,7 +5314,6 @@ var README_HINT = `# design/
 LeCodes Design canvas — run \`lecodes design\` here and open the printed URL.
 See CLAUDE.md for the conventions (it's written for AI assistants, but it's the spec).
 `;
-
 // src/commands/design.ts
 var DEFAULT_DIR = "design";
 var DEFAULT_PORT = 4477;
@@ -6564,50 +6586,47 @@ var login = async (args) => {
 };
 
 // src/commands/render.ts
-import { writeFileSync as writeFileSync14 } from "node:fs";
-import { resolve as resolve6 } from "node:path";
+import { mkdirSync as mkdirSync13, readFileSync as readFileSync17, writeFileSync as writeFileSync14 } from "node:fs";
+import { dirname as dirname11, resolve as resolve6 } from "node:path";
+
+// src/compile/headlessBundle.ts
 var LOCAL_ASSET_SCHEME2 = "lecodesfile://";
-var DEVICE_SAFE_AREA = {
-  none: { insets: [0, 0, 0, 0], bars: [] },
-  iphone: { insets: [59, 0, 34, 0], bars: [] },
-  android: { insets: [24, 0, 48, 0], bars: ["top", "bottom"] }
-};
-var resolveSafeArea = (args) => {
-  const explicit = flagStr(args, "safe-area");
-  if (explicit) {
-    const n = explicit.split(",").map((s) => Number(s.trim()));
-    if (n.length === 4 && n.every((v) => Number.isFinite(v)))
-      return { safeArea: n, safeAreaBars: [] };
-    throw new CliError(`--safe-area expects "top,right,bottom,left" (4 numbers), got "${explicit}".`);
-  }
-  const device = flagStr(args, "device");
-  if (device) {
-    const preset = DEVICE_SAFE_AREA[device];
-    if (!preset)
-      throw new CliError(`Unknown --device "${device}". Options: ${Object.keys(DEVICE_SAFE_AREA).join(", ")}.`);
-    return { safeArea: preset.insets, safeAreaBars: preset.bars };
+var compileHeadlessBundle = async (args) => {
+  let root;
+  let manifest;
+  try {
+    root = findProjectRoot(process.cwd());
+    manifest = readManifest(root);
+  } catch {
+    root = process.cwd();
+    manifest = null;
   }
-  return;
-};
-var render = async (args) => {
-  const timeoutMs = Number(flagStr(args, "timeout")) || 15000;
-  const killer = setTimeout(() => {
-    warnErr(`Render timed out after ${timeoutMs}ms (try --settle / --wait-network, or raise --timeout).`);
-    process.exit(1);
-  }, timeoutMs);
-  killer.unref?.();
-  const root = findProjectRoot(process.cwd());
-  const manifest = readManifest(root);
-  const config = loadConfig();
-  const apiUrl = requireApiUrl(config);
-  const token = requireToken(config);
-  note("Resolving project assets…");
-  const project = await getProject(apiUrl, token, manifest.uuid);
-  const { entries, warnings: collectWarnings } = collectEntries(root, manifest, project);
   const publicUrlFlag = flagStr(args, "public-url");
-  const useLocalAssets = !publicUrlFlag && !flagBool(args, "remote-assets");
+  const useLocalAssets = manifest ? !publicUrlFlag && !flagBool(args, "remote-assets") : true;
+  let entries;
+  let warnings;
+  let name;
+  let publicUrl;
+  if (manifest) {
+    const config = loadConfig();
+    const apiUrl = requireApiUrl(config);
+    const token = requireToken(config);
+    note("Resolving project assets…");
+    const project = await getProject(apiUrl, token, manifest.uuid);
+    ({ entries, warnings } = collectEntries(root, manifest, project));
+    name = manifest.name;
+    publicUrl = useLocalAssets ? LOCAL_ASSET_SCHEME2 : publicUrlFlag ?? apiUrl;
+    if (useLocalAssets)
+      warnings = warnings.filter((w) => !w.includes("No server URL"));
+  } else {
+    ({ entries, warnings } = collectLocalEntries(root, null, ""));
+    name = root.split(/[\\/]/).pop() ?? "project";
+    publicUrl = LOCAL_ASSET_SCHEME2;
+    if (flagBool(args, "remote-assets") || publicUrlFlag) {
+      warnings.push("This is a local project (no server) — assets always load from the working tree.");
+    }
+  }
   const compileEntries = useLocalAssets ? entries.map((e) => e.type === "resource" && e.absPath ? { ...e, fileSrc: encodeURIComponent(e.absPath) } : e) : entries;
-  const warnings = useLocalAssets ? collectWarnings.filter((w) => !w.includes("No server URL")) : collectWarnings;
   await applyProjectFonts(compileEntries, useLocalAssets ? {
     mode: "vendor",
     root,
@@ -6618,8 +6637,8 @@ var render = async (args) => {
   note("Compiling…");
   const js = await compileProject2({
     entries: compileEntries,
-    name: manifest.name,
-    publicUrl: useLocalAssets ? LOCAL_ASSET_SCHEME2 : publicUrlFlag ?? apiUrl,
+    name,
+    publicUrl,
     entryOverride: flagStr(args, "entry"),
     header: false,
     format: "iife"
@@ -6630,15 +6649,75 @@ var render = async (args) => {
   if (js.includes("_creator2d") && !useLocalAssets && !flagBool(args, "wait-network")) {
     warnings.push("2D scene detected: sprite textures load over the network — add --wait-network to include them (else sprites render as flat placeholders).");
   }
-  let renderer;
+  return { js, root, warnings, useLocalAssets };
+};
+
+// src/commands/render.ts
+var DEVICE_SAFE_AREA = {
+  none: { insets: [0, 0, 0, 0], bars: [] },
+  iphone: { insets: [59, 0, 34, 0], bars: [] },
+  android: { insets: [24, 0, 48, 0], bars: ["top", "bottom"] }
+};
+var resolveSafeAreaChoice = (explicit, device) => {
+  if (explicit) {
+    const n = explicit.split(",").map((s) => Number(s.trim()));
+    if (n.length === 4 && n.every((v) => Number.isFinite(v)))
+      return { safeArea: n, safeAreaBars: [] };
+    throw new CliError(`--safe-area expects "top,right,bottom,left" (4 numbers), got "${explicit}".`);
+  }
+  if (device) {
+    const preset = DEVICE_SAFE_AREA[device];
+    if (!preset)
+      throw new CliError(`Unknown --device "${device}". Options: ${Object.keys(DEVICE_SAFE_AREA).join(", ")}.`);
+    return { safeArea: preset.insets, safeAreaBars: preset.bars };
+  }
+  return;
+};
+var requireRenderer = async () => {
   try {
-    renderer = await import("lecodes-renderer/headless");
+    return await import("lecodes-renderer/headless");
   } catch {
     throw new CliError("The renderer isn't installed. Run:  npm i -D lecodes-renderer");
   }
-  const width = Number(flagStr(args, "width")) || 390;
-  const height = Number(flagStr(args, "height")) || 844;
-  const settleStr = flagStr(args, "settle");
+};
+var fileScenarioIO = (dir) => ({
+  write: (relPath, data) => {
+    const abs = resolve6(dir, relPath);
+    mkdirSync13(dirname11(abs), { recursive: true });
+    writeFileSync14(abs, data);
+  }
+});
+var readScenarioFile = (path) => {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync17(resolve6(path), "utf8"));
+  } catch (e) {
+    throw new CliError(`Can't read scenario "${path}": ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (Array.isArray(raw))
+    return { steps: raw };
+  if (typeof raw !== "object" || raw === null)
+    throw new CliError(`Scenario "${path}" must be a JSON object with "steps" (or a bare step array).`);
+  const file = raw;
+  if (file.steps === undefined)
+    throw new CliError(`Scenario "${path}" has no "steps".`);
+  return file;
+};
+var render = async (args) => {
+  const scriptFlag = flagStr(args, "script");
+  const scenario = scriptFlag !== undefined ? readScenarioFile(scriptFlag) : null;
+  const stepCount = scenario && Array.isArray(scenario.steps) ? scenario.steps.length : 0;
+  const timeoutMs = Number(flagStr(args, "timeout")) || 15000 + stepCount * 3000;
+  const killer = setTimeout(() => {
+    warnErr(`Render timed out after ${timeoutMs}ms (try --settle / --wait-network, or raise --timeout).`);
+    process.exit(1);
+  }, timeoutMs);
+  killer.unref?.();
+  const { js, warnings, useLocalAssets } = await compileHeadlessBundle(args);
+  const renderer = await requireRenderer();
+  const width = Number(flagStr(args, "width")) || scenario?.width || 390;
+  const height = Number(flagStr(args, "height")) || scenario?.height || 844;
+  const settleStr = flagStr(args, "settle") ?? (scenario?.settle !== undefined ? String(scenario.settle) : undefined);
   const timeStr = flagStr(args, "time");
   const onConsole = flagBool(args, "logs") ? (level, text2) => logErr(`${c.dim(`[${level}]`)} ${text2}`) : undefined;
   const timing = {
@@ -6647,13 +6726,36 @@ var render = async (args) => {
     localAssets: useLocalAssets,
     timeMs: timeStr !== undefined ? Number(timeStr) : undefined,
     afterAnimations: !flagBool(args, "no-after-animations"),
-    ...resolveSafeArea(args),
+    ...resolveSafeAreaChoice(flagStr(args, "safe-area") ?? scenario?.safeArea, flagStr(args, "device") ?? scenario?.device),
     onConsole
   };
-  const done = (flush) => flush(() => {
+  const done = (flush, code = 0) => flush(() => {
     clearTimeout(killer);
-    process.exit(0);
+    process.exit(code);
   });
+  if (scenario) {
+    const steps = renderer.parseScenarioSteps(scenario.steps);
+    const outDir = flagStr(args, "out-dir") ?? ".";
+    const needsRaster = steps.some((s) => s.screenshot !== undefined);
+    note(`Running ${steps.length} step${steps.length === 1 ? "" : "s"}…`);
+    const session = await renderer.createSession(js, { width, height, ...timing, raster: needsRaster ? true : "auto" });
+    try {
+      const result2 = await renderer.runScenario(session, steps, fileScenarioIO(outDir));
+      for (const w of [...warnings, ...session.warnings])
+        warnErr(w);
+      for (const st of result2.steps) {
+        logErr(st.ok ? `${c.green("✓")} ${st.desc}` : `${c.red("✗")} ${st.desc}
+  ${c.red(st.error ?? "failed")}`);
+      }
+      if (!result2.ok && result2.failureArtifacts.length > 0) {
+        logErr(c.dim(`  failing frame: ${result2.failureArtifacts.map((p) => resolve6(outDir, p)).join(", ")}`));
+      }
+      logErr(result2.ok ? c.green(`✓ ${result2.steps.length}/${steps.length} steps passed`) : c.red(`✗ failed at step ${result2.steps.length} of ${steps.length}`));
+      return done((cb) => cb(), result2.ok ? 0 : 1);
+    } finally {
+      session.dispose();
+    }
+  }
   const pngFlag = flagStr(args, "png") ?? (flagBool(args, "png") ? "screenshot.png" : undefined);
   if (pngFlag !== undefined) {
     note("Rendering PNG…");
@@ -6694,8 +6796,8 @@ var render = async (args) => {
 };
 
 // src/commands/pull.ts
-import { existsSync as existsSync17, mkdirSync as mkdirSync13, rmSync as rmSync2, writeFileSync as writeFileSync15 } from "node:fs";
-import { dirname as dirname11, join as join19 } from "node:path";
+import { existsSync as existsSync17, mkdirSync as mkdirSync14, rmSync as rmSync2, writeFileSync as writeFileSync15 } from "node:fs";
+import { dirname as dirname12, join as join19 } from "node:path";
 var pull = async (args) => {
   const root = findProjectRoot(process.cwd());
   const manifest = readManifest(root);
@@ -6755,7 +6857,7 @@ var pullPaths = async (root, manifest, project, paths, apiUrl, token) => {
   for (const asset of targets) {
     const key = pathById.get(asset.id);
     const abs = join19(root, ...key.replace(/^\//, "").split("/"));
-    mkdirSync13(dirname11(abs), { recursive: true });
+    mkdirSync14(dirname12(abs), { recursive: true });
     let sha;
     if (asset.type === "file") {
       if (!asset.file?.src)
@@ -6778,7 +6880,7 @@ var pullPaths = async (root, manifest, project, paths, apiUrl, token) => {
 
 // src/commands/push.ts
 import { basename as basename10 } from "node:path";
-import { readFileSync as readFileSync17 } from "node:fs";
+import { readFileSync as readFileSync18 } from "node:fs";
 var push = async (args) => {
   const root = findProjectRoot(process.cwd());
   const manifest = readManifest(root);
@@ -6837,9 +6939,9 @@ var push = async (args) => {
     if (source)
       entry.assetId = source.id;
     if (isTextKind(kind)) {
-      entry.text = readFileSync17(file.absPath, "utf8");
+      entry.text = readFileSync18(file.absPath, "utf8");
     } else if (!source || source.sha !== file.sha) {
-      const blob = await uploadBlob(apiUrl, token, manifest.uuid, basename10(file.path), readFileSync17(file.absPath));
+      const blob = await uploadBlob(apiUrl, token, manifest.uuid, basename10(file.path), readFileSync18(file.absPath));
       entry.blobFileId = blob.id;
       uploaded++;
     }
@@ -6892,11 +6994,11 @@ var reportPublish = (res) => {
 };
 
 // src/commands/scene.ts
-import { existsSync as existsSync19, readFileSync as readFileSync19, readdirSync as readdirSync8, statSync as statSync4, writeFileSync as writeFileSync16 } from "node:fs";
-import { basename as basename11, dirname as dirname12, join as join21, resolve as resolve7 } from "node:path";
+import { existsSync as existsSync19, readFileSync as readFileSync20, readdirSync as readdirSync8, statSync as statSync4, writeFileSync as writeFileSync16 } from "node:fs";
+import { basename as basename11, dirname as dirname13, join as join21, resolve as resolve7 } from "node:path";
 
 // src/compile/sceneCompile.ts
-import { existsSync as existsSync18, readFileSync as readFileSync18 } from "node:fs";
+import { existsSync as existsSync18, readFileSync as readFileSync19 } from "node:fs";
 import { join as join20 } from "node:path";
 var TEXT_EXT = /\.(ts|js|json|svg|txt|md)$/i;
 var rel = (key) => key.replace(/^\//, "");
@@ -6907,7 +7009,7 @@ var resolveHarness = (loadSceneHarness2) => {
   } catch {
     const vendored = join20(distRoot, "runtime", "scene-harness.json");
     if (existsSync18(vendored))
-      return JSON.parse(readFileSync18(vendored, "utf8"));
+      return JSON.parse(readFileSync19(vendored, "utf8"));
     throw new CliError("scene-editor harness sources not found — reinstall the CLI or set LECODES_SCENE_HARNESS_DIR.");
   }
 };
@@ -6919,7 +7021,7 @@ var compileSceneEditor = async (opts) => {
   for (const file of scan.files) {
     const path = "./" + rel(file.path);
     if (TEXT_EXT.test(path)) {
-      entries.push({ path, type: "text", text: readFileSync18(file.absPath, "utf8") });
+      entries.push({ path, type: "text", text: readFileSync19(file.absPath, "utf8") });
     } else {
       entries.push({ path, type: "resource", fileSrc: "/project/" + rel(file.path) });
     }
@@ -6963,7 +7065,7 @@ var getContext2 = (args) => {
       if (existsSync19(abs) && statSync4(abs).isDirectory())
         root = abs;
       else if (abs.endsWith(".scene.ts") && existsSync19(abs))
-        root = dirname12(abs);
+        root = dirname13(abs);
       else
         throw new CliError(`No such folder or .scene.ts: ${pathArg}`);
     }
@@ -6976,7 +7078,7 @@ var writeMcpConfig2 = (root, port) => {
   let config = {};
   if (existsSync19(path)) {
     try {
-      config = JSON.parse(readFileSync19(path, "utf8"));
+      config = JSON.parse(readFileSync20(path, "utf8"));
     } catch {
       warnErr(".mcp.json exists but isn't valid JSON — left it untouched. Add the lecodes-scene server by hand.");
       return;
@@ -7068,23 +7170,239 @@ var status = async (_args) => {
     info(c.dim(`  ${scan.ignored.length} ignored (.lecodesignore)`));
 };
 
+// src/commands/test.ts
+import { existsSync as existsSync20, readFileSync as readFileSync21, readdirSync as readdirSync9 } from "node:fs";
+import { resolve as resolve8 } from "node:path";
+var deriveDesignFlows = (meta, entryScreen) => {
+  const edges = meta.edges ?? [];
+  const isState = (id) => id.includes("@");
+  const verifiable = edges.filter((e) => e.activator && !isState(e.from) && !isState(e.to));
+  const prev = new Map;
+  const visited = new Set([entryScreen]);
+  const queue = [entryScreen];
+  while (queue.length > 0) {
+    const at = queue.shift();
+    for (const e of verifiable) {
+      if (e.from !== at || visited.has(e.to))
+        continue;
+      visited.add(e.to);
+      prev.set(e.to, e);
+      queue.push(e.to);
+    }
+  }
+  const pathTo = (screen) => {
+    if (screen === entryScreen)
+      return [];
+    if (!visited.has(screen))
+      return null;
+    const hops = [];
+    for (let at = screen;at !== entryScreen; at = hops[0].from)
+      hops.unshift(prev.get(at));
+    return hops;
+  };
+  const flows = [];
+  const skipped = [];
+  for (const e of edges) {
+    const name = `${e.from} —${e.activator ?? "?"}→ ${e.to}`;
+    if (!e.activator) {
+      skipped.push({ name, reason: "no activator (backend/gesture-driven) — cover it with a tests/*.flow.json" });
+      continue;
+    }
+    if (isState(e.from) || isState(e.to)) {
+      skipped.push({ name, reason: "screen-state edge (@state) — states are runtime conditions, not screens" });
+      continue;
+    }
+    const path = pathTo(e.from);
+    if (path === null) {
+      skipped.push({ name, reason: `"${e.from}" has no activator path from "${entryScreen}" (tab-bar navigation?) — cover it with a tests/*.flow.json` });
+      continue;
+    }
+    flows.push({
+      name,
+      kind: "flow",
+      steps: [
+        ...path.map((hop) => ({ tap: hop.activator, expect: { screen: hop.to } })),
+        { tap: e.activator, expect: { screen: e.to } }
+      ]
+    });
+  }
+  return { flows, skipped };
+};
+var slug3 = (s) => s.replace(/[^a-zA-Z0-9-_]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "case";
+var readFlowFile = (abs, displayName) => {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync21(abs, "utf8"));
+  } catch (e) {
+    throw new CliError(`Can't read "${displayName}": ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (Array.isArray(raw))
+    return { name: displayName, kind: "file", steps: raw };
+  if (typeof raw !== "object" || raw === null || raw.steps === undefined) {
+    throw new CliError(`"${displayName}" must be a JSON object with "steps" (or a bare step array).`);
+  }
+  const file = raw;
+  return { name: file.name ?? displayName, kind: "file", steps: file.steps, width: file.width, height: file.height, settle: file.settle, device: file.device, safeArea: file.safeArea };
+};
+var test = async (args) => {
+  const { js, warnings, useLocalAssets, root } = await compileHeadlessBundle(args);
+  const renderer = await requireRenderer();
+  const testsDir = resolve8(root, flagStr(args, "dir") ?? "tests");
+  const designMetaPath = resolve8(root, flagStr(args, "design-dir") ?? "design", "meta.json");
+  const asJson = flagBool(args, "json");
+  const out = asJson ? logErr : log;
+  const cases = [];
+  if (args._.length > 0) {
+    for (const given of args._) {
+      const candidates = [resolve8(given), resolve8(testsDir, given), resolve8(testsDir, `${given}.flow.json`)];
+      const abs = candidates.find((p) => existsSync20(p));
+      if (!abs)
+        throw new CliError(`No such test: "${given}" (looked in ${testsDir}).`);
+      cases.push(readFlowFile(abs, given));
+    }
+  } else if (existsSync20(testsDir)) {
+    for (const f2 of readdirSync9(testsDir).filter((f3) => f3.endsWith(".flow.json")).sort()) {
+      cases.push(readFlowFile(resolve8(testsDir, f2), f2));
+    }
+  }
+  const flowsOnly = flagBool(args, "flows");
+  const wantFlows = !flagBool(args, "no-flows") && args._.length === 0;
+  if (flowsOnly)
+    cases.length = 0;
+  let skipped = [];
+  let entryScreen = null;
+  if ((wantFlows || flowsOnly) && existsSync20(designMetaPath)) {
+    let meta;
+    try {
+      meta = JSON.parse(readFileSync21(designMetaPath, "utf8"));
+    } catch (e) {
+      throw new CliError(`Can't read ${designMetaPath}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if ((meta.edges ?? []).length > 0) {
+      note("Probing the start screen…");
+      const probe = await renderer.createSession(js, { raster: false, localAssets: useLocalAssets });
+      entryScreen = probe.screenName();
+      probe.dispose();
+      if (entryScreen === null) {
+        warnErr('Design flows skipped: the app\'s start screen root has no `name`. Name each screen root with its design screen id (e.g. UIScreen([...], { name: "login" })).');
+      } else {
+        const derived = deriveDesignFlows(meta, entryScreen);
+        cases.push(...derived.flows);
+        skipped = derived.skipped;
+      }
+    }
+  } else if (flowsOnly) {
+    throw new CliError(`--flows needs a design graph (${designMetaPath} not found).`);
+  }
+  if (cases.length === 0) {
+    for (const w of warnings)
+      warnErr(w);
+    throw new CliError(`No tests found. Write tests/*.flow.json scenarios, or draw activator edges in the design board (design/meta.json).`);
+  }
+  const timeoutMs = Number(flagStr(args, "timeout")) || 20000 + cases.length * 1e4;
+  const killer = setTimeout(() => {
+    warnErr(`Test run timed out after ${timeoutMs}ms (raise --timeout or lower --settle).`);
+    process.exit(1);
+  }, timeoutMs);
+  killer.unref?.();
+  const onConsole = flagBool(args, "logs") ? (level, text) => logErr(`${c.dim(`[${level}]`)} ${text}`) : undefined;
+  const artifactsRoot = resolve8(root, flagStr(args, "artifacts") ?? resolve8(testsDir, ".artifacts"));
+  const results = [];
+  for (const kase of cases) {
+    const flagSettle = flagStr(args, "settle");
+    let result;
+    try {
+      const steps = renderer.parseScenarioSteps(kase.steps);
+      const session = await renderer.createSession(js, {
+        width: Number(flagStr(args, "width")) || kase.width || 390,
+        height: Number(flagStr(args, "height")) || kase.height || 844,
+        settleMs: flagSettle !== undefined ? Number(flagSettle) : kase.settle,
+        waitNetwork: flagBool(args, "wait-network"),
+        localAssets: useLocalAssets,
+        ...resolveSafeAreaChoice(flagStr(args, "safe-area") ?? kase.safeArea, flagStr(args, "device") ?? kase.device),
+        onConsole
+      });
+      try {
+        const io = fileScenarioIO(resolve8(artifactsRoot, slug3(kase.name)));
+        const outcome = await renderer.runScenario(session, steps, io);
+        result = {
+          name: kase.name,
+          kind: kase.kind,
+          ok: outcome.ok,
+          steps: outcome.steps.map((s) => ({ desc: s.desc, ok: s.ok, error: s.error })),
+          artifacts: outcome.failureArtifacts.map((p) => resolve8(artifactsRoot, slug3(kase.name), p))
+        };
+      } finally {
+        session.dispose();
+      }
+    } catch (e) {
+      result = { name: kase.name, kind: kase.kind, ok: false, steps: [], error: e instanceof Error ? e.message : String(e), artifacts: [] };
+    }
+    results.push(result);
+    if (result.ok) {
+      out(`${c.green("✓")} ${result.name}`);
+    } else {
+      out(`${c.red("✗")} ${result.name}`);
+      if (result.error)
+        out(`    ${c.red(result.error)}`);
+      for (const s of result.steps) {
+        out(s.ok ? c.dim(`    ✓ ${s.desc}`) : `    ${c.red(`✗ ${s.desc} — ${s.error}`)}`);
+      }
+      if (result.artifacts.length > 0)
+        out(c.dim(`    failing frame: ${result.artifacts.join(", ")}`));
+    }
+  }
+  for (const w of warnings)
+    warnErr(w);
+  const passed = results.filter((r) => r.ok).length;
+  const failed = results.length - passed;
+  if (skipped.length > 0) {
+    out("");
+    out(c.dim(`Not machine-verifiable (${skipped.length}):`));
+    for (const s of skipped)
+      out(c.dim(`  - ${s.name}: ${s.reason}`));
+  }
+  out("");
+  const flowCount = results.filter((r) => r.kind === "flow").length;
+  const summary = [
+    `${passed} passed`,
+    failed > 0 ? c.red(`${failed} failed`) : undefined,
+    skipped.length > 0 ? `${skipped.length} unverifiable` : undefined,
+    flowCount > 0 ? c.dim(`(${flowCount} from the design graph${entryScreen ? `, start: ${entryScreen}` : ""})`) : undefined
+  ].filter(Boolean).join(", ");
+  out(failed > 0 ? `${c.red("✗")} ${summary}` : `${c.green("✓")} ${summary}`);
+  if (asJson) {
+    process.stdout.write(JSON.stringify({
+      ok: failed === 0,
+      passed,
+      failed,
+      entryScreen,
+      cases: results,
+      unverifiable: skipped
+    }, null, 2) + `
+`);
+  }
+  clearTimeout(killer);
+  process.exit(failed > 0 ? 1 : 0);
+};
+
 // src/index.ts
-import { existsSync as existsSync21, readFileSync as readFileSync21, realpathSync as realpathSync2 } from "node:fs";
+import { existsSync as existsSync22, readFileSync as readFileSync23, realpathSync as realpathSync2 } from "node:fs";
 import { createRequire as createRequire4 } from "node:module";
-import { delimiter as delimiter2, dirname as dirname14, join as join23 } from "node:path";
+import { delimiter as delimiter2, dirname as dirname15, join as join23 } from "node:path";
 
 // src/commands/install.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
-import { appendFileSync as appendFileSync2, chmodSync, cpSync as cpSync2, existsSync as existsSync20, mkdirSync as mkdirSync14, readFileSync as readFileSync20, realpathSync, rmSync as rmSync3, symlinkSync } from "node:fs";
+import { appendFileSync as appendFileSync2, chmodSync, cpSync as cpSync2, existsSync as existsSync21, mkdirSync as mkdirSync15, readFileSync as readFileSync22, realpathSync, rmSync as rmSync3, symlinkSync } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { basename as basename12, delimiter, dirname as dirname13, join as join22, resolve as resolve8, sep } from "node:path";
+import { basename as basename12, delimiter, dirname as dirname14, join as join22, resolve as resolve9, sep } from "node:path";
 var isWin = process.platform === "win32";
 var HOME = homedir3();
 var safeRealpath = (p) => {
   try {
     return realpathSync(p);
   } catch {
-    return resolve8(p);
+    return resolve9(p);
   }
 };
 var onPath = (dir) => {
@@ -7100,19 +7418,19 @@ var onPath = (dir) => {
   });
 };
 var install = async (args) => {
-  const bundle = dirname13(process.execPath);
+  const bundle = dirname14(process.execPath);
   const exeName = basename12(process.execPath);
   const chiselName = isWin ? "chisel.exe" : "chisel";
-  if (!existsSync20(join22(bundle, "runtime")) || !existsSync20(join22(bundle, chiselName))) {
+  if (!existsSync21(join22(bundle, "runtime")) || !existsSync21(join22(bundle, chiselName))) {
     throw new CliError("`lecodes install` only works from the packaged release build (the archive containing lecodes + " + "chisel + runtime/). You appear to be running from source or an npm install — install globally " + "with your package manager there instead.");
   }
-  const companions = [exeName, chiselName, "runtime", "README.txt"].filter((f2) => existsSync20(join22(bundle, f2)));
+  const companions = [exeName, chiselName, "runtime", "README.txt"].filter((f2) => existsSync21(join22(bundle, f2)));
   if (isWin)
     return installWindows(args, bundle, companions);
   return installUnix(args, bundle, companions);
 };
 var copyBundle = (bundle, target, companions) => {
-  mkdirSync14(target, { recursive: true });
+  mkdirSync15(target, { recursive: true });
   if (safeRealpath(target) === safeRealpath(bundle))
     return;
   for (const f2 of companions) {
@@ -7130,8 +7448,8 @@ var permError = (e, dir, system) => {
 };
 var installUnix = (args, bundle, companions) => {
   const system = flagBool(args, "system");
-  const libDir = resolve8(flagStr(args, "dir") ?? (system ? "/usr/local/lib/lecodes-cli" : join22(HOME, ".local", "lib", "lecodes-cli")));
-  const binDir = resolve8(flagStr(args, "bin") ?? (system ? "/usr/local/bin" : join22(HOME, ".local", "bin")));
+  const libDir = resolve9(flagStr(args, "dir") ?? (system ? "/usr/local/lib/lecodes-cli" : join22(HOME, ".local", "lib", "lecodes-cli")));
+  const binDir = resolve9(flagStr(args, "bin") ?? (system ? "/usr/local/bin" : join22(HOME, ".local", "bin")));
   const link = join22(binDir, "lecodes");
   try {
     copyBundle(bundle, libDir, companions);
@@ -7141,7 +7459,7 @@ var installUnix = (args, bundle, companions) => {
     throw permError(e, libDir, system);
   }
   try {
-    mkdirSync14(binDir, { recursive: true });
+    mkdirSync15(binDir, { recursive: true });
     rmSync3(link, { force: true });
     symlinkSync(join22(libDir, "lecodes"), link);
   } catch (e) {
@@ -7164,7 +7482,7 @@ var appendPathToShellRc = (binDir) => {
   const { file, name } = shellRc();
   const line = `export PATH="${binDir}:$PATH"`;
   try {
-    const existing = existsSync20(file) ? readFileSync20(file, "utf8") : "";
+    const existing = existsSync21(file) ? readFileSync22(file, "utf8") : "";
     if (existing.includes(line))
       return name;
     appendFileSync2(file, `${existing && !existing.endsWith(`
@@ -7202,7 +7520,7 @@ var finishPathUnix = (args, binDir) => {
   log(`  • or install system-wide (no PATH edit): ${c.bold("sudo lecodes install --system")}`);
 };
 var installWindows = (args, bundle, companions) => {
-  const target = resolve8(flagStr(args, "dir") ?? join22(process.env.LOCALAPPDATA ?? join22(HOME, "AppData", "Local"), "Programs", "lecodes-cli"));
+  const target = resolve9(flagStr(args, "dir") ?? join22(process.env.LOCALAPPDATA ?? join22(HOME, "AppData", "Local"), "Programs", "lecodes-cli"));
   try {
     copyBundle(bundle, target, companions);
   } catch (e) {
@@ -7239,9 +7557,9 @@ var addToUserPathWindows = (dir) => {
 
 // src/index.ts
 var STANDALONE = (() => {
-  const dir = dirname14(process.execPath);
+  const dir = dirname15(process.execPath);
   const chisel = process.platform === "win32" ? "chisel.exe" : "chisel";
-  return existsSync21(join23(dir, "runtime")) && existsSync21(join23(dir, chisel));
+  return existsSync22(join23(dir, "runtime")) && existsSync22(join23(dir, chisel));
 })();
 var INSTALLED = STANDALONE && (() => {
   const exe = process.platform === "win32" ? "lecodes.exe" : "lecodes";
@@ -7257,7 +7575,7 @@ var INSTALLED = STANDALONE && (() => {
       return false;
     try {
       const cand = join23(d, exe);
-      return existsSync21(cand) && realpathSync2(cand) === self;
+      return existsSync22(cand) && realpathSync2(cand) === self;
     } catch {
       return false;
     }
@@ -7320,12 +7638,28 @@ ${c.bold("Commands:")}
                                   -o, --out <file>   write JSON to a file instead of stdout
                                   --png [file]       rasterize a PNG (default screenshot.png;
                                                        needs @napi-rs/canvas)
+                                  --script <file>    drive the app through a step list (tap/type/
+                                                       scroll/wait/expect/screenshot/json steps)
+                                  --out-dir <dir>    where --script step outputs land (default .)
                                   --scale <n>        PNG device-pixel scale (default 2)
                                   --width/--height   viewport size (default 390x844)
                                   --entry <path>     override the entrypoint
                                   --settle <ms>      wait for promises/timers/fetch before snapshot
                                   --wait-network     let data fetches hit the real network
                                   --logs             forward the app's console output (to stderr)
+  test [name…]                  Run headless flow tests: tests/*.flow.json scenarios, plus flows
+                                  derived from the design graph (design/meta.json activator edges
+                                  — checks the built app against the designed navigation; needs
+                                  named elements + screen roots). Failing steps dump the frame
+                                  (JSON + PNG) under tests/.artifacts/<flow>/.
+                                  --flows            run ONLY the design-derived flows
+                                  --no-flows         run ONLY the tests/*.flow.json files
+                                  --json             machine-readable report on stdout
+                                  --dir <folder>     tests folder (default tests/)
+                                  --design-dir <dir> design folder (default design/)
+                                  --artifacts <dir>  failure-artifact folder override
+                                  (+ the render timing flags: --width/--height, --settle,
+                                   --device, --safe-area, --wait-network, --logs, --entry)
   design [serve]                LeCodes Design — a live canvas of screens for AI-driven prototyping
                                   (needs the optional 'lecodes-design' package; works inside a
                                    cloned project or standalone in any folder)
@@ -7374,7 +7708,7 @@ ${c.bold("Commands:")}
                                                        ASC API key; stored in ~/.lecodes/asc.json
 
 Config lives in ~/.lecodes/config.json (override with LECODES_API / LECODES_TOKEN).`;
-var commands = { init: init2, login, create, clone, status, diff, pull, push, compile: compile2, preview: previewLegacy, render, design, scene, dev, app };
+var commands = { init: init2, login, create, clone, status, diff, pull, push, compile: compile2, preview: previewLegacy, render, test, design, scene, dev, app };
 if (STANDALONE)
   commands.install = install;
 var readVersion = () => package_default.version ?? "unknown";
@@ -7386,15 +7720,15 @@ var OPTIONAL_PEERS = [
 var peerVersion = (name, probe) => {
   try {
     const require2 = createRequire4(import.meta.url);
-    let dir = dirname14(require2.resolve(probe));
+    let dir = dirname15(require2.resolve(probe));
     for (let depth = 0;depth < 16; depth++) {
       const manifest = join23(dir, "package.json");
-      if (existsSync21(manifest)) {
-        const parsed = JSON.parse(readFileSync21(manifest, "utf8"));
+      if (existsSync22(manifest)) {
+        const parsed = JSON.parse(readFileSync23(manifest, "utf8"));
         if (parsed.name === name)
           return parsed.version ?? "unknown";
       }
-      const parent = dirname14(dir);
+      const parent = dirname15(dir);
       if (parent === dir)
         break;
       dir = parent;