lecodes-cli 1.0.0 → 2.0.1

package/src/commands/app/desktopMac.ts

@@ -53,14 +53,14 @@ const cleanBundleName = (name: string) => name.replace(/[/:]/g, "").trim() || "A
 
 /* ------------------------------------- host bundle ------------------------------------- */
 
-/** The .app that owns a host executable (…/X.app/Contents/MacOS/lecodes-app → …/X.app). */
+/** The .app that owns a host executable (…/X.app/Contents/MacOS/lecodes-desktop → …/X.app). */
 export const macHostAppOf = (exe: string): string => {
   const app = resolve(exe, "..", "..", "..")
   if (!app.endsWith(".app") || !existsSync(join(app, "Contents", "Info.plist"))) {
     throw new CliError(
       `The macOS host must be an .app bundle (got ${exe}). Install LeCodes Desktop.app, or point ` +
-      `LECODES_DESKTOP_EXE at <Build>.app/Contents/MacOS/lecodes-app — a bare SwiftPM binary has no ` +
-      `resource bundles and can't be re-signed into an app.`,
+      `LECODES_DESKTOP_EXE at <Build>.app/Contents/MacOS/lecodes-desktop — a bare build-tree binary has no ` +
+      `Resources/runtime and can't be re-signed into an app (hosts/desktop/package-macos.sh makes the bundle).`,
     )
   }
   return app
@@ -120,7 +120,7 @@ export const assertMacHostCanBundle = (exe: string) => {
     `This LeCodes Desktop host (${macHostAppOf(exe)}) predates project bundles — an app built from it would ` +
     "open the host's home screen instead of the project.\n" +
     "  Run `lecodes desktop update` (needs a published macOS host with project-bundle support), or point " +
-    "LECODES_DESKTOP_EXE at a current build (…/LeCodes Desktop.app/Contents/MacOS/lecodes-app).",
+    "LECODES_DESKTOP_EXE at a current build (…/LeCodes Desktop.app/Contents/MacOS/lecodes-desktop).",
   )
 }
 
@@ -318,16 +318,17 @@ const writeIcns = async (root: string, config: AppConfig, dest: string, tmp: str
 
 /* ---------------------------------------- probe ---------------------------------------- */
 
-/** `--probe`: launch the built app for a few seconds and grab the presented 3D frame through the
- *  host's LECODES_SNAPSHOT hook. The window shows briefly — the macOS host has no hidden mode. */
+/** `--probe`: launch the built app for a few seconds and grab its last frame through the host's
+ *  headless render contract (CREATOR_MAX_FRAMES + CREATOR_DUMP_PNG, the same as render --desktop).
+ *  The window shows: the probe proves the SHIPPED bundle launches from cwd "/", not the hidden path. */
 const probeMacApp = async (app: string, out: string, after: number) => {
   const shot = join(out, `${basename(app, ".app")}-probe.png`)
   rmSync(shot, { force: true })
-  note(`Probe: launching the built app for ${after + 2}s (the window will show)…`)
+  note(`Probe: launching the built app for ~${after + 2}s (the window will show)…`)
   await new Promise<void>((done, fail) => {
-    const child = spawn(join(app, "Contents", "MacOS", "lecodes-app"), [], {
+    const child = spawn(join(app, "Contents", "MacOS", "lecodes-desktop"), [], {
       cwd: "/",   // what Finder gives a double-clicked app — proves nothing leans on the cwd
-      env: { ...process.env, LECODES_SNAPSHOT: shot, LECODES_SNAPSHOT_AFTER: String(after), LECODES_EXIT_AFTER: String(after + 2) },
+      env: { ...process.env, CREATOR_DUMP_PNG: shot, CREATOR_MAX_FRAMES: String((after + 2) * 60) },
       stdio: ["ignore", "pipe", "pipe"],
     })
     const tail: string[] = []

package/src/commands/app/icon.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { dirname, join, resolve } from "node:path"
 import type { JimpInstance } from "jimp"
+import { Color } from "lecodes-sdk/color"
 import { CliError, c, log, warn } from "../../cli"
 import type { AppConfig } from "./shared"
 
@@ -36,12 +37,14 @@ export const loadIconMaster = async (root: string, config: AppConfig): Promise<I
   const path = resolve(root, rel)
   if (!existsSync(path)) throw new CliError(`app.json "icon": ${rel} not found`)
 
-  const raw = (config.iconBackground ?? "#FFFFFF").trim()
-  const expanded = /^#[0-9a-fA-F]{3}$/.test(raw) ? "#" + [...raw.slice(1)].map(ch => ch + ch).join("") : raw
-  const m = /^#([0-9a-fA-F]{6})$/.exec(expanded)
-  if (!m) throw new CliError(`app.json "iconBackground" must be #RGB or #RRGGBB (got "${config.iconBackground}")`)
-  const backgroundHex = "#" + m[1].toUpperCase()
-  const background = (parseInt(m[1], 16) * 0x100 + 0xff) >>> 0
+  // Any CSS color, opaque (an icon backdrop has no alpha): the SDK's one parser.
+  const rgba = Color.tryParse(config.iconBackground ?? "#FFFFFF")
+  if (!rgba || (Color.toPackedRgba(rgba) & 0xff) !== 0xff) {
+    throw new CliError(`app.json "iconBackground" must be an opaque CSS color — #RRGGBB, a name, rgb() / hsl() (got ${JSON.stringify(config.iconBackground)})`)
+  }
+  const rgb = Color.toPackedRgb(rgba)
+  const backgroundHex = "#" + rgb.toString(16).padStart(6, "0").toUpperCase()
+  const background = (rgb * 0x100 + 0xff) >>> 0
 
   const { Jimp } = await import("jimp")
   let image: JimpInstance

package/src/commands/app/index.ts

@@ -379,7 +379,9 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
   // host's setFetchLocal reads Resources/ by basename, falling back to the SDK resources
   // bundle for the sdkProvided names.
   const preload = /^\/\/ preload: (.*)$/m.exec(bundleJs)?.[1].split(";").map((s) => s.trim()).filter(Boolean) ?? []
-  const IMPLICIT_PRELOADS = new Set(["uberarchive", "capture"]) // engine-synthesized, not project files
+  // engine-synthesized, not project files: the ubershader archive, the capture flag and the
+  // engine's own materials (`material:<name>` — they ride the SDK)
+  const IMPLICIT_PRELOADS = { has: (name: string) => name === "uberarchive" || name === "capture" || name.startsWith("material:") }
   const byName = new Map<string, BundleResource[]>()
   for (const r of resources) {
     if (r.remote || !r.absPath) continue

package/src/commands/app/shared.ts

@@ -62,7 +62,7 @@ export interface AppConfig {
     signing?: { storeFile?: string, keyAlias?: string },
     minify?: boolean,
   }
-  /** Desktop host (packages/desktop). `window` sizes are LOGICAL units — the host multiplies by
+  /** Desktop host (hosts/desktop). `window` sizes are LOGICAL units — the host multiplies by
    *  the display scale. `entry` picks a per-target entry file (default: the detected project
    *  entry) — see docs/desktop-target-plan.md. */
   desktop?: {
@@ -80,6 +80,14 @@ export interface AppConfig {
     /** 3D buffer cap in px, e.g. [1920, 1080]: on a bigger window/monitor the 3D renders at most
      *  this size (aspect kept) — the per-machine answer to "fullscreen on a 4K display is slow". */
     maxRenderSize?: [number, number],
+    /** Frame-rate CAP for the host's render loop: `"display"` (default — follow the screen's refresh
+     *  rate, 120 on a ProMotion Mac) or a number, meaning "at most this many fps" (the screen's
+     *  maximum still wins when it is lower — vsync is the real ceiling, so this can never be a
+     *  target above it). For an app that wants to spend less: a UI-heavy app on a laptop, a game
+     *  whose feel is tuned for 60. `desktop run` forwards it as CREATOR_FRAME_RATE (a set env wins);
+     *  a built .app's host reads it from the staged app.json. Honoured by the macOS host
+     *  (2026-09-09); the Windows/Linux host is vsync-locked and ignores it for now. */
+    frameRate?: number | "display",
     /** The mouse button acts as a finger: a left click-drag scrolls + flings like touch (the wheel
      *  always scrolls, clicks are unaffected; a button inside a scrollable then gets the touch-style
      *  press feedback delay). For testing the touch experience without a touchscreen, or an app
@@ -97,7 +105,7 @@ export interface AppConfig {
 }
 
 /** One style slot of the desktop on-screen keyboard — the SDK's style words, the subset the drawn
- *  keyboard reads. Unset fields keep the theme preset. */
+ *  keyboard reads (colors: any CSS color string). Unset fields keep the theme preset. */
 export interface DesktopKeyboardSlot {
   backgroundColor?: string
   color?: string
@@ -274,8 +282,8 @@ export interface PluginManifest {
      *  Bare ids resolve through the CLI's known-version table; "id:version" pins explicitly. */
     gradlePlugins?: string[],
   } | null
-  /** Desktop host (packages/desktop): a PREBUILT shared library per OS/arch behind the C ABI in
-   *  `packages/desktop/plugin-sdk/lecodes_plugin.h` — no host rebuild, no source vendoring.
+  /** Desktop host (hosts/desktop): a PREBUILT shared library per OS/arch behind the C ABI in
+   *  `hosts/desktop/plugin-sdk/lecodes_plugin.h` — no host rebuild, no source vendoring.
    *  `library` keys are `${process.platform}-${process.arch}` ("win32-x64", "linux-x64",
    *  "linux-arm64"), values plugin-dir-relative paths. `lecodes desktop run` / `render --desktop`
    *  forward the library's dir to the host (CREATOR_PLUGIN_DIRS); `app build desktop` stages the
@@ -533,7 +541,7 @@ const isDesktopPluginLibrary = (name: string): boolean => {
   return process.platform === "win32" ? n.endsWith(".dll") : n.endsWith(".so")
 }
 
-/** Native plugin libraries for THIS project on THIS machine (packages/desktop/plugin-sdk/
+/** Native plugin libraries for THIS project on THIS machine (hosts/desktop/plugin-sdk/
  *  lecodes_plugin.h — runtime-loaded .dll/.so, no host rebuild):
  *    - every library in the project's own `plugins/` dir — the zero-manifest dev loop (build a
  *      DLL, drop it there, `lecodes desktop run`);

package/src/commands/app/templates/android.ts

@@ -144,20 +144,18 @@ dependencies {
 
 /** lecodes-runtime/src/main/kotlin/io/letary/lecodes/runtime/LeCodesRuntime.kt — the generated
  *  registration + host-hook surface. Plugins are called by FQN (no import collisions); the
- *  activity hooks are always present and inert without a consuming plugin (the Android analog
- *  of iOS's buffered LeCodesAppHooks — here the only launch-time state, a notification tap's
- *  intent extra, survives until the host forwards it, so no buffering is needed). */
+ *  activity hooks forward to the SDK's LeCodesAppHooks, which NAMES NO PLUGIN — a plugin that
+ *  consumes activity moments (push: a notification tap is an intent) attaches its handler there. */
 export const runtimeKotlinTemplate = (plugins: AndroidRuntimePlugin[], projectUuid?: string): string => {
   const identity = projectUuid ? `        engine.bootProjectUuid = "${projectUuid}"\n` : ""
   const calls = plugins.map(p => `        ${p.register}.register(engine, context)\n`).join("")
   const body = identity + calls
-  const push = plugins.find(p => p.id === "push")
-  const pushNs = push ? push.register.split(".").slice(0, -1).join(".") : null
   return `// Generated by \`lecodes app sync\` — regenerated on every sync, do not edit.
 package io.letary.lecodes.runtime
 
 import android.content.Context
 import android.content.Intent
+import io.letary.lecodes.LeCodesAppHooks
 import io.letary.lecodes.LecodesEngine
 
 object LeCodesRuntime {
@@ -170,16 +168,17 @@ ${body === "" ? "        // no plugins installed\n" : body}    }
     /** Cold create only (savedInstanceState == null): forward the launch intent so a plugin
      *  can park launch-time state (a push notification tap) before the engine boots. */
     fun onActivityLaunch(intent: Intent) {
-${push ? `        ${pushNs}.PushPlugin.parkLaunchPayload(intent)\n` : "        // no plugin consumes launch intents\n"}    }
+        LeCodesAppHooks.launchIntent(intent)
+    }
 
     /** Warm intent (Activity.onNewIntent). @return true when a plugin consumed it — the
      *  caller must then SKIP its generic deep-link handling. */
-    fun onNewIntent(intent: Intent): Boolean {
-${push ? `        return ${pushNs}.PushPlugin.handleTapIntent(intent)\n` : "        return false\n"}    }
+    fun onNewIntent(intent: Intent): Boolean = LeCodesAppHooks.newIntent(intent)
 
     /** Activity.onResume(true) / onPause(false). */
     fun setForeground(foreground: Boolean) {
-${push ? `        ${pushNs}.PushPlugin.setForeground(foreground)\n` : "        // no plugin tracks foreground state\n"}    }
+        LeCodesAppHooks.foreground(foreground)
+    }
 }
 `
 }
@@ -321,8 +320,8 @@ R8 only touches the dex — the engine's native libraries and \`app.js\` are not
 ## Icons
 
 The easy path: set \`app.json\` \`"icon"\` to a square ≥1024px PNG/JPEG in the project (e.g.
-\`"icon": "icon.png"\`, optional \`"iconBackground": "#RRGGBB"\` — the adaptive-icon backdrop,
-default white). Every \`lecodes app sync\` then renders the full launcher set: legacy density
+\`"icon": "icon.png"\`, optional \`"iconBackground": "#RRGGBB"\` (any opaque CSS color) — the adaptive-icon
+backdrop, default white). Every \`lecodes app sync\` then renders the full launcher set: legacy density
 PNGs, the API 26+ adaptive icon (your image at 72dp on the 108dp canvas), and an Android 13
 themed-icon (monochrome) layer that reuses the foreground silhouette.
 

package/src/commands/app/templates/ios.ts

@@ -485,7 +485,7 @@ export const VIEW_CONTROLLER = `//
 //  Generated by lecodes app init — yours to edit.
 //
 //  Runs the bundled app.js (produced by \`lecodes app sync\`) offline: everything the
-//  script needs is provided by the SDK core (_creatorUI / _creatorUtils / console)
+//  script needs is provided by the SDK core (_creatorTree / the host bridges / console)
 //  plus the plugins registered below via LeCodesRuntime.
 //
 

package/src/commands/assets.ts

@@ -3,7 +3,7 @@ import { resolveCmgenExe } from "../hosts/cmgenTool"
 import { loadPeer } from "../hosts/peerInstall"
 
 /*
- * `lecodes assets …` — the asset pipeline (packages/lecodes-assets): FBX → GLB, the GLB doctor,
+ * `lecodes assets …` — the asset pipeline (tools/assets): FBX → GLB, the GLB doctor,
  * retargeting, Unity packs, skies. The package is an optional peer with its OWN argv parser and
  * help, so the argv is forwarded untouched (`passthrough`) — `lecodes assets --help` is theirs.
  */

package/src/commands/compile.ts

@@ -4,7 +4,7 @@ import { getProject } from "../platform/api"
 import { findProjectRoot, readManifest, type Manifest } from "../project/manifest"
 import { collectEntries } from "../compile/collect"
 import { collectLocalEntries } from "../compile/collectLocal"
-import { ambiguousEntryWarning, compileProject, type CompileEntry } from "../compile/projectCompile"
+import { ambiguousEntryWarning, compileProject, localAssetNames, type CompileEntry } from "../compile/projectCompile"
 import { applyProjectFonts } from "../compile/fonts"
 import { applyLocalShaders, desktopShaderPlatform, type StagedShader } from "../compile/shaders"
 import type { DesktopRenderer } from "../hosts/desktopRenderer"
@@ -134,12 +134,14 @@ export const buildBundle = async (bundle: BundleOptions, opts: BuildBundleOption
     localAssets = !!shell || (!!opts.localAssets && bundle.publicUrl === undefined && !bundle.remoteAssets)
 
     note("Resolving project assets…")
+    const tResolve = performance.now()
     const project = await getProject(apiUrl, token, manifest.uuid)
     // Local-asset compiles use URL-less resources as-is instead of degrading, so skip that warning
     // there (an unpushed resources.remote match still warns below).
     ;({ entries, warnings } = collectEntries(root, manifest, project, { warnMissingUrl: !localAssets }))
     name = manifest.name
     publicUrl = bundle.publicUrl ?? apiUrl
+    note(`Resolved ${entries.length} entries in ${((performance.now() - tResolve) / 1000).toFixed(1)} s`)
 
     // Local-asset compile: everything resolves from the tree except the resources.remote matches,
     // which keep their server URL — and can't without one, so an unpushed match falls back to local.
@@ -162,7 +164,9 @@ export const buildBundle = async (bundle: BundleOptions, opts: BuildBundleOption
     if (opts.localAssets && bundle.remoteAssets) warnErr("This is a local project (no server) — assets always load from the working tree.")
     // localShaders: a local-asset compile compiles the .mat files itself below, so the
     // "push the project once" degradation notice would be wrong.
+    const tEntries = performance.now()
     ;({ entries, warnings } = collectLocalEntries(root, null, "", { localShaders: localAssets && (opts.localShaders ?? !shell) }))
+    note(`Collected ${entries.length} entries in ${((performance.now() - tEntries) / 1000).toFixed(1)} s`)
     name = basename(root)
     if (shell && shell.remotePatterns.length > 0) warnErr("resources.remote needs a server-backed project (a streamed asset needs a server URL) — bundling everything.")
   }
@@ -187,6 +191,7 @@ export const buildBundle = async (bundle: BundleOptions, opts: BuildBundleOption
   // vendors faces into assets/fonts/ so the bundle stays self-contained (fetchLocal / --public-url).
   // Shell compiles pass publicUrl "" here so the `// fonts:` header carries no face URLs — the
   // host must register faces from the bundle, never wait on the network before first paint.
+  const tPrep = performance.now()
   const fontsHeader = await applyProjectFonts(entries, (manifest && !localAssets)
     ? { mode: "cdn", root, publicUrl }
     : {
@@ -199,8 +204,10 @@ export const buildBundle = async (bundle: BundleOptions, opts: BuildBundleOption
   // project. The returned pack list becomes the `// icons:` attribution header.
   if (opts.extraEntries) entries.push(...opts.extraEntries)
   const iconsHeader = await applyAppAssetIcons(entries)
+  note(`Prepared shaders, fonts and icons in ${((performance.now() - tPrep) / 1000).toFixed(1)} s`)
 
   note("Compiling…")
+  const tCompile = performance.now()
   const entryOverride = opts.entryOverride ?? bundle.entry
   if (!entryOverride) {
     const ambiguous = ambiguousEntryWarning(entries)
@@ -212,14 +219,20 @@ export const buildBundle = async (bundle: BundleOptions, opts: BuildBundleOption
     localAssets, fontsHeader, iconsHeader,
     minify: bundle.minify,
     sourcemap: bundle.sourcemap,
+    onWarning: (w) => warnings.push(w),
   })
+  note(`Compiled in ${((performance.now() - tCompile) / 1000).toFixed(1)} s (${(js.length / 1024).toFixed(0)} KB)`)
 
   for (const w of warnings) warnErr(w)
 
   // Resource inventory for shell/render callers (includes faces the font pass vendored into entries).
+  // The NAME is what the bundle passes to fetchLocal, so it has to come from where the bundle got
+  // it: a basename two project files share is disambiguated there, and a caller that re-derived the
+  // basename here would stage both packs' SM_Sign_01.glb onto one file again.
+  const localNames = localAssetNames(entries)
   const resources: BundleResource[] = entries
     .filter((e) => e.type === "resource")
-    .map((e) => ({ path: e.path.replace(/^\//, ""), name: e.path.split(/[\\/]/).pop() ?? e.path, absPath: e.absPath, remote: !!e.remote }))
+    .map((e) => ({ path: e.path.replace(/^\//, ""), name: localNames.get(e.path) ?? e.path.split(/[\\/]/).pop() ?? e.path, absPath: e.absPath, remote: !!e.remote }))
   // Compiled shader artifacts ship the same way (copied next to app.js, loaded by name), flagged
   // so the desktop packager keeps them — they have no asset() reference for its scan to match.
   for (const artifact of stagedShaders) resources.push({ path: artifact.name, name: artifact.name, absPath: artifact.absPath, remote: false, shader: true })

package/src/commands/design/index.ts

@@ -20,7 +20,7 @@ export { flushDesignComments, type CommentFlush } from "./comments"
  *
  *   design [serve]     start the dev server + browser canvas (needs `lecodes-design`)
  *   design init        scaffold the design folder (screens/, shared/, meta.json, spec.md, CLAUDE.md)
- *   design snapshot    render screens headless to JSON/PNG (snapshot.ts, needs `lecodes-renderer`)
+ *   design snapshot    render screens headless to JSON/PNG (snapshot.ts, needs `lecodes-headless`)
  *   design arrange     auto-layout the flow graph (--new: only place unplaced screens)
  *   design check       static coherence: spec.md links, flow warnings, untagged screens
  *   design share       toggle the public share link (design must be pushed first)
@@ -51,10 +51,10 @@ const serve = async (flags: FlagValues<typeof serveFlags>): Promise<void> => {
   const ctx = getContext(flags.dir)
   const designServer = await loadDesignServer(ctx)
 
-  // The MCP render_screen tool renders headless through lecodes-renderer, injected here so the
+  // The MCP render_screen tool renders headless through lecodes-headless, injected here so the
   // design server keeps no dependency on it. Absent renderer → the tool returns an install hint.
   // Opportunistic: never triggers an install from inside the MCP server (the tool reports the hint).
-  const renderer = await loadPeer<typeof import("lecodes-renderer/headless")>("lecodes-renderer", "headless", { for: "lecodes design (render_screen)", install: false })
+  const renderer = await loadPeer<typeof import("lecodes-headless/headless")>("lecodes-headless", "headless", { for: "lecodes design (render_screen)", install: false })
   const renderScreen = renderer
     ? async (id: string, format: "json" | "png" | "both", state?: string) => {
         const js = await compileDesignScreen({
@@ -104,7 +104,7 @@ const serve = async (flags: FlagValues<typeof serveFlags>): Promise<void> => {
 
   log(`${c.bold("LeCodes Design")} — ${ctx.name}`)
   log(`Canvas:   ${c.bold(server.url)}`)
-  log(`MCP:      ${c.bold(server.url + "/mcp")}${renderer ? "" : c.dim("  (render_screen off — npm install -g lecodes-renderer)")}`)
+  log(`MCP:      ${c.bold(server.url + "/mcp")}${renderer ? "" : c.dim("  (render_screen off — npm install -g lecodes-headless)")}`)
   log(`Watching: ${ctx.dirName}/  (screens hot-reload on save; Ctrl+C to stop)`)
   if (sync) log(`Comments: ${c.dim("in sync with the platform — replies and resolves go back automatically")}`)
   if (!flags["no-open"]) openBrowser(server.url)

package/src/commands/design/snapshot.ts

@@ -7,7 +7,7 @@ import { readMetaFrames } from "../../project/designMeta"
 import { dirFlag, getContext, type DesignServer } from "./context"
 
 /*
- * `lecodes design snapshot [screen…]` — render design screens headless through lecodes-renderer,
+ * `lecodes design snapshot [screen…]` — render design screens headless through lecodes-headless,
  * the way the board's MCP render_screen tool does, for AI feedback without a browser. One requested
  * screen prints its JSON to stdout; anything else lands as files in <dir>/.snapshots/ (or --out-dir).
  * States: `--state <s>` renders one named state of each screen, `--all-states` every discovered
@@ -26,7 +26,7 @@ const listScreens = (designDir: string): string[] => {
 
 export default defineCommand({
   name: "snapshot",
-  summary: "Render design screens headless to JSON / PNG (needs lecodes-renderer)",
+  summary: "Render design screens headless to JSON / PNG (needs lecodes-headless)",
   usage: "[screen…]",
   description: "One screen → its JSON on stdout; otherwise one file per screen in <dir>/.snapshots/ (<id>.json, <id>@<state>.json, PNGs with --png). --state and --all-states need lecodes-design to discover a screen's states from its source. A stuck screen (runaway loop) is killed after 120 s.",
   flags: {
@@ -56,7 +56,7 @@ export default defineCommand({
     const allStates = flags["all-states"]
     if (stateFlag !== undefined && allStates) throw new CliError("Use either --state <name> or --all-states, not both.")
 
-    const renderer = await loadPeer<typeof import("lecodes-renderer/headless")>("lecodes-renderer", "headless", { for: "lecodes design render" })
+    const renderer = await loadPeer<typeof import("lecodes-headless/headless")>("lecodes-headless", "headless", { for: "lecodes design render" })
 
     // Enumerating / validating states parses the screen source — that discovery lives in the design
     // package. The canonical-only path (no flag) needs no discovery, so base snapshot stays lean.

package/src/commands/desktop.ts

@@ -51,13 +51,14 @@ const run = defineCommand({
     "render-scale": str("3D render resolution 0.25..1 (over app.json desktop.renderScale)", { value: "<n>" }),
     renderer: str("host + shader variant: gl | vulkan (default: app.json desktop.renderer, else gl)", { value: "<gl|vulkan>" }),
     fps: bool("draw the host's frame counter in the corner (composited fps + the 3D fps when they diverge)"),
+    perf: bool("the host's profiler: a [perf] line a second (GPU frame time, CPU split, what the camera sees) + a second overlay row; implies --fps"),
     server: bool("launch as a multiplayer server"),
     port: num("(--server) listen port"),
     "max-clients": num("(--server) client cap"),
     connect: str("join a server as a client", { value: "<ip:port>" }),
     ...bundleFlags,
   },
-  examples: ["lecodes desktop run", "lecodes desktop run --scale fit --fps", "lecodes desktop run --server --port 7777"],
+  examples: ["lecodes desktop run", "lecodes desktop run --scale fit --fps", "lecodes desktop run --perf", "lecodes desktop run --server --port 7777"],
   run: async ({ flags, raw }) => {
     // Window defaults come from app.json's desktop block (flags win); standalone projects
     // without an app.json keep the host's built-in 1280×720.
@@ -89,11 +90,14 @@ const run = defineCommand({
       // from app.json only. Both are desktop-level (the machine/app), not window-level.
       renderScale: resolveRenderScale(flags["render-scale"], appCfg?.desktop?.renderScale),
       maxRenderSize: appCfg?.desktop?.maxRenderSize,
+      // Frame-rate cap (app.json only — like renderScale it is a property of the app, not of a run).
+      frameRate: appCfg?.desktop?.frameRate,
       mouseEmulateTouch: appCfg?.desktop?.mouseEmulateTouch,
       virtualKeyboard: appCfg?.desktop?.virtualKeyboard,
       // --fps: the host's own corner counter. A flag and not app.json on purpose — it is something you
       // switch on while looking at a frame, not a property of the app.
       fps: flags.fps,
+      perf: flags.perf,
       net: flags.server
         ? { role: "server", port: flags.port, maxClients: flags["max-clients"] }
         : flags.connect ? { role: "client", address: flags.connect } : undefined,

package/src/commands/dev.ts

@@ -5,10 +5,11 @@ import { basename, join } from "node:path"
 import { findProjectRoot, readManifest, LECODES_DIR, type Manifest } from "../project/manifest"
 import { loadIgnore } from "../project/ignore"
 import { startDevServer } from "../dev/devServer"
-import { resolveWebRunnerDir } from "../dev/webRunner"
+import { resolveWebRunner } from "../dev/webRunner"
 import { openBrowser } from "../platform/browserAuth"
 import { runDesktopDev } from "../hosts/desktopRenderer"
 import { androidCrashLines, launchOnAndroid, type AndroidDevSession } from "../dev/androidDev"
+import { launchOnIos, type IosDevSession } from "../dev/iosDev"
 import { readAppConfigAt } from "./app/shared"
 import { resolveScale } from "./desktop"
 import { CliError, bool, c, defineCommand, log, note, num, str, warnErr } from "../cli"
@@ -20,15 +21,17 @@ import { toKey } from "../project/paths"
  *
  * Starts a LAN dev server (compile + assets + reload channel), prints a QR code, and watches the
  * working tree. The device opens the QR URL like any project URL; every save recompiles and
- * hot-swaps the running app (`_creatorUtils.run` — fresh context, rollback on error). Device
+ * hot-swaps the running app (`_creatorApp.run` — fresh context, rollback on error). Device
  * console output and errors stream back to this terminal. Fully local: no login, no le.codes
  * backend. Custom shaders compile locally too (matc, downloaded on first use — matcTool.ts);
  * only when matc can't be fetched do they fall back to server-compiled artifacts (push once).
  *
- * `--web` opens the same project in the browser: the dev server also serves the Web Lite runner
- * (viewer-lite's dist-embed, vendored as runtime/web) under /web/ — CSS-flexbox UI + OGL 3D + the
- * web twins of the camera/map plugins, no wasm. Same bundle and hot reload; browser console
- * output streams back here like a device's. The URL is printed whenever the runner is available.
+ * `--web` opens the same project in the browser: the dev server also serves, under /web/, the
+ * app in a device (lecodes-web-frame's page: the device, the orientation, the console) around the
+ * web player (lecodes-web-player's dist — the runtime as wasm: Filament, creator-2d, the tree UI,
+ * and the web halves of the plugins). A phone that opens the url gets the player alone, the app
+ * filling its window. Same bundle and hot reload; the browser's console output streams back here
+ * like a device's. The URL is printed whenever the player is available.
  *
  * `--android` opens the dev URL in the LeCodes app on the phone plugged in over adb (adb reverse:
  * no Wi-Fi/LAN address needed — see dev/androidDev.ts). With `--time <s>` the run is bounded —
@@ -36,6 +39,10 @@ import { toKey } from "../project/paths"
  * the app runs until Ctrl+C, and Ctrl+C force-stops it (a device run has no frame cap, and a 3D
  * scene left rendering heats a charging phone).
  *
+ * `--ios` is the Apple twin (dev/iosDev.ts): the LeCodes app on a booted simulator or a plugged-in
+ * iPhone through `xcrun simctl` / `devicectl`, the url as a launch argument. Same `--time` / `--png`
+ * shape (screenshots on a simulator).
+ *
  * `--desktop` opens the dev URL in the native host too (same server, same hot reload — the host
  * speaks the websocket channel). The window closing does NOT stop the server: phones stay
  * connected, and re-running with --desktop is the reopen. Host errors degrade to a warning — the
@@ -67,7 +74,7 @@ const WATCH_SKIP_FILES = new Set(["tsconfig.json", "jsconfig.json", ".gitignore"
  */
 const VIRTUAL_IFACE = /wsl|docker|hyper-v|vethernet|virtualbox|vmware|tap|tun|zerotier|tailscale|loopback/i
 
-const lanCandidates = (): { address: string, iface: string }[] => {
+export const lanCandidates = (): { address: string, iface: string }[] => {
   const nets = networkInterfaces()
   const out: { address: string, iface: string, rank: number }[] = []
   for (const iface of Object.keys(nets)) {
@@ -110,7 +117,7 @@ const printQr = async (url: string) => {
 export default defineCommand({
   name: "dev",
   summary: "Run the project on a device / the desktop / the browser from this machine, with hot reload",
-  description: "Starts a LAN dev server + prints a QR code; scan it with the LeCodes app. Saves recompile + hot-swap the running app; device logs/errors stream back here. No login needed. The /web/ URL (Web Lite runner) is served always; --web, --android and --desktop each also open the app on that host.",
+  description: "Starts a LAN dev server + prints a QR code; scan it with the LeCodes app. Saves recompile + hot-swap the running app; device logs/errors stream back here. No login needed. The /web/ URL (the web player) is served always; --web, --android and --desktop each also open the app on that host.",
   flags: {
     port: num("server port", { default: DEFAULT_PORT }),
     host: str("LAN address to advertise (default: auto-detect)", { value: "<ip>" }),
@@ -120,13 +127,17 @@ export default defineCommand({
     serial: str("(--android) the device to use", { value: "<id>" }),
     apk: str("(--android) install this build first", { value: "<file>" }),
     package: str("(--android) the app's package (default com.letary.lecodes)", { value: "<name>" }),
-    time: num("(--android) bounded check: screenshot after this many seconds, force-stop, exit (exit 1 on a crash)", { value: "<s>" }),
-    png: str("(--android --time) where the device screenshot goes", { value: "<file>" }),
-    web: bool("also open the app in the browser (Web Lite host: same bundle + hot reload, camera/map plugins have web twins)"),
+    time: num("(--android | --ios) bounded check: screenshot after this many seconds, force-stop, exit (exit 1 on a crash)", { value: "<s>" }),
+    png: str("(--android | --ios, with --time) where the device screenshot goes", { value: "<file>" }),
+    ios: bool("open the dev url in the LeCodes app on a booted simulator or a plugged-in iPhone (Mac + Xcode: simctl / devicectl); a simulator gets the 127.0.0.1 url, a phone the LAN url; Ctrl+C terminates the app"),
+    udid: str("(--ios) the simulator (udid or name) or device (udid or name) to use", { value: "<id>" }),
+    app: str("(--ios) install this LeCodesApp.app first", { value: "<dir>" }),
+    bundle: str("(--ios) the app's bundle id (default com.letary.lecodes)", { value: "<id>" }),
+    web: bool("also open the app in the browser (the web player in a device: same bundle + hot reload, the console)"),
     desktop: bool("also open the app in the native desktop host (same hot reload; window from app.json's desktop block; closing it keeps the server)"),
     fps: bool("(--desktop) draw the host's frame counter"),
   },
-  examples: ["lecodes dev", "lecodes dev --web", "lecodes dev --android --time 12 --png phone.png", "lecodes dev --desktop --fps"],
+  examples: ["lecodes dev", "lecodes dev --web", "lecodes dev --android --time 12 --png phone.png", "lecodes dev --ios --time 12 --png sim.png", "lecodes dev --desktop --fps"],
   run: async ({ flags }) => {
     // Inside a cloned project the server runs at its root; anywhere else it runs standalone against
     // the current directory (no login / manifest needed) — same rule as `lecodes design`.
@@ -142,9 +153,13 @@ export default defineCommand({
     const name = manifest?.name ?? basename(root)
 
     // Bun's node:http can't complete a websocket upgrade (writes to the upgraded socket are dropped),
-    // so the reload push would silently never reach devices. Node is the shipped runtime.
-    if (typeof (globalThis as { Bun?: unknown }).Bun !== "undefined") {
-      warnErr("Running under Bun: the websocket reload channel doesn't work here — run `lecodes dev` with Node (or use ?t=poll on the device URL).")
+    // so the reload push would silently never reach devices: a phone that scanned a websocket url
+    // sat on "Connected — loading the project…" forever. Under Bun every device url — the QR, the
+    // printed one, what --ios / --android open — is the POLL form (/dev-poll.js: a path, since the
+    // launcher only fetches urls that end in .js). Node is the shipped runtime.
+    const underBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined"
+    if (underBun) {
+      warnErr("Running under Bun: no websocket reload channel here — devices poll instead (the QR points at /dev-poll.js). Node is the shipped runtime.")
     }
 
     const port = flags.port || DEFAULT_PORT
@@ -157,14 +172,14 @@ export default defineCommand({
     const origin = `http://${host}:${port}`
     const token = loadDevToken(root)
 
-    const webDir = resolveWebRunnerDir()
-    if (flags.web && !webDir) {
-      throw new CliError("No Web Lite runner found for --web: this CLI has no runtime/web (a monorepo checkout needs `bun run build:embed` in packages/viewer-lite).")
+    const web = resolveWebRunner(note)
+    if (flags.web && !web) {
+      throw new CliError("No web player found for --web: this CLI has no runtime/web (a monorepo checkout needs `bun run build` in hosts/web-player).")
     }
     const server = await startDevServer({
       root, manifest, name, origin, port, token,
       entryOverride: flags.entry,
-      webDir,
+      web,
       log: note,
     }).catch((e: unknown) => {
       const msg = e instanceof Error ? e.message : String(e)
@@ -194,7 +209,6 @@ export default defineCommand({
     }
 
     const debug = process.env.LECODES_DEV_DEBUG === "1"
-    const underBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined"
     let timer: NodeJS.Timeout | null = null
     const onChange = (file: string | null) => {
       if (debug) note(`[watch] event: ${file ?? "(null)"} → ${shouldRecompile(file) ? "recompile" : "skip"}`)
@@ -225,13 +239,15 @@ export default defineCommand({
     log("")
     log(`${c.bold("LeCodes Dev")} — ${name}`)
     log("")
-    if (!flags["no-qr"]) await printQr(server.url)
-    log(`Scan the QR with the LeCodes app, or open:  ${c.bold(server.url)}`)
+    // The url a device opens: the websocket form, or the poll form under Bun (see above).
+    const deviceUrl = underBun ? server.url.replace(/\/dev\.js$/, "/dev-poll.js") : server.url
+    if (!flags["no-qr"]) await printQr(deviceUrl)
+    log(`Scan the QR with the LeCodes app, or open:  ${c.bold(deviceUrl)}`)
     // The browser runner: localhost is a secure context (camera works there), the LAN address is
     // what a phone's browser can reach.
     const webLocal = server.webUrl ? server.webUrl.replace(`http://${host}:`, "http://localhost:") : null
-    if (server.webUrl && webLocal) log(`In the browser (Web Lite):                  ${c.bold(webLocal)}   (LAN: ${server.webUrl})`)
-    note(`Older desktop builds (no websocket bridge): ${server.url}?t=poll`)
+    if (server.webUrl && webLocal) log(`In the browser:                             ${c.bold(webLocal)}   (LAN: ${server.webUrl})`)
+    if (!underBun) note(`Older desktop builds (no websocket bridge): ${server.url}?t=poll`)
     if (alternatives.length > 0) {
       note(`Device can't reach it? This machine also has ${alternatives.map((a) => `${a.address} (${a.iface})`).join(", ")} — retry with --host <ip>.`)
     }
@@ -248,17 +264,16 @@ export default defineCommand({
     if (flags.android) {
       const seconds = flags.time ?? 0
       const png = flags.png
-      // Under Bun the websocket channel never delivers (see the warning above): the phone would sit on
-      // "Connected — loading the project…" forever. The path-form poll url works on both runtimes.
-      const deviceUrl = `http://127.0.0.1:${port}${server.url.slice(origin.length)}`.replace(/\/dev\.js$/, underBun ? "/dev-poll.js" : "/dev.js")
+      // adb reverse: the phone reaches the server through its own loopback.
+      const androidUrl = `http://127.0.0.1:${port}${deviceUrl.slice(origin.length)}`
       let session: AndroidDevSession
       try {
-        session = launchOnAndroid({ port, url: deviceUrl, serial: flags.serial, apk: flags.apk, packageName: flags.package })
+        session = launchOnAndroid({ port, url: androidUrl, serial: flags.serial, apk: flags.apk, packageName: flags.package })
       } catch (e) {
         server.close(); watcher?.close()
         throw e
       }
-      note(`Android: ${session.serial} → ${deviceUrl} (adb reverse; device logs stream here as [device:log])`)
+      note(`Android: ${session.serial} → ${androidUrl} (adb reverse; device logs stream here as [device:log])`)
       const finish = (code: number) => {
         session.stop()
         server.close(); watcher?.close()
@@ -281,6 +296,42 @@ export default defineCommand({
       }
     }
 
+    if (flags.ios) {
+      const seconds = flags.time ?? 0
+      const png = flags.png
+      // A simulator shares the Mac's network: the loopback url, no Wi-Fi involved. A phone gets the
+      // LAN url the QR shows.
+      const path = deviceUrl.slice(origin.length)
+      let session: IosDevSession
+      try {
+        session = launchOnIos({ simulatorUrl: `http://127.0.0.1:${port}${path}`, deviceUrl, udid: flags.udid, app: flags.app, bundleId: flags.bundle })
+      } catch (e) {
+        server.close(); watcher?.close()
+        throw e
+      }
+      note(`iOS: ${session.name} → ${session.kind === "simulator" ? `http://127.0.0.1:${port}${path}` : deviceUrl} (device logs stream here as [device:log])`)
+      const finish = (code: number) => {
+        session.stop()
+        server.close(); watcher?.close()
+        process.exit(code)
+      }
+      process.on("SIGINT", () => { note(`Stopping the app on ${session.name}…`); finish(0) })
+      if (seconds > 0) {
+        setTimeout(() => {
+          const crashes = session.crashLines()
+          if (png) {
+            if (session.screenshot(png)) note(`Wrote ${png} (screenshot after ${seconds} s)`)
+            else warnErr(session.kind === "simulator" ? "Screenshot failed (simctl io screenshot)." : "Screenshots need a simulator (no capture channel to a phone).")
+          }
+          if (crashes.length > 0) {
+            warnErr(`The app crashed:\n${crashes.join("\n")}`)
+            finish(1)
+          }
+          finish(0)
+        }, seconds * 1000)
+      }
+    }
+
     if (flags.desktop) {
       const appCfg = readAppConfigAt(root)
       const win = appCfg?.desktop?.window
@@ -293,6 +344,8 @@ export default defineCommand({
         resizable: win?.resizable,
         title: win?.title ?? appCfg?.name ?? name,
         scale: resolveScale(undefined, win?.scale),
+        // The frame-rate cap is forwarded too: it changes how the game FEELS, and dev should match production.
+        frameRate: appCfg?.desktop?.frameRate,
         fps: flags.fps,
       }).then(
         () => note("Desktop window closed — the dev server keeps running (Ctrl+C to stop)."),