lecodes-cli 0.2.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-cli",
-  "version": "0.2.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.2.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

@@ -0,0 +1,270 @@
+// A core 2D drawing surface that bakes to a texture — see docs/canvas-contract.md. It is NOT part of
+// creator-2d/creator-gl: the texture it produces is consumed by 2D sprites, 3D materials and UI
+// images alike ("a canvas is just a texture"), so world/label text and arbitrary 2D graphics are
+// drawn once, per platform, on that platform's native 2D stack (web OffscreenCanvas, iOS CoreGraphics,
+// Android Canvas).
+//
+// The API looks immediate but RECORDS commands into a compact buffer and flushes them to the backend
+// ONCE per bake (one bridge crossing, not one per lineTo). Colors and fonts are CSS strings, resolved
+// by the platform. Do all drawing AFTER `await registerFont(...)` — an unloaded font mis-measures.
+//
+// State (fillStyle, font, textAlign, …) is get/set like the browser; drawing calls are methods (they
+// return `this`, so drawing still chains). `pixelRatio` is the device-pixel multiplier (browser-style
+// `scale(sx, sy)` is a transform).
+//
+//   const c = new Canvas(160, 40, { pixelRatio: 2 })
+//   c.font = 'bold 24px Inter'
+//   const w = c.measureText('Alice').width + 24
+//   c.resize(w, 40)
+//   c.fillStyle = '#000a'; c.roundRect(0, 0, w, 40, 12).fill()
+//   c.fillStyle = '#fff'; c.textAlign = 'center'; c.fillText('Alice', w / 2, 27)
+//   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 = {
+  SAVE: 0, RESTORE: 1, TRANSLATE: 2, SCALE: 3, ROTATE: 4, GLOBAL_ALPHA: 5,
+  FILL_STYLE: 6, STROKE_STYLE: 7, LINE_WIDTH: 8, LINE_JOIN: 9, LINE_CAP: 10,
+  FONT: 11, TEXT_ALIGN: 12, TEXT_BASELINE: 13,
+  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
+const BASELINE = { alphabetic: 0, top: 1, middle: 2, bottom: 3, hanging: 4, ideographic: 5 } as const
+const JOIN = { miter: 0, round: 1, bevel: 2 } as const
+const CAP = { butt: 0, round: 1, square: 2 } as const
+
+export type TextAlign = keyof typeof ALIGN
+export type TextBaseline = keyof typeof BASELINE
+export type LineJoin = keyof typeof JOIN
+export type LineCap = keyof typeof CAP
+export interface CanvasTextMetrics { width: number, ascent: number, descent: number }
+
+export class Canvas {
+  /** Brand so `Sprite`/`UIImage`/`Material` can accept a Canvas anywhere a texture source is expected. */
+  readonly __canvas = true as const
+
+  width: number
+  height: number
+  /** Device-pixel multiplier (draw at 2 for crisp retina text). Applied by the backend. */
+  pixelRatio: number
+
+  private _cmd: number[] = []
+  private _refs: string[] = []
+  // Shadowed drawing state so the get/set accessors read back the current value (like the browser).
+  private _globalAlpha = 1
+  private _fillStyle = "#000000"
+  private _strokeStyle = "#000000"
+  private _lineWidth = 1
+  private _lineJoin: LineJoin = "miter"
+  private _lineCap: LineCap = "butt"
+  private _font = "10px sans-serif"
+  private _textAlign: TextAlign = "start"
+  private _textBaseline: TextBaseline = "alphabetic"
+  private _surfaceId = 0
+  private _tex2d?: Texture2D   // cached 2D texture, re-uploaded on update()
+  /** @internal — cached 3D (creator-gl) texture id, set by gl/Texture.fromCanvas; re-uploaded on
+   *  update(). Kept as a bare id (not a Texture import) so a 2D-only canvas never pulls the 3D engine. */
+  _tex3dId = 0
+
+  constructor(width: number, height: number, opts: { pixelRatio?: number } = {}) {
+    this.width = width
+    this.height = height
+    this.pixelRatio = opts.pixelRatio ?? 1
+  }
+
+  private _ref(s: string): number {
+    const i = this._refs.indexOf(s)
+    if (i >= 0) return i
+    this._refs.push(s)
+    return this._refs.length - 1
+  }
+
+  /** Discard the recorded drawing to start a new one (for dynamic canvases). */
+  reset(): this { this._cmd.length = 0; this._refs.length = 0; return this }
+  /** Change the surface size; takes effect on the next bake. */
+  resize(width: number, height: number): this { this.width = width; this.height = height; return this }
+
+  // --- transforms & state stack (actions; chainable) ---
+  save(): this { this._cmd.push(OP.SAVE); return this }
+  restore(): this { this._cmd.push(OP.RESTORE); return this }
+  translate(x: number, y: number): this { this._cmd.push(OP.TRANSLATE, x, y); return this }
+  scale(sx: number, sy: number): this { this._cmd.push(OP.SCALE, sx, sy); return this }
+  rotate(rad: number): this { this._cmd.push(OP.ROTATE, rad); return this }
+
+  // --- drawing state (get/set like the browser; colors/fonts are CSS strings resolved by the platform).
+  // The setter records the state op AND shadows the value so the getter reads it back.
+  get globalAlpha(): number { return this._globalAlpha }
+  set globalAlpha(a: number) { this._globalAlpha = a; this._cmd.push(OP.GLOBAL_ALPHA, a) }
+  get fillStyle(): string { return this._fillStyle }
+  set fillStyle(color: string) { this._fillStyle = color; this._cmd.push(OP.FILL_STYLE, this._ref(color)) }
+  get strokeStyle(): string { return this._strokeStyle }
+  set strokeStyle(color: string) { this._strokeStyle = color; this._cmd.push(OP.STROKE_STYLE, this._ref(color)) }
+  get lineWidth(): number { return this._lineWidth }
+  set lineWidth(w: number) { this._lineWidth = w; this._cmd.push(OP.LINE_WIDTH, w) }
+  get lineJoin(): LineJoin { return this._lineJoin }
+  set lineJoin(j: LineJoin) { this._lineJoin = j; this._cmd.push(OP.LINE_JOIN, JOIN[j]) }
+  get lineCap(): LineCap { return this._lineCap }
+  set lineCap(c: LineCap) { this._lineCap = c; this._cmd.push(OP.LINE_CAP, CAP[c]) }
+  get font(): string { return this._font }
+  set font(f: string) { this._font = f; this._cmd.push(OP.FONT, this._ref(f)) }
+  get textAlign(): TextAlign { return this._textAlign }
+  set textAlign(a: TextAlign) { this._textAlign = a; this._cmd.push(OP.TEXT_ALIGN, ALIGN[a]) }
+  get textBaseline(): TextBaseline { return this._textBaseline }
+  set textBaseline(b: TextBaseline) { this._textBaseline = b; this._cmd.push(OP.TEXT_BASELINE, BASELINE[b]) }
+
+  // --- paths ---
+  beginPath(): this { this._cmd.push(OP.BEGIN_PATH); return this }
+  closePath(): this { this._cmd.push(OP.CLOSE_PATH); return this }
+  moveTo(x: number, y: number): this { this._cmd.push(OP.MOVE_TO, x, y); return this }
+  lineTo(x: number, y: number): this { this._cmd.push(OP.LINE_TO, x, y); return this }
+  quadraticCurveTo(cx: number, cy: number, x: number, y: number): this { this._cmd.push(OP.QUADRATIC_TO, cx, cy, x, y); return this }
+  bezierCurveTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): this {
+    this._cmd.push(OP.BEZIER_TO, c1x, c1y, c2x, c2y, x, y); return this
+  }
+  arc(x: number, y: number, r: number, a0: number, a1: number, ccw = false): this {
+    this._cmd.push(OP.ARC, x, y, r, a0, a1, ccw ? 1 : 0); return this
+  }
+  rect(x: number, y: number, w: number, h: number): this { this._cmd.push(OP.RECT, x, y, w, h); return this }
+  roundRect(x: number, y: number, w: number, h: number, r: number): this { this._cmd.push(OP.ROUND_RECT, x, y, w, h, r); return this }
+  fill(evenOdd = false): this { this._cmd.push(OP.FILL, evenOdd ? 1 : 0); return this }
+  stroke(): this { this._cmd.push(OP.STROKE); return this }
+
+  // --- shape/text sugar ---
+  fillRect(x: number, y: number, w: number, h: number): this { this._cmd.push(OP.FILL_RECT, x, y, w, h); return this }
+  strokeRect(x: number, y: number, w: number, h: number): this { this._cmd.push(OP.STROKE_RECT, x, y, w, h); return this }
+  clearRect(x: number, y: number, w: number, h: number): this { this._cmd.push(OP.CLEAR_RECT, x, y, w, h); return this }
+  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)
+    return { width: o[0], ascent: o[1], descent: o[2] }
+  }
+
+  /** @internal — rasterize the recorded commands into the surface; returns the surface id. */
+  _bakeSurface(): number {
+    const buf = new Float32Array(this._cmd)
+    this._surfaceId = _creatorCanvas.rasterize(this._surfaceId, this.width, this.height, this.pixelRatio, buf, buf.length, this._refs)
+    return this._surfaceId
+  }
+
+  /** Bake and return the 2D texture (created once, then cached). */
+  texture(): Texture2D {
+    if (!this._tex2d) this._tex2d = Texture2D.fromCanvas(this)
+    return this._tex2d
+  }
+
+  /** Re-rasterize and re-upload to every texture this canvas produced (call after redrawing) — the
+   *  cached 2D and/or 3D texture, whichever engines this canvas was baked into. */
+  update(): this {
+    const surfaceId = this._bakeSurface()
+    if (this._tex2d) _creator2d.updateTextureFromCanvas(this._tex2d.id, surfaceId)
+    if (this._tex3dId) _creator.updateTextureFromCanvas(this._tex3dId, surfaceId)
+    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()
+    // The 3D texture (if any) is owned by creator-gl's engine and freed at its teardown — no per-texture
+    // destroy in the 3D API — so we just drop our cached id here.
+    this._surfaceId = 0
+    this._tex2d = undefined
+    this._tex3dId = 0
+  }
+}
+
+/** 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))}`
+}