lecodes-cli 0.8.2 → 0.9.1

package/dist/index.js

@@ -190,6 +190,23 @@ var resolveInject = () => {
       return bin;
   } catch {}
   throw new Error("chisel binary not found. Install @letary/chisel, or set LECODES_CHISEL_BIN.");
+}, scanModulesChisel = (files) => {
+  let bin;
+  try {
+    bin = resolveChiselBin();
+  } catch {
+    return null;
+  }
+  const input = JSON.stringify({ scan: true, files });
+  const r = spawnSync(bin, [], { input, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+  if (r.status !== 0 || r.error)
+    return null;
+  try {
+    const parsed = JSON.parse(r.stdout || "{}");
+    return parsed.scan ?? null;
+  } catch {
+    return null;
+  }
 }, bundleProjectChisel = async (entrypoint, files, format, sourcemap, minifyOverride, editor, libraries) => {
   const entry = normalize(entrypoint);
   const slugs = new Set(Object.keys(libraries ?? {}));
@@ -262,6 +279,79 @@ var init_bundler = __esm(() => {
   sdkFilesCache = new Map;
 });
 
+// ../sdk/src/compile/detectEntry.ts
+var ENTRY_CONVENTION = "/main.ts", isCode = (path) => /\.[tj]s$/.test(path) && !path.endsWith(".d.ts"), normalize2 = (path) => {
+  const parts = [];
+  for (const part of path.split("/")) {
+    if (!part || part === ".")
+      continue;
+    if (part === "..")
+      parts.pop();
+    else
+      parts.push(part);
+  }
+  return "/" + parts.join("/");
+}, dirOf = (path) => {
+  const i = path.lastIndexOf("/");
+  return i <= 0 ? "/" : path.slice(0, i);
+}, resolveSpec = (files, importer, spec) => {
+  if (!spec.startsWith("./") && !spec.startsWith("../") && !spec.startsWith("/"))
+    return null;
+  const base = normalize2(spec.startsWith("/") ? spec : dirOf(importer) + "/" + spec);
+  for (const cand of [base, base + ".ts", base + ".js", base + "/index.ts"]) {
+    if (cand in files)
+      return cand;
+  }
+  return null;
+}, IMPORT_RE, EXPORT_RE, scanModulesFallback = (files) => {
+  const out = {};
+  for (const [path, text] of Object.entries(files)) {
+    const imports = [];
+    for (const m of text.matchAll(IMPORT_RE)) {
+      const target = resolveSpec(files, path, m[1] ?? m[2] ?? "");
+      if (target && isCode(target) && !imports.includes(target))
+        imports.push(target);
+    }
+    out[path] = { imports, hasExports: EXPORT_RE.test(text) };
+  }
+  return out;
+}, detectEntry = (entries, scanner) => {
+  const files = {};
+  for (const e of entries) {
+    if (e.type !== undefined && e.type !== "text")
+      continue;
+    if (typeof e.text !== "string")
+      continue;
+    const path = normalize2(e.path.split("\\").join("/"));
+    if (isCode(path))
+      files[path] = e.text;
+  }
+  const candidates = Object.keys(files).filter((p) => !p.endsWith(".editor.ts"));
+  if (candidates.length === 0)
+    return { entry: "", roots: [] };
+  const scan = scanner?.(files) ?? scanModulesFallback(files);
+  const imported = new Set;
+  for (const [path, mod] of Object.entries(scan)) {
+    if (path.endsWith(".editor.ts"))
+      continue;
+    for (const target of mod.imports)
+      imported.add(target);
+  }
+  let roots = candidates.filter((p) => !imported.has(p));
+  if (roots.length === 0)
+    roots = candidates;
+  if (roots.includes(ENTRY_CONVENTION))
+    return { entry: ENTRY_CONVENTION, roots };
+  const scripts = roots.filter((p) => !scan[p]?.hasExports);
+  const pool = scripts.length > 0 ? scripts : roots;
+  const bySize = [...pool].sort((a, b) => files[b].length - files[a].length);
+  return { entry: bySize[0], roots };
+};
+var init_detectEntry = __esm(() => {
+  IMPORT_RE = /(?:^|[\n;])\s*(?:import|export)\b[^'"`]*?\bfrom\s*['"]([^'"\n]+)['"]|(?:^|[\n;])\s*import\s*['"]([^'"\n]+)['"]/g;
+  EXPORT_RE = /(?:^|[\n;])\s*export\b/;
+});
+
 // ../sdk/src/compile/sourcemap.ts
 var offsetSourceMap = (mapJson, lines) => {
   if (lines <= 0)
@@ -322,25 +412,10 @@ var buildHeader = (name, code, opts = {}) => {
 };
 
 // ../sdk/src/compile/compileProject.ts
-var detectEntry = (entries) => {
-  let entry = "";
-  let max = -1;
-  for (const e of entries) {
-    const ext2 = e.path.split(".").at(-1)?.toLowerCase();
-    if (e.path.endsWith(".editor.ts"))
-      continue;
-    if (e.type === "text" && e.text !== undefined && !e.text.includes("export") && (ext2 === "ts" || ext2 === "js")) {
-      if (e.text.length > max) {
-        entry = e.path;
-        max = e.text.length;
-      }
-    }
-  }
-  return entry;
-}, compileProject = async (opts) => {
-  const entry = opts.entryOverride ?? detectEntry(opts.entries);
+var compileProject = async (opts) => {
+  const entry = opts.entryOverride ?? detectEntry(opts.entries, scanModulesChisel).entry;
   if (!entry) {
-    throw new Error("Couldn't find an entrypoint (a top-level .ts/.js file with no `export`). Pass entryOverride.");
+    throw new Error("Couldn't find an entrypoint (no .ts/.js project file — name yours main.ts). Pass entryOverride.");
   }
   const files = {};
   for (const e of opts.entries) {
@@ -380,6 +455,7 @@ ${inlineSourceMapComment(offsetSourceMap(map, headerLines))}`;
 };
 var init_compileProject = __esm(() => {
   init_bundler();
+  init_detectEntry();
 });
 
 // ../sdk/src/compile/sceneEditor.ts
@@ -780,7 +856,7 @@ var FONT_ID, CODE_FILE, DECLARES_FONT, isIdentStart = (c2) => c2 >= "A" && c2 <=
     }
   }
   return null;
-}, norm = (p) => p.replace(/\\/g, "/").replace(/^\//, ""), dirOf = (p) => {
+}, norm = (p) => p.replace(/\\/g, "/").replace(/^\//, ""), dirOf2 = (p) => {
   const n = norm(p);
   const i = n.lastIndexOf("/");
   return i === -1 ? "" : n.slice(0, i);
@@ -823,7 +899,7 @@ var FONT_ID, CODE_FILE, DECLARES_FONT, isIdentStart = (c2) => c2 >= "A" && c2 <=
   const fileFaceCache = new Map;
   const resolveCall = (entryPath, call) => {
     if (call.kind === "file") {
-      const filePath = resolveRel(dirOf(entryPath), call.arg);
+      const filePath = resolveRel(dirOf2(entryPath), call.arg);
       const target = filePath && entryByPath.get(filePath);
       if (!target)
         throw new Error(`${entryPath}: font("${call.arg}"): no such file in the project (resolved to "${filePath || call.arg}").`);
@@ -897,7 +973,7 @@ var FONT_ID, CODE_FILE, DECLARES_FONT, isIdentStart = (c2) => c2 >= "A" && c2 <=
   }
   for (const fw of work) {
     const entryPath = norm(fw.entry.path);
-    const dir = dirOf(entryPath);
+    const dir = dirOf2(entryPath);
     const modBase = `.${baseOf(entryPath)}.__fonts.ts`;
     const modPath = dir ? `${dir}/${modBase}` : modBase;
     const idents = new Map;
@@ -961,6 +1037,8 @@ var init_fontMacro = __esm(() => {
 var exports_compile = {};
 __export(exports_compile, {
   sceneEditorEntries: () => sceneEditorEntries,
+  scanModulesFallback: () => scanModulesFallback,
+  scanModulesChisel: () => scanModulesChisel,
   scanFontCalls: () => scanFontCalls,
   parseSfnt: () => parseSfnt,
   offsetSourceMap: () => offsetSourceMap,
@@ -969,6 +1047,7 @@ __export(exports_compile, {
   fontRegistryBase: () => fontRegistryBase,
   faceFileName: () => faceFileName,
   detectProjectKind: () => detectProjectKind,
+  detectEntry: () => detectEntry,
   compileProject: () => compileProject,
   bundleProjectWithMap: () => bundleProjectWithMap,
   bundleProject: () => bundleProject,
@@ -978,10 +1057,12 @@ __export(exports_compile, {
   SCENE_HARNESS_DIR: () => SCENE_HARNESS_DIR,
   SCENE_ENTRY_PATH: () => SCENE_ENTRY_PATH,
   FONT_REGISTRY: () => FONT_REGISTRY,
+  ENTRY_CONVENTION: () => ENTRY_CONVENTION,
   DEFAULT_FONT_REGISTRY_BASE: () => DEFAULT_FONT_REGISTRY_BASE
 });
 var init_compile = __esm(() => {
   init_bundler();
+  init_detectEntry();
   init_compileProject();
   init_sceneEditor();
   init_fontMacro();
@@ -2007,43 +2088,39 @@ var require_main = __commonJS((exports, module) => {
 // package.json
 var package_default = {
   name: "lecodes-cli",
-  version: "0.8.2",
-  description: "Clone, edit and push LeCodes projects from your machine.",
-  type: "module",
-  license: "MIT",
-  keywords: [
-    "lecodes",
-    "cli"
-  ],
+  version: "0.9.1",
+  dependencies: {
+    "@letary/chisel": "^0.5.1"
+  },
+  devDependencies: {
+    "lecodes-design": "workspace:*",
+    "lecodes-renderer": "workspace:*",
+    "qrcode-terminal": "^0.12.0",
+    "lecodes-3d-editor": "workspace:*",
+    sdk: "workspace:*"
+  },
+  peerDependencies: {
+    "lecodes-design": "^0.3.2",
+    "lecodes-renderer": "^0.7.1",
+    "lecodes-3d-editor": "^0.1.0"
+  },
   bin: {
     lecodes: "dist/index.js"
   },
+  description: "Clone, edit and push LeCodes projects from your machine.",
+  engines: {
+    node: ">=18"
+  },
   files: [
     "dist",
     "runtime",
     "README.md"
   ],
-  engines: {
-    node: ">=18"
-  },
-  scripts: {
-    icon: "bun scripts/make-icon.ts",
-    "vendor-runtime": "bun scripts/vendor-runtime.ts",
-    "sync-peers": "bun scripts/sync-peer-versions.ts",
-    build: 'bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-renderer --external lecodes-design --external lecodes-3d-editor --banner="#!/usr/bin/env node"',
-    "build:bin": "bun scripts/build-bin.ts",
-    typecheck: "tsc --noEmit",
-    dev: "bun run src/index.ts",
-    prepublishOnly: "bun run sync-peers && bun run build"
-  },
-  dependencies: {
-    "@letary/chisel": "^0.4.1"
-  },
-  peerDependencies: {
-    "lecodes-design": "^0.3.2",
-    "lecodes-renderer": "^0.6.2",
-    "lecodes-3d-editor": "^0.1.0"
-  },
+  keywords: [
+    "lecodes",
+    "cli"
+  ],
+  license: "MIT",
   peerDependenciesMeta: {
     "lecodes-design": {
       optional: true
@@ -2055,13 +2132,17 @@ var package_default = {
       optional: true
     }
   },
-  devDependencies: {
-    "lecodes-design": "workspace:*",
-    "lecodes-renderer": "workspace:*",
-    "qrcode-terminal": "^0.12.0",
-    "lecodes-3d-editor": "workspace:*",
-    sdk: "workspace:*"
-  }
+  scripts: {
+    icon: "bun scripts/make-icon.ts",
+    "vendor-runtime": "bun scripts/vendor-runtime.ts",
+    "sync-peers": "bun scripts/sync-peer-versions.ts",
+    build: 'bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-renderer --external lecodes-design --external lecodes-3d-editor --banner="#!/usr/bin/env node"',
+    "build:bin": "bun scripts/build-bin.ts",
+    typecheck: "tsc --noEmit",
+    dev: "bun run src/index.ts",
+    prepublishOnly: "bun run sync-peers && bun run build"
+  },
+  type: "module"
 };
 
 // src/commands/app.ts
@@ -2239,10 +2320,11 @@ var requireApiUrl = (config) => {
 // src/ignore.ts
 import { existsSync as existsSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { join as join3 } from "node:path";
-var BUILTIN_PATTERNS = ["node_modules/", ".git/", "_*", "*.log", ".DS_Store"];
+var BUILTIN_PATTERNS = ["node_modules/", ".git/", "_*", "*.log", ".DS_Store", ".artifacts/"];
 var DEFAULT_IGNORE_FILE = `# Files matched here are NOT pushed to LeCodes.
 # Only untracked files are affected — assets already in the project stay tracked
-# even if they match a pattern. Built-in defaults (node_modules, _*, *.log) always apply.
+# even if they match a pattern. Built-in defaults (node_modules, _*, *.log, .artifacts)
+# always apply.
 
 # Render / preview outputs (the default \`lecodes render --png\` target)
 screenshot.png
@@ -2651,6 +2733,12 @@ var resolveChiselBin2 = () => {
 var chiselBin = resolveChiselBin2();
 if (chiselBin)
   process.env.LECODES_CHISEL_BIN = chiselBin;
+var ambiguousEntryWarning = (entries) => {
+  const { entry, roots } = detectEntry(entries, scanModulesChisel);
+  if (!entry || roots.length < 2 || roots.includes(ENTRY_CONVENTION))
+    return null;
+  return `Ambiguous entrypoint: nothing imports ${roots.join(", ")} — picked ${entry}. Rename your entry to main.ts (or pass --entry).`;
+};
 var compileProject2 = (opts) => compileProject({
   entries: opts.entries.map((e) => ({ path: e.path, type: e.type, text: e.text, fileSrc: e.fileSrc, remote: e.remote, shaders: e.shaders })),
   name: opts.name,
@@ -2846,11 +2934,17 @@ var compileImpl = async (args, shell) => {
     makeResourceEntry: (path, absPath) => ({ path, type: "resource", fileSrc: encodeURI(path), absPath })
   });
   note("Compiling…");
+  const entryFlag = flagStr(args, "entry");
+  if (!entryFlag) {
+    const ambiguous = ambiguousEntryWarning(entries);
+    if (ambiguous)
+      warnErr(ambiguous);
+  }
   const js = await compileProject2({
     entries,
     name,
     publicUrl,
-    entryOverride: flagStr(args, "entry"),
+    entryOverride: entryFlag,
     header: !flagBool(args, "no-header"),
     localAssets,
     fontsHeader,
@@ -4322,6 +4416,73 @@ var clone = async (args) => {
 // src/commands/create.ts
 import { existsSync as existsSync11, mkdirSync as mkdirSync8, readdirSync as readdirSync6, writeFileSync as writeFileSync9 } from "node:fs";
 import { join as join13, resolve as resolve4 } from "node:path";
+
+// src/commands/projectTemplates.ts
+var appClaudeMd = (name) => `# ${name} — LeCodes app
+
+Guidance for AI assistants working in this folder. Human docs: README.md. The whole SDK is
+available as globals (\`UIScreen\`, \`UIText\`, \`Scene2D\`, …) — no SDK imports. \`main.ts\` is
+the entry point; split code into other \`.ts\` files and import them (relative imports only) —
+a file no other file imports is treated as an entry candidate, so keep everything reachable
+from \`main.ts\`.
+
+## Feedback loop — run the app headless instead of guessing
+
+\`\`\`
+lecodes render                    # semantic JSON of the launched UI (structure, text, names, values)
+lecodes render --png shot.png     # pixels (needs @napi-rs/canvas installed)
+lecodes render --script <file>    # drive the app through a scenario (format below)
+lecodes test                      # all tests/*.flow.json + design-derived flows; run before "done"
+\`\`\`
+
+Iterate with \`--script\` scenarios and keep the useful ones as \`tests/<name>.flow.json\` — they
+are the regression suite. A failing step dumps the failing frame (JSON + PNG) under
+\`tests/.artifacts/\` so a red step explains itself.
+
+## Scenario format (tests/*.flow.json and --script files)
+
+One action per step (\`tap\`, \`type\`+\`text\`, \`fill\`, \`scroll\` [+\`by\`], \`wait\`), then an
+optional \`expect\` (\`screen\`, \`node\`/\`notNode\`, \`text\`/\`notText\`,
+\`value: { target, equals }\`), then outputs (\`screenshot\`, \`json\`). Targets resolve by
+\`name\` → exact visible text → substring → input placeholder. Envelope keys: \`name\`,
+\`width\`/\`height\`, \`settle\`, \`fixtures\`, \`steps\`.
+
+\`\`\`json
+{ "steps": [
+  { "expect": { "screen": "home", "text": "Taps: 0" } },
+  { "tap": "tap", "expect": { "text": "Taps: 1" }, "screenshot": "after.png" }
+] }
+\`\`\`
+
+## Make the app testable
+
+- Give interactive elements a \`name\`: \`UIButton(...).style({ name: "login" })\`.
+- Name every screen's ROOT node with the screen's id — \`expect.screen\` reads it.
+- If the project has a \`design/\` folder, keep the design's screen ids and activator \`name\`s
+  in the app code: \`lecodes test\` then checks the built app against the designed navigation
+  automatically (conventions in design/CLAUDE.md).
+- Backend-gated screens: canned responses in \`tests/fixtures.json\` (URL pattern →
+  \`{ status?, json?, text? }\`; \`*\` wildcards full-match, plain strings substring-match, first
+  match wins). \`lecodes test\` auto-loads it for design-derived flows; a scenario file opts in
+  with \`"fixtures": "fixtures.json"\` in its envelope.
+- \`fill\` fills every empty input — use it before tapping a disabled-until-filled submit.
+
+## Other commands
+
+\`lecodes dev\` (run on a device with hot reload + QR), \`lecodes compile -o app.js\`
+(single-file bundle), \`lecodes design\` (screen-design board — the living spec).
+`;
+var STARTER_FLOW = `{
+  "name": "counter",
+  "steps": [
+    { "expect": { "screen": "home", "text": "Taps: 0" } },
+    { "tap": "tap", "expect": { "text": "Taps: 1" } },
+    { "tap": "tap", "expect": { "text": "Taps: 2" } }
+  ]
+}
+`;
+
+// src/commands/create.ts
 var slug2 = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
 var STARTER = `// Welcome to le.codes — no imports needed, the whole SDK is available as globals.
 const scene = new Scene2D({ background: '#10131a' })
@@ -4351,6 +4512,7 @@ var create = async (args) => {
   writeTsconfig(root);
   writeDefaultIgnore(root);
   writeFileSync9(join13(root, "main.ts"), STARTER);
+  writeFileSync9(join13(root, "CLAUDE.md"), appClaudeMd(name));
   const commits = await getCommits(apiUrl, token, uuid);
   writeManifest(root, { uuid, apiUrl, name, baseHeadId: commits.headId, files: {} });
   success(`Created ${c.bold(name)} in ${c.bold(dir)}/`);
@@ -4866,15 +5028,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 +5063,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 +5235,30 @@ 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).
+- Backend-gated transitions (a submit that must succeed to navigate) run headless through
+  \`tests/fixtures.json\` — canned API responses (URL pattern → \`{ status?, json?, text? }\`)
+  that \`lecodes test\` loads automatically for the derived flows. Shape them after the app's
+  API types; the spec.md data model is their first draft.
+
+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 +5480,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;
@@ -5981,6 +6169,11 @@ var startDevServer = async (options) => {
         publicUrl: origin,
         makeResourceEntry: (path, absPath) => ({ path, type: "resource", fileSrc: `${base}/assets` + encodeURI(path), absPath })
       });
+      if (!entryOverride) {
+        const ambiguous = ambiguousEntryWarning(entries);
+        if (ambiguous)
+          warnings.push(ambiguous);
+      }
       const js = await compileProject2({ entries, name, publicUrl: origin, entryOverride, header: true, fontsHeader });
       const changed = bundleJs === null || stripVolatile(js) !== stripVolatile(bundleJs);
       if (changed) {
@@ -6472,10 +6665,12 @@ const button = UIButton(
     justifyContent: "center",
   },
   [UIText({ color: "#ffffff", fontSize: 22 }, "Tap me")],
-).onClick(() => {
-  count++
-  counter.text = "Taps: " + count
-})
+)
+  .style({ name: "tap" }) // names make elements targetable in tests/*.flow.json (see CLAUDE.md)
+  .onClick(() => {
+    count++
+    counter.text = "Taps: " + count
+  })
 
 const screen = UIScreen(
   { backgroundColor: "#1e2230", alignItems: "center", justifyContent: "center", padding: 40 },
@@ -6485,7 +6680,7 @@ const screen = UIScreen(
       [UIText({ color: "#ffffff", fontSize: 32 }, "Hello, LeCodes"), button, counter],
     ),
   ],
-)
+).style({ name: "home" }) // the screen root's name is what tests' \`expect: { screen: … }\` reads
 
 screen.open()
 `;
@@ -6501,6 +6696,16 @@ lecodes dev                  # live on your phone: scan the QR with the LeCodes
 lecodes compile -o app.js    # bundle to a single self-contained JS file
 \`\`\`
 
+## Test it (no device needed)
+
+\`\`\`
+lecodes render --png shot.png    # headless screenshot of the running app
+lecodes test                     # run tests/*.flow.json — the starter ships with a passing one
+\`\`\`
+
+Scenario format + conventions: see [CLAUDE.md](./CLAUDE.md) (written for AI assistants, useful
+for humans too).
+
 ## Go native
 
 \`\`\`
@@ -6511,8 +6716,11 @@ lecodes app open             # open it in Xcode, build & run
 
 ## Layout
 
-- \`main.ts\` — the app. Add more top-level .ts files freely; the largest export-free one
-  is picked as the entry point.
+- \`main.ts\` — the app's entry point. Add more .ts files freely and import them from
+  \`main.ts\`; a file named \`main.ts\` is always the entry.
+- \`tests/\` — headless flow tests (\`lecodes test\`); failing steps dump the frame to
+  \`tests/.artifacts/\`
+- \`CLAUDE.md\` — guidance for AI assistants (the headless feedback loop + testability conventions)
 - \`assets/\` — images/fonts the app references (created on demand)
 - \`tsconfig.json\` + \`.lecodes/types/\` — generated IDE types (rewritten by the CLI; don't edit)
 - \`.lecodesignore\` — files a future \`lecodes push\` would skip
@@ -6538,6 +6746,8 @@ var init2 = async (args) => {
   };
   write("main.ts", STARTER2);
   write("README.md", readmeTemplate(name));
+  write("CLAUDE.md", appClaudeMd(name));
+  write("tests/counter.flow.json", STARTER_FLOW);
   write(".lecodesignore", DEFAULT_IGNORE_FILE);
   const wroteTypes = materializeTypesLocal(root);
   writeTsconfig(root);
@@ -6549,6 +6759,7 @@ var init2 = async (args) => {
   success(created ? `Local project ${c.bold(name)} ready${dirArg === "." ? "" : ` in ${c.bold(dirArg)}/`}.` : `Project ${c.bold(name)} already initialized.`);
   const cd = dirArg === "." ? "" : `cd ${dirArg} && `;
   log(`  ${c.bold(cd + "lecodes dev")}                run it on a device with hot reload`);
+  log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (no device)`);
   log(`  ${c.bold(cd + "lecodes compile -o app.js")}  bundle it for LeCodes Desktop`);
 };
 
@@ -6564,50 +6775,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,
@@ -6616,11 +6824,17 @@ var render = async (args) => {
     makeResourceEntry: (path, absPath) => ({ path, type: "resource", fileSrc: encodeURIComponent(absPath), absPath })
   } : { mode: "cdn", root });
   note("Compiling…");
+  const entryFlag = flagStr(args, "entry");
+  if (!entryFlag) {
+    const ambiguous = ambiguousEntryWarning(compileEntries);
+    if (ambiguous)
+      warnings.push(ambiguous);
+  }
   const js = await compileProject2({
     entries: compileEntries,
-    name: manifest.name,
-    publicUrl: useLocalAssets ? LOCAL_ASSET_SCHEME2 : publicUrlFlag ?? apiUrl,
-    entryOverride: flagStr(args, "entry"),
+    name,
+    publicUrl,
+    entryOverride: entryFlag,
     header: false,
     format: "iife"
   });
@@ -6630,30 +6844,141 @@ 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 resolveFixtures = (value, baseDir) => {
+  if (value === undefined)
+    return;
+  let map = value;
+  if (typeof value === "string") {
+    const abs = resolve6(baseDir, value);
+    try {
+      map = JSON.parse(readFileSync17(abs, "utf8"));
+    } catch (e) {
+      throw new CliError(`Can't read fixtures "${value}": ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+  if (typeof map !== "object" || map === null || Array.isArray(map)) {
+    throw new CliError(`Fixtures must be an object mapping URL patterns to { status?, json?, text? }.`);
+  }
+  return map;
+};
+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 envelopeFixtures = resolveFixtures(scenario?.fixtures, scriptFlag !== undefined ? dirname11(resolve6(scriptFlag)) : ".");
+  const flagFixtures = resolveFixtures(flagStr(args, "fixtures"), ".");
+  const fixtures = envelopeFixtures || flagFixtures ? { ...envelopeFixtures, ...flagFixtures } : undefined;
+  if (fixtures) {
+    try {
+      renderer.validateFixtures(fixtures);
+    } catch (e) {
+      throw new CliError(e instanceof Error ? e.message : String(e));
+    }
+  }
   const timing = {
     settleMs: settleStr !== undefined ? Number(settleStr) : undefined,
     waitNetwork: flagBool(args, "wait-network"),
     localAssets: useLocalAssets,
+    fixtures,
     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 +7019,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 +7080,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 +7103,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 +7162,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 +7217,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 +7232,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 +7244,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 +7288,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 +7301,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 +7393,254 @@ 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 { dirname as dirname14, 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.flatMap((hop) => [{ fill: {} }, { tap: hop.activator, expect: { screen: hop.to } }]),
+        { fill: {} },
+        { 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,
+    fixtures: resolveFixtures(file.fixtures, dirname14(abs)),
+    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 fixturesFlag = flagStr(args, "fixtures");
+  const defaultPack = resolve8(testsDir, "fixtures.json");
+  const flowFixtures = fixturesFlag !== undefined ? resolveFixtures(fixturesFlag, ".") : existsSync20(defaultPack) ? resolveFixtures("fixtures.json", testsDir) : undefined;
+  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, fixtures: flowFixtures });
+      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.map((f2) => ({ ...f2, fixtures: flowFixtures })));
+        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,
+        fixtures: kase.fixtures,
+        ...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 dirname16, 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 dirname15, 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 +7656,19 @@ var onPath = (dir) => {
   });
 };
 var install = async (args) => {
-  const bundle = dirname13(process.execPath);
+  const bundle = dirname15(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 +7686,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 +7697,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 +7720,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 +7758,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 +7795,9 @@ var addToUserPathWindows = (dir) => {
 
 // src/index.ts
 var STANDALONE = (() => {
-  const dir = dirname14(process.execPath);
+  const dir = dirname16(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 +7813,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;
     }
@@ -7276,7 +7832,8 @@ ${c.bold("Usage:")} lecodes <command> [options]
 
 ${c.bold("Commands:")}
   init [dir]                    Scaffold a new LOCAL project (no login/server): a starter
-                                  main.ts, IDE types + tsconfig, and a .lecodesignore.
+                                  main.ts, a CLAUDE.md + passing flow test (the headless
+                                  render/test loop), IDE types + tsconfig, a .lecodesignore.
                                   Run it with 'lecodes dev' or 'lecodes compile'.${INSTALL_HELP}
   login                         Authorize in the browser and store an access token
                                   --token <pat>   store a token from the web UI instead
@@ -7320,12 +7877,36 @@ ${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 .)
+                                  --fixtures <file>  canned fetch responses (URL pattern →
+                                                       { status?, json?, text? }) — make
+                                                       backend-gated screens reachable headless
                                   --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>/.
+                                  Design flows read tests/fixtures.json automatically (canned
+                                  fetch responses) so backend-gated transitions run headless;
+                                  file scenarios declare their own via the "fixtures" envelope.
+                                  --flows            run ONLY the design-derived flows
+                                  --no-flows         run ONLY the tests/*.flow.json files
+                                  --fixtures <file>  fixture pack for the design flows (overrides
+                                                       the tests/fixtures.json default)
+                                  --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 +7955,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 +7967,15 @@ var OPTIONAL_PEERS = [
 var peerVersion = (name, probe) => {
   try {
     const require2 = createRequire4(import.meta.url);
-    let dir = dirname14(require2.resolve(probe));
+    let dir = dirname16(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 = dirname16(dir);
       if (parent === dir)
         break;
       dir = parent;