lecodes-cli 1.0.0 → 2.0.1

package/src/commands/update/index.ts

@@ -21,7 +21,7 @@ import app from "../app"
  *   3. shaders   recompile the project's .mat files with that matc                   (= `shaders compile`)
  *   4. types     the IDE types (.lecodes/types + tsconfig) from the server            (types.ts)
  *   5. shells    ios/ + android/ pins → newest SDK release + plugin tags, re-sync     (= `app update`)
- *   6. cli       the npm installs — every installed optional peer (lecodes-renderer, lecodes-design,
+ *   6. cli       the npm installs — every installed optional peer (lecodes-headless, lecodes-design,
  *                lecodes-3d-editor, lecodes-assets, @napi-rs/canvas) and the CLI itself that is behind:
  *                peers in ~/.lecodes/peers (first-use installs, peerInstall.ts) are re-installed there
  *                — the renderer at THIS CLI's version, the rest at npm's latest in range; global ones
@@ -92,7 +92,7 @@ const STANDALONE = existsSync(join(dirname(process.execPath), "runtime")) &&
 export default defineCommand({
   name: "update",
   summary: "Move everything the project depends on to its newest published state",
-  description: "In dependency order: the desktop host (`desktop update`), matc (`shaders update`), the project's shader compiles, the IDE types (.lecodes/types/ + tsconfig.json, from the server — the former `lecodes types`), the ios/android shell pins (`app update`), then the GLOBAL npm installs: every installed optional peer (lecodes-renderer, lecodes-design, lecodes-3d-editor, lecodes-assets) and this CLI that is behind npm's latest gets `npm install -g`.\n\nPinned tools are skipped, not overridden: LECODES_DESKTOP_EXE / LECODES_MATC mean a local build. Keeps going when a step fails; the summary says which.",
+  description: "In dependency order: the desktop host (`desktop update`), matc (`shaders update`), the project's shader compiles, the IDE types (.lecodes/types/ + tsconfig.json, from the server — the former `lecodes types`), the ios/android shell pins (`app update`), then the GLOBAL npm installs: every installed optional peer (lecodes-headless, lecodes-design, lecodes-3d-editor, lecodes-assets) and this CLI that is behind npm's latest gets `npm install -g`.\n\nPinned tools are skipped, not overridden: LECODES_DESKTOP_EXE / LECODES_MATC mean a local build. Keeps going when a step fails; the summary says which.",
   flags: {
     local: bool("types from the SDK bundled in this CLI"),
     "no-shells": bool("leave ios/android pins alone (no re-sync)"),
@@ -174,7 +174,7 @@ export default defineCommand({
         const where = peerSource(name, probe)
         const installed = peerVersion(name, probe)
         const latest = !installed ? null
-          : where === "prefix" && name === "lecodes-renderer" ? pkg.version
+          : where === "prefix" && name === "lecodes-headless" ? pkg.version
           : await npmLatest(name)
         rows.push({ name, installed, latest, where })
       }

package/src/compile/designCompile.ts

@@ -18,7 +18,7 @@ import { applyProjectFonts } from "./fonts"
 
 export type DesignAssetMode = "server" | "disk"
 
-// Must match lecodes-renderer's LOCAL_ASSET_SCHEME (headless/index.ts) — same as `lecodes render`.
+// Must match lecodes-headless's LOCAL_ASSET_SCHEME (headless/index.ts) — same as `lecodes render`.
 const LOCAL_ASSET_SCHEME = "lecodesfile://"
 
 export const compileDesignScreen = async (opts: {

package/src/compile/headlessBundle.ts

@@ -1,133 +1,133 @@
-import { getProject } from "../platform/api"
-import { loadConfig, requireApiUrl, requireToken } from "../platform/config"
-import { findProjectRoot, readManifest, type Manifest } from "../project/manifest"
-import { collectEntries } from "./collect"
-import { collectLocalEntries } from "./collectLocal"
-import { ambiguousEntryWarning, compileProject } from "./projectCompile"
-import { applyProjectFonts } from "./fonts"
-import { applyAppAssetIcons } from "./assetIcons"
-import type { ScreenTarget } from "./screenEntry"
-import { note } from "../cli"
-
-/*
- * Compile the project into the iife bundle the headless renderer runs — shared by `lecodes render`
- * and `lecodes test`. Two modes, picked automatically (same split as `lecodes compile`):
- *   - Server-backed project (.lecodes/manifest.json): entries resolve from local files + the
- *     project's server metadata (needs login).
- *   - Local project (from `lecodes init` — no manifest): compiles straight from the working tree,
- *     no login.
- * In both, resource assets default to LOCAL disk reads: each asset('./x.png') URL becomes
- * `lecodesfile://<abs-path>` which the renderer reads off disk — unpushed/edited files render with
- * no network. `--remote-assets` / an explicit `--public-url` switch to server URLs instead
- * (server-backed projects only; then data needs --wait-network).
- */
-
-// URL scheme emitted for a local project's resources so the renderer reads them off disk. Must match
-// lecodes-renderer's LOCAL_ASSET_SCHEME (headless/runProject.ts).
-export const LOCAL_ASSET_SCHEME = "lecodesfile://"
-
-export type HeadlessBundle = {
-  js: string
-  /** The project root the bundle was compiled from. */
-  root: string
-  /** Non-fatal compile-time notices (missing URLs, engine hints) — print via warnErr. */
-  warnings: string[]
-  /** Whether asset URLs resolve from the local disk (`lecodesfile://`). */
-  useLocalAssets: boolean
-}
-
-/** What a headless compile honours: `--entry` / `--public-url` / `--remote-assets` / `--wait-network`,
- *  and the screen module a `render <file>` named. */
-export type HeadlessOptions = { entry?: string, publicUrl?: string, remoteAssets?: boolean, waitNetwork?: boolean, screen?: ScreenTarget }
-
-/** Compile the local project for a headless run. */
-export const compileHeadlessBundle = async (opts: HeadlessOptions = {}): Promise<HeadlessBundle> => {
-  let root: string
-  let manifest: Manifest | null
-  try {
-    root = findProjectRoot(process.cwd())
-    manifest = readManifest(root)
-  } catch {
-    root = process.cwd()
-    manifest = null
-  }
-
-  const publicUrlFlag = opts.publicUrl
-  // A local (server-less) project has no remote asset URLs — it always reads from disk.
-  const useLocalAssets = manifest ? (!publicUrlFlag && !opts.remoteAssets) : true
-
-  let entries
-  let warnings: string[]
-  let name: string
-  let publicUrl: string
-
-  if (manifest) {
-    const config = loadConfig()
-    const apiUrl = requireApiUrl(config)
-    const token = requireToken(config)
-
-    note("Resolving project assets…")
-    const project = await getProject(apiUrl, token, manifest.uuid)
-    ;({ entries, warnings } = collectEntries(root, manifest, project))
-    name = manifest.name
-    publicUrl = useLocalAssets ? LOCAL_ASSET_SCHEME : (publicUrlFlag ?? apiUrl)
-    // In local mode the "push it so its URL resolves" notices are moot (we read from disk).
-    if (useLocalAssets) warnings = warnings.filter((w) => !w.includes("No server URL"))
-  } else {
-    ;({ entries, warnings } = collectLocalEntries(root, null, ""))
-    name = root.split(/[\\/]/).pop() ?? "project"
-    publicUrl = LOCAL_ASSET_SCHEME
-    if (opts.remoteAssets || publicUrlFlag) {
-      warnings.push("This is a local project (no server) — assets always load from the working tree.")
-    }
-  }
-
-  // Local assets (default): resolve each resource (asset('./x.png')) from the working tree instead of
-  // the server, so unpushed / edited images show up with no --wait-network. Each resource's URL becomes
-  // `lecodesfile://<abs-path>`, which the renderer reads off disk.
-  const compileEntries = useLocalAssets
-    ? entries.map((e) => (e.type === "resource" && e.absPath)
-      ? { ...e, fileSrc: encodeURIComponent(e.absPath) }
-      : e)
-    : [...entries]
-  // Rendering one screen: the generated entry that imports it and calls .open() (see screenEntry.ts).
-  if (opts.screen) compileEntries.push(opts.screen.entry)
-
-  // font() macro: vendor registry faces into assets/fonts/ so headless renders read them off disk
-  // (lecodesfile://); with --remote-assets they stay CDN URLs like every other remote resource.
-  await applyProjectFonts(compileEntries, useLocalAssets
-    ? {
-        mode: "vendor", root, vendorDir: root, vendorPrefix: "",
-        makeResourceEntry: (path, absPath) => ({ path, type: "resource", fileSrc: encodeURIComponent(absPath), absPath }),
-      }
-    : { mode: "cdn", root })
-
-  // assetIcon() macro: resolve from the user-level cache (~/.lecodes/cache/icons) and inline, so
-  // headless renders stay deterministic and offline after the first fetch (like local assets).
-  await applyAppAssetIcons(compileEntries)
-
-  note("Compiling…")
-  const entryFlag = opts.screen?.entryPath ?? opts.entry
-  if (!entryFlag) {
-    const ambiguous = ambiguousEntryWarning(compileEntries)
-    if (ambiguous) warnings.push(ambiguous)
-  }
-  const js = await compileProject({
-    entries: compileEntries,
-    name,
-    publicUrl,
-    entryOverride: entryFlag,
-    header: false,
-    format: "iife",
-  })
-  if (js.includes("_creator.createScene") || js.includes("_creator.createEntity")) {
-    warnings.push("3D project: the scene graph is captured as `scene3d` in the JSON output; 3D isn't rasterized into PNGs.")
-  }
-  // With --remote-assets, 2D textures come from the network; without --wait-network they resolve empty
-  // and sprites render as flat placeholders. Local assets (default) load from disk, so no hint needed.
-  if (js.includes("_creator2d") && !useLocalAssets && !opts.waitNetwork) {
-    warnings.push("2D scene detected: sprite textures load over the network — add --wait-network to include them (else sprites render as flat placeholders).")
-  }
-
-  return { js, root, warnings, useLocalAssets }
-}
+import { getProject } from "../platform/api"
+import { loadConfig, requireApiUrl, requireToken } from "../platform/config"
+import { findProjectRoot, readManifest, type Manifest } from "../project/manifest"
+import { collectEntries } from "./collect"
+import { collectLocalEntries } from "./collectLocal"
+import { ambiguousEntryWarning, compileProject } from "./projectCompile"
+import { applyProjectFonts } from "./fonts"
+import { applyAppAssetIcons } from "./assetIcons"
+import type { ScreenTarget } from "./screenEntry"
+import { note } from "../cli"
+
+/*
+ * Compile the project into the iife bundle the headless renderer runs — shared by `lecodes render`
+ * and `lecodes test`. Two modes, picked automatically (same split as `lecodes compile`):
+ *   - Server-backed project (.lecodes/manifest.json): entries resolve from local files + the
+ *     project's server metadata (needs login).
+ *   - Local project (from `lecodes init` — no manifest): compiles straight from the working tree,
+ *     no login.
+ * In both, resource assets default to LOCAL disk reads: each asset('./x.png') URL becomes
+ * `lecodesfile://<abs-path>` which the renderer reads off disk — unpushed/edited files render with
+ * no network. `--remote-assets` / an explicit `--public-url` switch to server URLs instead
+ * (server-backed projects only; then data needs --wait-network).
+ */
+
+// URL scheme emitted for a local project's resources so the renderer reads them off disk. Must match
+// lecodes-headless's LOCAL_ASSET_SCHEME (headless/runProject.ts).
+export const LOCAL_ASSET_SCHEME = "lecodesfile://"
+
+export type HeadlessBundle = {
+  js: string
+  /** The project root the bundle was compiled from. */
+  root: string
+  /** Non-fatal compile-time notices (missing URLs, engine hints) — print via warnErr. */
+  warnings: string[]
+  /** Whether asset URLs resolve from the local disk (`lecodesfile://`). */
+  useLocalAssets: boolean
+}
+
+/** What a headless compile honours: `--entry` / `--public-url` / `--remote-assets` / `--wait-network`,
+ *  and the screen module a `render <file>` named. */
+export type HeadlessOptions = { entry?: string, publicUrl?: string, remoteAssets?: boolean, waitNetwork?: boolean, screen?: ScreenTarget }
+
+/** Compile the local project for a headless run. */
+export const compileHeadlessBundle = async (opts: HeadlessOptions = {}): Promise<HeadlessBundle> => {
+  let root: string
+  let manifest: Manifest | null
+  try {
+    root = findProjectRoot(process.cwd())
+    manifest = readManifest(root)
+  } catch {
+    root = process.cwd()
+    manifest = null
+  }
+
+  const publicUrlFlag = opts.publicUrl
+  // A local (server-less) project has no remote asset URLs — it always reads from disk.
+  const useLocalAssets = manifest ? (!publicUrlFlag && !opts.remoteAssets) : true
+
+  let entries
+  let warnings: string[]
+  let name: string
+  let publicUrl: string
+
+  if (manifest) {
+    const config = loadConfig()
+    const apiUrl = requireApiUrl(config)
+    const token = requireToken(config)
+
+    note("Resolving project assets…")
+    const project = await getProject(apiUrl, token, manifest.uuid)
+    ;({ entries, warnings } = collectEntries(root, manifest, project))
+    name = manifest.name
+    publicUrl = useLocalAssets ? LOCAL_ASSET_SCHEME : (publicUrlFlag ?? apiUrl)
+    // In local mode the "push it so its URL resolves" notices are moot (we read from disk).
+    if (useLocalAssets) warnings = warnings.filter((w) => !w.includes("No server URL"))
+  } else {
+    ;({ entries, warnings } = collectLocalEntries(root, null, ""))
+    name = root.split(/[\\/]/).pop() ?? "project"
+    publicUrl = LOCAL_ASSET_SCHEME
+    if (opts.remoteAssets || publicUrlFlag) {
+      warnings.push("This is a local project (no server) — assets always load from the working tree.")
+    }
+  }
+
+  // Local assets (default): resolve each resource (asset('./x.png')) from the working tree instead of
+  // the server, so unpushed / edited images show up with no --wait-network. Each resource's URL becomes
+  // `lecodesfile://<abs-path>`, which the renderer reads off disk.
+  const compileEntries = useLocalAssets
+    ? entries.map((e) => (e.type === "resource" && e.absPath)
+      ? { ...e, fileSrc: encodeURIComponent(e.absPath) }
+      : e)
+    : [...entries]
+  // Rendering one screen: the generated entry that imports it and calls .open() (see screenEntry.ts).
+  if (opts.screen) compileEntries.push(opts.screen.entry)
+
+  // font() macro: vendor registry faces into assets/fonts/ so headless renders read them off disk
+  // (lecodesfile://); with --remote-assets they stay CDN URLs like every other remote resource.
+  await applyProjectFonts(compileEntries, useLocalAssets
+    ? {
+        mode: "vendor", root, vendorDir: root, vendorPrefix: "",
+        makeResourceEntry: (path, absPath) => ({ path, type: "resource", fileSrc: encodeURIComponent(absPath), absPath }),
+      }
+    : { mode: "cdn", root })
+
+  // assetIcon() macro: resolve from the user-level cache (~/.lecodes/cache/icons) and inline, so
+  // headless renders stay deterministic and offline after the first fetch (like local assets).
+  await applyAppAssetIcons(compileEntries)
+
+  note("Compiling…")
+  const entryFlag = opts.screen?.entryPath ?? opts.entry
+  if (!entryFlag) {
+    const ambiguous = ambiguousEntryWarning(compileEntries)
+    if (ambiguous) warnings.push(ambiguous)
+  }
+  const js = await compileProject({
+    entries: compileEntries,
+    name,
+    publicUrl,
+    entryOverride: entryFlag,
+    header: false,
+    format: "iife",
+  })
+  if (js.includes("_creator.createScene") || js.includes("_creator.createEntity")) {
+    warnings.push("3D project: the scene graph is captured as `scene3d` in the JSON output; 3D isn't rasterized into PNGs.")
+  }
+  // With --remote-assets, 2D textures come from the network; without --wait-network they resolve empty
+  // and sprites render as flat placeholders. Local assets (default) load from disk, so no hint needed.
+  if (js.includes("_creator2d") && !useLocalAssets && !opts.waitNetwork) {
+    warnings.push("2D scene detected: sprite textures load over the network — add --wait-network to include them (else sprites render as flat placeholders).")
+  }
+
+  return { js, root, warnings, useLocalAssets }
+}

package/src/compile/nativeStack.ts

@@ -1,4 +1,4 @@
-import { extractInlineSourceMap, mapNamedFileStack } from "lecodes-viewer-lite/src/sourcemapError"
+import { extractInlineSourceMap, mapNamedFileStack } from "lecodes-web-shared/src/sourcemapError"
 
 /*
  * De-minify native (QuickJS) stack traces in a desktop host's output.

package/src/compile/projectCompile.ts

@@ -3,14 +3,14 @@ import { createRequire } from "node:module"
 import { dirname, join } from "node:path"
 import type { FileKind } from "../project/manifest"
 import { distRoot } from "../hosts/distRoot"
-import { compileProject as sdkCompileProject, detectEntry, scanModulesChisel, ENTRY_CONVENTION } from "lecodes-sdk/compile"
+import { compileProject as sdkCompileProject, detectEntry, scanModulesChisel, localAssetNames, ENTRY_CONVENTION } from "lecodes-sdk/compile"
 
 // Every project compiles through the SDK's one import-free compiler, which bundles with chisel (the
 // Rust method-granular bundler, @letary/chisel) — the only bundler. The SDK resolves the chisel
 // binary itself; here we just hand it an explicit path when the @letary/chisel package is present,
 // and point it at the SDK *source* tree chisel compiles from:
 //   1. the `lecodes-sdk` package when it resolves — the npm install's dependency, or in the core
-//      workspace the live packages/sdk (so an SDK edit is picked up with no re-vendoring);
+//      workspace the live sdk (so an SDK edit is picked up with no re-vendoring);
 //   2. else the copy vendored beside the standalone binary (runtime/sdk/, scripts/vendor-runtime.ts
 //      --sdk) — the binary has no node_modules.
 const resolveSdkInject = (): string | null => {
@@ -81,6 +81,9 @@ export type CompileOptions = {
   /** Editor compile: the `EDITOR` global compiles to `true` and `*.editor.ts` plugin files are
    *  bundled in (scene-editor bundles). Default false — production compiles skip them. */
   editor?: boolean
+  /** What the compile has to say that is not an error (a plugin the app uses and app.json does not
+   *  list). */
+  onWarning?: (message: string) => void
 }
 
 /** A warning when auto-detection has several import-graph roots and no main.ts to settle it —
@@ -106,4 +109,9 @@ export const compileProject = (opts: CompileOptions): Promise<string> =>
     minify: opts.minify,
     sourcemap: opts.sourcemap,
     editor: opts.editor,
+    onWarning: opts.onWarning,
   })
+
+/** Re-exported so the CALLERS that stage files next to the bundle name them the way the bundle asks
+ *  for them (see localAssetNames in the SDK compile — two packs shipping SM_Sign_01.glb). */
+export { localAssetNames }

package/src/compile/sceneCompile.ts

@@ -4,8 +4,7 @@ import { join } from "node:path"
 import type { Manifest } from "../project/manifest"
 import { scanLocal } from "../project/localFiles"
 import { loadIgnore } from "../project/ignore"
-import { distRoot } from "../hosts/distRoot"
-import { CliError, warnErr } from "../cli"
+import { warnErr } from "../cli"
 import { compileProject, type CompileEntry } from "./projectCompile"
 import { applyLocalShaders, shadersCacheDir } from "./shaders"
 
@@ -14,8 +13,9 @@ import { applyLocalShaders, shadersCacheDir } from "./shaders"
  * point (the platform backend and the standalone playground are the other two). Reads the project
  * off disk, composes the edit-mode bundle with the SDK's shared `sceneEditorEntries`, and drives it
  * through the CLI's chisel + vendored-SDK pipeline. Deliberately mirrors the playground's in-process
- * closure (scene-editor/src/server/inProcess.ts) field-for-field so every host emits the same
- * bundle — only the file source (disk vs. the folder) and the harness source differ.
+ * closure (lecodes-3d-editor's src/server/inProcess.ts) field-for-field so every host emits the same
+ * bundle — only the file source differs. The harness is the editor's: the caller hands in
+ * `sceneHarness()` of the editor package it serves the UI from, so the two are one version.
  *
  *   publicUrl ""  +  resource fileSrc "/project/<rel>"  → the scene server's /project/* mount.
  *   minify:false  — mangling erases class names the inspector matches aspect schemas by.
@@ -29,22 +29,6 @@ const TEXT_EXT = /\.(ts|js|json|svg|txt|md)$/i
 /** Strip scanLocal's leading-slash key convention ("/city.scene.ts" → "city.scene.ts"). */
 const rel = (key: string) => key.replace(/^\//, "")
 
-/**
- * Resolve the scene-editor harness sources (packages/projects/src/scene-editor):
- *   LECODES_SCENE_HARNESS_DIR env → the in-repo dir (monorepo dev), both via the SDK helper, else
- *   the JSON snapshot vendored into the CLI at publish time (runtime/scene-harness.json).
- */
-const resolveHarness = (loadSceneHarness: (dir?: string) => Record<string, string>): Record<string, string> => {
-  const inRepo = join(distRoot, "..", "projects", "src", "scene-editor")
-  try {
-    return loadSceneHarness(existsSync(inRepo) ? inRepo : undefined)
-  } catch {
-    const vendored = join(distRoot, "runtime", "scene-harness.json")
-    if (existsSync(vendored)) return JSON.parse(readFileSync(vendored, "utf8")) as Record<string, string>
-    throw new CliError("scene-editor harness sources not found — reinstall the CLI or set LECODES_SCENE_HARNESS_DIR.")
-  }
-}
-
 export const compileSceneEditor = async (opts: {
   root: string
   /** Null in standalone mode (a bare folder, no cloned project). */
@@ -53,9 +37,11 @@ export const compileSceneEditor = async (opts: {
   name: string
   /** Project path of the scene file as the editor sends it ("./city.scene.ts"). */
   scenePath: string
+  /** The editor's harness, module name → source (`sceneHarness()` of lecodes-3d-editor/server). */
+  harness: Record<string, string>
 }): Promise<{ js: string | null, error?: string }> => {
   const { root, scenePath } = opts
-  const { loadSceneHarness, sceneEditorEntries, sceneImportsOf, SCENE_ENTRY_PATH } = await import("lecodes-sdk/compile")
+  const { sceneEditorEntries, sceneImportsOf, SCENE_ENTRY_PATH } = await import("lecodes-sdk/compile")
 
   const entries: CompileEntry[] = []
   const scan = scanLocal(root, { ignore: loadIgnore(root), tracked: new Set(Object.keys(opts.manifest?.files ?? {})) })
@@ -101,7 +87,7 @@ export const compileSceneEditor = async (opts: {
     return { js: null, error: `Scene file not found: ${scene}` }
   }
   const paths = entries.map((e) => e.path)
-  entries.push(...sceneEditorEntries(scene, resolveHarness(loadSceneHarness), paths, sceneImportsOf(sceneEntry.text ?? "", scene, paths)))
+  entries.push(...sceneEditorEntries(scene, opts.harness, paths, sceneImportsOf(sceneEntry.text ?? "", scene, paths)))
 
   try {
     const js = await compileProject({

package/src/declarations/lecodes-3d-editor.d.ts

@@ -24,6 +24,10 @@ declare module "lecodes-3d-editor/server" {
 
   export function startSceneServer(options: SceneServerOptions): Promise<SceneServer>
 
+  /** The editor's harness — its half that runs in the scene's world — as module name → source:
+   *  what the compile closure hands to the SDK's `sceneEditorEntries`. */
+  export function sceneHarness(): Record<string, string>
+
   /* The asset-preview cache (server/previewCache.ts) — `lecodes thumbs` writes into the same
    * `.lecodes/preview/<asset>.<hash>.png` layout the editor reads. */
 

package/src/declarations/lecodes-assets.d.ts

@@ -1,6 +1,6 @@
 // Types for the optional `lecodes-assets` package's CLI entry (lazy-loaded by the `assets` command).
 // The real package is installed separately; this lets the dynamic import typecheck without it
-// present. Keep in sync with packages/lecodes-assets/src/cli.ts.
+// present. Keep in sync with tools/assets/src/cli.ts.
 declare module "lecodes-assets/cli" {
   /** Runs `convert | probe | doctor` with the given argv (sub-command first). Resolves to the exit code. */
   export function runAssetsCli(argv: string[]): Promise<number>

package/src/declarations/{lecodes-renderer.d.ts → lecodes-headless.d.ts}

@@ -1,7 +1,7 @@
-// Types for the optional `lecodes-renderer` package's node headless entry (lazy-loaded by the
+// Types for the optional `lecodes-headless` package's node headless entry (lazy-loaded by the
 // `render` command). The real package is installed separately; this lets the dynamic import
 // typecheck without it present.
-declare module "lecodes-renderer/headless" {
+declare module "lecodes-headless/headless" {
   export type RenderOptions = {
     width?: number
     height?: number
@@ -21,7 +21,7 @@ declare module "lecodes-renderer/headless" {
     safeArea?: [number, number, number, number]
     /** Receive the project's console.* output (unset → swallowed). */
     onConsole?: (level: string, text: string) => void
-    /** Canned `_creatorUtils.fetch` responses (URL pattern → { status?, json?, text? }); they beat
+    /** Canned `_creatorFetch.fetch` responses (URL pattern → { status?, json?, text? }); they beat
      *  every other fetch path, including waitNetwork. */
     fixtures?: Fixtures
   }

package/src/dev/clientTemplates.ts

@@ -7,9 +7,9 @@
  *   header says `// gl: disable`, so the app launcher creates no engine for it.
  *
  * - DEV_PRELUDE_JS — plain JS appended VERBATIM to every bundle the dev server serves (dev.js and
- *   bundle.js alike). It only touches the raw `_creatorUtils` / `_creator` bridge — no SDK — so it
- *   can ride along any compiled project without duplicating the injected runtime. Each
- *   `_creatorUtils.run()` world therefore carries its own copy: the running world holds the live
+ *   bundle.js alike). It only touches the raw `_creatorFetch` / `_creatorSocket` / `_creatorApp` /
+ *   `_creator` bridge — no SDK — so it can ride along any compiled project without duplicating the
+ *   injected runtime. Each `_creatorApp.run()` world therefore carries its own copy: the running world holds the live
  *   connection; when it loads the next bundle, the NEW world's copy connects and the native
  *   per-world socket teardown closes the old one. On eval error, run()'s rollback keeps the
  *   current world (and its connection) alive, so the reject callback here reports + keeps serving.
@@ -33,6 +33,11 @@ UIScreen([
 
 export const DEV_PRELUDE_JS = `
 ;(function () {
+  // The raw bridges (sdk/src/bridges): fetch's onComplete hands an OWNED handle ({ id }) whose
+  // body is freed when the handle is collected — the readers / run take the NUMBER (handle.id).
+  var F = _creatorFetch
+  var S = _creatorSocket
+  var A = _creatorApp
   var ORIGIN = "__DEV_ORIGIN__"
   var BASE = "__DEV_BASE__"
   var TRANSPORT = "__DEV_TRANSPORT__"
@@ -44,12 +49,12 @@ export const DEV_PRELUDE_JS = `
   function post(obj) {
     var text = JSON.stringify(obj)
     if (TRANSPORT === "ws") {
-      if (wsId !== null) { try { _creatorUtils.websocketSend(wsId, text) } catch (e) {} }
+      if (wsId !== null) { try { S.send(wsId, text) } catch (e) {} }
       return
     }
     try {
-      _creatorUtils.fetch(ORIGIN + BASE + "/log", { method: "POST", body: text, headers: { "content-type": "application/json" } },
-        function (id) { try { _creatorUtils.disposeFetch(id) } catch (e) {} }, function () {})
+      F.fetch(ORIGIN + BASE + "/log", { method: "POST", body: text, headers: { "content-type": "application/json" } },
+        function () {}, function () {})
     } catch (e) {}
   }
 
@@ -80,16 +85,16 @@ export const DEV_PRELUDE_JS = `
   function load(v) {
     if (busy) { queued = v; return }
     busy = true
-    _creatorUtils.fetch(ORIGIN + BASE + "/bundle.js?v=" + v + "&t=" + TRANSPORT, {}, function (id, status) {
+    F.fetch(ORIGIN + BASE + "/bundle.js?v=" + v + "&t=" + TRANSPORT, {}, function (body, status) {
       if (status >= 400) { busy = false; report("bundle fetch: HTTP " + status); return }
       // Same engine bringup the app launcher does for a fresh launch (see desktop initial.ts).
       var head = ""
-      try { head = _creatorUtils.fetchSlice(id, 0, 300) } catch (e) {}
+      try { head = F.slice(body.id, 0, 300) } catch (e) {}
       var preloads = head.match(/\\/\\/ preload: (.+)/)
       if (head.indexOf("// gl:") < 0) {
         try { _creator.createEngine(preloads ? preloads[1].split(";") : []) } catch (e) { report("createEngine: " + String(e)) }
       }
-      _creatorUtils.run(id, function (err) {
+      A.run(body.id, function (err) {
         // Eval failed → native rollback kept THIS world (and its connection) alive. Keep serving.
         busy = false
         report(err)
@@ -109,9 +114,9 @@ export const DEV_PRELUDE_JS = `
     var url = ORIGIN.replace("http", "ws") + BASE + "/ws"
     var open = function () {
       try {
-        wsId = _creatorUtils.websocketOpen(url, function (channel, data) {
+        wsId = S.open(url, function (channel, data) {
           if (channel === "open") {
-            try { _creatorUtils.websocketSend(wsId, JSON.stringify({ type: "hello", v: V })) } catch (e) {}
+            try { S.send(wsId, JSON.stringify({ type: "hello", v: V })) } catch (e) {}
           } else if (channel === "message") {
             onServer(data)
           } else if (channel === "close" || channel === "error") {
@@ -124,10 +129,9 @@ export const DEV_PRELUDE_JS = `
     open()
   } else {
     var poll = function () {
-      _creatorUtils.fetch(ORIGIN + BASE + "/version", {}, function (id, status) {
+      F.fetch(ORIGIN + BASE + "/version", {}, function (body, status) {
         var v = null
-        try { v = _creatorUtils.fetchToJson(id).v } catch (e) {}
-        try { _creatorUtils.disposeFetch(id) } catch (e) {}
+        try { v = F.toJson(body.id).v } catch (e) {}
         setTimeout(poll, 700)
         if (status < 400 && typeof v === "number" && v !== V && !busy) load(v)
       }, function () { setTimeout(poll, 1500) })