lecodes-cli 0.19.0 → 0.20.0

package/src/compile/collect.ts

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs"
+import { basename } from "node:path"
+import type { Project } from "../api"
+import type { Manifest } from "../manifest"
+import { classifyKind, scanLocal } from "../localFiles"
+import { loadIgnore } from "../ignore"
+import { buildPaths } from "../project"
+import type { CompileEntry } from "./projectCompile"
+
+/*
+ * Builds the compile input from the working tree + the project's server metadata: code/.svg/scene
+ * content comes from local files (fresh); binary & shader URLs come from the server (matched by
+ * path). Local-only / locally-changed binaries and shaders are reported as warnings. Shared by
+ * `preview` and `render`. Untracked files matching .lecodesignore are skipped — same contract as
+ * `status`/`push` (tracked files are always in), so a generated `ios/` shell never leaks in here.
+ */
+export const collectEntries = (
+  root: string, manifest: Manifest, project: Project,
+  opts: { /** Warn about resources with no server URL yet (default true; shell compiles bundle them instead). */ warnMissingUrl?: boolean } = {},
+): { entries: CompileEntry[], warnings: string[] } => {
+  const pathById = buildPaths(project.assets)
+  const serverByPath = new Map<string, { fileSrc?: string, shaders?: { platform: string, src: string }[] }>()
+  for (const asset of project.assets) {
+    if (asset.type === "folder") continue
+    serverByPath.set(pathById.get(asset.id)!, { fileSrc: asset.file?.src ?? undefined, shaders: asset.shaders ?? [] })
+  }
+
+  const entries: CompileEntry[] = []
+  const warnings: string[] = []
+  const scan = scanLocal(root, { ignore: loadIgnore(root), tracked: new Set(Object.keys(manifest.files)) })
+  for (const file of scan.files) {
+    const type = manifest.files[file.path]?.type ?? classifyKind(basename(file.path))
+    if (type === "resource") {
+      const src = serverByPath.get(file.path)?.fileSrc
+      if (!src && (opts.warnMissingUrl ?? true)) warnings.push(`No server URL for ${file.path} — push it so its URL resolves.`)
+      entries.push({ path: file.path, type, fileSrc: src, absPath: file.absPath })
+    } else if (type === "shader") {
+      const shaders = serverByPath.get(file.path)?.shaders
+      if (!shaders?.length) warnings.push(`No compiled shader for ${file.path} — push it to compile the shader.`)
+      entries.push({ path: file.path, type, shaders })
+    } else {
+      entries.push({ path: file.path, type, text: readFileSync(file.absPath, "utf8") })
+    }
+  }
+  return { entries, warnings }
+}

package/src/compile/collectLocal.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs"
+import { basename } from "node:path"
+import type { Manifest } from "../manifest"
+import { classifyKind, scanLocal } from "../localFiles"
+import { loadIgnore } from "../ignore"
+import type { CompileEntry } from "./projectCompile"
+
+/*
+ * Builds the compile input for `lecodes dev` from the working tree ALONE — no server round-trip,
+ * no login. Binary resources compile to dev-server URLs (`<assetBase>/<path>`, served straight
+ * from the working tree), so the bundle works fully offline. Shaders carry their absPath so a
+ * caller that compiles them locally (the dev server's applyLocalShaders pass, via matc) can fill
+ * in the artifacts; callers that don't pass `localShaders` keep the old degradation — an empty
+ * artifact list + a push-once warning (same as `collectEntries` reports for unpushed shaders).
+ */
+export const collectLocalEntries = (
+  root: string, manifest: Manifest | null, assetBase: string,
+  opts: { localShaders?: boolean } = {},
+): { entries: CompileEntry[], warnings: string[] } => {
+  const entries: CompileEntry[] = []
+  const warnings: string[] = []
+  const scan = scanLocal(root, { ignore: loadIgnore(root), tracked: new Set(Object.keys(manifest?.files ?? {})) })
+  for (const file of scan.files) {
+    const type = manifest?.files[file.path]?.type ?? classifyKind(basename(file.path))
+    if (type === "resource") {
+      entries.push({ path: file.path, type, fileSrc: assetBase + encodeURI(file.path), absPath: file.absPath })
+    } else if (type === "shader") {
+      if (!opts.localShaders) {
+        warnings.push(`${file.path}: shaders compile on the server — push the project once for shaders to work in dev mode.`)
+      }
+      entries.push({ path: file.path, type, shaders: [], absPath: file.absPath })
+    } else {
+      entries.push({ path: file.path, type, text: readFileSync(file.absPath, "utf8") })
+    }
+  }
+  return { entries, warnings }
+}

package/src/compile/designCompile.ts

@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs"
+import { basename } from "node:path"
+import type { Manifest } from "../manifest"
+import { classifyKind, scanLocal } from "../localFiles"
+import { loadIgnore } from "../ignore"
+import { compileProject, type CompileEntry } from "./projectCompile"
+import { applyAssetIcons } from "./assetIcons"
+import { applyProjectFonts } from "./fonts"
+
+/*
+ * Per-screen compile for `lecodes design`. A design screen file default-exports either an
+ * already-computed UIScreen (a value) or a `(state) => UIScreen` function (screen states); the
+ * virtual entry imports it, invokes the function form for the requested state, and opens the result.
+ * Bundled through the normal project pipeline. Fully local — no server round-trip:
+ *   assets "server" → resource URLs are `/project/<path>` (the design dev server serves them)
+ *   assets "disk"   → `lecodesfile://<abs-path>` (the headless renderer reads them off disk)
+ */
+
+export type DesignAssetMode = "server" | "disk"
+
+// Must match lecodes-renderer's LOCAL_ASSET_SCHEME (headless/index.ts) — same as `lecodes render`.
+const LOCAL_ASSET_SCHEME = "lecodesfile://"
+
+export const compileDesignScreen = async (opts: {
+  root: string
+  /** Null in standalone mode (no cloned project): kinds come from filenames alone. */
+  manifest: Manifest | null
+  /** Project display name (compile metadata). */
+  name: string
+  /** Absolute path of the design folder — where `assetIcon()` icons are vendored (assets/icons/,
+   *  icons.lock.json, ICON-NOTICES.md). */
+  designDir: string
+  /** The design folder as a project key ("/design"). */
+  designKey: string
+  /** Screen id = filename without .ts ("login"). */
+  screenId: string
+  /** State to render for a function-of-state screen. Omit for the canonical state (the export's
+   *  param default). Ignored by a value-export screen. */
+  state?: string
+  assets: DesignAssetMode
+}): Promise<string> => {
+  const { root, manifest, designDir, designKey, screenId, state } = opts
+
+  const entries: CompileEntry[] = []
+  const scan = scanLocal(root, { ignore: loadIgnore(root), tracked: new Set(Object.keys(manifest?.files ?? {})) })
+  for (const file of scan.files) {
+    const type = manifest?.files[file.path]?.type ?? classifyKind(basename(file.path))
+    if (type === "resource") {
+      entries.push({
+        path: file.path,
+        type,
+        fileSrc: opts.assets === "disk" ? encodeURIComponent(file.absPath) : encodeURI(file.path),
+        absPath: file.absPath,
+      })
+    } else if (type === "shader") {
+      entries.push({ path: file.path, type, shaders: [] }) // UI-only render — no shader artifacts needed
+    } else {
+      entries.push({ path: file.path, type, text: readFileSync(file.absPath, "utf8") })
+    }
+  }
+
+  // The virtual entry lives in the design folder so `./screens/…` and the screen's own `../shared/…`
+  // imports resolve naturally. It never touches disk.
+  // A function-of-state export is invoked with the chosen state (canonical = a bare call, using the
+  // param's default); a value export is used as-is. Either way we .open() the resulting screen.
+  const invoke = state !== undefined ? `screen(${JSON.stringify(state)})` : "screen()"
+  const entryPath = `${designKey}/.screen-entry.ts`
+  entries.push({
+    path: entryPath,
+    type: "text",
+    text: `import screen from "./screens/${screenId}"\n`
+      + `const __screen = typeof screen === "function" ? ${invoke} : screen\n`
+      + `__screen.open()\n`,
+  })
+
+  // Resolve any `assetIcon('pack:name')` calls: vendor the SVGs into the design folder and rewrite
+  // each call to an inline SvgSource(...) so the bundle renders offline (no network at render time).
+  await applyAssetIcons(entries, designDir)
+
+  // Resolve `font(...)` calls the same way: registry faces vendor into the design folder
+  // (assets/fonts/ + fonts.lock.json) and each call becomes its family name plus a generated
+  // registration module — offline after the first compile, board and headless render alike.
+  await applyProjectFonts(entries, {
+    mode: "vendor",
+    root,
+    vendorDir: designDir,
+    vendorPrefix: designKey,
+    makeResourceEntry: (path, absPath) => ({
+      path,
+      type: "resource",
+      fileSrc: opts.assets === "disk" ? encodeURIComponent(absPath) : encodeURI(path),
+      absPath,
+    }),
+  })
+
+  return compileProject({
+    entries,
+    name: opts.name,
+    publicUrl: opts.assets === "disk" ? LOCAL_ASSET_SCHEME : "/project",
+    entryOverride: entryPath,
+    header: false,
+    format: "iife",
+  })
+}

package/src/compile/fonts.ts

@@ -0,0 +1,156 @@
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { applyFontMacro, buildFontsHeaderValue, fontRegistryBase, type FontFaceRef } from "lecodes-sdk/compile"
+import type { CompileEntry } from "./projectCompile"
+
+/*
+ * The CLI side of the `font()` compile macro (docs/font-system-plan.md): the sdk core scans and
+ * rewrites; this wrapper decides where face FILES come from per compile mode and keeps the vendor
+ * bookkeeping (fonts.lock.json + FONT-NOTICES.md, mirroring assetIcons.ts):
+ *
+ *   cdn    — server-backed compiles: registry faces stay remote (baked CDN URLs), only
+ *            project-file fonts touch entries. No disk writes.
+ *   vendor — local/dev/render/design compiles: registry faces are downloaded once into
+ *            <vendorDir>/assets/fonts/ (offline after that) and pushed as resource entries, so
+ *            they ride the normal asset pipeline (dev URLs / `id:`+fetchLocal / lecodesfile://).
+ *
+ * Returns the `// fonts:` header value (boot faces a host prefetches + holds first paint for),
+ * or undefined when the project uses no fonts.
+ */
+
+type LicenseEntry = { spdx: string, title: string, url: string, attribution: string | null, modifiedNotice: boolean }
+type LockFace = { id: string, family: string, weight: number, italic: boolean, hash: string, spdx: string, path: string }
+type Lock = { registry: string, faces: Record<string, LockFace>, families: Record<string, LicenseEntry> }
+
+export type ProjectFontsOptions = {
+  mode: "cdn" | "vendor"
+  /** Project root (abs) — fallback for reading project-font files without an absPath. */
+  root: string
+  /** vendor: where assets/fonts/, fonts.lock.json and FONT-NOTICES.md live (abs). */
+  vendorDir?: string
+  /** vendor: leading-slash entries prefix for vendorDir ("" = project root, "/design" = a design folder). */
+  vendorPrefix?: string
+  /** vendor: shape a resource entry for a vendored face the caller's way (fileSrc convention). */
+  makeResourceEntry?: (path: string, absPath: string) => CompileEntry
+  /** Registry override (URL or a local directory with the registry layout). */
+  registry?: string
+  /** Absolute-URL prefix of the compile (URL modes) — used for the header's entry-face URLs. */
+  publicUrl?: string
+}
+
+export const applyProjectFonts = async (entries: CompileEntry[], opts: ProjectFontsOptions): Promise<string | undefined> => {
+  const registry = (opts.registry ?? fontRegistryBase()).replace(/\/+$/, "")
+  const byPath = () => new Map(entries.map((e) => [e.path.replace(/^\//, ""), e]))
+
+  const faces = await applyFontMacro(entries, {
+    mode: opts.mode,
+    registryBase: registry,
+    readBytes: (entryPath) => {
+      const entry = byPath().get(entryPath)
+      const abs = entry?.absPath ?? join(opts.root, entryPath)
+      try { return new Uint8Array(readFileSync(abs)) } catch { return null }
+    },
+    vendorFace: opts.mode === "vendor"
+      ? async (face) => {
+          const vendorDir = opts.vendorDir ?? opts.root
+          const rel = `assets/fonts/${face.fileName}`
+          const abs = join(vendorDir, rel)
+          const entryPath = `${opts.vendorPrefix ?? ""}/${rel}`
+          if (!existsSync(abs)) await downloadFace(registry, vendorDir, face, rel, abs)
+          if (!byPath().has(entryPath.replace(/^\//, ""))) {
+            entries.push(opts.makeResourceEntry?.(entryPath, abs) ?? { path: entryPath, type: "resource", absPath: abs })
+          }
+          return entryPath
+        }
+      : undefined,
+  })
+  if (faces.length === 0) return undefined
+
+  return buildFontsHeaderValue(faces, (path) => {
+    if (!opts.publicUrl || !/^https?:/i.test(opts.publicUrl)) return null
+    const fileSrc = byPath().get(path.replace(/^\//, ""))?.fileSrc
+    return fileSrc ? opts.publicUrl + fileSrc : null
+  }) || undefined
+}
+
+// ---- vendoring (registry → assets/fonts + lock + notices; mirrors assetIcons.ts) ----------------
+
+const isHttp = (s: string) => /^https?:/i.test(s)
+const sha12 = (b: Uint8Array) => createHash("sha256").update(b).digest("hex").slice(0, 12)
+const registryHome = (registry: string) => registry.replace(/\/v\d+$/, "")
+
+const readRegistry = async (registry: string, rel: string): Promise<Uint8Array | null> => {
+  if (isHttp(registry)) {
+    const res = await fetch(`${registry}/${rel}`)
+    return res.ok ? new Uint8Array(await res.arrayBuffer()) : null
+  }
+  try { return new Uint8Array(readFileSync(join(registry, rel))) } catch { return null }
+}
+
+const readLock = (path: string): Lock | null => {
+  try {
+    const lock = JSON.parse(readFileSync(path, "utf8")) as Lock
+    if (lock && typeof lock === "object" && lock.faces && lock.families) return lock
+  } catch { /* absent or corrupt → start fresh */ }
+  return null
+}
+
+/** Stable serialization: keys sorted, no timestamp — same inputs, byte-identical output. */
+const serializeLock = (lock: Lock): string => {
+  const sortKeys = <T>(rec: Record<string, T>): Record<string, T> =>
+    Object.fromEntries(Object.keys(rec).sort().map((k) => [k, rec[k]]))
+  return JSON.stringify({ registry: lock.registry, faces: sortKeys(lock.faces), families: sortKeys(lock.families) }, null, 2) + "\n"
+}
+
+const renderNotices = (lock: Lock): string => {
+  const ids = [...new Set(Object.values(lock.faces).map((f) => f.id))].sort()
+  const lines = [
+    "# Font attribution & notices",
+    "",
+    "Fonts vendored from the font registry via `font(...)`. Keep this file in your repo / product.",
+    "",
+  ]
+  for (const id of ids) {
+    const l = lock.families[id]
+    if (!l) continue
+    let note = `- **${l.title || id}** — ${l.spdx}${l.url ? ` — ${l.url}` : ""}`
+    if (l.attribution) note += `\n  - **Attribution required:** ${l.attribution}`
+    lines.push(note)
+  }
+  lines.push("")
+  return lines.join("\n")
+}
+
+const writeIfChanged = (path: string, text: string) => {
+  try { if (readFileSync(path, "utf8") === text) return } catch { /* absent → write */ }
+  writeFileSync(path, text)
+}
+
+const downloadFace = async (
+  registry: string, vendorDir: string,
+  face: { id: string, family: string, weight: number, italic: boolean, fileName: string },
+  rel: string, abs: string,
+): Promise<void> => {
+  const licRaw = await readRegistry(registry, "licenses.json")
+  if (!licRaw) throw new Error(`font: can't reach the font registry (${registry}). Check your connection, or set LECODES_FONT_REGISTRY.`)
+  const licenses = JSON.parse(new TextDecoder().decode(licRaw)) as Record<string, LicenseEntry>
+  const lic = licenses[face.id]
+  if (!lic) throw new Error(`font("${face.id}"): the registry has no license entry for this family — it may not be published yet. Browse ${registryHome(registry)}.`)
+
+  const bytes = await readRegistry(registry, `${face.id}/${face.fileName}`)
+  if (!bytes) throw new Error(`font("${face.id}"): face "${face.fileName}" not found in the registry (${registryHome(registry)}).`)
+
+  mkdirSync(dirname(abs), { recursive: true })
+  writeFileSync(abs, bytes)
+
+  const lockPath = join(vendorDir, "fonts.lock.json")
+  const lock: Lock = readLock(lockPath) ?? { registry, faces: {}, families: {} }
+  lock.registry = registry
+  lock.faces[`${face.id}@${face.weight}${face.italic ? "i" : ""}`] =
+    { id: face.id, family: face.family, weight: face.weight, italic: face.italic, hash: sha12(bytes), spdx: lic.spdx, path: rel }
+  lock.families[face.id] = lic
+  writeIfChanged(lockPath, serializeLock(lock))
+  // Attribution is fail-closed: notices always reflect the vendored families (write throws → build fails).
+  writeIfChanged(join(vendorDir, "FONT-NOTICES.md"), renderNotices(lock))
+}

package/src/compile/headlessBundle.ts

@@ -0,0 +1,129 @@
+import { getProject } from "../api"
+import { loadConfig, requireApiUrl, requireToken } from "../config"
+import { findProjectRoot, readManifest, type Manifest } from "../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 { flagBool, flagStr, note, type Args } from "../util"
+
+/*
+ * 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
+}
+
+/** Compile the local project for a headless run (honors --entry / --public-url / --remote-assets). */
+export const compileHeadlessBundle = async (args: Args, opts: { screen?: ScreenTarget } = {}): 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 = flagStr(args, "public-url")
+  // A local (server-less) project has no remote asset URLs — it always reads from disk.
+  const useLocalAssets = manifest ? (!publicUrlFlag && !flagBool(args, "remote-assets")) : 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 (flagBool(args, "remote-assets") || 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 ?? flagStr(args, "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 && !flagBool(args, "wait-network")) {
+    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

@@ -0,0 +1,21 @@
+import { extractInlineSourceMap, mapNamedFileStack } from "lecodes-viewer-lite/src/sourcemapError"
+
+/*
+ * De-minify native (QuickJS) stack traces in a desktop host's output.
+ *
+ * The host evaluates the compiled bundle as one file, so every frame it prints reads
+ * `at e$ (module.js:5:51631)` — a minified column offset nobody can act on. The bundle carries its
+ * map inline (`//# lecodesMap=`, see sdk/compile/sourcemap.ts) and the CLI holds the very string it
+ * staged, so it can rewrite those frames into `main.ts:92:23` on the way through. The map consumer
+ * lives in viewer-lite (the preview needs the same decoding for its `new Function` frames).
+ */
+
+/** quickjs names the bundle "module.js" when a project world is `run()` into a fresh context
+ *  (creatorUtilsHandler) — "main.js" is the host's own boot eval, whose frames aren't ours. */
+const BUNDLE_FILENAME = "module.js"
+
+/** A rewriter for one bundle's output, or `null` when it carries no map (nothing to do). */
+export const makeStackDemangler = (bundleJs: string): ((chunk: string) => string) | null => {
+  const map = extractInlineSourceMap(bundleJs)
+  return map ? (chunk: string) => mapNamedFileStack(chunk, map, BUNDLE_FILENAME) : null
+}

package/src/compile/projectCompile.ts

@@ -0,0 +1,109 @@
+import { existsSync } from "node:fs"
+import { createRequire } from "node:module"
+import { dirname, join } from "node:path"
+import type { FileKind } from "../manifest"
+import { distRoot } from "../distRoot"
+import { compileProject as sdkCompileProject, detectEntry, scanModulesChisel, 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);
+//   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 => {
+  try { return createRequire(import.meta.url).resolve("lecodes-sdk/inject") } catch { /* no package: standalone */ }
+  const vendored = join(distRoot, "runtime", "sdk", "inject.ts")
+  return existsSync(vendored) ? vendored : null
+}
+const sdkInject = resolveSdkInject()
+if (sdkInject) process.env.LECODES_SDK_INJECT = sdkInject
+
+/** Absolute path to the chisel binary: env override → the @letary/chisel npm package → a chisel
+ *  binary shipped next to the executable (standalone binary distribution). Null when none found. */
+const resolveChiselBin = (): string | null => {
+  if (process.env.LECODES_CHISEL_BIN) return process.env.LECODES_CHISEL_BIN
+  try {
+    const fromPkg = createRequire(import.meta.url)("@letary/chisel").binaryPath()
+    if (fromPkg) return fromPkg
+  } catch {
+    // @letary/chisel (or its platform binary) not installed — try the exe-adjacent copy
+  }
+  const local = join(dirname(process.execPath), process.platform === "win32" ? "chisel.exe" : "chisel")
+  return existsSync(local) ? local : null
+}
+
+const chiselBin = resolveChiselBin()
+if (chiselBin) process.env.LECODES_CHISEL_BIN = chiselBin
+
+export type CompileEntry = {
+  path: string
+  type: FileKind
+  /** Source text for code / .svg / scene files. */
+  text?: string
+  /** Server src for a binary resource (e.g. "/uploads/x.png"); prefixed with publicUrl. */
+  fileSrc?: string
+  /** Under `localAssets`: keep THIS resource in the URL form anyway (app.json resources.remote). */
+  remote?: boolean
+  /** Absolute path of the local file (resources + shaders) — `render` resolves assets from disk
+   *  with it; the dev server's local shader compile (compile/shaders.ts) reads .mat sources. */
+  absPath?: string
+  /** Compiled-shader artifacts (platform + src); the first drives the per-backend URL. */
+  shaders?: { platform: string, src: string }[]
+  /** `shaders` are LOCAL files staged next to the bundle — the module compiles to a fetchLocal
+   *  lookup instead of a URL (set by compile/shaders.ts in `local` mode). */
+  shadersLocal?: boolean
+}
+
+export type CompileOptions = {
+  entries: CompileEntry[]
+  name: string
+  publicUrl: string
+  entryOverride?: string
+  header?: boolean
+  /** `// fonts:` header payload (from applyProjectFonts — the font() macro pass). */
+  fontsHeader?: string
+  /** `// icons:` header payload (from applyAppAssetIcons — the assetIcon() macro pass). */
+  iconsHeader?: string
+  /** Output format: "esm" (default, shipped) or "iife" (self-running, for the local renderer). */
+  format?: "esm" | "iife"
+  /** Resolve `asset()` resources via the host's `fetchLocal` (local file → systemId) instead of a
+   *  `publicUrl` URL — for a host with no asset server (e.g. the desktop native runtime). */
+  localAssets?: boolean
+  /** Override minification (default on). Scene-editor bundles pass `false`: mangling erases class
+   *  names, which the inspector matches aspect schemas by (describeAspect().className). */
+  minify?: boolean
+  /** Generate + inline a source map (default true). `false` gives a smaller bundle whose runtime
+   *  errors report generated positions only. */
+  sourcemap?: boolean
+  /** 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
+}
+
+/** A warning when auto-detection has several import-graph roots and no main.ts to settle it —
+ *  the pick still works, but the developer should make the entry explicit. Null when unambiguous.
+ *  Callers skip this when an explicit --entry / entryOverride is in play. */
+export const ambiguousEntryWarning = (entries: { path: string, type?: string, text?: string }[]): string | null => {
+  const { entry, roots } = detectEntry(entries, scanModulesChisel)
+  if (!entry || roots.length < 2 || roots.includes(ENTRY_CONVENTION)) return null
+  return `Ambiguous entrypoint: nothing imports ${roots.join(", ")} — picked ${entry}. Rename your entry to main.ts (or pass --entry).`
+}
+
+export const compileProject = (opts: CompileOptions): Promise<string> =>
+  sdkCompileProject({
+    entries: opts.entries.map((e) => ({ path: e.path, type: e.type as any, text: e.text, fileSrc: e.fileSrc, remote: e.remote, shaders: e.shaders, shadersLocal: e.shadersLocal })),
+    name: opts.name,
+    publicUrl: opts.publicUrl,
+    entryOverride: opts.entryOverride,
+    header: opts.header,
+    fontsHeader: opts.fontsHeader,
+    iconsHeader: opts.iconsHeader,
+    format: opts.format,
+    localAssets: opts.localAssets,
+    minify: opts.minify,
+    sourcemap: opts.sourcemap,
+    editor: opts.editor,
+  })