lecodes-cli 2.0.4 → 2.0.6

package/src/dev/projectBackend.ts

@@ -0,0 +1,199 @@
+import { rmSync } from "node:fs"
+import { join, relative } from "node:path"
+import { createChannelHub } from "lecodes-sdk/server"
+import { compileServer, hasServerFiles, type CompileEntry } from "../compile/projectCompile"
+import { loadPeer } from "../hosts/peerInstall"
+import { LECODES_DIR } from "../project/manifest"
+import { readAppConfigAt } from "../commands/app/shared"
+import { startLocalBackend, type LocalBackend } from "./localBackend"
+import { serve, type Served, type Socket, type SocketHandlers } from "./serve"
+
+/*
+ * The project's backend ON THE WIRE, on this machine: its server bundle run by localBackend.ts, put
+ * behind the routes the SDK's client transport speaks (sdk/src/runtime/rpc.ts) —
+ *
+ *   POST <base>/api/<id>   an endpoint call, the envelope always HTTP 200 (the client reads `ok`)
+ *   WS   <base>/ws         the channel socket: the SDK's hub, the one the runner serves on le.codes
+ *
+ * Two users: the dev server mounts the routes under its token path (`lecodes dev`, `web dev`, the
+ * browser tests), and `runBackend` listens on a port of its own for the commands that run a bundle
+ * on a host this CLI starts (`desktop run`, `serve`, `render --desktop`, `test --desktop`).
+ */
+
+export type ServerBundle = Awaited<ReturnType<typeof compileServer>>
+
+export type ProjectBackendOptions = {
+  root: string
+  log: (msg: string) => void
+  /** The database's folder (default `.lecodes/db`). */
+  dbDir?: string
+  /** The command, for the note of the database peer's install. */
+  command: string
+}
+
+export type ProjectBackend = {
+  /** The server bundle of these entries; null when the project has no server files. */
+  compile: (entries: CompileEntry[]) => Promise<ServerBundle | null>
+  /** Run this bundle from now on (null = the project has no server side any more: stop). Rejects
+   *  when it does not load; resolves to what to tell the developer. */
+  run: (bundle: ServerBundle | null) => Promise<string[]>
+  /** A request under the backend's base; `route` is the path after it ("/api/<id>"). */
+  handle: (req: Request, route: string, ip: string | undefined) => Promise<Response>
+  /** The channel socket (`<base>/ws`). */
+  socket: (req: Request, ip: string | undefined) => (conn: Socket) => SocketHandlers
+  /** Start again on an EMPTY database (a test's case). */
+  reset: () => Promise<void>
+  /** Resolves once the database is closed. */
+  close: () => Promise<void>
+}
+
+const CORS = {
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": "POST, GET, OPTIONS",
+  "access-control-allow-headers": "authorization, content-type",
+  "access-control-max-age": "86400",
+}
+const bearerOf = (req: Request): string | null => /^Bearer\s+(.+)$/i.exec(req.headers.get("authorization") ?? "")?.[1]?.trim() ?? null
+const BODY_LIMIT = 8 * 1024 * 1024
+
+export const createProjectBackend = (options: ProjectBackendOptions): ProjectBackend => {
+  const { root, log } = options
+  const dbDir = options.dbDir ?? join(root, LECODES_DIR, "db")
+  let backend: LocalBackend | null = null
+  let running: string | null = null
+
+  // The channel socket is the SDK's hub — the one the runner serves too.
+  const hub = createChannelHub<Socket>({
+    send: (conn, frame) => conn.send(frame),
+    subscribe: (_scope, ch, args, ctx) => backend
+      ? backend.subscribe(ch, args, ctx)
+      : Promise.resolve({ ok: false as const, status: 404, message: "The project has no server files" }),
+  })
+  const sockets = new Set<Socket>()
+  const start = () => startLocalBackend({ root, dbDir, log, onPublish: (ch, group, data) => hub.publish("", ch, group, data) })
+
+  const envelope = (body: unknown) => new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json", "cache-control": "no-store", ...CORS } })
+
+  return {
+    compile: async (entries) => {
+      if (!hasServerFiles(entries)) return null
+      // the app's name, for the sign-in mail
+      const app = readAppConfigAt(root)
+      return compileServer({ entries, root, app: app ? { name: app.name } : undefined })
+    },
+    run: async (bundle) => {
+      if (!bundle) {
+        await backend?.close()
+        backend = null
+        running = null
+        return []
+      }
+      // the embedded database is a peer, installed the first time a project defines models
+      if (Object.keys(bundle.manifest.modules).length && /\bdefineDb\s*\(/.test(bundle.code)) {
+        await loadPeer("marcidb-embedded", undefined, { for: `${options.command} (the project's database)` })
+      }
+      backend ??= start()
+      const deployed = await backend.deploy(bundle.code)
+      running = bundle.code
+      if (!deployed.changed) return []
+      const d = deployed.describe
+      const models = Object.keys(d.models).length
+      const count = (n: number, what: string) => `${n} ${what}${n === 1 ? "" : "s"}`
+      log(`server: ${count(d.endpoints.length, "endpoint")}, ${count(d.channels.length, "channel")}${models ? `, ${count(models, "model")} (database in ${relative(root, dbDir).replace(/\\/g, "/")})` : ""}`)
+      return deployed.notes.map((n) => `server: ${n}`)
+    },
+    handle: async (req, route, ip) => {
+      if (req.method === "OPTIONS") return new Response(null, { status: 204, headers: CORS })
+      const id = route.startsWith("/api/") ? decodeURIComponent(route.slice("/api/".length)) : ""
+      if (!id || req.method !== "POST") return envelope({ ok: false, status: 404, message: "not an endpoint call" })
+      if (!backend) return envelope({ ok: false, status: 404, message: "The project has no server files" })
+      let args: unknown
+      try {
+        const body = await req.text()
+        args = body.length > BODY_LIMIT ? null : JSON.parse(body)?.args
+      } catch { args = null }
+      if (!Array.isArray(args)) return envelope({ ok: false, status: 400, message: "body must be {\"args\":[…]}" })
+      return envelope(await backend.invoke(id, args, { headers: Object.fromEntries(req.headers), ip, sessionToken: bearerOf(req) ?? undefined }))
+    },
+    socket: (req, ip) => (conn) => {
+      const c = hub.connect(conn, { ip, session: bearerOf(req) })
+      sockets.add(conn)
+      return {
+        onMessage: (raw) => { void c.message(raw) },
+        onClose: () => { sockets.delete(conn); c.close() },
+      }
+    },
+    reset: async () => {
+      if (!backend || running === null) return
+      await backend.close()
+      rmSync(dbDir, { recursive: true, force: true })
+      backend = start()
+      await backend.deploy(running)
+    },
+    close: async () => {
+      for (const conn of [...sockets]) conn.close()
+      await backend?.close()
+      backend = null
+    },
+  }
+}
+
+// ───────────────────────────── a backend for one run of a bundle ─────────────────────────────
+
+export type RunBackend = {
+  /** Called by the compile, once it has the project's entries: the backend is started when there
+   *  are server files, and its url — what the app's stubs call — is the answer. */
+  start: (entries: CompileEntry[], onWarning: (w: string) => void) => Promise<string | undefined>
+  /** Start again on an empty database. */
+  reset: () => Promise<void>
+  close: () => Promise<void>
+}
+
+/** A port that stays the same for a project from run to run: the app keeps its session under the
+ *  backend's url, so a url that moved would sign the developer out at every run. */
+const stablePort = (root: string): number => {
+  let h = 0
+  for (let i = 0; i < root.length; i++) h = (h * 31 + root.charCodeAt(i)) >>> 0
+  return 42000 + (h % 4000)
+}
+
+/**
+ * The backend of a project run on this machine by a host the CLI starts, listening on
+ * 127.0.0.1. `test`: a database of its own (`.lecodes/test-db`, emptied by `reset`) and any free
+ * port — a test never touches what `lecodes dev` and `desktop run` keep in `.lecodes/db`.
+ */
+export const runBackend = (options: { root: string, command: string, log: (msg: string) => void, test?: boolean }): RunBackend => {
+  const { root } = options
+  const dbDir = join(root, LECODES_DIR, options.test ? "test-db" : "db")
+  if (options.test) rmSync(dbDir, { recursive: true, force: true })
+  const backend = createProjectBackend({ root, dbDir, log: options.log, command: options.command })
+  let server: Served | null = null
+
+  const listen = (port: number) => serve({
+    port,
+    hostname: "127.0.0.1",
+    fetch: (req, peer) => {
+      const path = new URL(req.url).pathname
+      return path.startsWith("/server/") ? backend.handle(req, path.slice("/server".length), peer.ip) : new Response("Not found", { status: 404 })
+    },
+    websocket: (req, peer) => new URL(req.url).pathname === "/server/ws" ? backend.socket(req, peer.ip) : null,
+    onError: (e) => options.log(`request failed: ${e instanceof Error ? e.message : String(e)}`),
+  })
+
+  return {
+    start: async (entries, onWarning) => {
+      const bundle = await backend.compile(entries)
+      if (!bundle) return undefined
+      for (const w of await backend.run(bundle)) onWarning(w)
+      // the project's port when it is free (two runs of one project at once: the second takes any)
+      server ??= await (options.test ? listen(0) : listen(stablePort(root)).catch(() => listen(0)))
+      return `http://127.0.0.1:${server.port}/server`
+    },
+    reset: () => backend.reset(),
+    close: async () => {
+      server?.close()
+      server = null
+      await backend.close()
+    },
+  }
+}

package/src/dev/serve.ts

@@ -0,0 +1,164 @@
+import { createServer, type IncomingMessage } from "node:http"
+import { Readable } from "node:stream"
+import { upgradeWebSocket } from "./wsServer"
+
+/*
+ * ONE way for the CLI to listen: a handler of web-standard requests (`Request` → `Response`) and
+ * websockets as text messages. The CLI runs on two runtimes — Node (the npm install) and Bun (a
+ * checkout, the standalone binary) — and this file is the only place that knows which:
+ *
+ *   Bun    `Bun.serve`: its own HTTP server and websockets. Bun's `node:http` is NOT an option
+ *          there — it emits 'upgrade' and then drops what is written to the socket, so a websocket
+ *          never completes its handshake (probed on 1.3.14).
+ *   Node   `node:http` + the dependency-free websocket of ./wsServer.ts.
+ *
+ * A server of the CLI that needs a websocket is written against this, never against `node:http`.
+ */
+
+export type Peer = {
+  /** The remote address, as the runtime reports it. */
+  ip: string | undefined
+}
+
+export type Socket = {
+  send: (text: string) => void
+  close: () => void
+}
+
+export type SocketHandlers = {
+  onMessage: (text: string) => void
+  /** Fired exactly once, however the connection ends. */
+  onClose: () => void
+}
+
+export type ServeOptions = {
+  port: number
+  /** Bind address (default 0.0.0.0). */
+  hostname?: string
+  fetch: (req: Request, peer: Peer) => Response | Promise<Response>
+  /** A websocket asks to connect: return what takes the open socket, or null to refuse. Decided
+   *  from the request alone (its path), before the handshake. */
+  websocket?: (req: Request, peer: Peer) => ((socket: Socket) => SocketHandlers) | null
+  /** A handler that threw (the response is a 500). */
+  onError?: (e: unknown) => void
+}
+
+export type Served = {
+  /** The bound port (differs from `options.port` when 0 was passed). */
+  port: number
+  close: () => void
+}
+
+const failure = (opts: ServeOptions, e: unknown): Response => {
+  opts.onError?.(e)
+  return new Response("Internal error", { status: 500, headers: { "content-type": "text/plain", "cache-control": "no-store" } })
+}
+
+// ───────────────────────────── Bun ─────────────────────────────
+
+type BunSocketData = { accept: (socket: Socket) => SocketHandlers, handlers: SocketHandlers | null }
+
+const serveBun = (opts: ServeOptions): Served => {
+  let server: ReturnType<typeof Bun.serve<BunSocketData>>
+  try {
+    server = Bun.serve<BunSocketData>({
+      port: opts.port,
+      hostname: opts.hostname ?? "0.0.0.0",
+      // seconds, the most Bun takes: an endpoint of a project's backend may think for 30
+      idleTimeout: 255,
+      async fetch(req, srv) {
+        const peer: Peer = { ip: srv.requestIP(req)?.address }
+        try {
+          if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
+            const accept = opts.websocket?.(req, peer)
+            if (!accept) return new Response("Not found", { status: 404 })
+            if (srv.upgrade(req, { data: { accept, handlers: null } })) return undefined as unknown as Response
+            return new Response("Expected a websocket upgrade", { status: 400 })
+          }
+          return await opts.fetch(req, peer)
+        } catch (e) {
+          return failure(opts, e)
+        }
+      },
+      websocket: {
+        // A reload channel is silent for as long as nobody saves: Bun's pings keep it open.
+        idleTimeout: 960,
+        sendPings: true,
+        open(ws) {
+          ws.data.handlers = ws.data.accept({
+            send: (text) => { if (ws.readyState === 1) ws.send(text) },
+            close: () => { ws.close() },
+          })
+        },
+        message(ws, raw) {
+          ws.data.handlers?.onMessage(typeof raw === "string" ? raw : new TextDecoder().decode(raw))
+        },
+        close(ws) {
+          const h = ws.data.handlers
+          ws.data.handlers = null
+          h?.onClose()
+        },
+      },
+    })
+  } catch (e) {
+    // the code node's listen() reports, which callers match on
+    if ((e as { code?: string }).code === "EADDRINUSE") throw new Error(`EADDRINUSE: port ${opts.port} is already in use`)
+    throw e
+  }
+  return { port: server.port ?? opts.port, close: () => { void server.stop(true) } }
+}
+
+// ───────────────────────────── Node ─────────────────────────────
+
+const requestOf = (req: IncomingMessage, upgrade = false): Request => {
+  const headers = new Headers()
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (v !== undefined) headers.set(k, Array.isArray(v) ? v.join(", ") : v)
+  }
+  const method = req.method ?? "GET"
+  const bodyless = upgrade || method === "GET" || method === "HEAD"
+  return new Request(new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`).href, {
+    method, headers,
+    ...(bodyless ? {} : { body: Readable.toWeb(req), duplex: "half" }),
+  } as unknown as RequestInit)
+}
+
+const serveNode = async (opts: ServeOptions): Promise<Served> => {
+  const server = createServer((req, res) => {
+    void (async () => {
+      let response: Response
+      try { response = await opts.fetch(requestOf(req), { ip: req.socket.remoteAddress }) }
+      catch (e) { response = failure(opts, e) }
+      res.writeHead(response.status, Object.fromEntries(response.headers))
+      if (!response.body || req.method === "HEAD") { res.end(); return }
+      Readable.fromWeb(response.body as unknown as import("node:stream/web").ReadableStream).on("error", () => res.destroy()).pipe(res)
+    })()
+  })
+  server.on("upgrade", (req, socket) => {
+    let accept: ((socket: Socket) => SocketHandlers) | null = null
+    try { accept = opts.websocket?.(requestOf(req, true), { ip: req.socket.remoteAddress }) ?? null }
+    catch (e) { opts.onError?.(e) }
+    if (!accept) { socket.destroy(); return }
+    let handlers: SocketHandlers | null = null
+    const conn = upgradeWebSocket(req, socket, {
+      onMessage: (text) => { handlers?.onMessage(text) },
+      onClose: () => { handlers?.onClose() },
+    })
+    if (conn) handlers = accept(conn)
+  })
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(opts.port, opts.hostname ?? "0.0.0.0", () => {
+      server.removeListener("error", reject)
+      resolve()
+    })
+  })
+  const address = server.address()
+  return {
+    port: typeof address === "object" && address !== null ? address.port : opts.port,
+    close: () => { server.close(); server.closeAllConnections?.() },
+  }
+}
+
+export const serve = async (opts: ServeOptions): Promise<Served> =>
+  typeof (globalThis as { Bun?: unknown }).Bun !== "undefined" ? serveBun(opts) : serveNode(opts)

package/src/hosts/cmgenTool.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, newestForPlatform, semverNewer, type ManifestFile, type ManifestVersion } from "./releases"
+import { downloadReleaseArchive, fetchReleaseProduct, macPlatformKey, newestForPlatform, semverNewer, type ManifestFile, type ManifestVersion } from "./releases"
 import { CliError, note } from "../cli"
 
 /*
@@ -11,9 +11,9 @@ import { CliError, note } from "../cli"
  *
  * The binary is NOT shipped with the CLI (most projects never bake an environment). It downloads on
  * first use from the same S3 release bucket as the desktop renderer and matc (product "cmgen" in
- * releases/versions.json — published by scripts/release/release-windows.ps1 from the desktop
- * build's in-tree filament host tools, so the KTX it writes always matches the engine the hosts
- * ship). Cache: ~/.lecodes/cmgen/cmgen-<version>/. LECODES_CMGEN overrides resolution entirely
+ * releases/versions.json — published by scripts/release/release-windows.ps1 / release-ubuntu.sh /
+ * release-macos.sh from the desktop build's in-tree filament host tools, so the KTX it writes always
+ * matches the engine the hosts ship). Cache: ~/.lecodes/cmgen/cmgen-<version>/. LECODES_CMGEN overrides resolution entirely
  * (local dev: hosts/desktop/build/creator-gl/filament/tools/cmgen/cmgen.exe).
  *
  * The CLI resolves it and hands the path to lecodes-assets through LECODES_CMGEN, so that package
@@ -29,11 +29,8 @@ const exeName = () => (process.platform === "win32" ? "cmgen.exe" : "cmgen")
 const platformKey = (): string => {
   if (process.platform === "win32") return "windows-x64"
   if (process.platform === "linux") return "linux-x64"
-  throw new CliError(
-    process.platform === "darwin"
-      ? "cmgen isn't published for macOS yet — build filament's host tools locally and set LECODES_CMGEN."
-      : `cmgen isn't published for ${process.platform}.`,
-  )
+  if (process.platform === "darwin") return macPlatformKey()
+  throw new CliError(`cmgen isn't published for ${process.platform}.`)
 }
 
 const cacheRoot = () => join(homedir(), ".lecodes", "cmgen")

package/src/hosts/desktopRenderer.ts

@@ -2,7 +2,7 @@ import { execFileSync, spawn, spawnSync } from "node:child_process"
 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"
+import { cachedArtifactSha, downloadReleaseArchive, fetchReleaseProduct, macPlatformKey, semverNewer, type ManifestVersion } from "./releases"
 import { CliError, note, warnErr } from "../cli"
 import { makeStackDemangler } from "../compile/nativeStack"
 
@@ -17,9 +17,10 @@ import { makeStackDemangler } from "../compile/nativeStack"
  * ~/.lecodes/renderer/desktop-<version>/. LECODES_DESKTOP_EXE overrides resolution entirely
  * (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)
- * as a notarized DMG under the same "desktop" product — so its version line has gaps: a release
+ * Platforms: windows-x64 + linux (the ubuntu build) + macos-arm64 / macos-x64. The macOS host is
+ * built and published separately (hosts/desktop's LeCodes Desktop.app, one per CPU, via
+ * scripts/release/release-macos.sh) as a notarized DMG under the same "desktop" product — so its
+ * version line has gaps: a release
  * may ship for Windows only. On darwin the cache therefore holds the newest published version
  * that HAS a macOS artifact (never below the pin), and an app installed in /Applications is only
  * the fallback for when the manifest can't be reached. The headless render contract
@@ -52,7 +53,7 @@ const platformKey = (renderer: DesktopRenderer = "gl"): string => {
     throw new CliError(`The Vulkan desktop host is Windows-only (this is ${process.platform}). Use the default renderer.`)
   }
   if (process.platform === "linux") return "ubuntu-linux-x64"
-  if (process.platform === "darwin") return process.arch === "arm64" ? "macos-arm64" : "macos-x64"
+  if (process.platform === "darwin") return macPlatformKey()
   throw new CliError(`The LeCodes Desktop host isn't available on ${process.platform}.`)
 }
 

package/src/hosts/liteRunner.ts

@@ -1,16 +1,17 @@
 import { spawn, type ChildProcess } from "node:child_process"
-import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs"
 import { createServer } from "node:net"
 import { dirname, join } from "node:path"
 import { createInterface } from "node:readline"
 import { CliError } from "../cli"
 import { startDevServer, type DevServer } from "../dev/devServer"
-import type { Manifest } from "../project/manifest"
+import type { WebRunner } from "../dev/webRunner"
+import { LECODES_DIR, type Manifest } from "../project/manifest"
 import { distRoot } from "./distRoot"
 import { peersDir } from "./peers"
 import type { DesktopPlan } from "./desktopScript"
 // (a relative source import, as desktopScript.ts does: lecodes-headless is an optional peer)
-import { findDumpTarget, parseTreeDump } from "../../../../runtime/headless/src/headless/paintDump"
+import { findDumpTarget, parseTreeDump, type DumpNode } from "../../../../runtime/headless/src/headless/paintDump"
 
 /*
  * `lecodes test --lite`: a flow scenario on WEB LITE, in a real browser. The scenario is the one
@@ -135,11 +136,15 @@ export type LiteSession = {
 }
 
 /** The project compiled and served with the page of Web Lite, and a browser to open it in. */
-export const startLiteSession = async (options: { root: string, manifest: Manifest | null, name: string, lite: string, entry?: string }): Promise<LiteSession> => {
+export const startLiteSession = async (options: { root: string, manifest: Manifest | null, name: string, lite?: string, web?: WebRunner, entry?: string }): Promise<LiteSession> => {
   const port = await freePort()
+  // The project's backend, when it has one: a database of the tests' own, emptied before every case.
+  const dbDir = join(options.root, LECODES_DIR, "test-db")
+  rmSync(dbDir, { recursive: true, force: true })
+  let ran = 0
   const server: DevServer = await startDevServer({
-    root: options.root, manifest: options.manifest, name: options.name, lite: options.lite,
-    origin: `http://127.0.0.1:${port}`, bind: "127.0.0.1", port, token: "test", entryOverride: options.entry,
+    root: options.root, manifest: options.manifest, name: options.name, lite: options.lite, web: options.web,
+    origin: `http://127.0.0.1:${port}`, bind: "127.0.0.1", port, token: "test", entryOverride: options.entry, dbDir,
   })
   const compiled = await server.recompile()
   if (!compiled.ok) { server.close(); throw new CliError(`Compile failed:\n${compiled.error}`) }
@@ -153,7 +158,13 @@ export const startLiteSession = async (options: { root: string, manifest: Manife
   }
 
   return {
-    run: (plan, runOptions) => runPlan(driver, `${server.liteUrl}?dev=..&test`, plan, runOptions),
+    // the web player (`web`): the same contract on its page — `window.lecodesTest` under `?test`
+    run: async (plan, runOptions) => {
+      if (ran++ > 0) await server.resetBackend()
+      return options.web
+        ? runPlan(driver, `${server.webUrl}player/?dev=../..&test`, plan, runOptions, "web")
+        : runPlan(driver, `${server.liteUrl}?dev=..&test`, plan, runOptions, "lite")
+    },
     async close() {
       await driver.close()
       server.close()
@@ -203,7 +214,7 @@ const FRAME = "new Promise((r) => requestAnimationFrame(() => requestAnimationFr
 
 const FILL_VALUE = `(f) => f.type === "email" ? "test@example.com" : f.type === "tel" ? "5550100" : f.inputMode === "numeric" || f.inputMode === "decimal" ? "1" : f.type === "date" ? "2026-01-01" : f.type === "time" ? "12:00" : "test"`
 
-const runPlan = async (driver: Driver, url: string, plan: DesktopPlan, options: LiteRunOptions): Promise<string> => {
+const runPlan = async (driver: Driver, url: string, plan: DesktopPlan, options: LiteRunOptions, page: "lite" | "web"): Promise<string> => {
   const output: string[] = []
   const seen: string[] = []
   const say = (line: string) => { output.push(line) }
@@ -294,6 +305,30 @@ const runPlan = async (driver: Driver, url: string, plan: DesktopPlan, options:
       case "type": await driver.keyboard("type", unwire(rest)); await frame(); return
       case "fill": {
         const value = rest === "" ? undefined : unwire(rest)
+        if (page === "web") {
+          // The player paints its fields: every empty one on show, in the tree's order, is tapped
+          // (a live <input> goes over it) and typed into.
+          const fields: DumpNode[] = []
+          const walk = (node: DumpNode) => {
+            if ((node.type === "input" || node.type === "textarea") && !node.value) fields.push(node)
+            for (const child of node.children ?? []) walk(child)
+            for (const p of node.pages ?? []) walk(p.node)
+          }
+          for (const root of parseTreeDump(await dump()).roots) walk(root.node)
+          for (const field of fields) {
+            const rect = await rectOf(field.id)
+            if (!rect || rect[2] === 0 || rect[3] === 0) continue   // not on show (a covered page)
+            const kind = String(field.paint?.type ?? "")
+            const text = value ?? (kind === "email" ? "test@example.com" : kind === "tel" || kind === "phone" ? "5550100" : kind === "number" || kind === "decimal" ? "1" : "test")
+            await driver.mouse("move", rect[0] + rect[2] / 2, rect[1] + rect[3] / 2)
+            await driver.mouse("down")
+            await driver.mouse("up")
+            await frame()
+            await driver.keyboard("type", text)
+          }
+          await frame()
+          return
+        }
         // every empty field on show, in the tree's order: what the native hosts fill
         const count = await driver.evaluate<number>(`(() => {
           window.__lecodesFill = [...document.querySelectorAll("${ON_SHOW} input.lc, ${ON_SHOW} textarea.lc")].filter((f) => f.value === "")
@@ -310,6 +345,14 @@ const runPlan = async (driver: Driver, url: string, plan: DesktopPlan, options:
       case "scroll": {
         const by = Number(args[0])
         const name = typeof args[1] === "string" ? args[1] : null
+        if (page === "web") {
+          // the player scrolls what is under the pointer: the wheel over the named node, or the middle of the page
+          const point = name === null ? [options.width / 2, options.height / 2] as [number, number] : (await pointOf(args, 1)).point
+          await driver.mouse("move", point[0], point[1])
+          await driver.mouse("wheel", 0, by)
+          await frame()
+          return
+        }
         const target = name === null
           ? `document.querySelector("${ON_SHOW} .lc-scrollable, ${ON_SHOW} .lc-vlist")`
           : `document.querySelector('[data-node="${(await nodeOf(name)).id}"]')`
@@ -355,7 +398,7 @@ const runPlan = async (driver: Driver, url: string, plan: DesktopPlan, options:
         return
       }
       default:
-        throw new Error(`"${op}" is not available on Web Lite (it has no 3D scene, no gamepad)`)
+        throw new Error(`"${op}" is not available in a browser run (no inspection camera, no gamepad)`)
     }
   }
 

package/src/hosts/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, newestForPlatform, semverNewer, type ManifestFile, type ManifestVersion } from "./releases"
+import { downloadReleaseArchive, fetchReleaseProduct, macPlatformKey, newestForPlatform, semverNewer, type ManifestFile, type ManifestVersion } from "./releases"
 import { CliError, note } from "../cli"
 
 /*
@@ -23,14 +23,9 @@ import { CliError, note } from "../cli"
  * 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
- * (filament's host tools build in-tree there). macOS has no such tree — release-macos.sh builds the
- * app from the vendored xcframeworks — so its matc comes from creator-gl's own host-tool build
- * (`out/cmake-release/filament/tools/matc`), which is the same filament tree those xcframeworks are
- * compiled from. Same guarantee, different source; see scripts/release/release-macos.sh.
- *
- * macos-x64 is deliberately absent: the host tools are built for the machine doing the release, and
- * only Apple Silicon is built today (release-macos.sh skips Intel for the same reason).
+ * Platforms: windows-x64, linux-x64, macos-arm64, macos-x64. matc rides the DESKTOP build on every
+ * OS (filament's host tools build in-tree there): on the Mac, the two trees of
+ * hosts/desktop/build-macos.sh — see scripts/release/release-macos.sh.
  */
 
 const matcName = () => (process.platform === "win32" ? "matc.exe" : "matc")
@@ -38,19 +33,7 @@ const matcName = () => (process.platform === "win32" ? "matc.exe" : "matc")
 const platformKey = (): string => {
   if (process.platform === "win32") return "windows-x64"
   if (process.platform === "linux") return "linux-x64"
-  if (process.platform === "darwin") {
-    // Intel Macs have no published matc (see the platform note above). Rosetta would run an
-    // arm64 binary anyway, but publishing a key we never build is how a download turns into a
-    // corrupt-archive error instead of a readable one.
-    if (process.arch !== "arm64") {
-      throw new CliError(
-        "matc isn't published for Intel macOS — set LECODES_MATC to a locally built matc " +
-        "(creator-gl/out/cmake-release/filament/tools/matc), or push the project once so shaders " +
-        "compile on the server.",
-      )
-    }
-    return "macos-arm64"
-  }
+  if (process.platform === "darwin") return macPlatformKey()
   throw new CliError(`matc isn't published for ${process.platform}.`)
 }
 

package/src/hosts/packageManager.ts

@@ -0,0 +1,45 @@
+import { spawnSync } from "node:child_process"
+import { homedir } from "node:os"
+import { join, resolve, sep } from "node:path"
+import { fileURLToPath } from "node:url"
+
+/*
+ * ONE answer to "which package manager installs things for this CLI": the one the CLI itself was
+ * installed with. A CLI under bun's global dir (`bun install -g lecodes-cli`) installs its peers and
+ * updates itself with bun; any other install goes through npm. Mixing them is the failure this
+ * removes: `npm install -g lecodes-cli@latest` beside a bun-installed CLI puts a SECOND copy in npm's
+ * prefix and leaves the `lecodes` on PATH as old as it was.
+ */
+export type PackageManager = "npm" | "bun"
+
+const onPath = (cmd: string): boolean => {
+  try { return spawnSync(cmd, ["--version"], { stdio: "ignore", shell: process.platform === "win32" }).status === 0 } catch { return false }
+}
+
+/** Bun's global install dir (`BUN_INSTALL` moves it). */
+const bunGlobalDir = (): string => join(process.env.BUN_INSTALL ? resolve(process.env.BUN_INSTALL) : join(homedir(), ".bun"), "install", "global")
+
+/** The manager that owns the install this file runs from. */
+export const ownManager = (file = fileURLToPath(import.meta.url)): PackageManager => {
+  const norm = (p: string) => process.platform === "win32" ? p.toLowerCase() : p
+  return norm(resolve(file)).startsWith(norm(bunGlobalDir()) + sep) ? "bun" : "npm"
+}
+
+/** The manager to install with: the CLI's own, else whichever of the two is on PATH; null = neither. */
+export const pickManager = (): PackageManager | null => {
+  const own = ownManager()
+  const other = own === "npm" ? "bun" : "npm"
+  return onPath(own) ? own : onPath(other) ? other : null
+}
+
+/** `<tool> <argv>` that installs `specs` into the directory `dir` (a private prefix with a package.json). */
+export const installIntoArgv = (tool: PackageManager, dir: string, specs: string[]): string[] =>
+  tool === "npm" ? ["install", "--prefix", dir, "--no-audit", "--no-fund", "--loglevel=error", ...specs] : ["add", "--cwd", dir, ...specs]
+
+/** `<tool> <argv>` that installs `specs` globally. */
+export const installGlobalArgv = (tool: PackageManager, specs: string[]): string[] =>
+  tool === "npm" ? ["install", "-g", ...specs] : ["add", "-g", ...specs]
+
+/** The same, as a line a person can run. */
+export const commandLine = (tool: PackageManager, argv: string[]): string =>
+  `${tool} ${argv.map((a) => /\s/.test(a) ? `"${a}"` : a).join(" ")}`