lecodes-cli 0.20.0 → 0.20.1

package/dist/index.js

@@ -47,6 +47,78 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
+// package.json
+var package_default;
+var init_package = __esm(() => {
+  package_default = {
+    name: "lecodes-cli",
+    version: "0.20.1",
+    dependencies: {
+      "@letary/chisel": "^0.10.0",
+      jimp: "^1.6.1",
+      "lecodes-sdk": "workspace:*"
+    },
+    devDependencies: {
+      "lecodes-design": "^0.9.0",
+      "lecodes-renderer": "workspace:*",
+      "qrcode-terminal": "^0.12.0",
+      "lecodes-3d-editor": "^0.7.0",
+      "lecodes-assets": "workspace:*",
+      "lecodes-creator-nav": "workspace:*",
+      "lecodes-viewer-lite": "workspace:*"
+    },
+    peerDependencies: {
+      "lecodes-design": "^0.9.0",
+      "lecodes-renderer": "^0.20.0",
+      "lecodes-3d-editor": "^0.7.0",
+      "lecodes-assets": "^0.2.1"
+    },
+    bin: {
+      lecodes: "dist/index.js"
+    },
+    description: "Clone, edit and push LeCodes projects from your machine.",
+    engines: {
+      node: ">=18"
+    },
+    files: [
+      "dist",
+      "src",
+      "runtime",
+      "README.md"
+    ],
+    keywords: [
+      "lecodes",
+      "cli"
+    ],
+    license: "MIT",
+    peerDependenciesMeta: {
+      "lecodes-design": {
+        optional: true
+      },
+      "lecodes-renderer": {
+        optional: true
+      },
+      "lecodes-3d-editor": {
+        optional: true
+      },
+      "lecodes-assets": {
+        optional: true
+      }
+    },
+    scripts: {
+      icon: "bun scripts/make-icon.ts",
+      "vendor-runtime": "bun scripts/vendor-runtime.ts",
+      "sync-peers": "bun scripts/sync-peer-versions.ts",
+      build: 'bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-renderer --external lecodes-design --external lecodes-3d-editor --external lecodes-assets --banner="#!/usr/bin/env node"',
+      "build:bin": "bun scripts/build-bin.ts",
+      typecheck: "tsc --noEmit",
+      dev: "bun run src/index.ts",
+      prepublishOnly: "bun run sync-peers && bun run build"
+    },
+    type: "module"
+  };
+});
+
 // ../sdk/src/compile/assetName.ts
 var inRanges = (cp, ranges) => ranges.some(([from, to]) => cp >= from && cp <= to), INVISIBLE, ODD_SPACE, ILLEGAL = '/\\:*?"<>|', sanitizeAssetName = (name) => {
   let out = "";
@@ -3177,7 +3249,7 @@ var require_source_map_support = __commonJS((exports, module) => {
 
 // ../../node_modules/.bun/typescript@5.8.3/node_modules/typescript/lib/typescript.js
 var require_typescript = __commonJS((exports, module) => {
-  var __dirname = "/Users/den/Desktop/Ingenuity/le-codes/node_modules/.bun/typescript@5.8.3/node_modules/typescript/lib", __filename = "/Users/den/Desktop/Ingenuity/le-codes/node_modules/.bun/typescript@5.8.3/node_modules/typescript/lib/typescript.js";
+  var __dirname = "C:\\Users\\Den\\Desktop\\LeCodes\\lecodes\\node_modules\\.bun\\typescript@5.8.3\\node_modules\\typescript\\lib", __filename = "C:\\Users\\Den\\Desktop\\LeCodes\\lecodes\\node_modules\\.bun\\typescript@5.8.3\\node_modules\\typescript\\lib\\typescript.js";
   /*! *****************************************************************************
   Copyright (c) Microsoft Corporation. All rights reserved.
   Licensed under the Apache License, Version 2.0 (the "License"); you may not use
@@ -172165,17 +172237,12 @@ var buildHeader = (name, code, opts = {}) => {
 };
 
 // ../sdk/src/compile/compileProject.ts
-var compileProject = async (opts) => {
-  const entries = stubServerEntries(opts.entries, opts.serverUrl ?? "");
-  const entry = opts.entryOverride ?? detectEntry(entries, scanModulesChisel).entry;
-  if (!entry) {
-    throw new Error("Couldn't find an entrypoint (no .ts/.js project file — name yours main.ts). Pass entryOverride.");
-  }
+var entriesToFiles = (entries, opts) => {
   const files = {};
   for (const e of entries) {
     if (e.type === "resource") {
       if (opts.localAssets && !e.remote) {
-        const name = e.path.split(/[\\/]/).pop() ?? e.path;
+        const name = e.path.split(/[\/]/).pop() ?? e.path;
         files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(name)}))`;
       } else {
         files[e.path] = `export default "${opts.publicUrl}${e.fileSrc ?? ""}"`;
@@ -172183,7 +172250,7 @@ var compileProject = async (opts) => {
     } else if (e.type === "shader") {
       const shaders = e.shaders ?? [];
       if (e.shadersLocal && shaders.length > 0) {
-        const name = shaders[0].src.split(/[\\/]/).pop() ?? "";
+        const name = shaders[0].src.split(/[\/]/).pop() ?? "";
         const [prefix, suffix = ".filamat"] = name.split("_opengl");
         files[e.path] = `export default ("id:" + _creatorUtils.fetchLocal(${JSON.stringify(prefix + "_")} + _creator.backend + ${JSON.stringify(suffix)}))`;
       } else if (shaders.length > 0) {
@@ -172199,17 +172266,24 @@ var compileProject = async (opts) => {
       files[e.path] = e.text ?? "";
     }
   }
-  const { code, map } = await bundleProjectWithMap(entry, files, opts.format ?? "esm", opts.minify, opts.editor, opts.libraries, opts.sourcemap ?? true);
-  if (opts.header === false) {
-    return map ? `${code}
-${inlineSourceMapComment(map)}` : code;
+  return files;
+}, compileProjectWithMap = async (opts) => {
+  const entries = stubServerEntries(opts.entries, opts.serverUrl ?? "");
+  const entry = opts.entryOverride ?? detectEntry(entries, scanModulesChisel).entry;
+  if (!entry) {
+    throw new Error("Couldn't find an entrypoint (no .ts/.js project file — name yours main.ts). Pass entryOverride.");
   }
+  const files = entriesToFiles(entries, opts);
+  const { code, map } = await bundleProjectWithMap(entry, files, opts.format ?? "esm", opts.minify, opts.editor, opts.libraries, opts.sourcemap ?? true);
+  if (opts.header === false)
+    return { code, map, entry };
   const header = buildHeader(opts.name, code, { icon: opts.icon, fonts: opts.fontsHeader, icons: opts.iconsHeader });
-  if (!map)
-    return header + code;
   const headerLines = (header.match(/\n/g) ?? []).length;
-  return `${header}${code}
-${inlineSourceMapComment(offsetSourceMap(map, headerLines))}`;
+  return { code: header + code, map: map ? offsetSourceMap(map, headerLines) : null, entry };
+}, compileProject = async (opts) => {
+  const { code, map } = await compileProjectWithMap(opts);
+  return map ? `${code}
+${inlineSourceMapComment(map)}` : code;
 };
 var init_compileProject = __esm(() => {
   init_bundler();
@@ -173144,10 +173218,12 @@ __export(exports_compile, {
   faceFileName: () => faceFileName,
   extractMatBlocks: () => extractMatBlocks,
   externalSamplerReg: () => externalSamplerReg,
+  entriesToFiles: () => entriesToFiles,
   detectProjectKind: () => detectProjectKind,
   detectEntry: () => detectEntry,
   deriveEndpointParams: () => deriveEndpointParams,
   compileServerBundle: () => compileServerBundle,
+  compileProjectWithMap: () => compileProjectWithMap,
   compileProject: () => compileProject,
   collectVendoredIcons: () => collectVendoredIcons,
   bundleProjectWithMap: () => bundleProjectWithMap,
@@ -214370,7 +214446,7 @@ var init_browserAuth = __esm(() => {
   init_util();
 });
 
-// ../../../lecodes-tools/packages/lecodes-design/src/core/concept.ts
+// ../../node_modules/.bun/lecodes-design@0.9.0+edf5a69441922373/node_modules/lecodes-design/src/core/concept.ts
 var SPEC_TEMPLATE = `# Concept
 
 The narrative half of this design. \`meta.json\` + the canvas hold the *visual/flow* half (screens,
@@ -214406,7 +214482,7 @@ Behaviour that isn't visible in a single screen — validation, permissions, not
 cases — and the decisions you've made and why, so they aren't re-litigated later.
 `;
 
-// ../../../lecodes-tools/packages/lecodes-design/src/templates.ts
+// ../../node_modules/.bun/lecodes-design@0.9.0+edf5a69441922373/node_modules/lecodes-design/src/templates.ts
 var SPEC_MD, META_JSON = `{
   "screens": {
     "home": { "pos": [0, 0], "desc": "Example screen — replace me", "role": "list" }
@@ -214845,12 +214921,179 @@ var init_designTemplates = __esm(() => {
   init_templates();
 });
 
+// src/peers.ts
+import { existsSync as existsSync24, readFileSync as readFileSync20 } from "node:fs";
+import { createRequire as createRequire5 } from "node:module";
+import { homedir as homedir8 } from "node:os";
+import { dirname as dirname14, join as join24, resolve as resolve11 } from "node:path";
+var OPTIONAL_PEERS, peersDir = () => process.env.LECODES_PEERS_DIR ? resolve11(process.env.LECODES_PEERS_DIR) : join24(homedir8(), ".lecodes", "peers"), peerDirInPrefix = (name) => join24(peersDir(), "node_modules", ...name.split("/")), readVersion = (dir) => {
+  try {
+    return JSON.parse(readFileSync20(join24(dir, "package.json"), "utf8")).version ?? "unknown";
+  } catch {
+    return null;
+  }
+}, peerVersionGlobal = (name, probe) => {
+  try {
+    const require2 = createRequire5(import.meta.url);
+    let dir = dirname14(require2.resolve(probe));
+    for (let depth = 0;depth < 16; depth++) {
+      const manifest = join24(dir, "package.json");
+      if (existsSync24(manifest)) {
+        const parsed = JSON.parse(readFileSync20(manifest, "utf8"));
+        if (parsed.name === name)
+          return parsed.version ?? "unknown";
+      }
+      const parent = dirname14(dir);
+      if (parent === dir)
+        break;
+      dir = parent;
+    }
+  } catch {}
+  return null;
+}, peerVersionPrefix = (name) => readVersion(peerDirInPrefix(name)), peerVersion = (name, probe) => peerVersionGlobal(name, probe) ?? peerVersionPrefix(name), peerSource = (name, probe) => peerVersionGlobal(name, probe) !== null ? "global" : peerVersionPrefix(name) !== null ? "prefix" : null;
+var init_peers = __esm(() => {
+  OPTIONAL_PEERS = [
+    ["lecodes-renderer", "lecodes-renderer/headless"],
+    ["lecodes-design", "lecodes-design/server"],
+    ["lecodes-3d-editor", "lecodes-3d-editor/server"],
+    ["lecodes-assets", "lecodes-assets/cli"],
+    ["@napi-rs/canvas", "@napi-rs/canvas"]
+  ];
+});
+
+// src/peerInstall.ts
+import { spawnSync as spawnSync6 } from "node:child_process";
+import { existsSync as existsSync25, mkdirSync as mkdirSync18, readFileSync as readFileSync21, writeFileSync as writeFileSync19 } from "node:fs";
+import { join as join25 } from "node:path";
+import { pathToFileURL } from "node:url";
+async function loadPeer(name, subpath, opts) {
+  const spec = subpath ? `${name}/${subpath}` : name;
+  try {
+    return await import(spec);
+  } catch (e2) {
+    if (!isNotFound(e2, spec))
+      throw e2;
+  }
+  const dir = peerDirInPrefix(name);
+  if (!existsSync25(join25(dir, "package.json"))) {
+    if (opts.install === false)
+      return null;
+    if (peerVersionGlobal(name, spec) !== null)
+      throw new CliError(`${name} is installed but "${spec}" can't be loaded from it — reinstall it: npm install -g ${peerSpec(name)}`);
+    await installPeers(companions(name), opts.for);
+  }
+  return await import(pathToFileURL(resolveEntry(dir, subpath)).href);
+}
+var CANVAS_RANGE_FALLBACK = "^0.1.65", readJson2 = (path2) => {
+  try {
+    return JSON.parse(readFileSync21(path2, "utf8"));
+  } catch {
+    return null;
+  }
+}, peerSpec = (name) => {
+  if (name === "lecodes-renderer")
+    return `lecodes-renderer@${package_default.version}`;
+  if (name === "@napi-rs/canvas") {
+    const renderer = readJson2(join25(peerDirInPrefix("lecodes-renderer"), "package.json"));
+    const range2 = renderer?.peerDependencies?.["@napi-rs/canvas"] ?? renderer?.optionalDependencies?.["@napi-rs/canvas"] ?? CANVAS_RANGE_FALLBACK;
+    return `@napi-rs/canvas@${range2}`;
+  }
+  const range = package_default.peerDependencies?.[name];
+  return range ? `${name}@${range}` : `${name}@latest`;
+}, companions = (name) => name === "lecodes-renderer" ? ["lecodes-renderer", "@napi-rs/canvas"] : [name], onPath = (cmd) => {
+  try {
+    return spawnSync6(cmd, ["--version"], { stdio: "ignore", shell: process.platform === "win32" }).status === 0;
+  } catch {
+    return false;
+  }
+}, pickInstaller = () => onPath("npm") ? "npm" : onPath("bun") ? "bun" : null, manualCommand = (dir, specs) => `npm install --prefix "${dir}" ${specs.join(" ")}`, installPeers = async (names3, why, opts = {}) => {
+  const dir = peersDir();
+  mkdirSync18(dir, { recursive: true });
+  const manifest = join25(dir, "package.json");
+  if (!existsSync25(manifest)) {
+    writeFileSync19(manifest, JSON.stringify({
+      name: "lecodes-peers",
+      private: true,
+      description: "Optional lecodes-cli peers, installed on first use. Safe to delete — the CLI re-installs what a command needs."
+    }, null, 2) + `
+`);
+  }
+  const ordered = [...names3].sort((a2, b) => a2 === "lecodes-renderer" ? -1 : b === "lecodes-renderer" ? 1 : 0);
+  const specsNow = ordered.map(peerSpec);
+  const yes = opts.yes === true || !!process.env.LECODES_YES;
+  if (!yes) {
+    const interactive = process.stdin.isTTY && process.stdout.isTTY;
+    if (!interactive) {
+      throw new CliError(`${why} needs ${names3.join(" + ")}, which isn't installed. Re-run with --yes to install it into ${dir}, or install by hand:  ${manualCommand(dir, specsNow)}`);
+    }
+    log(`${why} needs ${c.bold(names3.join(" + "))}.`);
+    log(c.dim(`It installs once into ${dir} (no admin rights); a newer CLI re-installs its own version.`));
+    if (!await confirm("Install now?", true)) {
+      throw new CliError(`Not installed. When you want it:  ${manualCommand(dir, specsNow)}`);
+    }
+  }
+  const tool = pickInstaller();
+  if (!tool)
+    throw new CliError(`Neither npm nor bun is on PATH, so ${names3.join(" + ")} can't be installed automatically. Install one, or run on a machine with Node:  ${manualCommand(dir, specsNow)}`);
+  for (const name of ordered) {
+    const spec = peerSpec(name);
+    const argv = tool === "npm" ? ["install", "--prefix", dir, "--no-audit", "--no-fund", "--loglevel=error", spec] : ["add", "--cwd", dir, spec];
+    note(`$ ${tool} ${argv.join(" ")}`);
+    const r2 = spawnSync6(tool, argv, { stdio: "inherit", shell: process.platform === "win32", timeout: 10 * 60000 });
+    if (r2.error)
+      throw new CliError(`${tool} could not run: ${r2.error.message}`);
+    if (r2.status !== 0)
+      throw new CliError(`${tool} exited with ${r2.status ?? "a signal"} while installing ${spec}. By hand:  ${manualCommand(dir, [spec])}`);
+    if (!existsSync25(join25(peerDirInPrefix(name), "package.json")))
+      throw new CliError(`${name} did not land in ${dir} — the installer finished but the package is missing`);
+  }
+}, resolveEntry = (pkgDir, subpath) => {
+  const manifest = readJson2(join25(pkgDir, "package.json"));
+  if (!manifest)
+    throw new CliError(`${pkgDir} holds no package.json`);
+  const key = subpath ? `./${subpath}` : ".";
+  const pick = (target) => {
+    if (typeof target === "string")
+      return target;
+    if (target && typeof target === "object") {
+      const t2 = target;
+      for (const cond of ["import", "node", "default", "require"])
+        if (cond in t2) {
+          const p2 = pick(t2[cond]);
+          if (p2)
+            return p2;
+        }
+    }
+    return null;
+  };
+  let rel = null;
+  const exp = manifest.exports;
+  if (typeof exp === "string")
+    rel = key === "." ? exp : null;
+  else if (exp && typeof exp === "object")
+    rel = pick(exp[key]);
+  if (!rel && key === ".")
+    rel = typeof manifest.main === "string" ? manifest.main : "index.js";
+  if (!rel)
+    throw new CliError(`${manifest.name} has no export "${key}"`);
+  return join25(pkgDir, rel);
+}, isNotFound = (e2, spec) => {
+  const code = e2?.code;
+  const msg = e2 instanceof Error ? e2.message : String(e2);
+  return (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || /Cannot find (module|package)/i.test(msg)) && msg.includes(spec.split("/")[0]);
+};
+var init_peerInstall = __esm(() => {
+  init_package();
+  init_peers();
+  init_util();
+});
+
 // src/designMeta.ts
-import { readFileSync as readFileSync20 } from "node:fs";
-import { join as join24 } from "node:path";
+import { readFileSync as readFileSync22 } from "node:fs";
+import { join as join26 } from "node:path";
 var PHONE_SIZE, readMetaFrames = (designDir) => {
   try {
-    const meta = JSON.parse(readFileSync20(join24(designDir, "meta.json"), "utf8"));
+    const meta = JSON.parse(readFileSync22(join26(designDir, "meta.json"), "utf8"));
     const d = meta?.defaultSize;
     const valid = Array.isArray(d) && d.length === 2 && d.every((n2) => typeof n2 === "number" && Number.isFinite(n2) && n2 >= 64 && n2 <= 8192);
     return {
@@ -214874,8 +215117,8 @@ __export(exports_design, {
   flushDesignComments: () => flushDesignComments,
   design: () => design
 });
-import { existsSync as existsSync24, mkdirSync as mkdirSync18, readFileSync as readFileSync21, readdirSync as readdirSync14, writeFileSync as writeFileSync19, appendFileSync } from "node:fs";
-import { basename as basename11, join as join25 } from "node:path";
+import { existsSync as existsSync26, mkdirSync as mkdirSync19, readFileSync as readFileSync23, readdirSync as readdirSync14, writeFileSync as writeFileSync20, appendFileSync } from "node:fs";
+import { basename as basename11, join as join27 } from "node:path";
 var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
   let root;
   let manifest;
@@ -214892,19 +215135,14 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
     manifest,
     name: manifest?.name ?? basename11(root),
     dirName,
-    designDir: join25(root, dirName),
+    designDir: join27(root, dirName),
     designKey: "/" + dirName.replace(/\\/g, "/")
   };
 }, loadDesignServer = async (ctx, needs = []) => {
-  if (!existsSync24(ctx.designDir)) {
+  if (!existsSync26(ctx.designDir)) {
     throw new CliError(`No ${ctx.dirName}/ folder here. Run "lecodes design init" to scaffold it.`);
   }
-  let mod;
-  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("lecodes-design", "server", { for: "lecodes design" });
   const missing = needs.filter((name) => typeof mod[name] !== "function");
   if (missing.length) {
     throw new CliError(`This needs a newer lecodes-design — the installed one has no \`${missing[0]}\`. Run:  npm install -g lecodes-design@latest`);
@@ -214912,7 +215150,7 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
   return mod;
 }, requirePlatform = (ctx, verb) => {
   if (!ctx.manifest) {
-    throw new CliError(`\`lecodes design comments ${verb}\` needs a cloned project. This folder is standalone, so ${ctx.dirName}/comments/ is already the only store — there is nothing to sync with.`);
+    throw new CliError(`\`lecodes design comments ${verb}\` needs a cloned project. This folder is standalone, so ` + `${ctx.dirName}/comments/ is already the only store — there is nothing to sync with.`);
   }
   const config = loadConfig();
   return { apiUrl: requireApiUrl(config), token: requireToken(config), uuid: ctx.manifest.uuid };
@@ -214928,17 +215166,17 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
 `).find((l2) => l2.trim())?.trim() ?? "";
   return line.length > max ? line.slice(0, max - 1) + "…" : line;
 }, listScreens = (designDir) => {
-  const dir = join25(designDir, "screens");
-  if (!existsSync24(dir))
+  const dir = join27(designDir, "screens");
+  if (!existsSync26(dir))
     return [];
   return readdirSync14(dir).filter((f3) => f3.endsWith(".ts") && !f3.startsWith(".")).map((f3) => f3.slice(0, -3)).sort();
 }, writeMcpConfig = (ctx, port) => {
-  const path2 = join25(ctx.root, ".mcp.json");
+  const path2 = join27(ctx.root, ".mcp.json");
   const entry = { type: "http", url: `http://localhost:${port}/mcp` };
   let config = {};
-  if (existsSync24(path2)) {
+  if (existsSync26(path2)) {
     try {
-      config = JSON.parse(readFileSync21(path2, "utf8"));
+      config = JSON.parse(readFileSync23(path2, "utf8"));
     } catch {
       warnErr(".mcp.json exists but isn't valid JSON — left it untouched. Add the lecodes-design server by hand.");
       return;
@@ -214951,7 +215189,7 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
     return;
   }
   config.mcpServers["lecodes-design"] = entry;
-  writeFileSync19(path2, JSON.stringify(config, null, 2) + `
+  writeFileSync20(path2, JSON.stringify(config, null, 2) + `
 `);
   log(`${c.green(existing ? "updated" : "created")}   .mcp.json (lecodes-design MCP → ${entry.url})`);
 }, init = async (ctx, args) => {
@@ -214960,26 +215198,26 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
     ["spec.md", SPEC_MD],
     ["README.md", README_HINT],
     ["CLAUDE.md", CLAUDE_MD],
-    [join25("shared", "tokens.ts"), TOKENS_TS],
-    [join25("shared", "tabs.ts"), TABS_TS],
-    [join25("screens", "home.ts"), HOME_SCREEN_TS]
+    [join27("shared", "tokens.ts"), TOKENS_TS],
+    [join27("shared", "tabs.ts"), TABS_TS],
+    [join27("screens", "home.ts"), HOME_SCREEN_TS]
   ];
-  mkdirSync18(join25(ctx.designDir, "screens"), { recursive: true });
-  mkdirSync18(join25(ctx.designDir, "shared"), { recursive: true });
+  mkdirSync19(join27(ctx.designDir, "screens"), { recursive: true });
+  mkdirSync19(join27(ctx.designDir, "shared"), { recursive: true });
   let created = 0;
   for (const [rel, content] of files) {
-    const abs = join25(ctx.designDir, rel);
-    if (existsSync24(abs)) {
+    const abs = join27(ctx.designDir, rel);
+    if (existsSync26(abs)) {
       note(`kept      ${ctx.dirName}/${rel.replace(/\\/g, "/")}`);
       continue;
     }
-    writeFileSync19(abs, content);
+    writeFileSync20(abs, content);
     log(`${c.green("created")}   ${ctx.dirName}/${rel.replace(/\\/g, "/")}`);
     created++;
   }
-  const ignorePath = join25(ctx.root, ".lecodesignore");
+  const ignorePath = join27(ctx.root, ".lecodesignore");
   const ignoreLines = [`${ctx.dirName}/.snapshots/`, `${ctx.dirName}/comments/`];
-  const current = existsSync24(ignorePath) ? readFileSync21(ignorePath, "utf8") : "";
+  const current = existsSync26(ignorePath) ? readFileSync23(ignorePath, "utf8") : "";
   const present = new Set(current.split(/\r?\n/));
   const missing = ignoreLines.filter((line) => !present.has(line));
   if (missing.length) {
@@ -214994,8 +215232,8 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
   writeMcpConfig(ctx, Number(flagStr(args, "port")) || DEFAULT_PORT);
   const wroteTypes = materializeTypesLocal(ctx.designDir);
   writeTsconfig(ctx.designDir);
-  mkdirSync18(join25(ctx.designDir, ".lecodes", "types"), { recursive: true });
-  writeFileSync19(join25(ctx.designDir, ".lecodes", "types", "design-macros.d.ts"), DESIGN_MACROS_DTS);
+  mkdirSync19(join27(ctx.designDir, ".lecodes", "types"), { recursive: true });
+  writeFileSync20(join27(ctx.designDir, ".lecodes", "types", "design-macros.d.ts"), DESIGN_MACROS_DTS);
   log(`${c.green("created")}   ${ctx.dirName}/tsconfig.json${wroteTypes ? ` + ${ctx.dirName}/.lecodes/types/` : ""}  (IDE types)`);
   if (!wroteTypes)
     warnErr("Bundled SDK types not found — tsconfig written, but globals may show unresolved until the CLI is rebuilt with vendored types.");
@@ -215018,23 +215256,14 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (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;
-  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("lecodes-renderer", "headless", { for: "lecodes design render" });
   let discover = 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("lecodes-design", "server", { for: "lecodes design render --state" });
+    discover = (src) => {
+      const d = ds.discoverScreenStates(src);
+      return { states: d.states, canonical: d.canonical };
+    };
   }
   const killer = setTimeout(() => {
     warnErr("Snapshot timed out after 120s.");
@@ -215043,16 +215272,16 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
   killer.unref?.();
   const png2 = flagBool(args, "png") || flagStr(args, "png") !== undefined;
   const frames = readMetaFrames(ctx.designDir);
-  const outDir = flagStr(args, "out-dir") ?? join25(ctx.designDir, ".snapshots");
+  const outDir = flagStr(args, "out-dir") ?? join27(ctx.designDir, ".snapshots");
   const single = targets.length === 1 && requested.length === 1 && !png2 && !allStates && !flagStr(args, "out-dir");
   const onConsole = flagBool(args, "logs") ? (level, text) => logErr(`${c.dim(`[${level}]`)} ${text}`) : undefined;
   if (!single)
-    mkdirSync18(outDir, { recursive: true });
+    mkdirSync19(outDir, { recursive: true });
   for (const id of targets) {
     const [width, height] = frames.screens[id]?.size ?? frames.defaultSize;
     let plan = [{ state: undefined, bases: [id] }];
     if (discover) {
-      const { states, canonical } = discover(readFileSync21(join25(ctx.designDir, "screens", `${id}.ts`), "utf8"));
+      const { states, canonical } = discover(readFileSync23(join27(ctx.designDir, "screens", `${id}.ts`), "utf8"));
       if (stateFlag !== undefined) {
         if (!states.includes(stateFlag)) {
           if (requested.length === 1)
@@ -215093,11 +215322,11 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
         for (const w of pngResult.warnings)
           warnErr(`${tag}: ${w}`);
       for (const base of bases) {
-        writeFileSync19(join25(outDir, `${base}.json`), result.text);
-        log(`${c.green("✓")} ${tag} → ${join25(outDir, `${base}.json`)}`);
+        writeFileSync20(join27(outDir, `${base}.json`), result.text);
+        log(`${c.green("✓")} ${tag} → ${join27(outDir, `${base}.json`)}`);
         if (pngResult) {
-          writeFileSync19(join25(outDir, `${base}.png`), pngResult.png);
-          log(`${c.green("✓")} ${tag} → ${join25(outDir, `${base}.png`)}`);
+          writeFileSync20(join27(outDir, `${base}.png`), pngResult.png);
+          log(`${c.green("✓")} ${tag} → ${join27(outDir, `${base}.png`)}`);
         }
       }
     }
@@ -215105,12 +215334,7 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
 }, serve = async (ctx, args) => {
   const designServer = await loadDesignServer(ctx);
   const port = Number(flagStr(args, "port")) || DEFAULT_PORT;
-  let renderer = null;
-  try {
-    renderer = await import("lecodes-renderer/headless");
-  } catch {
-    renderer = null;
-  }
+  const renderer = await loadPeer("lecodes-renderer", "headless", { for: "lecodes design (render_screen)", install: false });
   const renderScreen = renderer ? async (id, format, state) => {
     const r2 = renderer;
     const js = await compileDesignScreen({
@@ -215399,17 +215623,14 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
     note("Read them with:  lecodes design comments");
 }, flushDesignComments = async (args) => {
   const ctx = getContext(args);
-  if (!existsSync24(ctx.designDir))
+  if (!existsSync26(ctx.designDir))
     return null;
   const platform = optionalPlatform(ctx);
   if (!platform)
     return null;
-  let designServer;
-  try {
-    designServer = await import("lecodes-design/server");
-  } catch {
+  const designServer = await loadPeer("lecodes-design", "server", { for: "lecodes design", install: false });
+  if (!designServer)
     return null;
-  }
   if (typeof designServer.queuedThreads !== "function")
     return null;
   if (typeof designServer.settleQueued !== "function" || designServer.settleQueued.length < 4)
@@ -215516,6 +215737,7 @@ var init_design = __esm(() => {
   init_browserAuth();
   init_designTemplates();
   init_util();
+  init_peerInstall();
   init_config();
   init_api();
   init_types4();
@@ -216538,74 +216760,9 @@ var require_main = __commonJS((exports, module) => {
     }
   };
 });
-// package.json
-var package_default = {
-  name: "lecodes-cli",
-  version: "0.20.0",
-  dependencies: {
-    "@letary/chisel": "^0.10.0",
-    jimp: "^1.6.1",
-    "lecodes-sdk": "workspace:*"
-  },
-  devDependencies: {
-    "lecodes-design": "link:lecodes-design",
-    "lecodes-renderer": "workspace:*",
-    "qrcode-terminal": "^0.12.0",
-    "lecodes-3d-editor": "link:lecodes-3d-editor",
-    "lecodes-assets": "workspace:*",
-    "lecodes-creator-nav": "workspace:*",
-    "lecodes-viewer-lite": "workspace:*"
-  },
-  peerDependencies: {
-    "lecodes-design": "^0.9.0",
-    "lecodes-renderer": "^0.20.0",
-    "lecodes-3d-editor": "^0.7.0",
-    "lecodes-assets": "^0.2.1"
-  },
-  bin: {
-    lecodes: "dist/index.js"
-  },
-  description: "Clone, edit and push LeCodes projects from your machine.",
-  engines: {
-    node: ">=18"
-  },
-  files: [
-    "dist",
-    "src",
-    "runtime",
-    "README.md"
-  ],
-  keywords: [
-    "lecodes",
-    "cli"
-  ],
-  license: "MIT",
-  peerDependenciesMeta: {
-    "lecodes-design": {
-      optional: true
-    },
-    "lecodes-renderer": {
-      optional: true
-    },
-    "lecodes-3d-editor": {
-      optional: true
-    },
-    "lecodes-assets": {
-      optional: true
-    }
-  },
-  scripts: {
-    icon: "bun scripts/make-icon.ts",
-    "vendor-runtime": "bun scripts/vendor-runtime.ts",
-    "sync-peers": "bun scripts/sync-peer-versions.ts",
-    build: 'bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-renderer --external lecodes-design --external lecodes-3d-editor --external lecodes-assets --banner="#!/usr/bin/env node"',
-    "build:bin": "bun scripts/build-bin.ts",
-    typecheck: "tsc --noEmit",
-    dev: "bun run src/index.ts",
-    prepublishOnly: "bun run sync-peers && bun run build"
-  },
-  type: "module"
-};
+
+// src/index.ts
+init_package();
 
 // src/commands/app.ts
 init_manifest();
@@ -216769,6 +216926,11 @@ var semverNewer = (a, b) => {
       return (pb[i] ?? 0) - (pa[i] ?? 0);
   return 0;
 };
+var newestForPlatform = (versions, key) => {
+  const carrying = versions.filter((v) => v.files[key]).sort((a, b) => semverNewer(a.version, b.version));
+  const newest = carrying[0];
+  return newest ? { version: newest.version, file: newest.files[key] } : null;
+};
 var fetchReleaseProduct = async (product, label) => {
   let manifest;
   try {
@@ -216873,12 +217035,15 @@ var installedMatcVersions = () => {
   }
 };
 var fetchMatcManifest = () => fetchReleaseProduct("matc", "matc (shader compiler)");
-var downloadMatc = async (version, versions, dest) => {
+var pickMatc = (versions) => {
   const key = platformKey();
-  const file = versions.find((v) => v.version === version)?.files[key];
-  if (!file) {
-    throw new CliError(`matc ${version} [${key}] isn't published — push the project once so shaders compile on the ` + `server, or set LECODES_MATC to a locally built matc.`);
+  const hit = newestForPlatform(versions, key);
+  if (!hit) {
+    throw new CliError(`matc isn't published for ${key} — push the project once so shaders compile on the ` + `server, or set LECODES_MATC to a locally built matc.`);
   }
+  return hit;
+};
+var downloadMatc = async (version, file, dest) => {
   note(`Downloading the shader compiler (matc ${version}, ${(file.size / 1024 / 1024).toFixed(1)} MB)…`);
   await downloadReleaseArchive(file, {
     cacheRoot: cacheRoot(),
@@ -216900,24 +217065,26 @@ var resolveMatcExe = async () => {
   const cached = resolveMatcExeCached();
   if (cached)
     return cached;
-  const { latest, versions } = await fetchMatcManifest();
-  const dir = join12(cacheRoot(), `matc-${latest}`);
-  await downloadMatc(latest, versions, dir);
+  const { versions } = await fetchMatcManifest();
+  const { version, file } = pickMatc(versions);
+  const dir = join12(cacheRoot(), `matc-${version}`);
+  await downloadMatc(version, file, dir);
   const exe = findMatc(dir);
   if (!exe)
     throw new CliError(`matc cache at ${dir} is broken — delete the folder and retry.`);
   return exe;
 };
 var updateMatc = async () => {
-  const { latest, versions } = await fetchMatcManifest();
+  const { versions } = await fetchMatcManifest();
+  const { version, file } = pickMatc(versions);
   const before = installedMatcVersions()[0];
-  const dir = join12(cacheRoot(), `matc-${latest}`);
+  const dir = join12(cacheRoot(), `matc-${version}`);
   if (existsSync10(dir) && findMatc(dir) !== null) {
-    note(`Already up to date: matc ${latest}.`);
+    note(`Already up to date: matc ${version}.`);
     return;
   }
-  await downloadMatc(latest, versions, dir);
-  note(before ? `matc updated to ${latest} (was ${before}).` : `matc ${latest} installed.`);
+  await downloadMatc(version, file, dir);
+  note(before ? `matc updated to ${version} (was ${before}).` : `matc ${version} installed.`);
 };
 
 // src/compile/shaders.ts
@@ -220133,6 +220300,8 @@ var windowEnv = (opts) => {
     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)
@@ -220148,6 +220317,12 @@ var windowEnv = (opts) => {
   }
   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;
 };
 var netArgs = (net) => {
@@ -220783,7 +220958,15 @@ var buildDesktop = async (args) => {
     assetCount++;
   }
   note(`  assets: ${assetCount} files, ${mb2(assetBytes)} → ${ASSETS_DIR}/`);
-  writeJson(join20(out, "app.json"), { name, ...config.desktop ? { desktop: { window: config.desktop.window } } : {} });
+  const desktop = config.desktop;
+  writeJson(join20(out, "app.json"), {
+    name,
+    ...desktop ? { desktop: {
+      window: desktop.window,
+      ...desktop.mouseEmulateTouch !== undefined ? { mouseEmulateTouch: desktop.mouseEmulateTouch } : {},
+      ...desktop.virtualKeyboard !== undefined ? { virtualKeyboard: desktop.virtualKeyboard } : {}
+    } } : {}
+  });
   if (config.icon) {
     await writeIco(root, config, join20(out, "app.ico"));
     note("  app.ico rendered from " + config.icon);
@@ -221741,7 +221924,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 —
@@ -221761,6 +221944,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
@@ -221815,6 +222003,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
@@ -221938,10 +222133,13 @@ var run = async (args) => {
     minHeight: win?.minHeight,
     resizable: win?.resizable,
     title: flagStr(args, "title") ?? win?.title ?? appCfg?.name,
+    storageScope: appCfg?.name,
     fullscreen: flagBool(args, "fullscreen") ? true : flagBool(args, "windowed") ? false : win?.fullscreen,
     scale: resolveScale(flagStr(args, "scale"), win?.scale),
     renderScale: resolveRenderScale(flagStr(args, "render-scale"), appCfg?.desktop?.renderScale),
     maxRenderSize: appCfg?.desktop?.maxRenderSize,
+    mouseEmulateTouch: appCfg?.desktop?.mouseEmulateTouch,
+    virtualKeyboard: appCfg?.desktop?.virtualKeyboard,
     fps: flagBool(args, "fps"),
     net: flagBool(args, "server") ? { role: "server", port: Number(flagStr(args, "port")) || undefined, maxClients: Number(flagStr(args, "max-clients")) || undefined } : flagStr(args, "connect") ? { role: "client", address: flagStr(args, "connect") } : undefined
   });
@@ -221985,16 +222183,16 @@ init_design();
 // src/commands/dev.ts
 init_manifest();
 init_ignore();
-import { existsSync as existsSync26, mkdirSync as mkdirSync19, readFileSync as readFileSync22, watch, writeFileSync as writeFileSync20 } from "node:fs";
+import { existsSync as existsSync29, mkdirSync as mkdirSync20, readFileSync as readFileSync24, watch, writeFileSync as writeFileSync22 } from "node:fs";
 import { randomBytes as randomBytes3 } from "node:crypto";
 import { networkInterfaces } from "node:os";
-import { basename as basename12, join as join28 } from "node:path";
+import { basename as basename12, join as join31 } from "node:path";
 
 // src/dev/devServer.ts
 init_localFiles();
 import { createServer as createServer2 } from "node:http";
 import { createReadStream, statSync as statSync10 } from "node:fs";
-import { join as join26 } from "node:path";
+import { join as join28 } from "node:path";
 init_projectCompile();
 init_fonts();
 init_assetIcons();
@@ -222273,14 +222471,14 @@ var sendText = (res, status2, type, body) => {
   res.end(body);
 };
 var sendJson = (res, status2, body) => sendText(res, status2, "application/json", JSON.stringify(body));
-var readBody = (req) => new Promise((resolve11) => {
+var readBody = (req) => new Promise((resolve12) => {
   let body = "";
   req.on("data", (c4) => {
     if (body.length < 256 * 1024)
       body += c4.toString("utf8");
   });
-  req.on("end", () => resolve11(body));
-  req.on("error", () => resolve11(body));
+  req.on("end", () => resolve12(body));
+  req.on("error", () => resolve12(body));
 });
 var startDevServer = async (options) => {
   const { root, manifest, name, origin, token, entryOverride } = options;
@@ -222361,8 +222559,8 @@ var startDevServer = async (options) => {
     const t2 = url.searchParams.get("t");
     return t2 === "poll" ? "poll" : t2 === "web" ? "web" : "ws";
   };
-  const withPrelude = (js, url, v2) => {
-    const transport = transportOf(url);
+  const withPrelude = (js, url, v2, forced) => {
+    const transport = forced ?? transportOf(url);
     return transport === "web" ? js : js + `
 ` + renderPrelude({ origin, base, transport, v: v2 });
   };
@@ -222381,6 +222579,9 @@ var startDevServer = async (options) => {
     if (route === "/dev.js") {
       return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1));
     }
+    if (route === "/dev-poll.js") {
+      return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1, "poll"));
+    }
     if (route === "/bundle.js") {
       if (bundleJs === null)
         return sendText(res, 503, "text/plain", "No successful compile yet — check the terminal.");
@@ -222398,7 +222599,7 @@ var startDevServer = async (options) => {
       const rel = route === "/web/" ? "embed.html" : route.slice("/web/".length);
       if (rel.split("/").some((seg) => seg === ".." || seg === "" || seg === "."))
         return sendText(res, 400, "text/plain", "Bad path");
-      const abs = join26(webDir, ...rel.split("/"));
+      const abs = join28(webDir, ...rel.split("/"));
       try {
         if (!statSync10(abs).isFile())
           throw new Error("not a file");
@@ -222421,7 +222622,7 @@ var startDevServer = async (options) => {
       const name2 = route.slice("/shaders/".length);
       if (!isShaderArtifactName(name2))
         return sendText(res, 400, "text/plain", "Bad path");
-      const abs = join26(shadersCacheDir(root), name2);
+      const abs = join28(shadersCacheDir(root), name2);
       try {
         if (!statSync10(abs).isFile())
           throw new Error("not a file");
@@ -222483,11 +222684,11 @@ var startDevServer = async (options) => {
     if (conn)
       clients.add(conn);
   });
-  await new Promise((resolve11, reject) => {
+  await new Promise((resolve12, reject) => {
     server2.once("error", reject);
     server2.listen(options.port, options.bind ?? "0.0.0.0", () => {
       server2.removeListener("error", reject);
-      resolve11();
+      resolve12();
     });
   });
   const address = server2.address();
@@ -222510,23 +222711,146 @@ var startDevServer = async (options) => {
 
 // src/dev/webRunner.ts
 init_distRoot();
-import { existsSync as existsSync25 } from "node:fs";
-import { createRequire as createRequire5 } from "node:module";
-import { dirname as dirname14, join as join27 } from "node:path";
+import { existsSync as existsSync27 } from "node:fs";
+import { createRequire as createRequire6 } from "node:module";
+import { dirname as dirname15, join as join29 } from "node:path";
 var resolveWebRunnerDir = () => {
-  const candidates = [join27(distRoot, "runtime", "web")];
+  const candidates = [join29(distRoot, "runtime", "web")];
   try {
-    const pkg = createRequire5(import.meta.url).resolve("lecodes-viewer-lite/package.json");
-    candidates.push(join27(dirname14(pkg), "dist-embed"));
+    const pkg = createRequire6(import.meta.url).resolve("lecodes-viewer-lite/package.json");
+    candidates.push(join29(dirname15(pkg), "dist-embed"));
   } catch {}
   for (const dir of candidates)
-    if (existsSync25(join27(dir, "embed.html")) && existsSync25(join27(dir, "embed.js")))
+    if (existsSync27(join29(dir, "embed.html")) && existsSync27(join29(dir, "embed.js")))
       return dir;
   return null;
 };
 
 // src/commands/dev.ts
 init_browserAuth();
+
+// src/dev/androidDev.ts
+init_util();
+import { existsSync as existsSync28, writeFileSync as writeFileSync21 } from "node:fs";
+import { join as join30 } from "node:path";
+import { spawnSync as spawnSync7 } from "node:child_process";
+var DEFAULT_ANDROID_PACKAGE = "com.letary.lecodes";
+var adbCandidates = () => {
+  const out = [];
+  if (process.env.LECODES_ADB)
+    out.push(process.env.LECODES_ADB);
+  out.push("adb");
+  const exe = process.platform === "win32" ? "adb.exe" : "adb";
+  for (const home of [process.env.ANDROID_HOME, process.env.ANDROID_SDK_ROOT]) {
+    if (home)
+      out.push(join30(home, "platform-tools", exe));
+  }
+  if (process.platform === "win32" && process.env.LOCALAPPDATA)
+    out.push(join30(process.env.LOCALAPPDATA, "Android", "Sdk", "platform-tools", exe));
+  if (process.env.HOME)
+    out.push(join30(process.env.HOME, "Android", "Sdk", "platform-tools", exe), join30(process.env.HOME, "Library", "Android", "sdk", "platform-tools", exe));
+  return out;
+};
+var run2 = (adb, args, input) => {
+  const r2 = spawnSync7(adb, args, { encoding: "utf8", input, windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+  const out = `${r2.stdout ?? ""}${r2.stderr ?? ""}`.trim();
+  return { ok: r2.status === 0, out };
+};
+var resolveAdb = () => {
+  for (const cand of adbCandidates()) {
+    if (cand !== "adb" && !existsSync28(cand))
+      continue;
+    const r2 = spawnSync7(cand, ["version"], { encoding: "utf8", windowsHide: true });
+    if (r2.status === 0)
+      return cand;
+  }
+  throw new CliError("adb not found — install Android platform-tools (or point LECODES_ADB at adb).");
+};
+var listDevices = (adb) => {
+  const { out } = run2(adb, ["devices", "-l"]);
+  const devices = [];
+  for (const line of out.split(/\r?\n/).slice(1)) {
+    const m = /^(\S+)\s+(\S+)(.*)$/.exec(line.trim());
+    if (!m)
+      continue;
+    const model = /model:(\S+)/.exec(m[3] ?? "")?.[1];
+    devices.push({ serial: m[1], state: m[2], model });
+  }
+  return devices;
+};
+var pickDevice = (adb, serial) => {
+  const all = listDevices(adb);
+  if (serial) {
+    const d = all.find((x2) => x2.serial === serial);
+    if (!d)
+      throw new CliError(`No device "${serial}" — adb sees: ${all.map((x2) => `${x2.serial} (${x2.state})`).join(", ") || "nothing"}.`);
+    if (d.state !== "device")
+      throw new CliError(`Device ${serial} is "${d.state}" — accept the USB-debugging prompt on the phone.`);
+    return serial;
+  }
+  const ready = all.filter((d) => d.state === "device");
+  if (ready.length === 1)
+    return ready[0].serial;
+  if (ready.length === 0) {
+    const other = all.map((d) => `${d.serial} (${d.state})`).join(", ");
+    throw new CliError(other ? `No usable device: adb sees ${other}. "unauthorized" = accept the USB-debugging prompt on the phone; "offline" = replug.` : "No Android device: enable USB debugging (Developer options), plug the phone in, accept the prompt — or `adb connect <ip>:5555` for Wi-Fi debugging.");
+  }
+  throw new CliError(`Several devices: ${ready.map((d) => `${d.serial}${d.model ? ` (${d.model})` : ""}`).join(", ")} — pick one with --serial <id>.`);
+};
+var launchOnAndroid = (opts) => {
+  const adb = resolveAdb();
+  const serial = pickDevice(adb, opts.serial);
+  const packageName = opts.packageName ?? process.env.LECODES_ANDROID_PACKAGE ?? DEFAULT_ANDROID_PACKAGE;
+  const dev = (args) => run2(adb, ["-s", serial, ...args]);
+  if (opts.apk) {
+    if (!existsSync28(opts.apk))
+      throw new CliError(`--apk: ${opts.apk} does not exist.`);
+    note(`Installing ${opts.apk}…`);
+    const r2 = dev(["install", "-r", opts.apk]);
+    if (!r2.ok || !/Success/.test(r2.out)) {
+      throw new CliError(`adb install failed: ${r2.out}${/USER_RESTRICTED/.test(r2.out) ? `
+(MIUI: enable "Install via USB" in Developer options.)` : ""}`);
+    }
+  }
+  const installed = dev(["shell", "pm", "path", packageName]);
+  if (!installed.ok || !installed.out.includes("package:")) {
+    throw new CliError(`${packageName} is not installed on ${serial} — pass --apk <file> (lecodes-android: .\\gradlew :app:assembleDebug → app/build/outputs/apk/debug/app-debug.apk).`);
+  }
+  const rev = dev(["reverse", `tcp:${opts.port}`, `tcp:${opts.port}`]);
+  if (!rev.ok)
+    warnErr(`adb reverse failed (${rev.out}) — the phone must reach the LAN url instead.`);
+  dev(["shell", "am", "force-stop", packageName]);
+  dev(["logcat", "-c"]);
+  const start = dev(["shell", "am", "start", "-n", `${packageName}/.MainActivity`, "-a", "android.intent.action.VIEW", "-d", opts.url]);
+  if (!start.ok || /Error/.test(start.out))
+    throw new CliError(`Could not launch ${packageName}: ${start.out}`);
+  let stopped = false;
+  return {
+    serial,
+    packageName,
+    adb,
+    screenshot: (file) => {
+      const r2 = spawnSync7(adb, ["-s", serial, "exec-out", "screencap", "-p"], { windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+      if (r2.status !== 0 || !r2.stdout || r2.stdout.length === 0)
+        return false;
+      writeFileSync21(file, r2.stdout);
+      return true;
+    },
+    stop: () => {
+      if (stopped)
+        return;
+      stopped = true;
+      dev(["shell", "am", "force-stop", packageName]);
+      dev(["reverse", "--remove", `tcp:${opts.port}`]);
+    }
+  };
+};
+var androidCrashLines = (session) => {
+  const { out } = run2(session.adb, ["-s", session.serial, "logcat", "-d", "-v", "brief"]);
+  return out.split(/\r?\n/).filter((l2) => /FATAL EXCEPTION|Fatal signal|\[crash\]/.test(l2) || /AndroidRuntime/.test(l2) && l2.includes(session.packageName)).slice(-20);
+};
+
+// src/commands/dev.ts
 init_util();
 var DEFAULT_PORT2 = 4499;
 var DEBOUNCE_MS = 120;
@@ -222554,24 +222878,24 @@ var lanCandidates = () => {
   return out.sort((x2, y2) => x2.rank - y2.rank).map(({ address, iface }) => ({ address, iface }));
 };
 var loadDevToken = (root) => {
-  const path2 = join28(root, LECODES_DIR, "dev.json");
+  const path2 = join31(root, LECODES_DIR, "dev.json");
   try {
-    const token2 = JSON.parse(readFileSync22(path2, "utf8")).token;
+    const token2 = JSON.parse(readFileSync24(path2, "utf8")).token;
     if (token2 && /^[a-z0-9]{8,}$/.test(token2))
       return token2;
   } catch {}
   const token = randomBytes3(6).toString("hex");
-  mkdirSync19(join28(root, LECODES_DIR), { recursive: true });
-  writeFileSync20(path2, JSON.stringify({ token }, null, 2) + `
+  mkdirSync20(join31(root, LECODES_DIR), { recursive: true });
+  writeFileSync22(path2, JSON.stringify({ token }, null, 2) + `
 `);
   return token;
 };
 var printQr = async (url) => {
   try {
     const qrcode = (await Promise.resolve().then(() => __toESM(require_main(), 1))).default;
-    await new Promise((resolve11) => qrcode.generate(url, { small: true }, (out) => {
+    await new Promise((resolve12) => qrcode.generate(url, { small: true }, (out) => {
       log(out);
-      resolve11();
+      resolve12();
     }));
   } catch {
     note("(couldn't render a QR code — open the URL below on the device)");
@@ -222645,6 +222969,7 @@ ${first.error}`);
     return true;
   };
   const debug2 = process.env.LECODES_DEV_DEBUG === "1";
+  const underBun = typeof globalThis.Bun !== "undefined";
   let timer = null;
   const onChange = (file) => {
     if (debug2)
@@ -222687,7 +223012,7 @@ ${result.error}`);
   if (alternatives.length > 0) {
     note(`Device can't reach it? This machine also has ${alternatives.map((a2) => `${a2.address} (${a2.iface})`).join(", ")} — retry with --host <ip>.`);
   }
-  if (existsSync26(join28(root, LECODES_DIR, "manifest.json")))
+  if (existsSync29(join31(root, LECODES_DIR, "manifest.json")))
     note(`Token stored in ${LECODES_DIR}/dev.json (delete it to rotate the URL).`);
   log("");
   log(`Watching ${root} — save a file to hot-reload. Ctrl+C to stop.`);
@@ -222695,6 +223020,48 @@ ${result.error}`);
     note("Opening the browser…");
     openBrowser(webLocal);
   }
+  if (flagBool(args, "android")) {
+    const seconds = Number(flagStr(args, "time")) || 0;
+    const png2 = flagStr(args, "png");
+    const deviceUrl = `http://127.0.0.1:${port}${server2.url.slice(origin.length)}`.replace(/\/dev\.js$/, underBun ? "/dev-poll.js" : "/dev.js");
+    let session;
+    try {
+      session = launchOnAndroid({ port, url: deviceUrl, serial: flagStr(args, "serial"), apk: flagStr(args, "apk"), packageName: flagStr(args, "package") });
+    } catch (e2) {
+      server2.close();
+      watcher?.close();
+      throw e2;
+    }
+    note(`Android: ${session.serial} → ${deviceUrl} (adb reverse; device logs stream here as [device:log])`);
+    const finish = (code) => {
+      session.stop();
+      server2.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 (png2) {
+          if (session.screenshot(png2))
+            note(`Wrote ${png2} (device screenshot after ${seconds} s)`);
+          else
+            warnErr(`Screenshot failed (adb screencap).`);
+        }
+        if (crashes.length > 0) {
+          warnErr(`The app crashed on the phone:
+${crashes.join(`
+`)}`);
+          finish(1);
+        }
+        finish(0);
+      }, seconds * 1000);
+    }
+  }
   if (flagBool(args, "desktop")) {
     const appCfg = readAppConfigAt(root);
     const win = appCfg?.desktop?.window;
@@ -222720,7 +223087,7 @@ init_localFiles();
 
 // src/serverDiff.ts
 init_localFiles();
-import { readFileSync as readFileSync23 } from "node:fs";
+import { readFileSync as readFileSync25 } from "node:fs";
 import { basename as basename13 } from "node:path";
 var isTextAsset = (t2) => t2 === "text" || t2 === "shader" || t2 === "scene";
 var computeServerDiff = (project, scan2) => {
@@ -222739,7 +223106,7 @@ var computeServerDiff = (project, scan2) => {
     const local = localByPath.get(path2);
     if (local && !server2) {
       const text = isTextKind(classifyKind(basename13(path2)));
-      entries.push({ path: path2, status: "added", binary: !text, serverText: "", localText: text ? readFileSync23(local.absPath, "utf8") : undefined });
+      entries.push({ path: path2, status: "added", binary: !text, serverText: "", localText: text ? readFileSync25(local.absPath, "utf8") : undefined });
       continue;
     }
     if (server2 && !local) {
@@ -222750,12 +223117,12 @@ var computeServerDiff = (project, scan2) => {
     if (server2 && local) {
       if (isTextAsset(server2.type)) {
         const serverText = server2.text ?? "";
-        const localText = readFileSync23(local.absPath, "utf8");
+        const localText = readFileSync25(local.absPath, "utf8");
         if (serverText !== localText)
           entries.push({ path: path2, status: "modified", binary: false, serverText, localText });
       } else {
         const serverSize = server2.file?.size;
-        const localSize = Buffer.byteLength(readFileSync23(local.absPath));
+        const localSize = Buffer.byteLength(readFileSync25(local.absPath));
         if (serverSize !== undefined && serverSize !== localSize) {
           entries.push({ path: path2, status: "modified", binary: true });
         }
@@ -222913,8 +223280,8 @@ var statusLabel = (e2) => e2.status === "added" ? c.green("  added    ") : e2.st
 init_manifest();
 init_types4();
 init_ignore();
-import { existsSync as existsSync27, mkdirSync as mkdirSync20, writeFileSync as writeFileSync21 } from "node:fs";
-import { basename as basename14, dirname as dirname15, join as join29, resolve as resolve11 } from "node:path";
+import { existsSync as existsSync30, mkdirSync as mkdirSync21, writeFileSync as writeFileSync23 } from "node:fs";
+import { basename as basename14, dirname as dirname16, join as join32, resolve as resolve12 } from "node:path";
 init_util();
 var STARTER2 = `// Welcome to LeCodes — the whole SDK is available as globals, no imports needed.
 // Run it live on a device with \`lecodes dev\`, or bundle it with \`lecodes compile -o app.js\`.
@@ -223022,18 +223389,18 @@ Full command list: \`lecodes --help\`.
 `;
 var init2 = async (args) => {
   const dirArg = (args._[0] ?? ".").replace(/[/\\]+$/, "") || ".";
-  const root = resolve11(dirArg);
+  const root = resolve12(dirArg);
   const name = basename14(root);
-  mkdirSync20(root, { recursive: true });
+  mkdirSync21(root, { recursive: true });
   let created = 0;
   const write = (rel, content) => {
-    const abs = join29(root, rel);
-    if (existsSync27(abs)) {
+    const abs = join32(root, rel);
+    if (existsSync30(abs)) {
       note(`kept      ${rel}`);
       return;
     }
-    mkdirSync20(dirname15(abs), { recursive: true });
-    writeFileSync21(abs, content);
+    mkdirSync21(dirname16(abs), { recursive: true });
+    writeFileSync23(abs, content);
     log(`${c.green("created")}   ${rel}`);
     created++;
   };
@@ -223080,8 +223447,8 @@ init_config();
 init_ignore();
 init_localFiles();
 init_manifest();
-import { existsSync as existsSync28 } from "node:fs";
-import { basename as basename16, join as join30, resolve as resolve12 } from "node:path";
+import { existsSync as existsSync31 } from "node:fs";
+import { basename as basename16, join as join33, resolve as resolve13 } from "node:path";
 init_types4();
 init_util();
 
@@ -223091,7 +223458,7 @@ init_config();
 init_manifest();
 init_localFiles();
 import { basename as basename15 } from "node:path";
-import { readFileSync as readFileSync24 } from "node:fs";
+import { readFileSync as readFileSync26 } from "node:fs";
 init_util();
 var push = async (args) => {
   const root = findProjectRoot(process.cwd());
@@ -223152,9 +223519,9 @@ var push = async (args) => {
     if (source)
       entry.assetId = source.id;
     if (isTextKind(kind)) {
-      entry.text = readFileSync24(file.absPath, "utf8");
+      entry.text = readFileSync26(file.absPath, "utf8");
     } else if (!source || source.sha !== file.sha) {
-      const blob = await uploadBlob(apiUrl, token, manifest.uuid, basename15(file.path), readFileSync24(file.absPath));
+      const blob = await uploadBlob(apiUrl, token, manifest.uuid, basename15(file.path), readFileSync26(file.absPath));
       entry.blobFileId = blob.id;
       uploaded++;
     }
@@ -223261,10 +223628,10 @@ var link = async (args) => {
   const apiUrl = requireApiUrl(config);
   const token = requireToken(config);
   const dirArg = args._[0];
-  const root = dirArg ? resolve12(dirArg) : process.cwd();
-  if (!existsSync28(root))
+  const root = dirArg ? resolve13(dirArg) : process.cwd();
+  if (!existsSync31(root))
     throw new CliError(`No such directory: ${root}`);
-  if (existsSync28(join30(root, LECODES_DIR, "manifest.json")) && !flagBool(args, "force")) {
+  if (existsSync31(join33(root, LECODES_DIR, "manifest.json")) && !flagBool(args, "force")) {
     throw new CliError("This folder is already linked (.lecodes/manifest.json exists) — use `lecodes push`, or `lecodes link --force` to re-link it to another project.");
   }
   let enclosing = null;
@@ -223328,10 +223695,10 @@ var link = async (args) => {
 
 // src/commands/lightmap.ts
 init_manifest();
-import { existsSync as existsSync29, mkdirSync as mkdirSync21, mkdtempSync as mkdtempSync4, readFileSync as readFileSync25, renameSync as renameSync3, rmSync as rmSync9, statSync as statSync11, unlinkSync, writeFileSync as writeFileSync22 } from "node:fs";
-import { spawn as spawn6, spawnSync as spawnSync6 } from "node:child_process";
+import { existsSync as existsSync32, mkdirSync as mkdirSync22, mkdtempSync as mkdtempSync4, readFileSync as readFileSync27, renameSync as renameSync3, rmSync as rmSync9, statSync as statSync11, unlinkSync, writeFileSync as writeFileSync24 } from "node:fs";
+import { spawn as spawn6, spawnSync as spawnSync8 } from "node:child_process";
 import { tmpdir as tmpdir4 } from "node:os";
-import { join as join31, relative as relative4, resolve as resolve13 } from "node:path";
+import { join as join34, relative as relative4, resolve as resolve14 } from "node:path";
 init_util();
 var num = (args, key, fallback, min, max) => {
   const raw = flagStr(args, key);
@@ -223344,20 +223711,20 @@ var num = (args, key, fallback, min, max) => {
 };
 var findToktx = () => {
   const env = process.env.KTX_TOKTX;
-  if (env && existsSync29(env))
+  if (env && existsSync32(env))
     return env;
-  for (const base of [process.env.LOCALAPPDATA && join31(process.env.LOCALAPPDATA, "Programs"), process.env.ProgramFiles]) {
+  for (const base of [process.env.LOCALAPPDATA && join34(process.env.LOCALAPPDATA, "Programs"), process.env.ProgramFiles]) {
     if (!base)
       continue;
-    const guess = join31(base, "KTX-Software", "bin", "toktx.exe");
-    if (existsSync29(guess))
+    const guess = join34(base, "KTX-Software", "bin", "toktx.exe");
+    if (existsSync32(guess))
       return guess;
   }
   return "toktx";
 };
 var checkToktx = (toktx) => {
   try {
-    const p2 = spawnSync6(toktx, ["--version"], { encoding: "utf8" });
+    const p2 = spawnSync8(toktx, ["--version"], { encoding: "utf8" });
     if (p2.status === 0)
       return (p2.stdout ?? "").toString().trim() || "toktx";
   } catch {}
@@ -223371,7 +223738,7 @@ var requireToktx = () => {
   }
   return toktx;
 };
-var encodeKtx2 = (toktx, png2, ktx2) => new Promise((resolve14, reject) => {
+var encodeKtx2 = (toktx, png2, ktx2) => new Promise((resolve15, reject) => {
   const args = ["--t2", "--encode", "uastc", "--uastc_quality", "2", "--zcmp", "18", "--genmipmap", "--assign_oetf", "srgb", ktx2, png2];
   const p2 = spawn6(toktx, args, { stdio: ["ignore", "pipe", "pipe"] });
   let out = "";
@@ -223384,7 +223751,7 @@ var encodeKtx2 = (toktx, png2, ktx2) => new Promise((resolve14, reject) => {
   p2.on("error", (e2) => reject(new CliError(`toktx failed (${e2.message}) while encoding ${ktx2}`)));
   p2.on("close", (status2) => {
     if (status2 === 0)
-      resolve14();
+      resolve15();
     else
       reject(new CliError(`toktx failed (${status2 ?? "?"}) while encoding ${ktx2}:
 ${out.trim()}`));
@@ -223399,13 +223766,13 @@ var bake = async (args) => {
     root = process.cwd();
   }
   const toktx = requireToktx();
-  const outDir = resolve13(root, flagStr(args, "out") ?? "assets/lightmap");
+  const outDir = resolve14(root, flagStr(args, "out") ?? "assets/lightmap");
   const stem = flagStr(args, "name") ?? "lightmap";
   if (!/^[A-Za-z0-9_-]+$/.test(stem))
     throw new CliError(`--name wants a plain file stem (letters, digits, - and _), got "${stem}".`);
   const entryFlag = flagStr(args, "entry");
   const entryFile = entryFlag ?? "main.ts";
-  if (!existsSync29(resolve13(root, entryFile))) {
+  if (!existsSync32(resolve14(root, entryFile))) {
     throw new CliError(`No ${entryFile} in ${root} — pass --entry <file> (the file that builds the scene and calls Lightmap.load).`);
   }
   const cfg = {
@@ -223437,7 +223804,7 @@ var bake = async (args) => {
   const entryText = `globalThis.__lecodesLightmap = ${JSON.stringify(cfg)}
 import ${JSON.stringify(importPath)}
 `;
-  mkdirSync21(outDir, { recursive: true });
+  mkdirSync22(outDir, { recursive: true });
   ensurePlaceholders(outDir, stem);
   const desktopRenderer = resolveDesktopRenderer(root, args);
   const { js, resources } = await buildBundle(args, undefined, {
@@ -223446,8 +223813,8 @@ import ${JSON.stringify(importPath)}
     extraEntries: [{ path: entryPath, type: "text", text: entryText }],
     entryOverride: entryPath
   });
-  const scratch = mkdtempSync4(join31(tmpdir4(), "lecodes-lightmap-"));
-  const outPng = join31(scratch, "frame.png");
+  const scratch = mkdtempSync4(join34(tmpdir4(), "lecodes-lightmap-"));
+  const outPng = join34(scratch, "frame.png");
   note(`Baking up to ${cfg.pages} × ${cfg.size}² at ${(cfg.texel * 100).toFixed(1)} cm texels (${cfg.sunRays} sun + ${cfg.aoRays} AO + ${cfg.lightRays} light rays)${cfg.volumeCell ? ` + a ${cfg.volumeCell} m light volume` : ""} → ${relative4(root, outDir) || "."}/${stem}.*…`);
   let output = "";
   try {
@@ -223481,18 +223848,18 @@ import ${JSON.stringify(importPath)}
     logErr(text.startsWith("error") ? c.red(`✗ ${text}`) : text.startsWith("warning") ? c.yellow(`  ${text}`) : c.dim(`  ${text}`));
   }
   if (/\[lightmap\] done/.test(output)) {
-    const bakePath = join31(outDir, "lightmap.bake");
-    if (!existsSync29(bakePath))
+    const bakePath = join34(outDir, "lightmap.bake");
+    if (!existsSync32(bakePath))
       throw new CliError(`The host reported a bake but ${bakePath} is missing.`);
-    const data = JSON.parse(readFileSync25(bakePath, "utf8"));
+    const data = JSON.parse(readFileSync27(bakePath, "utf8"));
     const pages = Math.max(1, data.pages ?? 1);
     const hasLight = !!data.lightTextures?.length;
     const t0 = Date.now();
     let pngKb = 0, ktxKb = 0;
     const encodePage = async (page, light) => {
-      const png2 = join31(outDir, pageFile("lightmap", page, light, ".png"));
-      const ktx2 = join31(outDir, pageFile(stem, page, light));
-      if (!existsSync29(png2))
+      const png2 = join34(outDir, pageFile("lightmap", page, light, ".png"));
+      const ktx2 = join34(outDir, pageFile(stem, page, light));
+      if (!existsSync32(png2))
         throw new CliError(`The host reported a bake but ${png2} is missing.`);
       await encodeKtx2(toktx, png2, ktx2);
       pngKb += statSync11(png2).size / 1024;
@@ -223508,15 +223875,15 @@ import ${JSON.stringify(importPath)}
     await Promise.all(encodes);
     for (let p2 = pages;p2 < 16; p2++) {
       for (const light of [false, true]) {
-        const stale = join31(outDir, pageFile(stem, p2, light));
-        if (existsSync29(stale) && statSync11(stale).size !== PLACEHOLDER_KTX2.length)
-          writeFileSync22(stale, PLACEHOLDER_KTX2);
+        const stale = join34(outDir, pageFile(stem, p2, light));
+        if (existsSync32(stale) && statSync11(stale).size !== PLACEHOLDER_KTX2.length)
+          writeFileSync24(stale, PLACEHOLDER_KTX2);
       }
     }
     if (!hasLight) {
-      const light = join31(outDir, pageFile(stem, 0, true));
-      if (existsSync29(light) && statSync11(light).size !== PLACEHOLDER_KTX2.length)
-        writeFileSync22(light, PLACEHOLDER_KTX2);
+      const light = join34(outDir, pageFile(stem, 0, true));
+      if (existsSync32(light) && statSync11(light).size !== PLACEHOLDER_KTX2.length)
+        writeFileSync24(light, PLACEHOLDER_KTX2);
     }
     data.texture = pageFile(stem, 0, false);
     data.textures = Array.from({ length: pages }, (_, p2) => pageFile(stem, p2, false));
@@ -223524,19 +223891,19 @@ import ${JSON.stringify(importPath)}
       data.lightTextures = Array.from({ length: pages }, (_, p2) => pageFile(stem, p2, true));
     if (data.volume)
       data.volume.file = `${stem}.volume`;
-    writeFileSync22(join31(outDir, `${stem}.bake`), JSON.stringify(data, null, 1) + `
+    writeFileSync24(join34(outDir, `${stem}.bake`), JSON.stringify(data, null, 1) + `
 `);
     if (stem !== "lightmap")
       unlinkSync(bakePath);
-    const volumeSrc = join31(outDir, "lightmap.volume");
-    const hasVolume = cfg.volumeCell > 0 && existsSync29(volumeSrc);
+    const volumeSrc = join34(outDir, "lightmap.volume");
+    const hasVolume = cfg.volumeCell > 0 && existsSync32(volumeSrc);
     if (hasVolume && stem !== "lightmap") {
-      rmSync9(join31(outDir, `${stem}.volume`), { force: true });
-      renameSync3(volumeSrc, join31(outDir, `${stem}.volume`));
+      rmSync9(join34(outDir, `${stem}.volume`), { force: true });
+      renameSync3(volumeSrc, join34(outDir, `${stem}.volume`));
     }
     logErr(c.dim(`  encoded ${pages} page(s)${hasLight ? " + the light atlas" : ""} (UASTC + mips, ${Math.round(ktxKb)} KB from ${Math.round(pngKb)} KB of rasters) in ${((Date.now() - t0) / 1000).toFixed(1)} s`));
     logErr(c.green(`✓ baked → ${relative4(root, outDir) || "."}/${stem}.bake + ${data.textures.join(", ")}${hasLight ? ` + ${data.lightTextures.join(", ")}` : ""}${hasVolume ? ` + ${stem}.volume` : ""}`));
-    const rel = (f3) => relative4(root, join31(outDir, f3)).replace(/\\/g, "/");
+    const rel = (f3) => relative4(root, join34(outDir, f3)).replace(/\\/g, "/");
     const assets = (files) => files.length === 1 ? `asset('<rel>/${rel(files[0])}')` : `[${files.map((f3) => `asset('<rel>/${rel(f3)}')`).join(", ")}]`;
     logErr(c.dim(`  scene file: env.lightmap: { data: asset('<rel>/${rel(`${stem}.bake`)}'), texture: ${assets(data.textures)}${hasLight ? `, light: ${assets(data.lightTextures)}` : ""}${hasVolume ? `, volume: asset('<rel>/${rel(`${stem}.volume`)}')` : ""} }  — asset() paths are relative to the scene file`));
     return;
@@ -223566,20 +223933,20 @@ var placeholderVolume = () => {
   return b;
 };
 var ensurePlaceholders = (outDir, stem) => {
-  const missing = (f3) => !existsSync29(f3) || statSync11(f3).size === 0;
-  const bake2 = join31(outDir, `${stem}.bake`);
-  const ktx2 = join31(outDir, pageFile(stem, 0, false));
-  const light = join31(outDir, pageFile(stem, 0, true));
-  const volume = join31(outDir, `${stem}.volume`);
+  const missing = (f3) => !existsSync32(f3) || statSync11(f3).size === 0;
+  const bake2 = join34(outDir, `${stem}.bake`);
+  const ktx2 = join34(outDir, pageFile(stem, 0, false));
+  const light = join34(outDir, pageFile(stem, 0, true));
+  const volume = join34(outDir, `${stem}.volume`);
   if (missing(bake2))
-    writeFileSync22(bake2, JSON.stringify({ version: 2, placeholder: true, size: 1, texel: 0, pages: 1, instances: [] }) + `
+    writeFileSync24(bake2, JSON.stringify({ version: 2, placeholder: true, size: 1, texel: 0, pages: 1, instances: [] }) + `
 `);
   if (missing(ktx2))
-    writeFileSync22(ktx2, PLACEHOLDER_KTX2);
+    writeFileSync24(ktx2, PLACEHOLDER_KTX2);
   if (missing(light))
-    writeFileSync22(light, PLACEHOLDER_KTX2);
+    writeFileSync24(light, PLACEHOLDER_KTX2);
   if (missing(volume))
-    writeFileSync22(volume, placeholderVolume());
+    writeFileSync24(volume, placeholderVolume());
 };
 var lightmap = async (args) => {
   const sub = args._[0];
@@ -223590,9 +223957,9 @@ var lightmap = async (args) => {
 
 // src/commands/navmesh.ts
 init_manifest();
-import { existsSync as existsSync30, mkdirSync as mkdirSync22, mkdtempSync as mkdtempSync5, readdirSync as readdirSync15, readFileSync as readFileSync26, rmSync as rmSync10, statSync as statSync12, unlinkSync as unlinkSync2, writeFileSync as writeFileSync23 } from "node:fs";
+import { existsSync as existsSync33, mkdirSync as mkdirSync23, mkdtempSync as mkdtempSync5, readdirSync as readdirSync15, readFileSync as readFileSync28, rmSync as rmSync10, statSync as statSync12, unlinkSync as unlinkSync2, writeFileSync as writeFileSync25 } from "node:fs";
 import { tmpdir as tmpdir5 } from "node:os";
-import { basename as basename17, join as join32, relative as relative5, resolve as resolve14 } from "node:path";
+import { basename as basename17, join as join35, relative as relative5, resolve as resolve15 } from "node:path";
 init_util();
 
 // ../creator-nav/dist/creatorNav.js
@@ -223601,16 +223968,16 @@ var createCreatorNav = (() => {
     var moduleRtn;
     var Module = moduleArg;
     var readyPromiseResolve, readyPromiseReject;
-    var readyPromise = new Promise((resolve14, reject) => {
-      readyPromiseResolve = resolve14;
+    var readyPromise = new Promise((resolve15, reject) => {
+      readyPromiseResolve = resolve15;
       readyPromiseReject = reject;
     });
     var ENVIRONMENT_IS_WEB = typeof window == "object";
     var ENVIRONMENT_IS_WORKER = typeof WorkerGlobalScope != "undefined";
     var ENVIRONMENT_IS_NODE = typeof process == "object" && process.versions?.node && process.type != "renderer";
     if (ENVIRONMENT_IS_NODE) {
-      const { createRequire: createRequire6 } = await import("module");
-      var require2 = createRequire6(import.meta.url);
+      const { createRequire: createRequire7 } = await import("module");
+      var require2 = createRequire7(import.meta.url);
     }
     var arguments_ = [];
     var thisProgram = "./this.program";
@@ -223780,9 +224147,9 @@ var createCreatorNav = (() => {
       }
       var info2 = getWasmImports();
       if (Module["instantiateWasm"]) {
-        return new Promise((resolve14, reject) => {
+        return new Promise((resolve15, reject) => {
           Module["instantiateWasm"](info2, (mod, inst) => {
-            resolve14(receiveInstance(mod, inst));
+            resolve15(receiveInstance(mod, inst));
           });
         });
       }
@@ -224138,14 +224505,14 @@ var createCreatorNav = (() => {
     var __emscripten_stack_restore = wasmExports["_emscripten_stack_restore"];
     var __emscripten_stack_alloc = wasmExports["_emscripten_stack_alloc"];
     var _emscripten_stack_get_current = wasmExports["emscripten_stack_get_current"];
-    function run2() {
+    function run3() {
       if (runDependencies > 0) {
-        dependenciesFulfilled = run2;
+        dependenciesFulfilled = run3;
         return;
       }
       preRun();
       if (runDependencies > 0) {
-        dependenciesFulfilled = run2;
+        dependenciesFulfilled = run3;
         return;
       }
       function doRun() {
@@ -224177,7 +224544,7 @@ var createCreatorNav = (() => {
       }
     }
     preInit();
-    run2();
+    run3();
     moduleRtn = readyPromise;
     return moduleRtn;
   };
@@ -224389,9 +224756,9 @@ var num2 = (args, key, fallback, min, max) => {
   return n2;
 };
 var guessName = (root) => {
-  const dirs = [join32(root, "src"), root];
+  const dirs = [join35(root, "src"), root];
   for (const dir of dirs) {
-    if (!existsSync30(dir))
+    if (!existsSync33(dir))
       continue;
     let entries;
     try {
@@ -224403,7 +224770,7 @@ var guessName = (root) => {
       if (!f3.endsWith(".scene.ts"))
         continue;
       try {
-        if (/\bnavmesh\s*:/.test(readFileSync26(join32(dir, f3), "utf8")))
+        if (/\bnavmesh\s*:/.test(readFileSync28(join35(dir, f3), "utf8")))
           return f3.slice(0, -".scene.ts".length);
       } catch {}
     }
@@ -224432,7 +224799,7 @@ var writeObj = (path2, tris) => {
     lines.push(`v ${tris[i2].toFixed(4)} ${tris[i2 + 1].toFixed(4)} ${tris[i2 + 2].toFixed(4)}`);
   for (let i2 = 0;i2 < tris.length / 3; i2 += 3)
     lines.push(`f ${i2 + 1} ${i2 + 2} ${i2 + 3}`);
-  writeFileSync23(path2, lines.join(`
+  writeFileSync25(path2, lines.join(`
 `) + `
 `);
 };
@@ -224443,10 +224810,10 @@ var bake2 = async (args) => {
   } catch {
     root = process.cwd();
   }
-  const outDir = resolve14(root, flagStr(args, "out") ?? "assets/nav");
+  const outDir = resolve15(root, flagStr(args, "out") ?? "assets/nav");
   const entryFlag = flagStr(args, "entry");
   const entryFile = entryFlag ?? "main.ts";
-  if (!existsSync30(resolve14(root, entryFile))) {
+  if (!existsSync33(resolve15(root, entryFile))) {
     throw new CliError(`No ${entryFile} in ${root} — pass --entry <file> (the file that builds the level: a scene file with env.navmesh, or code calling NavMesh.load).`);
   }
   const name = flagStr(args, "name") ?? guessName(root) ?? "scene";
@@ -224457,10 +224824,10 @@ var bake2 = async (args) => {
   const logs = flagBool(args, "logs");
   const keepGeometry = flagBool(args, "keep-geometry");
   const obj = flagBool(args, "obj");
-  mkdirSync22(outDir, { recursive: true });
-  const navmeshPath = join32(outDir, `${name}.navmesh`);
-  if (!existsSync30(navmeshPath))
-    writeFileSync23(navmeshPath, placeholderLnav());
+  mkdirSync23(outDir, { recursive: true });
+  const navmeshPath = join35(outDir, `${name}.navmesh`);
+  if (!existsSync33(navmeshPath))
+    writeFileSync25(navmeshPath, placeholderLnav());
   const importPath = "./" + entryFile.replace(/\\/g, "/").replace(/\.tsx?$/, "");
   const entryPath = "/.navmesh-entry.ts";
   const cfg = { outDir: outDir.replace(/\\/g, "/"), name };
@@ -224474,8 +224841,8 @@ import ${JSON.stringify(importPath)}
     extraEntries: [{ path: entryPath, type: "text", text: entryText }],
     entryOverride: entryPath
   });
-  const scratch = mkdtempSync5(join32(tmpdir5(), "lecodes-navmesh-"));
-  const outPng = join32(scratch, "frame.png");
+  const scratch = mkdtempSync5(join35(tmpdir5(), "lecodes-navmesh-"));
+  const outPng = join35(scratch, "frame.png");
   note(`Dumping the level's static collision geometry through the desktop host → ${relative5(root, outDir) || "."}/${name}.navgeo…`);
   let output = "";
   try {
@@ -224528,10 +224895,10 @@ import ${JSON.stringify(importPath)}
   }
   if (!config)
     throw new CliError("The host reported a dump but no `[navmesh] config` line — SDK/host mismatch?");
-  const geoPath = join32(outDir, `${name}.navgeo`);
-  if (!existsSync30(geoPath))
+  const geoPath = join35(outDir, `${name}.navgeo`);
+  if (!existsSync33(geoPath))
     throw new CliError(`The host reported a dump but ${geoPath} is missing.`);
-  const geo = readNgeo(new Uint8Array(readFileSync26(geoPath)));
+  const geo = readNgeo(new Uint8Array(readFileSync28(geoPath)));
   const params = {
     agentRadius: num2(args, "radius", config.agent.radius, 0.05, 10),
     agentHeight: num2(args, "height", config.agent.height, 0.1, 20),
@@ -224577,9 +224944,9 @@ import ${JSON.stringify(importPath)}
   if (result.polys === 0) {
     throw new CliError("The build produced no polygons — nothing walkable for this agent. Check the cell size against the level's scale, the slope, and that the floor is a STATIC body (Shape + Physics { motion: 'static' }).");
   }
-  writeFileSync23(navmeshPath, result.data);
+  writeFileSync25(navmeshPath, result.data);
   if (obj) {
-    const objPath = join32(outDir, `${name}.navmesh.obj`);
+    const objPath = join35(outDir, `${name}.navmesh.obj`);
     writeObj(objPath, navMeshTriangles(mod, result.data));
     logErr(c.dim(`  wrote ${relative5(root, objPath)} (the polygon mesh, for inspection)`));
   }
@@ -224617,8 +224984,131 @@ var login = async (args) => {
 
 // src/commands/shaders.ts
 init_manifest();
-import { readFileSync as readFileSync27 } from "node:fs";
+import { readFileSync as readFileSync30 } from "node:fs";
+import { relative as relative7 } from "node:path";
 init_util();
+
+// src/commands/shadersNew.ts
+init_compile();
+init_distRoot();
+init_util();
+import { existsSync as existsSync34, mkdirSync as mkdirSync24, readdirSync as readdirSync16, readFileSync as readFileSync29, writeFileSync as writeFileSync26 } from "node:fs";
+import { basename as basename18, join as join36, relative as relative6, resolve as resolve16 } from "node:path";
+var engineMaterialsDir = () => {
+  const candidates = [
+    join36(distRoot, "runtime", "materials"),
+    join36(distRoot, "..", "creator-gl", "materials", "src")
+  ];
+  for (const c4 of candidates)
+    if (existsSync34(join36(c4, "unlit.mat")))
+      return c4;
+  return null;
+};
+var engineMaterialNames = () => {
+  const dir = engineMaterialsDir();
+  if (!dir)
+    return [];
+  return readdirSync16(dir).filter((f3) => f3.endsWith(".mat") && !f3.startsWith("camera") && f3 !== "shader360.mat").map((f3) => f3.slice(0, -4)).sort();
+};
+var NAME_RE = /^[a-z][a-z0-9_-]*$/i;
+var matName = (name) => name.replace(/-/g, "_");
+var starterMat = (name) => `// ${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;
+    }
+}
+`;
+var refMat = (name, ref, source) => {
+  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}`;
+};
+var materialAsset = (name, mat) => {
+  const schema = parseShaderSchema(mat);
+  const lines = [];
+  for (const p2 of schema.params) {
+    if (p2.editor === "texture") {
+      lines.push(`    // ${p2.name}: asset('./texture.png'),   // a sampler takes an image asset`);
+      continue;
+    }
+    if (p2.default === null || p2.default === undefined)
+      continue;
+    lines.push(`    ${p2.name}: ${JSON.stringify(p2.default)},${p2.tooltip ? `   // ${p2.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(`
+`)}
+  },
+})
+`;
+};
+var camel = (name) => name.replace(/[-_]+(.)/g, (_, ch) => ch.toUpperCase());
+var writeNewShader = (o2) => {
+  const name = o2.name.endsWith(".mat") ? o2.name.slice(0, -4) : o2.name;
+  if (!NAME_RE.test(name))
+    throw new CliError(`"${o2.name}" is not a shader name — letters, digits, - and _ (starting with a letter), e.g. hologram or rim-light`);
+  const dir = resolve16(o2.cwd ?? process.cwd(), o2.dir ?? ".");
+  const matPath = join36(dir, `${name}.mat`), assetPath = join36(dir, `${name}.material.ts`);
+  if (!o2.force) {
+    for (const p2 of [matPath, assetPath])
+      if (existsSync34(p2))
+        throw new CliError(`${relative6(o2.cwd ?? process.cwd(), p2) || basename18(p2)} exists — pick another name or pass --force to overwrite`);
+  }
+  let mat;
+  let ref = null;
+  if (o2.ref) {
+    ref = o2.ref.endsWith(".mat") ? o2.ref.slice(0, -4) : o2.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, readFileSync29(join36(srcDir, `${ref}.mat`), "utf8"));
+  } else
+    mat = starterMat(name);
+  mkdirSync24(dir, { recursive: true });
+  writeFileSync26(matPath, mat);
+  writeFileSync26(assetPath, materialAsset(name, mat));
+  return { mat: matPath, asset: assetPath, ref };
+};
+
+// src/commands/shaders.ts
 init_compile();
 var collectShaders = () => {
   let root;
@@ -224649,7 +225139,7 @@ var status2 = async () => {
       if (matcId === null)
         state = c.dim("unknown (matc not downloaded)");
       else {
-        const text = readFileSync27(shader.absPath, "utf8");
+        const text = readFileSync30(shader.absPath, "utf8");
         if (shaderIsCompiled(root, text, matcId))
           state = "compiled";
         else {
@@ -224658,7 +225148,7 @@ var status2 = async () => {
         }
       }
       log(`  ${shader.path.padEnd(width)}  ${state}`);
-      const schema = parseShaderSchema(readFileSync27(shader.absPath, "utf8"));
+      const schema = parseShaderSchema(readFileSync30(shader.absPath, "utf8"));
       for (const p2 of schema.params) {
         const range = p2.min !== undefined ? ` [${p2.min}..${p2.max}]` : "";
         const def = p2.default !== null && p2.default !== undefined ? ` = ${JSON.stringify(p2.default)}` : "";
@@ -224701,7 +225191,7 @@ var compile3 = async (args) => {
   }
   const matcExe = await resolveMatcExe();
   const matcId = matcIdentity(matcExe);
-  const wasCompiled = new Map(shaders.map((s2) => [s2.path, shaderIsCompiled(root, readFileSync27(s2.absPath, "utf8"), matcId)]));
+  const wasCompiled = new Map(shaders.map((s2) => [s2.path, shaderIsCompiled(root, readFileSync30(s2.absPath, "utf8"), matcId)]));
   const errors2 = [];
   for (const shader of shaders) {
     try {
@@ -224723,6 +225213,16 @@ ${c.red("✗")} ${e2}`);
   const scope = platforms ? ` [${platforms.join(", ")}]` : "";
   note(`${shaders.length} shader${shaders.length === 1 ? "" : "s"} compiled${scope} → ${shadersCacheDir(root)}`);
 };
+var newShader = (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 = (p2) => relative7(process.cwd(), p2);
+  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'))`);
+};
 var shaders = async (args) => {
   const sub = args._[0];
   if (sub === undefined)
@@ -224731,12 +225231,14 @@ var shaders = async (args) => {
     return compile3(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\`.`);
 };
 
 // src/commands/render.ts
-import { mkdirSync as mkdirSync23, readFileSync as readFileSync29, writeFileSync as writeFileSync24 } from "node:fs";
-import { dirname as dirname16, resolve as resolve17 } from "node:path";
+import { mkdirSync as mkdirSync25, readFileSync as readFileSync32, writeFileSync as writeFileSync27 } from "node:fs";
+import { dirname as dirname17, resolve as resolve19 } from "node:path";
 
 // src/compile/headlessBundle.ts
 init_api();
@@ -224820,23 +225322,23 @@ var compileHeadlessBundle = async (args, opts = {}) => {
 // src/compile/screenEntry.ts
 init_designMeta();
 init_util();
-import { existsSync as existsSync31, readFileSync as readFileSync28, statSync as statSync13 } from "node:fs";
-import { isAbsolute, join as join33, relative as relative6, resolve as resolve15 } from "node:path";
+import { existsSync as existsSync35, readFileSync as readFileSync31, statSync as statSync13 } from "node:fs";
+import { isAbsolute, join as join37, relative as relative8, resolve as resolve17 } from "node:path";
 var SCREEN_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs"];
 var SCREEN_ENTRY_PATH = "/.screen-entry.ts";
 var DEFAULT_DESIGN_DIR = "design";
 var screenArg = (args) => args._[0];
 var hasSeparator = (file) => file.includes("/") || file.includes("\\");
 var findScreenFile = (root, file, dirFlag) => {
-  const candidates = [resolve15(process.cwd(), file)];
+  const candidates = [resolve17(process.cwd(), file)];
   if (!hasSeparator(file)) {
-    candidates.push(join33(root, (dirFlag ?? DEFAULT_DESIGN_DIR).replace(/[/\\]+$/, ""), "screens", file));
+    candidates.push(join37(root, (dirFlag ?? DEFAULT_DESIGN_DIR).replace(/[/\\]+$/, ""), "screens", file));
   }
   for (const base of candidates) {
-    if (existsSync31(base) && statSync13(base).isFile())
+    if (existsSync35(base) && statSync13(base).isFile())
       return base;
     for (const ext2 of SCREEN_EXTS)
-      if (existsSync31(base + ext2))
+      if (existsSync35(base + ext2))
         return base + ext2;
   }
   throw new CliError(`No screen file at "${file}".` + (hasSeparator(file) ? "" : ` Pass a path, or a screen id that exists in ${dirFlag ?? DEFAULT_DESIGN_DIR}/screens/.`));
@@ -224845,17 +225347,17 @@ var designDirOf = (root, key) => {
   const m = /^\/(.*)screens\/([^/]+)\.[^./]+$/.exec(key);
   if (!m)
     return null;
-  const dir = join33(root, m[1]);
-  return existsSync31(join33(dir, "meta.json")) ? { dir, id: m[2] } : null;
+  const dir = join37(root, m[1]);
+  return existsSync35(join37(dir, "meta.json")) ? { dir, id: m[2] } : null;
 };
 var resolveScreenTarget = (root, file, opts = {}) => {
   const abs = findScreenFile(root, file, opts.dir);
-  const rel = relative6(root, abs);
+  const rel = relative8(root, abs);
   if (rel.startsWith("..") || isAbsolute(rel)) {
     throw new CliError(`"${file}" is outside the project (${root}) — a screen renders as part of its project, so its ` + `imports and asset() files resolve from the same tree.`);
   }
   const key = toKey(rel);
-  if (!/^\s*export\s+default\b/m.test(readFileSync28(abs, "utf8"))) {
+  if (!/^\s*export\s+default\b/m.test(readFileSync31(abs, "utf8"))) {
     throw new CliError(`${key.slice(1)} has no default export. A screen file ends with ` + `\`export default UIScreen([...])\` — or \`export default (state) => UIScreen([...])\` for screen states.`);
   }
   const invoke = opts.state !== undefined ? `screen(${JSON.stringify(opts.state)})` : "screen()";
@@ -224894,11 +225396,11 @@ init_manifest();
 
 // src/desktopScript.ts
 init_util();
-import { resolve as resolve16 } from "node:path";
+import { resolve as resolve18 } from "node:path";
 var isPoint = (v) => typeof v === "object" && v !== null && typeof v.x === "number" && typeof v.y === "number";
 var FRAME_MS = 16;
 var ACTIONS = ["tap", "type", "fill", "scroll", "wait", "frames", "drag", "hold", "key", "keyDown", "keyUp", "look", "mouseTo", "wheel", "stick", "gamepad", "camera", "view"];
-var SEMANTIC_EXPECT = ["text", "notText", "node", "notNode", "screen", "value"];
+var SEMANTIC_EXPECT = ["text", "notText", "node", "notNode", "screen", "value", "audio"];
 var VIEW_NAMES = ["iso", "top", "front", "side", "back"];
 var isVec3 = (v) => Array.isArray(v) && v.length === 3 && v.every((n2) => typeof n2 === "number");
 var pt = (p2) => `(${p2.x},${p2.y})`;
@@ -225095,7 +225597,7 @@ var translateScenario = (rawSteps, opts) => {
     if (s2.screenshot !== undefined) {
       if (typeof s2.screenshot !== "string")
         throw new CliError(`${at}: "screenshot" must be a path.`);
-      plan.screenshot = resolve16(opts.outDir, s2.screenshot);
+      plan.screenshot = resolve18(opts.outDir, s2.screenshot);
       plan.lines.push(emit(`frames 2`));
       plan.lines.push(emit(`shot ${plan.screenshot}`));
       budgetMs += 3 * FRAME_MS;
@@ -225175,6 +225677,7 @@ var evaluateDesktopRun = (plan, output) => {
 
 // src/commands/render.ts
 init_util();
+init_peerInstall();
 var DEVICE_SAFE_AREA = {
   none: { insets: [0, 0, 0, 0], bars: [] },
   iphone: { insets: [59, 0, 34, 0], bars: [] },
@@ -225195,18 +225698,12 @@ var resolveSafeAreaChoice = (explicit, device) => {
   }
   return;
 };
-var requireRenderer = async () => {
-  try {
-    return await import("lecodes-renderer/headless");
-  } catch {
-    throw new CliError("The renderer isn't installed. Run:  npm install -g lecodes-renderer");
-  }
-};
+var requireRenderer = async () => loadPeer("lecodes-renderer", "headless", { for: "lecodes render" });
 var fileScenarioIO = (dir) => ({
   write: (relPath, data) => {
-    const abs = resolve17(dir, relPath);
-    mkdirSync23(dirname16(abs), { recursive: true });
-    writeFileSync24(abs, data);
+    const abs = resolve19(dir, relPath);
+    mkdirSync25(dirname17(abs), { recursive: true });
+    writeFileSync27(abs, data);
   }
 });
 var resolveFixtures = (value, baseDir) => {
@@ -225214,9 +225711,9 @@ var resolveFixtures = (value, baseDir) => {
     return;
   let map = value;
   if (typeof value === "string") {
-    const abs = resolve17(baseDir, value);
+    const abs = resolve19(baseDir, value);
     try {
-      map = JSON.parse(readFileSync29(abs, "utf8"));
+      map = JSON.parse(readFileSync32(abs, "utf8"));
     } catch (e2) {
       throw new CliError(`Can't read fixtures "${value}": ${e2 instanceof Error ? e2.message : String(e2)}`);
     }
@@ -225229,7 +225726,7 @@ var resolveFixtures = (value, baseDir) => {
 var readScenarioFile = (path2) => {
   let raw;
   try {
-    raw = JSON.parse(readFileSync29(resolve17(path2), "utf8"));
+    raw = JSON.parse(readFileSync32(resolve19(path2), "utf8"));
   } catch (e2) {
     throw new CliError(`Can't read scenario "${path2}": ${e2 instanceof Error ? e2.message : String(e2)}`);
   }
@@ -225287,13 +225784,13 @@ var renderDesktop = async (args) => {
     extraEntries: screen2 ? [screen2.entry] : undefined,
     entryOverride: screen2?.entryPath
   });
-  mkdirSync23(dirname16(resolve17(pngFlag)), { recursive: true });
+  mkdirSync25(dirname17(resolve19(pngFlag)), { recursive: true });
   if (scenario) {
     const outDir = flagStr(args, "out-dir") ?? ".";
     const plan = translateScenario(scenario.steps, { outDir, headroomFrames: frames });
     for (const st of plan.steps)
       if (st.screenshot)
-        mkdirSync23(dirname16(st.screenshot), { recursive: true });
+        mkdirSync25(dirname17(st.screenshot), { recursive: true });
     const timeoutMs2 = 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, {
@@ -225399,7 +225896,7 @@ var render = async (args) => {
   const settleStr = flagStr(args, "settle") ?? (scenario?.settle !== undefined ? String(scenario.settle) : undefined);
   const timeStr = flagStr(args, "time");
   const onConsole = flagBool(args, "logs") ? (level, text2) => logErr(`${c.dim(`[${level}]`)} ${text2}`) : undefined;
-  const envelopeFixtures = resolveFixtures(scenario?.fixtures, scriptFlag !== undefined ? dirname16(resolve17(scriptFlag)) : ".");
+  const envelopeFixtures = resolveFixtures(scenario?.fixtures, scriptFlag !== undefined ? dirname17(resolve19(scriptFlag)) : ".");
   const flagFixtures = resolveFixtures(flagStr(args, "fixtures"), ".");
   const fixtures = envelopeFixtures || flagFixtures ? { ...envelopeFixtures, ...flagFixtures } : undefined;
   if (fixtures) {
@@ -225438,7 +225935,7 @@ var render = async (args) => {
   ${c.red(st.error ?? "failed")}`);
       }
       if (!result2.ok && result2.failureArtifacts.length > 0) {
-        logErr(c.dim(`  failing frame: ${result2.failureArtifacts.map((p2) => resolve17(outDir, p2)).join(", ")}`));
+        logErr(c.dim(`  failing frame: ${result2.failureArtifacts.map((p2) => resolve19(outDir, p2)).join(", ")}`));
       }
       logErr(result2.ok ? c.green(`✓ ${result2.steps.length}/${steps.length} steps passed`) : c.red(`✗ failed at step ${result2.steps.length} of ${steps.length}`));
       return done((cb) => cb(), result2.ok ? 0 : 1);
@@ -225459,10 +225956,10 @@ var render = async (args) => {
     for (const w of [...warnings, ...mapWarnings])
       warnErr(w);
     const pngPath = mapFlag.endsWith(".png") ? mapFlag : mapFlag + ".png";
-    mkdirSync23(dirname16(resolve17(pngPath)), { recursive: true });
-    writeFileSync24(resolve17(pngPath), png2);
+    mkdirSync25(dirname17(resolve19(pngPath)), { recursive: true });
+    writeFileSync27(resolve19(pngPath), png2);
     const jsonPath = pngPath.slice(0, -4) + ".json";
-    writeFileSync24(resolve17(jsonPath), JSON.stringify(data, null, 2));
+    writeFileSync27(resolve19(jsonPath), JSON.stringify(data, null, 2));
     note(`Wrote ${pngPath} + ${jsonPath}`);
     return done((cb) => cb());
   }
@@ -225482,8 +225979,8 @@ var render = async (args) => {
     if (isNullSink(pngFlag)) {
       note(`Discarded PNG (${pngFlag})`);
     } else {
-      mkdirSync23(dirname16(resolve17(pngFlag)), { recursive: true });
-      writeFileSync24(resolve17(pngFlag), png2);
+      mkdirSync25(dirname17(resolve19(pngFlag)), { recursive: true });
+      writeFileSync27(resolve19(pngFlag), png2);
       note(`Wrote ${pngFlag} (${png2.length} bytes, ${outW}x${outH}${clip !== undefined ? ", clipped" : ""})`);
     }
     return done((cb) => cb());
@@ -225498,7 +225995,7 @@ var render = async (args) => {
     return done((cb) => cb());
   }
   if (out) {
-    writeFileSync24(resolve17(out), result.text);
+    writeFileSync27(resolve19(out), result.text);
     note(`Wrote ${out} (${result.text.length} bytes)`);
     return done((cb) => cb());
   }
@@ -225513,8 +226010,8 @@ init_api();
 init_config();
 init_manifest();
 init_util();
-import { appendFileSync as appendFileSync2, existsSync as existsSync32, readFileSync as readFileSync30, writeFileSync as writeFileSync25 } from "node:fs";
-import { join as join34 } from "node:path";
+import { appendFileSync as appendFileSync2, existsSync as existsSync36, readFileSync as readFileSync33, writeFileSync as writeFileSync28 } from "node:fs";
+import { join as join38 } from "node:path";
 var ENV_VAR = "LECODES_PUSH_KEY";
 var context = () => {
   const root = findProjectRoot(process.cwd());
@@ -225658,11 +226155,11 @@ var pnKeysList = async (ctx) => {
 };
 var writeEnv = (root, key) => {
   const touched = [];
-  const envPath = join34(root, ".env");
+  const envPath = join38(root, ".env");
   const line = `${ENV_VAR}=${key}`;
-  const existing = existsSync32(envPath) ? readFileSync30(envPath, "utf8") : "";
+  const existing = existsSync36(envPath) ? readFileSync33(envPath, "utf8") : "";
   if (new RegExp(`^${ENV_VAR}=`, "m").test(existing)) {
-    writeFileSync25(envPath, existing.replace(new RegExp(`^${ENV_VAR}=.*$`, "m"), line));
+    writeFileSync28(envPath, existing.replace(new RegExp(`^${ENV_VAR}=.*$`, "m"), line));
   } else {
     const separator = !existing || existing.endsWith(`
 `) ? "" : `
@@ -225671,8 +226168,8 @@ var writeEnv = (root, key) => {
 `);
   }
   touched.push(".env");
-  const ignorePath = join34(root, ".gitignore");
-  const ignore = existsSync32(ignorePath) ? readFileSync30(ignorePath, "utf8") : "";
+  const ignorePath = join38(root, ".gitignore");
+  const ignore = existsSync36(ignorePath) ? readFileSync33(ignorePath, "utf8") : "";
   if (!ignore.split(`
 `).some((l2) => l2.trim() === ".env")) {
     const separator = !ignore || ignore.endsWith(`
@@ -225771,8 +226268,8 @@ var pn = async (args) => {
 init_api();
 init_config();
 init_manifest();
-import { existsSync as existsSync33, mkdirSync as mkdirSync24, rmSync as rmSync11, writeFileSync as writeFileSync26 } from "node:fs";
-import { dirname as dirname17, join as join35 } from "node:path";
+import { existsSync as existsSync37, mkdirSync as mkdirSync26, rmSync as rmSync11, writeFileSync as writeFileSync29 } from "node:fs";
+import { dirname as dirname18, join as join39 } from "node:path";
 init_types4();
 init_localFiles();
 init_util();
@@ -225795,8 +226292,8 @@ var pull = async (args) => {
   const remotePaths = new Set([...buildPaths(project.assets).entries()].filter(([id]) => project.assets.find((a2) => a2.id === id)?.type !== "folder").map(([, path2]) => path2));
   for (const path2 of Object.keys(manifest.files)) {
     if (!remotePaths.has(path2)) {
-      const abs = join35(root, ...path2.replace(/^\//, "").split("/"));
-      if (existsSync33(abs))
+      const abs = join39(root, ...path2.replace(/^\//, "").split("/"));
+      if (existsSync37(abs))
         rmSync11(abs);
     }
   }
@@ -225834,18 +226331,18 @@ var pullPaths = async (root, manifest, project, paths, apiUrl, token) => {
   const files = { ...manifest.files };
   for (const asset of targets) {
     const key = pathById.get(asset.id);
-    const abs = join35(root, ...key.replace(/^\//, "").split("/"));
-    mkdirSync24(dirname17(abs), { recursive: true });
+    const abs = join39(root, ...key.replace(/^\//, "").split("/"));
+    mkdirSync26(dirname18(abs), { recursive: true });
     let sha;
     if (asset.type === "file") {
       if (!asset.file?.src)
         continue;
       const bytes = await downloadBlob(apiUrl, asset.file.src);
-      writeFileSync26(abs, bytes);
+      writeFileSync29(abs, bytes);
       sha = sha256(bytes);
     } else {
       const text = asset.text ?? "";
-      writeFileSync26(abs, text);
+      writeFileSync29(abs, text);
       sha = sha256(text);
     }
     files[key] = { id: asset.id, type: kindOf3(asset.type), sha };
@@ -225858,8 +226355,8 @@ var pullPaths = async (root, manifest, project, paths, apiUrl, token) => {
 
 // src/commands/scene.ts
 init_manifest();
-import { existsSync as existsSync35, readFileSync as readFileSync32, readdirSync as readdirSync16, statSync as statSync14, writeFileSync as writeFileSync28 } from "node:fs";
-import { basename as basename18, dirname as dirname18, join as join37, resolve as resolve18 } from "node:path";
+import { existsSync as existsSync39, readFileSync as readFileSync35, readdirSync as readdirSync17, statSync as statSync14, writeFileSync as writeFileSync31 } from "node:fs";
+import { basename as basename19, dirname as dirname19, join as join41, resolve as resolve20 } from "node:path";
 
 // src/compile/sceneCompile.ts
 init_localFiles();
@@ -225868,18 +226365,18 @@ init_distRoot();
 init_util();
 init_projectCompile();
 import { createHash as createHash8 } from "node:crypto";
-import { existsSync as existsSync34, mkdirSync as mkdirSync25, readFileSync as readFileSync31, writeFileSync as writeFileSync27 } from "node:fs";
-import { join as join36 } from "node:path";
+import { existsSync as existsSync38, mkdirSync as mkdirSync27, readFileSync as readFileSync34, writeFileSync as writeFileSync30 } from "node:fs";
+import { join as join40 } from "node:path";
 var TEXT_EXT = /\.(ts|js|json|svg|txt|md)$/i;
 var rel = (key) => key.replace(/^\//, "");
 var resolveHarness = (loadSceneHarness2) => {
-  const inRepo = join36(distRoot, "..", "projects", "src", "scene-editor");
+  const inRepo = join40(distRoot, "..", "projects", "src", "scene-editor");
   try {
-    return loadSceneHarness2(existsSync34(inRepo) ? inRepo : undefined);
+    return loadSceneHarness2(existsSync38(inRepo) ? inRepo : undefined);
   } catch {
-    const vendored = join36(distRoot, "runtime", "scene-harness.json");
-    if (existsSync34(vendored))
-      return JSON.parse(readFileSync31(vendored, "utf8"));
+    const vendored = join40(distRoot, "runtime", "scene-harness.json");
+    if (existsSync38(vendored))
+      return JSON.parse(readFileSync34(vendored, "utf8"));
     throw new CliError("scene-editor harness sources not found — reinstall the CLI or set LECODES_SCENE_HARNESS_DIR.");
   }
 };
@@ -225891,9 +226388,9 @@ var compileSceneEditor = async (opts) => {
   for (const file of scan2.files) {
     const path2 = "./" + rel(file.path);
     if (TEXT_EXT.test(path2)) {
-      entries.push({ path: path2, type: "text", text: readFileSync31(file.absPath, "utf8") });
+      entries.push({ path: path2, type: "text", text: readFileSync34(file.absPath, "utf8") });
     } else if (/\.mat$/i.test(path2)) {
-      entries.push({ path: path2, type: "shader", text: readFileSync31(file.absPath, "utf8"), absPath: file.absPath });
+      entries.push({ path: path2, type: "shader", text: readFileSync34(file.absPath, "utf8"), absPath: file.absPath });
     } else {
       entries.push({ path: path2, type: "resource", fileSrc: "/project/" + rel(file.path) });
     }
@@ -225909,10 +226406,10 @@ var compileSceneEditor = async (opts) => {
         continue;
       const hash = createHash8("sha256").update(e2.text ?? "").digest("hex").slice(0, 16);
       const dir = shadersCacheDir(root);
-      mkdirSync25(dir, { recursive: true });
+      mkdirSync27(dir, { recursive: true });
       const liteName = `${hash}_webgl-lite.filamat`;
-      if (!existsSync34(join36(dir, liteName)))
-        writeFileSync27(join36(dir, liteName), JSON.stringify(buildLiteMaterialArtifact2(e2.text ?? "")));
+      if (!existsSync38(join40(dir, liteName)))
+        writeFileSync30(join40(dir, liteName), JSON.stringify(buildLiteMaterialArtifact2(e2.text ?? "")));
       const src = `/project/.lecodes/shaders/${hash}_opengl.filamat`;
       e2.shaders = ["opengl", "webgl-lite"].map((platform) => ({ platform, src }));
     }
@@ -225942,13 +226439,14 @@ var compileSceneEditor = async (opts) => {
 // src/commands/scene.ts
 init_browserAuth();
 init_util();
+init_peerInstall();
 var DEFAULT_PORT3 = 4488;
 var findAppRoot = (start) => {
   let dir = start;
   while (true) {
-    if (existsSync35(join37(dir, "app.json")))
+    if (existsSync39(join41(dir, "app.json")))
       return dir;
-    const parent = dirname18(dir);
+    const parent = dirname19(dir);
     if (parent === dir)
       return null;
     dir = parent;
@@ -225972,26 +226470,26 @@ var getContext2 = (args) => {
     manifest = null;
     const pathArg = args._[0];
     if (pathArg) {
-      const abs = resolve18(process.cwd(), pathArg);
-      if (existsSync35(abs) && statSync14(abs).isDirectory())
+      const abs = resolve20(process.cwd(), pathArg);
+      if (existsSync39(abs) && statSync14(abs).isDirectory())
         root = abs;
-      else if (abs.endsWith(".scene.ts") && existsSync35(abs))
-        root = findAppRoot(dirname18(abs)) ?? dirname18(abs);
+      else if (abs.endsWith(".scene.ts") && existsSync39(abs))
+        root = findAppRoot(dirname19(abs)) ?? dirname19(abs);
       else
         throw new CliError(`No such folder or .scene.ts: ${pathArg}`);
     } else {
       root = findAppRoot(root) ?? root;
     }
   }
-  return { root, manifest, name: manifest?.name ?? basename18(root) };
+  return { root, manifest, name: manifest?.name ?? basename19(root) };
 };
 var writeMcpConfig2 = (root, port) => {
-  const path2 = join37(root, ".mcp.json");
+  const path2 = join41(root, ".mcp.json");
   const entry = { type: "http", url: `http://localhost:${port}/mcp` };
   let config = {};
-  if (existsSync35(path2)) {
+  if (existsSync39(path2)) {
     try {
-      config = JSON.parse(readFileSync32(path2, "utf8"));
+      config = JSON.parse(readFileSync35(path2, "utf8"));
     } catch {
       warnErr(".mcp.json exists but isn't valid JSON — left it untouched. Add the lecodes-scene server by hand.");
       return;
@@ -226004,16 +226502,16 @@ var writeMcpConfig2 = (root, port) => {
     return;
   }
   config.mcpServers["lecodes-scene"] = entry;
-  writeFileSync28(path2, JSON.stringify(config, null, 2) + `
+  writeFileSync31(path2, JSON.stringify(config, null, 2) + `
 `);
   note(`${existing ? "updated" : "created"}   .mcp.json (lecodes-scene MCP → ${entry.url})`);
 };
 var countScenes = (dir) => {
   let n2 = 0;
-  for (const name of readdirSync16(dir)) {
+  for (const name of readdirSync17(dir)) {
     if (name === "node_modules" || name.startsWith("."))
       continue;
-    const full = join37(dir, name);
+    const full = join41(dir, name);
     if (statSync14(full).isDirectory())
       n2 += countScenes(full);
     else if (name.endsWith(".scene.ts"))
@@ -226023,12 +226521,7 @@ var countScenes = (dir) => {
 };
 var scene = async (args) => {
   const ctx = getContext2(args);
-  let sceneServer;
-  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("lecodes-3d-editor", "server", { for: "lecodes scene" });
   const port = Number(flagStr(args, "port")) || DEFAULT_PORT3;
   if (countScenes(ctx.root) === 0) {
     warnErr(`No .scene.ts file under ${ctx.root} yet — add one and the editor will pick it up.`);
@@ -226056,11 +226549,12 @@ var scene = async (args) => {
 };
 
 // src/commands/thumbs.ts
-import { createRequire as createRequire6 } from "node:module";
+init_peerInstall();
+import { createRequire as createRequire7 } from "node:module";
 import { execFileSync as execFileSync7 } from "node:child_process";
-import { existsSync as existsSync36, mkdtempSync as mkdtempSync6, readdirSync as readdirSync17, rmSync as rmSync12, statSync as statSync15 } from "node:fs";
+import { existsSync as existsSync40, mkdtempSync as mkdtempSync6, readdirSync as readdirSync18, rmSync as rmSync12, statSync as statSync15 } from "node:fs";
 import { tmpdir as tmpdir6 } from "node:os";
-import { extname, join as join38, relative as relative7, resolve as resolve19 } from "node:path";
+import { extname, join as join42, relative as relative9, resolve as resolve21 } from "node:path";
 init_util();
 var DEFAULT_SIZE = 256;
 var IMAGE_EXT = /\.(png|jpe?g|webp|bmp|gif|tiff?|ktx2)$/i;
@@ -226071,13 +226565,13 @@ var findKtx = () => {
     process.env.LECODES_KTX,
     process.env.KTX_CLI,
     process.env.KTX_TOKTX?.replace(/toktx(\.exe)?$/i, exe),
-    process.platform === "win32" ? join38(process.env.LOCALAPPDATA ?? "", "Programs", "KTX-Software", "bin", exe) : null,
-    process.platform === "win32" ? join38(process.env.ProgramFiles ?? "", "KTX-Software", "bin", exe) : null,
+    process.platform === "win32" ? join42(process.env.LOCALAPPDATA ?? "", "Programs", "KTX-Software", "bin", exe) : null,
+    process.platform === "win32" ? join42(process.env.ProgramFiles ?? "", "KTX-Software", "bin", exe) : null,
     "/usr/local/bin/ktx",
     "/opt/homebrew/bin/ktx"
   ].filter((p2) => !!p2);
   for (const path2 of candidates) {
-    if (existsSync36(path2))
+    if (existsSync40(path2))
       return path2;
   }
   try {
@@ -226089,8 +226583,8 @@ var findKtx = () => {
 };
 var sharpResizer = () => {
   try {
-    const req = createRequire6(import.meta.url);
-    const sharp = createRequire6(req.resolve("lecodes-assets/cli"))("sharp");
+    const req = createRequire7(import.meta.url);
+    const sharp = createRequire7(req.resolve("lecodes-assets/cli"))("sharp");
     return async (file, size) => sharp(file).resize({ width: size, height: size, fit: "inside", withoutEnlargement: true }).png().toBuffer();
   } catch {
     return null;
@@ -226104,21 +226598,21 @@ var jimpResizer = () => async (file, size) => {
   return await img.getBuffer("image/png");
 };
 var ktxToPng = (ktx, file, out) => {
-  const run2 = (args) => execFileSync7(ktx, args, { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8" });
+  const run3 = (args) => execFileSync7(ktx, args, { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8" });
   try {
-    run2(["extract", "--transcode", "rgba8", "--level", "0", file, out]);
+    run3(["extract", "--transcode", "rgba8", "--level", "0", file, out]);
   } catch (e2) {
-    run2(["extract", "--level", "0", file, out]);
-    if (!existsSync36(out))
+    run3(["extract", "--level", "0", file, out]);
+    if (!existsSync40(out))
       throw e2;
   }
 };
 var collect = (dir) => {
   const out = [];
-  for (const name of readdirSync17(dir)) {
+  for (const name of readdirSync18(dir)) {
     if (name === "node_modules" || name.startsWith("."))
       continue;
-    const full = join38(dir, name);
+    const full = join42(dir, name);
     if (statSync15(full).isDirectory())
       out.push(...collect(full));
     else if (IMAGE_EXT.test(name))
@@ -226128,20 +226622,15 @@ var collect = (dir) => {
 };
 var thumbs = async (args) => {
   const root = projectRootOf(process.cwd());
-  let sceneServer;
-  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");
-  }
+  const sceneServer = await loadPeer("lecodes-3d-editor", "server", { for: "lecodes thumbs" });
   const size = Number(flagStr(args, "size")) || DEFAULT_SIZE;
   const force = flagBool(args, "force");
   let files = [];
   const rendered = [];
   if (args._.length > 0) {
     for (const arg of args._) {
-      const abs = resolve19(process.cwd(), arg);
-      if (!existsSync36(abs))
+      const abs = resolve21(process.cwd(), arg);
+      if (!existsSync40(abs))
         throw new CliError(`No such file or folder: ${arg}`);
       if (statSync15(abs).isDirectory())
         files.push(...collect(abs));
@@ -226163,12 +226652,12 @@ var thumbs = async (args) => {
   const ktx = files.some((f3) => f3.toLowerCase().endsWith(".ktx2")) ? findKtx() : null;
   const sharp = sharpResizer();
   const resize = sharp ?? jimpResizer();
-  const tmp = mkdtempSync6(join38(tmpdir6(), "lecodes-thumbs-"));
+  const tmp = mkdtempSync6(join42(tmpdir6(), "lecodes-thumbs-"));
   let made = 0, fresh = 0;
   const skipped = [];
   try {
     for (const [i2, file] of files.entries()) {
-      const asset = "./" + toKey(relative7(root, file));
+      const asset = "./" + toKey(relative9(root, file));
       progress(i2, files.length, asset);
       const hash = sceneServer.hashAsset(root, asset);
       if (!hash)
@@ -226189,7 +226678,7 @@ var thumbs = async (args) => {
             skipped.push(`${asset} (KTX2 needs KTX-Software's \`ktx\` — set LECODES_KTX or put it on PATH)`);
             continue;
           }
-          source = join38(tmp, `${i2}.png`);
+          source = join42(tmp, `${i2}.png`);
           ktxToPng(ktx, file, source);
         }
         sceneServer.writePreviewFile(root, asset, await resize(source, size));
@@ -226209,16 +226698,13 @@ var thumbs = async (args) => {
   if (rendered.length > 0) {
     warnErr(`Models, materials and prefabs are RENDERED, not decoded — the scene editor does those: ${rendered.join(", ")}`);
   }
-  note(`Cache: ${join38(root, ".lecodes", "preview")}  (re-runs skip everything unchanged)`);
+  note(`Cache: ${join42(root, ".lecodes", "preview")}  (re-runs skip everything unchanged)`);
 };
 
-// src/commands/assets.ts
-init_util();
-
 // src/cmgenTool.ts
-import { existsSync as existsSync37, readdirSync as readdirSync18 } from "node:fs";
-import { homedir as homedir8 } from "node:os";
-import { join as join39, resolve as resolve20 } from "node:path";
+import { existsSync as existsSync41, readdirSync as readdirSync19 } from "node:fs";
+import { homedir as homedir9 } from "node:os";
+import { join as join43, resolve as resolve22 } from "node:path";
 init_util();
 var exeName2 = () => process.platform === "win32" ? "cmgen.exe" : "cmgen";
 var platformKey3 = () => {
@@ -226228,10 +226714,10 @@ var platformKey3 = () => {
     return "linux-x64";
   throw new CliError(process.platform === "darwin" ? "cmgen isn't published for macOS yet — build filament's host tools locally and set LECODES_CMGEN." : `cmgen isn't published for ${process.platform}.`);
 };
-var cacheRoot3 = () => join39(homedir8(), ".lecodes", "cmgen");
+var cacheRoot3 = () => join43(homedir9(), ".lecodes", "cmgen");
 var findCmgenIn = (dir) => {
-  for (const entry of readdirSync18(dir, { withFileTypes: true })) {
-    const p2 = join39(dir, entry.name);
+  for (const entry of readdirSync19(dir, { withFileTypes: true })) {
+    const p2 = join43(dir, entry.name);
     if (entry.isFile() && entry.name === exeName2())
       return p2;
     if (entry.isDirectory()) {
@@ -226244,18 +226730,21 @@ var findCmgenIn = (dir) => {
 };
 var installedCmgenVersions = () => {
   try {
-    return readdirSync18(cacheRoot3(), { withFileTypes: true }).filter((e2) => e2.isDirectory() && e2.name.startsWith("cmgen-")).map((e2) => e2.name.slice("cmgen-".length)).filter((v) => findCmgenIn(join39(cacheRoot3(), `cmgen-${v}`)) !== null).sort(semverNewer);
+    return readdirSync19(cacheRoot3(), { withFileTypes: true }).filter((e2) => e2.isDirectory() && e2.name.startsWith("cmgen-")).map((e2) => e2.name.slice("cmgen-".length)).filter((v) => findCmgenIn(join43(cacheRoot3(), `cmgen-${v}`)) !== null).sort(semverNewer);
   } catch {
     return [];
   }
 };
 var fetchCmgenManifest = () => fetchReleaseProduct("cmgen", "cmgen (environment tool)");
-var downloadCmgen = async (version, versions, dest) => {
+var pickCmgen = (versions) => {
   const key = platformKey3();
-  const file = versions.find((v) => v.version === version)?.files[key];
-  if (!file) {
-    throw new CliError(`cmgen ${version} [${key}] isn't published — build filament's host tools locally and point ` + `LECODES_CMGEN at the binary.`);
+  const hit = newestForPlatform(versions, key);
+  if (!hit) {
+    throw new CliError(`cmgen isn't published for ${key} — build filament's host tools locally and point ` + `LECODES_CMGEN at the binary.`);
   }
+  return hit;
+};
+var downloadCmgen = async (version, file, dest) => {
   note(`Downloading the environment tool (cmgen ${version}, ${(file.size / 1024 / 1024).toFixed(1)} MB)…`);
   await downloadReleaseArchive(file, {
     cacheRoot: cacheRoot3(),
@@ -226266,20 +226755,21 @@ var downloadCmgen = async (version, versions, dest) => {
 var resolveCmgenExeCached = () => {
   const override = process.env.LECODES_CMGEN;
   if (override) {
-    if (!existsSync37(override))
+    if (!existsSync41(override))
       throw new CliError(`LECODES_CMGEN points at "${override}" which doesn't exist.`);
-    return resolve20(override);
+    return resolve22(override);
   }
   const cached = installedCmgenVersions()[0];
-  return cached ? findCmgenIn(join39(cacheRoot3(), `cmgen-${cached}`)) : null;
+  return cached ? findCmgenIn(join43(cacheRoot3(), `cmgen-${cached}`)) : null;
 };
 var resolveCmgenExe = async () => {
   const cached = resolveCmgenExeCached();
   if (cached)
     return cached;
-  const { latest, versions } = await fetchCmgenManifest();
-  const dir = join39(cacheRoot3(), `cmgen-${latest}`);
-  await downloadCmgen(latest, versions, dir);
+  const { versions } = await fetchCmgenManifest();
+  const { version, file } = pickCmgen(versions);
+  const dir = join43(cacheRoot3(), `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.`);
@@ -226287,13 +226777,9 @@ var resolveCmgenExe = async () => {
 };
 
 // src/commands/assets.ts
+init_peerInstall();
 var assets = async (args) => {
-  let mod;
-  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("lecodes-assets", "cli", { for: "lecodes assets" });
   const raw = args._raw ?? args._;
   if (raw[0] === "sky" && !process.env.LECODES_CMGEN) {
     process.env.LECODES_CMGEN = await resolveCmgenExe();
@@ -226336,8 +226822,8 @@ var status3 = async (_args) => {
 };
 
 // src/commands/test.ts
-import { existsSync as existsSync38, mkdirSync as mkdirSync26, readFileSync as readFileSync33, readdirSync as readdirSync19 } from "node:fs";
-import { dirname as dirname19, resolve as resolve21 } from "node:path";
+import { existsSync as existsSync42, mkdirSync as mkdirSync28, readFileSync as readFileSync36, readdirSync as readdirSync20 } from "node:fs";
+import { dirname as dirname20, resolve as resolve23 } from "node:path";
 init_manifest();
 init_util();
 var deriveDesignFlows = (meta, entryScreen) => {
@@ -226400,7 +226886,7 @@ var slug3 = (s2) => s2.replace(/[^a-zA-Z0-9-_]+/g, "-").replace(/^-+|-+$/g, "").
 var readFlowFile = (abs, displayName) => {
   let raw;
   try {
-    raw = JSON.parse(readFileSync33(abs, "utf8"));
+    raw = JSON.parse(readFileSync36(abs, "utf8"));
   } catch (e2) {
     throw new CliError(`Can't read "${displayName}": ${e2 instanceof Error ? e2.message : String(e2)}`);
   }
@@ -226414,7 +226900,7 @@ var readFlowFile = (abs, displayName) => {
     name: file.name ?? displayName,
     kind: "file",
     steps: file.steps,
-    fixtures: resolveFixtures(file.fixtures, dirname19(abs)),
+    fixtures: resolveFixtures(file.fixtures, dirname20(abs)),
     width: file.width,
     height: file.height,
     settle: file.settle,
@@ -226455,40 +226941,40 @@ var test = async (args) => {
   if (!Number.isFinite(nativeFixedDt) || nativeFixedDt < 0 || nativeFixedDt > 1000)
     throw new CliError(`--fixed-dt wants a number of ms (0 = wall clock, max 1000), got "${fixedDtFlag}".`);
   const projectViewport = desktopDefaultViewport(root);
-  const testsDir = resolve21(root, flagStr(args, "dir") ?? "tests");
-  const designMetaPath = resolve21(root, flagStr(args, "design-dir") ?? "design", "meta.json");
+  const testsDir = resolve23(root, flagStr(args, "dir") ?? "tests");
+  const designMetaPath = resolve23(root, flagStr(args, "design-dir") ?? "design", "meta.json");
   const asJson = flagBool(args, "json");
   const out = asJson ? logErr : log;
   const cases = [];
   if (args._.length > 0) {
     for (const given of args._) {
-      const candidates = [resolve21(given), resolve21(testsDir, given), resolve21(testsDir, `${given}.flow.json`)];
-      const abs = candidates.find((p2) => existsSync38(p2));
+      const candidates = [resolve23(given), resolve23(testsDir, given), resolve23(testsDir, `${given}.flow.json`)];
+      const abs = candidates.find((p2) => existsSync42(p2));
       if (!abs)
         throw new CliError(`No such test: "${given}" (looked in ${testsDir}).`);
       cases.push(readFlowFile(abs, given));
     }
-  } else if (existsSync38(testsDir)) {
-    for (const f3 of readdirSync19(testsDir).filter((f4) => f4.endsWith(".flow.json")).sort()) {
-      cases.push(readFlowFile(resolve21(testsDir, f3), f3));
+  } else if (existsSync42(testsDir)) {
+    for (const f3 of readdirSync20(testsDir).filter((f4) => f4.endsWith(".flow.json")).sort()) {
+      cases.push(readFlowFile(resolve23(testsDir, f3), f3));
     }
   }
   const fixturesFlag = flagStr(args, "fixtures");
-  const defaultPack = resolve21(testsDir, "fixtures.json");
-  const flowFixtures = fixturesFlag !== undefined ? resolveFixtures(fixturesFlag, ".") : existsSync38(defaultPack) ? resolveFixtures("fixtures.json", testsDir) : undefined;
+  const defaultPack = resolve23(testsDir, "fixtures.json");
+  const flowFixtures = fixturesFlag !== undefined ? resolveFixtures(fixturesFlag, ".") : existsSync42(defaultPack) ? resolveFixtures("fixtures.json", testsDir) : undefined;
   const flowsOnly = flagBool(args, "flows");
   const wantFlows = !flagBool(args, "no-flows") && args._.length === 0;
   if (flowsOnly)
     cases.length = 0;
   let skipped = [];
   let entryScreen = null;
-  if (desktop2 && wantFlows && existsSync38(designMetaPath)) {
+  if (desktop2 && wantFlows && existsSync42(designMetaPath)) {
     note("Design-derived flows skipped with --desktop (they tap by name; run `lecodes test` headless for them).");
   }
-  if (!desktop2 && (wantFlows || flowsOnly) && existsSync38(designMetaPath)) {
+  if (!desktop2 && (wantFlows || flowsOnly) && existsSync42(designMetaPath)) {
     let meta;
     try {
-      meta = JSON.parse(readFileSync33(designMetaPath, "utf8"));
+      meta = JSON.parse(readFileSync36(designMetaPath, "utf8"));
     } catch (e2) {
       throw new CliError(`Can't read ${designMetaPath}: ${e2 instanceof Error ? e2.message : String(e2)}`);
     }
@@ -226520,16 +227006,16 @@ var test = async (args) => {
   }, timeoutMs);
   killer.unref?.();
   const onConsole = flagBool(args, "logs") ? (level, text) => logErr(`${c.dim(`[${level}]`)} ${text}`) : undefined;
-  const artifactsRoot = resolve21(root, flagStr(args, "artifacts") ?? resolve21(testsDir, ".artifacts"));
+  const artifactsRoot = resolve23(root, flagStr(args, "artifacts") ?? resolve23(testsDir, ".artifacts"));
   const results = [];
   const runNativeCase = async (kase) => {
-    const caseDir = resolve21(artifactsRoot, slug3(kase.name));
+    const caseDir = resolve23(artifactsRoot, slug3(kase.name));
     const plan = translateScenario(kase.steps, { outDir: caseDir, headroomFrames: nativeFrames });
     for (const st of plan.steps)
       if (st.screenshot)
-        mkdirSync26(dirname19(st.screenshot), { recursive: true });
-    mkdirSync26(caseDir, { recursive: true });
-    const finalPng = resolve21(caseDir, "final.png");
+        mkdirSync28(dirname20(st.screenshot), { recursive: true });
+    mkdirSync28(caseDir, { recursive: true });
+    const finalPng = resolve23(caseDir, "final.png");
     const { output } = await runDesktopRender(native.js, native.resources, {
       renderer: desktopRenderer,
       pluginDirs: desktopPluginLibraries(root).dirs,
@@ -226582,14 +227068,14 @@ var test = async (args) => {
         onConsole
       });
       try {
-        const io = fileScenarioIO(resolve21(artifactsRoot, slug3(kase.name)));
+        const io = fileScenarioIO(resolve23(artifactsRoot, slug3(kase.name)));
         const outcome = await renderer.runScenario(session, steps, io);
         result = {
           name: kase.name,
           kind: kase.kind,
           ok: outcome.ok,
           steps: outcome.steps.map((s2) => ({ desc: s2.desc, ok: s2.ok, error: s2.error })),
-          artifacts: outcome.failureArtifacts.map((p2) => resolve21(artifactsRoot, slug3(kase.name), p2))
+          artifacts: outcome.failureArtifacts.map((p2) => resolve23(artifactsRoot, slug3(kase.name), p2))
         };
       } finally {
         session.dispose();
@@ -226652,41 +227138,14 @@ var test = async (args) => {
 };
 
 // src/commands/update.ts
-import { spawnSync as spawnSync7 } from "node:child_process";
-import { existsSync as existsSync40, readdirSync as readdirSync20 } from "node:fs";
-import { homedir as homedir9 } from "node:os";
-import { dirname as dirname21, join as join41, resolve as resolve23 } from "node:path";
+init_package();
 init_util();
-
-// src/peers.ts
-import { existsSync as existsSync39, readFileSync as readFileSync34 } from "node:fs";
-import { createRequire as createRequire7 } from "node:module";
-import { dirname as dirname20, join as join40 } from "node:path";
-var OPTIONAL_PEERS = [
-  ["lecodes-renderer", "lecodes-renderer/headless"],
-  ["lecodes-design", "lecodes-design/server"],
-  ["lecodes-3d-editor", "lecodes-3d-editor/server"],
-  ["lecodes-assets", "lecodes-assets/cli"]
-];
-var peerVersion = (name, probe) => {
-  try {
-    const require2 = createRequire7(import.meta.url);
-    let dir = dirname20(require2.resolve(probe));
-    for (let depth = 0;depth < 16; depth++) {
-      const manifest = join40(dir, "package.json");
-      if (existsSync39(manifest)) {
-        const parsed = JSON.parse(readFileSync34(manifest, "utf8"));
-        if (parsed.name === name)
-          return parsed.version ?? "unknown";
-      }
-      const parent = dirname20(dir);
-      if (parent === dir)
-        break;
-      dir = parent;
-    }
-  } catch {}
-  return null;
-};
+init_peers();
+init_peerInstall();
+import { spawnSync as spawnSync9 } from "node:child_process";
+import { existsSync as existsSync43, readdirSync as readdirSync21 } from "node:fs";
+import { homedir as homedir10 } from "node:os";
+import { dirname as dirname21, join as join44, resolve as resolve25 } from "node:path";
 
 // src/commands/types.ts
 init_api();
@@ -226694,11 +227153,11 @@ init_config();
 init_manifest();
 init_types4();
 init_util();
-import { resolve as resolve22 } from "node:path";
+import { resolve as resolve24 } from "node:path";
 var label = (bundle) => `${Object.keys(bundle).length} file(s)`;
 var types4 = async (args) => {
   const dirArg = args._[0];
-  const root = dirArg ? resolve22(dirArg) : (() => {
+  const root = dirArg ? resolve24(dirArg) : (() => {
     try {
       return findProjectRoot(process.cwd());
     } catch {
@@ -226758,10 +227217,10 @@ var types4 = async (args) => {
 
 // src/commands/update.ts
 var findProjectDir = (start) => {
-  const home = resolve23(homedir9());
-  let dir = resolve23(start);
+  const home = resolve25(homedir10());
+  let dir = resolve25(start);
   while (true) {
-    if (dir !== home && (existsSync40(join41(dir, "app.json")) || existsSync40(join41(dir, ".lecodes", "manifest.json")) || existsSync40(join41(dir, ".lecodes", "types"))))
+    if (dir !== home && (existsSync43(join44(dir, "app.json")) || existsSync43(join44(dir, ".lecodes", "manifest.json")) || existsSync43(join44(dir, ".lecodes", "types"))))
       return dir;
     const parent = dirname21(dir);
     if (parent === dir)
@@ -226791,12 +227250,12 @@ var semverNewer2 = (a2, b) => {
   return 0;
 };
 var FROM_SOURCE = /[\\/]src[\\/]commands[\\/]/.test(import.meta.url);
-var STANDALONE = existsSync40(join41(dirname21(process.execPath), "runtime")) && existsSync40(join41(dirname21(process.execPath), process.platform === "win32" ? "chisel.exe" : "chisel"));
+var STANDALONE = existsSync43(join44(dirname21(process.execPath), "runtime")) && existsSync43(join44(dirname21(process.execPath), process.platform === "win32" ? "chisel.exe" : "chisel"));
 var update = async (args) => {
   const steps = [];
   const heading = (name, what) => log(`
 ${c.bold(name)}  ${c.dim(what)}`);
-  const run2 = async (name, what, fn) => {
+  const run3 = async (name, what, fn) => {
     heading(name, what);
     try {
       const r2 = await fn();
@@ -226811,77 +227270,88 @@ ${c.bold(name)}  ${c.dim(what)}`);
     }
   };
   const root = findProjectDir(process.cwd());
-  await run2("desktop", "LeCodes Desktop host (desktop run / render --desktop)", async () => {
+  await run3("desktop", "LeCodes Desktop host (desktop run / render --desktop)", async () => {
     if (process.env.LECODES_DESKTOP_EXE)
       return ["skipped", `LECODES_DESKTOP_EXE=${process.env.LECODES_DESKTOP_EXE} (a local build; \`lecodes desktop update\` refreshes the cache anyway)`];
     await updateDesktop();
     return "ok";
   });
-  await run2("matc", "Filament material compiler for local shader compiles", async () => {
+  await run3("matc", "Filament material compiler for local shader compiles", async () => {
     if (process.env.LECODES_MATC)
       return ["skipped", `LECODES_MATC=${process.env.LECODES_MATC} (a local matc)`];
     await updateMatc();
     return "ok";
   });
-  await run2("shaders", "recompile the project's .mat shaders with the current matc", async () => {
+  await run3("shaders", "recompile the project's .mat shaders with the current matc", async () => {
     if (!root)
       return ["skipped", "not inside a project"];
     await shaders({ _: ["compile"], flags: {} });
     return "ok";
   });
-  await run2("types", flagBool(args, "local") ? "IDE types from the SDK bundled in this CLI" : "IDE types from the server", async () => {
+  await run3("types", flagBool(args, "local") ? "IDE types from the SDK bundled in this CLI" : "IDE types from the server", async () => {
     if (!root)
       return ["skipped", "not inside a project"];
     await types4({ _: [], flags: flagBool(args, "local") ? { local: true } : {} });
     return "ok";
   });
-  await run2("shells", "ios/ + android/ pins → newest SDK release + plugin tags, then re-sync", async () => {
+  await run3("shells", "ios/ + android/ pins → newest SDK release + plugin tags, then re-sync", async () => {
     if (!root)
       return ["skipped", "not inside a project"];
     if (flagBool(args, "no-shells"))
       return ["skipped", "--no-shells"];
-    const present = ["ios", "android"].filter((d) => existsSync40(join41(root, d)) && readdirSync20(join41(root, d)).length > 0);
+    const present = ["ios", "android"].filter((d) => existsSync43(join44(root, d)) && readdirSync21(join44(root, d)).length > 0);
     if (present.length === 0)
       return ["skipped", "no ios/ or android/ shell in this project (`lecodes app init ios|android`)"];
     await app({ _: ["update"], flags: {} });
     return "ok";
   });
-  await run2("cli", "lecodes-cli + its optional peers (global npm installs)", async () => {
+  await run3("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 = [];
     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" ? package_default.version : await npmLatest(name);
+      rows.push({ name, installed, latest, where });
     }
-    rows.push({ name: "lecodes-cli", installed: package_default.version, latest: await npmLatest("lecodes-cli") });
-    if (rows.every((r3) => r3.latest === null))
+    rows.push({ name: "lecodes-cli", installed: package_default.version, latest: await npmLatest("lecodes-cli"), where: "global" });
+    if (rows.every((r2) => r2.latest === null))
       return ["skipped", "npm unreachable"];
-    const behind = rows.filter((r3) => r3.installed && r3.latest && semverNewer2(r3.latest, r3.installed) > 0);
-    for (const r3 of rows) {
-      const state = !r3.installed ? c.dim("not installed (optional — npm install -g " + r3.name + ")") : !r3.latest ? c.dim("(npm: unknown)") : behind.includes(r3) ? c.yellow("→ " + r3.latest) : c.dim("(up to date)");
-      log("  " + r3.name.padEnd(18) + " " + (r3.installed ?? "").padEnd(8) + " " + state);
+    const behind = rows.filter((r2) => r2.installed && r2.latest && semverNewer2(r2.latest, r2.installed) > 0);
+    for (const r2 of rows) {
+      const state = !r2.installed ? c.dim("not installed (optional — installed on first use)") : !r2.latest ? c.dim("(npm: unknown)") : behind.includes(r2) ? c.yellow("→ " + r2.latest) : c.dim("(up to date)");
+      log("  " + r2.name.padEnd(18) + " " + (r2.installed ?? "").padEnd(8) + " " + (r2.where === "prefix" ? c.dim("peers ") : "") + state);
     }
     if (behind.length === 0)
       return "ok";
-    const specs = behind.map((r3) => r3.name + "@latest");
-    if (flagBool(args, "check"))
-      return ["updated", behind.length + " behind — run: npm install -g " + specs.join(" ")];
-    if (STANDALONE && behind.some((r3) => r3.name === "lecodes-cli")) {
+    const prefixBehind = behind.filter((r2) => r2.where === "prefix");
+    const globalSpecs = behind.filter((r2) => r2.where !== "prefix").map((r2) => r2.name + "@latest");
+    if (flagBool(args, "check")) {
+      return ["updated", behind.length + " behind — run: lecodes update" + (globalSpecs.length ? "  (global: npm install -g " + globalSpecs.join(" ") + ")" : "")];
+    }
+    const done = [];
+    if (prefixBehind.length) {
+      await installPeers(prefixBehind.map((r2) => r2.name), "lecodes update", { yes: true });
+      done.push(...prefixBehind.map((r2) => r2.name));
+    }
+    if (STANDALONE && globalSpecs.some((s2) => s2.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((s2) => !s2.startsWith("lecodes-cli@")) : specs;
-    if (toInstall.length === 0)
+    const toInstall = STANDALONE ? globalSpecs.filter((s2) => !s2.startsWith("lecodes-cli@")) : globalSpecs;
+    if (toInstall.length) {
+      log("  " + c.dim("$") + " npm install -g " + toInstall.join(" "));
+      const r2 = spawnSync9("npm", ["install", "-g", ...toInstall], { stdio: "inherit", shell: true });
+      if (r2.status !== 0)
+        throw new CliError("npm install -g exited with " + (r2.status ?? "a signal"));
+      done.push(...toInstall.map((s2) => s2.replace("@latest", "")));
+    }
+    if (done.length === 0)
       return ["skipped", "only the standalone CLI itself is behind — download the release"];
-    log("  " + c.dim("$") + " npm install -g " + toInstall.join(" "));
-    const r2 = spawnSync7("npm", ["install", "-g", ...toInstall], { stdio: "inherit", shell: true });
-    if (r2.status !== 0)
-      throw new CliError("npm install -g exited with " + (r2.status ?? "a signal"));
-    const names3 = toInstall.map((s2) => s2.replace("@latest", "")).join(", ");
-    const cliToo = toInstall.some((s2) => s2.startsWith("lecodes-cli@"));
-    return ["updated", names3 + " → latest" + (cliToo ? " (the new CLI runs from your next command)" : "")];
+    const cliToo = done.includes("lecodes-cli");
+    return ["updated", done.join(", ") + " → latest" + (cliToo ? " (the new CLI runs from your next command)" : "")];
   });
   log(`
 ${c.bold("Summary")}`);
@@ -226895,25 +227365,25 @@ ${c.bold("Summary")}`);
 };
 
 // src/index.ts
-import { existsSync as existsSync43, realpathSync as realpathSync2 } from "node:fs";
-import { delimiter as delimiter3, dirname as dirname24, join as join44 } from "node:path";
+import { existsSync as existsSync46, realpathSync as realpathSync2 } from "node:fs";
+import { delimiter as delimiter3, dirname as dirname24, join as join47 } from "node:path";
 
 // src/commands/install.ts
 init_util();
 import { execFileSync as execFileSync8 } from "node:child_process";
-import { appendFileSync as appendFileSync3, chmodSync as chmodSync2, cpSync as cpSync5, existsSync as existsSync41, mkdirSync as mkdirSync27, readFileSync as readFileSync35, realpathSync, rmSync as rmSync13, symlinkSync as symlinkSync2 } from "node:fs";
-import { homedir as homedir10 } from "node:os";
-import { basename as basename19, delimiter as delimiter2, dirname as dirname22, join as join42, resolve as resolve24, sep as sep2 } from "node:path";
+import { appendFileSync as appendFileSync3, chmodSync as chmodSync2, cpSync as cpSync5, existsSync as existsSync44, mkdirSync as mkdirSync29, readFileSync as readFileSync37, realpathSync, rmSync as rmSync13, symlinkSync as symlinkSync2 } from "node:fs";
+import { homedir as homedir11 } from "node:os";
+import { basename as basename20, delimiter as delimiter2, dirname as dirname22, join as join45, resolve as resolve26, sep as sep2 } from "node:path";
 var isWin = process.platform === "win32";
-var HOME = homedir10();
+var HOME = homedir11();
 var safeRealpath = (p2) => {
   try {
     return realpathSync(p2);
   } catch {
-    return resolve24(p2);
+    return resolve26(p2);
   }
 };
-var onPath = (dir) => {
+var onPath2 = (dir) => {
   const want = safeRealpath(dir);
   return (process.env.PATH ?? "").split(delimiter2).some((p2) => {
     if (!p2)
@@ -226927,24 +227397,24 @@ var onPath = (dir) => {
 };
 var install = async (args) => {
   const bundle = dirname22(process.execPath);
-  const exeName3 = basename19(process.execPath);
+  const exeName3 = basename20(process.execPath);
   const chiselName = isWin ? "chisel.exe" : "chisel";
-  if (!existsSync41(join42(bundle, "runtime")) || !existsSync41(join42(bundle, chiselName))) {
+  if (!existsSync44(join45(bundle, "runtime")) || !existsSync44(join45(bundle, chiselName))) {
     throw new CliError("`lecodes install` only works from the packaged release build (the archive containing lecodes + " + "chisel + runtime/). You appear to be running from source or an npm install — install globally " + "with your package manager there instead.");
   }
-  const companions = [exeName3, chiselName, "runtime", "README.txt"].filter((f3) => existsSync41(join42(bundle, f3)));
+  const companions2 = [exeName3, chiselName, "runtime", "README.txt"].filter((f3) => existsSync44(join45(bundle, f3)));
   if (isWin)
-    return installWindows(args, bundle, companions);
-  return installUnix(args, bundle, companions);
+    return installWindows(args, bundle, companions2);
+  return installUnix(args, bundle, companions2);
 };
-var copyBundle = (bundle, target, companions) => {
-  mkdirSync27(target, { recursive: true });
+var copyBundle = (bundle, target, companions2) => {
+  mkdirSync29(target, { recursive: true });
   if (safeRealpath(target) === safeRealpath(bundle))
     return;
-  for (const f3 of companions) {
-    const dest = join42(target, f3);
+  for (const f3 of companions2) {
+    const dest = join45(target, f3);
     rmSync13(dest, { recursive: true, force: true });
-    cpSync5(join42(bundle, f3), dest, { recursive: true });
+    cpSync5(join45(bundle, f3), dest, { recursive: true });
   }
 };
 var permError = (e2, dir, system) => {
@@ -226954,43 +227424,43 @@ var permError = (e2, dir, system) => {
   }
   return new CliError(`Install failed: ${e2 instanceof Error ? e2.message : String(e2)}`);
 };
-var installUnix = (args, bundle, companions) => {
+var installUnix = (args, bundle, companions2) => {
   const system = flagBool(args, "system");
-  const libDir = resolve24(flagStr(args, "dir") ?? (system ? "/usr/local/lib/lecodes-cli" : join42(HOME, ".local", "lib", "lecodes-cli")));
-  const binDir = resolve24(flagStr(args, "bin") ?? (system ? "/usr/local/bin" : join42(HOME, ".local", "bin")));
-  const link2 = join42(binDir, "lecodes");
+  const libDir = resolve26(flagStr(args, "dir") ?? (system ? "/usr/local/lib/lecodes-cli" : join45(HOME, ".local", "lib", "lecodes-cli")));
+  const binDir = resolve26(flagStr(args, "bin") ?? (system ? "/usr/local/bin" : join45(HOME, ".local", "bin")));
+  const link2 = join45(binDir, "lecodes");
   try {
-    copyBundle(bundle, libDir, companions);
-    chmodSync2(join42(libDir, "lecodes"), 493);
-    chmodSync2(join42(libDir, "chisel"), 493);
+    copyBundle(bundle, libDir, companions2);
+    chmodSync2(join45(libDir, "lecodes"), 493);
+    chmodSync2(join45(libDir, "chisel"), 493);
   } catch (e2) {
     throw permError(e2, libDir, system);
   }
   try {
-    mkdirSync27(binDir, { recursive: true });
+    mkdirSync29(binDir, { recursive: true });
     rmSync13(link2, { force: true });
-    symlinkSync2(join42(libDir, "lecodes"), link2);
+    symlinkSync2(join45(libDir, "lecodes"), link2);
   } catch (e2) {
     throw permError(e2, binDir, system);
   }
   success(`Installed to ${c.bold(libDir)}`);
-  log(`  ${c.dim(link2 + " → " + join42(libDir, "lecodes"))}`);
+  log(`  ${c.dim(link2 + " → " + join45(libDir, "lecodes"))}`);
   finishPathUnix(args, binDir);
 };
 var shellRc = () => {
-  const shell = basename19(process.env.SHELL ?? "");
+  const shell = basename20(process.env.SHELL ?? "");
   if (shell === "zsh")
-    return { file: join42(HOME, ".zshrc"), name: "~/.zshrc" };
+    return { file: join45(HOME, ".zshrc"), name: "~/.zshrc" };
   if (shell === "bash")
-    return { file: join42(HOME, ".bashrc"), name: "~/.bashrc" };
-  return { file: join42(HOME, ".profile"), name: "~/.profile" };
+    return { file: join45(HOME, ".bashrc"), name: "~/.bashrc" };
+  return { file: join45(HOME, ".profile"), name: "~/.profile" };
 };
 var PATH_MARKER = "# Added by `lecodes install`";
 var appendPathToShellRc = (binDir) => {
   const { file, name } = shellRc();
   const line = `export PATH="${binDir}:$PATH"`;
   try {
-    const existing = existsSync41(file) ? readFileSync35(file, "utf8") : "";
+    const existing = existsSync44(file) ? readFileSync37(file, "utf8") : "";
     if (existing.includes(line))
       return name;
     appendFileSync3(file, `${existing && !existing.endsWith(`
@@ -227005,7 +227475,7 @@ ${line}
   }
 };
 var finishPathUnix = (args, binDir) => {
-  if (onPath(binDir)) {
+  if (onPath2(binDir)) {
     log(`  Run ${c.bold("lecodes --version")} in a new shell to verify.`);
     return;
   }
@@ -227027,15 +227497,15 @@ var finishPathUnix = (args, binDir) => {
   log(`  • let install do it: re-run with ${c.bold("--modify-path")}`);
   log(`  • or install system-wide (no PATH edit): ${c.bold("sudo lecodes install --system")}`);
 };
-var installWindows = (args, bundle, companions) => {
-  const target = resolve24(flagStr(args, "dir") ?? join42(process.env.LOCALAPPDATA ?? join42(HOME, "AppData", "Local"), "Programs", "lecodes-cli"));
+var installWindows = (args, bundle, companions2) => {
+  const target = resolve26(flagStr(args, "dir") ?? join45(process.env.LOCALAPPDATA ?? join45(HOME, "AppData", "Local"), "Programs", "lecodes-cli"));
   try {
-    copyBundle(bundle, target, companions);
+    copyBundle(bundle, target, companions2);
   } catch (e2) {
     throw new CliError(`Install failed writing to ${target}: ${e2 instanceof Error ? e2.message : String(e2)}`);
   }
   success(`Installed to ${c.bold(target)}`);
-  if (onPath(target)) {
+  if (onPath2(target)) {
     log(`  Already on PATH — run ${c.bold("lecodes --version")} in a new terminal.`);
     return;
   }
@@ -227067,9 +227537,9 @@ var addToUserPathWindows = (dir) => {
 init_util();
 
 // src/projectEnv.ts
-import { existsSync as existsSync42, readFileSync as readFileSync36 } from "node:fs";
-import { homedir as homedir11 } from "node:os";
-import { dirname as dirname23, join as join43, resolve as resolve25 } from "node:path";
+import { existsSync as existsSync45, readFileSync as readFileSync38 } from "node:fs";
+import { homedir as homedir12 } from "node:os";
+import { dirname as dirname23, join as join46, resolve as resolve27 } from "node:path";
 var KEY_RE = /^(LECODES|CREATOR)_[A-Z0-9_]+$/;
 var parseDotEnv = (text) => {
   const out = {};
@@ -227104,17 +227574,20 @@ var applyDotEnv = (parsed, dir, env) => {
       continue;
     let value = raw;
     if (value.startsWith("./") || value.startsWith("../"))
-      value = resolve25(dir, value);
+      value = resolve27(dir, value);
     else if (value === "~" || value.startsWith("~/"))
-      value = join43(homedir11(), value.slice(1));
+      value = join46(homedir12(), value.slice(1));
     out[key] = value;
   }
   return out;
 };
 var findEnvRoot = (start) => {
-  let dir = resolve25(start);
+  let dir = resolve27(start);
+  const home = resolve27(homedir12());
   while (true) {
-    if (existsSync42(join43(dir, "app.json")) || existsSync42(join43(dir, ".lecodes")))
+    if (dir === home)
+      return null;
+    if (existsSync45(join46(dir, "app.json")) || existsSync45(join46(dir, ".lecodes")))
       return dir;
     const parent = dirname23(dir);
     if (parent === dir)
@@ -227127,10 +227600,10 @@ var loadProjectEnv = (cwd = process.cwd()) => {
     const root = findEnvRoot(cwd);
     if (!root)
       return [];
-    const file = join43(root, ".env");
-    if (!existsSync42(file))
+    const file = join46(root, ".env");
+    if (!existsSync45(file))
       return [];
-    const added = applyDotEnv(parseDotEnv(readFileSync36(file, "utf8")), root, process.env);
+    const added = applyDotEnv(parseDotEnv(readFileSync38(file, "utf8")), root, process.env);
     for (const [k, v] of Object.entries(added))
       process.env[k] = v;
     return Object.keys(added);
@@ -227140,10 +227613,11 @@ var loadProjectEnv = (cwd = process.cwd()) => {
 };
 
 // src/index.ts
+init_peers();
 var STANDALONE2 = (() => {
   const dir = dirname24(process.execPath);
   const chisel = process.platform === "win32" ? "chisel.exe" : "chisel";
-  return existsSync43(join44(dir, "runtime")) && existsSync43(join44(dir, chisel));
+  return existsSync46(join47(dir, "runtime")) && existsSync46(join47(dir, chisel));
 })();
 var INSTALLED = STANDALONE2 && (() => {
   const exe = process.platform === "win32" ? "lecodes.exe" : "lecodes";
@@ -227158,8 +227632,8 @@ var INSTALLED = STANDALONE2 && (() => {
     if (!d)
       return false;
     try {
-      const cand = join44(d, exe);
-      return existsSync43(cand) && realpathSync2(cand) === self2;
+      const cand = join47(d, exe);
+      return existsSync46(cand) && realpathSync2(cand) === self2;
     } catch {
       return false;
     }
@@ -227227,6 +227701,14 @@ ${c.bold("Commands:")}
                                   --host <ip>     LAN address to advertise (default: auto-detect)
                                   --entry <path>  override the entrypoint
                                   --no-qr         don't render the QR code
+                                  --android       open the dev url in the LeCodes app on the phone
+                                                    plugged in over adb (adb reverse: no Wi-Fi/LAN
+                                                    address needed). --serial <id> picks a device,
+                                                    --apk <file> installs first, --package <name>
+                                                    (default com.letary.lecodes). Device logs stream
+                                                    here. --time <s> --png <file>: bounded check —
+                                                    screenshot after <s> seconds, force-stop, exit
+                                                    (exit 1 on a crash). Ctrl+C force-stops the app.
                                   --web           also open the app in the browser (Web Lite host:
                                                     same bundle + hot reload, camera/map plugins
                                                     have web twins; the /web/ URL is served always)
@@ -227422,12 +227904,15 @@ ${c.bold("Commands:")}
                                   --cell <m> (0.25)  --cell-height <m> (0.1)  --tile <cells> (48)
                                   --obj              also write <n>.navmesh.obj to inspect
                                   --frames <n>       load headroom (900) --logs  host output
-  shaders [compile|update]      The project's custom shaders (.mat) and their local compile:
+  shaders [compile|update|new]  The project's custom shaders (.mat) and their local compile:
                                   no args lists the shaders + their compile state; compile
                                   compiles them all into .lecodes/shaders (the same pass
                                   'lecodes dev' runs on the fly — via Filament's matc,
                                   downloaded on first use to ~/.lecodes/matc); update
-                                  downloads the newest matc (run after an engine upgrade)
+                                  downloads the newest matc (run after an engine upgrade);
+                                  new <name> [--ref lit] [--dir d] [--force] writes a fresh
+                                  .mat + .material.ts: the starter, or a copy of the engine's
+                                  own lit / unlit / particles / … source to start from
   scene [path]                  LeCodes Scene Editor — visually edit a .scene.ts (tree, inspector,
                                   gizmo) on local files (needs the optional 'lecodes-3d-editor' package;
                                   works inside a cloned project or standalone in any folder)
@@ -227542,12 +228027,13 @@ LECODES_DESKTOP_EXE, LECODES_MATC, LECODES_NOTARY_PROFILE, LECODES_MACOS_SIGN_ID
 var commands = { init: init2, login, create, clone: clone3, link, status: status3, diff: diff2, pull, push, compile: compile2, preview: previewLegacy, render, test, design, scene, thumbs, dev, app, pn, desktop, shaders, assets, lightmap, navmesh, update };
 if (STANDALONE2)
   commands.install = install;
-var readVersion = () => package_default.version ?? "unknown";
+var readVersion2 = () => package_default.version ?? "unknown";
 var printVersion = () => {
-  const rows = [["lecodes-cli", readVersion()]];
+  const rows = [["lecodes-cli", readVersion2()]];
   for (const [name, probe] of OPTIONAL_PEERS) {
     const version = peerVersion(name, probe);
-    rows.push([name, version ?? c.dim("not installed")]);
+    const where = peerSource(name, probe);
+    rows.push([name, version ? where === "prefix" ? `${version} ${c.dim("(~/.lecodes/peers)")}` : version : c.dim("not installed — installed on first use")]);
   }
   const desktopVersion = selectedDesktopVersion();
   rows.push(["lecodes-desktop", installedDesktopVersions().includes(desktopVersion) ? desktopVersion : `${desktopVersion} ${c.dim("(not downloaded — fetched on first `render --desktop`)")}`]);
@@ -227561,6 +228047,8 @@ var main = async () => {
   const argv = process.argv.slice(2);
   const command = argv[0];
   loadProjectEnv();
+  if (argv.includes("--yes") || argv.includes("-y"))
+    process.env.LECODES_YES = "1";
   if (!command || command === "help" || command === "--help" || command === "-h") {
     log(HELP);
     return;
@@ -227569,14 +228057,14 @@ var main = async () => {
     printVersion();
     return;
   }
-  const run2 = commands[command];
-  if (!run2) {
+  const run3 = commands[command];
+  if (!run3) {
     log(c.red(`Unknown command: ${command}`));
     log(HELP);
     process.exitCode = 1;
     return;
   }
-  await run2(Object.assign(parseArgs(argv.slice(1)), { _raw: argv.slice(1) }));
+  await run3(Object.assign(parseArgs(argv.slice(1)), { _raw: argv.slice(1) }));
 };
 main().catch((e2) => {
   if (e2 instanceof CliError)