lecodes-cli 2.0.2 → 2.0.4

package/src/commands/dev.ts

@@ -1,11 +1,11 @@
-import { existsSync, mkdirSync, readFileSync, watch, writeFileSync, type FSWatcher } from "node:fs"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { randomBytes } from "node:crypto"
 import { networkInterfaces } from "node:os"
 import { basename, join } from "node:path"
 import { findProjectRoot, readManifest, LECODES_DIR, type Manifest } from "../project/manifest"
-import { loadIgnore } from "../project/ignore"
 import { startDevServer } from "../dev/devServer"
 import { resolveWebRunner } from "../dev/webRunner"
+import { watchProject } from "../dev/watchProject"
 import { openBrowser } from "../platform/browserAuth"
 import { runDesktopDev } from "../hosts/desktopRenderer"
 import { androidCrashLines, launchOnAndroid, type AndroidDevSession } from "../dev/androidDev"
@@ -14,7 +14,6 @@ import { readAppConfigAt } from "./app/shared"
 import { resolveScale } from "./desktop"
 import { CliError, bool, c, defineCommand, log, note, num, str, warnErr } from "../cli"
 import { bundleFlags } from "./shared"
-import { toKey } from "../project/paths"
 
 /*
  * `lecodes dev` — run the project on a device straight from this machine, with hot reload.
@@ -54,12 +53,6 @@ import { toKey } from "../project/paths"
  */
 
 const DEFAULT_PORT = 4499
-const DEBOUNCE_MS = 120
-
-// Never trigger a recompile (mirrors scanLocal's skip lists + our own artifacts).
-const WATCH_SKIP_DIRS = new Set([".lecodes", ".git", "node_modules"])
-const WATCH_SKIP_FILES = new Set(["tsconfig.json", "jsconfig.json", ".gitignore", ".lecodesignore", ".DS_Store"])
-
 /*
  * The origin a phone on the same Wi-Fi can reach, best first.
  *
@@ -92,7 +85,7 @@ export const lanCandidates = (): { address: string, iface: string }[] => {
 }
 
 /** The per-project dev token, persisted so the QR/URL stays stable across runs. */
-const loadDevToken = (root: string): string => {
+export const loadDevToken = (root: string): string => {
   const path = join(root, LECODES_DIR, "dev.json")
   try {
     const token = (JSON.parse(readFileSync(path, "utf8")) as { token?: string }).token
@@ -195,45 +188,16 @@ export default defineCommand({
     }
 
     // ---- watcher: debounced whole-project recompile; a successful compile broadcasts the reload ----
-    const ignore = loadIgnore(root)
-    const shouldRecompile = (file: string | null): boolean => {
-      if (file === null) return true // event without a filename — assume project content
-      const parts = file.replace(/\\/g, "/").split("/")
-      if (parts.some((p) => WATCH_SKIP_DIRS.has(p))) return false
-      if (WATCH_SKIP_FILES.has(parts[parts.length - 1])) return false
-      try {
-        const key = toKey(file)
-        if (ignore(key, false)) return false
-      } catch { return false }
-      return true
-    }
-
-    const debug = process.env.LECODES_DEV_DEBUG === "1"
-    let timer: NodeJS.Timeout | null = null
-    const onChange = (file: string | null) => {
-      if (debug) note(`[watch] event: ${file ?? "(null)"} → ${shouldRecompile(file) ? "recompile" : "skip"}`)
-      if (!shouldRecompile(file)) return
-      if (timer) clearTimeout(timer)
-      timer = setTimeout(async () => {
-        timer = null
-        const result = await server.recompile()
-        if (!result.ok) {
-          warnErr(`Compile failed (devices keep the last good version):\n${result.error}`)
-        } else if (result.changed) {
-          const devices = server.clientCount()
-          note(`✓ v${result.v} → ${devices} device${devices === 1 ? "" : "s"}`)
-          for (const w of result.warnings) warnErr(w)
-        }
-      }, DEBOUNCE_MS)
-    }
-
-    let watcher: FSWatcher | null = null
-    try {
-      watcher = watch(root, { recursive: true }, (_type, file) => onChange(file))
-    } catch {
-      warnErr("fs.watch(recursive) unavailable on this platform — hot reload disabled (restart to pick up changes).")
-    }
-    watcher?.on("error", (e) => warnErr(`Watcher error — hot reload may have stopped (restart lecodes dev): ${e.message}`))
+    const watcher = watchProject(root, async () => {
+      const result = await server.recompile()
+      if (!result.ok) {
+        warnErr(`Compile failed (devices keep the last good version):\n${result.error}`)
+      } else if (result.changed) {
+        const devices = server.clientCount()
+        note(`✓ v${result.v} → ${devices} device${devices === 1 ? "" : "s"}`)
+        for (const w of result.warnings) warnErr(w)
+      }
+    }, { warn: warnErr, debug: process.env.LECODES_DEV_DEBUG === "1" ? note : undefined })
 
     // ---- banner ------------------------------------------------------------------------------------
     log("")
@@ -270,13 +234,13 @@ export default defineCommand({
       try {
         session = launchOnAndroid({ port, url: androidUrl, serial: flags.serial, apk: flags.apk, packageName: flags.package })
       } catch (e) {
-        server.close(); watcher?.close()
+        server.close(); watcher.close()
         throw e
       }
       note(`Android: ${session.serial} → ${androidUrl} (adb reverse; device logs stream here as [device:log])`)
       const finish = (code: number) => {
         session.stop()
-        server.close(); watcher?.close()
+        server.close(); watcher.close()
         process.exit(code)
       }
       process.on("SIGINT", () => { note("Stopping the app on the phone…"); finish(0) })
@@ -306,13 +270,13 @@ export default defineCommand({
       try {
         session = launchOnIos({ simulatorUrl: `http://127.0.0.1:${port}${path}`, deviceUrl, udid: flags.udid, app: flags.app, bundleId: flags.bundle })
       } catch (e) {
-        server.close(); watcher?.close()
+        server.close(); watcher.close()
         throw e
       }
       note(`iOS: ${session.name} → ${session.kind === "simulator" ? `http://127.0.0.1:${port}${path}` : deviceUrl} (device logs stream here as [device:log])`)
       const finish = (code: number) => {
         session.stop()
-        server.close(); watcher?.close()
+        server.close(); watcher.close()
         process.exit(code)
       }
       process.on("SIGINT", () => { note(`Stopping the app on ${session.name}…`); finish(0) })

package/src/commands/index.ts

@@ -26,6 +26,7 @@ import status from "./status"
 import test from "./test"
 import thumbs from "./thumbs"
 import update from "./update"
+import web from "./web"
 
 /*
  * THE command list. Adding a command = one file with a `defineCommand` default export + one line
@@ -35,6 +36,7 @@ export const commandGroups = (opts: { install: boolean }): Group[] => [
   { title: "Project", commands: [init, create, clone, link, status, diff, pull, push, login] },
   { title: "Run & test", commands: [
     dev,
+    web,
     compile,
     render,
     test,

package/src/commands/test.ts

@@ -7,6 +7,9 @@ import { buildBundle } from "./compile"
 import { findProjectRoot } from "../project/manifest"
 import { runDesktopRender } from "../hosts/desktopRenderer"
 import { evaluateDesktopRun, translateScenario } from "../hosts/desktopScript"
+import { startLiteSession, type LiteSession } from "../hosts/liteRunner"
+import { resolveLiteRunner } from "../dev/webRunner"
+import { readManifest, type Manifest } from "../project/manifest"
 import { CliError, bool, c, defineCommand, log, logErr, note, num, str, warnErr, type FlagValues } from "../cli"
 import { bundleFlags, bundleOptions } from "./shared"
 
@@ -32,6 +35,10 @@ import { bundleFlags, bundleOptions } from "./shared"
  * coordinates, expect.log + expect.paint checked, the semantic expects reported skipped). The
  * design-derived flows need `expect.screen` and `fill`, which the host can't answer, so they stay
  * headless-only. The viewport / timing and --desktop flags are `lecodes render`'s own groups.
+ *
+ * `--lite` runs them on WEB LITE in a browser (liteRunner.ts: headless Chromium, the page's own
+ * pointer and key events): the same steps, targets and expects, judged by the same rules as
+ * --desktop. The clock is the browser's — a step that expects a log line waits for it.
  */
 
 type DesignEdge = { from: string, to: string, label?: string, activator?: string }
@@ -149,6 +156,7 @@ const testFlags = {
   ...viewportFlags,
   ...bundleFlags,
   ...desktopRenderFlags,
+  lite: bool("run the file scenarios on Web Lite, in a browser (needs Playwright): the same steps, targets and expects; the clock is the browser's, so a step that expects a log line waits for it; design flows stay headless"),
   desktop: bool("run the file scenarios through the NATIVE host: the same steps, targets and expects as headless (expect.audio and the json output excepted); design flows stay headless. --frames / --fixed-dt as in render --desktop"),
 }
 // (`sim` comes with desktopRenderFlags: the file scenarios through the WINDOWLESS host — no GPU, no
@@ -169,6 +177,9 @@ export default defineCommand({
 const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
   // --sim is the native path on the windowless host: everything --desktop does, minus pixels.
   const sim = flags.sim
+  const lite = flags.lite
+  if (lite && (flags.desktop || sim)) throw new CliError("--lite is a host of its own — drop --desktop / --sim.")
+  if (lite && flags.flows) throw new CliError("--flows needs the headless renderer (design flows read expect.screen and fill inputs) — drop --lite.")
   const desktop = flags.desktop || sim
   if (desktop && flags.flows) throw new CliError(`--flows needs the headless renderer (design flows read expect.screen and fill inputs) — drop --${sim ? "sim" : "desktop"}.`)
   // --desktop: ONE renderer decision (host binary + the staged .filamat variant). The root is
@@ -177,14 +188,14 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
   try { desktopRoot = findProjectRoot(process.cwd()) } catch { desktopRoot = process.cwd() }
   const desktopRenderer = desktop ? resolveDesktopRenderer(desktopRoot, flags.renderer) : undefined
   const native = desktop ? await buildBundle(bundleOptions(flags), { localAssets: true, desktopRenderer }) : null
-  const headless = desktop ? null : await compileHeadlessBundle({ entry: flags.entry, publicUrl: flags["public-url"], remoteAssets: flags["remote-assets"], waitNetwork: flags["wait-network"] })
+  const headless = desktop || lite ? null : await compileHeadlessBundle({ entry: flags.entry, publicUrl: flags["public-url"], remoteAssets: flags["remote-assets"], waitNetwork: flags["wait-network"] })
   const warnings = headless?.warnings ?? []
   const useLocalAssets = headless?.useLocalAssets ?? false
   const js = headless?.js ?? ""
   let root: string
   if (headless) root = headless.root
   else { try { root = findProjectRoot(process.cwd()) } catch { root = process.cwd() } }
-  const renderer = desktop ? null : await requireRenderer()
+  const renderer = desktop || lite ? null : await requireRenderer()
   const nativeFrames = flags.frames || 60
   const nativeFixedDt = flags["fixed-dt"] ?? 16
   if (nativeFixedDt < 0 || nativeFixedDt > 1000) throw new CliError(`--fixed-dt wants a number of ms (0 = wall clock, max 1000), got "${nativeFixedDt}".`)
@@ -226,10 +237,10 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
   if (flowsOnly) cases.length = 0
   let skipped: SkippedFlow[] = []
   let entryScreen: string | null = null
-  if (desktop && wantFlows && existsSync(designMetaPath)) {
-    note("Design-derived flows skipped with --desktop (they read expect.screen and fill inputs; run `lecodes test` headless for them).")
+  if ((desktop || lite) && wantFlows && existsSync(designMetaPath)) {
+    note("Design-derived flows skipped with --desktop / --lite (they read expect.screen and fill inputs; run `lecodes test` headless for them).")
   }
-  if (!desktop && (wantFlows || flowsOnly) && existsSync(designMetaPath)) {
+  if (!desktop && !lite && (wantFlows || flowsOnly) && existsSync(designMetaPath)) {
     let meta: DesignMeta
     try {
       meta = JSON.parse(readFileSync(designMetaPath, "utf8")) as DesignMeta
@@ -286,7 +297,7 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
   const reportCase = (result: CaseResult): void => {
     const skippedCount = result.steps.reduce((n, s) => n + (s.skipped?.length ?? 0), 0)
     if (result.ok) {
-      out(`${c.green("✓")} ${result.name}${skippedCount > 0 ? c.dim(` (${skippedCount} semantic check${skippedCount === 1 ? "" : "s"} skipped on --desktop)`) : ""}`)
+      out(`${c.green("✓")} ${result.name}${skippedCount > 0 ? c.dim(` (${skippedCount} check${skippedCount === 1 ? "" : "s"} skipped on this host)`) : ""}`)
     } else {
       out(`${c.red("✗")} ${result.name}`)
       if (result.error) out(`    ${c.red(result.error)}`)
@@ -324,8 +335,45 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
     }
   }
 
+  // Web Lite: one compile, one browser; a page of its own per case.
+  let liteSession: LiteSession | null = null
+  if (lite) {
+    const page = resolveLiteRunner(note)
+    if (!page) throw new CliError("No Web Lite page found: this CLI has no runtime/web-lite (a monorepo checkout needs `bun run build` in hosts/web-lite).")
+    let manifest: Manifest | null = null
+    try { manifest = readManifest(root) } catch { /* a folder standing alone */ }
+    liteSession = await startLiteSession({ root, manifest, name: manifest?.name ?? "app", lite: page, entry: flags.entry })
+  }
+  const runLiteCase = async (kase: FlowCase): Promise<CaseResult> => {
+    const caseDir = resolve(artifactsRoot, slug(kase.name))
+    const plan = translateScenario(kase.steps, { outDir: caseDir, headroomFrames: 0 })
+    mkdirSync(caseDir, { recursive: true })
+    const output = await liteSession!.run(plan, {
+      width: flags.width || kase.width || projectViewport?.width || 390,
+      height: flags.height || kase.height || projectViewport?.height || 844,
+      onConsole,
+    })
+    const r = evaluateDesktopRun(plan, output, (path) => existsSync(path) ? readFileSync(path, "utf8") : null)
+    return {
+      name: kase.name, kind: kase.kind, ok: r.ok,
+      steps: r.steps.map((s) => ({ desc: s.desc, ok: s.ok, error: s.error, skipped: s.skipped.length > 0 ? s.skipped : undefined })),
+      error: !r.loaded ? "the page did not load the app" : r.ended ? undefined : "the page stopped before the script finished",
+      artifacts: [],
+    }
+  }
+
   for (const kase of cases) {
     let result: CaseResult
+    if (lite) {
+      try {
+        result = await runLiteCase(kase)
+      } catch (e) {
+        result = { name: kase.name, kind: kase.kind, ok: false, steps: [], error: e instanceof Error ? e.message : String(e), artifacts: [] }
+      }
+      results.push(result)
+      reportCase(result)
+      continue
+    }
     if (desktop) {
       try {
         result = await runNativeCase(kase)
@@ -397,6 +445,7 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
     }, null, 2) + "\n")
   }
 
+  await liteSession?.close()
   clearTimeout(killer)
   process.exit(failed > 0 ? 1 : 0)
 }

package/src/commands/update/index.ts

@@ -6,6 +6,7 @@ import pkg from "../../../package.json"
 import { CliError, bool, c, defineCommand, log, note, readFlags, type Command } from "../../cli"
 import { OPTIONAL_PEERS, peerSource, peerVersion } from "../../hosts/peers"
 import { installPeers } from "../../hosts/peerInstall"
+import { archiveSpec, archivedVersion } from "../../hosts/archives"
 import { updateDesktop } from "../../hosts/desktopRenderer"
 import { updateMatc } from "../../hosts/matcTool"
 import { refreshTypes } from "./types"
@@ -24,7 +25,8 @@ import app from "../app"
  *   6. cli       the npm installs — every installed optional peer (lecodes-headless, lecodes-design,
  *                lecodes-3d-editor, lecodes-assets, @napi-rs/canvas) and the CLI itself that is behind:
  *                peers in ~/.lecodes/peers (first-use installs, peerInstall.ts) are re-installed there
- *                — the renderer at THIS CLI's version, the rest at npm's latest in range; global ones
+ *                — the renderer at THIS CLI's version, an editor at the newest one out that this
+ *                CLI's peer range takes, the rest at npm's latest in range; global ones
  *                (`npm install -g`, the old way) via `npm install -g …@latest`; the CLI itself last
  *                (the standalone binary can't come from npm — it says so and does the peers only)
  *
@@ -173,9 +175,10 @@ export default defineCommand({
       for (const [name, probe] of OPTIONAL_PEERS) {
         const where = peerSource(name, probe)
         const installed = peerVersion(name, probe)
+        // an archived peer (the headless host, the editors) has no "latest" of a registry: the
+        // version this CLI installs is the one to have
         const latest = !installed ? null
-          : where === "prefix" && name === "lecodes-headless" ? pkg.version
-          : await npmLatest(name)
+          : await archivedVersion(name) ?? await npmLatest(name)
         rows.push({ name, installed, latest, where })
       }
       rows.push({ name: "lecodes-cli", installed: pkg.version, latest: await npmLatest("lecodes-cli"), where: "global" })
@@ -190,7 +193,7 @@ export default defineCommand({
       }
       if (behind.length === 0) return "ok"
       const prefixBehind = behind.filter((r) => r.where === "prefix")
-      const globalSpecs = behind.filter((r) => r.where !== "prefix").map((r) => r.name + "@latest")
+      const globalSpecs = await Promise.all(behind.filter((r) => r.where !== "prefix").map(async (r) => await archiveSpec(r.name) ?? r.name + "@latest"))
       if (flags.check) {
         return ["updated", behind.length + " behind — run: lecodes update" + (globalSpecs.length ? "  (global: npm install -g " + globalSpecs.join(" ") + ")" : "")]
       }
@@ -207,7 +210,7 @@ export default defineCommand({
         log("  " + c.dim("$") + " npm install -g " + toInstall.join(" "))
         const r = spawnSync("npm", ["install", "-g", ...toInstall], { stdio: "inherit", shell: true })
         if (r.status !== 0) throw new CliError("npm install -g exited with " + (r.status ?? "a signal"))
-        done.push(...toInstall.map((s) => s.replace("@latest", "")))
+        done.push(...behind.filter((r) => r.where !== "prefix" && (!STANDALONE || r.name !== "lecodes-cli")).map((r) => r.name))
       }
       if (done.length === 0) return ["skipped", "only the standalone CLI itself is behind — download the release"]
       const cliToo = done.includes("lecodes-cli")

package/src/commands/web.ts

@@ -0,0 +1,171 @@
+import { basename, relative } from "node:path"
+import { findProjectRoot, readManifest, type Manifest } from "../project/manifest"
+import { startDevServer } from "../dev/devServer"
+import { resolveLiteRunner } from "../dev/webRunner"
+import { watchProject } from "../dev/watchProject"
+import { openBrowser } from "../platform/browserAuth"
+import { CliError, bool, c, defineCommand, log, note, num, str, warnErr } from "../cli"
+import { buildWeb } from "../web/build"
+import { startPreview } from "../web/preview"
+import { bundleFlags } from "./shared"
+import { lanCandidates, loadDevToken } from "./dev"
+
+/*
+ * `lecodes web` — the project as a WEB PAGE (Web Lite: DOM and CSS, the browser's layout, text and
+ * scroll — docs/plans/web-lite-plan.md). Not the web player of `lecodes dev --web`, which runs
+ * the app on the runtime as wasm and paints it to a canvas: that one is how the app looks on a
+ * phone, this one is what a site ships.
+ *
+ *   dev      the page, served from this machine and reloaded on every save
+ *   build    a folder any static hosting serves (web/build.ts)
+ *   preview  serve a built folder, as a hosting would
+ *
+ * Fully local: no login, no le.codes backend.
+ */
+
+const DEFAULT_PORT = 4488
+const DEFAULT_OUT = "dist/web"
+
+const project = (): { root: string, manifest: Manifest | null, name: string } => {
+  let root: string
+  let manifest: Manifest | null
+  try {
+    root = findProjectRoot(process.cwd())
+    manifest = readManifest(root)
+  } catch {
+    root = process.cwd()
+    manifest = null
+  }
+  return { root, manifest, name: manifest?.name ?? basename(root) }
+}
+
+const litePage = (): string => {
+  const lite = resolveLiteRunner(note)
+  if (!lite) throw new CliError("No Web Lite page found: this CLI has no runtime/web-lite (a monorepo checkout needs `bun run build` in hosts/web-lite).")
+  return lite
+}
+
+const kb = (bytes: number): string => bytes < 1024 ? `${bytes} B` : bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1024 / 1024).toFixed(2)} MB`
+
+const dev = defineCommand({
+  name: "dev",
+  summary: "Open the project as a web page, reloaded on every save",
+  description: "Serves the project's bundle and assets with the page of Web Lite around them; a save recompiles and runs the app again, the page's console output and errors stream back here. The address's hash is the route the app is opened with (#/product/42 → app.launchUrl).",
+  flags: {
+    port: num("server port", { default: DEFAULT_PORT }),
+    entry: bundleFlags.entry,
+    "no-open": bool("don't open the browser"),
+  },
+  examples: ["lecodes web dev", "lecodes web dev --port 8080 --no-open"],
+  run: async ({ flags }) => {
+    const { root, manifest, name } = project()
+    const lite = litePage()
+
+    const port = flags.port || DEFAULT_PORT
+    // The page is opened on this machine; a phone on the same network reaches it by the LAN address.
+    const lan = lanCandidates()[0]?.address
+    const origin = `http://localhost:${port}`
+    const server = await startDevServer({
+      root, manifest, name, origin, port,
+      token: loadDevToken(root),
+      entryOverride: flags.entry,
+      lite,
+      log: note,
+    }).catch((e: unknown) => {
+      const msg = e instanceof Error ? e.message : String(e)
+      throw new CliError(msg.includes("EADDRINUSE") ? `Port ${port} is already in use — pass --port <n>.` : msg)
+    })
+
+    note("Compiling…")
+    const first = await server.recompile()
+    if (first.ok) for (const w of first.warnings) warnErr(w)
+    else warnErr(`Compile failed — fix it and save; the page loads once it compiles:\n${first.error}`)
+
+    const watcher = watchProject(root, async () => {
+      const result = await server.recompile()
+      if (!result.ok) warnErr(`Compile failed (the page keeps the last good version):\n${result.error}`)
+      else if (result.changed) {
+        note(`✓ v${result.v}`)
+        for (const w of result.warnings) warnErr(w)
+      }
+    }, { warn: warnErr, debug: process.env.LECODES_DEV_DEBUG === "1" ? note : undefined })
+
+    const url = server.liteUrl!
+    log("")
+    log(`${c.bold("LeCodes Web")} — ${name}`)
+    log("")
+    log(`In the browser:  ${c.bold(url)}`)
+    if (lan) note(`On this network: ${url.replace("http://localhost:", `http://${lan}:`)}`)
+    log("")
+    log(`Watching ${root} — save a file to reload. Ctrl+C to stop.`)
+
+    if (!flags["no-open"]) openBrowser(url)
+
+    process.on("SIGINT", () => {
+      watcher.close()
+      server.close()
+      process.exit(0)
+    })
+  },
+})
+
+const build = defineCommand({
+  name: "build",
+  summary: "Build the project into a folder any static hosting serves",
+  description: "Writes the page, the bundle, the page's own files and the assets the bundle names into one folder (dist/web). Every url in it is relative: the folder works at a domain's root and inside a folder of one.\n\napp.json `web` sets the page: `title`, `themeColor`, `lang`, and `urls` — \"hash\" (default: a route is `#/product/42`, which any hosting serves) or \"path\" (`/product/42` under `base`: the hosting has to answer every path with the page; a 404.html is written for the ones that do it that way).",
+  flags: {
+    out: str("the folder to write (cleaned first)", { alias: "o", value: "<dir>", default: DEFAULT_OUT }),
+    entry: bundleFlags.entry,
+    sourcemap: bool("inline the source map (errors name the app's own lines; the bundle grows by its sources)"),
+    "no-minify": bundleFlags["no-minify"],
+  },
+  examples: ["lecodes web build", "lecodes web build -o public"],
+  run: async ({ flags }) => {
+    const { root, manifest, name } = project()
+    const lite = litePage()
+    note("Building…")
+    const result = await buildWeb({
+      root, manifest, name, lite, out: flags.out, entry: flags.entry,
+      sourcemap: flags.sourcemap, minify: flags["no-minify"] ? false : undefined,
+    })
+    for (const w of result.warnings) warnErr(w)
+    const total = result.files.reduce((sum, f) => sum + f.bytes, 0)
+    const shown = relative(process.cwd(), result.out) || "."
+    log("")
+    for (const f of [...result.files].sort((a, b) => b.bytes - a.bytes).slice(0, 8)) log(`  ${kb(f.bytes).padStart(10)}  ${f.path}`)
+    if (result.files.length > 8) log(c.dim(`  …and ${result.files.length - 8} more`))
+    log("")
+    log(`${c.green("✓")} ${c.bold(shown)} — ${result.files.length} files, ${kb(total)}`)
+    note(`Look at it: lecodes web preview${flags.out === DEFAULT_OUT ? "" : ` ${flags.out}`}`)
+  },
+})
+
+const preview = defineCommand({
+  name: "preview",
+  summary: "Serve a built folder, as a static hosting would",
+  usage: "[dir]",
+  flags: {
+    port: num("server port", { default: DEFAULT_PORT + 1 }),
+    "no-open": bool("don't open the browser"),
+  },
+  examples: ["lecodes web preview", "lecodes web preview public --port 8080"],
+  run: async ({ args, flags }) => {
+    const dir = args[0] ?? DEFAULT_OUT
+    const server = await startPreview(dir, flags.port || DEFAULT_PORT + 1).catch((e: unknown) => {
+      const msg = e instanceof Error ? e.message : String(e)
+      throw new CliError(msg.includes("EADDRINUSE") ? `Port ${flags.port} is already in use — pass --port <n>.` : msg)
+    })
+    log(`${c.bold("LeCodes Web")} — ${dir}`)
+    log(`In the browser:  ${c.bold(server.url)}`)
+    log("Ctrl+C to stop.")
+    if (!flags["no-open"]) openBrowser(server.url)
+    process.on("SIGINT", () => { server.close(); process.exit(0) })
+  },
+})
+
+export default defineCommand({
+  name: "web",
+  summary: "The project as a web page (Web Lite): serve it with reload on save, build it for a hosting",
+  description: "Web Lite shows the app with the browser's own layout, text and scroll: what a site ships. UI apps for now — a project's 3D and 2D scenes are not shown yet.",
+  commands: [dev, build, preview],
+})

package/src/compile/fonts.ts

@@ -37,6 +37,9 @@ export type ProjectFontsOptions = {
   registry?: string
   /** Absolute-URL prefix of the compile (URL modes) — used for the header's entry-face URLs. */
   publicUrl?: string
+  /** The compile's urls are RELATIVE to the page that runs the bundle (a static web build): the
+   *  header's urls are written as they are, with no origin before them. */
+  relative?: boolean
 }
 
 export const applyProjectFonts = async (entries: CompileEntry[], opts: ProjectFontsOptions): Promise<string | undefined> => {
@@ -68,9 +71,9 @@ export const applyProjectFonts = async (entries: CompileEntry[], opts: ProjectFo
   if (faces.length === 0) return undefined
 
   return buildFontsHeaderValue(faces, (path) => {
-    if (!opts.publicUrl || !/^https?:/i.test(opts.publicUrl)) return null
+    if (!opts.relative && (!opts.publicUrl || !/^https?:/i.test(opts.publicUrl))) return null
     const fileSrc = byPath().get(path.replace(/^\//, ""))?.fileSrc
-    return fileSrc ? opts.publicUrl + fileSrc : null
+    return fileSrc ? (opts.publicUrl ?? "") + fileSrc : null
   }) || undefined
 }
 

package/src/dev/devServer.ts

@@ -31,6 +31,8 @@ import type { WebRunner } from "./webRunner"
  *                                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
+ *   GET /t/<tok>/lite/[file]     the page of Web Lite (lecodes-web-lite's dist), opened as
+ *                                lite/?dev=.. — the same bundle.js?t=web, the same reload and logs
  *
  * 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).
@@ -51,6 +53,8 @@ export type DevServerOptions = {
   /** What is served under /web/ (src/dev/webRunner.ts): the player, and the page around it; absent =
    *  no browser route. */
   web?: WebRunner | null
+  /** The page of Web Lite (lecodes-web-lite's dist), served under /lite/; absent = no such route. */
+  lite?: string | null
   /** Diagnostics (compile errors, device logs); defaults to stderr-style silence-safe noop. */
   log?: (msg: string) => void
 }
@@ -63,6 +67,8 @@ export type DevServer = {
   url: string
   /** The browser runner page (`dev --web`), or null when no runner is vendored. */
   webUrl: string | null
+  /** The page of Web Lite (`lecodes web dev`), or null when none is served. */
+  liteUrl: 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). */
@@ -84,7 +90,7 @@ const MIME: Record<string, string> = {
   css: "text/css", html: "text/html", wasm: "application/wasm", map: "application/json",
 }
 
-const contentType = (path: string): string => {
+export const contentType = (path: string): string => {
   const i = path.lastIndexOf(".")
   return (i >= 0 && MIME[path.slice(i + 1).toLowerCase()]) || "application/octet-stream"
 }
@@ -233,6 +239,7 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
     return transport === "web" ? js : js + "\n" + renderPrelude({ origin: reqOrigin, base, transport, v })
   }
   const web = options.web ?? null
+  const lite = options.lite ?? 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) => {
@@ -284,6 +291,17 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
       if (rel === "") return redirect(`${base}/web/${query()}`)
       return sendBuilt(res, web.page, rel === "/" ? "index.html" : rel.slice(1))
     }
+    if (route === "/lite" || route.startsWith("/lite/")) {
+      if (!lite) return sendText(res, 404, "text/plain", "No Web Lite page with this CLI (lecodes-web-lite's dist).")
+      const rel = route.slice("/lite".length)
+      if (rel === "" || (rel === "/" && !url.searchParams.has("dev"))) {
+        url.searchParams.set("dev", "..")
+        res.writeHead(302, { location: `${base}/lite/?${url.searchParams.toString()}${url.hash}` })
+        res.end()
+        return
+      }
+      return sendBuilt(res, lite, rel === "/" ? "index.html" : rel.slice(1))
+    }
     if (route === "/version") {
       return sendJson(res, 200, { v })
     }
@@ -363,6 +381,7 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
   return {
     url: `${origin}${base}/dev.js`,
     webUrl: web ? `${origin}${base}/web/` : null,
+    liteUrl: lite ? `${origin}${base}/lite/` : null,
     base,
     port: boundPort,
     v: () => v,

package/src/dev/watchProject.ts

@@ -0,0 +1,53 @@
+import { watch, type FSWatcher } from "node:fs"
+import { loadIgnore } from "../project/ignore"
+import { toKey } from "../project/paths"
+
+/*
+ * The watcher of a dev command: a change of the project's content calls `onChange`, debounced — a
+ * save of several files is one recompile. What never counts: the CLI's own folders, the editors'
+ * files, what the project ignores.
+ */
+
+const DEBOUNCE_MS = 120
+
+// Never trigger a recompile (mirrors scanLocal's skip lists + our own artifacts).
+const SKIP_DIRS = new Set([".lecodes", ".git", "node_modules", "dist"])
+const SKIP_FILES = new Set(["tsconfig.json", "jsconfig.json", ".gitignore", ".lecodesignore", ".DS_Store"])
+
+export type ProjectWatcher = { close(): void }
+
+export const watchProject = (root: string, onChange: () => void, log: { warn(message: string): void, debug?(message: string): void }): ProjectWatcher => {
+  const ignore = loadIgnore(root)
+  const counts = (file: string | null): boolean => {
+    if (file === null) return true   // an event without a name: assume the project's content
+    const parts = file.replace(/\\/g, "/").split("/")
+    if (parts.some((p) => SKIP_DIRS.has(p))) return false
+    if (SKIP_FILES.has(parts[parts.length - 1]!)) return false
+    try {
+      if (ignore(toKey(file), false)) return false
+    } catch { return false }
+    return true
+  }
+
+  let timer: NodeJS.Timeout | null = null
+  let watcher: FSWatcher | null = null
+  try {
+    watcher = watch(root, { recursive: true }, (_type, file) => {
+      const name = file === null ? null : String(file)
+      log.debug?.(`[watch] event: ${name ?? "(null)"} → ${counts(name) ? "recompile" : "skip"}`)
+      if (!counts(name)) return
+      if (timer) clearTimeout(timer)
+      timer = setTimeout(() => { timer = null; onChange() }, DEBOUNCE_MS)
+    })
+  } catch {
+    log.warn("fs.watch(recursive) unavailable on this platform — hot reload disabled (restart to pick up changes).")
+  }
+  watcher?.on("error", (e) => log.warn(`Watcher error — hot reload may have stopped (restart the command): ${e.message}`))
+
+  return {
+    close() {
+      if (timer) clearTimeout(timer)
+      watcher?.close()
+    },
+  }
+}