lecodes-cli 0.20.1 → 1.0.0

package/src/commands/push.ts

@@ -1,12 +1,12 @@
-import { basename } from "node:path"
 import { readFileSync } from "node:fs"
-import { getCommits, getProject, publishProject, sync, uploadBlob, type Project, type SyncFileInput, type SyncFolderInput } from "../api"
-import { loadConfig, requireApiUrl, requireToken } from "../config"
-import { findProjectRoot, readManifest, writeManifest, type FileKind, type Manifest, type ManifestFile } from "../manifest"
-import { classifyKind, diffLocal, hasChanges, isTextKind, scanProject } from "../localFiles"
-import { computeServerDiff } from "../serverDiff"
-import { buildPaths } from "../project"
-import { CliError, c, confirm, flagBool, flagStr, info, log, prompt, success, warn, type Args } from "../util"
+import { basename } from "node:path"
+import { CliError, bool, c, confirm, defineCommand, info, log, prompt, str, success, warn } from "../cli"
+import { getCommits, getProject, publishProject, sync, uploadBlob, type Project, type SyncFileInput, type SyncFolderInput } from "../platform/api"
+import { computeServerDiff } from "../platform/serverDiff"
+import { classifyKind, diffLocal, hasChanges, isTextKind, scanProject } from "../project/localFiles"
+import { writeManifest, type FileKind, type Manifest, type ManifestFile } from "../project/manifest"
+import { buildPaths } from "../project/materialize"
+import { linkedProject } from "./shared"
 
 /*
  * `lecodes push -m "message"` — diff the working tree against the manifest, upload changed binaries,
@@ -21,33 +21,42 @@ import { CliError, c, confirm, flagBool, flagStr, info, log, prompt, success, wa
  * arrives before the fix is a lie the reviewer has no way to detect. That ordering is why nothing
  * else in the toolchain sends a comment upward.
  */
-export const push = async (args: Args) => {
-  const root = findProjectRoot(process.cwd())
-  const manifest = readManifest(root)
-  const config = loadConfig()
-  const apiUrl = requireApiUrl(config)
-  const token = requireToken(config)
-
-  const publish = flagBool(args, "publish")
+
+export const pushFlags = {
+  message: str("checkpoint message (asked for when omitted)", { alias: "m", value: "<text>" }),
+  publish: bool("also deploy the project live (compile) with the push"),
+  force: bool("push even if the server moved on (shows + confirms which server files get overwritten)"),
+  yes: bool("skip the --force overwrite confirmation", { alias: "y" }),
+}
+
+export type PushOptions = { message?: string, publish?: boolean, force?: boolean, yes?: boolean }
+
+export default defineCommand({
+  name: "push",
+  summary: "Push local changes as one new checkpoint",
+  flags: pushFlags,
+  examples: ['lecodes push -m "Tweak the menu"', "lecodes push --publish"],
+  run: ({ flags }) => runPush(flags),
+})
+
+/** The push itself — `lecodes link --push` runs it too. */
+export const runPush = async (opts: PushOptions): Promise<void> => {
+  const { root, manifest, apiUrl, token } = linkedProject()
+  const publish = !!opts.publish
   const scan = scanProject(root, manifest)
   const diff = diffLocal(manifest, scan)
   if (!hasChanges(diff)) {
-    if (publish) {
-      await publishProject(apiUrl, token, manifest.uuid)
-      success("No file changes — published the current project state.")
-    } else {
-      info(c.dim("Working tree clean — nothing to push."))
-    }
+    if (publish) { await publishProject(apiUrl, token, manifest.uuid); success("No file changes — published the current project state.") }
+    else info(c.dim("Working tree clean — nothing to push."))
     // Still flush: a queued answer must not be stuck behind "no files changed", which is exactly the
     // state you're in after resolving a comment about something you already pushed.
-    await flushComments(args)
+    await flushComments()
     return
   }
 
-  const force = flagBool(args, "force")
   // Concurrency guard: a push rewrites the server's WHOLE tree (set-tree), so anything that changed
   // on the server since we cloned/pulled would be clobbered. Two kinds of drift to catch:
-  if (!force && manifest.baseHeadId !== null) {
+  if (!opts.force && manifest.baseHeadId !== null) {
     const commits = await getCommits(apiUrl, token, manifest.uuid)
     // (1) A new checkpoint was frozen on the server — that advances the head id.
     if (commits.headId !== manifest.baseHeadId) {
@@ -58,28 +67,24 @@ export const push = async (args: Args) => {
     // manifest (e.g. a resource was added in the editor) a blind push would silently DELETE it. Bail.
     if (commits.dirty) {
       const drift = serverPathDrift(await getProject(apiUrl, token, manifest.uuid), manifest)
-      if (drift) {
-        throw new CliError(`The project has uncommitted changes in the web editor your checkout doesn't have (${drift}). Run \`lecodes pull\` to take them, or \`lecodes push --force\` to overwrite the server.`)
-      }
+      if (drift) throw new CliError(`The project has uncommitted changes in the web editor your checkout doesn't have (${drift}). Run \`lecodes pull\` to take them, or \`lecodes push --force\` to overwrite the server.`)
     }
   }
 
   // With --force we may clobber server-side edits. Show exactly what changes on the server and
   // confirm (interactive only; skip with --yes or when piped).
-  if (force) {
+  if (opts.force) {
     const project = await getProject(apiUrl, token, manifest.uuid)
     const serverDiff = computeServerDiff(project, scan)
     if (serverDiff.length) {
       info(c.yellow(`--force will overwrite the server. ${serverDiff.length} file${serverDiff.length === 1 ? "" : "s"} change:`))
       const label: Record<string, string> = { added: c.green("  create  "), removed: c.red("  delete  "), modified: c.yellow("  update  ") }
       for (const e of serverDiff) log(label[e.status] + e.path + (e.binary ? c.dim(" (binary)") : ""))
-      if (process.stdin.isTTY && !flagBool(args, "y", "yes")) {
-        if (!(await confirm("Overwrite the server with your local copy?", false))) { info(c.dim("Aborted.")); return }
-      }
+      if (process.stdin.isTTY && !opts.yes && !(await confirm("Overwrite the server with your local copy?", false))) { info(c.dim("Aborted.")); return }
     }
   }
 
-  const message = (flagStr(args, "m", "message") ?? await prompt("Checkpoint message")) || "Update from lecodes CLI"
+  const message = (opts.message ?? await prompt("Checkpoint message")) || "Update from lecodes CLI"
 
   // The identity source for a path: the same path in the manifest, else its move origin.
   const sourceFor = (path: string): ManifestFile | undefined =>
@@ -92,10 +97,8 @@ export const push = async (args: Args) => {
     const kind: FileKind = source?.type ?? classifyKind(basename(file.path))
     const entry: SyncFileInput = { path: file.path, type: kind }
     if (source) entry.assetId = source.id
-
-    if (isTextKind(kind)) {
-      entry.text = readFileSync(file.absPath, "utf8")
-    } else if (!source || source.sha !== file.sha) {
+    if (isTextKind(kind)) entry.text = readFileSync(file.absPath, "utf8")
+    else if (!source || source.sha !== file.sha) {
       // New or changed binary — upload it and reference the fresh blob.
       const blob = await uploadBlob(apiUrl, token, manifest.uuid, basename(file.path), readFileSync(file.absPath))
       entry.blobFileId = blob.id
@@ -104,7 +107,6 @@ export const push = async (args: Args) => {
     // Else: unchanged binary — assetId alone tells the server to keep the existing blob.
     files.push(entry)
   }
-
   const folders: SyncFolderInput[] = scan.dirs.map(path => ({ path }))
 
   if (uploaded > 0) info(c.dim(`Uploaded ${uploaded} binary file${uploaded === 1 ? "" : "s"}.`))
@@ -118,9 +120,7 @@ export const push = async (args: Args) => {
   // Rebuild the manifest from the authoritative server tree + local hashes.
   const shaByPath = new Map(scan.files.map(f => [f.path, f.sha]))
   const newFiles: Record<string, ManifestFile> = {}
-  for (const node of res.nodes) {
-    newFiles[node.path] = { id: node.id, type: node.type as FileKind, sha: shaByPath.get(node.path) ?? "" }
-  }
+  for (const node of res.nodes) newFiles[node.path] = { id: node.id, type: node.type as FileKind, sha: shaByPath.get(node.path) ?? "" }
   writeManifest(root, { ...manifest, baseHeadId: res.headId, files: newFiles })
 
   const counts = [
@@ -131,19 +131,17 @@ export const push = async (args: Args) => {
   ].filter(Boolean).join(", ")
   success(`Pushed checkpoint${res.seq ? ` #${res.seq}` : ""}${counts ? ` (${counts})` : ""}: ${message}`)
   if (publish) reportPublish(res)
-  await flushComments(args)
+  await flushComments()
 }
 
 /** Send the design board's queued comment writes, now that the design they describe is up. Silent
  *  when there's no design folder, no queue, or no login — this is a rider on the push, not a step
  *  the user asked for. */
-const flushComments = async (args: Args) => {
+const flushComments = async (): Promise<void> => {
   const { flushDesignComments } = await import("./design")
-  const result = await flushDesignComments(args)
+  const result = await flushDesignComments()
   if (!result) return
-  if (result.threads) {
-    success(`Sent ${result.sent} comment update${result.sent === 1 ? "" : "s"} across ${result.threads} thread${result.threads === 1 ? "" : "s"}.`)
-  }
+  if (result.threads) success(`Sent ${result.sent} comment update${result.sent === 1 ? "" : "s"} across ${result.threads} thread${result.threads === 1 ? "" : "s"}.`)
   for (const failure of result.failures) warn(`Comment not sent — ${failure} (still queued; the next push retries it).`)
 }
 
@@ -157,17 +155,13 @@ const serverPathDrift = (project: Project, manifest: Manifest): string | null =>
   const manifestPaths = new Set(Object.keys(manifest.files))
   const added = [...serverPaths].filter(p => !manifestPaths.has(p))
   const removed = [...manifestPaths].filter(p => !serverPaths.has(p))
-  const describe = (label: string, paths: string[]) =>
-    `${paths.length} ${label} on the server: ${paths.slice(0, 3).join(", ")}${paths.length > 3 ? ", …" : ""}`
-  const parts = [
-    added.length ? describe("added", added) : "",
-    removed.length ? describe("removed", removed) : "",
-  ].filter(Boolean)
+  const describe = (label: string, paths: string[]) => `${paths.length} ${label} on the server: ${paths.slice(0, 3).join(", ")}${paths.length > 3 ? ", …" : ""}`
+  const parts = [added.length ? describe("added", added) : "", removed.length ? describe("removed", removed) : ""].filter(Boolean)
   return parts.length ? parts.join("; ") : null
 }
 
 /** Report the outcome of a --publish deploy bundled with the push (best-effort on the server). */
-const reportPublish = (res: { published?: boolean, publishError?: string }) => {
+const reportPublish = (res: { published?: boolean, publishError?: string }): void => {
   if (res.published) success("Published — the project is now live.")
   else warn(`Push landed, but publish failed: ${res.publishError ?? "unknown error"}`)
 }

package/src/commands/render.ts

@@ -1,14 +1,15 @@
 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
@@ -32,29 +33,45 @@ import { loadPeer } from "../peerInstall"
  * lecodes-renderer (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-renderer / @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)"),
+  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).
@@ -157,11 +174,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/scroll/wait/expect/screenshot/json steps; games: frames/drag/hold/key/keyDown/keyUp, expect.log, screenshot clip). With --desktop: tap/drag/hold take { x, y } coordinates (no names — the host has no UI tree; type/scroll/clip unavailable), expect.log is checked, text/node/screen/value are skipped; 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-renderer 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 ? 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,32 +257,30 @@ 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
+  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,
   })
@@ -204,10 +290,10 @@ const renderDesktop = async (args: Args) => {
   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 outDir = flags["out-dir"]
     const plan = translateScenario(scenario.steps, { outDir, headroomFrames: frames })
     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)
+    const timeoutMs = flags.timeout || (60000 + plan.steps.length * 5000)
     note(`Running ${plan.steps.length} step${plan.steps.length === 1 ? "" : "s"} (native)…`)
     const { output } = await runDesktopRender(js, resources, {
       renderer: desktopRenderer, pluginDirs,
@@ -229,7 +315,7 @@ const renderDesktop = async (args: Args) => {
     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 +324,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 +373,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 +390,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 +415,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 +433,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 +456,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())