lecodes-cli 0.19.0 → 0.19.2

package/src/commands/render.ts

@@ -0,0 +1,414 @@
+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 { buildBundle } from "./compile"
+import { desktopDefaultViewport, 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"
+
+/*
+ * `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
+ * 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,
+ * transforms, meshes, materials, lights, GLB structure + animations).
+ * --time advances the 2D simulation (physics/animation) to that instant.
+ *
+ * `lecodes render <file>` renders ONE screen module instead of the launched app: a file that
+ * default-exports a `UIScreen` (or a `(state) => UIScreen` function — pick the branch with
+ * `--state`), which is how every `lecodes design` screen is written. It compiles as part of the
+ * project (its imports and asset() files resolve normally), and a design screen picks up its board
+ * frame from the design folder's meta.json unless --width/--height say otherwise. A bare id
+ * ("login") is looked up in design/screens/ (--dir overrides the folder).
+ *
+ * `--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);
+ * the run stops at the first failed step and dumps the failing frame next to them.
+ *
+ * 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
+ */
+
+// 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).
+const DEVICE_SAFE_AREA: Record<string, { insets: [number, number, number, number]; bars: ("top" | "right" | "bottom" | "left")[] }> = {
+  none: { insets: [0, 0, 0, 0], bars: [] },
+  iphone: { insets: [59, 0, 34, 0], bars: [] }, // Dynamic Island + home indicator (iPhone 14 Pro+) — clearance built in
+  android: { insets: [24, 0, 48, 0], bars: ["top", "bottom"] }, // status bar + 3-button navigation bar (matches the design board's shell)
+}
+
+type SafeAreaChoice = { safeArea: [number, number, number, number]; safeAreaBars: ("top" | "right" | "bottom" | "left")[] }
+
+/** Resolve an explicit `t,r,b,l` string (wins; clearance edges) or a device preset, or undefined.
+ *  Shared by the flag form (`--safe-area` / `--device`) and a script file's envelope fields. */
+export const resolveSafeAreaChoice = (explicit: string | undefined, device: string | undefined): SafeAreaChoice | undefined => {
+  if (explicit) {
+    const n = explicit.split(",").map((s) => Number(s.trim()))
+    if (n.length === 4 && n.every((v) => Number.isFinite(v))) return { safeArea: n as [number, number, number, number], safeAreaBars: [] }
+    throw new CliError(`--safe-area expects "top,right,bottom,left" (4 numbers), got "${explicit}".`)
+  }
+  if (device) {
+    const preset = DEVICE_SAFE_AREA[device]
+    if (!preset) throw new CliError(`Unknown --device "${device}". Options: ${Object.keys(DEVICE_SAFE_AREA).join(", ")}.`)
+    return { safeArea: preset.insets, safeAreaBars: preset.bars }
+  }
+  return undefined
+}
+
+/** Import the optional renderer package or fail with the install hint. */
+export const requireRenderer = async (): Promise<typeof import("lecodes-renderer/headless")> => {
+  try {
+    return await import("lecodes-renderer/headless")
+  } catch {
+    throw new CliError("The renderer isn't installed. Run:  npm install -g lecodes-renderer")
+  }
+}
+
+/** A file-writing ScenarioIO rooted at `dir` (creates parent folders as needed). */
+export const fileScenarioIO = (dir: string) => ({
+  write: (relPath: string, data: string | Uint8Array) => {
+    const abs = resolve(dir, relPath)
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, data)
+  },
+})
+
+/** The parsed envelope of a scenario file: viewport/timing fields + the raw steps. `fixtures` is
+ *  a canned-response map (URL pattern → { status?, json?, text? }) or a path to a JSON file of one. */
+type ScenarioFile = {
+  name?: string
+  width?: number
+  height?: number
+  settle?: number
+  device?: string
+  safeArea?: string
+  fixtures?: Record<string, unknown> | string
+  steps: unknown
+}
+
+/** Resolve a fixtures value — an inline map, or a string path to a JSON file holding one —
+ *  relative to `baseDir`. Throws a CliError on bad shapes (with the offending pattern). */
+export const resolveFixtures = (
+  value: Record<string, unknown> | string | undefined,
+  baseDir: string,
+): import("lecodes-renderer/headless").Fixtures | undefined => {
+  if (value === undefined) return undefined
+  let map: unknown = value
+  if (typeof value === "string") {
+    const abs = resolve(baseDir, value)
+    try {
+      map = JSON.parse(readFileSync(abs, "utf8"))
+    } catch (e) {
+      throw new CliError(`Can't read fixtures "${value}": ${e instanceof Error ? e.message : String(e)}`)
+    }
+  }
+  if (typeof map !== "object" || map === null || Array.isArray(map)) {
+    throw new CliError(`Fixtures must be an object mapping URL patterns to { status?, json?, text? }.`)
+  }
+  return map as import("lecodes-renderer/headless").Fixtures
+}
+
+const readScenarioFile = (path: string): ScenarioFile => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(readFileSync(resolve(path), "utf8"))
+  } catch (e) {
+    throw new CliError(`Can't read scenario "${path}": ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (Array.isArray(raw)) return { steps: raw } // a bare step array is a valid scenario file
+  if (typeof raw !== "object" || raw === null) throw new CliError(`Scenario "${path}" must be a JSON object with "steps" (or a bare step array).`)
+  const file = raw as ScenarioFile
+  if (file.steps === undefined) throw new CliError(`Scenario "${path}" has no "steps".`)
+  return file
+}
+
+/** `--clip <name|x,y,w,h>`: a node name (its layout rect) or an explicit logical-px rect. */
+const parseClip = (raw: string | undefined): string | { x: number, y: number, width: number, height: number } | undefined => {
+  if (raw === undefined) return undefined
+  const parts = raw.split(",").map((p) => p.trim())
+  if (parts.length === 4 && parts.every((p) => /^-?\d+(\.\d+)?$/.test(p))) {
+    const [x, y, width, height] = parts.map(Number)
+    if (width <= 0 || height <= 0) throw new CliError(`--clip: width and height must be positive (got "${raw}").`)
+    return { x, y, width, height }
+  }
+  if (parts.length === 1 && raw.trim() !== "") return raw.trim()
+  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) => {
+  // 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
+  try { root = findProjectRoot(process.cwd()) } catch { root = process.cwd() }
+  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")
+  // --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}".`)
+
+  // 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)
+  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)
+  const { js, resources } = await buildBundle(args, undefined, {
+    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 (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 })
+    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 { output } = await runDesktopRender(js, resources, {
+      renderer: desktopRenderer,
+      width, height, frames: plan.frameCap, outPng: pngFlag, logs, timeoutMs, script: plan.text, fixedDtMs,
+    })
+    const result = evaluateDesktopRun(plan, output)
+    if (!result.loaded) {
+      throw new CliError("This desktop host doesn't support scripted input (CREATOR_SCRIPT) — it ran the frames and ignored the steps. Update it: lecodes desktop update (or point LECODES_DESKTOP_EXE at a newer build).")
+    }
+    for (const st of result.steps) {
+      logErr(st.ok ? `${c.green("✓")} ${st.desc}` : `${c.red("✗")} ${st.desc}\n  ${c.red(st.error ?? "failed")}`)
+      for (const sk of st.skipped) logErr(c.dim(`  – skipped: ${sk}`))
+    }
+    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)`)
+    process.exit(result.ok ? 0 : 1)
+  }
+
+  const timeoutMs = Number(flagStr(args, "timeout")) || 60000
+  note(screen ? `Rendering ${screen.label} (native)…` : "Rendering (native)…")
+  await runDesktopRender(js, resources, {
+    renderer: desktopRenderer,
+    width, height, frames, outPng: pngFlag, logs, timeoutMs, fixedDtMs, camera, view,
+  })
+  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)
+
+  const scriptFlag = flagStr(args, "script")
+  const scenario = scriptFlag !== undefined ? readScenarioFile(scriptFlag) : 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)
+
+  // 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 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 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")
+    ? (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 fixtures = envelopeFixtures || flagFixtures ? { ...envelopeFixtures, ...flagFixtures } : undefined
+  if (fixtures) {
+    try {
+      renderer.validateFixtures(fixtures)
+    } catch (e) {
+      throw new CliError(e instanceof Error ? e.message : String(e))
+    }
+  }
+
+  const timing = {
+    settleMs: settleStr !== undefined ? Number(settleStr) : undefined,
+    waitNetwork: flagBool(args, "wait-network"),
+    localAssets: useLocalAssets,
+    fixtures,
+    timeMs: timeStr !== undefined ? Number(timeStr) : undefined,
+    afterAnimations: !flagBool(args, "no-after-animations"),
+    ...resolveSafeAreaChoice(flagStr(args, "safe-area") ?? scenario?.safeArea, flagStr(args, "device") ?? scenario?.device),
+    onConsole,
+  }
+
+  // Clean process exit: clear the timeout guard, flush the given output, then exit. Without this the
+  // process could linger (e.g. on stdout pipe back-pressure) even though the render is done.
+  const done = (flush: (cb: () => void) => void, code = 0) => flush(() => { clearTimeout(killer); process.exit(code) })
+
+  // --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") ?? "."
+    // 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)
+    note(`Running ${steps.length} step${steps.length === 1 ? "" : "s"}…`)
+    const session = await renderer.createSession(js, { width, height, ...timing, raster: needsRaster ? true : "auto" })
+    try {
+      const result = await renderer.runScenario(session, steps, fileScenarioIO(outDir))
+      for (const w of [ ...warnings, ...session.warnings ]) warnErr(w)
+      for (const st of result.steps) {
+        logErr(st.ok ? `${c.green("✓")} ${st.desc}` : `${c.red("✗")} ${st.desc}\n  ${c.red(st.error ?? "failed")}`)
+      }
+      if (!result.ok && result.failureArtifacts.length > 0) {
+        logErr(c.dim(`  failing frame: ${result.failureArtifacts.map((p) => resolve(outDir, p)).join(", ")}`))
+      }
+      logErr(result.ok ? c.green(`✓ ${result.steps.length}/${steps.length} steps passed`) : c.red(`✗ failed at step ${result.steps.length} of ${steps.length}`))
+      return done((cb) => cb(), result.ok ? 0 : 1)
+    } finally {
+      session.dispose()
+    }
+  }
+
+  // --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)
+  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"),
+    })
+    for (const w of [ ...warnings, ...mapWarnings ]) warnErr(w)
+    const pngPath = mapFlag.endsWith(".png") ? mapFlag : mapFlag + ".png"
+    mkdirSync(dirname(resolve(pngPath)), { recursive: true })
+    writeFileSync(resolve(pngPath), png)
+    const jsonPath = pngPath.slice(0, -4) + ".json"
+    writeFileSync(resolve(jsonPath), JSON.stringify(data, null, 2))
+    note(`Wrote ${pngPath} + ${jsonPath}`)
+    return done((cb) => cb())
+  }
+
+  // --png [file]: rasterize a PNG (binary → always to a file, default screenshot.png).
+  const pngFlag = flagStr(args, "png") ?? (flagBool(args, "png") ? "screenshot.png" : undefined)
+  if (pngFlag !== undefined) {
+    note(screen ? `Rendering ${screen.label} (PNG)…` : "Rendering PNG…")
+    const clip = parseClip(flagStr(args, "clip"))
+    const { png, width: outW, height: outH, warnings: pngWarnings } = await renderer.renderToPng(js, {
+      width, height, scale: Number(flagStr(args, "scale")) || 2, ...timing, clip,
+    })
+    for (const w of [ ...warnings, ...pngWarnings ]) warnErr(w)
+    if (isNullSink(pngFlag)) {
+      note(`Discarded PNG (${pngFlag})`)
+    } else {
+      mkdirSync(dirname(resolve(pngFlag)), { recursive: true }) // --png shots/home.png: make the folder, like the native path does
+      writeFileSync(resolve(pngFlag), png)
+      note(`Wrote ${pngFlag} (${png.length} bytes, ${outW}x${outH}${clip !== undefined ? ", clipped" : ""})`)
+    }
+    return done((cb) => cb())
+  }
+
+  note(screen ? `Rendering ${screen.label}…` : "Rendering…")
+  const result = await renderer.renderToJson(js, { width, height, ...timing })
+
+  for (const w of [ ...warnings, ...result.warnings ]) warnErr(w)
+
+  const out = flagStr(args, "o", "out")
+  if (out && isNullSink(out)) {
+    note(`Discarded output (${out})`)
+    return done((cb) => cb())
+  }
+  if (out) {
+    writeFileSync(resolve(out), result.text)
+    note(`Wrote ${out} (${result.text.length} bytes)`)
+    return done((cb) => cb())
+  }
+  const text = result.text.endsWith("\n") ? result.text : result.text + "\n"
+  return done((cb) => process.stdout.write(text, cb))
+}

package/src/commands/scene.ts

@@ -0,0 +1,148 @@
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import { findProjectRoot, readManifest, type Manifest } from "../manifest"
+import { compileSceneEditor } from "../compile/sceneCompile"
+import { localShaderArtifact } from "../compile/shaders"
+import { openBrowser } from "../browserAuth"
+import { CliError, c, flagBool, flagStr, log, note, warnErr, type Args } from "../util"
+
+/*
+ * `lecodes scene [path]` — the 3D scene editor (lecodes-tools/packages/lecodes-3d-editor) hosted on a local project,
+ * exactly the way `lecodes design` hosts the design board. Starts scene-editor's node:http server,
+ * injects the CLI's compile closure (chisel + the vendored SDK + a vendored harness), and opens the
+ * browser. `.scene.ts` files are edited visually (tree + inspector) and written back to disk;
+ * external (IDE) edits hot-reload over SSE.
+ *
+ * Root resolution mirrors `design`: inside a cloned project the whole project is the compile input;
+ * anywhere else it runs standalone against the current directory (or a folder/scene passed as `path`).
+ */
+
+const DEFAULT_PORT = 4488
+
+type SceneContext = {
+  root: string
+  /** Null in standalone mode: the scene lives outside any cloned lecodes project. */
+  manifest: Manifest | null
+  name: string
+}
+
+/** The nearest ancestor (inclusive) holding an `app.json` — a local project's root — or null. */
+const findAppRoot = (start: string): string | null => {
+  let dir = start
+  while (true) {
+    if (existsSync(join(dir, "app.json"))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** The project a DIRECTORY belongs to: a cloned project's root, else the nearest ancestor with an
+ *  app.json, else the directory itself. `lecodes thumbs` resolves its root this way — its
+ *  positional args are targets, not the root, so it can't go through getContext. */
+export const projectRootOf = (dir: string): string => {
+  try {
+    return findProjectRoot(dir)
+  } catch {
+    return findAppRoot(dir) ?? dir
+  }
+}
+
+const getContext = (args: Args): SceneContext => {
+  let root: string
+  let manifest: Manifest | null
+  try {
+    root = findProjectRoot(process.cwd())
+    manifest = readManifest(root)
+  } catch {
+    // Standalone (a local project without a platform manifest): the current directory, or a
+    // folder / .scene.ts passed as the positional arg. The whole-project compile needs the PROJECT
+    // root — a scene file's imports (`../weaponRig`) resolve against it — so walk up to the nearest
+    // `app.json`; only without one does a scene path fall back to its containing dir.
+    root = process.cwd()
+    manifest = null
+    const pathArg = args._[0]
+    if (pathArg) {
+      const abs = resolve(process.cwd(), pathArg)
+      if (existsSync(abs) && statSync(abs).isDirectory()) root = abs
+      else if (abs.endsWith(".scene.ts") && existsSync(abs)) root = findAppRoot(dirname(abs)) ?? dirname(abs)
+      else throw new CliError(`No such folder or .scene.ts: ${pathArg}`)
+    } else {
+      root = findAppRoot(root) ?? root
+    }
+  }
+  return { root, manifest, name: manifest?.name ?? basename(root) }
+}
+
+/** Register the scene server as a project-scoped MCP server so Claude Code auto-discovers its
+ *  scene_state / check_scene tools. Merges into an existing .mcp.json (never clobbers a broken one).
+ *  Ported from `lecodes design init`'s writer; keyed "lecodes-scene". */
+const writeMcpConfig = (root: string, port: number) => {
+  const path = join(root, ".mcp.json")
+  const entry = { type: "http", url: `http://localhost:${port}/mcp` }
+  let config: { mcpServers?: Record<string, unknown> } = {}
+  if (existsSync(path)) {
+    try {
+      config = JSON.parse(readFileSync(path, "utf8"))
+    } catch {
+      warnErr(".mcp.json exists but isn't valid JSON — left it untouched. Add the lecodes-scene server by hand.")
+      return
+    }
+  }
+  config.mcpServers ??= {}
+  const existing = config.mcpServers["lecodes-scene"] as { url?: string } | undefined
+  if (existing?.url === entry.url) { note("kept      .mcp.json (lecodes-scene MCP server)"); return }
+  config.mcpServers["lecodes-scene"] = entry
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n")
+  note(`${existing ? "updated" : "created"}   .mcp.json (lecodes-scene MCP → ${entry.url})`)
+}
+
+/** Recursively find the first-level count of `.scene.ts` files under root (skip node_modules/dotdirs). */
+const countScenes = (dir: string): number => {
+  let n = 0
+  for (const name of readdirSync(dir)) {
+    if (name === "node_modules" || name.startsWith(".")) continue
+    const full = join(dir, name)
+    if (statSync(full).isDirectory()) n += countScenes(full)
+    else if (name.endsWith(".scene.ts")) n++
+  }
+  return n
+}
+
+export const scene = async (args: Args) => {
+  const ctx = getContext(args)
+
+  let sceneServer: typeof import("lecodes-3d-editor/server")
+  try {
+    sceneServer = await import("lecodes-3d-editor/server")
+  } catch {
+    throw new CliError("The scene editor isn't installed. Run:  npm install -g lecodes-3d-editor")
+  }
+
+  const port = Number(flagStr(args, "port")) || DEFAULT_PORT
+
+  if (countScenes(ctx.root) === 0) {
+    warnErr(`No .scene.ts file under ${ctx.root} yet — add one and the editor will pick it up.`)
+  }
+
+  const server = await sceneServer.startSceneServer({
+    root: ctx.root,
+    port,
+    log: note,
+    compile: (scenePath: string) => compileSceneEditor({
+      root: ctx.root, manifest: ctx.manifest, name: ctx.name, scenePath,
+    }),
+    // live material patches load a shader's compiled artifact (matc'd for the Rendered mode,
+    // the lite JSON otherwise) from the local shader cache
+    shaderArtifact: (shaderText, platform) => localShaderArtifact(ctx.root, shaderText, platform),
+  })
+
+  // Let Claude Code reach the running server over MCP (scene_state / check_scene), unless opted out.
+  if (!flagBool(args, "no-mcp")) writeMcpConfig(ctx.root, port)
+
+  log(`${c.bold("LeCodes Scene Editor")} — ${ctx.name}`)
+  log(`Editor:   ${c.bold(server.url)}`)
+  log(`MCP:      ${c.bold(server.url + "/mcp")}`)
+  log(`Watching: ${ctx.root}  (scenes hot-reload on save; Ctrl+C to stop)`)
+  if (!flagBool(args, "no-open")) openBrowser(server.url)
+}