lecodes-cli 0.19.2 → 0.20.1

package/src/commands/projectTemplates.ts

@@ -16,14 +16,14 @@ from \`main.ts\`.
 
 \`\`\`
 lecodes render                    # semantic JSON of the launched UI (structure, text, names, values)
-lecodes render --png shot.png     # pixels (needs @napi-rs/canvas installed)
+lecodes render --png shot.png     # pixels (the renderer + @napi-rs/canvas install themselves on first use; --yes skips the prompt)
 lecodes render --png card.png --clip card   # ONE component/region: a node name or x,y,w,h
 lecodes render src/screens/cart.ts   # ONE screen module, without booting the app: any file that
                                   # \`export default\`s a UIScreen (or a (state) => UIScreen —
                                   # --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
@@ -36,6 +36,11 @@ lecodes render --desktop --script <file>  # the same scenario on the NATIVE host
 lecodes test                      # all tests/*.flow.json + design-derived flows; run before "done"
 lecodes test --desktop            # the file flows on the NATIVE host (3D/Jolt/real GPU; coordinate
                                   # flows only — design flows stay headless)
+lecodes dev --android --time 12 --png phone.png   # the REAL phone over adb (USB): launches the app on
+                                  # the dev url via adb reverse, streams device logs as [device:log],
+                                  # screenshots after 12 s, force-stops, exit 1 on a crash. --serial
+                                  # <id> with several devices, --apk <file> to install a build first.
+                                  # Without --time it runs until Ctrl+C (which stops the app).
 \`\`\`
 
 Iterate with \`--script\` scenarios and keep the useful ones as \`tests/<name>.flow.json\` — they
@@ -72,8 +77,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
@@ -89,6 +95,13 @@ channel for game state that has no UI.
   with \`"fixtures": "fixtures.json"\` in its envelope.
 - \`fill\` fills every empty input — use it before tapping a disabled-until-filled submit.
 
+## 3D scenes
+
+- A HUD over a \`Scene\` is a widget ATTACHED to it: \`const hud = UIWidget(...).style({ left: 16,
+  bottom: 16, pointerEvents: "none" }); hud.attachTo(scene); hud.show()\`. Never a \`UIScreen\`:
+  a screen is a destination, so \`UIScreen(...).open()\` after \`scene.open()\` CLOSES the scene
+  (the host logs "3D scene closed" and you see only the screen) — no background makes it transparent.
+
 ## SDK documentation
 
 \`.lecodes/types/\` is the exact API surface (signatures only; generated and gitignored — run

package/src/commands/render.ts

@@ -4,10 +4,11 @@ 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"
+import { loadPeer } from "../peerInstall"
 
 /*
  * `lecodes render` — compile the local project and render it headless. By default it emits a
@@ -81,14 +82,9 @@ export const resolveSafeAreaChoice = (explicit: string | undefined, device: stri
   return undefined
 }
 
-/** Import the optional renderer package or fail with the install hint. */
-export const requireRenderer = async (): Promise<typeof import("lecodes-renderer/headless")> => {
-  try {
-    return await import("lecodes-renderer/headless")
-  } catch {
-    throw new CliError("The renderer isn't installed. Run:  npm install -g lecodes-renderer")
-  }
-}
+/** The optional renderer package — installed into ~/.lecodes/peers on first use (peerInstall.ts). */
+export const requireRenderer = async (): Promise<typeof import("lecodes-renderer/headless")> =>
+  loadPeer<typeof import("lecodes-renderer/headless")>("lecodes-renderer", "headless", { for: "lecodes render" })
 
 /** A file-writing ScenarioIO rooted at `dir` (creates parent folders as needed). */
 export const fileScenarioIO = (dir: string) => ({
@@ -196,6 +192,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 +210,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 +232,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/scene.ts

@@ -5,6 +5,7 @@ import { compileSceneEditor } from "../compile/sceneCompile"
 import { localShaderArtifact } from "../compile/shaders"
 import { openBrowser } from "../browserAuth"
 import { CliError, c, flagBool, flagStr, log, note, warnErr, type Args } from "../util"
+import { loadPeer } from "../peerInstall"
 
 /*
  * `lecodes scene [path]` — the 3D scene editor (lecodes-tools/packages/lecodes-3d-editor) hosted on a local project,
@@ -112,12 +113,7 @@ const countScenes = (dir: string): number => {
 export const scene = async (args: Args) => {
   const ctx = getContext(args)
 
-  let sceneServer: typeof import("lecodes-3d-editor/server")
-  try {
-    sceneServer = await import("lecodes-3d-editor/server")
-  } catch {
-    throw new CliError("The scene editor isn't installed. Run:  npm install -g lecodes-3d-editor")
-  }
+  const sceneServer = await loadPeer<typeof import("lecodes-3d-editor/server")>("lecodes-3d-editor", "server", { for: "lecodes scene" })
 
   const port = Number(flagStr(args, "port")) || DEFAULT_PORT
 

package/src/commands/shaders.ts

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs"
+import { relative } from "node:path"
 import { findProjectRoot, readManifest, type Manifest } from "../manifest"
 import { collectLocalEntries } from "../compile/collectLocal"
 import {
@@ -8,6 +9,7 @@ import {
 import { fetchMatcManifest, installedMatcVersions, resolveMatcExe, resolveMatcExeCached, updateMatc } from "../matcTool"
 import { semverNewer } from "../releases"
 import { CliError, c, flagStr, log, note, warnErr, type Args } from "../util"
+import { engineMaterialNames, writeNewShader } from "./shadersNew"
 import { parseShaderSchema, type AnyShaderPlatform } from "lecodes-sdk/compile"
 
 /*
@@ -17,6 +19,9 @@ import { parseShaderSchema, type AnyShaderPlatform } from "lecodes-sdk/compile"
  *   compile     compile every shader in the project into .lecodes/shaders (downloads matc on
  *               first use). `--platform a,b` compiles only those targets.
  *   update      download the newest published matc (run after an engine upgrade)
+ *   new <name>  a fresh .mat + its .material.ts asset in the current dir (--dir elsewhere): the
+ *               starter template, or `--ref lit|unlit|particles|…` = a copy of that engine source
+ *               to start from (shadersNew.ts); --force overwrites
  * matc (Filament's material compiler) caches in ~/.lecodes/matc/; LECODES_MATC overrides it.
  *
  * A shader compiles to one artifact per target: `opengl` + `metal` (mobile profile, Android/Apple),
@@ -148,10 +153,21 @@ const compile = async (args: Args) => {
   note(`${shaders.length} shader${shaders.length === 1 ? "" : "s"} compiled${scope} → ${shadersCacheDir(root)}`)
 }
 
+const newShader = (args: Args) => {
+  const name = args._[1]
+  if (!name) throw new CliError(`lecodes shaders new <name> [--ref ${engineMaterialNames().join("|") || "lit"}] [--dir <folder>] [--force]`)
+  const res = writeNewShader({ name, ref: flagStr(args, "ref"), dir: flagStr(args, "dir"), force: args.flags.force === true })
+  const rel = (p: string) => relative(process.cwd(), p)
+  log(`${rel(res.mat)}  ${c.dim(res.ref ? `(from the engine's ${res.ref}.mat)` : "(the starter template)")}`)
+  log(`${rel(res.asset)}  ${c.dim("(defineMaterial asset — a scene takes it as `material:`)")}`)
+  note(`next: edit it, then \`lecodes shaders compile\` (or just \`lecodes dev\`); in code: Material.load(asset('./${name.replace(/\.mat$/, "")}.mat'))`)
+}
+
 export const shaders = async (args: Args) => {
   const sub = args._[0]
   if (sub === undefined) return status()
   if (sub === "compile") return compile(args)
   if (sub === "update") return updateMatc()
-  throw new CliError(`Unknown subcommand "shaders ${sub}". Use \`lecodes shaders\` (status), \`lecodes shaders compile [--platform a,b]\` or \`lecodes shaders update\`.`)
+  if (sub === "new") return newShader(args)
+  throw new CliError(`Unknown subcommand "shaders ${sub}". Use \`lecodes shaders\` (status), \`lecodes shaders compile [--platform a,b]\`, \`lecodes shaders new <name> [--ref lit]\` or \`lecodes shaders update\`.`)
 }

package/src/commands/shadersNew.ts

@@ -0,0 +1,133 @@
+// `lecodes shaders new <name> [--ref lit] [--dir assets/shaders] [--force]` — a fresh .mat in the
+// project, ready to compile: either the starter template (an unlit material with an annotated
+// parameter of each kind) or a COPY of one of the engine's own sources (`--ref lit`, `--ref unlit`,
+// `--ref particles`…) renamed after the project's file — the way to get vertex colours, an emissive
+// term or a second map onto an otherwise standard material without touching the engine. A
+// `<name>.material.ts` asset goes next to it (defineMaterial with the parameters the .mat declares).
+//
+// The engine's sources come from the CLI's runtime/materials (vendored at build time from
+// creator-gl/materials/src, see scripts/vendor-runtime.ts); in the monorepo the source dir itself
+// is used, so a dev CLI sees the sources as they are.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { basename, join, relative, resolve } from "node:path"
+import { parseShaderSchema } from "lecodes-sdk/compile"
+import { distRoot } from "../distRoot"
+import { CliError } from "../util"
+
+/** where the engine's .mat sources are, or null when this CLI carries none */
+export const engineMaterialsDir = (): string | null => {
+  const candidates = [
+    join(distRoot, "runtime", "materials"),
+    join(distRoot, "..", "creator-gl", "materials", "src"),
+  ]
+  for (const c of candidates) if (existsSync(join(c, "unlit.mat"))) return c
+  return null
+}
+
+/** the sources a `--ref` may name (the common set every host ships; the AR camera ones are not materials to start from) */
+export const engineMaterialNames = (): string[] => {
+  const dir = engineMaterialsDir()
+  if (!dir) return []
+  return readdirSync(dir).filter((f) => f.endsWith(".mat") && !f.startsWith("camera") && f !== "shader360.mat").map((f) => f.slice(0, -4)).sort()
+}
+
+const NAME_RE = /^[a-z][a-z0-9_-]*$/i
+/** the `name :` inside the .mat — an identifier (Filament's rule), so a dash in the file name becomes an underscore */
+const matName = (name: string): string => name.replace(/-/g, "_")
+
+/** the starter: unlit, one parameter of each kind with the editor annotations spelled out */
+export const starterMat = (name: string): string => `// ${name}.mat — a custom material (lecodes shaders new).
+//
+// Filament's material language: the \`material\` block declares the parameters and the render state,
+// \`fragment\` computes the surface. Read it with \`Material.load(asset('./${name}.mat'))\` or the
+// ${name}.material.ts asset beside it; set parameters with material.set('tint', '#ff8800').
+// \`lecodes shaders compile\` (or \`lecodes dev\`) compiles it for every host into .lecodes/shaders.
+//
+// The comment on a parameter's line is what the scene editor shows for it:
+//   @color            a colour picker (also inferred from a name like tint / color / emissive)
+//   @range(min, max)  a slider, @step(s) its step, @default(v) the value a new material starts with
+//   the rest of the line is the tooltip
+
+material {
+    name : ${matName(name)},
+    shadingModel : unlit,
+    parameters : [
+        { type : float3,    name : tint },        // @color @default(#ffffff) the flat colour
+        { type : float,     name : glow },        // @range(0, 2) @step(0.05) @default(1) brightness multiplier
+        { type : sampler2d, name : map }          // the texture, white when unset
+    ],
+    requires : [
+        uv0
+    ]
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        vec4 base = texture(materialParams_map, getUV0());
+        material.baseColor.rgb = base.rgb * materialParams.tint * materialParams.glow;
+    }
+}
+`
+
+/** the engine's source renamed after the file, with a header saying where it came from */
+export const refMat = (name: string, ref: string, source: string): string => {
+  const renamed = source.replace(/(\bname\s*:\s*)([A-Za-z_][A-Za-z0-9_]*)/, `$1${matName(name)}`)
+  return `// ${name}.mat — started from the engine's ${ref}.mat (lecodes shaders new --ref ${ref}); edit freely,
+// the engine keeps its own. \`lecodes shaders compile\` builds it for every host into .lecodes/shaders.
+// Load it with Material.load(asset('./${name}.mat')) or the ${name}.material.ts asset beside it.
+
+${renamed}`
+}
+
+/** the defineMaterial asset for a .mat: every non-sampler parameter with the value the schema gives it */
+export const materialAsset = (name: string, mat: string): string => {
+  const schema = parseShaderSchema(mat)
+  const lines: string[] = []
+  for (const p of schema.params) {
+    if (p.editor === "texture") { lines.push(`    // ${p.name}: asset('./texture.png'),   // a sampler takes an image asset`); continue }
+    if (p.default === null || p.default === undefined) continue
+    lines.push(`    ${p.name}: ${JSON.stringify(p.default)},${p.tooltip ? `   // ${p.tooltip}` : ""}`)
+  }
+  return `// ${name}.material.ts — the material as a project asset: ONE shared instance a scene file takes as
+// \`material: ${camel(name)}\` and code loads with \`await ${camel(name)}.load()\`. The parameters and their
+// widgets come from the annotations in ${name}.mat.
+export default defineMaterial({
+  shader: asset('./${name}.mat'),
+  params: {
+${lines.join("\n")}
+  },
+})
+`
+}
+const camel = (name: string): string => name.replace(/[-_]+(.)/g, (_, ch: string) => ch.toUpperCase())
+
+export type NewShaderOptions = { name: string, ref?: string, dir?: string, force?: boolean, cwd?: string }
+export type NewShaderResult = { mat: string, asset: string, ref: string | null }
+
+/** Write `<name>.mat` and `<name>.material.ts`; returns the paths. Throws a CliError on a bad name,
+ *  an unknown --ref, or files already there (unless `force`). */
+export const writeNewShader = (o: NewShaderOptions): NewShaderResult => {
+  const name = o.name.endsWith(".mat") ? o.name.slice(0, -4) : o.name
+  if (!NAME_RE.test(name)) throw new CliError(`"${o.name}" is not a shader name — letters, digits, - and _ (starting with a letter), e.g. hologram or rim-light`)
+  const dir = resolve(o.cwd ?? process.cwd(), o.dir ?? ".")
+  const matPath = join(dir, `${name}.mat`), assetPath = join(dir, `${name}.material.ts`)
+  if (!o.force) for (const p of [ matPath, assetPath ]) if (existsSync(p)) throw new CliError(`${relative(o.cwd ?? process.cwd(), p) || basename(p)} exists — pick another name or pass --force to overwrite`)
+
+  let mat: string
+  let ref: string | null = null
+  if (o.ref) {
+    ref = o.ref.endsWith(".mat") ? o.ref.slice(0, -4) : o.ref
+    const srcDir = engineMaterialsDir()
+    if (!srcDir) throw new CliError("this CLI carries no engine material sources (runtime/materials) — --ref needs a CLI built with them")
+    const known = engineMaterialNames()
+    if (!known.includes(ref)) throw new CliError(`no engine material "${ref}". Known: ${known.join(", ")}`)
+    mat = refMat(name, ref, readFileSync(join(srcDir, `${ref}.mat`), "utf8"))
+  } else mat = starterMat(name)
+
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(matPath, mat)
+  writeFileSync(assetPath, materialAsset(name, mat))
+  return { mat: matPath, asset: assetPath, ref }
+}

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/commands/thumbs.ts

@@ -3,6 +3,7 @@ import { execFileSync } from "node:child_process"
 import { existsSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { extname, join, relative, resolve } from "node:path"
+import { loadPeer } from "../peerInstall"
 import { projectRootOf } from "./scene"
 import { CliError, c, endProgress, flagBool, flagStr, log, note, progress, toKey, warnErr, type Args } from "../util"
 
@@ -102,12 +103,8 @@ const collect = (dir: string): string[] => {
 export const thumbs = async (args: Args) => {
   const root = projectRootOf(process.cwd())
 
-  let sceneServer: typeof import("lecodes-3d-editor/server")
-  try {
-    sceneServer = await import("lecodes-3d-editor/server")
-  } catch {
-    throw new CliError("The scene editor isn't installed (it owns the preview cache). Run:  npm install -g lecodes-3d-editor")
-  }
+  // The scene editor owns the preview cache — installed into ~/.lecodes/peers on first use.
+  const sceneServer = await loadPeer<typeof import("lecodes-3d-editor/server")>("lecodes-3d-editor", "server", { for: "lecodes thumbs" })
 
   const size = Number(flagStr(args, "size")) || DEFAULT_SIZE
   const force = flagBool(args, "force")

package/src/commands/update.ts

@@ -4,7 +4,8 @@ import { homedir } from "node:os"
 import { dirname, join, resolve } from "node:path"
 import pkg from "../../package.json"
 import { CliError, c, flagBool, log, note, type Args } from "../util"
-import { OPTIONAL_PEERS, peerVersion } from "../peers"
+import { OPTIONAL_PEERS, peerSource, peerVersion } from "../peers"
+import { installPeers } from "../peerInstall"
 import { updateDesktop } from "../desktopRenderer"
 import { updateMatc } from "../matcTool"
 import { types } from "./types"
@@ -20,10 +21,12 @@ import { app } from "./app"
  *   3. shaders   recompile the project's .mat files with that matc                   (= `shaders compile`)
  *   4. types     the IDE types (.lecodes/types + tsconfig) from the server            (= `types`)
  *   5. shells    ios/ + android/ pins → newest SDK release + plugin tags, re-sync     (= `app update`)
- *   6. cli       the GLOBAL npm installs — every installed optional peer (lecodes-renderer,
- *                lecodes-design, lecodes-3d-editor, lecodes-assets) and the CLI itself that is behind
- *                npm's latest: `npm install -g …@latest` (peers first, the CLI last; the standalone
- *                binary can't come from npm — it says so and does the peers only)
+ *   6. cli       the npm installs — every installed optional peer (lecodes-renderer, 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
+ *                (`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)
  *
  * Every step is the existing subcommand, so nothing here can drift from what the individual
  * commands do; this only sequences them and keeps going when one fails (the summary says which).
@@ -148,35 +151,53 @@ export const update = async (args: Args) => {
   await run("cli", "lecodes-cli + its optional peers (global npm installs)", async () => {
     if (flagBool(args, "no-cli")) return ["skipped", "--no-cli"]
     if (FROM_SOURCE) return ["skipped", "running from the repo checkout — the CLI and its peers are the repo's own"]
-    const rows: { name: string, installed: string | null, latest: string | null }[] = []
+    // Where each peer lives decides how it moves: the CLI's own prefix (~/.lecodes/peers, filled on
+    // first use) is re-installed by peerInstall — the renderer there tracks THIS CLI's version, not
+    // npm's latest, because compiler and headless host are one ABI set; a global install
+    // (`npm install -g`, the old way) moves through npm like before.
+    const rows: { name: string, installed: string | null, latest: string | null, where: "global" | "prefix" | null }[] = []
     for (const [name, probe] of OPTIONAL_PEERS) {
+      const where = peerSource(name, probe)
       const installed = peerVersion(name, probe)
-      rows.push({ name, installed, latest: installed ? await npmLatest(name) : null })
+      const latest = !installed ? null
+        : where === "prefix" && name === "lecodes-renderer" ? pkg.version
+        : await npmLatest(name)
+      rows.push({ name, installed, latest, where })
     }
-    rows.push({ name: "lecodes-cli", installed: pkg.version, latest: await npmLatest("lecodes-cli") })
+    rows.push({ name: "lecodes-cli", installed: pkg.version, latest: await npmLatest("lecodes-cli"), where: "global" })
     if (rows.every((r) => r.latest === null)) return ["skipped", "npm unreachable"]
     const behind = rows.filter((r) => r.installed && r.latest && semverNewer(r.latest, r.installed) > 0)
     for (const r of rows) {
-      const state = !r.installed ? c.dim("not installed (optional — npm install -g " + r.name + ")")
+      const state = !r.installed ? c.dim("not installed (optional — installed on first use)")
         : !r.latest ? c.dim("(npm: unknown)")
         : behind.includes(r) ? c.yellow("→ " + r.latest)
         : c.dim("(up to date)")
-      log("  " + r.name.padEnd(18) + " " + (r.installed ?? "").padEnd(8) + " " + state)
+      log("  " + r.name.padEnd(18) + " " + (r.installed ?? "").padEnd(8) + " " + (r.where === "prefix" ? c.dim("peers ") : "") + state)
     }
     if (behind.length === 0) return "ok"
-    const specs = behind.map((r) => r.name + "@latest")
-    if (flagBool(args, "check")) return ["updated", behind.length + " behind — run: npm install -g " + specs.join(" ")]
-    if (STANDALONE && behind.some((r) => r.name === "lecodes-cli")) {
+    const prefixBehind = behind.filter((r) => r.where === "prefix")
+    const globalSpecs = behind.filter((r) => r.where !== "prefix").map((r) => r.name + "@latest")
+    if (flagBool(args, "check")) {
+      return ["updated", behind.length + " behind — run: lecodes update" + (globalSpecs.length ? "  (global: npm install -g " + globalSpecs.join(" ") + ")" : "")]
+    }
+    const done: string[] = []
+    if (prefixBehind.length) {
+      await installPeers(prefixBehind.map((r) => r.name), "lecodes update", { yes: true })
+      done.push(...prefixBehind.map((r) => r.name))
+    }
+    if (STANDALONE && globalSpecs.some((s) => s.startsWith("lecodes-cli@"))) {
       note("this is the standalone build — the CLI updates by re-installing the release archive, not through npm; peers still go through npm")
     }
-    const toInstall = STANDALONE ? specs.filter((s) => !s.startsWith("lecodes-cli@")) : specs
-    if (toInstall.length === 0) return ["skipped", "only the standalone CLI itself is behind — download the release"]
-    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"))
-    const names = toInstall.map((s) => s.replace("@latest", "")).join(", ")
-    const cliToo = toInstall.some((s) => s.startsWith("lecodes-cli@"))
-    return ["updated", names + " → latest" + (cliToo ? " (the new CLI runs from your next command)" : "")]
+    const toInstall = STANDALONE ? globalSpecs.filter((s) => !s.startsWith("lecodes-cli@")) : globalSpecs
+    if (toInstall.length) {
+      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", "")))
+    }
+    if (done.length === 0) return ["skipped", "only the standalone CLI itself is behind — download the release"]
+    const cliToo = done.includes("lecodes-cli")
+    return ["updated", done.join(", ") + " → latest" + (cliToo ? " (the new CLI runs from your next command)" : "")]
   })
 
   // Summary — one line per step so a scrolled-away failure can't hide.

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"
@@ -284,6 +284,10 @@ export type DesktopWindowOpts = {
   minHeight?: number
   resizable?: boolean
   title?: string
+  /** localStorage scope (CREATOR_STORAGE_SCOPE, host ≥1.5.0): the app's stable identity — app.json
+   *  `name` — so a `desktop run` keeps its saved state across runs (the host would otherwise key the
+   *  storage by the launch path, which is a fresh temp dir every run). */
+  storageScope?: string
   /** Borderless fullscreen on the primary monitor (host ≥1.3.0; older hosts ignore the env). */
   fullscreen?: boolean
   /** Display scale: a fixed density (0.5–4) or "fit" (derive from design frame vs monitor/work
@@ -293,22 +297,39 @@ export type DesktopWindowOpts = {
   renderScale?: number
   /** 3D buffer cap [W, H] in px (host ≥1.4.0) — e.g. [1920, 1080] keeps a 4K fullscreen at 1080p 3D. */
   maxRenderSize?: [number, number]
+  /** The mouse button acts as a finger — click-drag scrolls/flings like touch (CREATOR_MOUSE_TOUCH;
+   *  every host reads the env). A CREATOR_MOUSE_TOUCH already in the environment (shell / .env) wins. */
+  mouseEmulateTouch?: boolean
+  /** On-screen keyboard for every input (app.json desktop.virtualKeyboard, host ≥1.5.5): `true` or
+   *  the block, forwarded verbatim as CREATOR_VIRTUAL_KEYBOARD JSON. A set env wins, like the mouse knob. */
+  virtualKeyboard?: boolean | object
   /** Draw the host's frame counter in the corner (host ≥1.5.0; older hosts ignore the env). Costs
    *  nothing to leave off and next to nothing on — the digits are rectangles, no UI behind them. */
   fps?: boolean
   /** 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)
   if (width && height) env.CREATOR_WINDOW_SIZE = `${width}x${height}`
   if (opts.minWidth && opts.minHeight) env.CREATOR_MIN_WINDOW_SIZE = `${opts.minWidth}x${opts.minHeight}`
   if (opts.title) env.CREATOR_WINDOW_TITLE = opts.title
+  if (opts.storageScope) env.CREATOR_STORAGE_SCOPE = opts.storageScope
   if (opts.resizable === false) env.CREATOR_WINDOW_FIXED = "1"
   if (opts.fullscreen !== undefined) env.CREATOR_WINDOW_FULLSCREEN = opts.fullscreen ? "1" : "0"
   if (opts.scale === "fit") env.CREATOR_UI_SCALE = "fit"
@@ -318,6 +339,12 @@ const windowEnv = (opts: DesktopWindowOpts): Record<string, string> => {
     env.CREATOR_RENDER_MAX = `${Math.round(opts.maxRenderSize[0])}x${Math.round(opts.maxRenderSize[1])}`
   }
   if (opts.fps) env.CREATOR_FPS = "1"
+  if (opts.mouseEmulateTouch !== undefined && process.env.CREATOR_MOUSE_TOUCH === undefined) {
+    env.CREATOR_MOUSE_TOUCH = opts.mouseEmulateTouch ? "1" : "0"
+  }
+  if (opts.virtualKeyboard !== undefined && process.env.CREATOR_VIRTUAL_KEYBOARD === undefined) {
+    env.CREATOR_VIRTUAL_KEYBOARD = typeof opts.virtualKeyboard === "boolean" ? (opts.virtualKeyboard ? "1" : "0") : JSON.stringify(opts.virtualKeyboard)
+  }
   return env
 }
 
@@ -356,6 +383,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 +511,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/desktopScript.ts

@@ -40,7 +40,7 @@ export type DesktopPlan = {
 }
 
 const ACTIONS = ["tap", "type", "fill", "scroll", "wait", "frames", "drag", "hold", "key", "keyDown", "keyUp", "look", "mouseTo", "wheel", "stick", "gamepad", "camera", "view"] as const
-const SEMANTIC_EXPECT = ["text", "notText", "node", "notNode", "screen", "value"]
+const SEMANTIC_EXPECT = ["text", "notText", "node", "notNode", "screen", "value", "audio"]
 const VIEW_NAMES = ["iso", "top", "front", "side", "back"]
 const isVec3 = (v: unknown): v is [number, number, number] => Array.isArray(v) && v.length === 3 && v.every((n) => typeof n === "number")