lecodes-cli 0.18.2 → 0.19.2

package/src/commands/shaders.ts

@@ -0,0 +1,157 @@
+import { readFileSync } from "node:fs"
+import { findProjectRoot, readManifest, type Manifest } from "../manifest"
+import { collectLocalEntries } from "../compile/collectLocal"
+import {
+  allShaderPlatforms, applyLocalShaders, matcIdentity, shaderCompiledPlatforms, shaderIsCompiled,
+  shadersCacheDir,
+} from "../compile/shaders"
+import { fetchMatcManifest, installedMatcVersions, resolveMatcExe, resolveMatcExeCached, updateMatc } from "../matcTool"
+import { semverNewer } from "../releases"
+import { CliError, c, flagStr, log, note, warnErr, type Args } from "../util"
+import { parseShaderSchema, type AnyShaderPlatform } from "lecodes-sdk/compile"
+
+/*
+ * `lecodes shaders` — the project's custom shaders (.mat) and their LOCAL compile
+ * (compile/shaders.ts — the same pass `lecodes dev` runs on the fly):
+ *   (no args)   list the project's shaders + their local compile state, and the matc tool status
+ *   compile     compile every shader in the project into .lecodes/shaders (downloads matc on
+ *               first use). `--platform a,b` compiles only those targets.
+ *   update      download the newest published matc (run after an engine upgrade)
+ * matc (Filament's material compiler) caches in ~/.lecodes/matc/; LECODES_MATC overrides it.
+ *
+ * A shader compiles to one artifact per target: `opengl` + `metal` (mobile profile, Android/Apple),
+ * `desktop` (desktop profile, Windows desktop GL), `desktop-vulkan` (desktop profile, SPIR-V — the
+ * Vulkan desktop host), and the `webgl-lite` JSON. Compiling all of them is the default
+ * because one bundle serves every host and the runtime picks by `_creator.backend`; `--platform`
+ * exists for when you know the target — a Windows-desktop-only project needs one of the five, and
+ * skipping the other matc runs is most of the shader step.
+ */
+
+/** The project's shader entries from the working tree (works with or without a server manifest). */
+const collectShaders = () => {
+  let root: string
+  let manifest: Manifest | null
+  try {
+    root = findProjectRoot(process.cwd())
+    manifest = readManifest(root)
+  } catch {
+    root = process.cwd()
+    manifest = null
+  }
+  const { entries } = collectLocalEntries(root, manifest, "", { localShaders: true })
+  return { root, entries, shaders: entries.filter((e) => e.type === "shader" && e.absPath) }
+}
+
+const status = async () => {
+  const { root, shaders } = collectShaders()
+
+  const installed = installedMatcVersions()
+  const matcExe = resolveMatcExeCached()
+  log(`matc            ${matcExe
+    ? (process.env.LECODES_MATC ? `LECODES_MATC=${process.env.LECODES_MATC}` : `${installed[0]}   ${c.dim("(~/.lecodes/matc)")}`)
+    : c.dim("not downloaded — fetched by `lecodes shaders compile` / `lecodes dev`")}`)
+
+  if (shaders.length === 0) {
+    log(c.dim("No .mat shaders in this project."))
+  } else {
+    const matcId = matcExe ? matcIdentity(matcExe) : null
+    log(`shaders         ${c.dim(`(compiled = up-to-date artifacts in ${shadersCacheDir(root)})`)}`)
+    const width = Math.max(...shaders.map((s) => s.path.length))
+    for (const shader of shaders) {
+      let state: string
+      if (matcId === null) state = c.dim("unknown (matc not downloaded)")
+      else {
+        const text = readFileSync(shader.absPath!, "utf8")
+        // Distinguish a deliberate subset (`--platform`, or a desktop build's single target) from a
+        // stale cache — otherwise a narrower compile reads as permanently broken and invites a full
+        // recompile that throws the saving away.
+        if (shaderIsCompiled(root, text, matcId)) state = "compiled"
+        else {
+          const present = shaderCompiledPlatforms(root, text, matcId)
+          state = present.length === 0
+            ? c.yellow("not compiled — run `lecodes shaders compile`")
+            : c.yellow(`partial (${present.join(", ")}) — \`lecodes shaders compile\` for the rest`)
+        }
+      }
+      log(`  ${shader.path.padEnd(width)}  ${state}`)
+      // the parameter table the scene editor's material card renders (sdk/compile shaderSchema)
+      const schema = parseShaderSchema(readFileSync(shader.absPath!, "utf8"))
+      for (const p of schema.params) {
+        const range = p.min !== undefined ? ` [${p.min}..${p.max}]` : ""
+        const def = p.default !== null && p.default !== undefined ? ` = ${JSON.stringify(p.default)}` : ""
+        log(`      ${c.dim(p.type.padEnd(10))} ${p.name}${c.dim(`  ${p.editor}${range}${def}`)}${p.tooltip ? c.dim(`  — ${p.tooltip}`) : ""}`)
+      }
+      for (const e of schema.errors) log(`      ${c.yellow(e)}`)
+    }
+  }
+
+  try {
+    const { latest } = await fetchMatcManifest()
+    const newest = installed[0]
+    const hint = !newest ? ""
+      : semverNewer(newest, latest) > 0 ? `   ${c.yellow("(newer — run `lecodes shaders update`)")}`
+      : latest === newest ? `   ${c.dim("(up to date)")}` : ""
+    log(`published       ${latest}${hint}`)
+  } catch (e) {
+    log(`published       ${c.dim(e instanceof CliError ? e.message : "unknown (couldn't reach the release manifest)")}`)
+  }
+}
+
+/** Parse `--platform a,b` into a validated target list. A typo must fail loudly: silently compiling
+ *  nothing would look like success and leave the cache short of what the caller asked for. */
+const parsePlatforms = (args: Args): AnyShaderPlatform[] | undefined => {
+  const raw = flagStr(args, "platform", "platforms")
+  if (raw === undefined) return undefined
+  const known = allShaderPlatforms()
+  const asked = raw.split(",").map((p) => p.trim()).filter(Boolean)
+  if (asked.length === 0) throw new CliError(`--platform needs at least one target. Known: ${known.join(", ")}`)
+  const bad = asked.filter((p) => !known.includes(p as AnyShaderPlatform))
+  if (bad.length > 0) {
+    throw new CliError(`Unknown shader platform${bad.length > 1 ? "s" : ""}: ${bad.join(", ")}\n  Known: ${known.join(", ")}`)
+  }
+  return asked as AnyShaderPlatform[]
+}
+
+/** Compile every project shader into the local cache — what `lecodes dev` does lazily, run
+ *  explicitly (e.g. to pre-warm before going offline, or to see all compile errors at once).
+ *  `--platform` narrows the targets; compiling is incremental per artifact, so a narrow run now and
+ *  a full one later add up rather than redoing each other's work. */
+const compile = async (args: Args) => {
+  const platforms = parsePlatforms(args)
+  const { root, entries, shaders } = collectShaders()
+  if (shaders.length === 0) {
+    note("No .mat shaders in this project.")
+    return
+  }
+  // Resolve matc up front so an explicit compile FAILS on an unavailable tool (the dev server's
+  // lazy pass degrades to a warning instead — see applyLocalShaders).
+  const matcExe = await resolveMatcExe()
+  const matcId = matcIdentity(matcExe)
+  const wasCompiled = new Map(shaders.map((s) => [s.path, shaderIsCompiled(root, readFileSync(s.absPath!, "utf8"), matcId)]))
+
+  const errors: string[] = []
+  for (const shader of shaders) {
+    try {
+      // One entry at a time so a broken shader doesn't hide the state of the others.
+      const { warnings } = await applyLocalShaders([shader], { root, local: true, platforms })
+      for (const w of warnings) warnErr(w)
+      log(`  ${shader.path}  ${wasCompiled.get(shader.path) ? c.dim("compiled (cached)") : "compiled"}`)
+    } catch (e) {
+      const message = e instanceof CliError ? e.message : String(e)
+      log(`  ${shader.path}  ${c.red("FAILED")}`)
+      errors.push(message)
+    }
+  }
+  for (const e of errors) log(`\n${c.red("✗")} ${e}`)
+  if (errors.length > 0) throw new CliError(`${errors.length} of ${shaders.length} shader${shaders.length === 1 ? "" : "s"} failed to compile.`)
+  const scope = platforms ? ` [${platforms.join(", ")}]` : ""
+  note(`${shaders.length} shader${shaders.length === 1 ? "" : "s"} compiled${scope} → ${shadersCacheDir(root)}`)
+}
+
+export const shaders = async (args: Args) => {
+  const sub = args._[0]
+  if (sub === undefined) return status()
+  if (sub === "compile") return compile(args)
+  if (sub === "update") return updateMatc()
+  throw new CliError(`Unknown subcommand "shaders ${sub}". Use \`lecodes shaders\` (status), \`lecodes shaders compile [--platform a,b]\` or \`lecodes shaders update\`.`)
+}

package/src/commands/status.ts

@@ -0,0 +1,29 @@
+import { findProjectRoot, readManifest } from "../manifest"
+import { diffLocal, hasChanges, scanProject } from "../localFiles"
+import { c, info, log, type Args } from "../util"
+
+/* `lecodes status` — show local changes vs the last clone/pull/push. */
+export const status = async (_args: Args) => {
+  const root = findProjectRoot(process.cwd())
+  const manifest = readManifest(root)
+  const scan = scanProject(root, manifest)
+  const diff = diffLocal(manifest, scan)
+
+  info(`Project ${c.bold(manifest.name)} (${manifest.uuid})`)
+  const ignoredNote = scan.ignored.length ? c.dim(` (${scan.ignored.length} ignored)`) : ""
+  if (!hasChanges(diff)) {
+    info(c.dim("Working tree clean — nothing to push.") + ignoredNote)
+    return
+  }
+
+  for (const f of diff.added) {
+    if (!diff.moves.has(f.path)) log(c.green(`  added     ${f.path}`))
+  }
+  for (const f of diff.modified) log(c.yellow(`  modified  ${f.path}`))
+  for (const [to, from] of diff.moves) log(c.cyan(`  moved     ${from} → ${to}`))
+  const movedFrom = new Set(diff.moves.values())
+  for (const path of diff.deleted) {
+    if (!movedFrom.has(path)) log(c.red(`  deleted   ${path}`))
+  }
+  if (scan.ignored.length) info(c.dim(`  ${scan.ignored.length} ignored (.lecodesignore)`))
+}

package/src/commands/test.ts

@@ -0,0 +1,370 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { compileHeadlessBundle } from "../compile/headlessBundle"
+import { desktopDefaultViewport, resolveDesktopRenderer } from "./appShared"
+import { fileScenarioIO, requireRenderer, resolveFixtures, resolveSafeAreaChoice } from "./render"
+import { buildBundle } from "./compile"
+import { findProjectRoot } from "../manifest"
+import { runDesktopRender } from "../desktopRenderer"
+import { evaluateDesktopRun, translateScenario } from "../desktopScript"
+import { CliError, c, flagBool, flagStr, log, logErr, note, warnErr, type Args } from "../util"
+
+/*
+ * `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.
+ */
+
+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,
+  }
+}
+
+export const test = async (args: Args) => {
+  // --desktop: run every file scenario 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.
+  const desktop = flagBool(args, "desktop")
+  if (desktop && flagBool(args, "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, args) : undefined
+  const native = desktop ? await buildBundle(args, undefined, { localAssets: true, desktopRenderer }) : null
+  const headless = desktop ? null : await compileHeadlessBundle(args)
+  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 = Number(flagStr(args, "frames")) || 60
+  const fixedDtFlag = flagStr(args, "fixed-dt")
+  const nativeFixedDt = fixedDtFlag !== undefined ? Number(fixedDtFlag) : 16
+  if (!Number.isFinite(nativeFixedDt) || nativeFixedDt < 0 || nativeFixedDt > 1000) throw new CliError(`--fixed-dt wants a number of ms (0 = wall clock, max 1000), got "${fixedDtFlag}".`)
+  // Desktop-only projects (app.json desktop block, no ios/android) run flows desktop-sized.
+  const projectViewport = desktopDefaultViewport(root)
+
+  const testsDir = resolve(root, flagStr(args, "dir") ?? "tests")
+  const designMetaPath = resolve(root, flagStr(args, "design-dir") ?? "design", "meta.json")
+  const asJson = flagBool(args, "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 fixturesFlag = flagStr(args, "fixtures")
+  const defaultPack = resolve(testsDir, "fixtures.json")
+  const flowFixtures = fixturesFlag !== undefined
+    ? resolveFixtures(fixturesFlag, ".")
+    : existsSync(defaultPack) ? resolveFixtures("fixtures.json", testsDir) : undefined
+
+  // 2. Design-graph flows (opt out with --no-flows; --flows runs ONLY these).
+  const flowsOnly = flagBool(args, "flows")
+  const wantFlows = !flagBool(args, "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 = Number(flagStr(args, "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 = flagBool(args, "logs")
+    ? (level: string, text: string) => logErr(`${c.dim(`[${level}]`)} ${text}`)
+    : undefined
+  const artifactsRoot = resolve(root, flagStr(args, "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[] = []
+
+  // 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,
+      width: Number(flagStr(args, "width")) || kase.width || projectViewport?.width || 390,
+      height: Number(flagStr(args, "height")) || kase.height || projectViewport?.height || 844,
+      frames: plan.frameCap, outPng: finalPng, logs: flagBool(args, "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) {
+    const flagSettle = flagStr(args, "settle")
+    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: Number(flagStr(args, "width")) || kase.width || projectViewport?.width || 390,
+        height: Number(flagStr(args, "height")) || kase.height || projectViewport?.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(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)
+  }
+
+  function 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(", ")}`))
+    }
+  }
+
+  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)
+}