lecodes-cli 1.0.0 → 2.0.0

package/src/hosts/desktopRenderer.ts

@@ -1,5 +1,5 @@
 import { execFileSync, spawn, spawnSync } from "node:child_process"
-import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, linkSync } 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"
@@ -15,7 +15,7 @@ import { makeStackDemangler } from "../compile/nativeStack"
  * 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).
+ * (local dev: point it at hosts/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)
@@ -58,8 +58,9 @@ const platformKey = (renderer: DesktopRenderer = "gl"): string => {
 
 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")
+/** The host binary's file name — the same on every OS; on macOS it sits inside LeCodes Desktop.app
+ *  (Contents/MacOS/lecodes-desktop, hosts/desktop/package-macos.sh). */
+const exeName = () => (process.platform === "win32" ? "lecodes-desktop.exe" : "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). */
@@ -167,7 +168,7 @@ 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"))
+  ].map((app) => join(app, "Contents", "MacOS", "lecodes-desktop"))
   return candidates.find((exe) => existsSync(exe)) ?? null
 }
 
@@ -205,7 +206,7 @@ const resolveMacExe = async (selected: string): Promise<string> => {
     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).",
+      "  /Applications, or point LECODES_DESKTOP_EXE at a build (hosts/desktop/build-macos/lecodes-desktop, or an .app's Contents/MacOS/lecodes-desktop).",
     )
   }
 }
@@ -235,6 +236,38 @@ export const resolveDesktopExe = async (renderer: DesktopRenderer = "gl"): Promi
   return exe
 }
 
+/** Which native host runs a bundle: the desktop (a window, a GPU, pixels) or the windowless server
+ *  (hosts/desktop lecodes-server: the same engine on Filament's NOOP backend — the dedicated
+ *  multiplayer server, a headless client, an offline simulation run; no UI hit-test, no pixels). */
+export type HostKind = "desktop" | "server"
+
+const serverExeName = () => (process.platform === "win32" ? "lecodes-server.exe" : "lecodes-server")
+
+/** The windowless host: LECODES_SERVER_EXE override → the binary beside the resolved desktop host
+ *  (one product, two executables — a release archive and a repo build both keep them side by side,
+ *  sharing runtime/). A host older than the server's introduction has none beside it. */
+export const resolveServerExe = async (renderer: DesktopRenderer = "gl"): Promise<string> => {
+  const override = process.env.LECODES_SERVER_EXE
+  if (override) {
+    if (!existsSync(override)) throw new CliError(`LECODES_SERVER_EXE points at "${override}" which doesn't exist.`)
+    return resolve(override)
+  }
+  // macOS: the server ships inside the .app beside the window host (Contents/MacOS/) since the
+  // in-repo Metal host (hosts/desktop/build-macos.sh); the "beside the desktop exe" rule holds.
+  const desktopExe = await resolveDesktopExe(renderer)
+  const exe = join(desktopExe, "..", serverExeName())
+  if (!existsSync(exe)) {
+    throw new CliError(
+      `No ${serverExeName()} beside ${desktopExe} — this desktop host predates the windowless server. ` +
+      "Update it (lecodes desktop update), or point LECODES_SERVER_EXE at a build (hosts/desktop/build[-linux|-macos]/lecodes-server).",
+    )
+  }
+  return exe
+}
+
+const resolveHostExe = (host: HostKind | undefined, renderer: DesktopRenderer | undefined): Promise<string> =>
+  host === "server" ? resolveServerExe(renderer) : resolveDesktopExe(renderer)
+
 /** `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. */
@@ -279,6 +312,8 @@ 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
+  /** The desktop window (default) or the windowless server host (see HostKind). */
+  host?: HostKind
   width?: number
   height?: number
   minWidth?: number
@@ -305,8 +340,16 @@ export type DesktopWindowOpts = {
    *  the block, forwarded verbatim as CREATOR_VIRTUAL_KEYBOARD JSON. A set env wins, like the mouse knob. */
   virtualKeyboard?: boolean | object
   /** 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. */
+   *  nothing to leave off and next to nothing on — the digits are rectangles, no UI behind them.
+   *  On macOS too (host 2026-09-09; the CLI sets the same env there). */
   fps?: boolean
+  /** The host's profiler (CREATOR_PERF=1, host 2026-09-26): a `[perf]` line a second — GPU frame time from
+   *  Filament's timer query, the CPU split, visible / total renderables, the view's switches — and the
+   *  fps overlay's second row. docs/profiling.md in the core repo. */
+  perf?: boolean
+  /** app.json desktop.frameRate — a CAP on the host's render loop, "display" or a number; forwarded
+   *  verbatim as CREATOR_FRAME_RATE (a set env wins). macOS host 2026-09-09; Windows ignores it. */
+  frameRate?: number | "display"
   /** 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 }
@@ -340,6 +383,10 @@ const windowEnv = (opts: DesktopWindowOpts): Record<string, string> => {
     env.CREATOR_RENDER_MAX = `${Math.round(opts.maxRenderSize[0])}x${Math.round(opts.maxRenderSize[1])}`
   }
   if (opts.fps) env.CREATOR_FPS = "1"
+  if (opts.perf) env.CREATOR_PERF = "1"
+  if (opts.frameRate !== undefined && process.env.CREATOR_FRAME_RATE === undefined) {
+    env.CREATOR_FRAME_RATE = String(opts.frameRate)
+  }
   if (opts.mouseEmulateTouch !== undefined && process.env.CREATOR_MOUSE_TOUCH === undefined) {
     env.CREATOR_MOUSE_TOUCH = opts.mouseEmulateTouch ? "1" : "0"
   }
@@ -367,6 +414,9 @@ export type DesktopRenderOptions = {
   /** 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
+  /** The hidden desktop host (default: pixels, a PNG) or the windowless server host (no pixels — the
+   *  run is judged by its output alone; `outPng` is ignored). */
+  host?: HostKind
   width: number
   height: number
   /** Frames to run before the dump — headroom for async loads (GLB, images, fonts). */
@@ -376,7 +426,7 @@ export type DesktopRenderOptions = {
   /** 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
+  /** CREATOR_SCRIPT contents (the line format in hosts/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). */
@@ -396,13 +446,29 @@ export type DesktopRenderOutcome = {
 
 /** 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. */
+/** The staging dir the host runs from: app.js + every resource the bundle names, next to it (fetchLocal's
+ *  fallback). A resource is HARD-LINKED when the temp dir shares the project's volume (the usual case:
+ *  both on C:) and copied otherwise — a yard-sized project names hundreds of MB of models and textures,
+ *  and copying them was seconds of "the window has not opened yet" on every run. The host only reads
+ *  them, and the dir is removed after the run, so a link is as safe as a copy. */
 const stageBundle = (js: string, resources: { name: string, absPath?: string }[]): string => {
+  const t0 = performance.now()
   const runDir = mkdtempSync(join(tmpdir(), "lecodes-render-"))
   writeFileSync(join(runDir, "app.js"), js)
+  let files = 0, bytes = 0, copied = 0
   for (const r of resources) {
-    if (r.absPath && existsSync(r.absPath) && statSync(r.absPath).isFile()) {
-      copyFileSync(r.absPath, join(runDir, r.name))
-    }
+    if (!r.absPath || !existsSync(r.absPath)) continue
+    const st = statSync(r.absPath)
+    if (!st.isFile()) continue
+    const dst = join(runDir, r.name)
+    try { linkSync(r.absPath, dst) }
+    catch { copyFileSync(r.absPath, dst); copied++ }
+    files++
+    bytes += st.size
+  }
+  const ms = performance.now() - t0
+  if (files > 0 && (ms > 250 || copied > 0)) {
+    note(`Staged ${files} resources (${(bytes / 1048576).toFixed(0)} MB${copied > 0 ? `, ${copied} copied` : ", linked"}) in ${(ms / 1000).toFixed(1)} s`)
   }
   return runDir
 }
@@ -429,7 +495,8 @@ export const runDesktopApp = async (
   resources: { name: string, absPath?: string }[],
   opts: DesktopWindowOpts = {},
 ): Promise<void> => {
-  const exe = await resolveDesktopExe(opts.renderer)
+  const exe = await resolveHostExe(opts.host, opts.renderer)
+  const what = opts.host === "server" ? "server" : "desktop"
   const runDir = stageBundle(js, resources)
   try {
     const env = { ...process.env, ...windowEnv(opts) }
@@ -445,10 +512,15 @@ export const runDesktopApp = async (
         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}`)))
+      // Ctrl+C in the terminal: the child gets it too on a console (Windows) or via SIGINT (POSIX),
+      // and the server host tears its endpoint down on it; make sure a detached one is not left behind.
+      const onSigint = () => { child.kill("SIGINT") }
+      process.once("SIGINT", onSigint)
+      child.on("error", (e) => { process.off("SIGINT", onSigint); fail(new CliError(`Can't run the ${what} host: ${e.message}`)) })
       child.on("exit", (code) => {
+        process.off("SIGINT", onSigint)
         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}.`))
+        else fail(new CliError(`The ${what} host exited with code ${code}.`))
       })
     })
   } finally {
@@ -480,30 +552,29 @@ export const runDesktopDev = async (url: string, opts: DesktopWindowOpts = {}):
   })
 }
 
-/** Run a compiled bundle in the hidden desktop host and dump the final frame as a PNG. */
+/** Run a compiled bundle in the hidden desktop host and dump the final frame as a PNG — or, with
+ *  `host: "server"`, in the windowless host, which paints nothing: the outcome is its output. */
 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 server = opts.host === "server"
+  // macOS: the in-repo Metal host (hosts/desktop, phase 11) carries the headless render contract like
+  // the other two platforms (CREATOR_HIDDEN / CREATOR_DUMP_PNG / CREATOR_SCRIPT); the old Swift shell
+  // did not — a cached one is refused by its missing lecodes-server, not here.
+  const exe = await resolveHostExe(opts.host, 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",
+      CREATOR_HIDDEN: "1",   // a clean storage every run (and, on the desktop host, no window)
     }
+    if (!server) env.CREATOR_DUMP_PNG = outAbs
     if (opts.script !== undefined) {
       const scriptPath = join(runDir, "script.txt")
       writeFileSync(scriptPath, opts.script)
@@ -535,17 +606,17 @@ export const runDesktopRender = async (
         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("error", (e) => { clearTimeout(killer); fail(new CliError(`Can't run the ${server ? "server" : "desktop"} host: ${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 })
+        if (code === 0 && (server || 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}`))
+          : `The ${server ? "server host" : "renderer"} exited with code ${code}.${detail}`))
       })
     })
   } finally {

package/src/hosts/desktopScript.ts

@@ -1,15 +1,24 @@
 import { resolve } from "node:path"
 import { CliError } from "../cli"
+// The evaluator lives with the headless runner (one source of truth); a relative source import,
+// since lecodes-headless is an OPTIONAL peer of the CLI and --desktop must not require it.
+import { evaluateDumpExpect, evaluatePaintExpect, parseTreeDump, type DumpSemanticExpect, type PaintExpect } from "../../../../runtime/headless/src/headless/paintDump"
 
 /*
  * `lecodes render --desktop --script`: the same JSON scenario a headless run takes, driven through
- * the NATIVE desktop host. The host has no semantic UI tree, so it can't resolve names or read text —
- * it takes a line-based command file (CREATOR_SCRIPT, see packages/desktop/src/main.cpp `scriptStep`)
- * with COORDINATES, and reports `[script] #<line> done <op>` on stdout as each command completes.
- * This module does both halves: translate the scenario into that file (refusing, with guidance, the
- * steps the host can't honour) and turn the host's stdout back into per-step results — `expect.log`
- * is evaluated here against the console lines seen up to each step's marker; the semantic expects
- * (`screen`/`node`/`text`/`value`) are reported as skipped, never silently passed.
+ * the NATIVE desktop host. The host takes a line-based command file (CREATOR_SCRIPT, the contract in
+ * hosts/desktop/src/host/script.h) and reports `[script] #<line> done <op>` on stdout as each command
+ * completes. A pointer target goes over as `X Y` (logical px) or as a quoted "name": the RUNTIME
+ * resolves it exactly as the headless session does (name → exact text → text substring, creator-pkg
+ * pkgFindNode) and the renderer places it — so a flow written by name runs on the desktop too; `fill`
+ * / `scroll` / `clip` are host commands of their own. This module does both halves: translate the
+ * scenario into that file and turn the host's stdout back into per-step results — `expect.log` is
+ * evaluated here against the console lines seen up to each step's marker; `expect.paint` and the
+ * semantic expects (`text` / `node` / `screen` / `value`) against the tree dump the host writes right
+ * after the step (the same rules as the headless session, paintDump.ts). Only `expect.audio` (the
+ * headless recorder's) and the `json` output (the headless renderer's shape) are reported as
+ * skipped, never silently passed. The windowless host (`--sim`) has no UI at all: names, hover,
+ * typing, fill, scroll and screenshots are refused there.
  */
 
 type Point = { x: number, y: number }
@@ -24,9 +33,16 @@ export type DesktopPlanStep = {
   /** Script line numbers this step emitted; the LAST one's `done` marker completes the step. */
   lines: number[]
   expectLog?: string
-  /** Expect keys the native host can't evaluate (no semantic tree) — reported as skipped. */
+  /** expect.paint and the semantic expects: the host writes the tree dump to `paintDump` (a `dump`
+   *  line) right before the step's marker; the assertions are evaluated here against that file. */
+  expectPaint?: PaintExpect
+  expectSemantic?: DumpSemanticExpect
+  paintDump?: string
+  /** A `dump` output step: the file the host wrote. */
+  dump?: string
+  /** Expect keys the native host can't evaluate (`audio`: the headless recorder's) — reported as skipped. */
   skippedExpect: string[]
-  /** Outputs the native host can't produce (`json`). */
+  /** Outputs the native host can't produce (`json`: the headless renderer's semantic shape — use `dump`). */
   skippedOutputs: string[]
   screenshot?: string
 }
@@ -39,31 +55,41 @@ export type DesktopPlan = {
   frameCap: number
 }
 
-const ACTIONS = ["tap", "type", "fill", "scroll", "wait", "frames", "drag", "hold", "key", "keyDown", "keyUp", "look", "mouseTo", "wheel", "stick", "gamepad", "camera", "view"] as const
-const SEMANTIC_EXPECT = ["text", "notText", "node", "notNode", "screen", "value", "audio"]
+const ACTIONS = ["tap", "type", "fill", "scroll", "wait", "frames", "drag", "hold", "hover", "key", "keyDown", "keyUp", "look", "mouseTo", "wheel", "stick", "gamepad", "camera", "view"] as const
+const SEMANTIC_EXPECT = ["text", "notText", "node", "notNode", "screen", "value"]
+const UNSUPPORTED_EXPECT = ["audio"]
 const VIEW_NAMES = ["iso", "top", "front", "side", "back"]
 const isVec3 = (v: unknown): v is [number, number, number] => Array.isArray(v) && v.length === 3 && v.every((n) => typeof n === "number")
 
-const pt = (p: Point) => `(${p.x},${p.y})`
+type Target = Point | string
+const pt = (p: Target) => typeof p === "string" ? p : `(${p.x},${p.y})`
+/** A target as the host's script reads it: `X Y`, or a quoted "name" (`"` and `\` escaped). */
+const wire = (p: Target) => typeof p === "string" ? `"${p.replace(/[\\"]/g, (ch) => "\\" + ch)}"` : `${p.x} ${p.y}`
+/** `type` text as the host's `type` line takes it: the rest of the line, `\n` = enter, `\\` = a backslash. */
+const wireText = (s: string) => s.replace(/\\/g, "\\\\").replace(/\r?\n/g, "\\n")
 
 /** Translate scenario steps into the host's command file. `headroomFrames` runs first so the app
- *  can load (the `--frames` value); screenshots land under `outDir`. Throws a CliError for steps the
- *  native host can't honour (named targets, typing, scrolling, clips). */
-export const translateScenario = (rawSteps: unknown, opts: { outDir: string, headroomFrames: number }): DesktopPlan => {
+ *  can load (the `--frames` value); screenshots land under `outDir`. `sim` = the windowless host
+ *  (`--sim`): it has no UI, so names, `hover`, `type`, `fill` and `scroll` are refused there, it
+ *  paints nothing, so per-step screenshots are refused too, and a tap/drag/hold reaches the SCENE's
+ *  touch input directly. */
+export const translateScenario = (rawSteps: unknown, opts: { outDir: string, headroomFrames: number, sim?: boolean }): DesktopPlan => {
   if (!Array.isArray(rawSteps)) throw new CliError(`"steps" must be an array of step objects.`)
   const lines: string[] = []
   const steps: DesktopPlanStep[] = []
   let budgetMs = 0
   const emit = (line: string): number => { lines.push(line); return lines.length }
-  emit(`# generated by lecodes render --desktop --script`)
+  emit(`# generated by lecodes render ${opts.sim ? "--sim" : "--desktop"} --script`)
   emit(`frames ${Math.max(0, opts.headroomFrames)}`)
 
-  const coord = (at: string, key: string, v: unknown): Point => {
+  const target = (at: string, key: string, v: unknown): Target => {
     if (isPoint(v)) return v
     if (typeof v === "string") {
-      throw new CliError(`${at}: "${key}": "${v}" — the native host can't resolve names; give --desktop scripts { "x", "y" } coordinates (logical px), or run the scenario headless (without --desktop).`)
+      if (v.length === 0) throw new CliError(`${at}: "${key}" is an empty name.`)
+      if (opts.sim) throw new CliError(`${at}: "${key}": "${v}" — the windowless host has no UI to resolve a name in; give --sim scripts { "x", "y" } coordinates (scene input), or run the scenario with --desktop / headless.`)
+      return v
     }
-    throw new CliError(`${at}: "${key}" must be { "x", "y" }.`)
+    throw new CliError(`${at}: "${key}" must be a name or { "x", "y" }.`)
   }
   const num = (at: string, key: string, v: unknown, def?: number): number => {
     if (v === undefined && def !== undefined) return def
@@ -84,10 +110,10 @@ export const translateScenario = (rawSteps: unknown, opts: { outDir: string, hea
     const parts: string[] = []
     const action = actions[0]
 
-    if (action === "type" || action === "fill" || action === "scroll") {
-      throw new CliError(`${at}: "${action}" isn't available with --desktop (the native host has no semantic tree / soft keyboard) — run this scenario headless, or drive the gesture with "drag" coordinates.`)
+    if ((action === "type" || action === "hover" || action === "fill" || action === "scroll") && opts.sim) {
+      throw new CliError(`${at}: "${action}" isn't available with --sim (the windowless host has no UI) — run this scenario with --desktop or headless.`)
     }
-    if ((action === "tap" || action === "drag" || action === "hold") && inspecting) {
+    if ((action === "tap" || action === "drag" || action === "hold" || action === "hover" || action === "type") && inspecting) {
       throw new CliError(`${at}: "${action}" while an inspection camera is active — the app's hit-testing uses its own camera, not the one in the shot. Add { "view": "off" } (or { "camera": "off" }) first.`)
     }
     if (action === "view") {
@@ -112,19 +138,52 @@ export const translateScenario = (rawSteps: unknown, opts: { outDir: string, hea
     }
     if (s.fov !== undefined && action !== "view") throw new CliError(`${at}: "fov" only goes with "view" (inside "camera" use camera.fov).`)
     if (action === "tap") {
-      const p = coord(at, "tap", s.tap)
-      plan.lines.push(emit(`tap ${p.x} ${p.y}`)); budgetMs += 4 * FRAME_MS
+      const p = target(at, "tap", s.tap)
+      plan.lines.push(emit(`tap ${wire(p)}`)); budgetMs += 4 * FRAME_MS
       parts.push(`tap ${pt(p)}`)
+    } else if (action === "type") {
+      // The host types into the FOCUSED input: a tap on the target focuses it, then the characters go
+      // in one by one (appended — the headless session sets the value; on an empty input they agree).
+      const p = target(at, "type", s.type)
+      if (typeof s.text !== "string") throw new CliError(`${at}: "type" needs a "text" string.`)
+      plan.lines.push(emit(`tap ${wire(p)}`))
+      plan.lines.push(emit(`type ${wireText(s.text)}`)); budgetMs += 6 * FRAME_MS
+      parts.push(`type ${pt(p)}="${s.text}"`)
     } else if (action === "drag") {
-      const a = coord(at, "drag", s.drag), b = coord(at, "to", s.to)
+      const a = target(at, "drag", s.drag), b = target(at, "to", s.to)
       const ms = num(at, "ms", s.ms, 300)
-      plan.lines.push(emit(`drag ${a.x} ${a.y} ${b.x} ${b.y} ${Math.round(ms)}`)); budgetMs += ms + 4 * FRAME_MS
+      plan.lines.push(emit(`drag ${wire(a)} ${wire(b)} ${Math.round(ms)}`)); budgetMs += ms + 4 * FRAME_MS
       parts.push(`drag ${pt(a)} → ${pt(b)} over ${ms}ms`)
     } else if (action === "hold") {
-      const p = coord(at, "hold", s.hold)
+      const p = target(at, "hold", s.hold)
       const ms = num(at, "ms", s.ms)
-      plan.lines.push(emit(`hold ${p.x} ${p.y} ${Math.round(ms)}`)); budgetMs += ms + 4 * FRAME_MS
+      plan.lines.push(emit(`hold ${wire(p)} ${Math.round(ms)}`)); budgetMs += ms + 4 * FRAME_MS
       parts.push(`hold ${pt(p)} ${ms}ms`)
+    } else if (action === "hover") {
+      // The cursor over a node: Input.mouse.position + the UI hover (`$hovered`, onMouseEnter). The
+      // host completes it two frames later, after the enter / leave crossed into JS.
+      const p = target(at, "hover", s.hover)
+      plan.lines.push(emit(`mouseto ${wire(p)}`)); budgetMs += 3 * FRAME_MS
+      parts.push(`hover ${pt(p)}`)
+    } else if (action === "fill") {
+      const f = s.fill
+      if (typeof f !== "object" || f === null || ((f as { value?: unknown }).value !== undefined && typeof (f as { value?: unknown }).value !== "string")) {
+        throw new CliError(`${at}: "fill" must be {} or { "value": string }.`)
+      }
+      const value = (f as { value?: string }).value
+      plan.lines.push(emit(value !== undefined ? `fill ${wireText(value)}` : "fill")); budgetMs += 8 * 6 * FRAME_MS   // room for a form of inputs
+      parts.push(value !== undefined ? `fill inputs ("${value}")` : "fill inputs")
+    } else if (action === "scroll") {
+      // `{ "scroll": 300 }` = the first scrollable; `{ "scroll": "feed", "by": 300 }` = the named one's.
+      if (typeof s.scroll === "number") {
+        if (s.by !== undefined) throw new CliError(`${at}: "by" only goes with a named "scroll".`)
+        plan.lines.push(emit(`scroll ${s.scroll}`)); parts.push(`scroll ${s.scroll}`)
+      } else if (typeof s.scroll === "string") {
+        if (typeof s.by !== "number") throw new CliError(`${at}: scrolling a named target needs "by" (px).`)
+        if (s.scroll.length === 0) throw new CliError(`${at}: "scroll" is an empty name.`)
+        plan.lines.push(emit(`scroll ${s.by} ${wire(s.scroll)}`)); parts.push(`scroll ${s.scroll} by ${s.by}`)
+      } else throw new CliError(`${at}: "scroll" must be a number (px) or a name (+ "by").`)
+      budgetMs += 2 * FRAME_MS
     } else if (action === "key") {
       if (typeof s.key !== "string") throw new CliError(`${at}: "key" must be a KeyboardEvent.code string.`)
       const ms = num(at, "ms", s.ms)
@@ -144,7 +203,7 @@ export const translateScenario = (rawSteps: unknown, opts: { outDir: string, hea
     } else if (action === "mouseTo") {
       const v = s.mouseTo
       if (!Array.isArray(v) || v.length !== 2 || !v.every((n: unknown) => typeof n === "number")) throw new CliError(`${at}: "mouseTo" must be [x, y] (logical px).`)
-      plan.lines.push(emit(`mouseto ${v[0]} ${v[1]}`)); budgetMs += FRAME_MS
+      plan.lines.push(emit(`mouseto ${v[0]} ${v[1]}`)); budgetMs += 3 * FRAME_MS
       parts.push(`mouseTo ${v[0]},${v[1]}`)
     } else if (action === "wheel") {
       const v = s.wheel
@@ -184,29 +243,71 @@ export const translateScenario = (rawSteps: unknown, opts: { outDir: string, hea
       if (typeof s.expect !== "object" || s.expect === null) throw new CliError(`${at}: "expect" must be an object.`)
       const e = s.expect as Record<string, unknown>
       const bits: string[] = []
+      let needDump = false
       for (const k of Object.keys(e)) {
         if (k === "log") {
           if (typeof e.log !== "string") throw new CliError(`${at}: expect.log must be a string.`)
           plan.expectLog = e.log
           bits.push(`log~"${e.log}"`)
+        } else if (k === "paint") {
+          if (typeof e.paint !== "object" || e.paint === null) throw new CliError(`${at}: expect.paint must be an object of node names.`)
+          plan.expectPaint = e.paint as PaintExpect
+          needDump = true
+          bits.push(`paint(${Object.keys(e.paint).join(", ")})`)
         } else if (SEMANTIC_EXPECT.includes(k)) {
+          if (k === "value") {
+            const v = e.value as { target?: unknown, equals?: unknown } | null
+            if (typeof v !== "object" || v === null || typeof v.target !== "string" || typeof v.equals !== "string") throw new CliError(`${at}: expect.value needs { "target": string, "equals": string }.`)
+          } else if (typeof e[k] !== "string") throw new CliError(`${at}: expect.${k} must be a string.`)
+          plan.expectSemantic = { ...(plan.expectSemantic ?? {}), [k]: e[k] }
+          needDump = true
+          const v = e[k]
+          bits.push(k === "screen" ? `screen=${v}` : k === "node" ? `node=${v}` : k === "notNode" ? `!node=${v}` : k === "text" ? `text~"${v}"` : k === "notText" ? `!text~"${v}"` : `${(v as { target: string }).target}="${(v as { equals: string }).equals}"`)
+        } else if (UNSUPPORTED_EXPECT.includes(k)) {
           plan.skippedExpect.push(k)
         } else {
           throw new CliError(`${at}: unknown expect key "${k}".`)
         }
       }
+      if (needDump) {
+        plan.paintDump = resolve(opts.outDir, `.dump-${i}.json`)
+        // The tree dump lands one frame after the action settled, like a screenshot.
+        plan.lines.push(emit(`frames 1`))
+        plan.lines.push(emit(`dump ${plan.paintDump}`)); budgetMs += 2 * FRAME_MS
+      }
       if (bits.length > 0) parts.push(`expect ${bits.join(" · ")}`)
     }
-    if (s.clip !== undefined) throw new CliError(`${at}: "clip" isn't available with --desktop (the native host dumps the whole window).`)
+    if (s.clip !== undefined && s.screenshot === undefined) throw new CliError(`${at}: "clip" only goes with "screenshot".`)
     if (s.screenshot !== undefined) {
       if (typeof s.screenshot !== "string") throw new CliError(`${at}: "screenshot" must be a path.`)
+      if (opts.sim) throw new CliError(`${at}: "screenshot" isn't available with --sim (the windowless host paints nothing) — judge the run by expect.log, or run it with --desktop for pixels.`)
       plan.screenshot = resolve(opts.outDir, s.screenshot)
       // The shot lands AFTER the action settles (two frames), like the headless act → capture order.
+      // A clip (a node's box or a logical-px rect) is set for the shot and cleared after it.
+      const clip = s.clip
+      if (clip !== undefined) {
+        if (typeof clip === "string") {
+          if (clip.length === 0) throw new CliError(`${at}: "clip" is an empty name.`)
+          plan.lines.push(emit(`frames 2`))   // the node's box after the action settled
+          plan.lines.push(emit(`clip ${wire(clip)}`))
+        } else if (typeof clip === "object" && clip !== null && ["x", "y", "width", "height"].every((k) => typeof (clip as Record<string, unknown>)[k] === "number")) {
+          const r = clip as { x: number, y: number, width: number, height: number }
+          plan.lines.push(emit(`clip ${r.x} ${r.y} ${r.width} ${r.height}`))
+        } else throw new CliError(`${at}: "clip" must be a node name or { "x", "y", "width", "height" }.`)
+      }
       plan.lines.push(emit(`frames 2`))
-      plan.lines.push(emit(`shot ${plan.screenshot}`)); budgetMs += 3 * FRAME_MS
-      parts.push(`→ ${s.screenshot}`)
+      plan.lines.push(emit(`shot ${plan.screenshot}`)); budgetMs += 5 * FRAME_MS
+      if (clip !== undefined) plan.lines.push(emit(`clip off`))
+      parts.push(`→ ${s.screenshot}${clip !== undefined ? ` (clip ${typeof clip === "string" ? clip : "rect"})` : ""}`)
     }
     if (s.json !== undefined) plan.skippedOutputs.push("json")
+    if (s.dump !== undefined) {
+      if (typeof s.dump !== "string") throw new CliError(`${at}: "dump" must be a path.`)
+      plan.dump = resolve(opts.outDir, s.dump)
+      plan.lines.push(emit(`frames 1`))
+      plan.lines.push(emit(`dump ${plan.dump}`)); budgetMs += 2 * FRAME_MS
+      parts.push(`→ ${s.dump} (dump)`)
+    }
     if (plan.lines.length === 0) {
       // An expect-only step still needs a marker to anchor its evaluation.
       plan.lines.push(emit(`frames 1`)); budgetMs += FRAME_MS
@@ -230,7 +331,7 @@ export type DesktopRunResult = {
 
 /** Turn the host's stdout into per-step results. Console lines are every non-`[script]` line the
  *  host printed up to a step's completion marker (the core prints `console.log` as `[DEBUG] …`). */
-export const evaluateDesktopRun = (plan: DesktopPlan, output: string): DesktopRunResult => {
+export const evaluateDesktopRun = (plan: DesktopPlan, output: string, readFile: (path: string) => string | null = () => null): DesktopRunResult => {
   const lines = output.split(/\r?\n/)
   const doneAt = new Map<number, { at: number, error?: string }>()
   const consoleLines: string[] = []
@@ -251,8 +352,8 @@ export const evaluateDesktopRun = (plan: DesktopPlan, output: string): DesktopRu
   let ok = true
   for (const st of plan.steps) {
     const skipped = [
-      ...st.skippedExpect.map((k) => `expect.${k} (no semantic tree on --desktop)`),
-      ...st.skippedOutputs.map((k) => `${k} output (no semantic tree on --desktop)`),
+      ...st.skippedExpect.map((k) => `expect.${k} (the headless audio recorder's — not on a native host)`),
+      ...st.skippedOutputs.map((k) => `${k} output (the headless renderer's shape — use "dump" on a native host)`),
     ]
     let error: string | undefined
     let cutoff = consoleLines.length
@@ -262,6 +363,20 @@ export const evaluateDesktopRun = (plan: DesktopPlan, output: string): DesktopRu
       if (d.error) { error = error ?? d.error; break }
       cutoff = d.at
     }
+    if (!error && (st.expectPaint !== undefined || st.expectSemantic !== undefined)) {
+      const text = st.paintDump ? readFile(st.paintDump) : null
+      if (text === null) error = "the host wrote no tree dump for the expect (an older host without the `dump` command?)"
+      else {
+        try {
+          const dump = parseTreeDump(text)
+          const failures = [
+            ...(st.expectSemantic !== undefined ? evaluateDumpExpect(dump, st.expectSemantic) : []),
+            ...(st.expectPaint !== undefined ? evaluatePaintExpect(dump, st.expectPaint) : []),
+          ]
+          if (failures.length > 0) error = failures.join("; ")
+        } catch (e) { error = `expect: ${e instanceof Error ? e.message : String(e)}` }
+      }
+    }
     if (!error && st.expectLog !== undefined) {
       const seen = consoleLines.slice(0, cutoff)
       if (!seen.some((l) => l.includes(st.expectLog!))) {

package/src/hosts/distRoot.ts

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url"
  *  - npm package: the bundle is dist/index.js, companions at ../runtime.
  *  - monorepo dev: this module runs from src/hosts/, so the package root is two levels up. The
  *    package.json marker matters here — runtime/ is gitignored and absent until vendor-runtime runs,
- *    and callers also resolve siblings from the root (../projects, ../creator-gl).
+ *    and callers also resolve siblings from the root (../../engines/gl).
  *  - standalone binary (`bun build --compile`, see scripts/build-bin.ts): import.meta.url points into
  *    the virtual bunfs archive which does NOT exist on disk, so the companions ship in the release
  *    archive NEXT TO the executable and are resolved via process.execPath. */

package/src/hosts/matcTool.ts

@@ -14,7 +14,7 @@ import { CliError, note } from "../cli"
  * releases/versions.json — published by scripts/release/release-windows.ps1 / release-ubuntu.sh
  * from the desktop build's in-tree filament host tools, so it always matches the engines the
  * hosts ship). Cache: ~/.lecodes/matc/matc-<version>/. LECODES_MATC overrides resolution entirely
- * (local dev: point it at packages/desktop/build/creator-gl/filament/tools/matc/matc.exe).
+ * (local dev: point it at hosts/desktop/build/creator-gl/filament/tools/matc/matc.exe).
  *
  * No version pin: a filamat's compatibility is tied to the vendored Filament, which changes rarely —
  * resolution takes the newest cached copy, else downloads the newest release PUBLISHED FOR THIS

package/src/hosts/peerInstall.ts

@@ -8,7 +8,7 @@ import { CliError, c, confirm, log, note } from "../cli"
 
 /*
  * Peers install themselves on first use. `lecodes render` on a machine with only the CLI asks once,
- * then puts lecodes-renderer (+ @napi-rs/canvas for PNG) into ~/.lecodes/peers and loads it from
+ * then puts lecodes-headless (+ @napi-rs/canvas for PNG) into ~/.lecodes/peers and loads it from
  * there — the same pattern as matc and the desktop host (downloaded into ~/.lecodes on first use),
  * applied to npm packages. Why a private prefix and not `npm install -g`: no sudo / system prefix
  * to guess, and the runtime-set peer is installed at EXACTLY this CLI's version — the compiler and the
@@ -31,9 +31,9 @@ const readJson = (path: string): any => { try { return JSON.parse(readFileSync(p
 /** The npm spec a peer installs at: the renderer at exactly this CLI's version (one ABI set), canvas
  *  at the range the installed renderer declares, the editors / assets at this CLI's peer ranges. */
 export const peerSpec = (name: string): string => {
-  if (name === "lecodes-renderer") return `lecodes-renderer@${pkg.version}`
+  if (name === "lecodes-headless") return `lecodes-headless@${pkg.version}`
   if (name === "@napi-rs/canvas") {
-    const renderer = readJson(join(peerDirInPrefix("lecodes-renderer"), "package.json"))
+    const renderer = readJson(join(peerDirInPrefix("lecodes-headless"), "package.json"))
     const range = renderer?.peerDependencies?.["@napi-rs/canvas"] ?? renderer?.optionalDependencies?.["@napi-rs/canvas"] ?? CANVAS_RANGE_FALLBACK
     return `@napi-rs/canvas@${range}`
   }
@@ -42,7 +42,7 @@ export const peerSpec = (name: string): string => {
 }
 
 /** Peers that only make sense together: the renderer's PNG output needs canvas next to it. */
-const companions = (name: string): string[] => name === "lecodes-renderer" ? ["lecodes-renderer", "@napi-rs/canvas"] : [name]
+const companions = (name: string): string[] => name === "lecodes-headless" ? ["lecodes-headless", "@napi-rs/canvas"] : [name]
 
 const onPath = (cmd: string): boolean => {
   try { return spawnSync(cmd, ["--version"], { stdio: "ignore", shell: process.platform === "win32" }).status === 0 } catch { return false }
@@ -66,7 +66,7 @@ export const installPeers = async (names: string[], why: string, opts: { yes?: b
     }, null, 2) + "\n")
   }
   // The renderer must be in place before canvas's range can be read off it — install in order.
-  const ordered = [...names].sort((a, b) => (a === "lecodes-renderer" ? -1 : b === "lecodes-renderer" ? 1 : 0))
+  const ordered = [...names].sort((a, b) => (a === "lecodes-headless" ? -1 : b === "lecodes-headless" ? 1 : 0))
   const specsNow = ordered.map(peerSpec)
 
   const yes = opts.yes === true || !!process.env.LECODES_YES