lecodes-cli 0.19.2 → 0.20.0

package/src/commands/app.ts

@@ -291,7 +291,12 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
     for (const [key, value] of Object.entries(ios.entitlements ?? {})) {
       (entitlementValues[key] ??= []).push(value)
     }
-    runtimePlugins.push({ id, module, register })
+    for (const pkg of ios.packages ?? []) {
+      if (!pkg.url || !Array.isArray(pkg.products) || pkg.products.length === 0 || (!pkg.exact && !pkg.from) || (pkg.exact && pkg.from)) {
+        throw new CliError(`Plugin "${id}": manifest ios.packages entries need { url, exact | from, products: [...] } — got ${JSON.stringify(pkg)}`)
+      }
+    }
+    runtimePlugins.push({ id, module, register, packages: ios.packages })
     newLock[id] = plugin.lock
     log(`${c.green("plugin")}    ${id}@${plugin.lock.version} (${plugin.lock.tag} → Sources/${module})`)
   }

package/src/commands/appDesktop.ts

@@ -4,7 +4,7 @@ import { basename, dirname, join, resolve } from "node:path"
 import { buildBundle } from "./compile"
 import { resolveDesktopExe, selectedDesktopVersion } from "../desktopRenderer"
 import { CliError, c, flagBool, flagStr, log, note, success, warn, type Args } from "../util"
-import { assertRendererSupportsBundle, projectRoot, readJson, resolveDesktopRenderer, writeJson, type AppConfig } from "./appShared"
+import { assertRendererSupportsBundle, desktopPluginLibraries, projectRoot, readJson, resolveDesktopRenderer, writeJson, type AppConfig } from "./appShared"
 import { loadIconMaster } from "./appIcon"
 import { buildMacApp, macHostProvidedNames } from "./appDesktopMac"
 
@@ -208,7 +208,20 @@ export const buildDesktop = async (args: Args) => {
     note("  app.ico rendered from " + config.icon)
   }
 
-  // 5) A short README (BOM so double-click-Notepad shows it right).
+  // 5) Native plugins (packages/desktop/plugin-sdk/lecodes_plugin.h): the project's plugins/ dir +
+  //    every declared plugin's desktop library → plugins/ next to the exe, where a host WITH the plugin
+  //    loader (added after 1.4.0) scans at startup; an older host ignores the folder.
+  //    A declared library that's missing is a build error (strict).
+  {
+    const { files } = desktopPluginLibraries(root, { strict: true })
+    if (files.length > 0) {
+      mkdirSync(join(out, "plugins"), { recursive: true })
+      for (const f of files) cpSync(f, join(out, "plugins", basename(f)))
+      note(`  plugins: ${files.map((f) => basename(f)).join(", ")} → plugins/`)
+    }
+  }
+
+  // 6) A short README (BOM so double-click-Notepad shows it right).
   writeFileSync(join(out, "README.txt"), "\uFEFF" + readmeText(name, exeName, version))
 
   success(`Portable build: ${out}  (${mb(dirSize(out))})`)

package/src/commands/appShared.ts

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process"
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { dirname, join, resolve } from "node:path"
 import { findProjectRoot } from "../manifest"
@@ -16,6 +16,7 @@ import { CliError, c, flagStr, log, note, warn, type Args } from "../util"
 export const FIRST_PARTY_PLUGINS: Record<string, string> = {
   "camera": "letary/lecodes-plugins",
   "qr-scanner": "letary/lecodes-plugins",
+  "map": "letary/lecodes-plugins",
   "geolocation": "letary/lecodes-plugins",
   "push": "letary/lecodes-plugins",
 }
@@ -166,6 +167,21 @@ export const desktopDefaultViewport = (root: string): { width: number, height: n
   }
 }
 
+/** A SwiftPM dependency a plugin's iOS target links (manifest ios.packages). */
+export interface IosPackage {
+  url: string
+  /** Pinned release — the normal case (a plugin's sources compile against one API). */
+  exact?: string
+  /** Minimum release, SwiftPM picks the newest compatible major. Exclusive with `exact`. */
+  from?: string
+  /** Library products of that package the plugin target imports. */
+  products: string[]
+}
+
+/** SwiftPM's package identity for a url: the last path segment without `.git`. */
+export const swiftPackageName = (url: string): string =>
+  (url.replace(/\/+$/, "").split("/").pop() ?? url).replace(/\.git$/, "")
+
 export interface PluginManifest {
   id: string
   version?: string
@@ -178,6 +194,12 @@ export interface PluginManifest {
      *  by sync; the relay signs sends for Letary-published bundle ids with the shared team
      *  key, and the register route fail-fasts for anything outside that namespace. */
     entitlements?: Record<string, unknown>,
+    /** Swift packages the vendored target links (e.g. the map plugin's maplibre-native). Each
+     *  becomes a `.package(url:…)` in the generated LeCodesRuntime/Package.swift (exact or
+     *  from — one of the two) and its `products` become `.product(name:package:)` deps of the
+     *  plugin target. The package name is the URL's last path segment minus `.git`, as SwiftPM
+     *  derives it. Two plugins naming the same url must agree on the version. */
+    packages?: IosPackage[],
   } | null
   android?: {
     /** Dir vendored into the shell (default "android") — a Gradle-module-shaped tree minus
@@ -200,6 +222,15 @@ export interface PluginManifest {
      *  Bare ids resolve through the CLI's known-version table; "id:version" pins explicitly. */
     gradlePlugins?: string[],
   } | null
+  /** Desktop host (packages/desktop): a PREBUILT shared library per OS/arch behind the C ABI in
+   *  `packages/desktop/plugin-sdk/lecodes_plugin.h` — no host rebuild, no source vendoring.
+   *  `library` keys are `${process.platform}-${process.arch}` ("win32-x64", "linux-x64",
+   *  "linux-arm64"), values plugin-dir-relative paths. `lecodes desktop run` / `render --desktop`
+   *  forward the library's dir to the host (CREATOR_PLUGIN_DIRS); `app build desktop` stages the
+   *  file into `<build>/plugins/`. A plugin without a build for the current target is skipped. */
+  desktop?: {
+    library?: Record<string, string>,
+  } | null
 }
 
 export interface LockEntry { repo: string, tag: string, commit: string, version: string }
@@ -400,7 +431,12 @@ export const ensureRepo = (repo: string, wantTag: string | null, lock: LockEntry
 
 /** Resolve one app.json plugin entry to vendorable sources + manifest + lock pin. The platform
  *  being synced must be supported (its manifest branch non-null) — a hard error otherwise. */
-export const resolvePlugin = (id: string, spec: string, lock: LockEntry | undefined, platform: "ios" | "android"): ResolvedPlugin => {
+export type PluginPlatform = "ios" | "android" | "desktop"
+const PLUGIN_PLATFORM_LABEL: Record<PluginPlatform, string> = { ios: "iOS", android: "Android", desktop: "desktop" }
+
+export function resolvePlugin(id: string, spec: string, lock: LockEntry | undefined, platform: PluginPlatform): ResolvedPlugin
+export function resolvePlugin(id: string, spec: string, lock: LockEntry | undefined, platform: PluginPlatform, opts: { optional: true }): ResolvedPlugin | null
+export function resolvePlugin(id: string, spec: string, lock: LockEntry | undefined, platform: PluginPlatform, opts?: { optional?: boolean }): ResolvedPlugin | null {
   let repo: string
   let subdir: string
   let wantTag: string | null = null
@@ -424,7 +460,8 @@ export const resolvePlugin = (id: string, spec: string, lock: LockEntry | undefi
   if (!manifest) throw new CliError(`Plugin "${id}": no lecodes-plugin.json in ${dir}`)
   if (manifest.id !== id) throw new CliError(`Plugin "${id}": manifest declares id "${manifest.id}"`)
   if (!manifest[platform]) {
-    throw new CliError(`Plugin "${id}" does not support ${platform === "ios" ? "iOS" : "Android"} (manifest "${platform}" is null)`)
+    if (opts?.optional) return null
+    throw new CliError(`Plugin "${id}" does not support ${PLUGIN_PLATFORM_LABEL[platform]} (manifest "${platform}" is null)`)
   }
 
   // Namespacing: third-party channel names must be vendor-prefixed ("acme.thing").
@@ -446,3 +483,60 @@ export const resolvePlugin = (id: string, spec: string, lock: LockEntry | undefi
 export const latestPluginTag = (repo: string): string | null => {
   try { return ensureRepo(repo, null, undefined).tag } catch { return null }
 }
+
+/* ---------------------------------- desktop native plugins ---------------------------------- */
+
+/** The desktop host's plugin library target key (manifest `desktop.library` keys). */
+export const desktopPluginTarget = (): string => `${process.platform}-${process.arch}`
+
+const isDesktopPluginLibrary = (name: string): boolean => {
+  const n = name.toLowerCase()
+  return process.platform === "win32" ? n.endsWith(".dll") : n.endsWith(".so")
+}
+
+/** Native plugin libraries for THIS project on THIS machine (packages/desktop/plugin-sdk/
+ *  lecodes_plugin.h — runtime-loaded .dll/.so, no host rebuild):
+ *    - every library in the project's own `plugins/` dir — the zero-manifest dev loop (build a
+ *      DLL, drop it there, `lecodes desktop run`);
+ *    - the `desktop.library[target]` of every app.json plugin whose manifest declares one
+ *      (mobile-only plugins are skipped, not errors).
+ *  `dirs` is what a run forwards to the host as CREATOR_PLUGIN_DIRS (the host scans them);
+ *  `files` is what `app build desktop` copies into `<build>/plugins/`. `strict` turns a broken
+ *  declaration into an error (builds); runs warn and go on without that plugin. */
+export const desktopPluginLibraries = (root: string, opts: { strict?: boolean } = {}): { dirs: string[], files: string[] } => {
+  const dirs: string[] = []
+  const files: string[] = []
+  const local = join(root, "plugins")
+  if (existsSync(local) && statSync(local).isDirectory()) {
+    dirs.push(local)
+    for (const f of readdirSync(local)) if (isDesktopPluginLibrary(f)) files.push(join(local, f))
+  }
+  const config = readJson<AppConfig>(join(root, "app.json"))
+  const specs = Object.entries(config?.plugins ?? {})
+  if (specs.length === 0) return { dirs, files }
+  const lock = readJson<{ plugins?: Record<string, LockEntry> }>(join(root, "plugins.lock.json"))?.plugins ?? {}
+  const target = desktopPluginTarget()
+  for (const [id, spec] of specs) {
+    let plugin: ResolvedPlugin | null
+    try {
+      plugin = resolvePlugin(id, spec, lock[id], "desktop", { optional: true })
+    } catch (e) {
+      if (opts.strict) throw e
+      warn(`Plugin "${id}": ${(e as Error).message} — skipped for this desktop run`)
+      continue
+    }
+    const rel = plugin?.manifest.desktop?.library?.[target]
+    if (!plugin || !rel) continue   // mobile-only, or no build for this OS/arch
+    const abs = resolve(plugin.dir, rel)
+    if (!existsSync(abs)) {
+      const msg = `Plugin "${id}": desktop library ${abs} is missing (manifest desktop.library["${target}"])`
+      if (opts.strict) throw new CliError(msg)
+      warn(`${msg} — skipped for this desktop run`)
+      continue
+    }
+    files.push(abs)
+    const dir = dirname(abs)
+    if (!dirs.includes(dir)) dirs.push(dir)
+  }
+  return { dirs, files }
+}

package/src/commands/appTemplates.ts

@@ -1,3 +1,5 @@
+import { swiftPackageName, type IosPackage } from "./appShared"
+
 /* Templates for `lecodes app init ios` / `lecodes app sync` — distilled 1:1 from the
  * hand-built, device-verified reference shell (docs/xcode-app-plan.md). Three ownership
  * tiers: App/ Swift files are USER-owned after generation (init writes once, sync never
@@ -696,6 +698,8 @@ export interface RuntimePlugin {
   register: string
   /** Plugin id, for the generated comments. */
   id: string
+  /** Swift packages the target links (manifest ios.packages). */
+  packages?: IosPackage[]
 }
 
 /** The SDK binary products (all vend the same `LeCodesSDK` module): core = UI only,
@@ -711,13 +715,33 @@ export type SdkVariant = "core" | "2d" | "3d" | "full"
  *  SDK. Moving the version is the CLI's job — `lecodes app update` (or app.json ios.sdk). */
 export const runtimePackageTemplate = (sdkVersion: string, variant: SdkVariant, plugins: RuntimePlugin[]): string => {
   const product = `LeCodesSDK-${variant}`
-  const pluginTargets = plugins.map(p => `
+  // Third-party Swift packages (manifest ios.packages), one `.package(…)` per url. Two plugins
+  // naming the same url must agree on the pin — SwiftPM has one resolution per package.
+  const packages = new Map<string, IosPackage>()
+  for (const p of plugins) {
+    for (const pkg of p.packages ?? []) {
+      const prior = packages.get(pkg.url)
+      if (prior && (prior.exact !== pkg.exact || prior.from !== pkg.from)) {
+        throw new Error(`Plugin "${p.id}" pins ${pkg.url} at ${pkg.exact ?? `from ${pkg.from}`} but another plugin pins ${prior.exact ?? `from ${prior.from}`} — the shell can link one version.`)
+      }
+      packages.set(pkg.url, pkg)
+    }
+  }
+  const packageDecls = [...packages.values()].map(pkg =>
+    `\n        .package(url: "${pkg.url}", ${pkg.exact ? `exact: "${pkg.exact}"` : `from: "${pkg.from}"`}),`).join("")
+  const pluginTargets = plugins.map(p => {
+    const deps = [
+      `.product(name: "${product}", package: "lecodes-ios-sdk")`,
+      ...(p.packages ?? []).flatMap(pkg => pkg.products.map(name => `.product(name: "${name}", package: "${swiftPackageName(pkg.url)}")`)),
+    ]
+    return `
         // plugin: ${p.id} (vendored — see plugins.lock.json)
         .target(
             name: "${p.module}",
-            dependencies: [.product(name: "${product}", package: "lecodes-ios-sdk")],
+            dependencies: [${deps.join(", ")}],
             path: "Sources/${p.module}"
-        ),`).join("")
+        ),`
+  }).join("")
   const runtimeDeps = [`.product(name: "${product}", package: "lecodes-ios-sdk")`, ...plugins.map(p => `"${p.module}"`)]
   return `// swift-tools-version:5.9
 //
@@ -736,7 +760,7 @@ let package = Package(
         .library(name: "LeCodesRuntime", targets: ["LeCodesRuntime"]),
     ],
     dependencies: [
-        .package(url: "https://github.com/letary/lecodes-ios-sdk.git", exact: "${sdkVersion}"),
+        .package(url: "https://github.com/letary/lecodes-ios-sdk.git", exact: "${sdkVersion}"),${packageDecls}
     ],
     targets: [
         .target(

package/src/commands/desktop.ts

@@ -1,7 +1,8 @@
+import { basename } from "node:path"
 import { CliError, c, flagBool, flagStr, log, note, type Args } from "../util"
 import { findProjectRoot } from "../manifest"
 import { buildBundle } from "./compile"
-import { assertRendererSupportsBundle, readAppConfigAt, resolveDesktopRenderer } from "./appShared"
+import { assertRendererSupportsBundle, desktopPluginLibraries, readAppConfigAt, resolveDesktopRenderer } from "./appShared"
 import { buildDesktop } from "./appDesktop"
 import {
   DESKTOP_RENDERER_VERSION,
@@ -57,9 +58,13 @@ const run = async (args: Args) => {
   const renderer = resolveDesktopRenderer(root, args)
   const { js, resources } = await buildBundle(args, undefined, { localAssets: true, desktopRenderer: renderer })
   assertRendererSupportsBundle(renderer, js)
+  // Native plugins: the project's plugins/ dir + declared plugin libraries, scanned by the host.
+  const { dirs: pluginDirs, files: pluginFiles } = desktopPluginLibraries(root)
+  if (pluginFiles.length > 0) note(`Native plugins: ${pluginFiles.map((f) => basename(f)).join(", ")}`)
   note(`Launching LeCodes Desktop${renderer === "vulkan" ? " (Vulkan)" : ""}… (close the window to return)`)
   await runDesktopApp(js, resources, {
     renderer,
+    pluginDirs,
     width: Number(flagStr(args, "width")) || win?.width,
     height: Number(flagStr(args, "height")) || win?.height,
     minWidth: win?.minWidth,

package/src/commands/dev.ts

@@ -5,6 +5,8 @@ import { basename, join } from "node:path"
 import { findProjectRoot, readManifest, LECODES_DIR, type Manifest } from "../manifest"
 import { loadIgnore } from "../ignore"
 import { startDevServer } from "../dev/devServer"
+import { resolveWebRunnerDir } from "../dev/webRunner"
+import { openBrowser } from "../browserAuth"
 import { runDesktopDev } from "../desktopRenderer"
 import { readAppConfigAt } from "./appShared"
 import { resolveScale } from "./desktop"
@@ -20,6 +22,11 @@ import { CliError, c, flagBool, flagStr, log, note, toKey, warnErr, type Args }
  * backend. Custom shaders compile locally too (matc, downloaded on first use — matcTool.ts);
  * only when matc can't be fetched do they fall back to server-compiled artifacts (push once).
  *
+ * `--web` opens the same project in the browser: the dev server also serves the Web Lite runner
+ * (viewer-lite's dist-embed, vendored as runtime/web) under /web/ — CSS-flexbox UI + OGL 3D + the
+ * web twins of the camera/map plugins, no wasm. Same bundle and hot reload; browser console
+ * output streams back here like a device's. The URL is printed whenever the runner is available.
+ *
  * Works inside a cloned project or standalone in any folder with an entry .ts file.
  * The desktop host speaks websocket since 1.0.0 (host_ws); `?t=poll` remains the fallback
  * for older desktop builds (or any host without a websocket bridge).
@@ -116,9 +123,14 @@ export const dev = async (args: Args) => {
   const origin = `http://${host}:${port}`
   const token = loadDevToken(root)
 
+  const webDir = resolveWebRunnerDir()
+  if (flagBool(args, "web") && !webDir) {
+    throw new CliError("No Web Lite runner found for --web: this CLI has no runtime/web (a monorepo checkout needs `bun run build:embed` in packages/viewer-lite).")
+  }
   const server = await startDevServer({
     root, manifest, name, origin, port, token,
     entryOverride: flagStr(args, "entry"),
+    webDir,
     log: note,
   }).catch((e: unknown) => {
     const msg = e instanceof Error ? e.message : String(e)
@@ -180,6 +192,10 @@ export const dev = async (args: Args) => {
   log("")
   if (!flagBool(args, "no-qr")) await printQr(server.url)
   log(`Scan the QR with the LeCodes app, or open:  ${c.bold(server.url)}`)
+  // The browser runner: localhost is a secure context (camera works there), the LAN address is
+  // what a phone's browser can reach.
+  const webLocal = server.webUrl ? server.webUrl.replace(`http://${host}:`, "http://localhost:") : null
+  if (server.webUrl && webLocal) log(`In the browser (Web Lite):                  ${c.bold(webLocal)}   (LAN: ${server.webUrl})`)
   note(`Older desktop builds (no websocket bridge): ${server.url}?t=poll`)
   if (alternatives.length > 0) {
     note(`Device can't reach it? This machine also has ${alternatives.map((a) => `${a.address} (${a.iface})`).join(", ")} — retry with --host <ip>.`)
@@ -188,6 +204,12 @@ export const dev = async (args: Args) => {
   log("")
   log(`Watching ${root} — save a file to hot-reload. Ctrl+C to stop.`)
 
+  // --web: open the browser runner (the server keeps serving it either way).
+  if (flagBool(args, "web") && webLocal) {
+    note("Opening the browser…")
+    openBrowser(webLocal)
+  }
+
   // --desktop: open the dev URL in the native host too (same server, same hot reload — the host
   // speaks the websocket channel). Window config comes from app.json's desktop block. The window
   // closing does NOT stop the server: phones stay connected, and re-running with --desktop is the

package/src/commands/projectTemplates.ts

@@ -23,7 +23,7 @@ lecodes render src/screens/cart.ts   # ONE screen module, without booting the ap
                                   # --state <name> picks the branch). Same flags as above.
 lecodes render --desktop --png shot.png  # NATIVE render: real Filament 3D + UI + 2D composited —
                                   # use this to SEE 3D scenes / procedural geometry (headless
-                                  # renders record 3D as JSON only). Windows/Linux; downloads
+                                  # renders record 3D as JSON — simulated, not drawn). Windows/Linux; downloads
                                   # the renderer on first use. --frames <n> for slow loads.
 lecodes render --script <file>    # drive the app through a scenario (format below)
 lecodes render --desktop --view iso --png iso.png   # 3D: inspection camera fitted to the WHOLE
@@ -72,8 +72,9 @@ advance in fixed 1/60 steps driven by \`wait\`/\`frames\`/\`drag\`/\`key\` — n
 so a flow that passes once passes every time. \`Input.key(code)\` reads the keys a flow holds and
 \`Input.on('keydown' | 'keyup', e => e.code)\` fires for each \`key\`/\`keyDown\`/\`keyUp\` step
 (events land before the next loop tick); \`stick\` values are what \`Input.gamepad(0).axis()\` reads.
-Headless draws UI + the 2D scene (sprites, tilemaps, Box2D); 3D is captured as JSON and Jolt does
-not simulate — use \`--desktop\` for 3D pixels. \`console.log\` + \`expect.log\` is the assertion
+Headless draws UI + the 2D scene (sprites, tilemaps, Box2D); 3D is captured as JSON with REAL Jolt
+physics (bodies fall, characters collide, triggers fire, ragdolls drop — a character with no ground
+under it falls, like on device) — use \`--desktop\` for 3D pixels. \`console.log\` + \`expect.log\` is the assertion
 channel for game state that has no UI.
 
 ## Make the app testable

package/src/commands/render.ts

@@ -4,7 +4,7 @@ import { compileHeadlessBundle } from "../compile/headlessBundle"
 import { screenTargetFromArgs } from "../compile/screenEntry"
 import { findProjectRoot } from "../manifest"
 import { buildBundle } from "./compile"
-import { desktopDefaultViewport, readAppConfigAt, resolveDesktopRenderer } from "./appShared"
+import { desktopDefaultViewport, desktopPluginLibraries, readAppConfigAt, resolveDesktopRenderer } from "./appShared"
 import { runDesktopRender } from "../desktopRenderer"
 import { evaluateDesktopRun, translateScenario } from "../desktopScript"
 import { CliError, c, flagStr, flagBool, isNullSink, logErr, note, warnErr, type Args } from "../util"
@@ -196,6 +196,8 @@ const renderDesktop = async (args: Args) => {
 
   // One renderer decision: the host binary AND the staged .filamat variant (see appShared).
   const desktopRenderer = resolveDesktopRenderer(root, args)
+  // Native plugins (project plugins/ dir + declared libraries) — the host scans CREATOR_PLUGIN_DIRS.
+  const { dirs: pluginDirs } = desktopPluginLibraries(root)
   const { js, resources } = await buildBundle(args, undefined, {
     localAssets: true, desktopRenderer,
     extraEntries: screen ? [screen.entry] : undefined, entryOverride: screen?.entryPath,
@@ -212,7 +214,7 @@ const renderDesktop = async (args: Args) => {
     const timeoutMs = Number(flagStr(args, "timeout")) || (60000 + plan.steps.length * 5000)
     note(`Running ${plan.steps.length} step${plan.steps.length === 1 ? "" : "s"} (native)…`)
     const { output } = await runDesktopRender(js, resources, {
-      renderer: desktopRenderer,
+      renderer: desktopRenderer, pluginDirs,
       width, height, frames: plan.frameCap, outPng: pngFlag, logs, timeoutMs, script: plan.text, fixedDtMs,
     })
     const result = evaluateDesktopRun(plan, output)
@@ -234,7 +236,7 @@ const renderDesktop = async (args: Args) => {
   const timeoutMs = Number(flagStr(args, "timeout")) || 60000
   note(screen ? `Rendering ${screen.label} (native)…` : "Rendering (native)…")
   await runDesktopRender(js, resources, {
-    renderer: desktopRenderer,
+    renderer: desktopRenderer, pluginDirs,
     width, height, frames, outPng: pngFlag, logs, timeoutMs, fixedDtMs, camera, view,
   })
   note(`Wrote ${pngFlag} (${width}x${height}, native render${view ? `, ${view.split(";")[0]} view` : camera ? ", custom camera" : ""})`)

package/src/commands/test.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs"
 import { dirname, resolve } from "node:path"
 import { compileHeadlessBundle } from "../compile/headlessBundle"
-import { desktopDefaultViewport, resolveDesktopRenderer } from "./appShared"
+import { desktopDefaultViewport, desktopPluginLibraries, resolveDesktopRenderer } from "./appShared"
 import { fileScenarioIO, requireRenderer, resolveFixtures, resolveSafeAreaChoice } from "./render"
 import { buildBundle } from "./compile"
 import { findProjectRoot } from "../manifest"
@@ -261,6 +261,7 @@ export const test = async (args: Args) => {
     const finalPng = resolve(caseDir, "final.png")
     const { output } = await runDesktopRender(native!.js, native!.resources, {
       renderer: desktopRenderer,
+      pluginDirs: desktopPluginLibraries(root).dirs,
       width: Number(flagStr(args, "width")) || kase.width || projectViewport?.width || 390,
       height: Number(flagStr(args, "height")) || kase.height || projectViewport?.height || 844,
       frames: plan.frameCap, outPng: finalPng, logs: flagBool(args, "logs"),

package/src/desktopRenderer.ts

@@ -1,7 +1,7 @@
 import { execFileSync, spawn, spawnSync } from "node:child_process"
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
 import { homedir, tmpdir } from "node:os"
-import { join, resolve } from "node:path"
+import { delimiter, join, resolve } from "node:path"
 import { cachedArtifactSha, downloadReleaseArchive, fetchReleaseProduct, semverNewer, type ManifestVersion } from "./releases"
 import { CliError, note, warnErr } from "./util"
 import { makeStackDemangler } from "./compile/nativeStack"
@@ -299,10 +299,20 @@ export type DesktopWindowOpts = {
   /** Multiplayer launch facts for the host (`--server --port N --max-clients N` / `--connect ip:port`);
    *  the SDK reads them through `Net.launch` and decides (docs/multiplayer-plan.md). */
   net?: { role: "server" | "client"; address?: string; port?: number; maxClients?: number }
+  /** Dirs the host scans for native plugin libraries (CREATOR_PLUGIN_DIRS; the loader was added
+   *  after host 1.4.0 — an older host ignores the env). See appShared.desktopPluginLibraries. */
+  pluginDirs?: string[]
+}
+
+/** CREATOR_PLUGIN_DIRS: the project's plugin dirs first, then whatever the environment already
+ *  carried (a `.env` CREATOR_PLUGIN_DIRS keeps working alongside the project's `plugins/`). */
+const pluginEnv = (dirs: string[] | undefined): Record<string, string> => {
+  const all = [...(dirs ?? []), ...(process.env.CREATOR_PLUGIN_DIRS ? [process.env.CREATOR_PLUGIN_DIRS] : [])]
+  return all.length > 0 ? { CREATOR_PLUGIN_DIRS: all.join(delimiter) } : {}
 }
 
 const windowEnv = (opts: DesktopWindowOpts): Record<string, string> => {
-  const env: Record<string, string> = {}
+  const env: Record<string, string> = { ...pluginEnv(opts.pluginDirs) }
   // A lone width/height fills the other side from the host default so it isn't silently ignored.
   const width = opts.width ?? (opts.height !== undefined ? 1280 : undefined)
   const height = opts.height ?? (opts.width !== undefined ? 720 : undefined)
@@ -356,6 +366,8 @@ export type DesktopRenderOptions = {
   /** Inspection camera: CREATOR_CAMERA ("ex,ey,ez;tx,ty,tz[;fov]") or CREATOR_VIEW ("iso[;fov]"). */
   camera?: string
   view?: string
+  /** Dirs the host scans for native plugin libraries (CREATOR_PLUGIN_DIRS). */
+  pluginDirs?: string[]
 }
 
 export type DesktopRenderOutcome = {
@@ -482,6 +494,7 @@ export const runDesktopRender = async (
     if (opts.fixedDtMs) env.CREATOR_FIXED_DT = String(opts.fixedDtMs)
     if (opts.camera) env.CREATOR_CAMERA = opts.camera
     if (opts.view) env.CREATOR_VIEW = opts.view
+    Object.assign(env, pluginEnv(opts.pluginDirs))
     // Frames the host prints name the minified bundle (`module.js:5:51631`); map them back to
     // project positions. Chunks stay raw so `[script]` marker parsing sees exactly what was sent —
     // the rewrite happens on the joined text (and best-effort per chunk for live --logs).

package/src/dev/devServer.ts

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

package/src/dev/webRunner.ts

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

package/src/index.ts

@@ -120,6 +120,9 @@ ${c.bold("Commands:")}
                                   --host <ip>     LAN address to advertise (default: auto-detect)
                                   --entry <path>  override the entrypoint
                                   --no-qr         don't render the QR code
+                                  --web           also open the app in the browser (Web Lite host:
+                                                    same bundle + hot reload, camera/map plugins
+                                                    have web twins; the /web/ URL is served always)
                                   --desktop       also open the app in the native desktop host
                                                     (same hot reload; window from app.json's
                                                     desktop block; closing it keeps the server)