lecodes-cli 0.19.2 → 0.20.1

package/src/dev/androidDev.ts

@@ -0,0 +1,154 @@
+import { existsSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { spawnSync } from "node:child_process"
+import { CliError, note, warnErr } from "../util"
+
+/*
+ * `lecodes dev --android` — open the dev URL in the LeCodes app on the connected phone, through adb.
+ *
+ * Why adb instead of "scan the QR": the phone reaches this machine over `adb reverse` (its
+ * 127.0.0.1:<port> is our port), so it works over USB with no Wi-Fi, no LAN-address guessing
+ * (WSL/Docker/VPN adapters), no firewall prompt. The launch is an EXPLICIT component intent — the
+ * app's VIEW filter is pinned to le.codes/qr, and an explicit start bypasses filter matching — with
+ * the plain dev.js url: the app's initial.js only fetches a url that ends in ".js", anything else is
+ * sent to le.codes/api/code, which answers 400 for a dev bundle (the "Произошла ошибка при открытии
+ * проекта" screen). That is also why the poll transport is a PATH (/dev-poll.js), never `?t=poll`.
+ *
+ * A device run has no frame cap (unlike the desktop host), so every exit path force-stops the app:
+ * a 3D scene left rendering is a sustained GPU load on a charging phone.
+ */
+
+export const DEFAULT_ANDROID_PACKAGE = "com.letary.lecodes"
+
+export type AndroidDevOptions = {
+  port: number
+  /** The device-side url to open (with `adb reverse` in place, 127.0.0.1:<port> is this machine). */
+  url: string
+  serial?: string
+  apk?: string
+  packageName?: string
+}
+
+export type AndroidDevSession = {
+  serial: string
+  packageName: string
+  adb: string
+  /** `adb exec-out screencap -p` → the file. */
+  screenshot: (file: string) => boolean
+  /** force-stop the app + drop the reverse forward. Idempotent. */
+  stop: () => void
+}
+
+const adbCandidates = (): string[] => {
+  const out: string[] = []
+  if (process.env.LECODES_ADB) out.push(process.env.LECODES_ADB)
+  out.push("adb")
+  const exe = process.platform === "win32" ? "adb.exe" : "adb"
+  for (const home of [process.env.ANDROID_HOME, process.env.ANDROID_SDK_ROOT]) {
+    if (home) out.push(join(home, "platform-tools", exe))
+  }
+  if (process.platform === "win32" && process.env.LOCALAPPDATA) out.push(join(process.env.LOCALAPPDATA, "Android", "Sdk", "platform-tools", exe))
+  if (process.env.HOME) out.push(join(process.env.HOME, "Android", "Sdk", "platform-tools", exe), join(process.env.HOME, "Library", "Android", "sdk", "platform-tools", exe))
+  return out
+}
+
+const run = (adb: string, args: string[], input?: string): { ok: boolean, out: string } => {
+  const r = spawnSync(adb, args, { encoding: "utf8", input, windowsHide: true, maxBuffer: 64 * 1024 * 1024 })
+  const out = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim()
+  return { ok: r.status === 0, out }
+}
+
+/** The adb binary: LECODES_ADB, PATH, then the usual SDK locations. */
+export const resolveAdb = (): string => {
+  for (const cand of adbCandidates()) {
+    if (cand !== "adb" && !existsSync(cand)) continue
+    const r = spawnSync(cand, ["version"], { encoding: "utf8", windowsHide: true })
+    if (r.status === 0) return cand
+  }
+  throw new CliError("adb not found — install Android platform-tools (or point LECODES_ADB at adb).")
+}
+
+/** Connected devices in the `device` state (unauthorized/offline ones are reported, not used). */
+export const listDevices = (adb: string): { serial: string, state: string, model?: string }[] => {
+  const { out } = run(adb, ["devices", "-l"])
+  const devices: { serial: string, state: string, model?: string }[] = []
+  for (const line of out.split(/\r?\n/).slice(1)) {
+    const m = /^(\S+)\s+(\S+)(.*)$/.exec(line.trim())
+    if (!m) continue
+    const model = /model:(\S+)/.exec(m[3] ?? "")?.[1]
+    devices.push({ serial: m[1], state: m[2], model })
+  }
+  return devices
+}
+
+const pickDevice = (adb: string, serial: string | undefined): string => {
+  const all = listDevices(adb)
+  if (serial) {
+    const d = all.find((x) => x.serial === serial)
+    if (!d) throw new CliError(`No device "${serial}" — adb sees: ${all.map((x) => `${x.serial} (${x.state})`).join(", ") || "nothing"}.`)
+    if (d.state !== "device") throw new CliError(`Device ${serial} is "${d.state}" — accept the USB-debugging prompt on the phone.`)
+    return serial
+  }
+  const ready = all.filter((d) => d.state === "device")
+  if (ready.length === 1) return ready[0].serial
+  if (ready.length === 0) {
+    const other = all.map((d) => `${d.serial} (${d.state})`).join(", ")
+    throw new CliError(other
+      ? `No usable device: adb sees ${other}. "unauthorized" = accept the USB-debugging prompt on the phone; "offline" = replug.`
+      : "No Android device: enable USB debugging (Developer options), plug the phone in, accept the prompt — or `adb connect <ip>:5555` for Wi-Fi debugging.")
+  }
+  throw new CliError(`Several devices: ${ready.map((d) => `${d.serial}${d.model ? ` (${d.model})` : ""}`).join(", ")} — pick one with --serial <id>.`)
+}
+
+/** Install (optional), forward the port, launch the app on the dev url. Returns the session handle. */
+export const launchOnAndroid = (opts: AndroidDevOptions): AndroidDevSession => {
+  const adb = resolveAdb()
+  const serial = pickDevice(adb, opts.serial)
+  const packageName = opts.packageName ?? process.env.LECODES_ANDROID_PACKAGE ?? DEFAULT_ANDROID_PACKAGE
+  const dev = (args: string[]) => run(adb, ["-s", serial, ...args])
+
+  if (opts.apk) {
+    if (!existsSync(opts.apk)) throw new CliError(`--apk: ${opts.apk} does not exist.`)
+    note(`Installing ${opts.apk}…`)
+    const r = dev(["install", "-r", opts.apk])
+    if (!r.ok || !/Success/.test(r.out)) {
+      throw new CliError(`adb install failed: ${r.out}${/USER_RESTRICTED/.test(r.out) ? "\n(MIUI: enable \"Install via USB\" in Developer options.)" : ""}`)
+    }
+  }
+  const installed = dev(["shell", "pm", "path", packageName])
+  if (!installed.ok || !installed.out.includes("package:")) {
+    throw new CliError(`${packageName} is not installed on ${serial} — pass --apk <file> (lecodes-android: .\\gradlew :app:assembleDebug → app/build/outputs/apk/debug/app-debug.apk).`)
+  }
+
+  // The phone's 127.0.0.1:<port> → this machine's dev server. Survives Wi-Fi changes and VPNs.
+  const rev = dev(["reverse", `tcp:${opts.port}`, `tcp:${opts.port}`])
+  if (!rev.ok) warnErr(`adb reverse failed (${rev.out}) — the phone must reach the LAN url instead.`)
+
+  dev(["shell", "am", "force-stop", packageName])
+  dev(["logcat", "-c"])
+  const start = dev(["shell", "am", "start", "-n", `${packageName}/.MainActivity`, "-a", "android.intent.action.VIEW", "-d", opts.url])
+  if (!start.ok || /Error/.test(start.out)) throw new CliError(`Could not launch ${packageName}: ${start.out}`)
+
+  let stopped = false
+  return {
+    serial, packageName, adb,
+    screenshot: (file: string) => {
+      const r = spawnSync(adb, ["-s", serial, "exec-out", "screencap", "-p"], { windowsHide: true, maxBuffer: 64 * 1024 * 1024 })
+      if (r.status !== 0 || !r.stdout || r.stdout.length === 0) return false
+      writeFileSync(file, r.stdout)
+      return true
+    },
+    stop: () => {
+      if (stopped) return
+      stopped = true
+      dev(["shell", "am", "force-stop", packageName])
+      dev(["reverse", "--remove", `tcp:${opts.port}`])
+    },
+  }
+}
+
+/** Crash lines for the app since the launch (logcat was cleared then): the native + Java fatals. */
+export const androidCrashLines = (session: AndroidDevSession): string[] => {
+  const { out } = run(session.adb, ["-s", session.serial, "logcat", "-d", "-v", "brief"])
+  return out.split(/\r?\n/).filter((l) => /FATAL EXCEPTION|Fatal signal|\[crash\]/.test(l) || (/AndroidRuntime/.test(l) && l.includes(session.packageName))).slice(-20)
+}

package/src/dev/devServer.ts

@@ -24,6 +24,9 @@ import { makeStackDemangler } from "../compile/nativeStack"
  *   GET /t/<tok>/version         {"v":N} — polling fallback
  *   POST /t/<tok>/log            log/error backchannel for polling clients
  *   WS  /t/<tok>/ws              reload push + log/error backchannel
+ *   GET /t/<tok>/web/[file]      the Web Lite browser runner (viewer-lite dist-embed, `dev --web`):
+ *                                it loads bundle.js?t=web — the bundle WITHOUT the native prelude;
+ *                                the page owns reload (ws / version polling) and the log backchannel
  *
  * Compile is eager: the command calls recompile() on every file change; a successful compile bumps
  * `v` and broadcasts {type:"reload", v} to connected sockets (polling clients see /version move).
@@ -41,6 +44,8 @@ export type DevServerOptions = {
   port: number
   token: string
   entryOverride?: string
+  /** The Web Lite runner folder to serve under /web/ (src/dev/webRunner.ts); absent = no browser route. */
+  webDir?: string | null
   /** Diagnostics (compile errors, device logs); defaults to stderr-style silence-safe noop. */
   log?: (msg: string) => void
 }
@@ -51,6 +56,8 @@ export type RecompileResult =
 
 export type DevServer = {
   url: string
+  /** The browser runner page (`dev --web`), or null when no runner is vendored. */
+  webUrl: string | null
   /** The token base path ("/t/<token>"). */
   base: string
   /** The actually-bound port (differs from options.port when 0 was passed, e.g. in tests). */
@@ -68,7 +75,8 @@ const MIME: Record<string, string> = {
   mp3: "audio/mpeg", wav: "audio/wav", ogg: "audio/ogg", m4a: "audio/mp4",
   mp4: "video/mp4", webm: "video/webm",
   ttf: "font/ttf", otf: "font/otf", woff: "font/woff", woff2: "font/woff2",
-  json: "application/json", txt: "text/plain", js: "text/javascript",
+  json: "application/json", txt: "text/plain", js: "text/javascript", mjs: "text/javascript",
+  css: "text/css", html: "text/html", wasm: "application/wasm", map: "application/json",
 }
 
 const contentType = (path: string): string => {
@@ -182,22 +190,60 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
   }
 
   // ---- http --------------------------------------------------------------------------------------
-  const transportOf = (url: URL): "ws" | "poll" => (url.searchParams.get("t") === "poll" ? "poll" : "ws")
+  // "web" = the browser runner: no prelude at all (the page brings its own reload + log channel).
+  const transportOf = (url: URL): "ws" | "poll" | "web" => {
+    const t = url.searchParams.get("t")
+    return t === "poll" ? "poll" : t === "web" ? "web" : "ws"
+  }
+  const withPrelude = (js: string, url: URL, v: number, forced?: "poll") => {
+    const transport = forced ?? transportOf(url)
+    return transport === "web" ? js : js + "\n" + renderPrelude({ origin, base, transport, v })
+  }
+  const webDir = options.webDir ?? null
 
   const handle = async (req: IncomingMessage, res: ServerResponse) => {
     const url = new URL(req.url ?? "/", origin)
     const path = url.pathname
+    // Browsers ask for it on every page load (the /web/ runner) — keep the console clean.
+    if (path === "/favicon.ico") { res.writeHead(204); res.end(); return }
     if (!path.startsWith(base + "/")) return sendText(res, 404, "text/plain", "Not found")
     const route = path.slice(base.length)
 
     if (route === "/dev.js") {
-      return sendText(res, 200, "text/javascript",
-        devJs + "\n" + renderPrelude({ origin, base, transport: transportOf(url), v: -1 }))
+      return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1))
+    }
+    // The poll transport as a PATH: the Android app's initial.js only fetches a launch url that ends
+    // in ".js" (anything else goes to le.codes/api/code), so `?t=poll` can't reach it. Same bundle,
+    // prelude polls instead of the websocket — what `dev --android` opens under Bun (no ws there).
+    if (route === "/dev-poll.js") {
+      return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1, "poll"))
     }
     if (route === "/bundle.js") {
       if (bundleJs === null) return sendText(res, 503, "text/plain", "No successful compile yet — check the terminal.")
-      return sendText(res, 200, "text/javascript",
-        bundleJs + "\n" + renderPrelude({ origin, base, transport: transportOf(url), v }))
+      res.setHeader("x-lecodes-v", String(v))   // the browser runner learns the version it runs
+      return sendText(res, 200, "text/javascript", withPrelude(bundleJs, url, v))
+    }
+    // The browser runner: a static folder with relative asset paths, so it needs the trailing slash.
+    if (route === "/web") {
+      res.writeHead(302, { location: `${base}/web/${url.search}` })
+      res.end()
+      return
+    }
+    if (route.startsWith("/web/")) {
+      if (!webDir) return sendText(res, 404, "text/plain", "No Web Lite runner vendored with this CLI (lecodes-viewer-lite dist-embed).")
+      const rel = route === "/web/" ? "embed.html" : route.slice("/web/".length)
+      if (rel.split("/").some((seg) => seg === ".." || seg === "" || seg === ".")) return sendText(res, 400, "text/plain", "Bad path")
+      const abs = join(webDir, ...rel.split("/"))
+      try {
+        if (!statSync(abs).isFile()) throw new Error("not a file")
+      } catch {
+        return sendText(res, 404, "text/plain", "Not found")
+      }
+      // The entry files (html, embed.js) must revalidate — a CLI update swaps them under the same URL.
+      const hashed = rel.startsWith("assets/")
+      res.writeHead(200, { "content-type": contentType(rel), "cache-control": hashed ? "max-age=31536000, immutable" : "no-store" })
+      createReadStream(abs).pipe(res)
+      return
     }
     if (route === "/version") {
       return sendJson(res, 200, { v })
@@ -279,6 +325,7 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
 
   return {
     url: `${origin}${base}/dev.js`,
+    webUrl: webDir ? `${origin}${base}/web/` : null,
     base,
     port: boundPort,
     v: () => v,

package/src/dev/webRunner.ts

@@ -0,0 +1,22 @@
+import { existsSync } from "node:fs"
+import { createRequire } from "node:module"
+import { dirname, join } from "node:path"
+import { distRoot } from "../distRoot"
+
+/**
+ * Where the browser runner for `lecodes dev --web` lives: viewer-lite's built `dist-embed`
+ * (embed.html + embed.js + assets/ — the Web Lite host as a static folder). Two shapes:
+ *   - vendored next to the CLI as runtime/web (scripts/vendor-runtime.ts — the npm package and
+ *     the standalone binary),
+ *   - the lecodes-viewer-lite package's own dist-embed (monorepo dev after `bun run build:embed`).
+ * `null` = no runner available (the dev server then serves everything but /web/).
+ */
+export const resolveWebRunnerDir = (): string | null => {
+  const candidates = [join(distRoot, "runtime", "web")]
+  try {
+    const pkg = createRequire(import.meta.url).resolve("lecodes-viewer-lite/package.json")
+    candidates.push(join(dirname(pkg), "dist-embed"))
+  } catch { /* no package: standalone */ }
+  for (const dir of candidates) if (existsSync(join(dir, "embed.html")) && existsSync(join(dir, "embed.js"))) return dir
+  return null
+}

package/src/index.ts

@@ -31,7 +31,7 @@ import { CliError, c, log, parseArgs, type Args } from "./util"
 import { installedDesktopVersions, selectedDesktopVersion } from "./desktopRenderer"
 import { installedMatcVersions } from "./matcTool"
 import { loadProjectEnv } from "./projectEnv"
-import { OPTIONAL_PEERS, peerVersion } from "./peers"
+import { OPTIONAL_PEERS, peerSource, peerVersion } from "./peers"
 
 /* `install` is a standalone-binary-only command: it installs the shipped bundle onto PATH, so it's only
  * meaningful when that bundle actually sits next to the executable — the `chisel` bundler + `runtime/`
@@ -120,6 +120,17 @@ ${c.bold("Commands:")}
                                   --host <ip>     LAN address to advertise (default: auto-detect)
                                   --entry <path>  override the entrypoint
                                   --no-qr         don't render the QR code
+                                  --android       open the dev url in the LeCodes app on the phone
+                                                    plugged in over adb (adb reverse: no Wi-Fi/LAN
+                                                    address needed). --serial <id> picks a device,
+                                                    --apk <file> installs first, --package <name>
+                                                    (default com.letary.lecodes). Device logs stream
+                                                    here. --time <s> --png <file>: bounded check —
+                                                    screenshot after <s> seconds, force-stop, exit
+                                                    (exit 1 on a crash). Ctrl+C force-stops the app.
+                                  --web           also open the app in the browser (Web Lite host:
+                                                    same bundle + hot reload, camera/map plugins
+                                                    have web twins; the /web/ URL is served always)
                                   --desktop       also open the app in the native desktop host
                                                     (same hot reload; window from app.json's
                                                     desktop block; closing it keeps the server)
@@ -312,12 +323,15 @@ ${c.bold("Commands:")}
                                   --cell <m> (0.25)  --cell-height <m> (0.1)  --tile <cells> (48)
                                   --obj              also write <n>.navmesh.obj to inspect
                                   --frames <n>       load headroom (900) --logs  host output
-  shaders [compile|update]      The project's custom shaders (.mat) and their local compile:
+  shaders [compile|update|new]  The project's custom shaders (.mat) and their local compile:
                                   no args lists the shaders + their compile state; compile
                                   compiles them all into .lecodes/shaders (the same pass
                                   'lecodes dev' runs on the fly — via Filament's matc,
                                   downloaded on first use to ~/.lecodes/matc); update
-                                  downloads the newest matc (run after an engine upgrade)
+                                  downloads the newest matc (run after an engine upgrade);
+                                  new <name> [--ref lit] [--dir d] [--force] writes a fresh
+                                  .mat + .material.ts: the starter, or a copy of the engine's
+                                  own lit / unlit / particles / … source to start from
   scene [path]                  LeCodes Scene Editor — visually edit a .scene.ts (tree, inspector,
                                   gizmo) on local files (needs the optional 'lecodes-3d-editor' package;
                                   works inside a cloned project or standalone in any folder)
@@ -443,7 +457,10 @@ const printVersion = () => {
   const rows: [label: string, value: string][] = [["lecodes-cli", readVersion()]]
   for (const [name, probe] of OPTIONAL_PEERS) {
     const version = peerVersion(name, probe)
-    rows.push([name, version ?? c.dim("not installed")])
+    const where = peerSource(name, probe)
+    rows.push([name, version
+      ? (where === "prefix" ? `${version} ${c.dim("(~/.lecodes/peers)")}` : version)
+      : c.dim("not installed — installed on first use")])
   }
   const desktopVersion = selectedDesktopVersion()
   rows.push(["lecodes-desktop", installedDesktopVersions().includes(desktopVersion)
@@ -461,6 +478,9 @@ const main = async () => {
   // The project's .env (LECODES_* / CREATOR_* next to app.json) — before any command reads the
   // environment; the real environment keeps precedence. See projectEnv.ts.
   loadProjectEnv()
+  // `--yes` / `-y` anywhere on the line also pre-approves first-use installs of optional peers
+  // (peerInstall.ts) — the same knob LECODES_YES=1 gives CI.
+  if (argv.includes("--yes") || argv.includes("-y")) process.env.LECODES_YES = "1"
 
   if (!command || command === "help" || command === "--help" || command === "-h") {
     log(HELP)

package/src/matcTool.ts

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync } from "node:fs"
 import { homedir } from "node:os"
 import { join, resolve } from "node:path"
-import { downloadReleaseArchive, fetchReleaseProduct, semverNewer, type ManifestVersion } from "./releases"
+import { downloadReleaseArchive, fetchReleaseProduct, newestForPlatform, semverNewer, type ManifestFile, type ManifestVersion } from "./releases"
 import { CliError, note } from "./util"
 
 /*
@@ -16,8 +16,11 @@ import { CliError, note } from "./util"
  * 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).
  *
- * No version pin: a filamat's compatibility is tied to the vendored Filament, which changes
- * rarely — resolution takes the newest cached copy, else downloads `latest`. `lecodes shaders
+ * 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
+ * PLATFORM (releases.ts newestForPlatform), NOT the product's `latest`: a release only ships the
+ * platforms whose machine ran it, so `latest` is often Windows-only and every other platform would
+ * read "not published" with a perfectly good older build sitting right there. `lecodes shaders
  * update` moves an existing cache forward after an engine upgrade.
  *
  * Platforms: windows-x64, linux-x64, macos-arm64. On Windows/Linux matc rides the DESKTOP build
@@ -80,15 +83,21 @@ export const installedMatcVersions = (): string[] => {
 export const fetchMatcManifest = (): Promise<{ latest: string, versions: ManifestVersion[] }> =>
   fetchReleaseProduct("matc", "matc (shader compiler)")
 
-const downloadMatc = async (version: string, versions: ManifestVersion[], dest: string): Promise<void> => {
+/** The published matc this platform should get: the newest version carrying a build for it (see
+ *  newestForPlatform — a release often ships one platform, so `latest` is the wrong question). */
+const pickMatc = (versions: ManifestVersion[]): { version: string, file: ManifestFile } => {
   const key = platformKey()
-  const file = versions.find((v) => v.version === version)?.files[key]
-  if (!file) {
+  const hit = newestForPlatform(versions, key)
+  if (!hit) {
     throw new CliError(
-      `matc ${version} [${key}] isn't published — push the project once so shaders compile on the ` +
+      `matc isn't published for ${key} — push the project once so shaders compile on the ` +
       `server, or set LECODES_MATC to a locally built matc.`,
     )
   }
+  return hit
+}
+
+const downloadMatc = async (version: string, file: ManifestFile, dest: string): Promise<void> => {
   note(`Downloading the shader compiler (matc ${version}, ${(file.size / 1024 / 1024).toFixed(1)} MB)…`)
   await downloadReleaseArchive(file, {
     cacheRoot: cacheRoot(),
@@ -109,29 +118,32 @@ export const resolveMatcExeCached = (): string | null => {
   return cached ? findMatc(join(cacheRoot(), `matc-${cached}`)) : null
 }
 
-/** The matc binary: LECODES_MATC override → newest cached version → download the latest release.
- *  Throws CliError when unavailable (callers degrade to the push-once server-compile warning). */
+/** The matc binary: LECODES_MATC override → newest cached version → download the newest release
+ *  published for this platform. Throws CliError when unavailable (callers degrade to the push-once
+ *  server-compile warning). */
 export const resolveMatcExe = async (): Promise<string> => {
   const cached = resolveMatcExeCached()
   if (cached) return cached
-  const { latest, versions } = await fetchMatcManifest()
-  const dir = join(cacheRoot(), `matc-${latest}`)
-  await downloadMatc(latest, versions, dir)
+  const { versions } = await fetchMatcManifest()
+  const { version, file } = pickMatc(versions)
+  const dir = join(cacheRoot(), `matc-${version}`)
+  await downloadMatc(version, file, dir)
   const exe = findMatc(dir)
   if (!exe) throw new CliError(`matc cache at ${dir} is broken — delete the folder and retry.`)
   return exe
 }
 
-/** `lecodes shaders update`: download the newest published matc (cached versions stay; the newest
- *  wins resolution). Run it after an engine upgrade so local shader artifacts match the hosts. */
+/** `lecodes shaders update`: download the newest matc published for this platform (cached versions
+ *  stay; the newest wins resolution). Run it after an engine upgrade so local artifacts match the hosts. */
 export const updateMatc = async (): Promise<void> => {
-  const { latest, versions } = await fetchMatcManifest()
+  const { versions } = await fetchMatcManifest()
+  const { version, file } = pickMatc(versions)
   const before = installedMatcVersions()[0]
-  const dir = join(cacheRoot(), `matc-${latest}`)
+  const dir = join(cacheRoot(), `matc-${version}`)
   if (existsSync(dir) && findMatc(dir) !== null) {
-    note(`Already up to date: matc ${latest}.`)
+    note(`Already up to date: matc ${version}.`)
     return
   }
-  await downloadMatc(latest, versions, dir)
-  note(before ? `matc updated to ${latest} (was ${before}).` : `matc ${latest} installed.`)
+  await downloadMatc(version, file, dir)
+  note(before ? `matc updated to ${version} (was ${before}).` : `matc ${version} installed.`)
 }

package/src/peerInstall.ts

@@ -0,0 +1,160 @@
+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 { peerDirInPrefix, peersDir, peerVersionGlobal } from "./peers"
+import { CliError, c, confirm, log, note } from "./util"
+
+/*
+ * 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
+ * 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
+ * headless host are one ABI set, so a global renderer that drifted behind the CLI is the very failure
+ * this removes. A newer CLI re-installs its own version on the next use (peerSpec → `lecodes update`).
+ *
+ * Consent: an interactive terminal is asked (default yes); `--yes` / `-y` on any command or
+ * LECODES_YES=1 (CI) skips the question; a non-interactive run without either fails with the exact
+ * command to run by hand. Installer: npm if on PATH, else bun; neither → a clear error (the standalone
+ * binary on a machine without Node can't install packages — it says so).
+ *
+ * Search order when a command needs a peer: the bare specifier (global / the workspace — what the
+ * user installed by hand always wins) → the prefix → install into the prefix, then load from there.
+ */
+
+const CANVAS_RANGE_FALLBACK = "^0.1.65"
+
+const readJson = (path: string): any => { try { return JSON.parse(readFileSync(path, "utf8")) } catch { return null } }
+
+/** 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 === "@napi-rs/canvas") {
+    const renderer = readJson(join(peerDirInPrefix("lecodes-renderer"), "package.json"))
+    const range = renderer?.peerDependencies?.["@napi-rs/canvas"] ?? renderer?.optionalDependencies?.["@napi-rs/canvas"] ?? CANVAS_RANGE_FALLBACK
+    return `@napi-rs/canvas@${range}`
+  }
+  const range = (pkg.peerDependencies as Record<string, string> | undefined)?.[name]
+  return range ? `${name}@${range}` : `${name}@latest`
+}
+
+/** 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 onPath = (cmd: string): boolean => {
+  try { return spawnSync(cmd, ["--version"], { stdio: "ignore", shell: process.platform === "win32" }).status === 0 } catch { return false }
+}
+const pickInstaller = (): "npm" | "bun" | null => onPath("npm") ? "npm" : onPath("bun") ? "bun" : null
+
+const manualCommand = (dir: string, specs: string[]) => `npm install --prefix "${dir}" ${specs.join(" ")}`
+
+/**
+ * Install peers into the prefix. Asks for consent unless `opts.yes` / LECODES_YES / `--yes` say so;
+ * throws CliError with the manual command when it can't ask or the user declines.
+ */
+export const installPeers = async (names: string[], why: string, opts: { yes?: boolean } = {}): Promise<void> => {
+  const dir = peersDir()
+  mkdirSync(dir, { recursive: true })
+  const manifest = join(dir, "package.json")
+  if (!existsSync(manifest)) {
+    writeFileSync(manifest, JSON.stringify({
+      name: "lecodes-peers", private: true,
+      description: "Optional lecodes-cli peers, installed on first use. Safe to delete — the CLI re-installs what a command needs.",
+    }, 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 specsNow = ordered.map(peerSpec)
+
+  const yes = opts.yes === true || !!process.env.LECODES_YES
+  if (!yes) {
+    const interactive = process.stdin.isTTY && process.stdout.isTTY
+    if (!interactive) {
+      throw new CliError(`${why} needs ${names.join(" + ")}, which isn't installed. Re-run with --yes to install it into ${dir}, or install by hand:  ${manualCommand(dir, specsNow)}`)
+    }
+    log(`${why} needs ${c.bold(names.join(" + "))}.`)
+    log(c.dim(`It installs once into ${dir} (no admin rights); a newer CLI re-installs its own version.`))
+    if (!(await confirm("Install now?", true))) {
+      throw new CliError(`Not installed. When you want it:  ${manualCommand(dir, specsNow)}`)
+    }
+  }
+
+  const tool = pickInstaller()
+  if (!tool) throw new CliError(`Neither npm nor bun is on PATH, so ${names.join(" + ")} can't be installed automatically. Install one, or run on a machine with Node:  ${manualCommand(dir, specsNow)}`)
+
+  for (const name of ordered) {
+    const spec = peerSpec(name) // canvas's range comes from the renderer installed a step earlier
+    const argv = tool === "npm"
+      ? ["install", "--prefix", dir, "--no-audit", "--no-fund", "--loglevel=error", spec]
+      : ["add", "--cwd", dir, spec]
+    note(`$ ${tool} ${argv.join(" ")}`)
+    const r = spawnSync(tool, argv, { stdio: "inherit", shell: process.platform === "win32", timeout: 10 * 60_000 })
+    if (r.error) throw new CliError(`${tool} could not run: ${r.error.message}`)
+    if (r.status !== 0) throw new CliError(`${tool} exited with ${r.status ?? "a signal"} while installing ${spec}. By hand:  ${manualCommand(dir, [spec])}`)
+    if (!existsSync(join(peerDirInPrefix(name), "package.json"))) throw new CliError(`${name} did not land in ${dir} — the installer finished but the package is missing`)
+  }
+}
+
+/** The file a package subpath points at, read from its exports map (string, or a conditions object —
+ *  `import` / `node` / `default`), falling back to `main`. Absolute path. */
+const resolveEntry = (pkgDir: string, subpath?: string): string => {
+  const manifest = readJson(join(pkgDir, "package.json"))
+  if (!manifest) throw new CliError(`${pkgDir} holds no package.json`)
+  const key = subpath ? `./${subpath}` : "."
+  const pick = (target: unknown): string | null => {
+    if (typeof target === "string") return target
+    if (target && typeof target === "object") {
+      const t = target as Record<string, unknown>
+      for (const cond of ["import", "node", "default", "require"]) if (cond in t) { const p = pick(t[cond]); if (p) return p }
+    }
+    return null
+  }
+  let rel: string | null = null
+  const exp = manifest.exports
+  if (typeof exp === "string") rel = key === "." ? exp : null
+  else if (exp && typeof exp === "object") rel = pick((exp as Record<string, unknown>)[key])
+  if (!rel && key === ".") rel = typeof manifest.main === "string" ? manifest.main : "index.js"
+  if (!rel) throw new CliError(`${manifest.name} has no export "${key}"`)
+  return join(pkgDir, rel)
+}
+
+const isNotFound = (e: unknown, spec: string): boolean => {
+  const code = (e as { code?: string })?.code
+  const msg = e instanceof Error ? e.message : String(e)
+  return (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || /Cannot find (module|package)/i.test(msg)) && msg.includes(spec.split("/")[0]!)
+}
+
+export type LoadPeerOptions = {
+  /** What is asking — names the command in the consent prompt / error ("lecodes render"). */
+  for: string
+  /** `false`: never install — return null when the peer is nowhere (opportunistic features). */
+  install?: boolean
+}
+
+/**
+ * Load an optional peer's subpath: the bare specifier first (global / workspace), then the CLI's
+ * prefix, else install it there (with its companions) and load. Returns null only with
+ * `install: false` and the peer absent.
+ */
+export async function loadPeer<T>(name: string, subpath: string | undefined, opts: LoadPeerOptions & { install?: true }): Promise<T>
+export async function loadPeer<T>(name: string, subpath: string | undefined, opts: LoadPeerOptions & { install: false }): Promise<T | null>
+export async function loadPeer<T>(name: string, subpath: string | undefined, opts: LoadPeerOptions): Promise<T | null> {
+  const spec = subpath ? `${name}/${subpath}` : name
+  try {
+    return (await import(spec)) as T
+  } catch (e) {
+    if (!isNotFound(e, spec)) throw e
+  }
+  const dir = peerDirInPrefix(name)
+  if (!existsSync(join(dir, "package.json"))) {
+    if (opts.install === false) return null
+    // A global install of a DIFFERENT version than the probe expects would have resolved above; here
+    // the peer is nowhere. (Globally installed but broken → the error above was not "not found".)
+    if (peerVersionGlobal(name, spec) !== null) throw new CliError(`${name} is installed but "${spec}" can't be loaded from it — reinstall it: npm install -g ${peerSpec(name)}`)
+    await installPeers(companions(name), opts.for)
+  }
+  return (await import(pathToFileURL(resolveEntry(dir, subpath)).href)) as T
+}