lecodes-cli 0.16.2 → 0.17.0

package/dist/index.js

@@ -215816,7 +215816,7 @@ var require_main = __commonJS((exports, module) => {
 // package.json
 var package_default = {
   name: "lecodes-cli",
-  version: "0.16.2",
+  version: "0.17.0",
   dependencies: {
     "@letary/chisel": "^0.8.0",
     jimp: "^1.6.1"
@@ -215827,11 +215827,12 @@ var package_default = {
     "qrcode-terminal": "^0.12.0",
     "lecodes-3d-editor": "workspace:*",
     "lecodes-assets": "workspace:*",
-    sdk: "workspace:*"
+    sdk: "workspace:*",
+    "viewer-lite": "workspace:*"
   },
   peerDependencies: {
     "lecodes-design": "^0.8.1",
-    "lecodes-renderer": "^0.8.4",
+    "lecodes-renderer": "^0.8.5",
     "lecodes-3d-editor": "^0.3.0",
     "lecodes-assets": "^0.1.0"
   },
@@ -215891,8 +215892,8 @@ import { basename as basename6, dirname as dirname12, join as join17, resolve as
 init_api();
 init_config();
 init_manifest();
-import { writeFileSync as writeFileSync7 } from "node:fs";
-import { basename as basename3, resolve } from "node:path";
+import { writeFileSync as writeFileSync8 } from "node:fs";
+import { basename as basename3, resolve as resolve2 } from "node:path";
 
 // src/compile/collect.ts
 init_localFiles();
@@ -216005,6 +216006,226 @@ init_projectCompile();
 init_fonts();
 init_assetIcons();
 init_ignore();
+
+// src/commands/appShared.ts
+init_manifest();
+init_ignore();
+init_util();
+import { execFileSync } from "node:child_process";
+import { existsSync as existsSync10, mkdirSync as mkdirSync6, readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { dirname as dirname8, join as join12, resolve } from "node:path";
+var FIRST_PARTY_PLUGINS = {
+  camera: "letary/lecodes-plugins",
+  "qr-scanner": "letary/lecodes-plugins",
+  geolocation: "letary/lecodes-plugins",
+  push: "letary/lecodes-plugins"
+};
+var readAppConfigAt = (root) => readJson(join12(root, "app.json"));
+var DESKTOP_DEFAULT_WINDOW = { width: 1280, height: 720 };
+var desktopDefaultViewport = (root) => {
+  const cfg = readAppConfigAt(root);
+  if (!cfg?.desktop || cfg.ios || cfg.android)
+    return null;
+  return {
+    width: cfg.desktop.window?.width ?? DESKTOP_DEFAULT_WINDOW.width,
+    height: cfg.desktop.window?.height ?? DESKTOP_DEFAULT_WINDOW.height
+  };
+};
+var readJson = (path) => {
+  if (!existsSync10(path))
+    return null;
+  try {
+    return JSON.parse(readFileSync11(path, "utf8").replace(/^\uFEFF/, ""));
+  } catch {
+    throw new CliError(`Invalid JSON in ${path}`);
+  }
+};
+var writeJson = (path, value) => writeFileSync7(path, JSON.stringify(value, null, 2) + `
+`);
+var projectRoot = () => {
+  try {
+    return findProjectRoot(process.cwd());
+  } catch {
+    return process.cwd();
+  }
+};
+var git = (cwd, ...args) => execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+var slugify = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "app";
+var runTool = (cwd, cmd, args) => {
+  try {
+    return execFileSync(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 128 * 1024 * 1024 });
+  } catch (e) {
+    const err = e;
+    const tail = ((err.stdout ?? "") + `
+` + (err.stderr ?? "")).split(`
+`).filter((l) => l.trim()).slice(-25).join(`
+`);
+    throw new CliError(`${cmd} ${args[0] ?? ""} failed:
+${tail}`);
+  }
+};
+var ensureShellIgnored = (root, dir) => {
+  const ignorePath = join12(root, ".lecodesignore");
+  const ignore = existsSync10(ignorePath) ? readFileSync11(ignorePath, "utf8") : DEFAULT_IGNORE_FILE;
+  if (new RegExp(`^${dir}\\/$`, "m").test(ignore))
+    return;
+  const comment = ignore.includes("# Native app shells") ? "" : "# Native app shells — generated by `lecodes app init`, never pushed to LeCodes.\n";
+  writeFileSync7(ignorePath, ignore.replace(/\n*$/, `
+`) + `
+` + comment + `${dir}/
+`);
+  log(`${c.green("updated")}   .lecodesignore  (+ ${dir}/)`);
+};
+var SDK_VARIANTS = ["core", "2d", "3d", "full"];
+var detectEngines = (bundleJs) => {
+  const lines = [];
+  for (const line of bundleJs.split(`
+`)) {
+    if (!line.startsWith("//"))
+      break;
+    lines.push(line);
+  }
+  const header = lines.join(`
+`);
+  return { gl: !/^\/\/ gl: disable$/m.test(header), g2: /^\/\/ 2d: enable$/m.test(header) };
+};
+var resolveVariant = (requested, bundleJs, configKey = "ios.variant") => {
+  const uses = detectEngines(bundleJs);
+  const detected = uses.gl && uses.g2 ? "full" : uses.gl ? "3d" : uses.g2 ? "2d" : "core";
+  if (requested === "auto")
+    return { variant: detected, detected };
+  const variant = requested;
+  const missing = [
+    uses.gl && variant !== "3d" && variant !== "full" ? "3D" : null,
+    uses.g2 && variant !== "2d" && variant !== "full" ? "2D" : null
+  ].filter(Boolean);
+  if (missing.length > 0) {
+    warn(`project uses the ${missing.join(" + ")} engine but ${configKey} forces "${variant}" — those scenes won't run on device; remove ${configKey} to auto-select "${detected}".`);
+  }
+  return { variant, detected };
+};
+var VERSION_RE = /^\d+\.\d+\.\d+$/;
+var cmpVersion = (a, b) => {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0;i < 3; i++) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+      return (pa[i] ?? 0) - (pb[i] ?? 0);
+  }
+  return 0;
+};
+var fetchLatestSdkVersion = async (repo) => {
+  const url = `https://api.github.com/repos/${repo}/releases/latest`;
+  const res = await fetch(url, { headers: { accept: "application/vnd.github+json", "user-agent": "lecodes-cli" } });
+  if (!res.ok)
+    throw new CliError(`Could not read the latest ${repo} release (HTTP ${res.status}) — ${url}`);
+  const tag = (await res.json()).tag_name?.replace(/^v/, "") ?? "";
+  if (!VERSION_RE.test(tag))
+    throw new CliError(`${repo} latest release has no x.y.z tag (got "${tag}")`);
+  return tag;
+};
+var resolveSdkVersion = async (pin, fallback, opts) => {
+  if (pin !== "latest") {
+    if (!VERSION_RE.test(pin)) {
+      throw new CliError(`app.json ${opts.configKey} must be "latest" or an exact x.y.z release (got "${pin}").`);
+    }
+    if (cmpVersion(pin, opts.minVersion) < 0) {
+      throw new CliError(`app.json ${opts.configKey} ${pin} is older than the ${opts.minVersion} these generated shells need.`);
+    }
+    return pin;
+  }
+  try {
+    return await fetchLatestSdkVersion(opts.repo);
+  } catch (e) {
+    const kept = fallback ?? opts.minVersion;
+    warn(`Could not resolve the latest SDK (${e.message}) — staying on ${kept}.`);
+    return kept;
+  }
+};
+var ensureRepo = (repo, wantTag, lock) => {
+  const override = process.env.LECODES_PLUGINS_DIR;
+  if (override) {
+    note(`Using local plugin checkout ${override} (LECODES_PLUGINS_DIR)`);
+    return { dir: resolve(override), tag: "local", commit: "local" };
+  }
+  const cache = join12(homedir3(), ".lecodes", "plugins", repo.replace("/", "__"));
+  const url = `https://github.com/${repo}.git`;
+  if (!existsSync10(join12(cache, ".git"))) {
+    mkdirSync6(dirname8(cache), { recursive: true });
+    note(`Cloning ${url}…`);
+    git(dirname8(cache), "clone", "--quiet", url, cache);
+  }
+  let tag = lock?.tag ?? wantTag;
+  let commit = lock?.commit;
+  if (commit) {
+    try {
+      git(cache, "cat-file", "-e", `${commit}^{commit}`);
+    } catch {
+      git(cache, "fetch", "--quiet", "--tags", "origin");
+    }
+  } else {
+    git(cache, "fetch", "--quiet", "--tags", "origin");
+    if (!tag) {
+      tag = git(cache, "tag", "--list", "v*", "--sort=-version:refname").split(`
+`)[0] ?? "";
+      if (!tag)
+        throw new CliError(`${repo} has no v* version tags to install from`);
+    }
+    commit = git(cache, "rev-list", "-n", "1", tag);
+  }
+  git(cache, "checkout", "--quiet", "--detach", commit);
+  return { dir: cache, tag: tag ?? "unknown", commit };
+};
+var resolvePlugin = (id, spec, lock, platform) => {
+  let repo;
+  let subdir;
+  let wantTag = null;
+  if (spec.startsWith("github:")) {
+    const [repoPart, tagPart] = spec.slice("github:".length).split("@");
+    repo = repoPart;
+    wantTag = tagPart ?? null;
+    subdir = "";
+  } else {
+    repo = FIRST_PARTY_PLUGINS[id];
+    if (!repo) {
+      throw new CliError(`Unknown plugin "${id}" — known: ${Object.keys(FIRST_PARTY_PLUGINS).join(", ")}, or use a github:owner/repo spec.`);
+    }
+    subdir = `plugins/${id}`;
+  }
+  const checkout = ensureRepo(repo, wantTag, lock?.repo === repo ? lock : undefined);
+  const dir = subdir ? join12(checkout.dir, subdir) : checkout.dir;
+  const manifest = readJson(join12(dir, "lecodes-plugin.json"));
+  if (!manifest)
+    throw new CliError(`Plugin "${id}": no lecodes-plugin.json in ${dir}`);
+  if (manifest.id !== id)
+    throw new CliError(`Plugin "${id}": manifest declares id "${manifest.id}"`);
+  if (!manifest[platform]) {
+    throw new CliError(`Plugin "${id}" does not support ${platform === "ios" ? "iOS" : "Android"} (manifest "${platform}" is null)`);
+  }
+  if (spec.startsWith("github:")) {
+    const names = [...manifest.provides?.views ?? [], ...manifest.provides?.services ?? []];
+    for (const name of names) {
+      if (!name.includes("."))
+        warn(`Plugin "${id}" provides bare channel name "${name}" — third-party names should be vendor-prefixed (e.g. "acme.${name}").`);
+    }
+  }
+  return {
+    id,
+    dir,
+    manifest,
+    lock: { repo, tag: checkout.tag, commit: checkout.commit, version: manifest.version ?? "unknown" }
+  };
+};
+var latestPluginTag = (repo) => {
+  try {
+    return ensureRepo(repo, null, undefined).tag;
+  } catch {
+    return null;
+  }
+};
+
+// src/commands/compile.ts
 init_util();
 var compile2 = async (args) => {
   await compileImpl(args);
@@ -216016,7 +216237,7 @@ var compileImpl = async (args, shell) => {
   if (out && isNullSink(out)) {
     note(`Discarded output (${out})`);
   } else if (out) {
-    writeFileSync7(resolve(out), js);
+    writeFileSync8(resolve2(out), js);
     note(`Wrote ${out} (${js.length} bytes)`);
   } else {
     process.stdout.write(js);
@@ -216027,7 +216248,7 @@ var compileImpl = async (args, shell) => {
   }
   return resources;
 };
-var buildBundle = async (args, shell) => {
+var buildBundle = async (args, shell, opts = {}) => {
   let root;
   let manifest;
   try {
@@ -216046,19 +216267,21 @@ var buildBundle = async (args, shell) => {
     const config = loadConfig();
     const apiUrl = requireApiUrl(config);
     const token = requireToken(config);
+    const publicUrlFlag = flagStr(args, "public-url");
+    localAssets = !!shell || !!opts.localAssets && publicUrlFlag === undefined && !flagBool(args, "remote-assets");
     note("Resolving project assets…");
     const project = await getProject(apiUrl, token, manifest.uuid);
-    ({ entries, warnings } = collectEntries(root, manifest, project, { warnMissingUrl: !shell }));
+    ({ entries, warnings } = collectEntries(root, manifest, project, { warnMissingUrl: !localAssets }));
     name = manifest.name;
-    publicUrl = flagStr(args, "public-url") ?? apiUrl;
-    localAssets = !!shell;
-    if (shell && shell.remotePatterns.length > 0) {
-      const isRemote = buildGlobMatcher(shell.remotePatterns);
+    publicUrl = publicUrlFlag ?? apiUrl;
+    const remotePatterns = shell?.remotePatterns ?? (localAssets ? readAppConfigAt(root)?.resources?.remote ?? [] : []);
+    if (localAssets && remotePatterns.length > 0) {
+      const isRemote = buildGlobMatcher(remotePatterns);
       for (const e of entries) {
         if (e.type !== "resource" || !isRemote(e.path))
           continue;
         if (!e.fileSrc) {
-          warnErr(`${e.path} matches resources.remote but has no server URL yet — bundling it (push, then re-sync).`);
+          warnErr(`${e.path} matches resources.remote but has no server URL yet — ${shell ? "bundling it (push, then re-sync)" : "reading it from the working tree"}.`);
           continue;
         }
         e.remote = true;
@@ -216068,13 +216291,16 @@ var buildBundle = async (args, shell) => {
     const publicUrlFlag = flagStr(args, "public-url");
     localAssets = shell ? true : publicUrlFlag === undefined;
     publicUrl = publicUrlFlag ?? "";
+    if (opts.localAssets && flagBool(args, "remote-assets")) {
+      warnErr("This is a local project (no server) — assets always load from the working tree.");
+    }
     ({ entries, warnings } = collectLocalEntries(root, null, ""));
     name = basename3(root);
     if (shell && shell.remotePatterns.length > 0) {
       warnErr("resources.remote needs a server-backed project (a streamed asset needs a server URL) — bundling everything.");
     }
   }
-  const fontsHeader = await applyProjectFonts(entries, manifest && !shell ? { mode: "cdn", root, publicUrl } : {
+  const fontsHeader = await applyProjectFonts(entries, manifest && !localAssets ? { mode: "cdn", root, publicUrl } : {
     mode: "vendor",
     root,
     vendorDir: root,
@@ -216822,358 +217048,140 @@ let package = Package(
             name: "LeCodesRuntime",
             dependencies: [
                 ${runtimeDeps.join(`,
-                `)},
-            ],
-            path: "Sources/LeCodesRuntime"
-        ),${pluginTargets}
-    ]
-)
-`;
-};
-var runtimeSwiftTemplate = (plugins, projectUuid) => {
-  const imports = plugins.map((p) => `import ${p.module}
-`).join("");
-  const identity = !projectUuid ? "" : `    // World identity: this shell IS the project — the engine attributes the boot world so
-    // identity-gated services (push registration) see the app's uuid from its first
-    // synchronous statement. Baked from .lecodes/manifest.json by \`lecodes app sync\`.
-    engine.bootProjectUuid = "${projectUuid}"
-`;
-  const calls = plugins.map((p) => `    ${p.register}.register(in: engine)
-`).join("");
-  const body = identity + calls;
-  return `//
-//  LeCodesRuntime.swift
-//  GENERATED by lecodes — regenerated by \`lecodes app sync\`; do not edit.
-//
-//  Re-exports the SDK (so app code needs only \`import LeCodesRuntime\`) and registers
-//  every plugin installed in app.json.
-//
-
-@_exported import LeCodesSDK
-${imports}
-public func registerBundledPlugins(in engine: LeCodesEngine) {
-${body === "" ? `
-` : body}}
-`;
-};
-var IOS_README = `# ios/ — native Xcode shell
-
-Generated by \`lecodes app init ios\` for the LeCodes project one folder up. The app runs the
-compiled bundle in \`App/Resources/app.js\` — fully offline, nothing fetched at launch. This
-folder is ignored by the platform (\`ios/\` in \`.lecodesignore\`) and is never pushed to LeCodes.
-
-## Daily workflow
-
-Edit the app's code at the project root (\`main.ts\` …), then:
-
-\`\`\`
-lecodes app sync     # recompile app.js + assets into the shell, vendor plugins
-lecodes app open     # open App.xcodeproj in Xcode — build & run from there
-\`\`\`
-
-\`lecodes app doctor\` preflights builds; \`lecodes app build ios\` archives and exports an
-.ipa; \`lecodes app upload ios\` sends the archive to App Store Connect.
-
-## SDK version
-
-\`../app.json\` \`ios.sdk\` is the exact \`lecodes-ios-sdk\` release this shell links —
-\`lecodes app init\` pinned the newest one at the time, so builds stay reproducible.
-
-\`\`\`
-lecodes app update           # → newest SDK release + newest plugin tags, then sync
-lecodes app update --check   # what's available, writes nothing
-lecodes app update --sdk 1.3.0
-\`\`\`
-
-Set \`"sdk": "latest"\` instead of a version to re-resolve on every sync (needs network;
-offline it keeps whatever the shell already links). The pin is exact rather than a range
-because the CLI also downloads that release's filament resources bundle into
-\`App/Resources/\` — the two halves of one SDK must not drift apart.
-
-## Who owns what
-
-Yours — \`lecodes app sync\` never touches these:
-
-- \`App/*.swift\` (AppDelegate, SceneDelegate, ViewController) — customize freely, add files.
-  App-local native code goes here too: add a Swift file that calls
-  \`engine.registerCallback\` / \`registerService\`, and invoke it from ViewController.
-- \`App/Assets.xcassets/\` — the app icon. Easy path: set \`app.json\` \`"icon"\` to a square
-  ≥1024px image and every sync renders AppIcon.png from it (flattened over \`"iconBackground"\`,
-  default white — App Store icons must be opaque). Or leave the key unset and drop a
-  1024×1024 PNG into AppIcon.appiconset/ yourself — sync never touches it then.
-- \`App/Base.lproj/LaunchScreen.storyboard\`
-
-CLI-owned — regenerated on every sync, hand edits are overwritten:
-
-- \`App/Resources/\` — the compiled app.js + every asset it references (fonts included), so
-  the app runs fully offline. Globs in app.json \`"resources": {"remote": [...]}\` opt heavy
-  assets (videos, big models) back into streaming from the server instead.
-- \`App/Info.plist\` — template + the installed plugins' usage keys
-- \`App/App.entitlements\` — the capabilities the installed plugins declare (e.g. push)
-- \`LeCodesRuntime/\` — local Swift package: the LeCodesSDK dependency, vendored plugin
-  sources (Sources/<Module>/), and the registerBundledPlugins entry point
-- the version values inside \`App.xcodeproj/project.pbxproj\` (from app.json)
-- this README
-
-## SDK variant
-
-Sync links the smallest SDK product that covers what the compiled bundle actually uses:
-\`core\` (UI only), \`2d\` (+ 2D engine with physics), \`3d\` (+ 3D/AR engine with physics,
-~17 MB heavier), or \`full\` (everything). Adding your first 3D scene or 2D game to the
-project switches it automatically on the next sync; set \`ios.variant\` in \`../app.json\`
-to pin one instead.
-
-## Over-the-air updates
-
-With \`"update": true\` in \`../app.json\` (server-backed projects; or
-\`"update": {"url": "https://…/app.js"}\` for any static hosting), the app checks that URL
-at launch — natively, before any JS runs, so a broken bundle can never block its own fix.
-Unchanged code costs a ~0-byte 304; new code downloads in the background and runs on the
-NEXT launch. Offline it's a silent no-op — the app always launches from a local bundle.
-An App Store update always beats a cached OTA bundle. JS only: adding/removing native
-plugins still needs a store release.
-
-Shipping an update is just \`lecodes push --publish\` — no rebuild, no store review:
-running apps download the new code on their next launch and run it on the launch after.
-
-Shells generated before OTA support have a \`ViewController.swift\` that reads app.js from
-\`Bundle.main\` directly, so downloaded updates would never run — and since \`App/*.swift\`
-is yours, sync won't rewrite it (\`lecodes app doctor\` flags this). Replace the
-\`Bundle.main\` load with:
-
-\`\`\`swift
-LeCodesUpdater.checkForUpdate()
-guard let code = LeCodesUpdater.activeBundle() else {
-    print("LeCodes: bundled app.js is missing — run \`lecodes app sync\`")
-    return
-}
-engine.run(code)
-\`\`\`
-
-## Config
-
-Identity lives in \`../app.json\` (name, version, plugins, ios.bundleId / teamId / variant /
-buildNumber) — edit it there, then re-run \`lecodes app sync\`. Plugins are managed with
-\`lecodes app plugin add <id | github:owner/repo[@tag]>\` and pinned in \`../plugins.lock.json\`.
-`;
-
-// src/commands/appShared.ts
-init_manifest();
-init_ignore();
-init_util();
-import { execFileSync } from "node:child_process";
-import { existsSync as existsSync10, mkdirSync as mkdirSync6, readFileSync as readFileSync11, writeFileSync as writeFileSync8 } from "node:fs";
-import { homedir as homedir3 } from "node:os";
-import { dirname as dirname8, join as join12, resolve as resolve2 } from "node:path";
-var FIRST_PARTY_PLUGINS = {
-  camera: "letary/lecodes-plugins",
-  "qr-scanner": "letary/lecodes-plugins",
-  geolocation: "letary/lecodes-plugins",
-  push: "letary/lecodes-plugins"
-};
-var readAppConfigAt = (root) => readJson(join12(root, "app.json"));
-var DESKTOP_DEFAULT_WINDOW = { width: 1280, height: 720 };
-var desktopDefaultViewport = (root) => {
-  const cfg = readAppConfigAt(root);
-  if (!cfg?.desktop || cfg.ios || cfg.android)
-    return null;
-  return {
-    width: cfg.desktop.window?.width ?? DESKTOP_DEFAULT_WINDOW.width,
-    height: cfg.desktop.window?.height ?? DESKTOP_DEFAULT_WINDOW.height
-  };
-};
-var readJson = (path) => {
-  if (!existsSync10(path))
-    return null;
-  try {
-    return JSON.parse(readFileSync11(path, "utf8").replace(/^\uFEFF/, ""));
-  } catch {
-    throw new CliError(`Invalid JSON in ${path}`);
-  }
-};
-var writeJson = (path, value) => writeFileSync8(path, JSON.stringify(value, null, 2) + `
-`);
-var projectRoot = () => {
-  try {
-    return findProjectRoot(process.cwd());
-  } catch {
-    return process.cwd();
-  }
-};
-var git = (cwd, ...args) => execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
-var slugify = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "app";
-var runTool = (cwd, cmd, args) => {
-  try {
-    return execFileSync(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 128 * 1024 * 1024 });
-  } catch (e) {
-    const err = e;
-    const tail = ((err.stdout ?? "") + `
-` + (err.stderr ?? "")).split(`
-`).filter((l) => l.trim()).slice(-25).join(`
-`);
-    throw new CliError(`${cmd} ${args[0] ?? ""} failed:
-${tail}`);
-  }
-};
-var ensureShellIgnored = (root, dir) => {
-  const ignorePath = join12(root, ".lecodesignore");
-  const ignore = existsSync10(ignorePath) ? readFileSync11(ignorePath, "utf8") : DEFAULT_IGNORE_FILE;
-  if (new RegExp(`^${dir}\\/$`, "m").test(ignore))
-    return;
-  const comment = ignore.includes("# Native app shells") ? "" : "# Native app shells — generated by `lecodes app init`, never pushed to LeCodes.\n";
-  writeFileSync8(ignorePath, ignore.replace(/\n*$/, `
-`) + `
-` + comment + `${dir}/
-`);
-  log(`${c.green("updated")}   .lecodesignore  (+ ${dir}/)`);
-};
-var SDK_VARIANTS = ["core", "2d", "3d", "full"];
-var detectEngines = (bundleJs) => {
-  const lines = [];
-  for (const line of bundleJs.split(`
-`)) {
-    if (!line.startsWith("//"))
-      break;
-    lines.push(line);
-  }
-  const header = lines.join(`
-`);
-  return { gl: !/^\/\/ gl: disable$/m.test(header), g2: /^\/\/ 2d: enable$/m.test(header) };
-};
-var resolveVariant = (requested, bundleJs, configKey = "ios.variant") => {
-  const uses = detectEngines(bundleJs);
-  const detected = uses.gl && uses.g2 ? "full" : uses.gl ? "3d" : uses.g2 ? "2d" : "core";
-  if (requested === "auto")
-    return { variant: detected, detected };
-  const variant = requested;
-  const missing = [
-    uses.gl && variant !== "3d" && variant !== "full" ? "3D" : null,
-    uses.g2 && variant !== "2d" && variant !== "full" ? "2D" : null
-  ].filter(Boolean);
-  if (missing.length > 0) {
-    warn(`project uses the ${missing.join(" + ")} engine but ${configKey} forces "${variant}" — those scenes won't run on device; remove ${configKey} to auto-select "${detected}".`);
-  }
-  return { variant, detected };
-};
-var VERSION_RE = /^\d+\.\d+\.\d+$/;
-var cmpVersion = (a, b) => {
-  const pa = a.split(".").map(Number);
-  const pb = b.split(".").map(Number);
-  for (let i = 0;i < 3; i++) {
-    if ((pa[i] ?? 0) !== (pb[i] ?? 0))
-      return (pa[i] ?? 0) - (pb[i] ?? 0);
-  }
-  return 0;
-};
-var fetchLatestSdkVersion = async (repo) => {
-  const url = `https://api.github.com/repos/${repo}/releases/latest`;
-  const res = await fetch(url, { headers: { accept: "application/vnd.github+json", "user-agent": "lecodes-cli" } });
-  if (!res.ok)
-    throw new CliError(`Could not read the latest ${repo} release (HTTP ${res.status}) — ${url}`);
-  const tag = (await res.json()).tag_name?.replace(/^v/, "") ?? "";
-  if (!VERSION_RE.test(tag))
-    throw new CliError(`${repo} latest release has no x.y.z tag (got "${tag}")`);
-  return tag;
-};
-var resolveSdkVersion = async (pin, fallback, opts) => {
-  if (pin !== "latest") {
-    if (!VERSION_RE.test(pin)) {
-      throw new CliError(`app.json ${opts.configKey} must be "latest" or an exact x.y.z release (got "${pin}").`);
-    }
-    if (cmpVersion(pin, opts.minVersion) < 0) {
-      throw new CliError(`app.json ${opts.configKey} ${pin} is older than the ${opts.minVersion} these generated shells need.`);
-    }
-    return pin;
-  }
-  try {
-    return await fetchLatestSdkVersion(opts.repo);
-  } catch (e) {
-    const kept = fallback ?? opts.minVersion;
-    warn(`Could not resolve the latest SDK (${e.message}) — staying on ${kept}.`);
-    return kept;
-  }
-};
-var ensureRepo = (repo, wantTag, lock) => {
-  const override = process.env.LECODES_PLUGINS_DIR;
-  if (override) {
-    note(`Using local plugin checkout ${override} (LECODES_PLUGINS_DIR)`);
-    return { dir: resolve2(override), tag: "local", commit: "local" };
-  }
-  const cache = join12(homedir3(), ".lecodes", "plugins", repo.replace("/", "__"));
-  const url = `https://github.com/${repo}.git`;
-  if (!existsSync10(join12(cache, ".git"))) {
-    mkdirSync6(dirname8(cache), { recursive: true });
-    note(`Cloning ${url}…`);
-    git(dirname8(cache), "clone", "--quiet", url, cache);
-  }
-  let tag = lock?.tag ?? wantTag;
-  let commit = lock?.commit;
-  if (commit) {
-    try {
-      git(cache, "cat-file", "-e", `${commit}^{commit}`);
-    } catch {
-      git(cache, "fetch", "--quiet", "--tags", "origin");
-    }
-  } else {
-    git(cache, "fetch", "--quiet", "--tags", "origin");
-    if (!tag) {
-      tag = git(cache, "tag", "--list", "v*", "--sort=-version:refname").split(`
-`)[0] ?? "";
-      if (!tag)
-        throw new CliError(`${repo} has no v* version tags to install from`);
-    }
-    commit = git(cache, "rev-list", "-n", "1", tag);
-  }
-  git(cache, "checkout", "--quiet", "--detach", commit);
-  return { dir: cache, tag: tag ?? "unknown", commit };
-};
-var resolvePlugin = (id, spec, lock, platform) => {
-  let repo;
-  let subdir;
-  let wantTag = null;
-  if (spec.startsWith("github:")) {
-    const [repoPart, tagPart] = spec.slice("github:".length).split("@");
-    repo = repoPart;
-    wantTag = tagPart ?? null;
-    subdir = "";
-  } else {
-    repo = FIRST_PARTY_PLUGINS[id];
-    if (!repo) {
-      throw new CliError(`Unknown plugin "${id}" — known: ${Object.keys(FIRST_PARTY_PLUGINS).join(", ")}, or use a github:owner/repo spec.`);
-    }
-    subdir = `plugins/${id}`;
-  }
-  const checkout = ensureRepo(repo, wantTag, lock?.repo === repo ? lock : undefined);
-  const dir = subdir ? join12(checkout.dir, subdir) : checkout.dir;
-  const manifest = readJson(join12(dir, "lecodes-plugin.json"));
-  if (!manifest)
-    throw new CliError(`Plugin "${id}": no lecodes-plugin.json in ${dir}`);
-  if (manifest.id !== id)
-    throw new CliError(`Plugin "${id}": manifest declares id "${manifest.id}"`);
-  if (!manifest[platform]) {
-    throw new CliError(`Plugin "${id}" does not support ${platform === "ios" ? "iOS" : "Android"} (manifest "${platform}" is null)`);
-  }
-  if (spec.startsWith("github:")) {
-    const names = [...manifest.provides?.views ?? [], ...manifest.provides?.services ?? []];
-    for (const name of names) {
-      if (!name.includes("."))
-        warn(`Plugin "${id}" provides bare channel name "${name}" — third-party names should be vendor-prefixed (e.g. "acme.${name}").`);
-    }
-  }
-  return {
-    id,
-    dir,
-    manifest,
-    lock: { repo, tag: checkout.tag, commit: checkout.commit, version: manifest.version ?? "unknown" }
-  };
+                `)},
+            ],
+            path: "Sources/LeCodesRuntime"
+        ),${pluginTargets}
+    ]
+)
+`;
 };
-var latestPluginTag = (repo) => {
-  try {
-    return ensureRepo(repo, null, undefined).tag;
-  } catch {
-    return null;
-  }
+var runtimeSwiftTemplate = (plugins, projectUuid) => {
+  const imports = plugins.map((p) => `import ${p.module}
+`).join("");
+  const identity = !projectUuid ? "" : `    // World identity: this shell IS the project — the engine attributes the boot world so
+    // identity-gated services (push registration) see the app's uuid from its first
+    // synchronous statement. Baked from .lecodes/manifest.json by \`lecodes app sync\`.
+    engine.bootProjectUuid = "${projectUuid}"
+`;
+  const calls = plugins.map((p) => `    ${p.register}.register(in: engine)
+`).join("");
+  const body = identity + calls;
+  return `//
+//  LeCodesRuntime.swift
+//  GENERATED by lecodes — regenerated by \`lecodes app sync\`; do not edit.
+//
+//  Re-exports the SDK (so app code needs only \`import LeCodesRuntime\`) and registers
+//  every plugin installed in app.json.
+//
+
+@_exported import LeCodesSDK
+${imports}
+public func registerBundledPlugins(in engine: LeCodesEngine) {
+${body === "" ? `
+` : body}}
+`;
 };
+var IOS_README = `# ios/ — native Xcode shell
+
+Generated by \`lecodes app init ios\` for the LeCodes project one folder up. The app runs the
+compiled bundle in \`App/Resources/app.js\` — fully offline, nothing fetched at launch. This
+folder is ignored by the platform (\`ios/\` in \`.lecodesignore\`) and is never pushed to LeCodes.
+
+## Daily workflow
+
+Edit the app's code at the project root (\`main.ts\` …), then:
+
+\`\`\`
+lecodes app sync     # recompile app.js + assets into the shell, vendor plugins
+lecodes app open     # open App.xcodeproj in Xcode — build & run from there
+\`\`\`
+
+\`lecodes app doctor\` preflights builds; \`lecodes app build ios\` archives and exports an
+.ipa; \`lecodes app upload ios\` sends the archive to App Store Connect.
+
+## SDK version
+
+\`../app.json\` \`ios.sdk\` is the exact \`lecodes-ios-sdk\` release this shell links —
+\`lecodes app init\` pinned the newest one at the time, so builds stay reproducible.
+
+\`\`\`
+lecodes app update           # → newest SDK release + newest plugin tags, then sync
+lecodes app update --check   # what's available, writes nothing
+lecodes app update --sdk 1.3.0
+\`\`\`
+
+Set \`"sdk": "latest"\` instead of a version to re-resolve on every sync (needs network;
+offline it keeps whatever the shell already links). The pin is exact rather than a range
+because the CLI also downloads that release's filament resources bundle into
+\`App/Resources/\` — the two halves of one SDK must not drift apart.
+
+## Who owns what
+
+Yours — \`lecodes app sync\` never touches these:
+
+- \`App/*.swift\` (AppDelegate, SceneDelegate, ViewController) — customize freely, add files.
+  App-local native code goes here too: add a Swift file that calls
+  \`engine.registerCallback\` / \`registerService\`, and invoke it from ViewController.
+- \`App/Assets.xcassets/\` — the app icon. Easy path: set \`app.json\` \`"icon"\` to a square
+  ≥1024px image and every sync renders AppIcon.png from it (flattened over \`"iconBackground"\`,
+  default white — App Store icons must be opaque). Or leave the key unset and drop a
+  1024×1024 PNG into AppIcon.appiconset/ yourself — sync never touches it then.
+- \`App/Base.lproj/LaunchScreen.storyboard\`
+
+CLI-owned — regenerated on every sync, hand edits are overwritten:
+
+- \`App/Resources/\` — the compiled app.js + every asset it references (fonts included), so
+  the app runs fully offline. Globs in app.json \`"resources": {"remote": [...]}\` opt heavy
+  assets (videos, big models) back into streaming from the server instead.
+- \`App/Info.plist\` — template + the installed plugins' usage keys
+- \`App/App.entitlements\` — the capabilities the installed plugins declare (e.g. push)
+- \`LeCodesRuntime/\` — local Swift package: the LeCodesSDK dependency, vendored plugin
+  sources (Sources/<Module>/), and the registerBundledPlugins entry point
+- the version values inside \`App.xcodeproj/project.pbxproj\` (from app.json)
+- this README
+
+## SDK variant
+
+Sync links the smallest SDK product that covers what the compiled bundle actually uses:
+\`core\` (UI only), \`2d\` (+ 2D engine with physics), \`3d\` (+ 3D/AR engine with physics,
+~17 MB heavier), or \`full\` (everything). Adding your first 3D scene or 2D game to the
+project switches it automatically on the next sync; set \`ios.variant\` in \`../app.json\`
+to pin one instead.
+
+## Over-the-air updates
+
+With \`"update": true\` in \`../app.json\` (server-backed projects; or
+\`"update": {"url": "https://…/app.js"}\` for any static hosting), the app checks that URL
+at launch — natively, before any JS runs, so a broken bundle can never block its own fix.
+Unchanged code costs a ~0-byte 304; new code downloads in the background and runs on the
+NEXT launch. Offline it's a silent no-op — the app always launches from a local bundle.
+An App Store update always beats a cached OTA bundle. JS only: adding/removing native
+plugins still needs a store release.
+
+Shipping an update is just \`lecodes push --publish\` — no rebuild, no store review:
+running apps download the new code on their next launch and run it on the launch after.
+
+Shells generated before OTA support have a \`ViewController.swift\` that reads app.js from
+\`Bundle.main\` directly, so downloaded updates would never run — and since \`App/*.swift\`
+is yours, sync won't rewrite it (\`lecodes app doctor\` flags this). Replace the
+\`Bundle.main\` load with:
+
+\`\`\`swift
+LeCodesUpdater.checkForUpdate()
+guard let code = LeCodesUpdater.activeBundle() else {
+    print("LeCodes: bundled app.js is missing — run \`lecodes app sync\`")
+    return
+}
+engine.run(code)
+\`\`\`
+
+## Config
+
+Identity lives in \`../app.json\` (name, version, plugins, ios.bundleId / teamId / variant /
+buildNumber) — edit it there, then re-run \`lecodes app sync\`. Plugins are managed with
+\`lecodes app plugin add <id | github:owner/repo[@tag]>\` and pinned in \`../plugins.lock.json\`.
+`;
 
 // src/commands/appAndroid.ts
 init_manifest();
@@ -218692,6 +218700,106 @@ import { spawn as spawn2, spawnSync as spawnSync3 } from "node:child_process";
 import { copyFileSync, existsSync as existsSync14, mkdirSync as mkdirSync9, mkdtempSync, readdirSync as readdirSync5, readFileSync as readFileSync14, renameSync as renameSync2, rmSync as rmSync2, statSync as statSync3, writeFileSync as writeFileSync11 } from "node:fs";
 import { homedir as homedir5, tmpdir } from "node:os";
 import { join as join15, resolve as resolve4 } from "node:path";
+
+// ../viewer-lite/src/sourcemapError.ts
+var B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+var B64_INDEX = {};
+for (let i2 = 0;i2 < B64.length; i2++)
+  B64_INDEX[B64[i2]] = i2;
+var decodeVlq = (segment) => {
+  const out = [];
+  let shift = 0, value = 0;
+  for (const ch of segment) {
+    const digit = B64_INDEX[ch];
+    if (digit === undefined)
+      break;
+    const more = digit & 32;
+    value += (digit & 31) << shift;
+    if (more) {
+      shift += 5;
+    } else {
+      const negative = value & 1;
+      value >>= 1;
+      out.push(negative ? -value : value);
+      value = 0;
+      shift = 0;
+    }
+  }
+  return out;
+};
+
+class SourceMap {
+  sources;
+  lines;
+  constructor(raw) {
+    this.sources = raw.sources;
+    this.lines = [];
+    let srcIdx = 0, srcLine = 0, srcCol = 0;
+    for (const lineStr of raw.mappings.split(";")) {
+      const segs = [];
+      let genCol = 0;
+      if (lineStr) {
+        for (const segStr of lineStr.split(",")) {
+          const v = decodeVlq(segStr);
+          if (v.length === 0)
+            continue;
+          genCol += v[0];
+          if (v.length >= 4) {
+            srcIdx += v[1];
+            srcLine += v[2];
+            srcCol += v[3];
+            segs.push([genCol, srcIdx, srcLine, srcCol]);
+          }
+        }
+      }
+      this.lines.push(segs);
+    }
+  }
+  originalPositionFor(line, column) {
+    const segs = this.lines[line - 1];
+    if (!segs || segs.length === 0)
+      return null;
+    let best = null;
+    for (const seg of segs) {
+      if (seg[0] <= column)
+        best = seg;
+      else
+        break;
+    }
+    best ??= segs[0];
+    const source = this.sources[best[1]];
+    if (source === undefined)
+      return null;
+    return { source, line: best[2] + 1, column: best[3] };
+  }
+}
+var extractInlineSourceMap = (code) => {
+  const m = code.match(/\/\/# lecodesMap=data:application\/json;(?:charset=[^;]+;)?base64,([A-Za-z0-9+/=]+)\s*$/);
+  if (!m)
+    return null;
+  try {
+    const json = typeof atob === "function" ? atob(m[1]) : Buffer.from(m[1], "base64").toString("utf8");
+    return new SourceMap(JSON.parse(json));
+  } catch {
+    return null;
+  }
+};
+var mapNamedFileStack = (text, map, filename) => {
+  const escaped = filename.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return text.replace(new RegExp(`\\b${escaped}:(\\d+):(\\d+)`, "g"), (whole, l2, c4) => {
+    const orig = map.originalPositionFor(parseInt(l2, 10), Math.max(0, parseInt(c4, 10) - 1));
+    return orig ? `${orig.source.replace(/^(\.\/|\/)/, "")}:${orig.line}:${orig.column}` : whole;
+  });
+};
+
+// src/compile/nativeStack.ts
+var BUNDLE_FILENAME = "module.js";
+var makeStackDemangler = (bundleJs) => {
+  const map = extractInlineSourceMap(bundleJs);
+  return map ? (chunk) => mapNamedFileStack(chunk, map, BUNDLE_FILENAME) : null;
+};
+
+// src/desktopRenderer.ts
 var MANIFEST_URL = "https://storage.yandexcloud.net/le-codes/releases/versions.json";
 var DESKTOP_RENDERER_VERSION = "1.1.0";
 var semverNewer = (a2, b) => {
@@ -218864,13 +218972,34 @@ var stageBundle = (js, resources) => {
   }
   return runDir;
 };
+var pipeThroughDemangler = (src, dst, map) => {
+  let rest = "";
+  src.on("data", (d) => {
+    rest += String(d);
+    const nl = rest.lastIndexOf(`
+`);
+    if (nl < 0)
+      return;
+    dst.write(map(rest.slice(0, nl + 1)));
+    rest = rest.slice(nl + 1);
+  });
+  src.on("end", () => {
+    if (rest)
+      dst.write(map(rest));
+  });
+};
 var runDesktopApp = async (js, resources, opts = {}) => {
   const exe = await resolveDesktopExe();
   const runDir = stageBundle(js, resources);
   try {
     const env = { ...process.env, ...windowEnv(opts) };
+    const demangle = makeStackDemangler(js);
     await new Promise((done, fail) => {
-      const child = spawn2(exe, [join15(runDir, "app.js")], { cwd: runDir, env, stdio: ["ignore", "inherit", "inherit"] });
+      const child = demangle ? spawn2(exe, [join15(runDir, "app.js")], { cwd: runDir, env, stdio: ["ignore", "pipe", "pipe"] }) : spawn2(exe, [join15(runDir, "app.js")], { cwd: runDir, env, stdio: ["ignore", "inherit", "inherit"] });
+      if (demangle) {
+        pipeThroughDemangler(child.stdout, process.stdout, demangle);
+        pipeThroughDemangler(child.stderr, process.stderr, demangle);
+      }
       child.on("error", (e2) => fail(new CliError(`Can't run the desktop host: ${e2.message}`)));
       child.on("exit", (code) => {
         if (code === 0 || code === null)
@@ -218898,26 +219027,33 @@ var runDesktopRender = async (js, resources, opts) => {
   try {
     const appJs = join15(runDir, "app.js");
     const outAbs = resolve4(opts.outPng);
-    await new Promise((done, fail) => {
-      const child = spawn2(exe, [appJs], {
-        cwd: runDir,
-        env: {
-          ...process.env,
-          CREATOR_DUMP_PNG: outAbs,
-          CREATOR_MAX_FRAMES: String(opts.frames),
-          CREATOR_WINDOW_SIZE: `${opts.width}x${opts.height}`,
-          CREATOR_HIDDEN: "1"
-        },
-        stdio: ["ignore", "pipe", "pipe"]
-      });
-      const tail = [];
+    const env = {
+      ...process.env,
+      CREATOR_DUMP_PNG: outAbs,
+      CREATOR_MAX_FRAMES: String(opts.frames),
+      CREATOR_WINDOW_SIZE: `${opts.width}x${opts.height}`,
+      CREATOR_HIDDEN: "1"
+    };
+    if (opts.script !== undefined) {
+      const scriptPath = join15(runDir, "script.txt");
+      writeFileSync11(scriptPath, opts.script);
+      env.CREATOR_SCRIPT = scriptPath;
+    }
+    if (opts.fixedDtMs)
+      env.CREATOR_FIXED_DT = String(opts.fixedDtMs);
+    if (opts.camera)
+      env.CREATOR_CAMERA = opts.camera;
+    if (opts.view)
+      env.CREATOR_VIEW = opts.view;
+    const demangle = makeStackDemangler(js) ?? ((text) => text);
+    return await new Promise((done, fail) => {
+      const child = spawn2(exe, [appJs], { cwd: runDir, env, stdio: ["ignore", "pipe", "pipe"] });
+      const chunks = [];
       const sink = (d) => {
         const text = String(d);
-        tail.push(text);
-        while (tail.length > 80)
-          tail.shift();
+        chunks.push(text);
         if (opts.logs)
-          process.stderr.write(text);
+          process.stderr.write(demangle(text));
       };
       child.stdout.on("data", sink);
       child.stderr.on("data", sink);
@@ -218931,10 +219067,12 @@ var runDesktopRender = async (js, resources, opts) => {
       });
       child.on("exit", (code) => {
         clearTimeout(killer);
+        const output = demangle(chunks.join(""));
         if (code === 0 && existsSync14(outAbs))
-          return done();
+          return done({ output, exitCode: code });
+        const tail = demangle(chunks.slice(-80).join("")).trimEnd();
         const detail = tail.length > 0 ? `
-${tail.join("").trimEnd()}` : "";
+${tail}` : "";
         fail(new CliError(code === 0 ? `The renderer exited cleanly but produced no PNG — did the app open a screen?${detail}` : `The renderer exited with code ${code}.${detail}`));
       });
     });
@@ -219980,12 +220118,22 @@ 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 card.png --clip card   # ONE component/region: a node name or x,y,w,h
 lecodes render --desktop --png shot.png  # NATIVE render: real Filament 3D + UI + 2D composited —
                                   # use this to SEE 3D scenes / procedural geometry (headless
                                   # renders record 3D as JSON only). Windows/Linux; downloads
                                   # the renderer on first use. --frames <n> for slow loads.
 lecodes render --script <file>    # drive the app through a scenario (format below)
+lecodes render --desktop --view iso --png iso.png   # 3D: inspection camera fitted to the WHOLE
+                                  # scene (iso|top|front|side|back [--fov N]) — or --camera x,y,z
+                                  # --look-at x,y,z; the app's camera is untouched. In scripts:
+                                  # { "view": "iso", "screenshot": "iso.png" } then { "view": "off" }
+lecodes render --desktop --script <file>  # the same scenario on the NATIVE host (3D/Jolt, real
+                                  # GPU): coordinates only ({ x, y }), expect.log checked,
+                                  # text/node/screen expects skipped; deterministic 16 ms frames
 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)
 \`\`\`
 
 Iterate with \`--script\` scenarios and keep the useful ones as \`tests/<name>.flow.json\` — they
@@ -219994,19 +220142,32 @@ are the regression suite. A failing step dumps the failing frame (JSON + PNG) un
 
 ## Scenario format (tests/*.flow.json and --script files)
 
-One action per step (\`tap\`, \`type\`+\`text\`, \`fill\`, \`scroll\` [+\`by\`], \`wait\`), then an
+One action per step (\`tap\`, \`type\`+\`text\`, \`fill\`, \`scroll\` [+\`by\`], \`wait\`, and for
+games: \`frames\` (advance N fixed 1/60 steps, no sleeping), \`drag\`+\`to\` [+\`ms\`], \`hold\`+\`ms\`,
+\`key\`+\`ms\` / \`keyDown\` / \`keyUp\` (KeyboardEvent.code: "ArrowRight", "KeyW", "Space")), then an
 optional \`expect\` (\`screen\`, \`node\`/\`notNode\`, \`text\`/\`notText\`,
-\`value: { target, equals }\`), then outputs (\`screenshot\`, \`json\`). Targets resolve by
-\`name\` → exact visible text → substring → input placeholder. Envelope keys: \`name\`,
+\`value: { target, equals }\`, \`log\` — a \`console.log\` line contains it), then outputs
+(\`screenshot\` [+\`clip\`: a node name or \`{ x, y, width, height }\`], \`json\`). Targets resolve by
+\`name\` → exact visible text → substring → input placeholder; a tap/drag on empty space reaches
+the 2D scene (sprite \`click\`/\`touchstart\`, \`ev.track()\`). Envelope keys: \`name\`,
 \`width\`/\`height\`, \`settle\`, \`fixtures\`, \`steps\`.
 
 \`\`\`json
 { "steps": [
   { "expect": { "screen": "home", "text": "Taps: 0" } },
-  { "tap": "tap", "expect": { "text": "Taps: 1" }, "screenshot": "after.png" }
+  { "tap": "tap", "expect": { "text": "Taps: 1" }, "screenshot": "after.png" },
+  { "key": "ArrowRight", "ms": 500, "expect": { "log": "hero x=" } },
+  { "frames": 60, "screenshot": "hud.png", "clip": "hud" }
 ] }
 \`\`\`
 
+Game time is deterministic headless: \`setLoop\`, 2D physics/animation and aspect \`update(dt)\`
+advance in fixed 1/60 steps driven by \`wait\`/\`frames\`/\`drag\`/\`key\` — never by a wall clock —
+so a flow that passes once passes every time. \`Input.key(code)\` reads the keys a flow holds.
+Headless draws UI + the 2D scene (sprites, tilemaps, Box2D); 3D is captured as JSON and Jolt does
+not simulate — use \`--desktop\` for 3D pixels. \`console.log\` + \`expect.log\` is the assertion
+channel for game state that has no UI.
+
 ## Make the app testable
 
 - Give interactive elements a \`name\`: \`UIButton(...).style({ name: "login" })\`.
@@ -220116,7 +220277,7 @@ var run = async (args) => {
   }
   const appCfg = readAppConfigAt(root);
   const win = appCfg?.desktop?.window;
-  const { js, resources } = await buildBundle(args);
+  const { js, resources } = await buildBundle(args, undefined, { localAssets: true });
   note("Launching LeCodes Desktop… (close the window to return)");
   await runDesktopApp(js, resources, {
     width: Number(flagStr(args, "width")) || win?.width,
@@ -220207,23 +220368,29 @@ var DEV_PRELUDE_JS = `
     } catch (e) {}
   }
 
+  // An Error carries its stack (JSON.stringify would send a useless "{}"); the dev server maps the
+  // frames back to project positions before printing.
+  function describe(a) {
+    if (typeof a === "string") return a
+    if (a && typeof a.stack === "string" && typeof a.message === "string") {
+      return a.stack ? String(a) + "\\n" + a.stack : String(a)
+    }
+    try { return JSON.stringify(a) } catch (e) { return String(a) }
+  }
+
   // Mirror console output to the dev terminal ('silent' guards recursion through wrapped calls).
   var silent = false
   ;["log", "warn", "error"].forEach(function (level) {
     var orig = console[level]
     console[level] = function () {
       var parts = []
-      for (var i = 0; i < arguments.length; i++) {
-        var a = arguments[i]
-        if (typeof a === "string") { parts.push(a); continue }
-        try { parts.push(JSON.stringify(a)) } catch (e) { parts.push(String(a)) }
-      }
+      for (var i = 0; i < arguments.length; i++) parts.push(describe(arguments[i]))
       try { orig.apply(console, arguments) } catch (e) {}
       if (!silent) { silent = true; try { post({ type: "log", level: level, text: parts.join(" ") }) } finally { silent = false } }
     }
   })
 
-  function report(err) { post({ type: "error", text: String(err) }) }
+  function report(err) { post({ type: "error", text: describe(err) }) }
 
   function load(v) {
     if (busy) { queued = v; return }
@@ -220501,6 +220668,14 @@ var startDevServer = async (options) => {
     for (const client of clients)
       client.send(text);
   };
+  let demangleFor = null;
+  const demangle = (text) => {
+    if (bundleJs === null)
+      return text;
+    if (demangleFor?.js !== bundleJs)
+      demangleFor = { js: bundleJs, map: makeStackDemangler(bundleJs) };
+    return demangleFor.map ? demangleFor.map(text) : text;
+  };
   const printDeviceMessage = (raw) => {
     let m = {};
     try {
@@ -220509,9 +220684,9 @@ var startDevServer = async (options) => {
       return;
     }
     if (m.type === "log")
-      log2(`[device:${m.level ?? "log"}] ${m.text ?? ""}`);
+      log2(`[device:${m.level ?? "log"}] ${demangle(m.text ?? "")}`);
     else if (m.type === "error")
-      log2(`[device:error] ${m.text ?? ""}`);
+      log2(`[device:error] ${demangle(m.text ?? "")}`);
   };
   const transportOf = (url) => url.searchParams.get("t") === "poll" ? "poll" : "ws";
   const handle = async (req, res) => {
@@ -221403,7 +221578,7 @@ var login = async (args) => {
 
 // src/commands/render.ts
 import { mkdirSync as mkdirSync18, readFileSync as readFileSync22, writeFileSync as writeFileSync19 } from "node:fs";
-import { dirname as dirname15, resolve as resolve11 } from "node:path";
+import { dirname as dirname15, resolve as resolve12 } from "node:path";
 
 // src/compile/headlessBundle.ts
 init_api();
@@ -221484,6 +221659,240 @@ var compileHeadlessBundle = async (args) => {
 
 // src/commands/render.ts
 init_manifest();
+
+// src/desktopScript.ts
+init_util();
+import { resolve as resolve11 } 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", "camera", "view"];
+var SEMANTIC_EXPECT = ["text", "notText", "node", "notNode", "screen", "value"];
+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})`;
+var translateScenario = (rawSteps, opts) => {
+  if (!Array.isArray(rawSteps))
+    throw new CliError(`"steps" must be an array of step objects.`);
+  const lines = [];
+  const steps = [];
+  let budgetMs = 0;
+  const emit = (line) => {
+    lines.push(line);
+    return lines.length;
+  };
+  emit(`# generated by lecodes render --desktop --script`);
+  emit(`frames ${Math.max(0, opts.headroomFrames)}`);
+  const coord = (at, key, v) => {
+    if (isPoint(v))
+      return v;
+    if (typeof v === "string") {
+      throw new CliError(`${at}: "${key}": "${v}" — the native host can't resolve names; give --desktop scripts { "x", "y" } coordinates (logical px), or run the scenario headless (without --desktop).`);
+    }
+    throw new CliError(`${at}: "${key}" must be { "x", "y" }.`);
+  };
+  const num = (at, key, v, def) => {
+    if (v === undefined && def !== undefined)
+      return def;
+    if (typeof v !== "number")
+      throw new CliError(`${at}: "${key}" must be a number.`);
+    return v;
+  };
+  let inspecting = false;
+  rawSteps.forEach((step, i2) => {
+    const at = `steps[${i2}]`;
+    if (typeof step !== "object" || step === null || Array.isArray(step))
+      throw new CliError(`${at}: must be an object.`);
+    const s2 = step;
+    const actions = ACTIONS.filter((k) => s2[k] !== undefined);
+    if (actions.length > 1)
+      throw new CliError(`${at}: one action per step (found ${actions.join(" + ")}).`);
+    const plan = { index: i2, desc: "", lines: [], skippedExpect: [], skippedOutputs: [] };
+    const parts = [];
+    const action = actions[0];
+    if (action === "type" || action === "fill" || action === "scroll") {
+      throw new CliError(`${at}: "${action}" isn't available with --desktop (the native host has no semantic tree / soft keyboard) — run this scenario headless, or drive the gesture with "drag" coordinates.`);
+    }
+    if ((action === "tap" || action === "drag" || action === "hold") && inspecting) {
+      throw new CliError(`${at}: "${action}" while an inspection camera is active — the app's hit-testing uses its own camera, not the one in the shot. Add { "view": "off" } (or { "camera": "off" }) first.`);
+    }
+    if (action === "view") {
+      const v = s2.view;
+      const fov = s2.fov !== undefined ? num(at, "fov", s2.fov) : undefined;
+      if (v === "off") {
+        plan.lines.push(emit("view off"));
+        inspecting = false;
+        parts.push("view off");
+      } else if (typeof v === "string" && VIEW_NAMES.includes(v)) {
+        plan.lines.push(emit(`view ${v}${fov !== undefined ? ` ${fov}` : ""}`));
+        inspecting = true;
+        parts.push(`view ${v}${fov !== undefined ? ` (fov ${fov})` : ""}`);
+      } else
+        throw new CliError(`${at}: "view" wants one of ${VIEW_NAMES.join(", ")} or "off".`);
+      budgetMs += 2 * FRAME_MS;
+    } else if (action === "camera") {
+      const cam = s2.camera;
+      if (cam === "off") {
+        plan.lines.push(emit("camera off"));
+        inspecting = false;
+        parts.push("camera off");
+      } else if (typeof cam === "object" && cam !== null && isVec3(cam.at) && isVec3(cam.lookAt)) {
+        const { at: eye, lookAt, fov } = cam;
+        const fovN = fov !== undefined ? num(at, "camera.fov", fov) : undefined;
+        plan.lines.push(emit(`camera ${eye.join(" ")} ${lookAt.join(" ")}${fovN !== undefined ? ` ${fovN}` : ""}`));
+        inspecting = true;
+        parts.push(`camera at (${eye.join(",")}) → (${lookAt.join(",")})`);
+      } else
+        throw new CliError(`${at}: "camera" wants { "at": [x,y,z], "lookAt": [x,y,z], "fov"? } or "off".`);
+      budgetMs += 2 * FRAME_MS;
+    }
+    if (s2.fov !== undefined && action !== "view")
+      throw new CliError(`${at}: "fov" only goes with "view" (inside "camera" use camera.fov).`);
+    if (action === "tap") {
+      const p2 = coord(at, "tap", s2.tap);
+      plan.lines.push(emit(`tap ${p2.x} ${p2.y}`));
+      budgetMs += 4 * FRAME_MS;
+      parts.push(`tap ${pt(p2)}`);
+    } else if (action === "drag") {
+      const a2 = coord(at, "drag", s2.drag), b = coord(at, "to", s2.to);
+      const ms = num(at, "ms", s2.ms, 300);
+      plan.lines.push(emit(`drag ${a2.x} ${a2.y} ${b.x} ${b.y} ${Math.round(ms)}`));
+      budgetMs += ms + 4 * FRAME_MS;
+      parts.push(`drag ${pt(a2)} → ${pt(b)} over ${ms}ms`);
+    } else if (action === "hold") {
+      const p2 = coord(at, "hold", s2.hold);
+      const ms = num(at, "ms", s2.ms);
+      plan.lines.push(emit(`hold ${p2.x} ${p2.y} ${Math.round(ms)}`));
+      budgetMs += ms + 4 * FRAME_MS;
+      parts.push(`hold ${pt(p2)} ${ms}ms`);
+    } else if (action === "key") {
+      if (typeof s2.key !== "string")
+        throw new CliError(`${at}: "key" must be a KeyboardEvent.code string.`);
+      const ms = num(at, "ms", s2.ms);
+      plan.lines.push(emit(`key ${s2.key} ${Math.round(ms)}`));
+      budgetMs += ms + 2 * FRAME_MS;
+      parts.push(`key ${s2.key} ${ms}ms`);
+    } else if (action === "keyDown" || action === "keyUp") {
+      const code = s2[action];
+      if (typeof code !== "string")
+        throw new CliError(`${at}: "${action}" must be a code string.`);
+      plan.lines.push(emit(`${action.toLowerCase()} ${code}`));
+      budgetMs += 2 * FRAME_MS;
+      parts.push(`${action} ${code}`);
+    } else if (action === "wait") {
+      const ms = num(at, "wait", s2.wait);
+      plan.lines.push(emit(`wait ${Math.round(ms)}`));
+      budgetMs += ms + FRAME_MS;
+      parts.push(`wait ${ms}ms`);
+    } else if (action === "frames") {
+      const n2 = num(at, "frames", s2.frames);
+      plan.lines.push(emit(`frames ${Math.round(n2)}`));
+      budgetMs += n2 * FRAME_MS + FRAME_MS;
+      parts.push(`advance ${n2} frames`);
+    }
+    if (s2.expect !== undefined) {
+      if (typeof s2.expect !== "object" || s2.expect === null)
+        throw new CliError(`${at}: "expect" must be an object.`);
+      const e2 = s2.expect;
+      const bits = [];
+      for (const k of Object.keys(e2)) {
+        if (k === "log") {
+          if (typeof e2.log !== "string")
+            throw new CliError(`${at}: expect.log must be a string.`);
+          plan.expectLog = e2.log;
+          bits.push(`log~"${e2.log}"`);
+        } else if (SEMANTIC_EXPECT.includes(k)) {
+          plan.skippedExpect.push(k);
+        } else {
+          throw new CliError(`${at}: unknown expect key "${k}".`);
+        }
+      }
+      if (bits.length > 0)
+        parts.push(`expect ${bits.join(" · ")}`);
+    }
+    if (s2.clip !== undefined)
+      throw new CliError(`${at}: "clip" isn't available with --desktop (the native host dumps the whole window).`);
+    if (s2.screenshot !== undefined) {
+      if (typeof s2.screenshot !== "string")
+        throw new CliError(`${at}: "screenshot" must be a path.`);
+      plan.screenshot = resolve11(opts.outDir, s2.screenshot);
+      plan.lines.push(emit(`frames 2`));
+      plan.lines.push(emit(`shot ${plan.screenshot}`));
+      budgetMs += 3 * FRAME_MS;
+      parts.push(`→ ${s2.screenshot}`);
+    }
+    if (s2.json !== undefined)
+      plan.skippedOutputs.push("json");
+    if (plan.lines.length === 0) {
+      plan.lines.push(emit(`frames 1`));
+      budgetMs += FRAME_MS;
+    }
+    plan.desc = typeof s2.name === "string" ? s2.name : parts.join(", ") || "(empty step)";
+    steps.push(plan);
+  });
+  const frameCap = Math.max(0, opts.headroomFrames) + Math.ceil(budgetMs / FRAME_MS) + 600;
+  return { text: lines.join(`
+`) + `
+`, steps, frameCap };
+};
+var evaluateDesktopRun = (plan, output) => {
+  const lines = output.split(/\r?\n/);
+  const doneAt = new Map;
+  const consoleLines = [];
+  let loaded = false, ended = false;
+  for (const line of lines) {
+    const m = /^\[script\] #(\d+) (done|error) (\S+)(?:: (.*))?$/.exec(line);
+    if (m) {
+      doneAt.set(Number(m[1]), { at: consoleLines.length, error: m[2] === "error" ? `${m[3]}: ${m[4] ?? "failed"}` : undefined });
+      continue;
+    }
+    if (line.startsWith("[script] loaded")) {
+      loaded = true;
+      continue;
+    }
+    if (line === "[script] end") {
+      ended = true;
+      continue;
+    }
+    if (line.startsWith("[script]"))
+      continue;
+    consoleLines.push(line);
+  }
+  const steps = [];
+  let ok = true;
+  for (const st of plan.steps) {
+    const skipped = [
+      ...st.skippedExpect.map((k) => `expect.${k} (no semantic tree on --desktop)`),
+      ...st.skippedOutputs.map((k) => `${k} output (no semantic tree on --desktop)`)
+    ];
+    let error;
+    let cutoff = consoleLines.length;
+    for (const ln of st.lines) {
+      const d = doneAt.get(ln);
+      if (!d) {
+        error = error ?? "the host never completed this step (crashed, closed, or hit the frame cap before it)";
+        break;
+      }
+      if (d.error) {
+        error = error ?? d.error;
+        break;
+      }
+      cutoff = d.at;
+    }
+    if (!error && st.expectLog !== undefined) {
+      const seen = consoleLines.slice(0, cutoff);
+      if (!seen.some((l2) => l2.includes(st.expectLog))) {
+        const tail = seen.filter((l2) => l2.startsWith("[DEBUG]") || l2.startsWith("[INFO]") || l2.startsWith("[WARN]") || l2.startsWith("[ERROR]")).slice(-3);
+        error = `expected a console line containing "${st.expectLog}" — ${tail.length === 0 ? "the app logged nothing" : `last lines: ${tail.map((l2) => `"${l2}"`).join(", ")}`}`;
+      }
+    }
+    if (error)
+      ok = false;
+    steps.push({ desc: st.desc, ok: !error, error, skipped });
+  }
+  return { loaded, ended, ok: ok && loaded, steps };
+};
+
+// src/commands/render.ts
 init_util();
 var DEVICE_SAFE_AREA = {
   none: { insets: [0, 0, 0, 0], bars: [] },
@@ -221514,7 +221923,7 @@ var requireRenderer = async () => {
 };
 var fileScenarioIO = (dir) => ({
   write: (relPath, data) => {
-    const abs = resolve11(dir, relPath);
+    const abs = resolve12(dir, relPath);
     mkdirSync18(dirname15(abs), { recursive: true });
     writeFileSync19(abs, data);
   }
@@ -221524,7 +221933,7 @@ var resolveFixtures = (value, baseDir) => {
     return;
   let map = value;
   if (typeof value === "string") {
-    const abs = resolve11(baseDir, value);
+    const abs = resolve12(baseDir, value);
     try {
       map = JSON.parse(readFileSync22(abs, "utf8"));
     } catch (e2) {
@@ -221539,7 +221948,7 @@ var resolveFixtures = (value, baseDir) => {
 var readScenarioFile = (path2) => {
   let raw;
   try {
-    raw = JSON.parse(readFileSync22(resolve11(path2), "utf8"));
+    raw = JSON.parse(readFileSync22(resolve12(path2), "utf8"));
   } catch (e2) {
     throw new CliError(`Can't read scenario "${path2}": ${e2 instanceof Error ? e2.message : String(e2)}`);
   }
@@ -221552,6 +221961,20 @@ var readScenarioFile = (path2) => {
     throw new CliError(`Scenario "${path2}" has no "steps".`);
   return file;
 };
+var parseClip = (raw) => {
+  if (raw === undefined)
+    return;
+  const parts = raw.split(",").map((p2) => p2.trim());
+  if (parts.length === 4 && parts.every((p2) => /^-?\d+(\.\d+)?$/.test(p2))) {
+    const [x2, y2, width, height] = parts.map(Number);
+    if (width <= 0 || height <= 0)
+      throw new CliError(`--clip: width and height must be positive (got "${raw}").`);
+    return { x: x2, y: y2, width, height };
+  }
+  if (parts.length === 1 && raw.trim() !== "")
+    return raw.trim();
+  throw new CliError(`--clip: expected a node name or "x,y,width,height" (got "${raw}").`);
+};
 var renderDesktop = async (args) => {
   let root;
   try {
@@ -221560,22 +221983,101 @@ var renderDesktop = async (args) => {
     root = process.cwd();
   }
   const win = readAppConfigAt(root)?.desktop?.window;
-  const width = Number(flagStr(args, "width")) || win?.width || 390;
-  const height = Number(flagStr(args, "height")) || win?.height || 844;
+  const scriptFlag = flagStr(args, "script");
+  const scenario = scriptFlag !== undefined ? readScenarioFile(scriptFlag) : null;
+  const width = Number(flagStr(args, "width")) || scenario?.width || win?.width || 390;
+  const height = Number(flagStr(args, "height")) || scenario?.height || win?.height || 844;
   const frames = Number(flagStr(args, "frames")) || 60;
-  const timeoutMs = Number(flagStr(args, "timeout")) || 60000;
   const pngFlag = flagStr(args, "png") ?? "screenshot.png";
-  const { js, resources } = await buildBundle(args);
+  const logs = flagBool(args, "logs");
+  const fixedDtFlag = flagStr(args, "fixed-dt");
+  const fixedDtMs = fixedDtFlag !== undefined ? Number(fixedDtFlag) : scenario ? 16 : 0;
+  if (!Number.isFinite(fixedDtMs) || fixedDtMs < 0 || fixedDtMs > 1000)
+    throw new CliError(`--fixed-dt wants a number of ms (0 = wall clock, max 1000), got "${fixedDtFlag}".`);
+  const { camera, view } = resolveInspectionCamera(args);
+  if ((camera || view) && scenario)
+    throw new CliError('--camera/--view apply to a plain render; in a --script run use a { "view": "iso" } or { "camera": { "at", "lookAt" } } step before the screenshot.');
+  const { js, resources } = await buildBundle(args, undefined, { localAssets: true });
+  mkdirSync18(dirname15(resolve12(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)
+        mkdirSync18(dirname15(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, {
+      width,
+      height,
+      frames: plan.frameCap,
+      outPng: pngFlag,
+      logs,
+      timeoutMs: timeoutMs2,
+      script: plan.text,
+      fixedDtMs
+    });
+    const result = evaluateDesktopRun(plan, output);
+    if (!result.loaded) {
+      throw new CliError("This desktop host doesn't support scripted input (CREATOR_SCRIPT) — it ran the frames and ignored the steps. Update it: lecodes desktop update (or point LECODES_DESKTOP_EXE at a newer build).");
+    }
+    for (const st of result.steps) {
+      logErr(st.ok ? `${c.green("✓")} ${st.desc}` : `${c.red("✗")} ${st.desc}
+  ${c.red(st.error ?? "failed")}`);
+      for (const sk of st.skipped)
+        logErr(c.dim(`  – skipped: ${sk}`));
+    }
+    const skippedCount = result.steps.reduce((n2, s2) => n2 + s2.skipped.length, 0);
+    if (skippedCount > 0)
+      logErr(c.dim(`  ${skippedCount} semantic check${skippedCount === 1 ? "" : "s"} skipped — the native host has no UI tree; run the same scenario headless to verify them.`));
+    if (!result.ended)
+      warnErr("The host stopped before the script finished (frame cap / crash) — later steps are reported as incomplete.");
+    logErr(result.ok ? c.green(`✓ ${result.steps.length}/${result.steps.length} steps passed (native)`) : c.red(`✗ ${result.steps.filter((s2) => !s2.ok).length} of ${result.steps.length} steps failed (native)`));
+    note(`Wrote ${pngFlag} (${width}x${height}, native render, final frame)`);
+    process.exit(result.ok ? 0 : 1);
+  }
+  const timeoutMs = Number(flagStr(args, "timeout")) || 60000;
   note("Rendering (native)…");
   await runDesktopRender(js, resources, {
     width,
     height,
     frames,
     outPng: pngFlag,
-    logs: flagBool(args, "logs"),
-    timeoutMs
+    logs,
+    timeoutMs,
+    fixedDtMs,
+    camera,
+    view
   });
-  note(`Wrote ${pngFlag} (${width}x${height}, native render)`);
+  note(`Wrote ${pngFlag} (${width}x${height}, native render${view ? `, ${view.split(";")[0]} view` : camera ? ", custom camera" : ""})`);
+};
+var VIEW_NAMES2 = ["iso", "top", "front", "side", "back"];
+var parseVec3Flag = (name, raw) => {
+  const parts = raw.split(",").map((p2) => p2.trim());
+  if (parts.length !== 3 || parts.some((p2) => !/^-?\d+(\.\d+)?$/.test(p2)))
+    throw new CliError(`--${name} wants "x,y,z" (got "${raw}").`);
+  return parts.join(",");
+};
+var resolveInspectionCamera = (args) => {
+  const cam = flagStr(args, "camera"), look = flagStr(args, "look-at"), view = flagStr(args, "view"), fov = flagStr(args, "fov");
+  if (fov !== undefined && !(Number(fov) > 0 && Number(fov) < 180))
+    throw new CliError(`--fov wants degrees in (0, 180), got "${fov}".`);
+  const fovSuffix = fov !== undefined ? `;${Number(fov)}` : "";
+  if (cam !== undefined || look !== undefined) {
+    if (view !== undefined)
+      throw new CliError("Use either --camera/--look-at or --view, not both.");
+    if (cam === undefined || look === undefined)
+      throw new CliError("--camera and --look-at go together: --camera x,y,z --look-at x,y,z");
+    return { camera: `${parseVec3Flag("camera", cam)};${parseVec3Flag("look-at", look)}${fovSuffix}` };
+  }
+  if (view !== undefined) {
+    if (!VIEW_NAMES2.includes(view))
+      throw new CliError(`--view wants one of ${VIEW_NAMES2.join(", ")} (got "${view}").`);
+    return { view: `${view}${fovSuffix}` };
+  }
+  if (fov !== undefined)
+    throw new CliError("--fov goes with --camera/--look-at or --view.");
+  return {};
 };
 var render = async (args) => {
   if (flagBool(args, "desktop"))
@@ -221597,7 +222099,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 ? dirname15(resolve11(scriptFlag)) : ".");
+  const envelopeFixtures = resolveFixtures(scenario?.fixtures, scriptFlag !== undefined ? dirname15(resolve12(scriptFlag)) : ".");
   const flagFixtures = resolveFixtures(flagStr(args, "fixtures"), ".");
   const fixtures = envelopeFixtures || flagFixtures ? { ...envelopeFixtures, ...flagFixtures } : undefined;
   if (fixtures) {
@@ -221636,7 +222138,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) => resolve11(outDir, p2)).join(", ")}`));
+        logErr(c.dim(`  failing frame: ${result2.failureArtifacts.map((p2) => resolve12(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);
@@ -221647,19 +222149,21 @@ var render = async (args) => {
   const pngFlag = flagStr(args, "png") ?? (flagBool(args, "png") ? "screenshot.png" : undefined);
   if (pngFlag !== undefined) {
     note("Rendering PNG…");
-    const { png: png2, warnings: pngWarnings } = await renderer.renderToPng(js, {
+    const clip = parseClip(flagStr(args, "clip"));
+    const { png: png2, width: outW, height: outH, warnings: pngWarnings } = await renderer.renderToPng(js, {
       width,
       height,
       scale: Number(flagStr(args, "scale")) || 2,
-      ...timing
+      ...timing,
+      clip
     });
     for (const w of [...warnings, ...pngWarnings])
       warnErr(w);
     if (isNullSink(pngFlag)) {
       note(`Discarded PNG (${pngFlag})`);
     } else {
-      writeFileSync19(resolve11(pngFlag), png2);
-      note(`Wrote ${pngFlag} (${png2.length} bytes, ${width}x${height})`);
+      writeFileSync19(resolve12(pngFlag), png2);
+      note(`Wrote ${pngFlag} (${png2.length} bytes, ${outW}x${outH}${clip !== undefined ? ", clipped" : ""})`);
     }
     return done((cb) => cb());
   }
@@ -221673,7 +222177,7 @@ var render = async (args) => {
     return done((cb) => cb());
   }
   if (out) {
-    writeFileSync19(resolve11(out), result.text);
+    writeFileSync19(resolve12(out), result.text);
     note(`Wrote ${out} (${result.text.length} bytes)`);
     return done((cb) => cb());
   }
@@ -222034,7 +222538,7 @@ var pullPaths = async (root, manifest, project, paths, apiUrl, token) => {
 // src/commands/scene.ts
 init_manifest();
 import { existsSync as existsSync27, readFileSync as readFileSync25, readdirSync as readdirSync12, statSync as statSync8, writeFileSync as writeFileSync22 } from "node:fs";
-import { basename as basename14, dirname as dirname17, join as join27, resolve as resolve12 } from "node:path";
+import { basename as basename14, dirname as dirname17, join as join27, resolve as resolve13 } from "node:path";
 
 // src/compile/sceneCompile.ts
 init_localFiles();
@@ -222107,7 +222611,7 @@ var getContext2 = (args) => {
     manifest = null;
     const pathArg = args._[0];
     if (pathArg) {
-      const abs = resolve12(process.cwd(), pathArg);
+      const abs = resolve13(process.cwd(), pathArg);
       if (existsSync27(abs) && statSync8(abs).isDirectory())
         root = abs;
       else if (abs.endsWith(".scene.ts") && existsSync27(abs))
@@ -222235,8 +222739,9 @@ var status2 = async (_args) => {
 };
 
 // src/commands/test.ts
-import { existsSync as existsSync28, readFileSync as readFileSync26, readdirSync as readdirSync13 } from "node:fs";
-import { dirname as dirname18, resolve as resolve13 } from "node:path";
+import { existsSync as existsSync28, mkdirSync as mkdirSync20, readFileSync as readFileSync26, readdirSync as readdirSync13 } from "node:fs";
+import { dirname as dirname18, resolve as resolve14 } from "node:path";
+init_manifest();
 init_util();
 var deriveDesignFlows = (meta, entryScreen) => {
   const edges = meta.edges ?? [];
@@ -222321,17 +222826,39 @@ var readFlowFile = (abs, displayName) => {
   };
 };
 var test = async (args) => {
-  const { js, warnings, useLocalAssets, root } = await compileHeadlessBundle(args);
-  const renderer = await requireRenderer();
+  const desktop2 = flagBool(args, "desktop");
+  if (desktop2 && flagBool(args, "flows"))
+    throw new CliError("--flows needs the headless renderer (design flows tap by name) — drop --desktop.");
+  const native = desktop2 ? await buildBundle(args, undefined, { localAssets: true }) : null;
+  const headless = desktop2 ? null : await compileHeadlessBundle(args);
+  const warnings = headless?.warnings ?? [];
+  const useLocalAssets = headless?.useLocalAssets ?? false;
+  const js = headless?.js ?? "";
+  let root;
+  if (headless)
+    root = headless.root;
+  else {
+    try {
+      root = findProjectRoot(process.cwd());
+    } catch {
+      root = process.cwd();
+    }
+  }
+  const renderer = desktop2 ? null : await requireRenderer();
+  const nativeFrames = Number(flagStr(args, "frames")) || 60;
+  const fixedDtFlag = flagStr(args, "fixed-dt");
+  const nativeFixedDt = fixedDtFlag !== undefined ? Number(fixedDtFlag) : 16;
+  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 = resolve13(root, flagStr(args, "dir") ?? "tests");
-  const designMetaPath = resolve13(root, flagStr(args, "design-dir") ?? "design", "meta.json");
+  const testsDir = resolve14(root, flagStr(args, "dir") ?? "tests");
+  const designMetaPath = resolve14(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 = [resolve13(given), resolve13(testsDir, given), resolve13(testsDir, `${given}.flow.json`)];
+      const candidates = [resolve14(given), resolve14(testsDir, given), resolve14(testsDir, `${given}.flow.json`)];
       const abs = candidates.find((p2) => existsSync28(p2));
       if (!abs)
         throw new CliError(`No such test: "${given}" (looked in ${testsDir}).`);
@@ -222339,11 +222866,11 @@ var test = async (args) => {
     }
   } else if (existsSync28(testsDir)) {
     for (const f3 of readdirSync13(testsDir).filter((f4) => f4.endsWith(".flow.json")).sort()) {
-      cases.push(readFlowFile(resolve13(testsDir, f3), f3));
+      cases.push(readFlowFile(resolve14(testsDir, f3), f3));
     }
   }
   const fixturesFlag = flagStr(args, "fixtures");
-  const defaultPack = resolve13(testsDir, "fixtures.json");
+  const defaultPack = resolve14(testsDir, "fixtures.json");
   const flowFixtures = fixturesFlag !== undefined ? resolveFixtures(fixturesFlag, ".") : existsSync28(defaultPack) ? resolveFixtures("fixtures.json", testsDir) : undefined;
   const flowsOnly = flagBool(args, "flows");
   const wantFlows = !flagBool(args, "no-flows") && args._.length === 0;
@@ -222351,7 +222878,10 @@ var test = async (args) => {
     cases.length = 0;
   let skipped = [];
   let entryScreen = null;
-  if ((wantFlows || flowsOnly) && existsSync28(designMetaPath)) {
+  if (desktop2 && wantFlows && existsSync28(designMetaPath)) {
+    note("Design-derived flows skipped with --desktop (they tap by name; run `lecodes test` headless for them).");
+  }
+  if (!desktop2 && (wantFlows || flowsOnly) && existsSync28(designMetaPath)) {
     let meta;
     try {
       meta = JSON.parse(readFileSync26(designMetaPath, "utf8"));
@@ -222379,18 +222909,60 @@ var test = async (args) => {
       warnErr(w);
     throw new CliError(`No tests found. Write tests/*.flow.json scenarios, or draw activator edges in the design board (design/meta.json).`);
   }
-  const timeoutMs = Number(flagStr(args, "timeout")) || 20000 + cases.length * 1e4;
+  const timeoutMs = Number(flagStr(args, "timeout")) || (desktop2 ? 60000 + cases.length * 60000 : 20000 + cases.length * 1e4);
   const killer = setTimeout(() => {
     warnErr(`Test run timed out after ${timeoutMs}ms (raise --timeout or lower --settle).`);
     process.exit(1);
   }, timeoutMs);
   killer.unref?.();
   const onConsole = flagBool(args, "logs") ? (level, text) => logErr(`${c.dim(`[${level}]`)} ${text}`) : undefined;
-  const artifactsRoot = resolve13(root, flagStr(args, "artifacts") ?? resolve13(testsDir, ".artifacts"));
+  const artifactsRoot = resolve14(root, flagStr(args, "artifacts") ?? resolve14(testsDir, ".artifacts"));
   const results = [];
+  const runNativeCase = async (kase) => {
+    const caseDir = resolve14(artifactsRoot, slug3(kase.name));
+    const plan = translateScenario(kase.steps, { outDir: caseDir, headroomFrames: nativeFrames });
+    for (const st of plan.steps)
+      if (st.screenshot)
+        mkdirSync20(dirname18(st.screenshot), { recursive: true });
+    mkdirSync20(caseDir, { recursive: true });
+    const finalPng = resolve14(caseDir, "final.png");
+    const { output } = await runDesktopRender(native.js, native.resources, {
+      width: Number(flagStr(args, "width")) || kase.width || projectViewport?.width || 390,
+      height: Number(flagStr(args, "height")) || kase.height || projectViewport?.height || 844,
+      frames: plan.frameCap,
+      outPng: finalPng,
+      logs: flagBool(args, "logs"),
+      timeoutMs: 60000 + plan.steps.length * 5000,
+      script: plan.text,
+      fixedDtMs: nativeFixedDt
+    });
+    const r2 = evaluateDesktopRun(plan, output);
+    if (!r2.loaded)
+      throw new CliError("This desktop host doesn't support scripted input (CREATOR_SCRIPT). Update it: lecodes desktop update (or point LECODES_DESKTOP_EXE at a newer build).");
+    return {
+      name: kase.name,
+      kind: kase.kind,
+      ok: r2.ok,
+      steps: r2.steps.map((s2) => ({ desc: s2.desc, ok: s2.ok, error: s2.error, skipped: s2.skipped.length > 0 ? s2.skipped : undefined })),
+      error: r2.ended ? undefined : "the host stopped before the script finished (frame cap / crash)",
+      artifacts: r2.ok ? [] : [finalPng]
+    };
+  };
   for (const kase of cases) {
     const flagSettle = flagStr(args, "settle");
     let result;
+    if (desktop2) {
+      try {
+        result = await runNativeCase(kase);
+      } catch (e2) {
+        if (e2 instanceof CliError && /doesn't support scripted input/.test(e2.message))
+          throw e2;
+        result = { name: kase.name, kind: kase.kind, ok: false, steps: [], error: e2 instanceof Error ? e2.message : String(e2), artifacts: [] };
+      }
+      results.push(result);
+      reportCase(result);
+      continue;
+    }
     try {
       const steps = renderer.parseScenarioSteps(kase.steps);
       const session = await renderer.createSession(js, {
@@ -222404,14 +222976,14 @@ var test = async (args) => {
         onConsole
       });
       try {
-        const io = fileScenarioIO(resolve13(artifactsRoot, slug3(kase.name)));
+        const io = fileScenarioIO(resolve14(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) => resolve13(artifactsRoot, slug3(kase.name), p2))
+          artifacts: outcome.failureArtifacts.map((p2) => resolve14(artifactsRoot, slug3(kase.name), p2))
         };
       } finally {
         session.dispose();
@@ -222420,14 +222992,20 @@ var test = async (args) => {
       result = { name: kase.name, kind: kase.kind, ok: false, steps: [], error: e2 instanceof Error ? e2.message : String(e2), artifacts: [] };
     }
     results.push(result);
+    reportCase(result);
+  }
+  function reportCase(result) {
+    const skippedCount = result.steps.reduce((n2, s2) => n2 + (s2.skipped?.length ?? 0), 0);
     if (result.ok) {
-      out(`${c.green("✓")} ${result.name}`);
+      out(`${c.green("✓")} ${result.name}${skippedCount > 0 ? c.dim(` (${skippedCount} semantic check${skippedCount === 1 ? "" : "s"} skipped on --desktop)`) : ""}`);
     } else {
       out(`${c.red("✗")} ${result.name}`);
       if (result.error)
         out(`    ${c.red(result.error)}`);
       for (const s2 of result.steps) {
         out(s2.ok ? c.dim(`    ✓ ${s2.desc}`) : `    ${c.red(`✗ ${s2.desc} — ${s2.error}`)}`);
+        for (const sk of s2.skipped ?? [])
+          out(c.dim(`      – skipped: ${sk}`));
       }
       if (result.artifacts.length > 0)
         out(c.dim(`    failing frame: ${result.artifacts.join(", ")}`));
@@ -222473,11 +223051,11 @@ init_config();
 init_manifest();
 init_types4();
 init_util();
-import { resolve as resolve14 } from "node:path";
+import { resolve as resolve15 } from "node:path";
 var label = (bundle) => `${Object.keys(bundle).length} file(s)`;
 var types4 = async (args) => {
   const dirArg = args._[0];
-  const root = dirArg ? resolve14(dirArg) : (() => {
+  const root = dirArg ? resolve15(dirArg) : (() => {
     try {
       return findProjectRoot(process.cwd());
     } catch {
@@ -222543,16 +223121,16 @@ import { delimiter as delimiter2, dirname as dirname20, join as join29 } from "n
 // src/commands/install.ts
 init_util();
 import { execFileSync as execFileSync5 } from "node:child_process";
-import { appendFileSync as appendFileSync3, chmodSync as chmodSync2, cpSync as cpSync4, existsSync as existsSync29, mkdirSync as mkdirSync20, readFileSync as readFileSync27, realpathSync, rmSync as rmSync7, symlinkSync } from "node:fs";
+import { appendFileSync as appendFileSync3, chmodSync as chmodSync2, cpSync as cpSync4, existsSync as existsSync29, mkdirSync as mkdirSync21, readFileSync as readFileSync27, realpathSync, rmSync as rmSync7, symlinkSync } from "node:fs";
 import { homedir as homedir7 } from "node:os";
-import { basename as basename15, delimiter, dirname as dirname19, join as join28, resolve as resolve15, sep as sep2 } from "node:path";
+import { basename as basename15, delimiter, dirname as dirname19, join as join28, resolve as resolve16, sep as sep2 } from "node:path";
 var isWin = process.platform === "win32";
 var HOME = homedir7();
 var safeRealpath = (p2) => {
   try {
     return realpathSync(p2);
   } catch {
-    return resolve15(p2);
+    return resolve16(p2);
   }
 };
 var onPath = (dir) => {
@@ -222580,7 +223158,7 @@ var install = async (args) => {
   return installUnix(args, bundle, companions);
 };
 var copyBundle = (bundle, target, companions) => {
-  mkdirSync20(target, { recursive: true });
+  mkdirSync21(target, { recursive: true });
   if (safeRealpath(target) === safeRealpath(bundle))
     return;
   for (const f3 of companions) {
@@ -222598,8 +223176,8 @@ var permError = (e2, dir, system) => {
 };
 var installUnix = (args, bundle, companions) => {
   const system = flagBool(args, "system");
-  const libDir = resolve15(flagStr(args, "dir") ?? (system ? "/usr/local/lib/lecodes-cli" : join28(HOME, ".local", "lib", "lecodes-cli")));
-  const binDir = resolve15(flagStr(args, "bin") ?? (system ? "/usr/local/bin" : join28(HOME, ".local", "bin")));
+  const libDir = resolve16(flagStr(args, "dir") ?? (system ? "/usr/local/lib/lecodes-cli" : join28(HOME, ".local", "lib", "lecodes-cli")));
+  const binDir = resolve16(flagStr(args, "bin") ?? (system ? "/usr/local/bin" : join28(HOME, ".local", "bin")));
   const link2 = join28(binDir, "lecodes");
   try {
     copyBundle(bundle, libDir, companions);
@@ -222609,7 +223187,7 @@ var installUnix = (args, bundle, companions) => {
     throw permError(e2, libDir, system);
   }
   try {
-    mkdirSync20(binDir, { recursive: true });
+    mkdirSync21(binDir, { recursive: true });
     rmSync7(link2, { force: true });
     symlinkSync(join28(libDir, "lecodes"), link2);
   } catch (e2) {
@@ -222670,7 +223248,7 @@ var finishPathUnix = (args, binDir) => {
   log(`  • or install system-wide (no PATH edit): ${c.bold("sudo lecodes install --system")}`);
 };
 var installWindows = (args, bundle, companions) => {
-  const target = resolve15(flagStr(args, "dir") ?? join28(process.env.LOCALAPPDATA ?? join28(HOME, "AppData", "Local"), "Programs", "lecodes-cli"));
+  const target = resolve16(flagStr(args, "dir") ?? join28(process.env.LOCALAPPDATA ?? join28(HOME, "AppData", "Local"), "Programs", "lecodes-cli"));
   try {
     copyBundle(bundle, target, companions);
   } catch (e2) {
@@ -222811,8 +223389,12 @@ ${c.bold("Commands:")}
                                   --png [file]       rasterize a PNG (default screenshot.png;
                                                        needs @napi-rs/canvas)
                                   --script <file>    drive the app through a step list (tap/type/
-                                                       scroll/wait/expect/screenshot/json steps)
+                                                       scroll/wait/expect/screenshot/json steps;
+                                                       games: frames/drag/hold/key/keyDown/keyUp,
+                                                       expect.log, screenshot clip)
                                   --out-dir <dir>    where --script step outputs land (default .)
+                                  --clip <name|x,y,w,h>  (--png) crop to one node's rect or a
+                                                       logical-px rect — a component/region render
                                   --fixtures <file>  canned fetch responses (URL pattern →
                                                        { status?, json?, text? }) — make
                                                        backend-gated screens reachable headless
@@ -222830,6 +223412,22 @@ ${c.bold("Commands:")}
                                                        LECODES_DESKTOP_EXE overrides)
                                   --frames <n>       (--desktop) frames to run before the shot —
                                                        headroom for async loads (default 60)
+                                  --desktop --script <file>  drive the scenario through the native
+                                                       host: tap/drag/hold take { x, y } coordinates
+                                                       (no names — the host has no UI tree; type/
+                                                       scroll/clip unavailable), expect.log is
+                                                       checked, text/node/screen/value are skipped;
+                                                       per-step screenshots + final --png
+                                  --view <name>      (--desktop) inspection camera auto-fitted to the
+                                                       whole 3D scene: iso | top | front | side | back
+                                                       [--fov N]; the app's camera is untouched
+                                  --camera x,y,z --look-at x,y,z [--fov N]
+                                                     (--desktop) inspection camera at a fixed eye /
+                                                       look-at point (world units, Y up). In a
+                                                       --script run use { "view" } / { "camera" } steps
+                                  --fixed-dt <ms>    (--desktop) virtual app clock, ms per frame —
+                                                       deterministic game time (scripted runs
+                                                       default to 16; plain renders to wall clock)
   test [name…]                  Run headless flow tests: tests/*.flow.json scenarios, plus flows
                                   derived from the design graph (design/meta.json activator edges
                                   — checks the built app against the designed navigation; needs
@@ -222846,6 +223444,11 @@ ${c.bold("Commands:")}
                                   --dir <folder>     tests folder (default tests/)
                                   --design-dir <dir> design folder (default design/)
                                   --artifacts <dir>  failure-artifact folder override
+                                  --desktop          run the file scenarios through the NATIVE host
+                                                       (coordinates only; expect.log checked,
+                                                       text/node/screen/value skipped; design flows
+                                                       stay headless). --frames / --fixed-dt as in
+                                                       render --desktop
                                   (+ the render timing flags: --width/--height, --settle,
                                    --device, --safe-area, --wait-network, --logs, --entry)
   types [dir]                   Refresh the IDE types (.lecodes/types/ + tsconfig.json) — by
@@ -222884,7 +223487,9 @@ ${c.bold("Commands:")}
                                           app.json fullscreen; --scale <0.5..4|fit> overrides
                                           the display scale — "fit" sizes a 1080p-designed app
                                           to the monitor with the density raised to match;
-                                          --entry overrides the entrypoint)
+                                          --entry overrides the entrypoint; asset() resources
+                                          load from the working tree — --remote-assets or
+                                          --public-url <url> uses the server's copies instead)
                                   update  move to the newest published release
                                           (cached in ~/.lecodes/renderer)
   scene [path]                  LeCodes Scene Editor — visually edit a .scene.ts (tree, inspector,