lecodes-cli 0.20.2 → 2.0.0

package/src/{desktopScript.ts → hosts/desktopScript.ts}

@@ -1,15 +1,24 @@
 import { resolve } from "node:path"
-import { CliError } from "./util"
+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/{distRoot.ts → hosts/distRoot.ts}

@@ -5,16 +5,20 @@ import { fileURLToPath } from "node:url"
 /* Root of the CLI's on-disk companion files (runtime/ with the vendored SDK source + type bundle).
  *
  * Two distribution shapes:
- *  - npm package / monorepo dev: this module lives in dist/ (or src/), companions at ../runtime —
- *    resolve relative to import.meta.url as before.
+ *  - 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 (../../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. */
 export const distRoot = (() => {
+  const here = dirname(fileURLToPath(import.meta.url))
   const candidates = [
-    join(dirname(fileURLToPath(import.meta.url)), ".."), // package root (dist/.. or src/..)
-    dirname(process.execPath),                           // standalone binary: next to the exe
+    join(here, ".."),           // npm package: dist/..
+    join(here, "..", ".."),     // monorepo dev: src/hosts/../..
+    dirname(process.execPath),  // standalone binary: next to the exe
   ]
-  for (const c of candidates) if (existsSync(join(c, "runtime"))) return c
+  for (const c of candidates) if (existsSync(join(c, "runtime")) || existsSync(join(c, "package.json"))) return c
   return candidates[0]
 })()

package/src/{matcTool.ts → hosts/matcTool.ts}

@@ -2,7 +2,7 @@ import { existsSync, readdirSync } from "node:fs"
 import { homedir } from "node:os"
 import { join, resolve } from "node:path"
 import { downloadReleaseArchive, fetchReleaseProduct, newestForPlatform, semverNewer, type ManifestFile, type ManifestVersion } from "./releases"
-import { CliError, note } from "./util"
+import { CliError, note } from "../cli"
 
 /*
  * Filament's matc (material compiler) — the tool behind LOCAL shader compile: `lecodes dev`
@@ -14,7 +14,7 @@ import { CliError, note } from "./util"
  * 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/{peerInstall.ts → hosts/peerInstall.ts}

@@ -2,13 +2,13 @@ import { spawnSync } from "node:child_process"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 import { pathToFileURL } from "node:url"
-import pkg from "../package.json"
+import pkg from "../../package.json"
 import { peerDirInPrefix, peersDir, peerVersionGlobal } from "./peers"
-import { CliError, c, confirm, log, note } from "./util"
+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

package/src/{peers.ts → hosts/peers.ts}

@@ -10,7 +10,7 @@ import { dirname, join, resolve } from "node:path"
  *            peers (a project-local `-D` install is invisible to it).
  *   prefix   ~/.lecodes/peers (LECODES_PEERS_DIR) — the CLI's own install dir, filled ON FIRST USE by
  *            peerInstall.ts when a command needs a peer that isn't there: no admin rights, and the
- *            runtime-set peer (lecodes-renderer) is pinned to THIS CLI's version, so the compiler and
+ *            runtime-set peer (lecodes-headless) is pinned to THIS CLI's version, so the compiler and
  *            the headless host can't drift apart. `@napi-rs/canvas` (PNG output) rides along with it.
  *
  * Global wins when both exist (it is what the user chose by hand). `--version` reports each peer's
@@ -18,7 +18,7 @@ import { dirname, join, resolve } from "node:path"
  * errors or a design screen rendering empty — is visible at a glance. The probe is an export subpath
  * that resolves to a real file in BOTH the published package and the workspace source. */
 export const OPTIONAL_PEERS: [name: string, probe: string][] = [
-  ["lecodes-renderer", "lecodes-renderer/headless"],
+  ["lecodes-headless", "lecodes-headless/headless"],
   ["lecodes-design", "lecodes-design/server"],
   ["lecodes-3d-editor", "lecodes-3d-editor/server"],
   ["lecodes-assets", "lecodes-assets/cli"],

package/src/{releases.ts → hosts/releases.ts}

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto"
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 import { spawnSync } from "node:child_process"
-import { CliError } from "./util"
+import { CliError } from "../cli"
 
 /*
  * The S3 release channel the CLI downloads native tools from: the manifest scripts/release/*