lecodes-cli 0.20.2 → 2.0.0

package/src/commands/render.ts

@@ -1,19 +1,20 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { dirname, resolve } from "node:path"
 import { compileHeadlessBundle } from "../compile/headlessBundle"
-import { screenTargetFromArgs } from "../compile/screenEntry"
-import { findProjectRoot } from "../manifest"
+import { screenTargetFrom } from "../compile/screenEntry"
+import { findProjectRoot } from "../project/manifest"
 import { buildBundle } from "./compile"
-import { desktopDefaultViewport, desktopPluginLibraries, readAppConfigAt, resolveDesktopRenderer } from "./appShared"
-import { runDesktopRender } from "../desktopRenderer"
-import { evaluateDesktopRun, translateScenario } from "../desktopScript"
-import { CliError, c, flagStr, flagBool, isNullSink, logErr, note, warnErr, type Args } from "../util"
-import { loadPeer } from "../peerInstall"
+import { desktopDefaultViewport, desktopPluginLibraries, readAppConfigAt, resolveDesktopRenderer } from "./app/shared"
+import { runDesktopRender } from "../hosts/desktopRenderer"
+import { evaluateDesktopRun, translateScenario } from "../hosts/desktopScript"
+import { CliError, bool, c, defineCommand, isNullSink, logErr, note, num, str, warnErr, type FlagValues } from "../cli"
+import { bundleFlags, bundleOptions, outFlag } from "./shared"
+import { loadPeer } from "../hosts/peerInstall"
 
 /*
  * `lecodes render` — compile the local project and render it headless. By default it emits a
  * semantic JSON description (stdout or -o/--out); `--png [file]` also rasterizes a PNG. Rendering
- * runs locally via the optional `lecodes-renderer` package (canvas-ui + the layout WASM, and the
+ * runs locally via the optional `lecodes-headless` package (canvas-ui + the layout WASM, and the
  * GPU-free creator-2d WASM for 2D scenes); PNG also needs @napi-rs/canvas. UI and 2D (creator-2d)
  * scenes are both rendered — the 2D scene composites UNDER the UI. 3D (Filament) isn't rasterized,
  * but the scene graph is recorded and serialized into the JSON output as `scene3d` (hierarchy,
@@ -29,32 +30,49 @@ import { loadPeer } from "../peerInstall"
  *
  * `--script <file>` switches to an interactive run: the file lists steps (tap / type / scroll /
  * wait / expect / screenshot / json) executed against a live session — see the scenario schema in
- * lecodes-renderer (headless/scenario.ts). Step outputs land under --out-dir (default: the CWD);
+ * lecodes-headless (headless/scenario.ts). Step outputs land under --out-dir (default: the CWD);
  * the run stops at the first failed step and dumps the failing frame next to them.
  *
+ * `--desktop` renders through the NATIVE desktop host instead of the headless renderer — the real
+ * tgfx UI + Filament 3D + creator-2d pipeline, composited exactly as desktop users see it. PNG only
+ * (the host has no semantic-JSON serializer), no lecodes-headless / @napi-rs/canvas needed. The
+ * host binary downloads on first use (see desktopRenderer.ts); Windows + Linux for now.
+ *
  * Works in both server-backed projects (login) and local `lecodes init` projects (no login) — see
  * compile/headlessBundle.ts. Resource assets (asset('./x.png')) resolve from the local working tree
  * by default; use --remote-assets (or an explicit --public-url) to load them from the server
  * instead, which then needs --wait-network.
  *
- * Snapshot timing flags:
- *   --settle <ms>          max wait for promises/timers/fetch/image decode (ends early when idle)
- *   --wait-network         let data fetches hit the real network (off by default → empty responses)
- *   --remote-assets        load asset() resources from the server URL instead of the local disk
- *   --time <ms>            render at this animation time (0 = the initial frame-0 state)
- *   --no-after-animations  keep frame 0 instead of advancing animations to their resting state
- *   --timeout <ms>         hard cap on the whole render before aborting (default 15000; a script
- *                          run defaults to 15000 + 3000 per step)
- *   --safe-area t,r,b,l    override the safe-area insets (px) the `safe-*` keywords resolve to
- *   --device <preset>      safe-area preset: none | iphone | android (default: orientation-based).
- *                          Presets also carry the edge KIND: android's status/nav bars are exact
- *                          heights (comfort-* adds its knob past them); iphone insets are
- *                          clearance zones (comfort-* floors). --safe-area alone = all clearance.
- *   --logs                 forward the app's console.log/error (to stderr) for logic debugging
- *   --clip <name|x,y,w,h>  (--png) crop to a named node's layout rect or an explicit logical-px
- *                          rect — a component / region render instead of the whole viewport
+ * The viewport / timing flags and the --desktop flags are exported as groups because `lecodes test`
+ * takes the very same ones. The device presets carry the edge KIND: android's status/nav bars are
+ * exact heights (comfort-* adds its knob past them); iphone insets are clearance zones (comfort-*
+ * floors). --safe-area alone = all clearance.
  */
 
+// ---- flag groups (shared with `lecodes test`) ------------------------------------------------
+
+/** Viewport + snapshot timing. */
+export const viewportFlags = {
+  width: num("viewport width, logical px (default 390 — a desktop-only project renders at its window, a design screen at its board frame)"),
+  height: num("viewport height, logical px (default 844, same fallbacks)"),
+  settle: num("max wait for promises / timers / fetch / image decode before the snapshot (ends early when idle)", { value: "<ms>" }),
+  "wait-network": bool("let data fetches hit the real network (off by default → empty responses)"),
+  device: str("safe-area preset: none | iphone | android (default: orientation-based)", { value: "<preset>" }),
+  "safe-area": str("override the safe-area insets (px) the safe-* keywords resolve to", { value: "<t,r,b,l>" }),
+  logs: bool("forward the app's console output (to stderr)"),
+}
+
+/** `--desktop`: the NATIVE host in place of the headless renderer. */
+export const desktopRenderFlags = {
+  desktop: bool("render through the NATIVE desktop host instead: real Filament 3D + tgfx UI + 2D, composited. PNG only (--png). Downloads the LeCodes Desktop renderer on first use into ~/.lecodes/renderer (Windows/Linux; LECODES_DESKTOP_EXE overrides)"),
+  sim: bool("run a --script scenario through the WINDOWLESS native host (lecodes-server, beside the desktop host; LECODES_SERVER_EXE overrides): the real engine — Jolt, animators, navmesh — with no GPU and no pixels, so it runs on a CI box or a container and in parallel with an open desktop window. expect.log / expect.paint only; input is scene input (key/look/stick/drag/tap by { x, y } straight to the scene — no UI, so no names, hover or type); no screenshots, no --png"),
+  frames: num("(--desktop) frames to run before the shot — headroom for async loads", { default: 60 }),
+  "fixed-dt": num("(--desktop) virtual app clock, ms per frame — deterministic game time (scripted runs default to 16; plain renders to wall clock)", { value: "<ms>" }),
+  renderer: str("(--desktop) host + shader variant: gl | vulkan (default: app.json desktop.renderer, else gl)", { value: "<gl|vulkan>" }),
+}
+
+// ---- helpers `lecodes test` shares -----------------------------------------------------------
+
 // Approximate device safe-area presets, portrait: insets [top, right, bottom, left] (px) + which
 // edges are exact-height system BARS. `comfort-*` ADDS its knob past a bar edge (content at the
 // inset touches the chrome) and floors (max) a clearance edge (breathing room built in).
@@ -83,8 +101,8 @@ export const resolveSafeAreaChoice = (explicit: string | undefined, device: stri
 }
 
 /** The optional renderer package — installed into ~/.lecodes/peers on first use (peerInstall.ts). */
-export const requireRenderer = async (): Promise<typeof import("lecodes-renderer/headless")> =>
-  loadPeer<typeof import("lecodes-renderer/headless")>("lecodes-renderer", "headless", { for: "lecodes render" })
+export const requireRenderer = async (): Promise<typeof import("lecodes-headless/headless")> =>
+  loadPeer<typeof import("lecodes-headless/headless")>("lecodes-headless", "headless", { for: "lecodes render" })
 
 /** A file-writing ScenarioIO rooted at `dir` (creates parent folders as needed). */
 export const fileScenarioIO = (dir: string) => ({
@@ -113,7 +131,7 @@ type ScenarioFile = {
 export const resolveFixtures = (
   value: Record<string, unknown> | string | undefined,
   baseDir: string,
-): import("lecodes-renderer/headless").Fixtures | undefined => {
+): import("lecodes-headless/headless").Fixtures | undefined => {
   if (value === undefined) return undefined
   let map: unknown = value
   if (typeof value === "string") {
@@ -127,7 +145,7 @@ export const resolveFixtures = (
   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 as import("lecodes-renderer/headless").Fixtures
+  return map as import("lecodes-headless/headless").Fixtures
 }
 
 const readScenarioFile = (path: string): ScenarioFile => {
@@ -157,11 +175,82 @@ const parseClip = (raw: string | undefined): string | { x: number, y: number, wi
   throw new CliError(`--clip: expected a node name or "x,y,width,height" (got "${raw}").`)
 }
 
-/* `--desktop`: render through the NATIVE desktop host instead of the headless renderer — the real
- * tgfx UI + Filament 3D + creator-2d pipeline, composited exactly as desktop users see it. PNG
- * only (the host has no semantic-JSON serializer), no lecodes-renderer / @napi-rs/canvas needed.
- * The host binary downloads on first use (see desktopRenderer.ts); Windows + Linux for now. */
-const renderDesktop = async (args: Args) => {
+/** `--png` / `--map` take an optional file: bare = the default name, absent = off. */
+const optionalFile = (value: string | undefined, fallback: string): string | undefined =>
+  value === undefined ? undefined : value || fallback
+
+// ---- the command -----------------------------------------------------------------------------
+
+const renderFlags = {
+  state: str("([file]) the state to pass a (state) => UIScreen screen", { value: "<name>" }),
+  dir: str("([file]) the design folder a bare screen id resolves in (default design/)", { value: "<folder>" }),
+  ...outFlag,
+  png: str("rasterize a PNG (default screenshot.png; needs @napi-rs/canvas)", { value: "[file]", optional: true }),
+  map: str("draw the 3D scene's annotated top-down map (grid + XZ footprints + named markers) as <file>.png + <file>.json world-space data (default map.png; also a { \"map\": \"f.png\" } script step)", { value: "[file]", optional: true }),
+  "label-all": bool("(--map) label every object, not only the named markers"),
+  "max-px": num("(--map) longest edge of the map image, px"),
+  script: str("drive the app through a step list (tap/type/fill/scroll/hover/wait/expect/screenshot/json steps; games: frames/drag/hold/key/keyDown/keyUp, expect.log, screenshot clip). With --desktop the same steps, targets (a name or { x, y }) and expects run on the native host — only expect.audio and the json output are headless-only; per-step screenshots + final --png", { value: "<file>" }),
+  "out-dir": str("where --script step outputs land", { value: "<dir>", default: "." }),
+  clip: str("(--png) crop to one node's rect or a logical-px rect — a component / region render", { value: "<name|x,y,w,h>" }),
+  fixtures: str("canned fetch responses (URL pattern → { status?, json?, text? }) — make backend-gated screens reachable headless; merged over the scenario file's own", { value: "<file>" }),
+  scale: num("PNG device-pixel scale", { default: 2 }),
+  time: num("render at this animation time (0 = the initial frame-0 state)", { value: "<ms>" }),
+  "no-after-animations": bool("keep frame 0 instead of advancing animations to their resting state"),
+  timeout: num("hard cap on the whole render before aborting (default 15000, + 3000 per script step; --desktop 60000, + 5000 per step)", { value: "<ms>" }),
+  ...viewportFlags,
+  ...bundleFlags,
+  ...desktopRenderFlags,
+  view: str("(--desktop) inspection camera auto-fitted to the whole 3D scene: iso | top | front | side | back [--fov N]; the app's camera is untouched", { value: "<name>" }),
+  camera: str("(--desktop) inspection camera at a fixed eye point (world units, Y up) — goes with --look-at [--fov N]. In a --script run use { \"view\" } / { \"camera\" } steps", { value: "<x,y,z>" }),
+  "look-at": str("(--desktop) the point --camera looks at", { value: "<x,y,z>" }),
+  fov: num("(--desktop) vertical field of view for --view / --camera, degrees", { value: "<deg>" }),
+}
+
+type RenderFlags = FlagValues<typeof renderFlags>
+
+export default defineCommand({
+  name: "render",
+  summary: "Render the local project headless (JSON / PNG), or through the desktop host",
+  usage: "[file]",
+  description: "Needs the optional lecodes-headless package (installed on first use). [file] renders ONE screen module instead of the app: a file that default-exports a UIScreen (or a (state) => UIScreen) — every `lecodes design` screen is written that way. A bare id (\"login\") resolves in design/screens/, and a design screen renders at its meta.json frame.\n\nasset() resources load from the working tree by default; --remote-assets / --public-url use the server's copies (then data needs --wait-network).",
+  flags: renderFlags,
+  examples: [
+    "lecodes render -o ui.json",
+    "lecodes render --png shots/home.png --device iphone",
+    "lecodes render login --state empty --png",
+    "lecodes render --script tests/hero.flow.json --out-dir tests/.shots --logs",
+    "lecodes render --desktop --png --view iso",
+  ],
+  run: ({ args, flags }) => flags.desktop || flags.sim ? renderDesktop(flags, args[0]) : renderHeadless(flags, args[0]),
+})
+
+// ---- --desktop -------------------------------------------------------------------------------
+
+const VIEW_NAMES = ["iso", "top", "front", "side", "back"]
+const parseVec3Flag = (name: string, raw: string): string => {
+  const parts = raw.split(",").map((p) => p.trim())
+  if (parts.length !== 3 || parts.some((p) => !/^-?\d+(\.\d+)?$/.test(p))) throw new CliError(`--${name} wants "x,y,z" (got "${raw}").`)
+  return parts.join(",")
+}
+
+/** `--camera x,y,z --look-at x,y,z [--fov N]` → CREATOR_CAMERA; `--view name [--fov N]` → CREATOR_VIEW. */
+const resolveInspectionCamera = ({ camera: cam, "look-at": look, view, fov }: Pick<RenderFlags, "camera" | "look-at" | "view" | "fov">): { camera?: string, view?: string } => {
+  if (fov !== undefined && !(fov > 0 && fov < 180)) throw new CliError(`--fov wants degrees in (0, 180), got "${fov}".`)
+  const fovSuffix = fov !== undefined ? `;${fov}` : ""
+  if (cam !== undefined || look !== undefined) {
+    if (view !== undefined) throw new CliError("Use either --camera/--look-at or --view, not both.")
+    if (cam === undefined || look === undefined) throw new CliError("--camera and --look-at go together: --camera x,y,z --look-at x,y,z")
+    return { camera: `${parseVec3Flag("camera", cam)};${parseVec3Flag("look-at", look)}${fovSuffix}` }
+  }
+  if (view !== undefined) {
+    if (!VIEW_NAMES.includes(view)) throw new CliError(`--view wants one of ${VIEW_NAMES.join(", ")} (got "${view}").`)
+    return { view: `${view}${fovSuffix}` }
+  }
+  if (fov !== undefined) throw new CliError("--fov goes with --camera/--look-at or --view.")
+  return {}
+}
+
+const renderDesktop = async (flags: RenderFlags, file: string | undefined): Promise<void> => {
   // A project with a desktop block renders at its configured window (this IS the desktop host);
   // the phone-portrait literal stays only for projects that never declared one.
   let root: string
@@ -169,48 +258,51 @@ const renderDesktop = async (args: Args) => {
   const win = readAppConfigAt(root)?.desktop?.window
   // `render <file>`: one screen module rather than the app (see screenEntry.ts) — the native host
   // runs the same bundle, so a design screen renders through the real tgfx UI here.
-  const screen = screenTargetFromArgs(root, args)
-  const scriptFlag = flagStr(args, "script")
-  const scenario = scriptFlag !== undefined ? readScenarioFile(scriptFlag) : null
-  const width = Number(flagStr(args, "width")) || scenario?.width || screen?.frame?.[0] || win?.width || 390
-  const height = Number(flagStr(args, "height")) || scenario?.height || screen?.frame?.[1] || win?.height || 844
-  const frames = Number(flagStr(args, "frames")) || 60
-  const pngFlag = flagStr(args, "png") ?? "screenshot.png"
-  const logs = flagBool(args, "logs")
+  const screen = screenTargetFrom(root, { file, state: flags.state, entry: flags.entry, dir: flags.dir })
+  const scenario = flags.script !== undefined ? readScenarioFile(flags.script) : null
+  // --sim: the windowless host — a scripted run judged by its log; nothing to render without a script.
+  const sim = flags.sim
+  if (sim && !scenario) throw new CliError("--sim runs a --script scenario (the windowless host paints nothing to render) — add --script <file>, or use --desktop for a PNG.")
+  if (sim && flags.png) throw new CliError("--sim produces no PNG (the windowless host paints nothing) — drop --png, or use --desktop.")
+  const width = flags.width || scenario?.width || screen?.frame?.[0] || win?.width || 390
+  const height = flags.height || scenario?.height || screen?.frame?.[1] || win?.height || 844
+  const frames = flags.frames || 60
+  const pngFlag = flags.png || "screenshot.png"
+  const logs = flags.logs
   // --fixed-dt <ms>: virtual app clock (CREATOR_FIXED_DT). Scripted runs default to 16 so a held
   // key / drag / wait means the same game time on every machine; plain renders keep the wall clock
   // (their contract is "frame N", unchanged) unless asked.
-  const fixedDtFlag = flagStr(args, "fixed-dt")
-  const fixedDtMs = fixedDtFlag !== undefined ? Number(fixedDtFlag) : scenario ? 16 : 0
-  if (!Number.isFinite(fixedDtMs) || fixedDtMs < 0 || fixedDtMs > 1000) throw new CliError(`--fixed-dt wants a number of ms (0 = wall clock, max 1000), got "${fixedDtFlag}".`)
+  const fixedDtMs = flags["fixed-dt"] ?? (scenario ? 16 : 0)
+  if (fixedDtMs < 0 || fixedDtMs > 1000) throw new CliError(`--fixed-dt wants a number of ms (0 = wall clock, max 1000), got "${fixedDtMs}".`)
 
   // Inspection camera: --camera x,y,z --look-at x,y,z [--fov N], or --view iso|top|front|side|back
   // [--fov N] (auto-fitted to the scene's bounds). App input can't be trusted while it's on, so a
   // scripted run sets it per step ({ "view": … } / { "camera": … }) instead of globally.
-  const { camera, view } = resolveInspectionCamera(args)
+  const { camera, view } = resolveInspectionCamera(flags)
   if ((camera || view) && scenario) throw new CliError("--camera/--view apply to a plain render; in a --script run use a { \"view\": \"iso\" } or { \"camera\": { \"at\", \"lookAt\" } } step before the screenshot.")
 
-  // One renderer decision: the host binary AND the staged .filamat variant (see appShared).
-  const desktopRenderer = resolveDesktopRenderer(root, args)
+  // One renderer decision: the host binary AND the staged .filamat variant (see app/shared).
+  const desktopRenderer = resolveDesktopRenderer(root, flags.renderer)
   // Native plugins (project plugins/ dir + declared libraries) — the host scans CREATOR_PLUGIN_DIRS.
   const { dirs: pluginDirs } = desktopPluginLibraries(root)
-  const { js, resources } = await buildBundle(args, undefined, {
+  const { js, resources } = await buildBundle(bundleOptions(flags), {
     localAssets: true, desktopRenderer,
     extraEntries: screen ? [screen.entry] : undefined, entryOverride: screen?.entryPath,
   })
   // The host writes PNGs but never creates folders — make every output dir up front.
-  mkdirSync(dirname(resolve(pngFlag)), { recursive: true })
+  if (!sim) mkdirSync(dirname(resolve(pngFlag)), { recursive: true })
 
   if (scenario) {
     // Scripted native run: translate the scenario into the host's command file, let the host drive
     // it (it self-terminates), then read its markers back into per-step results.
-    const outDir = flagStr(args, "out-dir") ?? "."
-    const plan = translateScenario(scenario.steps, { outDir, headroomFrames: frames })
+    const outDir = flags["out-dir"]
+    const plan = translateScenario(scenario.steps, { outDir, headroomFrames: frames, sim })
     for (const st of plan.steps) if (st.screenshot) mkdirSync(dirname(st.screenshot), { recursive: true })
-    const timeoutMs = Number(flagStr(args, "timeout")) || (60000 + plan.steps.length * 5000)
-    note(`Running ${plan.steps.length} step${plan.steps.length === 1 ? "" : "s"} (native)…`)
+    const timeoutMs = flags.timeout || (60000 + plan.steps.length * 5000)
+    const label = sim ? "sim" : "native"
+    note(`Running ${plan.steps.length} step${plan.steps.length === 1 ? "" : "s"} (${label})…`)
     const { output } = await runDesktopRender(js, resources, {
-      renderer: desktopRenderer, pluginDirs,
+      renderer: desktopRenderer, host: sim ? "server" : "desktop", pluginDirs,
       width, height, frames: plan.frameCap, outPng: pngFlag, logs, timeoutMs, script: plan.text, fixedDtMs,
     })
     const result = evaluateDesktopRun(plan, output)
@@ -224,12 +316,12 @@ const renderDesktop = async (args: Args) => {
     const skippedCount = result.steps.reduce((n, s) => n + s.skipped.length, 0)
     if (skippedCount > 0) logErr(c.dim(`  ${skippedCount} semantic check${skippedCount === 1 ? "" : "s"} skipped — the native host has no UI tree; run the same scenario headless to verify them.`))
     if (!result.ended) warnErr("The host stopped before the script finished (frame cap / crash) — later steps are reported as incomplete.")
-    logErr(result.ok ? c.green(`✓ ${result.steps.length}/${result.steps.length} steps passed (native)`) : c.red(`✗ ${result.steps.filter((s) => !s.ok).length} of ${result.steps.length} steps failed (native)`))
-    note(`Wrote ${pngFlag} (${width}x${height}, native render, final frame)`)
+    logErr(result.ok ? c.green(`✓ ${result.steps.length}/${result.steps.length} steps passed (${label})`) : c.red(`✗ ${result.steps.filter((s) => !s.ok).length} of ${result.steps.length} steps failed (${label})`))
+    if (!sim) note(`Wrote ${pngFlag} (${width}x${height}, native render, final frame)`)
     process.exit(result.ok ? 0 : 1)
   }
 
-  const timeoutMs = Number(flagStr(args, "timeout")) || 60000
+  const timeoutMs = flags.timeout || 60000
   note(screen ? `Rendering ${screen.label} (native)…` : "Rendering (native)…")
   await runDesktopRender(js, resources, {
     renderer: desktopRenderer, pluginDirs,
@@ -238,72 +330,45 @@ const renderDesktop = async (args: Args) => {
   note(`Wrote ${pngFlag} (${width}x${height}, native render${view ? `, ${view.split(";")[0]} view` : camera ? ", custom camera" : ""})`)
 }
 
-const VIEW_NAMES = ["iso", "top", "front", "side", "back"]
-const parseVec3Flag = (name: string, raw: string): string => {
-  const parts = raw.split(",").map((p) => p.trim())
-  if (parts.length !== 3 || parts.some((p) => !/^-?\d+(\.\d+)?$/.test(p))) throw new CliError(`--${name} wants "x,y,z" (got "${raw}").`)
-  return parts.join(",")
-}
-/** `--camera x,y,z --look-at x,y,z [--fov N]` → CREATOR_CAMERA; `--view name [--fov N]` → CREATOR_VIEW. */
-const resolveInspectionCamera = (args: Args): { camera?: string, view?: string } => {
-  const cam = flagStr(args, "camera"), look = flagStr(args, "look-at"), view = flagStr(args, "view"), fov = flagStr(args, "fov")
-  if (fov !== undefined && !(Number(fov) > 0 && Number(fov) < 180)) throw new CliError(`--fov wants degrees in (0, 180), got "${fov}".`)
-  const fovSuffix = fov !== undefined ? `;${Number(fov)}` : ""
-  if (cam !== undefined || look !== undefined) {
-    if (view !== undefined) throw new CliError("Use either --camera/--look-at or --view, not both.")
-    if (cam === undefined || look === undefined) throw new CliError("--camera and --look-at go together: --camera x,y,z --look-at x,y,z")
-    return { camera: `${parseVec3Flag("camera", cam)};${parseVec3Flag("look-at", look)}${fovSuffix}` }
-  }
-  if (view !== undefined) {
-    if (!VIEW_NAMES.includes(view)) throw new CliError(`--view wants one of ${VIEW_NAMES.join(", ")} (got "${view}").`)
-    return { view: `${view}${fovSuffix}` }
-  }
-  if (fov !== undefined) throw new CliError("--fov goes with --camera/--look-at or --view.")
-  return {}
-}
-
-export const render = async (args: Args) => {
-  if (flagBool(args, "desktop")) return renderDesktop(args)
+// ---- headless --------------------------------------------------------------------------------
 
-  const scriptFlag = flagStr(args, "script")
-  const scenario = scriptFlag !== undefined ? readScenarioFile(scriptFlag) : null
+const renderHeadless = async (flags: RenderFlags, file: string | undefined): Promise<void> => {
+  const scenario = flags.script !== undefined ? readScenarioFile(flags.script) : null
 
   // `render <file>`: render that one screen module instead of the app's own entrypoint.
   let projectRoot: string
   try { projectRoot = findProjectRoot(process.cwd()) } catch { projectRoot = process.cwd() }
-  const screen = screenTargetFromArgs(projectRoot, args)
+  const screen = screenTargetFrom(projectRoot, { file, state: flags.state, entry: flags.entry, dir: flags.dir })
 
   // Hard timeout so a pathological scene (stuck fetch, runaway loop) can't hang the CLI. Scripts get
   // a per-step allowance. Unref'd so it never itself keeps the process alive once we're done.
   const stepCount = scenario && Array.isArray(scenario.steps) ? scenario.steps.length : 0
-  const timeoutMs = Number(flagStr(args, "timeout")) || (15000 + stepCount * 3000)
+  const timeoutMs = flags.timeout || (15000 + stepCount * 3000)
   const killer = setTimeout(() => {
     warnErr(`Render timed out after ${timeoutMs}ms (try --settle / --wait-network, or raise --timeout).`)
     process.exit(1)
   }, timeoutMs)
   killer.unref?.()
 
-  const { js, warnings, useLocalAssets, root } = await compileHeadlessBundle(args, { screen })
+  const { js, warnings, useLocalAssets, root } = await compileHeadlessBundle({ screen, entry: flags.entry, publicUrl: flags["public-url"], remoteAssets: flags["remote-assets"], waitNetwork: flags["wait-network"] })
   const renderer = await requireRenderer()
 
   // Flags override the scenario file's envelope; both fall back to the project default (a
   // desktop-only app.json renders desktop-sized), then the phone-portrait literals.
   // A design screen carries its own board frame (meta.json), which beats the app-wide default.
   const projectViewport = desktopDefaultViewport(root)
-  const width = Number(flagStr(args, "width")) || scenario?.width || screen?.frame?.[0] || projectViewport?.width || 390
-  const height = Number(flagStr(args, "height")) || scenario?.height || screen?.frame?.[1] || projectViewport?.height || 844
-
-  // Shared snapshot-timing options (see the header comment). `--logs` forwards the app's console to
-  // stderr (kept off stdout so it never corrupts the JSON/PNG result there).
-  const settleStr = flagStr(args, "settle") ?? (scenario?.settle !== undefined ? String(scenario.settle) : undefined)
-  const timeStr = flagStr(args, "time")
-  const onConsole = flagBool(args, "logs")
+  const width = flags.width || scenario?.width || screen?.frame?.[0] || projectViewport?.width || 390
+  const height = flags.height || scenario?.height || screen?.frame?.[1] || projectViewport?.height || 844
+
+  // Shared snapshot-timing options. `--logs` forwards the app's console to stderr (kept off stdout
+  // so it never corrupts the JSON/PNG result there).
+  const onConsole = flags.logs
     ? (level: string, text: string) => logErr(`${c.dim(`[${level}]`)} ${text}`)
     : undefined
   // Fixtures: the scenario file's (inline map or a path), with a `--fixtures <file>` flag merged
   // over it (flag patterns win on collision). Validated here so a typo is a clean CLI error.
-  const envelopeFixtures = resolveFixtures(scenario?.fixtures, scriptFlag !== undefined ? dirname(resolve(scriptFlag)) : ".")
-  const flagFixtures = resolveFixtures(flagStr(args, "fixtures"), ".")
+  const envelopeFixtures = resolveFixtures(scenario?.fixtures, flags.script !== undefined ? dirname(resolve(flags.script)) : ".")
+  const flagFixtures = resolveFixtures(flags.fixtures, ".")
   const fixtures = envelopeFixtures || flagFixtures ? { ...envelopeFixtures, ...flagFixtures } : undefined
   if (fixtures) {
     try {
@@ -314,13 +379,13 @@ export const render = async (args: Args) => {
   }
 
   const timing = {
-    settleMs: settleStr !== undefined ? Number(settleStr) : undefined,
-    waitNetwork: flagBool(args, "wait-network"),
+    settleMs: flags.settle ?? scenario?.settle,
+    waitNetwork: flags["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),
+    timeMs: flags.time,
+    afterAnimations: !flags["no-after-animations"],
+    ...resolveSafeAreaChoice(flags["safe-area"] ?? scenario?.safeArea, flags.device ?? scenario?.device),
     onConsole,
   }
 
@@ -331,7 +396,7 @@ export const render = async (args: Args) => {
   // --script: drive the compiled app through the scenario steps against a live session.
   if (scenario) {
     const steps = renderer.parseScenarioSteps(scenario.steps)
-    const outDir = flagStr(args, "out-dir") ?? "."
+    const outDir = flags["out-dir"]
     // Screenshots require pixels; otherwise rasterize opportunistically (napi installed → failure
     // PNGs and real Skia text metrics, absent → deterministic HeadlessHost metrics).
     const needsRaster = steps.some((s) => s.screenshot !== undefined)
@@ -356,12 +421,12 @@ export const render = async (args: Args) => {
   // --map [file]: draw the 3D scene's annotated top-down map (grid + XZ footprints + named
   // markers) instead of a screenshot — the level-design view. Writes <file>.png + <file>.json
   // (the same data, world-space, queryable). Default map.png. `--label-all` labels every object.
-  const mapFlag = flagStr(args, "map") ?? (flagBool(args, "map") ? "map.png" : undefined)
+  const mapFlag = optionalFile(flags.map, "map.png")
   if (mapFlag !== undefined) {
     note(`Rendering map…`)
     const title = root.split(/[\\/]/).pop()
     const { png, data, warnings: mapWarnings } = await renderer.renderToMap(js, {
-      ...timing, maxPx: Number(flagStr(args, "max-px")) || undefined, title, labelAll: flagBool(args, "label-all"),
+      ...timing, maxPx: flags["max-px"] || undefined, title, labelAll: flags["label-all"],
     })
     for (const w of [ ...warnings, ...mapWarnings ]) warnErr(w)
     const pngPath = mapFlag.endsWith(".png") ? mapFlag : mapFlag + ".png"
@@ -374,12 +439,12 @@ export const render = async (args: Args) => {
   }
 
   // --png [file]: rasterize a PNG (binary → always to a file, default screenshot.png).
-  const pngFlag = flagStr(args, "png") ?? (flagBool(args, "png") ? "screenshot.png" : undefined)
+  const pngFlag = optionalFile(flags.png, "screenshot.png")
   if (pngFlag !== undefined) {
     note(screen ? `Rendering ${screen.label} (PNG)…` : "Rendering PNG…")
-    const clip = parseClip(flagStr(args, "clip"))
+    const clip = parseClip(flags.clip)
     const { png, width: outW, height: outH, warnings: pngWarnings } = await renderer.renderToPng(js, {
-      width, height, scale: Number(flagStr(args, "scale")) || 2, ...timing, clip,
+      width, height, scale: flags.scale || 2, ...timing, clip,
     })
     for (const w of [ ...warnings, ...pngWarnings ]) warnErr(w)
     if (isNullSink(pngFlag)) {
@@ -397,7 +462,7 @@ export const render = async (args: Args) => {
 
   for (const w of [ ...warnings, ...result.warnings ]) warnErr(w)
 
-  const out = flagStr(args, "o", "out")
+  const out = flags.out
   if (out && isNullSink(out)) {
     note(`Discarded output (${out})`)
     return done((cb) => cb())