lecodes-cli 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Clone, edit and push LeCodes projects from your machine.",
   "type": "module",
   "license": "MIT",
@@ -21,23 +21,28 @@
   },
   "scripts": {
     "vendor-runtime": "bun scripts/vendor-runtime.ts",
-    "build": "bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-renderer --banner=\"#!/usr/bin/env node\"",
+    "build": "bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-renderer --external lecodes-design --banner=\"#!/usr/bin/env node\"",
     "typecheck": "tsc --noEmit",
     "dev": "bun run src/index.ts",
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@letary/chisel": "^0.1.2"
+    "@letary/chisel": "^0.2.0"
   },
   "peerDependencies": {
-    "lecodes-renderer": "^0.3.0"
+    "lecodes-design": "^0.1.0",
+    "lecodes-renderer": "^0.4.0"
   },
   "peerDependenciesMeta": {
+    "lecodes-design": {
+      "optional": true
+    },
     "lecodes-renderer": {
       "optional": true
     }
   },
   "devDependencies": {
+    "lecodes-design": "workspace:*",
     "lecodes-renderer": "workspace:*",
     "sdk": "workspace:*"
   }

package/runtime/sdk/canvas/Canvas.ts

@@ -21,6 +21,7 @@
 //   new Sprite({ texture: c })          // Canvas is a valid texture source everywhere
 
 import { Texture2D } from "../g2/Texture2D"
+import { File } from "../runtime/fetch"
 
 // Opcodes — MUST stay in sync with docs/canvas-contract.md.
 const OP = {
@@ -30,6 +31,7 @@ const OP = {
   BEGIN_PATH: 14, CLOSE_PATH: 15, MOVE_TO: 16, LINE_TO: 17, QUADRATIC_TO: 18, BEZIER_TO: 19,
   ARC: 20, RECT: 21, ROUND_RECT: 22, FILL: 23, STROKE: 24,
   FILL_RECT: 25, STROKE_RECT: 26, CLEAR_RECT: 27, FILL_TEXT: 28, STROKE_TEXT: 29,
+  DRAW_IMAGE: 30,
 } as const
 
 const ALIGN = { left: 0, center: 1, right: 2, start: 3, end: 4 } as const
@@ -140,6 +142,31 @@ export class Canvas {
   fillText(text: string, x: number, y: number, maxWidth = 0): this { this._cmd.push(OP.FILL_TEXT, this._ref(text), x, y, maxWidth); return this }
   strokeText(text: string, x: number, y: number, maxWidth = 0): this { this._cmd.push(OP.STROKE_TEXT, this._ref(text), x, y, maxWidth); return this }
 
+  // --- images ---
+  /** Blit a `Bitmap` (a snapshot from `toBitmap()`) onto this canvas. All coordinates are LOGICAL —
+   *  including the source sub-rect in the 9-arg form (it's scaled by the bitmap's pixelRatio here).
+   *  Records a DRAW_IMAGE op, so the blit runs at bake time: keep the Bitmap alive until the next
+   *  `update()`/`toBitmap()`/`texture()`. Three browser-style forms:
+   *    drawImage(bmp, dx, dy)                         — whole bitmap at its natural size
+   *    drawImage(bmp, dx, dy, dw, dh)                 — whole bitmap, scaled into dw×dh
+   *    drawImage(bmp, sx, sy, sw, sh, dx, dy, dw, dh) — a sub-rect of the bitmap, scaled into dw×dh */
+  drawImage(img: Bitmap, dx: number, dy: number): this
+  drawImage(img: Bitmap, dx: number, dy: number, dw: number, dh: number): this
+  drawImage(img: Bitmap, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): this
+  drawImage(img: Bitmap, a: number, b: number, c?: number, d?: number, e?: number, f?: number, g?: number, h?: number): this {
+    const pr = img.pixelRatio
+    let sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number
+    if (e === undefined) {                    // (dx, dy) or (dx, dy, dw, dh): the whole bitmap
+      sx = 0; sy = 0; sw = img.pixelWidth; sh = img.pixelHeight
+      dx = a; dy = b; dw = c ?? img.width; dh = d ?? img.height
+    } else {                                  // (sx, sy, sw, sh, dx, dy, dw, dh): a sub-rect (logical → device px)
+      sx = a * pr; sy = b * pr; sw = c! * pr; sh = d! * pr
+      dx = e; dy = f!; dw = g!; dh = h!
+    }
+    this._cmd.push(OP.DRAW_IMAGE, img._surfaceId, sx, sy, sw, sh, dx, dy, dw, dh)
+    return this
+  }
+
   /** Measure `text` in the current font on THIS platform. The one synchronous round-trip. */
   measureText(text: string): CanvasTextMetrics {
     const o = _creatorCanvas.measureText(text, this._font)
@@ -168,6 +195,26 @@ export class Canvas {
     return this
   }
 
+  /** Copy the current pixels into a standalone, immutable `Bitmap` — independent of this canvas, so
+   *  later drawing/`reset()` never touches it. Draw it back with `drawImage()`, export it with
+   *  `toDataURL()`, or use it to "flatten" an ever-growing drawing so re-bakes stay O(1):
+   *    const snap = canvas.toBitmap()
+   *    canvas.reset(); canvas.drawImage(snap, 0, 0)   // one op replaces the whole history
+   *    // …keep drawing on top; snap.destroy() once it's been drawn in. */
+  toBitmap(): Bitmap {
+    return new Bitmap(_creatorCanvas.snapshot(this._bakeSurface()), this.width, this.height, this.pixelRatio)
+  }
+
+  /** Encode the current pixels to an image `File` — 'image/png' (default) or 'image/jpeg'. The File
+   *  is a host buffer handle {id,name,size}: append it to a FormData to upload, load it as a texture
+   *  (`Texture2D.load(file)`), or hand it to a share/save sheet. */
+  toFile(name = "canvas.png", type = "image/png"): Promise<File> {
+    const surfaceId = this._bakeSurface()
+    return new Promise<File>((res, rej) => {
+      _creatorCanvas.toFile(surfaceId, type, (bufferId, size) => res(new File(bufferId, name, size)), rej)
+    })
+  }
+
   destroy(): void {
     if (this._surfaceId) _creatorCanvas.destroySurface(this._surfaceId)
     this._tex2d?.destroy()
@@ -182,3 +229,42 @@ export class Canvas {
 /** Duck-type guard so consumers can accept a Canvas anywhere a texture source is expected. */
 export const isCanvas = (v: unknown): v is Canvas =>
   typeof v === "object" && v !== null && (v as { __canvas?: unknown }).__canvas === true
+
+/** An immutable RGBA8 snapshot of a canvas, produced by `Canvas.toBitmap()`. It owns its own baked
+ *  surface (a copy), so the source canvas can keep drawing or `reset()` without affecting it. Use it
+ *  to stamp/blit back (`canvas.drawImage(bitmap, …)`), to export (`bitmap.toDataURL()`), or as a
+ *  cheap "layer" you composite. Call `destroy()` when done — it holds a native surface. */
+export class Bitmap {
+  readonly __bitmap = true as const
+  /** @internal — a standalone `_creatorCanvas` surface (RGBA8), independent of any Canvas. */
+  readonly _surfaceId: number
+  /** Logical width, matching the Canvas it was captured from (pixelRatio is crispness, not size). */
+  readonly width: number
+  readonly height: number
+  readonly pixelRatio: number
+
+  constructor(surfaceId: number, width: number, height: number, pixelRatio: number) {
+    this._surfaceId = surfaceId
+    this.width = width
+    this.height = height
+    this.pixelRatio = pixelRatio
+  }
+
+  /** Device-pixel dimensions of the stored bitmap (`width * pixelRatio`, rounded). */
+  get pixelWidth(): number { return Math.round(this.width * this.pixelRatio) }
+  get pixelHeight(): number { return Math.round(this.height * this.pixelRatio) }
+
+  /** Encode to an image `File` — 'image/png' (default) or 'image/jpeg'. See `Canvas.toFile`. */
+  toFile(name = "canvas.png", type = "image/png"): Promise<File> {
+    return new Promise<File>((res, rej) => {
+      _creatorCanvas.toFile(this._surfaceId, type, (bufferId, size) => res(new File(bufferId, name, size)), rej)
+    })
+  }
+
+  /** Free the native surface. The bitmap must not be drawn or encoded afterwards. */
+  destroy(): void { _creatorCanvas.destroySurface(this._surfaceId) }
+}
+
+/** Duck-type guard for a Bitmap (see `isCanvas`). */
+export const isBitmap = (v: unknown): v is Bitmap =>
+  typeof v === "object" && v !== null && (v as { __bitmap?: unknown }).__bitmap === true

package/runtime/sdk/compile/aspectMacro.ts

@@ -0,0 +1,42 @@
+// Compile-time injection of an aspect's runtime name. A user aspect carries its accessor name in the
+// (type-erased) generic — `class Health extends Aspect<'health', Sprite> {…}` — so neither the
+// bundler nor the runtime can see it after types are stripped. This pass injects the matching
+// `static aspect = "health"` so node.aspect()/node.health work at runtime, exactly like the SDK's
+// built-in aspects declare it by hand.
+//
+// Runs on PROJECT files only (the SDK's own aspects already declare `static aspect`). Idempotent:
+// skips a class that already declares one. String-based, like assetMacro — no parser dependency.
+
+// `class X extends Aspect<'name', …>` up to the class body's opening brace. Group 3 = the name.
+const ASPECT_RE = /\bclass\s+\w+\s+extends\s+Aspect\s*<\s*(["'])((?:[^"'\\]|\\.)*)\1[^{};]*>\s*\{/g
+
+/** Cheap pre-check so we don't scan files that define no aspects. */
+export const hasAspectExtends = (src: string): boolean => /\bextends\s+Aspect\s*</.test(src)
+
+/** Inject `static aspect = "<name>"` into each `class … extends Aspect<'<name>', …>`. */
+export const injectAspectNames = (src: string): string => {
+  let out = ""
+  let last = 0
+  ASPECT_RE.lastIndex = 0
+  let m: RegExpExecArray | null
+  while ((m = ASPECT_RE.exec(src)) !== null) {
+    const braceEnd = m.index + m[0].length // index just past the opening `{`
+    if (!classBodyDeclaresAspect(src, braceEnd)) {
+      out += src.slice(last, braceEnd) + ` static aspect = ${JSON.stringify(m[2])};`
+      last = braceEnd
+    }
+  }
+  return last === 0 ? src : out + src.slice(last)
+}
+
+/** Does the class body starting just after `from` (its `{`) already declare a `static aspect`? */
+const classBodyDeclaresAspect = (src: string, from: number): boolean => {
+  let depth = 1
+  let i = from
+  for (; i < src.length && depth > 0; i++) {
+    const c = src[i]
+    if (c === "{") depth++
+    else if (c === "}") depth--
+  }
+  return /\bstatic\b[^;{}()=]*\baspect\b/.test(src.slice(from, i))
+}

package/runtime/sdk/compile/assetMacro.ts

@@ -0,0 +1,44 @@
+// Ported from packages/lecodes-cli/src/compile/assetMacro.ts (itself from the backend). The
+// compile-time `asset('./x.png')` macro is desugared into a real import so it goes through the same
+// loader/resolver as a hand-written import.
+
+// Matches `asset("./img.png")` / `asset('./img.png')` calls whose argument is a single string
+// literal (handling escaped chars inside the literal).
+const ASSET_RE = /\basset\(\s*(["'])((?:[^"'\\]|\\.)*)\1\s*\)/g
+
+/** Cheap pre-check so we don't run the regex over every file. */
+export const hasAssetMacro = (src: string): boolean => src.includes("asset(")
+
+/**
+ * Desugars `asset('./path.png')` into the exact import the user could have written by hand.
+ * Identical paths within a file map to one identifier. Only string-literal arguments are supported.
+ */
+export const desugarAssetMacros = (src: string, filePath: string): string => {
+  const byPath = new Map<string, string>()
+  let i = 0
+
+  const out = src.replace(ASSET_RE, (_match, _quote, path) => {
+    let name = byPath.get(path)
+    if (!name) {
+      name = `__asset_${i++}`
+      byPath.set(path, name)
+    }
+    return name
+  })
+
+  if (/\basset\(/.test(out)) {
+    throw new Error(`asset() expects a string literal, found a dynamic argument in: ${filePath}`)
+  }
+
+  if (byPath.size === 0) return src
+
+  const imports = [ ...byPath ]
+    .map(([ path, name ]) => `import ${name} from ${JSON.stringify(path)};`)
+    .join("\n")
+
+  // APPENDED, never prepended. ESM imports hoist, so their position is semantically irrelevant —
+  // but lines added at the TOP would shift every original line, and the bundle's source map would
+  // then disagree with the file the editor shows: inspector jumps and error-overlay stack frames
+  // land N lines off in exactly (and only) the files that use asset(). Appending adds no offsets.
+  return out + "\n" + imports
+}

package/runtime/sdk/compile/bundler.ts

@@ -0,0 +1,173 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import { spawnSync } from "node:child_process"
+import { createRequire } from "node:module"
+import { dirname, join, relative } from "node:path"
+import { fileURLToPath } from "node:url"
+import { desugarAssetMacros, hasAssetMacro } from "./assetMacro"
+import { hasAspectExtends, injectAspectNames } from "./aspectMacro"
+
+/*
+ * The user-project bundler. Project files live in an in-memory map; the whole SDK is delivered via
+ * chisel's `inject` so user code uses globals (Scene, Sprite, toast, …) with NO imports. chisel — the
+ * Rust method-granular bundler (@letary/chisel) — tree-shakes the injected SDK down to what the
+ * project references, including unused class *methods*. It is the only bundler (the esbuild fallback
+ * is gone). Bare imports are a hard error (chisel's resolver enforces it).
+ */
+
+export type MemoryFiles = Record<string, string>
+
+/** Locate the SDK inject entry: an explicit override (LECODES_SDK_INJECT — used by the published CLI,
+ *  which vendors the SDK source), else the source in-repo. chisel needs the SOURCE tree (not a bundle). */
+const resolveInject = (): string => {
+  const override = process.env.LECODES_SDK_INJECT
+  if (override && existsSync(override)) return override
+  const here = dirname(fileURLToPath(import.meta.url)) // …/sdk/src/compile — portable (Node + Bun)
+  const src = join(here, "..", "inject.ts")
+  if (existsSync(src)) return src
+  throw new Error("sdk: could not locate the inject source (LECODES_SDK_INJECT / src/inject.ts)")
+}
+
+const normalize = (path: string): string => {
+  const parts: string[] = []
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue
+    if (part === "..") parts.pop()
+    else parts.push(part)
+  }
+  return "/" + parts.join("/")
+}
+
+// ---- chisel (Rust) bundler -------------------------------------------------------------------
+//
+// chisel is fed an in-memory file map over JSON-stdio: the SDK source under `/__sdk/…` (injected via
+// `/__sdk/inject.ts`), the project files at their own paths, and a `define` map. It does
+// method-granular tree-shaking + (when minify is on) compress + mangle. Assets/shaders/svg reach it
+// as `asset()` macros desugared to default imports; aspect names are injected as `static aspect`.
+
+const CHISEL_DEFINE: Record<string, string> = { RAD2DEG: "57.29577951308232", DEG2RAD: "0.017453292519943295" }
+
+// Methods the native host invokes by name have no in-bundle caller, so method-DCE can't see them.
+// The SDK prefixes its framework / host-facing methods with `_` (`_emitTouchStart`, `_emitClick`,
+// `_onAnimationComplete`, `_emitAnim`, …), so keep every underscore-prefixed method on classes that survive.
+const CHISEL_KEEP = [ "_*" ]
+
+/** The SDK source root (parent of `inject.ts`). chisel needs the source tree, not a prebuilt bundle. */
+const resolveSdkSrc = (): string => {
+  const inject = resolveInject()
+  if (!inject.endsWith("inject.ts")) {
+    throw new Error(`chisel needs the SDK source tree (src/inject.ts); got ${inject}. Set LECODES_SDK_INJECT to the source.`)
+  }
+  return dirname(inject)
+}
+
+const isSdkSource = (path: string) =>
+  /\.[tj]s$/.test(path) && !path.endsWith(".d.ts") &&
+  !path.includes("/compile/") && !path.includes("/tests/") && !path.includes("/__tests__/")
+
+// The SDK tree doesn't change within a process — read it once.
+const sdkFilesCache = new Map<string, MemoryFiles>()
+const collectSdkFiles = (sdkSrc: string): MemoryFiles => {
+  const cached = sdkFilesCache.get(sdkSrc)
+  if (cached) return cached
+  const out: MemoryFiles = {}
+  const walk = (dir: string) => {
+    for (const name of readdirSync(dir)) {
+      const p = join(dir, name)
+      if (statSync(p).isDirectory()) walk(p)
+      else if (isSdkSource(p)) out["/__sdk/" + relative(sdkSrc, p).split("\\").join("/")] = readFileSync(p, "utf8")
+    }
+  }
+  walk(sdkSrc)
+  sdkFilesCache.set(sdkSrc, out)
+  return out
+}
+
+/** Locate the chisel binary: an explicit override (LECODES_CHISEL_BIN), else the prebuilt binary from
+ *  the @letary/chisel npm package (which resolves the platform via optional @letary/chisel-<platform>). */
+const resolveChiselBin = (): string => {
+  const override = process.env.LECODES_CHISEL_BIN
+  if (override) {
+    if (existsSync(override)) return override
+    throw new Error(`LECODES_CHISEL_BIN points at a missing file: ${override}`)
+  }
+  try {
+    const bin = createRequire(import.meta.url)("@letary/chisel").binaryPath() as string | null
+    if (bin && existsSync(bin)) return bin
+  } catch { /* @letary/chisel (or its platform binary) not installed */ }
+  throw new Error("chisel binary not found. Install @letary/chisel, or set LECODES_CHISEL_BIN.")
+}
+
+const bundleProjectChisel = async (
+  entrypoint: string,
+  files: MemoryFiles,
+  format: "esm" | "iife",
+  sourcemap: boolean,
+): Promise<{ code: string, map: string | null }> => {
+  const entry = normalize(entrypoint)
+  // Per-file source transforms (project files only — SDK aspects declare their own `static aspect`):
+  //  - desugar `asset('./x')` → a default import that resolves to the synthetic asset module
+  //  - inject `static aspect = '<name>'` from `class … extends Aspect<'<name>', …>`
+  const projFiles: MemoryFiles = {}
+  for (const [ k, v ] of Object.entries(files)) {
+    const path = normalize(k)
+    let src = v
+    if (/\.[tj]sx?$/.test(path)) {
+      if (hasAssetMacro(src)) src = desugarAssetMacros(src, path)
+      if (hasAspectExtends(src)) src = injectAspectNames(src)
+    }
+    projFiles[path] = src
+  }
+  if (!projFiles[entry]) throw new Error(`Entrypoint not found: ${entry}`)
+
+  const sdkFiles = collectSdkFiles(resolveSdkSrc())
+  const minify = process.env.LECODES_CHISEL_MINIFY !== "0" // shipped bundles minify by default
+  const input = JSON.stringify({
+    files: { ...sdkFiles, ...projFiles },
+    entry,
+    inject: [ "/__sdk/inject.ts" ],
+    format,
+    minify,
+    fuse: process.env.LECODES_CHISEL_FUSE === "1",
+    define: CHISEL_DEFINE,
+    keep: CHISEL_KEEP,
+    sourcemap,
+    // Reactive-UI desugaring (memoized children .map → __uiMap + auto-wrapped signal reads in
+    // UIText/style args). Only fires on free references to the injected globals, i.e. user code.
+    // An older chisel binary ignores the unknown field — bundles still work, children just
+    // rebuild per change instead of reusing nodes.
+    reactive_ui: process.env.LECODES_CHISEL_REACTIVE_UI !== "0",
+  })
+
+  const bin = resolveChiselBin()
+  const r = spawnSync(bin, [], { input, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 })
+  if (r.status === 2 || r.error) {
+    throw new Error(`chisel failed: ${r.error?.message ?? r.stderr ?? "unknown error"}`)
+  }
+  let parsed: { code?: string, map?: string, error?: string }
+  try {
+    parsed = JSON.parse(r.stdout || "{}")
+  } catch {
+    throw new Error(`chisel produced invalid output: ${(r.stdout || r.stderr || "").slice(0, 200)}`)
+  }
+  if (parsed.error) throw new Error(`chisel: ${parsed.error}`)
+  if (parsed.code == null) throw new Error("chisel produced no code")
+  return { code: parsed.code, map: parsed.map ?? null }
+}
+
+/**
+ * Bundle the project `files` (path → source) starting at `entrypoint`, with the SDK injected.
+ * `format` is "esm" by default (what the platform ships); "iife" produces a self-running script.
+ */
+export const bundleProject = async (
+  entrypoint: string,
+  files: MemoryFiles,
+  format: "esm" | "iife" = "esm",
+): Promise<string> => (await bundleProjectChisel(entrypoint, files, format, false)).code
+
+/** Like `bundleProject`, but also returns chisel's source map. The map's `sources` are the original
+ *  module paths and its generated positions are relative to `code` (line 1 = first line of `code`). */
+export const bundleProjectWithMap = async (
+  entrypoint: string,
+  files: MemoryFiles,
+  format: "esm" | "iife" = "esm",
+): Promise<{ code: string, map: string | null }> => bundleProjectChisel(entrypoint, files, format, true)

package/runtime/sdk/compile/compileProject.ts

@@ -0,0 +1,84 @@
+// Turns a project's files into the esbuild input map + entrypoint + metadata header, then bundles.
+// The one canonical "user project → deployable bundle" path: the backend and CLI both call this
+// (the backend resolves asset URLs from the DB, the CLI from local metadata — same function, the
+// URLs are passed in as `publicUrl` + per-entry `fileSrc`/`shaders`).
+
+import { bundleProjectWithMap } from "./bundler"
+import { buildHeader } from "./header"
+import { inlineSourceMapComment, offsetSourceMap } from "./sourcemap"
+
+export type CompileFileType = "text" | "resource" | "shader"
+
+export type CompileEntry = {
+  path: string
+  type: CompileFileType
+  /** Source text for code / .svg files. */
+  text?: string
+  /** Server src for a binary resource (e.g. "/uploads/x.png"); prefixed with publicUrl. */
+  fileSrc?: string
+  /** Compiled-shader artifacts (platform + src); the first drives the per-backend URL. */
+  shaders?: { platform: string, src: string }[]
+}
+
+export type CompileOptions = {
+  entries: CompileEntry[]
+  name: string
+  publicUrl: string
+  entryOverride?: string
+  /** Prepend the metadata header (default true). */
+  header?: boolean
+  /** Generated-icon URL for the header (backend only). */
+  icon?: string
+  /** "esm" (default, shipped) or "iife" (self-running, for the local renderer). */
+  format?: "esm" | "iife"
+}
+
+/** The default entrypoint: the largest top-level .ts/.js file with no `export` (a script entry). */
+const detectEntry = (entries: CompileEntry[]): string => {
+  let entry = ""
+  let max = -1
+  for (const e of entries) {
+    const ext = e.path.split(".").at(-1)?.toLowerCase()
+    if (e.type === "text" && e.text !== undefined && !e.text.includes("export") && (ext === "ts" || ext === "js")) {
+      if (e.text.length > max) { entry = e.path; max = e.text.length }
+    }
+  }
+  return entry
+}
+
+export const compileProject = async (opts: CompileOptions): Promise<string> => {
+  const entry = opts.entryOverride ?? detectEntry(opts.entries)
+  if (!entry) {
+    throw new Error("Couldn't find an entrypoint (a top-level .ts/.js file with no `export`). Pass entryOverride.")
+  }
+
+  const files: Record<string, string> = {}
+  for (const e of opts.entries) {
+    if (e.type === "resource") {
+      files[e.path] = `export default "${opts.publicUrl}${e.fileSrc ?? ""}"`
+    } else if (e.type === "shader") {
+      const shaders = e.shaders ?? []
+      if (shaders.length > 2) {
+        files[e.path] = `export default \`${opts.publicUrl}${shaders[0].src.replace("_opengl", "_${_creator.subBackend ?? _creator.backend}")}\``
+      } else if (shaders.length > 0) {
+        files[e.path] = `export default \`${opts.publicUrl}${shaders[0].src.replace("_opengl", "_${_creator.backend}")}\``
+      } else {
+        files[e.path] = `export default ""` // local-only shader with no compiled artifact yet
+      }
+    } else if (e.path.toLowerCase().endsWith(".svg")) {
+      files[e.path] = `export default SvgSource(\`${e.text ?? ""}\`)`
+    } else {
+      files[e.path] = e.text ?? ""
+    }
+  }
+
+  const { code, map } = await bundleProjectWithMap(entry, files, opts.format ?? "esm")
+  if (opts.header === false) {
+    return map ? `${code}\n${inlineSourceMapComment(map)}` : code
+  }
+  const header = buildHeader(opts.name, code, { icon: opts.icon })
+  if (!map) return header + code
+  // Shift the map down past the header (prepended before the code); the inline comment lands last.
+  const headerLines = (header.match(/\n/g) ?? []).length
+  return `${header}${code}\n${inlineSourceMapComment(offsetSourceMap(map, headerLines))}`
+}

package/runtime/sdk/compile/header.ts

@@ -0,0 +1,46 @@
+// The metadata header the launcher reads from the compiled bundle: name / icon / preload / gl / 2d /
+// ar. Single source of truth — the backend and CLI both call this (today they mirror it by hand).
+//
+// Detection keys on the *bundled* `_creator*` calls, which the SDK's thin wrappers still emit
+// (new Scene() → _creator.createScene, new Scene2D() → _creator2d.createScene), so the re-skin keeps
+// the exact same signals the old worker bundles produced.
+
+export type HeaderOptions = {
+  /** Generated-icon URL (backend supplies it; the CLI omits it). */
+  icon?: string
+}
+
+export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}): string => {
+  let header = `// name: ${name.slice(0, 20)}\n`
+  if (opts.icon) header += `// icon: ${opts.icon}\n`
+  header += `// last-updated: ${new Date().toISOString()}\n`
+
+  // Local assets to preload: explicit fetchLocal() calls + implicit engine archives.
+  const localAssets = new Set<string>()
+  for (const m of code.matchAll(/_creatorUtils\.fetchLocal\((.+?)\)/g)) {
+    localAssets.add(m[1].replaceAll(/['"]/g, "").trim())
+  }
+  if (/_creator\.createGlb/.test(code)) localAssets.add("uberarchive")
+  if (/_creator\.captureImage/.test(code)) localAssets.add("capture")
+  if (localAssets.size > 0) header += `// preload: ${[ ...localAssets ].join(";")}\n`
+
+  // GL: disabled unless the project touches the 3D engine; deferred if it lazily creates the engine.
+  if (!code.includes("_creator.createScene") && !code.includes("_creator.createEntity")) header += `// gl: disable\n`
+  else if (code.includes("_creator.createEngine")) header += `// gl: defer\n`
+
+  // 2D (creator-2d) — non-exclusive: emitted alongside `gl: disable` so hosts skip Filament and a
+  // 2D-aware host brings up the lightweight sokol engine instead.
+  if (code.includes("_creator2d.")) header += `// 2d: enable\n`
+
+  if (code.includes("_creator.createARController")) header += "// ar: enable"
+  header += "\n"
+  return header
+}
+
+/** Same engine signals the header uses, for callers that need the project kind (e.g. icon type). */
+export const detectProjectKind = (code: string): "ar" | "ui" | "2d" | "3d" => {
+  if (code.includes("_creator.createARController")) return "ar"
+  if (code.includes("_creator2d.")) return "2d"
+  if (!code.includes("_creator.")) return "ui"
+  return "3d"
+}

package/runtime/sdk/compile/index.ts

@@ -0,0 +1,12 @@
+// The public entry of the SDK's bundle build system. The backend, CLI, and local renderer import
+// from here instead of re-forking a bundler. (Node + Bun safe — no top-level host globals.)
+
+export { bundleProject, bundleProjectWithMap, type MemoryFiles } from "./bundler"
+export { offsetSourceMap, inlineSourceMapComment } from "./sourcemap"
+export { buildHeader, detectProjectKind, type HeaderOptions } from "./header"
+export {
+  compileProject,
+  type CompileEntry,
+  type CompileOptions,
+  type CompileFileType,
+} from "./compileProject"

package/runtime/sdk/compile/sourcemap.ts

@@ -0,0 +1,25 @@
+// Helpers for serving the bundler's source map alongside the bundle. The map's generated positions
+// are relative to the bundle code; when the deploy/preview prepends a comment header, the map must be
+// shifted down by that many lines, then inlined into the bundle as a data URL (the preview executes
+// the bundle via `new Function(string)`, which has no URL identity, so an external `.map` can't be
+// fetched — it must be inline).
+
+/** Shift every generated position in `mapJson` down by `lines` (each VLQ line is `;`-separated). */
+export const offsetSourceMap = (mapJson: string, lines: number): string => {
+  if (lines <= 0) return mapJson
+  const map = JSON.parse(mapJson) as { mappings: string }
+  map.mappings = ";".repeat(lines) + map.mappings
+  return JSON.stringify(map)
+}
+
+/**
+ * Inline the map into a bundle string under a **non-standard** directive (`lecodesMap`, not
+ * `sourceMappingURL`), so the browser does NOT auto-apply it. The bundle runs via `new Function`, and
+ * the browser maps the raw stack position *including* the `new Function` wrapper (~2-3 lines) which the
+ * map can't subtract — so its native source location would be off by those lines. Our preview mapper
+ * reads `lecodesMap` and subtracts the (calibrated) wrapper itself, so its locations are correct.
+ */
+export const inlineSourceMapComment = (mapJson: string): string => {
+  const b64 = Buffer.from(mapJson, "utf8").toString("base64")
+  return `//# lecodesMap=data:application/json;charset=utf-8;base64,${b64}`
+}

package/runtime/sdk/core/Aspect.ts

@@ -3,7 +3,7 @@
 //
 //   const hero = new Sprite({ texture })
 //     .aspect(SpriteAnimation, { fps: 8, clips: { walk: [1, 2, 3] } })   // attach + configure
-//     .aspect(Collider, { box: [16, 8], trigger: true })                 // chains: returns the node
+//     .aspect(Shape2D, { box: [16, 8] })                                 // chains: returns the node
 //   hero.anim.play('walk')          // access by name (the chain result is typed as having it)
 //   if (hero.has(Physics)) hero.physics.velocity = [0, 0]                // has() is a type guard
 //
@@ -73,7 +73,7 @@ const policyOf = (a: Updatable): { early: boolean; order: number } =>
 // Stable insert by ascending order: place after the last element whose order is <= this one's.
 const addSorted = (list: Updatable[], a: Updatable, order: number): void => {
   let i = list.length
-  while (i > 0 && policyOf(list[i - 1]).order > order) i--
+  while (i > 0 && list[i - 1].order > order) i--
   list.splice(i, 0, a)
 }