lecodes-cli 1.0.0 → 2.0.0

package/src/commands/test.ts

@@ -1,398 +1,402 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs"
-import { dirname, resolve } from "node:path"
-import { compileHeadlessBundle } from "../compile/headlessBundle"
-import { desktopDefaultViewport, desktopPluginLibraries, resolveDesktopRenderer } from "./app/shared"
-import { desktopRenderFlags, fileScenarioIO, requireRenderer, resolveFixtures, resolveSafeAreaChoice, viewportFlags } from "./render"
-import { buildBundle } from "./compile"
-import { findProjectRoot } from "../project/manifest"
-import { runDesktopRender } from "../hosts/desktopRenderer"
-import { evaluateDesktopRun, translateScenario } from "../hosts/desktopScript"
-import { CliError, bool, c, defineCommand, log, logErr, note, num, str, warnErr, type FlagValues } from "../cli"
-import { bundleFlags, bundleOptions } from "./shared"
-
-/*
- * `lecodes test` — run the project's headless flow tests (needs the optional `lecodes-renderer`
- * package). Two sources, both executed as scenario step lists against a fresh session each:
- *
- *   1. `tests/*.flow.json` — hand-written scenarios (same schema as `lecodes render --script`:
- *      tap / type / scroll / wait / expect / screenshot / json steps).
- *   2. The design graph: when `design/meta.json` exists, every edge with an `activator` between two
- *      real screens becomes a flow test — walk to the edge's `from` screen along activator edges
- *      from the start screen, tap the activator, expect a screen named `to`. This checks the BUILT
- *      app against the DESIGNED navigation — it requires the app to keep the design's `name`s on
- *      interactive elements and to name each screen root with its design screen id.
- *      Edges without an activator (backend-driven) or targeting an `@state` are reported as
- *      "unverifiable"; edges whose `from` has no activator path (e.g. tab-bar navigation, which is
- *      a surface, not edges) are "unreachable" — cover those with a hand-written flow file.
- *
- * A failing step stops its flow and dumps the failing frame (JSON + PNG when @napi-rs/canvas is
- * installed) under tests/.artifacts/<flow>/ so a red test explains itself without a rerun.
- *
- * `--desktop` runs the file scenarios through the NATIVE host (desktopScript.ts — coordinates only,
- * expect.log checked, semantic expects reported skipped). Design-derived flows tap by activator
- * NAME, which the host can't resolve, so they stay headless-only. The viewport / timing and
- * --desktop flags are `lecodes render`'s own groups.
- */
-
-type DesignEdge = { from: string, to: string, label?: string, activator?: string }
-type DesignMeta = { screens?: Record<string, unknown>, edges?: DesignEdge[] }
-
-type FlowCase = {
-  name: string
-  kind: "file" | "flow"
-  steps: unknown
-  /** Canned fetch responses for this case's session. File scenarios: their envelope `fixtures`
-   *  (inline or a path). Design flows: the project pack (tests/fixtures.json / --fixtures). */
-  fixtures?: import("lecodes-renderer/headless").Fixtures
-  /** Per-file envelope overrides (file scenarios only). */
-  width?: number
-  height?: number
-  settle?: number
-  device?: string
-  safeArea?: string
-}
-
-type SkippedFlow = { name: string, reason: string }
-
-/** Derive flow cases from the design graph. Returns the runnable flows + the ones that can't be
- *  machine-verified (documented, not failed). */
-export const deriveDesignFlows = (meta: DesignMeta, entryScreen: string): { flows: FlowCase[], skipped: SkippedFlow[] } => {
-  const edges = meta.edges ?? []
-  const isState = (id: string) => id.includes("@")
-  const verifiable = edges.filter((e) => e.activator && !isState(e.from) && !isState(e.to))
-
-  // BFS shortest activator-path from the entry screen (over verifiable edges only).
-  const prev = new Map<string, DesignEdge>()
-  const visited = new Set<string>([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: string): DesignEdge[] | null => {
-    if (screen === entryScreen) return []
-    if (!visited.has(screen)) return null
-    const hops: DesignEdge[] = []
-    for (let at = screen; at !== entryScreen; at = hops[0].from) hops.unshift(prev.get(at)!)
-    return hops
-  }
-
-  const flows: FlowCase[] = []
-  const skipped: SkippedFlow[] = []
-  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
-    }
-    // A `fill` precedes every activator tap: submits are commonly disabled until their form is
-    // filled, and the graph tests NAVIGATION — dummy input satisfies local gates, the fixture pack
-    // answers what the submit then fetches. A no-op on screens without inputs.
-    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 }
-}
-
-const slug = (s: string): string => s.replace(/[^a-zA-Z0-9-_]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "case"
-
-/** Read one tests/*.flow.json (envelope + steps, or a bare step array). */
-const readFlowFile = (abs: string, displayName: string): FlowCase => {
-  let raw: unknown
-  try {
-    raw = JSON.parse(readFileSync(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 as { steps?: unknown }).steps === undefined) {
-    throw new CliError(`"${displayName}" must be a JSON object with "steps" (or a bare step array).`)
-  }
-  const file = raw as { name?: string, width?: number, height?: number, settle?: number, device?: string, safeArea?: string, fixtures?: Record<string, unknown> | string, steps: unknown }
-  return {
-    name: file.name ?? displayName, kind: "file", steps: file.steps,
-    fixtures: resolveFixtures(file.fixtures, dirname(abs)),
-    width: file.width, height: file.height, settle: file.settle, device: file.device, safeArea: file.safeArea,
-  }
-}
-
-const testFlags = {
-  flows: bool("run ONLY the design-derived flows"),
-  "no-flows": bool("run ONLY the tests/*.flow.json files"),
-  fixtures: str("fixture pack for the design flows (overrides the tests/fixtures.json default)", { value: "<file>" }),
-  json: bool("machine-readable report on stdout"),
-  dir: str("tests folder", { value: "<folder>", default: "tests" }),
-  "design-dir": str("design folder", { value: "<dir>", default: "design" }),
-  artifacts: str("failure-artifact folder override (default <tests>/.artifacts)", { value: "<dir>" }),
-  timeout: num("hard cap on the whole run (default 20000 + 10000 per case; --desktop 60000 + 60000 per case)", { value: "<ms>" }),
-  ...viewportFlags,
-  ...bundleFlags,
-  ...desktopRenderFlags,
-  desktop: bool("run the file scenarios through the NATIVE host (coordinates only; expect.log checked, text/node/screen/value skipped; design flows stay headless). --frames / --fixed-dt as in render --desktop"),
-}
-
-type TestFlags = FlagValues<typeof testFlags>
-
-export default defineCommand({
-  name: "test",
-  summary: "Run the flow tests (tests/*.flow.json + design-derived flows)",
-  usage: "[name…]",
-  description: "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>/.\n\nDesign flows read tests/fixtures.json automatically (canned fetch responses) so backend-gated transitions run headless; file scenarios declare their own via the \"fixtures\" envelope. [name…] runs only those files (a path, or a name under the tests folder).",
-  flags: testFlags,
-  examples: ["lecodes test", "lecodes test hero --logs", "lecodes test --flows --json", "lecodes test --desktop"],
-  run: ({ args, flags }) => runTests(args, flags),
-})
-
-const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
-  const desktop = flags.desktop
-  if (desktop && flags.flows) throw new CliError("--flows needs the headless renderer (design flows tap by name) — drop --desktop.")
-  // --desktop: ONE renderer decision (host binary + the staged .filamat variant). The root is
-  // recomputed here because `root` below comes from the headless bundle, which --desktop skips.
-  let desktopRoot: string
-  try { desktopRoot = findProjectRoot(process.cwd()) } catch { desktopRoot = process.cwd() }
-  const desktopRenderer = desktop ? resolveDesktopRenderer(desktopRoot, flags.renderer) : undefined
-  const native = desktop ? await buildBundle(bundleOptions(flags), { localAssets: true, desktopRenderer }) : null
-  const headless = desktop ? null : await compileHeadlessBundle({ entry: flags.entry, publicUrl: flags["public-url"], remoteAssets: flags["remote-assets"], waitNetwork: flags["wait-network"] })
-  const warnings = headless?.warnings ?? []
-  const useLocalAssets = headless?.useLocalAssets ?? false
-  const js = headless?.js ?? ""
-  let root: string
-  if (headless) root = headless.root
-  else { try { root = findProjectRoot(process.cwd()) } catch { root = process.cwd() } }
-  const renderer = desktop ? null : await requireRenderer()
-  const nativeFrames = flags.frames || 60
-  const nativeFixedDt = flags["fixed-dt"] ?? 16
-  if (nativeFixedDt < 0 || nativeFixedDt > 1000) throw new CliError(`--fixed-dt wants a number of ms (0 = wall clock, max 1000), got "${nativeFixedDt}".`)
-  // Desktop-only projects (app.json desktop block, no ios/android) run flows desktop-sized.
-  const projectViewport = desktopDefaultViewport(root)
-
-  const testsDir = resolve(root, flags.dir)
-  const designMetaPath = resolve(root, flags["design-dir"], "meta.json")
-  const asJson = flags.json
-  const out = asJson ? logErr : log // --json owns stdout; the human report moves to stderr
-
-  // 1. File scenarios: the given paths, or every tests/*.flow.json.
-  const cases: FlowCase[] = []
-  if (args.length > 0) {
-    for (const given of args) {
-      const candidates = [resolve(given), resolve(testsDir, given), resolve(testsDir, `${given}.flow.json`)]
-      const abs = candidates.find((p) => existsSync(p))
-      if (!abs) throw new CliError(`No such test: "${given}" (looked in ${testsDir}).`)
-      cases.push(readFlowFile(abs, given))
-    }
-  } else if (existsSync(testsDir)) {
-    for (const f of readdirSync(testsDir).filter((f) => f.endsWith(".flow.json")).sort()) {
-      cases.push(readFlowFile(resolve(testsDir, f), f))
-    }
-  }
-
-  // The project fixture pack: backing data for the design-derived flows (whose success paths are
-  // usually backend-gated). `tests/fixtures.json` is picked up automatically; --fixtures overrides
-  // the path. File scenarios do NOT inherit it — they declare their own via the envelope, so a
-  // deliberately-offline scenario (error states) stays offline.
-  const defaultPack = resolve(testsDir, "fixtures.json")
-  const flowFixtures = flags.fixtures !== undefined
-    ? resolveFixtures(flags.fixtures, ".")
-    : existsSync(defaultPack) ? resolveFixtures("fixtures.json", testsDir) : undefined
-
-  // 2. Design-graph flows (opt out with --no-flows; --flows runs ONLY these).
-  const flowsOnly = flags.flows
-  const wantFlows = !flags["no-flows"] && args.length === 0
-  if (flowsOnly) cases.length = 0
-  let skipped: SkippedFlow[] = []
-  let entryScreen: string | null = null
-  if (desktop && wantFlows && existsSync(designMetaPath)) {
-    note("Design-derived flows skipped with --desktop (they tap by name; run `lecodes test` headless for them).")
-  }
-  if (!desktop && (wantFlows || flowsOnly) && existsSync(designMetaPath)) {
-    let meta: DesignMeta
-    try {
-      meta = JSON.parse(readFileSync(designMetaPath, "utf8")) as DesignMeta
-    } catch (e) {
-      throw new CliError(`Can't read ${designMetaPath}: ${e instanceof Error ? e.message : String(e)}`)
-    }
-    if ((meta.edges ?? []).length > 0) {
-      // Probe the app for its start screen — the BFS origin of every derived flow.
-      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((f) => ({ ...f, 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).`)
-  }
-
-  // Hard timeout across the whole run (each case is bounded by settles, but a pathological app can
-  // still spin) — generous per-case allowance, overridable.
-  const timeoutMs = flags.timeout || (desktop ? 60000 + cases.length * 60000 : 20000 + cases.length * 10000)
-  const killer = setTimeout(() => {
-    warnErr(`Test run timed out after ${timeoutMs}ms (raise --timeout or lower --settle).`)
-    process.exit(1)
-  }, timeoutMs)
-  killer.unref?.()
-
-  const onConsole = flags.logs
-    ? (level: string, text: string) => logErr(`${c.dim(`[${level}]`)} ${text}`)
-    : undefined
-  const artifactsRoot = resolve(root, flags.artifacts ?? resolve(testsDir, ".artifacts"))
-
-  type CaseResult = {
-    name: string
-    kind: FlowCase["kind"]
-    ok: boolean
-    steps: { desc: string, ok: boolean, error?: string, skipped?: string[] }[]
-    error?: string
-    artifacts: string[]
-  }
-  const results: CaseResult[] = []
-
-  const reportCase = (result: CaseResult): void => {
-    const skippedCount = result.steps.reduce((n, s) => n + (s.skipped?.length ?? 0), 0)
-    if (result.ok) {
-      out(`${c.green("✓")} ${result.name}${skippedCount > 0 ? c.dim(` (${skippedCount} semantic check${skippedCount === 1 ? "" : "s"} skipped on --desktop)`) : ""}`)
-    } 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}`)}`)
-        for (const sk of s.skipped ?? []) out(c.dim(`      – skipped: ${sk}`))
-      }
-      if (result.artifacts.length > 0) out(c.dim(`    failing frame: ${result.artifacts.join(", ")}`))
-    }
-  }
-
-  // Native case runner: each case is its own host process (fresh state, like a fresh session);
-  // per-step screenshots + the final frame land under the case's artifacts folder.
-  const runNativeCase = async (kase: FlowCase): Promise<CaseResult> => {
-    const caseDir = resolve(artifactsRoot, slug(kase.name))
-    const plan = translateScenario(kase.steps, { outDir: caseDir, headroomFrames: nativeFrames })
-    for (const st of plan.steps) if (st.screenshot) mkdirSync(dirname(st.screenshot), { recursive: true })
-    mkdirSync(caseDir, { recursive: true })
-    const finalPng = resolve(caseDir, "final.png")
-    const { output } = await runDesktopRender(native!.js, native!.resources, {
-      renderer: desktopRenderer,
-      pluginDirs: desktopPluginLibraries(root).dirs,
-      width: flags.width || kase.width || projectViewport?.width || 390,
-      height: flags.height || kase.height || projectViewport?.height || 844,
-      frames: plan.frameCap, outPng: finalPng, logs: flags.logs,
-      timeoutMs: 60000 + plan.steps.length * 5000, script: plan.text, fixedDtMs: nativeFixedDt,
-    })
-    const r = evaluateDesktopRun(plan, output)
-    if (!r.loaded) throw new CliError("This desktop host doesn't support scripted input (CREATOR_SCRIPT). Update it: lecodes desktop update (or point LECODES_DESKTOP_EXE at a newer build).")
-    return {
-      name: kase.name, kind: kase.kind, ok: r.ok,
-      steps: r.steps.map((s) => ({ desc: s.desc, ok: s.ok, error: s.error, skipped: s.skipped.length > 0 ? s.skipped : undefined })),
-      error: r.ended ? undefined : "the host stopped before the script finished (frame cap / crash)",
-      artifacts: r.ok ? [] : [finalPng],
-    }
-  }
-
-  for (const kase of cases) {
-    let result: CaseResult
-    if (desktop) {
-      try {
-        result = await runNativeCase(kase)
-      } catch (e) {
-        if (e instanceof CliError && /doesn't support scripted input/.test(e.message)) throw e
-        result = { name: kase.name, kind: kase.kind, ok: false, steps: [], error: e instanceof Error ? e.message : String(e), artifacts: [] }
-      }
-      results.push(result)
-      reportCase(result)
-      continue
-    }
-    try {
-      const steps = renderer!.parseScenarioSteps(kase.steps)
-      // Every case runs in a FRESH session — no state bleeds between flows.
-      const session = await renderer!.createSession(js, {
-        width: flags.width || kase.width || projectViewport?.width || 390,
-        height: flags.height || kase.height || projectViewport?.height || 844,
-        settleMs: flags.settle ?? kase.settle,
-        waitNetwork: flags["wait-network"],
-        localAssets: useLocalAssets,
-        fixtures: kase.fixtures,
-        ...resolveSafeAreaChoice(flags["safe-area"] ?? kase.safeArea, flags.device ?? kase.device),
-        onConsole,
-      })
-      try {
-        const io = fileScenarioIO(resolve(artifactsRoot, slug(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) => resolve(artifactsRoot, slug(kase.name), p)),
-        }
-      } finally {
-        session.dispose()
-      }
-    } catch (e) {
-      // A malformed scenario / session crash is a failed case, not a dead run.
-      result = { name: kase.name, kind: kase.kind, ok: false, steps: [], error: e instanceof Error ? e.message : String(e), artifacts: [] }
-    }
-    results.push(result)
-    reportCase(result)
-  }
-
-  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) + "\n")
-  }
-
-  clearTimeout(killer)
-  process.exit(failed > 0 ? 1 : 0)
-}
+import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { compileHeadlessBundle } from "../compile/headlessBundle"
+import { desktopDefaultViewport, desktopPluginLibraries, resolveDesktopRenderer } from "./app/shared"
+import { desktopRenderFlags, fileScenarioIO, requireRenderer, resolveFixtures, resolveSafeAreaChoice, viewportFlags } from "./render"
+import { buildBundle } from "./compile"
+import { findProjectRoot } from "../project/manifest"
+import { runDesktopRender } from "../hosts/desktopRenderer"
+import { evaluateDesktopRun, translateScenario } from "../hosts/desktopScript"
+import { CliError, bool, c, defineCommand, log, logErr, note, num, str, warnErr, type FlagValues } from "../cli"
+import { bundleFlags, bundleOptions } from "./shared"
+
+/*
+ * `lecodes test` — run the project's headless flow tests (needs the optional `lecodes-headless`
+ * package). Two sources, both executed as scenario step lists against a fresh session each:
+ *
+ *   1. `tests/*.flow.json` — hand-written scenarios (same schema as `lecodes render --script`:
+ *      tap / type / scroll / wait / expect / screenshot / json steps).
+ *   2. The design graph: when `design/meta.json` exists, every edge with an `activator` between two
+ *      real screens becomes a flow test — walk to the edge's `from` screen along activator edges
+ *      from the start screen, tap the activator, expect a screen named `to`. This checks the BUILT
+ *      app against the DESIGNED navigation — it requires the app to keep the design's `name`s on
+ *      interactive elements and to name each screen root with its design screen id.
+ *      Edges without an activator (backend-driven) or targeting an `@state` are reported as
+ *      "unverifiable"; edges whose `from` has no activator path (e.g. tab-bar navigation, which is
+ *      a surface, not edges) are "unreachable" — cover those with a hand-written flow file.
+ *
+ * A failing step stops its flow and dumps the failing frame (JSON + PNG when @napi-rs/canvas is
+ * installed) under tests/.artifacts/<flow>/ so a red test explains itself without a rerun.
+ *
+ * `--desktop` runs the file scenarios through the NATIVE host (desktopScript.ts — targets by name or
+ * coordinates, expect.log + expect.paint checked, the semantic expects reported skipped). The
+ * design-derived flows need `expect.screen` and `fill`, which the host can't answer, so they stay
+ * headless-only. The viewport / timing and --desktop flags are `lecodes render`'s own groups.
+ */
+
+type DesignEdge = { from: string, to: string, label?: string, activator?: string }
+type DesignMeta = { screens?: Record<string, unknown>, edges?: DesignEdge[] }
+
+type FlowCase = {
+  name: string
+  kind: "file" | "flow"
+  steps: unknown
+  /** Canned fetch responses for this case's session. File scenarios: their envelope `fixtures`
+   *  (inline or a path). Design flows: the project pack (tests/fixtures.json / --fixtures). */
+  fixtures?: import("lecodes-headless/headless").Fixtures
+  /** Per-file envelope overrides (file scenarios only). */
+  width?: number
+  height?: number
+  settle?: number
+  device?: string
+  safeArea?: string
+}
+
+type SkippedFlow = { name: string, reason: string }
+
+/** Derive flow cases from the design graph. Returns the runnable flows + the ones that can't be
+ *  machine-verified (documented, not failed). */
+export const deriveDesignFlows = (meta: DesignMeta, entryScreen: string): { flows: FlowCase[], skipped: SkippedFlow[] } => {
+  const edges = meta.edges ?? []
+  const isState = (id: string) => id.includes("@")
+  const verifiable = edges.filter((e) => e.activator && !isState(e.from) && !isState(e.to))
+
+  // BFS shortest activator-path from the entry screen (over verifiable edges only).
+  const prev = new Map<string, DesignEdge>()
+  const visited = new Set<string>([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: string): DesignEdge[] | null => {
+    if (screen === entryScreen) return []
+    if (!visited.has(screen)) return null
+    const hops: DesignEdge[] = []
+    for (let at = screen; at !== entryScreen; at = hops[0].from) hops.unshift(prev.get(at)!)
+    return hops
+  }
+
+  const flows: FlowCase[] = []
+  const skipped: SkippedFlow[] = []
+  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
+    }
+    // A `fill` precedes every activator tap: submits are commonly disabled until their form is
+    // filled, and the graph tests NAVIGATION — dummy input satisfies local gates, the fixture pack
+    // answers what the submit then fetches. A no-op on screens without inputs.
+    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 }
+}
+
+const slug = (s: string): string => s.replace(/[^a-zA-Z0-9-_]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "case"
+
+/** Read one tests/*.flow.json (envelope + steps, or a bare step array). */
+const readFlowFile = (abs: string, displayName: string): FlowCase => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(readFileSync(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 as { steps?: unknown }).steps === undefined) {
+    throw new CliError(`"${displayName}" must be a JSON object with "steps" (or a bare step array).`)
+  }
+  const file = raw as { name?: string, width?: number, height?: number, settle?: number, device?: string, safeArea?: string, fixtures?: Record<string, unknown> | string, steps: unknown }
+  return {
+    name: file.name ?? displayName, kind: "file", steps: file.steps,
+    fixtures: resolveFixtures(file.fixtures, dirname(abs)),
+    width: file.width, height: file.height, settle: file.settle, device: file.device, safeArea: file.safeArea,
+  }
+}
+
+const testFlags = {
+  flows: bool("run ONLY the design-derived flows"),
+  "no-flows": bool("run ONLY the tests/*.flow.json files"),
+  fixtures: str("fixture pack for the design flows (overrides the tests/fixtures.json default)", { value: "<file>" }),
+  json: bool("machine-readable report on stdout"),
+  dir: str("tests folder", { value: "<folder>", default: "tests" }),
+  "design-dir": str("design folder", { value: "<dir>", default: "design" }),
+  artifacts: str("failure-artifact folder override (default <tests>/.artifacts)", { value: "<dir>" }),
+  timeout: num("hard cap on the whole run (default 20000 + 10000 per case; --desktop 60000 + 60000 per case)", { value: "<ms>" }),
+  ...viewportFlags,
+  ...bundleFlags,
+  ...desktopRenderFlags,
+  desktop: bool("run the file scenarios through the NATIVE host: the same steps, targets and expects as headless (expect.audio and the json output excepted); design flows stay headless. --frames / --fixed-dt as in render --desktop"),
+}
+// (`sim` comes with desktopRenderFlags: the file scenarios through the WINDOWLESS host — no GPU, no
+// pixels, expect.log only; the same coordinate-only contract as --desktop minus screenshots.)
+
+type TestFlags = FlagValues<typeof testFlags>
+
+export default defineCommand({
+  name: "test",
+  summary: "Run the flow tests (tests/*.flow.json + design-derived flows)",
+  usage: "[name…]",
+  description: "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>/.\n\nDesign flows read tests/fixtures.json automatically (canned fetch responses) so backend-gated transitions run headless; file scenarios declare their own via the \"fixtures\" envelope. [name…] runs only those files (a path, or a name under the tests folder).",
+  flags: testFlags,
+  examples: ["lecodes test", "lecodes test hero --logs", "lecodes test --flows --json", "lecodes test --desktop"],
+  run: ({ args, flags }) => runTests(args, flags),
+})
+
+const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
+  // --sim is the native path on the windowless host: everything --desktop does, minus pixels.
+  const sim = flags.sim
+  const desktop = flags.desktop || sim
+  if (desktop && flags.flows) throw new CliError(`--flows needs the headless renderer (design flows read expect.screen and fill inputs) — drop --${sim ? "sim" : "desktop"}.`)
+  // --desktop: ONE renderer decision (host binary + the staged .filamat variant). The root is
+  // recomputed here because `root` below comes from the headless bundle, which --desktop skips.
+  let desktopRoot: string
+  try { desktopRoot = findProjectRoot(process.cwd()) } catch { desktopRoot = process.cwd() }
+  const desktopRenderer = desktop ? resolveDesktopRenderer(desktopRoot, flags.renderer) : undefined
+  const native = desktop ? await buildBundle(bundleOptions(flags), { localAssets: true, desktopRenderer }) : null
+  const headless = desktop ? null : await compileHeadlessBundle({ entry: flags.entry, publicUrl: flags["public-url"], remoteAssets: flags["remote-assets"], waitNetwork: flags["wait-network"] })
+  const warnings = headless?.warnings ?? []
+  const useLocalAssets = headless?.useLocalAssets ?? false
+  const js = headless?.js ?? ""
+  let root: string
+  if (headless) root = headless.root
+  else { try { root = findProjectRoot(process.cwd()) } catch { root = process.cwd() } }
+  const renderer = desktop ? null : await requireRenderer()
+  const nativeFrames = flags.frames || 60
+  const nativeFixedDt = flags["fixed-dt"] ?? 16
+  if (nativeFixedDt < 0 || nativeFixedDt > 1000) throw new CliError(`--fixed-dt wants a number of ms (0 = wall clock, max 1000), got "${nativeFixedDt}".`)
+  // Desktop-only projects (app.json desktop block, no ios/android) run flows desktop-sized.
+  const projectViewport = desktopDefaultViewport(root)
+
+  const testsDir = resolve(root, flags.dir)
+  const designMetaPath = resolve(root, flags["design-dir"], "meta.json")
+  const asJson = flags.json
+  const out = asJson ? logErr : log // --json owns stdout; the human report moves to stderr
+
+  // 1. File scenarios: the given paths, or every tests/*.flow.json.
+  const cases: FlowCase[] = []
+  if (args.length > 0) {
+    for (const given of args) {
+      const candidates = [resolve(given), resolve(testsDir, given), resolve(testsDir, `${given}.flow.json`)]
+      const abs = candidates.find((p) => existsSync(p))
+      if (!abs) throw new CliError(`No such test: "${given}" (looked in ${testsDir}).`)
+      cases.push(readFlowFile(abs, given))
+    }
+  } else if (existsSync(testsDir)) {
+    for (const f of readdirSync(testsDir).filter((f) => f.endsWith(".flow.json")).sort()) {
+      cases.push(readFlowFile(resolve(testsDir, f), f))
+    }
+  }
+
+  // The project fixture pack: backing data for the design-derived flows (whose success paths are
+  // usually backend-gated). `tests/fixtures.json` is picked up automatically; --fixtures overrides
+  // the path. File scenarios do NOT inherit it — they declare their own via the envelope, so a
+  // deliberately-offline scenario (error states) stays offline.
+  const defaultPack = resolve(testsDir, "fixtures.json")
+  const flowFixtures = flags.fixtures !== undefined
+    ? resolveFixtures(flags.fixtures, ".")
+    : existsSync(defaultPack) ? resolveFixtures("fixtures.json", testsDir) : undefined
+
+  // 2. Design-graph flows (opt out with --no-flows; --flows runs ONLY these).
+  const flowsOnly = flags.flows
+  const wantFlows = !flags["no-flows"] && args.length === 0
+  if (flowsOnly) cases.length = 0
+  let skipped: SkippedFlow[] = []
+  let entryScreen: string | null = null
+  if (desktop && wantFlows && existsSync(designMetaPath)) {
+    note("Design-derived flows skipped with --desktop (they read expect.screen and fill inputs; run `lecodes test` headless for them).")
+  }
+  if (!desktop && (wantFlows || flowsOnly) && existsSync(designMetaPath)) {
+    let meta: DesignMeta
+    try {
+      meta = JSON.parse(readFileSync(designMetaPath, "utf8")) as DesignMeta
+    } catch (e) {
+      throw new CliError(`Can't read ${designMetaPath}: ${e instanceof Error ? e.message : String(e)}`)
+    }
+    if ((meta.edges ?? []).length > 0) {
+      // Probe the app for its start screen — the BFS origin of every derived flow.
+      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(...).named(\"login\")).")
+      } else {
+        const derived = deriveDesignFlows(meta, entryScreen)
+        cases.push(...derived.flows.map((f) => ({ ...f, 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).`)
+  }
+
+  // Hard timeout across the whole run (each case is bounded by settles, but a pathological app can
+  // still spin) — generous per-case allowance, overridable.
+  const timeoutMs = flags.timeout || (desktop ? 60000 + cases.length * 60000 : 20000 + cases.length * 10000)
+  const killer = setTimeout(() => {
+    warnErr(`Test run timed out after ${timeoutMs}ms (raise --timeout or lower --settle).`)
+    process.exit(1)
+  }, timeoutMs)
+  killer.unref?.()
+
+  const onConsole = flags.logs
+    ? (level: string, text: string) => logErr(`${c.dim(`[${level}]`)} ${text}`)
+    : undefined
+  const artifactsRoot = resolve(root, flags.artifacts ?? resolve(testsDir, ".artifacts"))
+
+  type CaseResult = {
+    name: string
+    kind: FlowCase["kind"]
+    ok: boolean
+    steps: { desc: string, ok: boolean, error?: string, skipped?: string[] }[]
+    error?: string
+    artifacts: string[]
+  }
+  const results: CaseResult[] = []
+
+  const reportCase = (result: CaseResult): void => {
+    const skippedCount = result.steps.reduce((n, s) => n + (s.skipped?.length ?? 0), 0)
+    if (result.ok) {
+      out(`${c.green("✓")} ${result.name}${skippedCount > 0 ? c.dim(` (${skippedCount} semantic check${skippedCount === 1 ? "" : "s"} skipped on --desktop)`) : ""}`)
+    } 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}`)}`)
+        for (const sk of s.skipped ?? []) out(c.dim(`      – skipped: ${sk}`))
+      }
+      if (result.artifacts.length > 0) out(c.dim(`    failing frame: ${result.artifacts.join(", ")}`))
+    }
+  }
+
+  // Native case runner: each case is its own host process (fresh state, like a fresh session);
+  // per-step screenshots + the final frame land under the case's artifacts folder.
+  const runNativeCase = async (kase: FlowCase): Promise<CaseResult> => {
+    const caseDir = resolve(artifactsRoot, slug(kase.name))
+    const plan = translateScenario(kase.steps, { outDir: caseDir, headroomFrames: nativeFrames, sim })
+    for (const st of plan.steps) if (st.screenshot) mkdirSync(dirname(st.screenshot), { recursive: true })
+    mkdirSync(caseDir, { recursive: true })
+    const finalPng = resolve(caseDir, "final.png")
+    const { output } = await runDesktopRender(native!.js, native!.resources, {
+      renderer: desktopRenderer, host: sim ? "server" : "desktop",
+      pluginDirs: desktopPluginLibraries(root).dirs,
+      width: flags.width || kase.width || projectViewport?.width || 390,
+      height: flags.height || kase.height || projectViewport?.height || 844,
+      frames: plan.frameCap, outPng: finalPng, logs: flags.logs,
+      timeoutMs: 60000 + plan.steps.length * 5000, script: plan.text, fixedDtMs: nativeFixedDt,
+    })
+    const r = evaluateDesktopRun(plan, output, (path) => existsSync(path) ? readFileSync(path, "utf8") : null)
+    if (!r.loaded) throw new CliError("This desktop host doesn't support scripted input (CREATOR_SCRIPT). Update it: lecodes desktop update (or point LECODES_DESKTOP_EXE at a newer build).")
+    return {
+      name: kase.name, kind: kase.kind, ok: r.ok,
+      steps: r.steps.map((s) => ({ desc: s.desc, ok: s.ok, error: s.error, skipped: s.skipped.length > 0 ? s.skipped : undefined })),
+      error: r.ended ? undefined : "the host stopped before the script finished (frame cap / crash)",
+      artifacts: r.ok ? [] : [finalPng],
+    }
+  }
+
+  for (const kase of cases) {
+    let result: CaseResult
+    if (desktop) {
+      try {
+        result = await runNativeCase(kase)
+      } catch (e) {
+        if (e instanceof CliError && /doesn't support scripted input/.test(e.message)) throw e
+        result = { name: kase.name, kind: kase.kind, ok: false, steps: [], error: e instanceof Error ? e.message : String(e), artifacts: [] }
+      }
+      results.push(result)
+      reportCase(result)
+      continue
+    }
+    try {
+      const steps = renderer!.parseScenarioSteps(kase.steps)
+      // Every case runs in a FRESH session — no state bleeds between flows.
+      const session = await renderer!.createSession(js, {
+        width: flags.width || kase.width || projectViewport?.width || 390,
+        height: flags.height || kase.height || projectViewport?.height || 844,
+        settleMs: flags.settle ?? kase.settle,
+        waitNetwork: flags["wait-network"],
+        localAssets: useLocalAssets,
+        fixtures: kase.fixtures,
+        ...resolveSafeAreaChoice(flags["safe-area"] ?? kase.safeArea, flags.device ?? kase.device),
+        onConsole,
+      })
+      try {
+        const io = fileScenarioIO(resolve(artifactsRoot, slug(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) => resolve(artifactsRoot, slug(kase.name), p)),
+        }
+      } finally {
+        session.dispose()
+      }
+    } catch (e) {
+      // A malformed scenario / session crash is a failed case, not a dead run.
+      result = { name: kase.name, kind: kase.kind, ok: false, steps: [], error: e instanceof Error ? e.message : String(e), artifacts: [] }
+    }
+    results.push(result)
+    reportCase(result)
+  }
+
+  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) + "\n")
+  }
+
+  clearTimeout(killer)
+  process.exit(failed > 0 ? 1 : 0)
+}