lecodes-cli 0.19.2 → 0.20.1

package/src/cmgenTool.ts

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync } from "node:fs"
 import { homedir } from "node:os"
 import { join, resolve } from "node:path"
-import { downloadReleaseArchive, fetchReleaseProduct, semverNewer, type ManifestVersion } from "./releases"
+import { downloadReleaseArchive, fetchReleaseProduct, newestForPlatform, semverNewer, type ManifestFile, type ManifestVersion } from "./releases"
 import { CliError, note } from "./util"
 
 /*
@@ -20,7 +20,8 @@ import { CliError, note } from "./util"
  * stays network-free and still works standalone against a local build.
  *
  * No version pin, same reasoning as matc: the KTX1 layout is tied to the vendored Filament and
- * changes rarely, so resolution takes the newest cached copy, else downloads `latest`.
+ * changes rarely, so resolution takes the newest cached copy, else downloads the newest release
+ * PUBLISHED FOR THIS PLATFORM (see releases.ts newestForPlatform).
  */
 
 const exeName = () => (process.platform === "win32" ? "cmgen.exe" : "cmgen")
@@ -63,15 +64,21 @@ export const installedCmgenVersions = (): string[] => {
 export const fetchCmgenManifest = (): Promise<{ latest: string, versions: ManifestVersion[] }> =>
   fetchReleaseProduct("cmgen", "cmgen (environment tool)")
 
-const downloadCmgen = async (version: string, versions: ManifestVersion[], dest: string): Promise<void> => {
+/** The published cmgen this platform should get: the newest version carrying a build for it (see
+ *  newestForPlatform — a release often ships one platform, so `latest` is the wrong question). */
+const pickCmgen = (versions: ManifestVersion[]): { version: string, file: ManifestFile } => {
   const key = platformKey()
-  const file = versions.find((v) => v.version === version)?.files[key]
-  if (!file) {
+  const hit = newestForPlatform(versions, key)
+  if (!hit) {
     throw new CliError(
-      `cmgen ${version} [${key}] isn't published — build filament's host tools locally and point ` +
+      `cmgen isn't published for ${key} — build filament's host tools locally and point ` +
       `LECODES_CMGEN at the binary.`,
     )
   }
+  return hit
+}
+
+const downloadCmgen = async (version: string, file: ManifestFile, dest: string): Promise<void> => {
   note(`Downloading the environment tool (cmgen ${version}, ${(file.size / 1024 / 1024).toFixed(1)} MB)…`)
   await downloadReleaseArchive(file, {
     cacheRoot: cacheRoot(),
@@ -95,9 +102,10 @@ export const resolveCmgenExeCached = (): string | null => {
 export const resolveCmgenExe = async (): Promise<string> => {
   const cached = resolveCmgenExeCached()
   if (cached) return cached
-  const { latest, versions } = await fetchCmgenManifest()
-  const dir = join(cacheRoot(), `cmgen-${latest}`)
-  await downloadCmgen(latest, versions, dir)
+  const { versions } = await fetchCmgenManifest()
+  const { version, file } = pickCmgen(versions)
+  const dir = join(cacheRoot(), `cmgen-${version}`)
+  await downloadCmgen(version, file, dir)
   const exe = findCmgenIn(dir)
   if (!exe) throw new CliError(`cmgen cache at ${dir} is broken — delete the folder and retry.`)
   return exe

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"
 
@@ -199,8 +199,18 @@ export const buildDesktop = async (args: Args) => {
   note(`  assets: ${assetCount} files, ${mb(assetBytes)} → ${ASSETS_DIR}/`)
 
   // 3) Pruned app.json — the host (≥1.3.0) reads name + desktop.window next to app.js, so the
-  //    folder carries its own window config (title/size/min/resizable/fullscreen).
-  writeJson(join(out, "app.json"), { name, ...(config.desktop ? { desktop: { window: config.desktop.window } } : {}) })
+  //    folder carries its own window config (title/size/min/resizable/fullscreen); a newer host also
+  //    reads desktop.mouseEmulateTouch + desktop.virtualKeyboard there (an older one skips the
+  //    unknown fields).
+  const desktop = config.desktop
+  writeJson(join(out, "app.json"), {
+    name,
+    ...(desktop ? { desktop: {
+      window: desktop.window,
+      ...(desktop.mouseEmulateTouch !== undefined ? { mouseEmulateTouch: desktop.mouseEmulateTouch } : {}),
+      ...(desktop.virtualKeyboard !== undefined ? { virtualKeyboard: desktop.virtualKeyboard } : {}),
+    } } : {}),
+  })
 
   // 4) Window/taskbar icon (host ≥1.3.0 loads app.ico next to the exe at runtime).
   if (config.icon) {
@@ -208,7 +218,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",
 }
@@ -76,12 +77,60 @@ export interface AppConfig {
     /** 3D buffer cap in px, e.g. [1920, 1080]: on a bigger window/monitor the 3D renders at most
      *  this size (aspect kept) — the per-machine answer to "fullscreen on a 4K display is slow". */
     maxRenderSize?: [number, number],
+    /** The mouse button acts as a finger: a left click-drag scrolls + flings like touch (the wheel
+     *  always scrolls, clicks are unaffected; a button inside a scrollable then gets the touch-style
+     *  press feedback delay). For testing the touch experience without a touchscreen, or an app
+     *  driven by a mouse-like device. `desktop run` forwards it as CREATOR_MOUSE_TOUCH (a set env
+     *  wins); a built folder's host reads it from the staged app.json. Headless render/test ignore it. */
+    mouseEmulateTouch?: boolean,
+    /** On-screen keyboard for EVERY input/textarea (touch kiosks, a screen without a keyboard).
+     *  `true` or a block; `desktop run` forwards it as CREATOR_VIRTUAL_KEYBOARD (a set env wins),
+     *  a built folder's host reads it from the staged app.json. Headless render/test ignore it. */
+    virtualKeyboard?: boolean | DesktopVirtualKeyboard,
     /** The macOS .app build (`lecodes app build desktop` on a Mac) — identity + signing +
      *  notarization. See appDesktopMac.ts for the whole story. */
     macos?: MacDesktopConfig,
   }
 }
 
+/** One style slot of the desktop on-screen keyboard — the SDK's style words, the subset the drawn
+ *  keyboard reads. Unset fields keep the theme preset. */
+export interface DesktopKeyboardSlot {
+  backgroundColor?: string
+  color?: string
+  borderRadius?: number
+  fontSize?: number
+  /** A family the app registered with `font()` / `Fonts`, so labels match the UI. */
+  fontFamily?: string
+  /** `board` only: band inset / key spacing (logical px). */
+  padding?: number
+  gap?: number
+}
+
+/** app.json `desktop.virtualKeyboard` as a block. */
+export interface DesktopVirtualKeyboard {
+  /** Off/on; an object without it counts as on. */
+  enabled?: boolean
+  /** Layouts in order, the first is the start one; the language key appears with two or more.
+   *  Shipped: "en", "ru". */
+  layouts?: ("en" | "ru")[]
+  /** Band height: ≤ 1 = a fraction of the window (default 0.32), > 1 = logical px. */
+  height?: number
+  /** Cap on the KEY AREA's width in logical px — on a wide kiosk the keys would otherwise stretch
+   *  across the whole window. The band itself always spans the window; the keys sit centred in it. */
+  maxWidth?: number
+  /** Colour preset the style slots override. */
+  theme?: "dark" | "light"
+  style?: {
+    board?: DesktopKeyboardSlot
+    key?: DesktopKeyboardSlot
+    /** A held key (and an active shift). Inherits `key` first. */
+    keyPressed?: DesktopKeyboardSlot
+    /** Shift / backspace / enter / page keys. Inherits `key` first. */
+    keySpecial?: DesktopKeyboardSlot
+  }
+}
+
 /** app.json `desktop.macos`. Only NAMES live here (identity, keychain profile) — the certificate
  *  and the notarization password stay in the keychain. */
 export interface MacDesktopConfig {
@@ -166,6 +215,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 +242,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 +270,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 +479,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 +508,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 +531,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/assets.ts

@@ -1,5 +1,6 @@
-import { CliError, type Args } from "../util"
+import { type Args } from "../util"
 import { resolveCmgenExe } from "../cmgenTool"
+import { loadPeer } from "../peerInstall"
 
 /*
  * `lecodes assets <convert|probe|doctor|sky> …` — the LeCodes asset pipeline (packages/lecodes-assets):
@@ -9,12 +10,7 @@ import { resolveCmgenExe } from "../cmgenTool"
  * forwarded untouched (`assets` gets `_raw` from main). See docs/animation-plan.md §2.9.
  */
 export const assets = async (args: Args & { _raw?: string[] }) => {
-  let mod: typeof import("lecodes-assets/cli")
-  try {
-    mod = await import("lecodes-assets/cli")
-  } catch {
-    throw new CliError("The asset pipeline isn't installed. Run:  npm install -g lecodes-assets")
-  }
+  const mod = await loadPeer<typeof import("lecodes-assets/cli")>("lecodes-assets", "cli", { for: "lecodes assets" })
   const raw = args._raw ?? args._
   // `sky` shells out to filament's cmgen, which the asset package deliberately never downloads
   // itself (it stays network-free and usable standalone). The CLI owns release artifacts, so it

package/src/commands/design.ts

@@ -5,6 +5,7 @@ import { compileDesignScreen } from "../compile/designCompile"
 import { openBrowser } from "../browserAuth"
 import { CLAUDE_MD, DESIGN_MACROS_DTS, HOME_SCREEN_TS, META_JSON, META_JSON_DESKTOP, README_HINT, SPEC_MD, TABS_TS, TOKENS_TS } from "./designTemplates"
 import { CliError, c, flagBool, flagStr, log, logErr, note, warnErr, type Args } from "../util"
+import { loadPeer } from "../peerInstall"
 import { loadConfig, normalizeApiUrl, requireApiUrl, requireToken } from "../config"
 import {
   createDesignComment, deleteDesignComment, deleteDesignCommentMessage, disableDesignShare,
@@ -87,12 +88,7 @@ const loadDesignServer = async (
   if (!existsSync(ctx.designDir)) {
     throw new CliError(`No ${ctx.dirName}/ folder here. Run "lecodes design init" to scaffold it.`)
   }
-  let mod: typeof import("lecodes-design/server")
-  try {
-    mod = await import("lecodes-design/server")
-  } catch {
-    throw new CliError("The design canvas isn't installed. Run:  npm install -g lecodes-design")
-  }
+  const mod = await loadPeer<typeof import("lecodes-design/server")>("lecodes-design", "server", { for: "lecodes design" })
   const missing = needs.filter((name) => typeof mod[name] !== "function")
   if (missing.length) {
     throw new CliError(
@@ -236,23 +232,14 @@ const snapshot = async (ctx: DesignContext, args: Args) => {
   const allStates = flagBool(args, "all-states")
   if (stateFlag !== undefined && allStates) throw new CliError("Use either --state <name> or --all-states, not both.")
 
-  let renderer: typeof import("lecodes-renderer/headless")
-  try {
-    renderer = await import("lecodes-renderer/headless")
-  } catch {
-    throw new CliError("The renderer isn't installed. Run:  npm install -g lecodes-renderer")
-  }
+  const renderer = await loadPeer<typeof import("lecodes-renderer/headless")>("lecodes-renderer", "headless", { for: "lecodes design render" })
 
   // Enumerating / validating states parses the screen source — that discovery lives in the design
   // package. The canonical-only path (no flag) needs no discovery, so base snapshot stays lean.
   let discover: ((source: string) => { states: string[], canonical: string }) | null = null
   if (stateFlag !== undefined || allStates) {
-    try {
-      const ds = await import("lecodes-design/server")
-      discover = (src) => { const d = ds.discoverScreenStates(src); return { states: d.states, canonical: d.canonical } }
-    } catch {
-      throw new CliError("Rendering specific states needs the design canvas. Run:  npm install -g lecodes-design")
-    }
+    const ds = await loadPeer<typeof import("lecodes-design/server")>("lecodes-design", "server", { for: "lecodes design render --state" })
+    discover = (src) => { const d = ds.discoverScreenStates(src); return { states: d.states, canonical: d.canonical } }
   }
 
   // A stuck screen (runaway loop) shouldn't hang the CLI forever.
@@ -330,8 +317,8 @@ const serve = async (ctx: DesignContext, args: Args) => {
 
   // The MCP render_screen tool renders headless through lecodes-renderer, injected here so the
   // design server keeps no dependency on it. Absent renderer → the tool returns an install hint.
-  let renderer: typeof import("lecodes-renderer/headless") | null = null
-  try { renderer = await import("lecodes-renderer/headless") } catch { renderer = null }
+  // Opportunistic: never triggers an install from inside the MCP server (the tool reports the hint).
+  const renderer = await loadPeer<typeof import("lecodes-renderer/headless")>("lecodes-renderer", "headless", { for: "lecodes design (render_screen)", install: false })
   const renderScreen = renderer
     ? async (id: string, format: "json" | "png" | "both", state?: string) => {
         const r = renderer!
@@ -740,12 +727,8 @@ export const flushDesignComments = async (args: Args): Promise<CommentFlush | nu
   const platform = optionalPlatform(ctx)
   if (!platform) return null
 
-  let designServer: typeof import("lecodes-design/server")
-  try {
-    designServer = await import("lecodes-design/server")
-  } catch {
-    return null
-  }
+  const designServer = await loadPeer<typeof import("lecodes-design/server")>("lecodes-design", "server", { for: "lecodes design", install: false })
+  if (!designServer) return null
   // `settleQueued` must take `delivered` (4 params): settling a half-failed push with the older
   // signature would drop the writes that DIDN'T go through instead of retrying them.
   if (typeof designServer.queuedThreads !== "function") return null

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,15 +58,20 @@ 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,
     minHeight: win?.minHeight,
     resizable: win?.resizable,
     title: flagStr(args, "title") ?? win?.title ?? appCfg?.name,
+    storageScope: appCfg?.name,
     // --fullscreen forces it on; --windowed forces it off (over app.json); else the config decides.
     fullscreen: flagBool(args, "fullscreen") ? true : flagBool(args, "windowed") ? false : win?.fullscreen,
     scale: resolveScale(flagStr(args, "scale"), win?.scale),
@@ -73,6 +79,8 @@ const run = async (args: Args) => {
     // from app.json only. Both are desktop-level (the machine/app), not window-level.
     renderScale: resolveRenderScale(flagStr(args, "render-scale"), appCfg?.desktop?.renderScale),
     maxRenderSize: appCfg?.desktop?.maxRenderSize,
+    mouseEmulateTouch: appCfg?.desktop?.mouseEmulateTouch,
+    virtualKeyboard: appCfg?.desktop?.virtualKeyboard,
     // --fps: the host's own corner counter. A flag and not app.json on purpose — it is something you
     // switch on while looking at a frame, not a property of the app.
     fps: flagBool(args, "fps"),

package/src/commands/dev.ts

@@ -5,7 +5,10 @@ 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 { androidCrashLines, launchOnAndroid, type AndroidDevSession } from "../dev/androidDev"
 import { readAppConfigAt } from "./appShared"
 import { resolveScale } from "./desktop"
 import { CliError, c, flagBool, flagStr, log, note, toKey, warnErr, type Args } from "../util"
@@ -20,6 +23,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 +124,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)
@@ -148,6 +161,7 @@ export const dev = async (args: Args) => {
   }
 
   const debug = process.env.LECODES_DEV_DEBUG === "1"
+  const underBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined"
   let timer: NodeJS.Timeout | null = null
   const onChange = (file: string | null) => {
     if (debug) note(`[watch] event: ${file ?? "(null)"} → ${shouldRecompile(file) ? "recompile" : "skip"}`)
@@ -180,6 +194,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 +206,52 @@ 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)
+  }
+
+  // --android: open the dev URL in the LeCodes app on the phone (adb; see dev/androidDev.ts). With
+  // --time <s> the run is bounded — screenshot to --png, force-stop, exit — which is the shape a
+  // scripted check wants; without it the app runs until Ctrl+C, and Ctrl+C force-stops it (a
+  // device run has no frame cap, and a 3D scene left rendering heats a charging phone).
+  if (flagBool(args, "android")) {
+    const seconds = Number(flagStr(args, "time")) || 0
+    const png = flagStr(args, "png")
+    // Under Bun the websocket channel never delivers (see the warning above): the phone would sit on
+    // "Connected — loading the project…" forever. The path-form poll url works on both runtimes.
+    const deviceUrl = `http://127.0.0.1:${port}${server.url.slice(origin.length)}`.replace(/\/dev\.js$/, underBun ? "/dev-poll.js" : "/dev.js")
+    let session: AndroidDevSession
+    try {
+      session = launchOnAndroid({ port, url: deviceUrl, serial: flagStr(args, "serial"), apk: flagStr(args, "apk"), packageName: flagStr(args, "package") })
+    } catch (e) {
+      server.close(); watcher?.close()
+      throw e
+    }
+    note(`Android: ${session.serial} → ${deviceUrl} (adb reverse; device logs stream here as [device:log])`)
+    const finish = (code: number) => {
+      session.stop()
+      server.close(); watcher?.close()
+      process.exit(code)
+    }
+    process.on("SIGINT", () => { note("Stopping the app on the phone…"); finish(0) })
+    if (seconds > 0) {
+      setTimeout(() => {
+        const crashes = androidCrashLines(session)
+        if (png) {
+          if (session.screenshot(png)) note(`Wrote ${png} (device screenshot after ${seconds} s)`)
+          else warnErr(`Screenshot failed (adb screencap).`)
+        }
+        if (crashes.length > 0) {
+          warnErr(`The app crashed on the phone:\n${crashes.join("\n")}`)
+          finish(1)
+        }
+        finish(0)
+      }, seconds * 1000)
+    }
+  }
+
   // --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