lecodes-cli 0.20.0 → 0.20.2

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/appDesktop.ts

@@ -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) {

package/src/commands/appShared.ts

@@ -77,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 {

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

@@ -71,6 +71,7 @@ const run = async (args: Args) => {
     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),
@@ -78,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

@@ -8,6 +8,7 @@ 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"
@@ -160,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"}`)
@@ -210,6 +212,46 @@ export const dev = async (args: Args) => {
     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

package/src/commands/projectTemplates.ts

@@ -16,7 +16,7 @@ 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 —
@@ -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
@@ -90,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

@@ -8,6 +8,7 @@ import { desktopDefaultViewport, desktopPluginLibraries, readAppConfigAt, resolv
 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) => ({

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/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")