lecodes-cli 0.9.0 → 0.9.2

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.9.0",
-  description: "Clone, edit and push LeCodes projects from your machine.",
-  type: "module",
-  license: "MIT",
-  keywords: [
-    "lecodes",
-    "cli"
-  ],
+  version: "0.9.2",
+  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.2"
-  },
-  peerDependencies: {
-    "lecodes-design": "^0.3.2",
-    "lecodes-renderer": "^0.7.0",
-    "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)}/`);
@@ -5088,6 +5250,10 @@ contract instead of a discarded sketch — but only if the app build keeps the w
   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
@@ -6003,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) {
@@ -6494,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 },
@@ -6507,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()
 `;
@@ -6523,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
 
 \`\`\`
@@ -6533,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
@@ -6560,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);
@@ -6571,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`);
 };
 
@@ -6635,11 +6824,17 @@ var compileHeadlessBundle = 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,
     publicUrl,
-    entryOverride: flagStr(args, "entry"),
+    entryOverride: entryFlag,
     header: false,
     format: "iife"
   });
@@ -6687,6 +6882,23 @@ var fileScenarioIO = (dir) => ({
     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 {
@@ -6720,10 +6932,21 @@ var render = async (args) => {
   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"),
     ...resolveSafeAreaChoice(flagStr(args, "safe-area") ?? scenario?.safeArea, flagStr(args, "device") ?? scenario?.device),
@@ -7172,7 +7395,7 @@ var status = async (_args) => {
 
 // src/commands/test.ts
 import { existsSync as existsSync20, readFileSync as readFileSync21, readdirSync as readdirSync9 } from "node:fs";
-import { resolve as resolve8 } from "node:path";
+import { dirname as dirname14, resolve as resolve8 } from "node:path";
 var deriveDesignFlows = (meta, entryScreen) => {
   const edges = meta.edges ?? [];
   const isState = (id) => id.includes("@");
@@ -7221,7 +7444,8 @@ var deriveDesignFlows = (meta, entryScreen) => {
       name,
       kind: "flow",
       steps: [
-        ...path.map((hop) => ({ tap: hop.activator, expect: { screen: hop.to } })),
+        ...path.flatMap((hop) => [{ fill: {} }, { tap: hop.activator, expect: { screen: hop.to } }]),
+        { fill: {} },
         { tap: e.activator, expect: { screen: e.to } }
       ]
     });
@@ -7242,7 +7466,17 @@ var readFlowFile = (abs, displayName) => {
     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 };
+  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);
@@ -7265,6 +7499,9 @@ var test = async (args) => {
       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)
@@ -7280,14 +7517,14 @@ var test = async (args) => {
     }
     if ((meta.edges ?? []).length > 0) {
       note("Probing the start screen…");
-      const probe = await renderer.createSession(js, { raster: false, localAssets: useLocalAssets });
+      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);
+        cases.push(...derived.flows.map((f2) => ({ ...f2, fixtures: flowFixtures })));
         skipped = derived.skipped;
       }
     }
@@ -7319,6 +7556,7 @@ var test = async (args) => {
         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
       });
@@ -7389,13 +7627,13 @@ var test = async (args) => {
 // src/index.ts
 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 dirname15, 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 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 dirname14, join as join22, resolve as resolve9, 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) => {
@@ -7418,7 +7656,7 @@ var onPath = (dir) => {
   });
 };
 var install = async (args) => {
-  const bundle = dirname14(process.execPath);
+  const bundle = dirname15(process.execPath);
   const exeName = basename12(process.execPath);
   const chiselName = isWin ? "chisel.exe" : "chisel";
   if (!existsSync21(join22(bundle, "runtime")) || !existsSync21(join22(bundle, chiselName))) {
@@ -7557,7 +7795,7 @@ var addToUserPathWindows = (dir) => {
 
 // src/index.ts
 var STANDALONE = (() => {
-  const dir = dirname15(process.execPath);
+  const dir = dirname16(process.execPath);
   const chisel = process.platform === "win32" ? "chisel.exe" : "chisel";
   return existsSync22(join23(dir, "runtime")) && existsSync22(join23(dir, chisel));
 })();
@@ -7594,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
@@ -7641,6 +7880,9 @@ ${c.bold("Commands:")}
                                   --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
@@ -7652,8 +7894,13 @@ ${c.bold("Commands:")}
                                   — 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/)
@@ -7720,7 +7967,7 @@ var OPTIONAL_PEERS = [
 var peerVersion = (name, probe) => {
   try {
     const require2 = createRequire4(import.meta.url);
-    let dir = dirname15(require2.resolve(probe));
+    let dir = dirname16(require2.resolve(probe));
     for (let depth = 0;depth < 16; depth++) {
       const manifest = join23(dir, "package.json");
       if (existsSync22(manifest)) {
@@ -7728,7 +7975,7 @@ var peerVersion = (name, probe) => {
         if (parsed.name === name)
           return parsed.version ?? "unknown";
       }
-      const parent = dirname15(dir);
+      const parent = dirname16(dir);
       if (parent === dir)
         break;
       dir = parent;