lecodes-cli 0.19.0 → 0.20.0

package/src/desktopRenderer.ts

@@ -0,0 +1,545 @@
+import { execFileSync, spawn, spawnSync } from "node:child_process"
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { homedir, tmpdir } from "node:os"
+import { delimiter, join, resolve } from "node:path"
+import { cachedArtifactSha, downloadReleaseArchive, fetchReleaseProduct, semverNewer, type ManifestVersion } from "./releases"
+import { CliError, note, warnErr } from "./util"
+import { makeStackDemangler } from "./compile/nativeStack"
+
+/*
+ * The NATIVE renderer behind `lecodes render --desktop`: the LeCodes Desktop host (tgfx UI + Filament
+ * 3D + creator-2d, composited) run headless — CREATOR_HIDDEN + CREATOR_WINDOW_SIZE +
+ * CREATOR_MAX_FRAMES + CREATOR_DUMP_PNG (the host dumps only the final frame of a bounded run).
+ *
+ * The binary is NOT shipped with the CLI (it's ~23 MB per platform and most users never render
+ * natively). It downloads on first use from the same S3 release bucket the desktop distribution
+ * publishes to (scripts/release/* → releases/versions.json), sha256-verified, into
+ * ~/.lecodes/renderer/desktop-<version>/. LECODES_DESKTOP_EXE overrides resolution entirely
+ * (local dev: point it at packages/desktop/build/lecodes-desktop.exe).
+ *
+ * Platforms: windows-x64 + linux (the ubuntu build) + macos-arm64. The macOS host is built and
+ * published separately (the Apple repo's LeCodes Desktop.app, via scripts/release/release-macos.sh)
+ * as a notarized DMG under the same "desktop" product — so its version line has gaps: a release
+ * may ship for Windows only. On darwin the cache therefore holds the newest published version
+ * that HAS a macOS artifact (never below the pin), and an app installed in /Applications is only
+ * the fallback for when the manifest can't be reached. The headless render contract
+ * (CREATOR_HIDDEN & co) is still Windows/Linux-only — the macOS host has no hidden mode.
+ */
+
+/** The MINIMUM desktop version this CLI drives. The headless-render envs (CREATOR_HIDDEN,
+ *  CREATOR_WINDOW_SIZE, final-frame-only CREATOR_DUMP_PNG) shipped in 1.1.0 — an older host would
+ *  ignore the size, flash a window and dump every frame, so we require the pin rather than degrade.
+ *  Bump together with desktop releases that change the render contract. `lecodes desktop update`
+ *  can move FORWARD past it (selection saved in ~/.lecodes/renderer/current.json); it never goes below. */
+export const DESKTOP_RENDERER_VERSION = "1.1.0"
+
+// The manifest fetch + sha256-verified archive download live in releases.ts (shared with the
+// matc tool). semverNewer is re-exported for the existing importers (commands/desktop.ts).
+export { semverNewer }
+
+/** Which desktop host to run. "gl" is the default everywhere; "vulkan" is a separate Windows binary
+ *  (Filament + tgfx on one VkDevice), NOT a runtime switch — it has its own artifact, its own
+ *  shaders, and a smaller feature set (no 2D engine, no native-view plugins). Chosen per project via
+ *  app.json `desktop.renderer`, or per run via `--renderer` / LECODES_DESKTOP_RENDERER. */
+export type DesktopRenderer = "gl" | "vulkan"
+
+export const DESKTOP_RENDERER_MIN_VERSION: Record<DesktopRenderer, string> = { gl: "0.0.0", vulkan: "1.4.0" }
+
+const platformKey = (renderer: DesktopRenderer = "gl"): string => {
+  if (process.platform === "win32") return renderer === "vulkan" ? "windows-x64-vulkan" : "windows-x64"
+  if (renderer === "vulkan") {
+    throw new CliError(`The Vulkan desktop host is Windows-only (this is ${process.platform}). Use the default renderer.`)
+  }
+  if (process.platform === "linux") return "ubuntu-linux-x64"
+  if (process.platform === "darwin") return process.arch === "arm64" ? "macos-arm64" : "macos-x64"
+  throw new CliError(`The LeCodes Desktop host isn't available on ${process.platform}.`)
+}
+
+const isMac = () => process.platform === "darwin"
+
+/** The host binary's file name. macOS: the executable inside LeCodes Desktop.app. */
+const exeName = () => (process.platform === "win32" ? "lecodes-desktop.exe" : isMac() ? "lecodes-app" : "lecodes-desktop")
+
+/** Recursively locate the host binary inside an extracted archive (the zip nests a
+ *  `lecodes-desktop/` top-level folder; the tarballs may differ — search, don't assume). */
+const findExe = (dir: string): string | null => {
+  const name = exeName()
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name)
+    if (entry.isFile() && entry.name === name) return p
+    if (entry.isDirectory()) { const found = findExe(p); if (found) return found }
+  }
+  return null
+}
+
+const cacheRoot = () => join(homedir(), ".lecodes", "renderer")
+const currentFile = () => join(cacheRoot(), "current.json")
+
+/** Versions with a working host binary in the cache, newest first. */
+export const installedDesktopVersions = (): string[] => {
+  try {
+    return readdirSync(cacheRoot(), { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name.startsWith("desktop-"))
+      .map((e) => e.name.slice("desktop-".length))
+      .filter((v) => findExe(join(cacheRoot(), `desktop-${v}`)) !== null)
+      .sort(semverNewer)
+  } catch {
+    return []
+  }
+}
+
+/** The version `--desktop` renders with: the `lecodes desktop update` selection when it's ahead of
+ *  the CLI's pin, the pin otherwise (a CLI upgrade that raises the contract wins over a stale save). */
+export const selectedDesktopVersion = (): string => {
+  try {
+    const saved = (JSON.parse(readFileSync(currentFile(), "utf8")) as { version?: string }).version
+    if (saved && /^\d+\.\d+\.\d+/.test(saved) && semverNewer(DESKTOP_RENDERER_VERSION, saved) > 0) return saved
+  } catch { /* no saved selection */ }
+  return DESKTOP_RENDERER_VERSION
+}
+
+/** The desktop product from the release manifest (always fetched fresh — see releases.ts). */
+export const fetchDesktopManifest = (): Promise<{ latest: string, versions: ManifestVersion[] }> =>
+  fetchReleaseProduct("desktop", "desktop")
+
+/** The version a Mac actually gets for a wanted one: the same version when it has a macOS
+ *  artifact, else the newest published one that does (never below the CLI's pin — the render
+ *  contract) — null when nothing qualifies. Pure; see the platform note in the header. */
+export const pickMacVersion = (versions: ManifestVersion[], wanted: string, key = "macos-arm64"): string | null => {
+  if (versions.find((v) => v.version === wanted)?.files[key]) return wanted
+  const eligible = versions
+    .filter((v) => v.files[key] && semverNewer(DESKTOP_RENDERER_VERSION, v.version) >= 0)
+    .map((v) => v.version)
+    .sort(semverNewer)
+  return eligible[0] ?? null
+}
+
+/** Unpack a DMG: mount read-only, copy the .app out, unmount — the copy is a plain folder in the
+ *  cache with no quarantine flag (it never went through a browser), like every other host. */
+const extractDmg = (archive: string, stage: string) => {
+  const mount = join(stage, "mnt")
+  mkdirSync(mount, { recursive: true })
+  execFileSync("hdiutil", ["attach", "-nobrowse", "-readonly", "-quiet", "-mountpoint", mount, archive])
+  try {
+    const app = readdirSync(mount).find((n) => n.endsWith(".app"))
+    if (!app) throw new CliError("The downloaded DMG holds no .app bundle.")
+    execFileSync("cp", ["-R", join(mount, app), join(stage, app)])
+  } finally {
+    spawnSync("hdiutil", ["detach", "-quiet", "-force", mount])
+    rmSync(mount, { recursive: true, force: true })
+  }
+}
+
+const downloadDesktop = async (version: string, dest: string, renderer: DesktopRenderer = "gl"): Promise<void> => {
+  const key = platformKey(renderer)
+  const entry = (await fetchDesktopManifest()).versions.find((v) => v.version === version)
+  const file = entry?.files[key]
+  if (!file) {
+    // Never silently fall back to the GL host: a project asking for Vulkan and quietly getting
+    // OpenGL makes "why is it slow / why does the shader look wrong" unanswerable.
+    if (renderer === "vulkan") {
+      throw new CliError(
+        `The Vulkan desktop host isn't published for LeCodes Desktop ${version} [${key}].\n` +
+        `  Vulkan needs desktop >= ${DESKTOP_RENDERER_MIN_VERSION.vulkan}; run \`lecodes desktop update\`, ` +
+        `set LECODES_DESKTOP_EXE to a locally built host, or drop desktop.renderer from app.json.`,
+      )
+    }
+    throw new CliError(
+      `LeCodes Desktop ${version} [${key}] isn't published yet — \`--desktop\` needs it for the ` +
+      `headless render contract.\nSet LECODES_DESKTOP_EXE to a locally built host, or update lecodes-cli.`,
+    )
+  }
+
+  note(`Downloading LeCodes Desktop ${version} [${key}] (${(file.size / 1024 / 1024).toFixed(1)} MB)…`)
+  await downloadReleaseArchive(file, {
+    cacheRoot: cacheRoot(),
+    dest,
+    validate: (dir) => (findExe(dir) ? null : "The downloaded archive doesn't contain the desktop host binary."),
+    extract: file.url.toLowerCase().endsWith(".dmg") ? extractDmg : undefined,
+  })
+}
+
+/** A macOS host installed by hand (/Applications or ~/Applications) — the OFFLINE fallback when
+ *  nothing is cached and the manifest can't be fetched; the cache is preferred because its
+ *  version is known and chosen by the CLI, an installed app is whatever the user last dragged in. */
+export const findMacHostExe = (): string | null => {
+  const candidates = [
+    ...["/Applications", join(homedir(), "Applications")]
+      .flatMap((root) => ["LeCodes Desktop.app", "LeCodes.app"].map((app) => join(root, app))),
+  ].map((app) => join(app, "Contents", "MacOS", "lecodes-app"))
+  return candidates.find((exe) => existsSync(exe)) ?? null
+}
+
+/** macOS: the cached host for the selected version, else the newest published version with a
+ *  macOS artifact (downloaded + remembered as the selection, so later runs are offline-stable),
+ *  else the installed app. */
+const resolveMacExe = async (selected: string): Promise<string> => {
+  const cached = findExe(join(cacheRoot(), `desktop-${selected}`))
+  if (cached) return cached
+  try {
+    const { versions } = await fetchDesktopManifest()
+    const version = pickMacVersion(versions, selected, platformKey())
+    if (!version) {
+      throw new CliError(`No LeCodes Desktop release for ${platformKey()} is published at or above ${DESKTOP_RENDERER_VERSION}.`)
+    }
+    const dir = join(cacheRoot(), `desktop-${version}`)
+    let exe = findExe(dir)
+    if (!exe) {
+      await downloadDesktop(version, dir)
+      exe = findExe(dir)
+      if (!exe) throw new CliError(`Renderer cache at ${dir} is broken — delete the folder and retry.`)
+    }
+    if (version !== selected) {
+      note(`LeCodes Desktop ${selected} has no macOS build — using ${version}.`)
+      mkdirSync(cacheRoot(), { recursive: true })
+      writeFileSync(currentFile(), JSON.stringify({ version }, null, 2))
+    }
+    return exe
+  } catch (e) {
+    const installed = findMacHostExe()
+    if (installed) {
+      warnErr(`${e instanceof Error ? e.message : String(e)}\n  Falling back to the installed host: ${installed}`)
+      return installed
+    }
+    throw new CliError(
+      `${e instanceof Error ? e.message : String(e)}\n` +
+      "  No LeCodes Desktop.app is installed either — retry online (`lecodes desktop update`), install the DMG into\n" +
+      "  /Applications, or point LECODES_DESKTOP_EXE at a build (…/LeCodes Desktop.app/Contents/MacOS/lecodes-app).",
+    )
+  }
+}
+
+/** The desktop host binary: LECODES_DESKTOP_EXE override → the selected version's cache → download.
+ *  The two renderers cache side by side (`desktop-<version>` / `desktop-<version>-vulkan`) so
+ *  switching costs nothing after the first download. LECODES_DESKTOP_EXE wins over the renderer —
+ *  it names an exact binary, and which backend that binary uses is its own business. */
+export const resolveDesktopExe = async (renderer: DesktopRenderer = "gl"): Promise<string> => {
+  const override = process.env.LECODES_DESKTOP_EXE
+  if (override) {
+    if (!existsSync(override)) throw new CliError(`LECODES_DESKTOP_EXE points at "${override}" which doesn't exist.`)
+    return resolve(override)
+  }
+  if (renderer === "vulkan") platformKey(renderer)   // fail early + clearly on a non-Windows machine
+  const version = selectedDesktopVersion()
+  // macOS: the same cache, fed from the DMG the Apple repo publishes; the version may differ from
+  // the selection (gaps in the macOS line) and an installed app is the offline fallback.
+  if (isMac()) return resolveMacExe(version)
+  const dir = join(cacheRoot(), `desktop-${version}${renderer === "vulkan" ? "-vulkan" : ""}`)
+  let exe = existsSync(dir) ? findExe(dir) : null
+  if (!exe) {
+    await downloadDesktop(version, dir, renderer)
+    exe = findExe(dir)
+    if (!exe) throw new CliError(`Renderer cache at ${dir} is broken — delete the folder and retry.`)
+  }
+  return exe
+}
+
+/** `lecodes desktop update`: move the render host to the newest published release (never below the
+ *  CLI's pin — a manifest that somehow regressed under it is an error, not a downgrade). Saves the
+ *  selection so later `render --desktop` runs use it; the download is skipped when already cached. */
+export const updateDesktop = async (): Promise<void> => {
+  const manifest = await fetchDesktopManifest()
+  // macOS: "latest" is the latest WITH a macOS artifact — a Windows-only release isn't an update here.
+  const latest = isMac() ? pickMacVersion(manifest.versions, manifest.latest, platformKey()) : manifest.latest
+  if (!latest) throw new CliError(`No LeCodes Desktop release for ${platformKey()} is published at or above ${DESKTOP_RENDERER_VERSION}.`)
+  if (semverNewer(latest, DESKTOP_RENDERER_VERSION) > 0) {
+    throw new CliError(
+      `The newest published LeCodes Desktop is ${latest}, but this CLI needs ≥ ${DESKTOP_RENDERER_VERSION} ` +
+      `for the render contract. Publish the desktop release first.`,
+    )
+  }
+  const before = selectedDesktopVersion()
+  const dir = join(cacheRoot(), `desktop-${latest}`)
+  // "Up to date" means the cache holds the artifact the manifest CURRENTLY names, not merely a dir
+  // with the right version in its name: a release can be republished under the same number (the
+  // macOS host was, as 1.3.2), and a stale cache then silently outlives it. Comparing the recorded
+  // sha256 catches that; a dir with no stamp predates the check, so its contents are unknown and it
+  // is replaced too. Only `update` pays for this — it already has the manifest in hand.
+  const published = (await fetchDesktopManifest()).versions.find((v) => v.version === latest)?.files[platformKey()]
+  const cached = existsSync(dir) && findExe(dir) !== null
+  const republished = cached && published !== undefined && cachedArtifactSha(dir) !== published.sha256
+  if (republished) {
+    note(`LeCodes Desktop ${latest} was republished since this machine cached it — downloading the current build.`)
+    rmSync(dir, { recursive: true, force: true })
+  }
+  const hadIt = cached && !republished
+  if (!hadIt) await downloadDesktop(latest, dir)
+  mkdirSync(cacheRoot(), { recursive: true })
+  writeFileSync(currentFile(), JSON.stringify({ version: latest }, null, 2))
+  if (latest === before && hadIt) note(`Already up to date: LeCodes Desktop ${latest}.`)
+  else if (latest === before) note(`Re-downloaded LeCodes Desktop ${latest}.`)
+  else note(`Desktop renderer set to ${latest} (was ${before}).`)
+}
+
+/** Window config forwarded to the host as CREATOR_* envs (unknown envs are ignored by older
+ *  hosts, so none of these bump the version pin — they just don't apply there). Sizes are
+ *  LOGICAL units; the host multiplies by the display scale. */
+export type DesktopWindowOpts = {
+  /** Which host binary to run (see DesktopRenderer). Must match the renderer the bundle's shaders
+   *  were staged for — resolve it once per command and pass the same value to both. */
+  renderer?: DesktopRenderer
+  width?: number
+  height?: number
+  minWidth?: number
+  minHeight?: number
+  resizable?: boolean
+  title?: string
+  /** Borderless fullscreen on the primary monitor (host ≥1.3.0; older hosts ignore the env). */
+  fullscreen?: boolean
+  /** Display scale: a fixed density (0.5–4) or "fit" (derive from design frame vs monitor/work
+   *  area; host ≥1.3.0 — a 1.2.0 host warns and ignores "fit"). */
+  scale?: number | "fit"
+  /** 3D buffer scale vs the window, 0.25–1 (host ≥1.4.0); the UI stays at native pixels. */
+  renderScale?: number
+  /** 3D buffer cap [W, H] in px (host ≥1.4.0) — e.g. [1920, 1080] keeps a 4K fullscreen at 1080p 3D. */
+  maxRenderSize?: [number, number]
+  /** Draw the host's frame counter in the corner (host ≥1.5.0; older hosts ignore the env). Costs
+   *  nothing to leave off and next to nothing on — the digits are rectangles, no UI behind them. */
+  fps?: boolean
+  /** Multiplayer launch facts for the host (`--server --port N --max-clients N` / `--connect ip:port`);
+   *  the SDK reads them through `Net.launch` and decides (docs/multiplayer-plan.md). */
+  net?: { role: "server" | "client"; address?: string; port?: number; maxClients?: number }
+  /** Dirs the host scans for native plugin libraries (CREATOR_PLUGIN_DIRS; the loader was added
+   *  after host 1.4.0 — an older host ignores the env). See appShared.desktopPluginLibraries. */
+  pluginDirs?: string[]
+}
+
+/** CREATOR_PLUGIN_DIRS: the project's plugin dirs first, then whatever the environment already
+ *  carried (a `.env` CREATOR_PLUGIN_DIRS keeps working alongside the project's `plugins/`). */
+const pluginEnv = (dirs: string[] | undefined): Record<string, string> => {
+  const all = [...(dirs ?? []), ...(process.env.CREATOR_PLUGIN_DIRS ? [process.env.CREATOR_PLUGIN_DIRS] : [])]
+  return all.length > 0 ? { CREATOR_PLUGIN_DIRS: all.join(delimiter) } : {}
+}
+
+const windowEnv = (opts: DesktopWindowOpts): Record<string, string> => {
+  const env: Record<string, string> = { ...pluginEnv(opts.pluginDirs) }
+  // A lone width/height fills the other side from the host default so it isn't silently ignored.
+  const width = opts.width ?? (opts.height !== undefined ? 1280 : undefined)
+  const height = opts.height ?? (opts.width !== undefined ? 720 : undefined)
+  if (width && height) env.CREATOR_WINDOW_SIZE = `${width}x${height}`
+  if (opts.minWidth && opts.minHeight) env.CREATOR_MIN_WINDOW_SIZE = `${opts.minWidth}x${opts.minHeight}`
+  if (opts.title) env.CREATOR_WINDOW_TITLE = opts.title
+  if (opts.resizable === false) env.CREATOR_WINDOW_FIXED = "1"
+  if (opts.fullscreen !== undefined) env.CREATOR_WINDOW_FULLSCREEN = opts.fullscreen ? "1" : "0"
+  if (opts.scale === "fit") env.CREATOR_UI_SCALE = "fit"
+  else if (typeof opts.scale === "number") env.CREATOR_UI_SCALE = String(opts.scale)
+  if (typeof opts.renderScale === "number") env.CREATOR_RENDER_SCALE = String(opts.renderScale)
+  if (opts.maxRenderSize && opts.maxRenderSize[0] > 0 && opts.maxRenderSize[1] > 0) {
+    env.CREATOR_RENDER_MAX = `${Math.round(opts.maxRenderSize[0])}x${Math.round(opts.maxRenderSize[1])}`
+  }
+  if (opts.fps) env.CREATOR_FPS = "1"
+  return env
+}
+
+// The host's own multiplayer flags (main.cpp argv) — options, not env, so a shipped exe takes them too.
+const netArgs = (net: DesktopWindowOpts["net"]): string[] => {
+  if (!net) return []
+  const args: string[] = []
+  if (net.role === "server") args.push("--server")
+  else if (net.address) args.push("--connect", net.address)
+  if (net.port) args.push("--port", String(net.port))
+  if (net.maxClients) args.push("--max-clients", String(net.maxClients))
+  return args
+}
+
+export type DesktopRenderOptions = {
+  /** Called per output chunk; returning true ends the run early (the host is killed, the
+   *  outcome is a success with the output so far — a bake that printed its done marker). */
+  stopOnLine?: (chunk: string) => boolean
+  /** Which host binary to run (see DesktopRenderer). Must match the renderer the bundle's shaders
+   *  were staged for — resolve it once per command and pass the same value to both. */
+  renderer?: DesktopRenderer
+  width: number
+  height: number
+  /** Frames to run before the dump — headroom for async loads (GLB, images, fonts). */
+  frames: number
+  /** Absolute or cwd-relative path the PNG lands at. */
+  outPng: string
+  /** Forward the host's stdout/stderr (app console.log included) to stderr. */
+  logs: boolean
+  timeoutMs: number
+  /** CREATOR_SCRIPT contents (the line format in packages/desktop/src/main.cpp `scriptStep`): the
+   *  host drives these commands and self-terminates when done; `frames` is then only a safety cap. */
+  script?: string
+  /** CREATOR_FIXED_DT: virtual app clock, ms per frame (0/undefined = wall clock). */
+  fixedDtMs?: number
+  /** Inspection camera: CREATOR_CAMERA ("ex,ey,ez;tx,ty,tz[;fov]") or CREATOR_VIEW ("iso[;fov]"). */
+  camera?: string
+  view?: string
+  /** Dirs the host scans for native plugin libraries (CREATOR_PLUGIN_DIRS). */
+  pluginDirs?: string[]
+}
+
+export type DesktopRenderOutcome = {
+  /** Everything the host printed (stdout + stderr), for marker parsing / expect.log. */
+  output: string
+  exitCode: number | null
+}
+
+/** Stage a compiled bundle for the host: app.js + the local-asset resources copied next to it
+ *  (the host's fetchLocal resolves them by basename relative to its cwd). Caller removes the dir. */
+const stageBundle = (js: string, resources: { name: string, absPath?: string }[]): string => {
+  const runDir = mkdtempSync(join(tmpdir(), "lecodes-render-"))
+  writeFileSync(join(runDir, "app.js"), js)
+  for (const r of resources) {
+    if (r.absPath && existsSync(r.absPath) && statSync(r.absPath).isFile()) {
+      copyFileSync(r.absPath, join(runDir, r.name))
+    }
+  }
+  return runDir
+}
+
+/** Forward a child stream line-by-line through `map`. Line-buffered so a chunk boundary can never
+ *  cut a `module.js:L:C` frame in half; the trailing partial line is flushed when the stream ends. */
+const pipeThroughDemangler = (src: NodeJS.ReadableStream, dst: NodeJS.WritableStream, map: (s: string) => string) => {
+  let rest = ""
+  src.on("data", (d: Buffer | string) => {
+    rest += String(d)
+    const nl = rest.lastIndexOf("\n")
+    if (nl < 0) return
+    dst.write(map(rest.slice(0, nl + 1)))
+    rest = rest.slice(nl + 1)
+  })
+  src.on("end", () => { if (rest) dst.write(map(rest)) })
+}
+
+/** `lecodes desktop run`: open the compiled project in a normal (visible, interactive) desktop
+ *  window and stream the host's output — the plain-run counterpart of `lecodes dev`, no reload.
+ *  Resolves until the window is closed. Ambient CREATOR_* envs pass through (handy for testing). */
+export const runDesktopApp = async (
+  js: string,
+  resources: { name: string, absPath?: string }[],
+  opts: DesktopWindowOpts = {},
+): Promise<void> => {
+  const exe = await resolveDesktopExe(opts.renderer)
+  const runDir = stageBundle(js, resources)
+  try {
+    const env = { ...process.env, ...windowEnv(opts) }
+    const demangle = makeStackDemangler(js)
+    const argv = [join(runDir, "app.js"), ...netArgs(opts.net)]
+    await new Promise<void>((done, fail) => {
+      // Piped (not inherited) only when there's a map to apply — the host's frames name the minified
+      // bundle (`module.js:5:51631`) and we rewrite them to project positions on the way through.
+      const child = demangle
+        ? spawn(exe, argv, { cwd: runDir, env, stdio: ["ignore", "pipe", "pipe"] })
+        : spawn(exe, argv, { cwd: runDir, env, stdio: ["ignore", "inherit", "inherit"] })
+      if (demangle) {
+        pipeThroughDemangler(child.stdout!, process.stdout, demangle)
+        pipeThroughDemangler(child.stderr!, process.stderr, demangle)
+      }
+      child.on("error", (e) => fail(new CliError(`Can't run the desktop host: ${e.message}`)))
+      child.on("exit", (code) => {
+        if (code === 0 || code === null) done()   // null: killed (e.g. Ctrl+C reached the child)
+        else fail(new CliError(`The desktop host exited with code ${code}.`))
+      })
+    })
+  } finally {
+    // A host that was just killed (timeout / stopOnLine) can still hold the staging dir for a moment;
+    // an EPERM here must not replace the real error with "Permission denied" (seen on a 10-minute
+    // lightmap timeout, read as a crash for two hours). Retry briefly, then leave it to the OS temp.
+    for (let attempt = 0; ; attempt++) {
+      try { rmSync(runDir, { recursive: true, force: true }); break }
+      catch {
+        if (attempt >= 5) break
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200)
+      }
+    }
+  }
+}
+
+/** `lecodes dev --desktop`: open the dev-server URL in the host — its launcher fetches the
+ *  bundle and the appended prelude hot-reloads over websocket. No staging dir: assets stream
+ *  from the dev server. Resolves when the window closes (any exit code — a dev host getting
+ *  killed mid-session is not an error); the caller's dev server keeps running. stdout is
+ *  dropped: the prelude already mirrors app console output to the dev terminal. */
+export const runDesktopDev = async (url: string, opts: DesktopWindowOpts = {}): Promise<void> => {
+  const exe = await resolveDesktopExe(opts.renderer)
+  const env = { ...process.env, ...windowEnv(opts) }
+  await new Promise<void>((done, fail) => {
+    const child = spawn(exe, [url], { env, stdio: ["ignore", "ignore", "inherit"] })
+    child.on("error", (e) => fail(new CliError(`Can't run the desktop host: ${e.message}`)))
+    child.on("exit", () => done())
+  })
+}
+
+/** Run a compiled bundle in the hidden desktop host and dump the final frame as a PNG. */
+export const runDesktopRender = async (
+  js: string,
+  resources: { name: string, absPath?: string }[],
+  opts: DesktopRenderOptions,
+): Promise<DesktopRenderOutcome> => {
+  if (isMac()) {
+    throw new CliError(
+      "`lecodes render --desktop` isn't available on macOS yet — the macOS host has no headless mode " +
+      "(CREATOR_HIDDEN / CREATOR_DUMP_PNG). `lecodes desktop run` and `lecodes desktop build` do work there.",
+    )
+  }
+  const exe = await resolveDesktopExe(opts.renderer)
+  const runDir = stageBundle(js, resources)
+  try {
+    const appJs = join(runDir, "app.js")
+    const outAbs = resolve(opts.outPng)
+    const env: Record<string, string | undefined> = {
+      ...process.env,
+      CREATOR_DUMP_PNG: outAbs,
+      CREATOR_MAX_FRAMES: String(opts.frames),
+      CREATOR_WINDOW_SIZE: `${opts.width}x${opts.height}`,
+      CREATOR_HIDDEN: "1",
+    }
+    if (opts.script !== undefined) {
+      const scriptPath = join(runDir, "script.txt")
+      writeFileSync(scriptPath, opts.script)
+      env.CREATOR_SCRIPT = scriptPath
+    }
+    if (opts.fixedDtMs) env.CREATOR_FIXED_DT = String(opts.fixedDtMs)
+    if (opts.camera) env.CREATOR_CAMERA = opts.camera
+    if (opts.view) env.CREATOR_VIEW = opts.view
+    Object.assign(env, pluginEnv(opts.pluginDirs))
+    // Frames the host prints name the minified bundle (`module.js:5:51631`); map them back to
+    // project positions. Chunks stay raw so `[script]` marker parsing sees exactly what was sent —
+    // the rewrite happens on the joined text (and best-effort per chunk for live --logs).
+    const demangle = makeStackDemangler(js) ?? ((text: string) => text)
+    return await new Promise<DesktopRenderOutcome>((done, fail) => {
+      const child = spawn(exe, [appJs], { cwd: runDir, env, stdio: ["ignore", "pipe", "pipe"] })
+      // Keep the whole output (scripted runs parse its `[script]` markers + console lines); forward
+      // live only with --logs. The error tail is the last 80 chunks.
+      const chunks: string[] = []
+      let stopped = false
+      const sink = (d: unknown) => {
+        const text = String(d)
+        chunks.push(text)
+        if (opts.logs) process.stderr.write(demangle(text))
+        if (!stopped && opts.stopOnLine?.(text)) { stopped = true; child.kill() }
+      }
+      child.stdout.on("data", sink)
+      child.stderr.on("data", sink)
+      const killer = setTimeout(() => {
+        child.kill()
+        fail(new CliError(`The native render timed out after ${opts.timeoutMs}ms (raise --timeout, or lower --frames).`))
+      }, opts.timeoutMs)
+      child.on("error", (e) => { clearTimeout(killer); fail(new CliError(`Can't run the desktop renderer: ${e.message}`)) })
+      child.on("exit", (code) => {
+        clearTimeout(killer)
+        const output = demangle(chunks.join(""))
+        if (stopped) return done({ output, exitCode: 0 })
+        if (code === 0 && existsSync(outAbs)) return done({ output, exitCode: code })
+        const tail = demangle(chunks.slice(-80).join("")).trimEnd()
+        const detail = tail.length > 0 ? `\n${tail}` : ""
+        fail(new CliError(code === 0
+          ? `The renderer exited cleanly but produced no PNG — did the app open a screen?${detail}`
+          : `The renderer exited with code ${code}.${detail}`))
+      })
+    })
+  } finally {
+    // A host that was just killed (timeout / stopOnLine) can still hold the staging dir for a moment;
+    // an EPERM here must not replace the real error with "Permission denied" (seen on a 10-minute
+    // lightmap timeout, read as a crash for two hours). Retry briefly, then leave it to the OS temp.
+    for (let attempt = 0; ; attempt++) {
+      try { rmSync(runDir, { recursive: true, force: true }); break }
+      catch {
+        if (attempt >= 5) break
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200)
+      }
+    }
+  }
+}