lecodes-cli 1.0.0 → 2.0.0

package/src/dev/devServer.ts

@@ -12,6 +12,7 @@ import { renderDevScreen, renderPrelude } from "./clientTemplates"
 import { upgradeWebSocket, type WsConnection } from "./wsServer"
 import { toKey } from "../project/paths"
 import { makeStackDemangler } from "../compile/nativeStack"
+import type { WebRunner } from "./webRunner"
 
 /*
  * The `lecodes dev` LAN server: serves the project to devices and hot-reloads it on change.
@@ -24,9 +25,12 @@ 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
+ *   GET /t/<tok>/web/[file]      the page of `dev --web` (lecodes-web-frame's dist-page): the app
+ *                                in a device, the buttons, the console — around an <iframe> of…
+ *   GET /t/<tok>/web/player/[file]  …the web player (lecodes-web-player's dist), opened as
+ *                                player/?dev=../.. — it loads bundle.js?t=web, the bundle WITHOUT
+ *                                the native prelude; the player owns reload (ws / version
+ *                                polling) and the log backchannel. A phone is sent here at once
  *
  * 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).
@@ -44,8 +48,9 @@ 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
+  /** What is served under /web/ (src/dev/webRunner.ts): the player, and the page around it; absent =
+   *  no browser route. */
+  web?: WebRunner | null
   /** Diagnostics (compile errors, device logs); defaults to stderr-style silence-safe noop. */
   log?: (msg: string) => void
 }
@@ -89,6 +94,32 @@ const sendText = (res: ServerResponse, status: number, type: string, body: strin
   res.end(body)
 }
 
+/** A working-tree file with byte-range support. AVPlayer (the iOS host's video / audio players)
+ *  opens an HTTP source with `Range: bytes=0-1` and fails the item with -11850 "The server is not
+ *  correctly configured" when the answer is a plain 200, so an asset route must answer ranges. */
+const sendFile = (req: IncomingMessage, res: ServerResponse, abs: string, type: string) => {
+  const size = statSync(abs).size
+  const headers = { "content-type": type, "cache-control": "no-store", "accept-ranges": "bytes" }
+  const m = /^bytes=(\d*)-(\d*)$/.exec(req.headers.range ?? "")
+  if (m && (m[1] || m[2])) {
+    // bytes=a-b, bytes=a- (to the end), bytes=-n (the last n bytes)
+    const start = m[1] ? Number(m[1]) : Math.max(0, size - Number(m[2]))
+    const end = m[1] && m[2] ? Math.min(Number(m[2]), size - 1) : size - 1
+    if (start >= size || start > end) {
+      res.writeHead(416, { ...headers, "content-range": `bytes */${size}` })
+      res.end()
+      return
+    }
+    res.writeHead(206, { ...headers, "content-range": `bytes ${start}-${end}/${size}`, "content-length": end - start + 1 })
+    if (req.method === "HEAD") return void res.end()
+    createReadStream(abs, { start, end }).pipe(res)
+    return
+  }
+  res.writeHead(200, { ...headers, "content-length": size })
+  if (req.method === "HEAD") return void res.end()
+  createReadStream(abs).pipe(res)
+}
+
 const sendJson = (res: ServerResponse, status: number, body: unknown) =>
   sendText(res, status, "application/json", JSON.stringify(body))
 
@@ -138,7 +169,7 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
         const ambiguous = ambiguousEntryWarning(entries)
         if (ambiguous) warnings.push(ambiguous)
       }
-      const js = await compileProject({ entries, name, publicUrl: origin, entryOverride, header: true, fontsHeader, iconsHeader })
+      const js = await compileProject({ entries, name, publicUrl: origin, entryOverride, header: true, fontsHeader, iconsHeader, onWarning: (w) => warnings.push(w) })
       const changed = bundleJs === null || stripVolatile(js) !== stripVolatile(bundleJs)
       if (changed) {
         bundleJs = js
@@ -195,14 +226,30 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
     const t = url.searchParams.get("t")
     return t === "poll" ? "poll" : t === "web" ? "web" : "ws"
   }
-  const withPrelude = (js: string, url: URL, v: number, forced?: "poll") => {
+  // The prelude talks back to the origin THIS request came through (the Host header): a phone on
+  // `adb reverse` reached us as 127.0.0.1:<port> and can't see the LAN address the QR carries.
+  const withPrelude = (js: string, url: URL, v: number, reqOrigin: string, forced?: "poll") => {
     const transport = forced ?? transportOf(url)
-    return transport === "web" ? js : js + "\n" + renderPrelude({ origin, base, transport, v })
+    return transport === "web" ? js : js + "\n" + renderPrelude({ origin: reqOrigin, base, transport, v })
+  }
+  const web = options.web ?? null
+  /** A file of a built folder; the entry files revalidate — a CLI update swaps them under the same
+   *  url — while what is under assets/ carries its hash in its name. */
+  const sendBuilt = (res: ServerResponse, dir: string, rel: string) => {
+    if (rel.split("/").some((seg) => seg === ".." || seg === "" || seg === ".")) return sendText(res, 400, "text/plain", "Bad path")
+    const abs = join(dir, ...rel.split("/"))
+    try {
+      if (!statSync(abs).isFile()) throw new Error("not a file")
+    } catch {
+      return sendText(res, 404, "text/plain", "Not found")
+    }
+    res.writeHead(200, { "content-type": contentType(rel), "cache-control": rel.startsWith("assets/") ? "max-age=31536000, immutable" : "no-store" })
+    createReadStream(abs).pipe(res)
   }
-  const webDir = options.webDir ?? null
 
   const handle = async (req: IncomingMessage, res: ServerResponse) => {
-    const url = new URL(req.url ?? "/", origin)
+    const reqOrigin = req.headers.host ? `http://${req.headers.host}` : origin
+    const url = new URL(req.url ?? "/", reqOrigin)
     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 }
@@ -210,40 +257,32 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
     const route = path.slice(base.length)
 
     if (route === "/dev.js") {
-      return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1))
+      return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1, reqOrigin))
     }
     // 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"))
+      return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1, reqOrigin, "poll"))
     }
     if (route === "/bundle.js") {
       if (bundleJs === null) return sendText(res, 503, "text/plain", "No successful compile yet — check the terminal.")
       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
+      return sendText(res, 200, "text/javascript", withPrelude(bundleJs, url, v, reqOrigin))
     }
-    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
+    // The browser: built folders with relative asset paths, so each needs its trailing slash. The
+    // player is told the server it runs the project of (`dev`: this one, two folders up).
+    if (route === "/web" || route.startsWith("/web/")) {
+      if (!web) return sendText(res, 404, "text/plain", "No web player vendored with this CLI (lecodes-web-player's dist).")
+      const redirect = (to: string) => { res.writeHead(302, { location: to }); res.end() }
+      const query = (extra?: [string, string]) => { if (extra) url.searchParams.set(...extra); const q = url.searchParams.toString(); return q ? `?${q}` : "" }
+      const rel = route.slice("/web".length)
+      if (rel === "/player" || (rel === "/player/" && !url.searchParams.has("dev"))) return redirect(`${base}/web/player/${query(["dev", "../.."])}`)
+      if (rel.startsWith("/player/")) return sendBuilt(res, web.player, rel === "/player/" ? "index.html" : rel.slice("/player/".length))
+      // no page around the player in this CLI: the player alone
+      if (!web.page) return redirect(`${base}/web/player/${query(["dev", "../.."])}`)
+      if (rel === "") return redirect(`${base}/web/${query()}`)
+      return sendBuilt(res, web.page, rel === "/" ? "index.html" : rel.slice(1))
     }
     if (route === "/version") {
       return sendJson(res, 200, { v })
@@ -274,9 +313,7 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
       }
       const abs = resolveLocalPath(root, key)
       if (!abs || !statSync(abs).isFile()) return sendText(res, 404, "text/plain", "Not found")
-      res.writeHead(200, { "content-type": contentType(key), "cache-control": "no-store" })
-      createReadStream(abs).pipe(res)
-      return
+      return sendFile(req, res, abs, contentType(key))
     }
     return sendText(res, 404, "text/plain", "Not found")
   }
@@ -325,7 +362,7 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
 
   return {
     url: `${origin}${base}/dev.js`,
-    webUrl: webDir ? `${origin}${base}/web/` : null,
+    webUrl: web ? `${origin}${base}/web/` : null,
     base,
     port: boundPort,
     v: () => v,

package/src/dev/iosDev.ts

@@ -0,0 +1,180 @@
+import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { spawnSync } from "node:child_process"
+import { CliError, note, warnErr } from "../cli"
+
+/*
+ * `lecodes dev --ios` — open the dev URL in the LeCodes app on a simulator or a plugged-in iPhone,
+ * through Xcode's tools (`xcrun simctl` for a simulator, `xcrun devicectl` for a device). The twin of
+ * dev/androidDev.ts, on a Mac only.
+ *
+ * The url reaches the app as a LAUNCH ARGUMENT (`--lecodes-url <url>`, read by LeCodesViewController
+ * and seeded as the launch URL before the launcher boots — hosts/apple/lecodes): a simulator has no
+ * universal links (no AASA), and `simctl openurl` on an http url opens Safari. A simulator shares the
+ * Mac's network, so it gets the 127.0.0.1 url (no Wi-Fi involved, like adb reverse); a device gets the
+ * LAN url the QR shows — there is no reverse tunnel over USB for iPhones.
+ *
+ * Like Android, every exit path terminates the app: a device run has no frame cap, and a 3D scene
+ * left rendering is a sustained GPU load on a charging phone.
+ */
+
+export const DEFAULT_IOS_BUNDLE = "com.letary.lecodes"
+
+export type IosDevOptions = {
+  /** The url for a simulator (127.0.0.1) and the one for a device (the LAN address). */
+  simulatorUrl: string
+  deviceUrl: string
+  /** A simulator's or a device's udid (or a simulator's name); omitted = the booted simulator, else the paired device. */
+  udid?: string
+  /** A built LeCodesApp.app to install first. */
+  app?: string
+  bundleId?: string
+}
+
+export type IosDevSession = {
+  kind: "simulator" | "device"
+  udid: string
+  name: string
+  bundleId: string
+  /** `simctl io screenshot` → the file; false on a device (no screenshot channel). */
+  screenshot: (file: string) => boolean
+  /** Terminate the app. Idempotent. */
+  stop: () => void
+  /** Crash reports of the app written since the launch (the simulator's, on this Mac). */
+  crashLines: () => string[]
+}
+
+const run = (args: string[]): { ok: boolean, out: string } => {
+  const r = spawnSync("xcrun", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 })
+  const out = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim()
+  return { ok: r.status === 0, out }
+}
+
+type Simulator = { udid: string, name: string, state: string, runtime: string }
+type Device = { udid: string, name: string, model: string, state: string }
+
+/** The simulators (`simctl list devices`), every runtime. */
+export const listSimulators = (): Simulator[] => {
+  const { ok, out } = run(["simctl", "list", "devices", "--json"])
+  if (!ok) return []
+  try {
+    const json = JSON.parse(out) as { devices: Record<string, { udid: string, name: string, state: string, isAvailable?: boolean }[]> }
+    const all: Simulator[] = []
+    for (const [runtime, list] of Object.entries(json.devices)) {
+      for (const d of list) if (d.isAvailable !== false) all.push({ udid: d.udid, name: d.name, state: d.state, runtime: runtime.split(".").pop() ?? runtime })
+    }
+    return all
+  } catch { return [] }
+}
+
+/** The paired physical devices (`devicectl list devices`). */
+export const listDevices = (): Device[] => {
+  const tmp = join(process.env.TMPDIR ?? "/tmp", `lecodes-devicectl-${process.pid}.json`)
+  const { ok } = run(["devicectl", "list", "devices", "--json-output", tmp])
+  if (!ok || !existsSync(tmp)) return []
+  try {
+    const json = JSON.parse(readFileSync(tmp, "utf8")) as { result?: { devices?: { identifier: string, deviceProperties?: { name?: string }, hardwareProperties?: { marketingName?: string }, connectionProperties?: { pairingState?: string, tunnelState?: string } }[] } }
+    return (json.result?.devices ?? []).map((d) => ({
+      udid: d.identifier,
+      name: d.deviceProperties?.name ?? d.identifier,
+      model: d.hardwareProperties?.marketingName ?? "",
+      state: d.connectionProperties?.tunnelState ?? d.connectionProperties?.pairingState ?? "unknown",
+    }))
+  } catch { return [] } finally { try { unlinkSync(tmp) } catch { /* gone */ } }
+}
+
+const pickTarget = (udid: string | undefined): { kind: "simulator" | "device", udid: string, name: string } => {
+  if (process.platform !== "darwin") throw new CliError("--ios needs a Mac with Xcode (xcrun simctl / devicectl).")
+  const sims = listSimulators()
+  if (udid) {
+    const sim = sims.find((s) => s.udid === udid || s.name === udid)
+    if (sim) return { kind: "simulator", udid: sim.udid, name: `${sim.name} (${sim.runtime})` }
+    const dev = listDevices().find((d) => d.udid === udid || d.name === udid)
+    if (dev) return { kind: "device", udid: dev.udid, name: `${dev.name}${dev.model ? ` (${dev.model})` : ""}` }
+    throw new CliError(`No simulator or device "${udid}" — simulators: ${sims.map((s) => `${s.name} [${s.udid}]`).join(", ") || "none"}.`)
+  }
+  const booted = sims.filter((s) => s.state === "Booted")
+  if (booted.length === 1) return { kind: "simulator", udid: booted[0].udid, name: `${booted[0].name} (${booted[0].runtime})` }
+  if (booted.length > 1) throw new CliError(`Several booted simulators: ${booted.map((s) => `${s.name} [${s.udid}]`).join(", ")} — pick one with --udid <id|name>.`)
+  const devices = listDevices()
+  if (devices.length === 1) return { kind: "device", udid: devices[0].udid, name: `${devices[0].name}${devices[0].model ? ` (${devices[0].model})` : ""}` }
+  if (devices.length > 1) throw new CliError(`Several devices: ${devices.map((d) => `${d.name} [${d.udid}]`).join(", ")} — pick one with --udid <id|name>.`)
+  throw new CliError("No booted simulator and no paired iPhone: boot one in Simulator.app (or `xcrun simctl boot \"iPhone 17\"`), or plug a phone in and trust this Mac.")
+}
+
+const simulatorHasApp = (udid: string, bundleId: string): boolean => run(["simctl", "get_app_container", udid, bundleId]).ok
+
+const deviceHasApp = (udid: string, bundleId: string): boolean => {
+  const tmp = join(process.env.TMPDIR ?? "/tmp", `lecodes-devicectl-apps-${process.pid}.json`)
+  const { ok } = run(["devicectl", "device", "info", "apps", "--device", udid, "--json-output", tmp])
+  if (!ok || !existsSync(tmp)) return false
+  try {
+    const json = JSON.parse(readFileSync(tmp, "utf8")) as { result?: { apps?: { bundleIdentifier?: string }[] } }
+    return (json.result?.apps ?? []).some((a) => a.bundleIdentifier === bundleId)
+  } catch { return false } finally { try { unlinkSync(tmp) } catch { /* gone */ } }
+}
+
+/** Install (optional), launch the app on the dev url. Returns the session handle. */
+export const launchOnIos = (opts: IosDevOptions): IosDevSession => {
+  const target = pickTarget(opts.udid)
+  const bundleId = opts.bundleId ?? process.env.LECODES_IOS_BUNDLE ?? DEFAULT_IOS_BUNDLE
+  const launchedAt = Date.now()
+
+  if (opts.app) {
+    if (!existsSync(opts.app)) throw new CliError(`--app: ${opts.app} does not exist.`)
+    note(`Installing ${opts.app} on ${target.name}…`)
+    const r = target.kind === "simulator"
+      ? run(["simctl", "install", target.udid, opts.app])
+      : run(["devicectl", "device", "install", "app", "--device", target.udid, opts.app])
+    if (!r.ok) throw new CliError(`install failed: ${r.out}`)
+  }
+  const installed = target.kind === "simulator" ? simulatorHasApp(target.udid, bundleId) : deviceHasApp(target.udid, bundleId)
+  if (!installed) {
+    throw new CliError(`${bundleId} is not installed on ${target.name} — pass --app <LeCodesApp.app> (hosts/apple/app: xcodebuild -scheme LeCodesApp -destination 'generic/platform=iOS Simulator' build → DerivedData/…/LeCodesApp.app).`)
+  }
+
+  const url = target.kind === "simulator" ? opts.simulatorUrl : opts.deviceUrl
+  let pid: string | null = null
+  if (target.kind === "simulator") {
+    run(["simctl", "terminate", target.udid, bundleId])
+    const start = run(["simctl", "launch", target.udid, bundleId, "--lecodes-url", url])
+    if (!start.ok) throw new CliError(`Could not launch ${bundleId} on ${target.name}: ${start.out}`)
+    pid = /:\s*(\d+)\s*$/.exec(start.out)?.[1] ?? null
+  } else {
+    const tmp = join(process.env.TMPDIR ?? "/tmp", `lecodes-devicectl-launch-${process.pid}.json`)
+    const start = run(["devicectl", "device", "process", "launch", "--device", target.udid, "--terminate-existing", "--json-output", tmp, bundleId, "--lecodes-url", url])
+    if (!start.ok) throw new CliError(`Could not launch ${bundleId} on ${target.name}: ${start.out}`)
+    try {
+      const json = JSON.parse(readFileSync(tmp, "utf8")) as { result?: { process?: { processIdentifier?: number } } }
+      pid = json.result?.process?.processIdentifier?.toString() ?? null
+    } catch { pid = null } finally { try { unlinkSync(tmp) } catch { /* gone */ } }
+    if (!pid) warnErr("devicectl reported no pid — Ctrl+C will not terminate the app on the phone.")
+  }
+
+  let stopped = false
+  return {
+    kind: target.kind, udid: target.udid, name: target.name, bundleId,
+    screenshot: (file: string) => {
+      if (target.kind !== "simulator") return false
+      return run(["simctl", "io", target.udid, "screenshot", file]).ok
+    },
+    stop: () => {
+      if (stopped) return
+      stopped = true
+      if (target.kind === "simulator") run(["simctl", "terminate", target.udid, bundleId])
+      else if (pid) run(["devicectl", "device", "process", "terminate", "--device", target.udid, "--pid", pid])
+    },
+    crashLines: () => {
+      // A simulator app's crash lands in this Mac's DiagnosticReports as <AppName>-<date>.ips.
+      if (target.kind !== "simulator") return []
+      const dir = join(homedir(), "Library", "Logs", "DiagnosticReports")
+      if (!existsSync(dir)) return []
+      const appName = bundleId.split(".").pop() ?? ""
+      return readdirSync(dir)
+        .filter((f) => f.endsWith(".ips") && (f.startsWith("LeCodes") || (appName && f.toLowerCase().startsWith(appName.toLowerCase()))))
+        .filter((f) => statSync(join(dir, f)).mtimeMs >= launchedAt)
+        .map((f) => join(dir, f))
+    },
+  }
+}

package/src/dev/webRunner.ts

@@ -1,22 +1,90 @@
-import { existsSync } from "node:fs"
+import { spawnSync } from "node:child_process"
+import { existsSync, readdirSync, statSync } from "node:fs"
 import { createRequire } from "node:module"
 import { dirname, join } from "node:path"
 import { distRoot } from "../hosts/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/).
+ * What `lecodes dev --web` serves to a browser, two built folders:
+ *   player   the web player (lecodes-web-player's dist: index.html + player.js + assets/ — the
+ *            runtime module, the archives, the plugins' web halves): the app, filling its window
+ *   page     the page around it (lecodes-web-frame's dist-page: the app in a device, the buttons,
+ *            the console), which holds the player in an <iframe>; absent = the player alone
+ *
+ * Each comes in one of two shapes:
+ *   - its package's own build, in a CHECKOUT of the core (the package has its sources beside it):
+ *     built here when it is older than what it is built from — a stale build is yesterday's host
+ *     under today's SDK, and it fails in ways that name nothing;
+ *   - vendored next to the CLI as runtime/web and runtime/web-page (scripts/vendor-runtime.ts —
+ *     the npm package and the standalone binary).
+ * `null` = no player available (the dev server then serves everything but /web/).
  */
-export const resolveWebRunnerDir = (): string | null => {
-  const candidates = [join(distRoot, "runtime", "web")]
+export type WebRunner = { player: string, page: string | null }
+
+type Built = {
+  /** The package, as npm names it. */
+  pkg: string
+  /** Its build, a folder of the package. */
+  dist: string
+  /** The file a build has. */
+  entry: string
+  /** The folder it is vendored as, beside the CLI. */
+  vendored: string
+  /** What it is built from, relative to the repo. */
+  sources: string[]
+  /** The arguments of the `vite build` that makes it. */
+  build: string[]
+}
+
+const PLAYER: Built = {
+  pkg: "lecodes-web-player", dist: "dist", entry: "player.js", vendored: "web", build: [],
+  sources: ["hosts/web-player/src", "hosts/web-player/build", "hosts/web-player/index.html", "hosts/web-host/src", "renderers/web-canvas/src", "renderers/web-shared/src", "runtime/web/src", "runtime/web/native/dist", "hosts/plugins/plugins"],
+}
+const PAGE: Built = {
+  // (the package's own build is the element, a library; the page is another)
+  pkg: "lecodes-web-frame", dist: "dist-page", entry: "page.js", vendored: "web-page", build: ["-c", "vite.page.config.ts"],
+  sources: ["hosts/web-frame/src", "hosts/web-frame/page", "hosts/web-player/src/protocol.ts"],
+}
+
+export const resolveWebRunner = (log: (message: string) => void = () => {}): WebRunner | null => {
+  const player = resolve(PLAYER, log)
+  return player ? { player, page: resolve(PAGE, log) } : null
+}
+
+const resolve = (built: Built, log: (message: string) => void): string | null => {
+  const has = (dir: string) => existsSync(join(dir, "index.html")) && existsSync(join(dir, built.entry))
+  const checkout = checkoutOf(built.pkg)
+  if (checkout) {
+    const dist = join(checkout, built.dist)
+    const repo = join(checkout, "..", "..")
+    if (!has(dist) || newest(built.sources.map((s) => join(repo, s))) > statSync(join(dist, built.entry)).mtimeMs) {
+      log(`Building ${built.pkg} (its sources are newer than its build)…`)
+      const done = spawnSync("bunx", ["vite", "build", ...built.build], { cwd: checkout, stdio: "pipe", encoding: "utf8", shell: process.platform === "win32" })
+      if (done.status !== 0) log(`${built.pkg} did not build — the browser gets the build that is there:\n${done.stderr || done.stdout}`)
+    }
+    if (has(dist)) return dist
+  }
+  const vendored = join(distRoot, "runtime", built.vendored)
+  return has(vendored) ? vendored : null
+}
+
+/** A package when it is a checkout (its sources are there), else null. */
+const checkoutOf = (pkg: string): string | null => {
   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
+    const dir = dirname(createRequire(import.meta.url).resolve(`${pkg}/package.json`))
+    return existsSync(join(dir, "vite.config.ts")) && existsSync(join(dir, "src")) ? dir : null
+  } catch { return null }
+}
+
+/** The latest modification under the paths (0 when none exists). */
+const newest = (paths: string[]): number => {
+  let latest = 0
+  const walk = (path: string) => {
+    let stat
+    try { stat = statSync(path) } catch { return }
+    if (!stat.isDirectory()) { latest = Math.max(latest, stat.mtimeMs); return }
+    for (const name of readdirSync(path)) if (name !== "node_modules" && name !== "ios" && name !== "android") walk(join(path, name))
+  }
+  for (const path of paths) walk(path)
+  return latest
 }

package/src/hosts/cmgenTool.ts

@@ -14,7 +14,7 @@ import { CliError, note } from "../cli"
  * 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
- * (local dev: packages/desktop/build/creator-gl/filament/tools/cmgen/cmgen.exe).
+ * (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
  * stays network-free and still works standalone against a local build.