lecodes-sdk 0.19.0

package/src/canvas/Canvas.ts

@@ -0,0 +1,305 @@
+// 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, type FetchResponse } from "../runtime/fetch"
+import type { SvgSourceValue } from "../runtime/misc"
+
+// 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
+  // Set once this canvas is baked as a UIImage source (see _bakeSurfaceForUI). When true, update()
+  // also refreshes the on-screen image node(s) via _creatorUI — the UI consumer the 2D/3D texture
+  // hooks below don't cover. Stays a bare flag so a non-UI canvas never references the UI bridge.
+  private _uiBound = false
+
+  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
+  }
+
+  /** Decode an image source into a standalone `Bitmap` you can blit with `drawImage()` — either an
+   *  `SvgSource(...)` (rasterized) or a `FetchResponse` holding already-fetched image bytes (decoded).
+   *  This is async because turning SVG markup / encoded bytes into pixels needs a decode step (on the
+   *  web, `createImageBitmap` / an `<img>` load); `await` it ONCE, then `drawImage(bitmap, …)` is
+   *  synchronous and the Bitmap is reusable. The returned Bitmap owns a native surface at the image's
+   *  natural pixel size (`pixelRatio` 1) — `destroy()` it when done. Typical use:
+   *    const logo = await canvas.loadImage(SvgSource(svg))   // or: await fetch(url) → the response
+   *    canvas.drawImage(logo, 0, 0)                          // sync, blit as often as you like */
+  loadImage(source: SvgSourceValue | FetchResponse): Promise<Bitmap> {
+    // Discriminate without touching FetchResponse internals: only an SvgSource carries `.svg`.
+    const isSvg = typeof (source as SvgSourceValue).svg === "string"
+    const svg = isSvg ? (source as SvgSourceValue).svg : ""
+    const bufferId = isSvg ? -1 : (source as any)._id   // <0 = the SVG path; else the host buffer id
+    return new Promise<Bitmap>((res, rej) => {
+      _creatorCanvas.loadImage(svg, bufferId, (surfaceId, w, h) => res(new Bitmap(surfaceId, w, h, 1)), rej)
+    })
+  }
+
+  /** 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
+  }
+
+  /** @internal — bake for a `UIImage(canvas)` source: same as `_bakeSurface()` but also flags this
+   *  canvas UI-bound, so a later `update()` re-reads the re-baked pixels into the on-screen image
+   *  node(s) — not just the 2D/3D engine textures. Called by UIImage when a Canvas is assigned as src. */
+  _bakeSurfaceForUI(): number {
+    this._uiBound = true
+    return this._bakeSurface()
+  }
+
+  /** 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)
+    // UIImage(canvas): repaint any live image node showing this surface with the re-baked pixels —
+    // draw-only, no relayout (the surface keeps its id and size). Feature-detected so an older host
+    // without the hook just no-ops (fall back to re-assigning UIImage.src). See docs/canvas-contract.md.
+    if (this._uiBound) _creatorUI.refreshCanvasSurface?.(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 an opaque host buffer handle (`name`/`size` only): 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/src/compile/__tests__/assetIconMacro.test.ts

@@ -0,0 +1,219 @@
+import { test, expect, describe } from "bun:test"
+import { applyAssetIconMacro, buildIconsHeaderValue, iconNotFoundError, rewriteAssetIcons, scanAssetIconCalls, suggestIconNames } from "../assetIconMacro"
+
+const svg = (stroke: string) => `<svg viewBox="0 0 24 24"><path stroke="${stroke}" d="M1 1"/></svg>`
+
+describe("scanAssetIconCalls", () => {
+  test("a bare call → id + pack + name, no color, correct span", () => {
+    const src = `UIImage(assetIcon("lucide:bell"))`
+    const [c] = scanAssetIconCalls(src)
+    expect(c.id).toBe("lucide:bell")
+    expect(c.pack).toBe("lucide")
+    expect(c.name).toBe("bell")
+    expect(c.bake).toBeUndefined()
+    expect(c.tint).toBeUndefined()
+    expect(c.error).toBeUndefined()
+    expect(src.slice(c.start, c.end)).toBe(`assetIcon("lucide:bell")`)
+  })
+
+  test("a literal color option → captured as a compile-time bake", () => {
+    const [c] = scanAssetIconCalls(`assetIcon('lucide:check', { color: "#5b8cff" })`)
+    expect(c.id).toBe("lucide:check")
+    expect(c.bake).toBe("#5b8cff")
+    expect(c.tint).toBeUndefined()
+    expect(c.error).toBeUndefined()
+  })
+
+  test("a token / expression color → captured verbatim as a runtime tint (not an error)", () => {
+    const [c] = scanAssetIconCalls(`assetIcon("lucide:bell", { color: tokens.accent })`)
+    expect(c.tint).toBe("tokens.accent")
+    expect(c.bake).toBeUndefined()
+    expect(c.error).toBeUndefined()
+  })
+
+  test("dashed pack/name ids are valid", () => {
+    const [c] = scanAssetIconCalls(`assetIcon("simple-icons:arrow-right")`)
+    expect(c.pack).toBe("simple-icons")
+    expect(c.name).toBe("arrow-right")
+    expect(c.error).toBeUndefined()
+  })
+
+  test("a non-literal id → error", () => {
+    const [c] = scanAssetIconCalls(`assetIcon(iconVar)`)
+    expect(c.error).toContain("string-literal id")
+  })
+
+  test("a malformed id → error naming pack:name", () => {
+    const [c] = scanAssetIconCalls(`assetIcon("BellIcon")`)
+    expect(c.error).toContain("pack:name")
+  })
+
+  test("a non-object opts → error", () => {
+    const [c] = scanAssetIconCalls(`assetIcon("lucide:bell", "#fff")`)
+    expect(c.error).toContain("object literal")
+  })
+
+  test("a method named assetIcon is not matched", () => {
+    expect(scanAssetIconCalls(`icons.assetIcon("lucide:bell")`)).toEqual([])
+  })
+
+  test("assetIcon inside a string or comment is ignored", () => {
+    expect(scanAssetIconCalls(`const s = "assetIcon('lucide:bell')" // assetIcon('lucide:x')`)).toEqual([])
+  })
+
+  test("surrounding template literals don't confuse the scan", () => {
+    const src = "UIBox([]).style({ border: `2px solid ${c.muted}` })\nUIImage(assetIcon('lucide:bell'))"
+    const calls = scanAssetIconCalls(src)
+    expect(calls).toHaveLength(1)
+    expect(calls[0].id).toBe("lucide:bell")
+  })
+
+  test("multiple calls are all found in order", () => {
+    const calls = scanAssetIconCalls(`assetIcon("lucide:bell"); assetIcon("lucide:check")`)
+    expect(calls.map((c) => c.id)).toEqual(["lucide:bell", "lucide:check"])
+  })
+})
+
+describe("rewriteAssetIcons", () => {
+  test("rewrites a call to an inline SvgSource(...)", () => {
+    const src = `UIImage(assetIcon("lucide:bell"))`
+    const out = rewriteAssetIcons(src, scanAssetIconCalls(src), new Map([["lucide:bell", svg("currentColor")]]))
+    expect(out).toBe("UIImage(SvgSource(`" + svg("currentColor") + "`))")
+    expect(out).not.toContain("assetIcon")
+  })
+
+  test("bakes a literal color (currentColor → color)", () => {
+    const src = `assetIcon("lucide:bell", { color: "#f00" })`
+    const out = rewriteAssetIcons(src, scanAssetIconCalls(src), new Map([["lucide:bell", svg("currentColor")]]))
+    expect(out).toContain(`stroke="#f00"`)
+    expect(out).not.toContain("currentColor")
+    expect(out).not.toContain("tintColor")
+  })
+
+  test("a token color → source-level tint, SVG left as currentColor", () => {
+    const src = `assetIcon("lucide:bell", { color: colors.accent })`
+    const out = rewriteAssetIcons(src, scanAssetIconCalls(src), new Map([["lucide:bell", svg("currentColor")]]))
+    expect(out).toContain("Object.assign(SvgSource(`")
+    expect(out).toContain("{ tintColor: (colors.accent) }")
+    expect(out).toContain("currentColor")
+  })
+
+  test("escapes backticks and ${ in the SVG body", () => {
+    const nasty = "<svg>`${danger}`</svg>"
+    const src = `assetIcon("lucide:bell")`
+    const out = rewriteAssetIcons(src, scanAssetIconCalls(src), new Map([["lucide:bell", nasty]]))
+    expect(out).toContain("\\`")
+    expect(out).toContain("\\${")
+  })
+
+  test("two calls in one file are both rewritten (indices stay valid)", () => {
+    const src = `[assetIcon("lucide:bell"), assetIcon("lucide:check")]`
+    const map = new Map([["lucide:bell", svg("a")], ["lucide:check", svg("b")]])
+    const out = rewriteAssetIcons(src, scanAssetIconCalls(src), map)
+    expect(out).not.toContain("assetIcon")
+    expect(out).toContain(svg("a"))
+    expect(out).toContain(svg("b"))
+  })
+})
+
+describe("applyAssetIconMacro", () => {
+  test("rewrites every text entry via the resolver and returns the resolved ids", async () => {
+    const entries = [
+      { path: "/screens/home.ts", type: "text", text: `export default UIImage(assetIcon("lucide:bell"))` },
+      { path: "/shared/icon.ts", type: "text", text: `export const c = () => UIImage(assetIcon("lucide:check", { color: "#0f0" }))` },
+      { path: "/logo.png", type: "resource", text: undefined },
+    ]
+    let asked: string[] = []
+    const ids = await applyAssetIconMacro(entries, (want) => {
+      asked = want
+      return new Map(want.map((id) => [id, svg("currentColor")]))
+    })
+    expect(ids.sort()).toEqual(["lucide:bell", "lucide:check"])
+    expect(asked.sort()).toEqual(["lucide:bell", "lucide:check"])
+    expect(entries[0].text).toContain("SvgSource(`")
+    expect(entries[0].text).not.toContain("assetIcon")
+    expect(entries[1].text).toContain(`stroke="#0f0"`)
+  })
+
+  test("a no-op when nothing uses assetIcon — the resolver is never called", async () => {
+    const entries = [{ path: "/x.ts", type: "text", text: `export default UIScreen([])` }]
+    const ids = await applyAssetIconMacro(entries, () => { throw new Error("resolver must not run") })
+    expect(ids).toEqual([])
+    expect(entries[0].text).toBe(`export default UIScreen([])`)
+  })
+
+  test("a malformed call aborts before the resolver runs", async () => {
+    const entries = [{ path: "/x.ts", type: "text", text: `UIImage(assetIcon(runtimeVar))` }]
+    await expect(applyAssetIconMacro(entries, () => new Map())).rejects.toThrow(/string-literal id/)
+  })
+
+  test("an id the resolver silently omits fails the pass", async () => {
+    const entries = [{ path: "/x.ts", type: "text", text: `UIImage(assetIcon("lucide:ghost"))` }]
+    await expect(applyAssetIconMacro(entries, () => new Map())).rejects.toThrow(/could not resolve icon/)
+  })
+})
+
+describe("buildIconsHeaderValue", () => {
+  test("distinct packs, sorted", () => {
+    expect(buildIconsHeaderValue(["noto:star", "lucide:bell", "lucide:check"])).toBe("lucide;noto")
+    expect(buildIconsHeaderValue([])).toBe("")
+  })
+})
+
+describe("suggestIconNames", () => {
+  const icons = {
+    "bell": { kw: ["bell"] },
+    "bell-ring": { kw: ["bell", "ring"] },
+    "bell-off": { kw: ["bell", "off"] },
+    "check": { kw: ["check"] },
+    "arrow-right": { kw: ["arrow", "right"] },
+  }
+
+  test("a typo resolves by edit distance, exact-ish first", () => {
+    const s = suggestIconNames("bel", icons)
+    expect(s[0]).toBe("bell")
+    expect(s).toContain("bell-off") // substring family follows
+  })
+
+  test("a sub-word matches by substring", () => {
+    expect(suggestIconNames("ring", icons)).toContain("bell-ring")
+  })
+
+  test("swapped word order matches via keywords", () => {
+    expect(suggestIconNames("right-arrow", icons)).toContain("arrow-right")
+  })
+
+  test("nothing similar → empty", () => {
+    expect(suggestIconNames("zzz-qqq", icons)).toEqual([])
+  })
+})
+
+describe("iconNotFoundError", () => {
+  const registry: Record<string, string> = {
+    "lucide/meta.json": JSON.stringify({ icons: { bell: { kw: ["bell"] }, "bell-ring": { kw: ["bell", "ring"] } } }),
+    "licenses.json": JSON.stringify({ lucide: {}, tabler: {} }),
+  }
+  const read = async (rel: string) => registry[rel] ?? null
+
+  test("a known pack + missing name → did-you-mean from the pack's meta", async () => {
+    const err = await iconNotFoundError("lucide", "bel", read)
+    expect(err.message).toContain(`"lucide:bel" not found`)
+    expect(err.message).toContain(`"lucide:bell"`)
+  })
+
+  test("a known pack, nothing similar → says so", async () => {
+    const err = await iconNotFoundError("lucide", "zzz-qqq", read)
+    expect(err.message).toContain("No similar name")
+  })
+
+  test("an unknown pack → the available-pack list", async () => {
+    const err = await iconNotFoundError("nope", "bell", read)
+    expect(err.message).toContain(`unknown icon pack "nope"`)
+    expect(err.message).toContain("lucide, tabler")
+  })
+
+  test("nothing reachable → a connectivity error naming the registry", async () => {
+    const err = await iconNotFoundError("lucide", "bell", async () => null, "https://reg.example/v1")
+    expect(err.message).toContain("can't reach the icon registry (https://reg.example/v1)")
+  })
+})

package/src/compile/__tests__/assetMacro.test.ts

@@ -0,0 +1,74 @@
+import { test, expect } from "bun:test"
+import { collectAssetMacros, desugarAssetMacros } from "../assetMacro"
+import { compileProject } from "../compileProject"
+
+// A missing asset is a COMPILE ERROR — never a fallback. The old behaviour compiled
+// `asset('../x.bake')` whose file didn't exist into the source path verbatim: a string nothing
+// resolves at runtime, handed to the app as a broken reference with no diagnostic at all (and,
+// since the macro appends its generated imports, a const used before its own declaration — a TDZ
+// ReferenceError at boot that read like a bundler crash).
+
+const paths = (src: string) => collectAssetMacros(src, "/main.ts").map(r => r.path)
+
+test("a missing asset fails the compile, naming the file and the call site", async () => {
+  const main = "const scene = new Scene()\nconst bake = asset('./assets/lightmap.bake')\nconsole.log(scene, bake)\n"
+  const compile = compileProject({
+    name: "Missing",
+    publicUrl: "https://le.codes",
+    entries: [ { path: "/main.ts", type: "text", text: main } ],
+  })
+  await expect(compile).rejects.toThrow("asset not found: ./assets/lightmap.bake (main.ts:2)")
+})
+
+test("the same asset present in the entries compiles to its URL", async () => {
+  const main = "const bake = asset('./assets/lightmap.bake')\nconsole.log(bake)\n"
+  const js = await compileProject({
+    name: "Present",
+    publicUrl: "https://le.codes",
+    entries: [
+      { path: "/main.ts", type: "text", text: main },
+      { path: "/assets/lightmap.bake", type: "resource", fileSrc: "/u/lightmap.bake" },
+    ],
+  })
+  expect(js).toContain("https://le.codes/u/lightmap.bake")
+  expect(js).not.toContain("./assets/lightmap.bake")
+})
+
+test("a commented-out asset() is not an asset at all", () => {
+  const src = [
+    "/** The atlas image — write `asset('./TileSet.png')`. */",
+    "// const old = asset('./deleted.png')",
+    "const live = asset('./hero.png')",
+    "/* asset('./block-commented.png') */",
+  ].join("\n")
+  expect(paths(src)).toEqual([ "./hero.png" ])
+  const out = desugarAssetMacros(src, "/main.ts")
+  expect(out).toContain(`import __asset_0 from "./hero.png";`)
+  expect(out).not.toContain("deleted.png\";")
+  expect(out).toContain("asset('./deleted.png')") // the comment itself is untouched
+})
+
+test("an asset() inside a string literal is text, one inside `${…}` is a call", () => {
+  expect(paths(`const doc = "call asset('./x.png') to load"`)).toEqual([])
+  expect(paths("const url = `bg:${asset('./bg.png')}`")).toEqual([ "./bg.png" ])
+  expect(paths("const url = `not ${1} asset('./no.png')`")).toEqual([])
+})
+
+test("method calls named asset are still untouched, dynamic arguments still throw", () => {
+  expect(paths(`state.model = ui.asset("model")`)).toEqual([])
+  expect(() => paths("const p = './x.png'\nconst a = asset(p)")).toThrow("expects a string literal")
+})
+
+test("repeated paths share one import and the line numbers stay exact", () => {
+  const src = "const a = asset('./x.png')\n\nconst b = asset('./x.png')\nconst c = asset('./y.png')\n"
+  const refs = collectAssetMacros(src, "/main.ts")
+  expect(refs.map(r => r.line)).toEqual([ 1, 3, 4 ])
+  const out = desugarAssetMacros(src, "/main.ts")
+  // The generated imports are APPENDED, so no original line moves (source maps stay honest).
+  const lines = out.split("\n")
+  expect(lines.slice(0, 4)).toEqual([ "const a = __asset_0", "", "const b = __asset_0", "const c = __asset_1" ])
+  expect(lines.slice(4).join("\n")).toContain("import __asset_0")
+  expect(out).toContain("const a = __asset_0")
+  expect(out).toContain("const b = __asset_0")
+  expect(out).toContain("const c = __asset_1")
+})

package/src/compile/__tests__/assetName.test.ts

@@ -0,0 +1,55 @@
+import { test, expect } from "bun:test"
+import { isCanonicalAssetName, sanitizeAssetName } from "../assetName"
+
+// The invariant: two names that LOOK the same on screen must be stored the same way, or the import
+// written from what the user sees resolves to nothing. Codepoints are spelled out via fromCharCode
+// so the cases stay readable — the characters themselves are invisible in an editor.
+
+const NBSP = String.fromCharCode(0x00a0)
+const NARROW_NBSP = String.fromCharCode(0x202f)
+const ZERO_WIDTH = String.fromCharCode(0x200b)
+const RTL_MARK = String.fromCharCode(0x200f)
+const COMBINING_BREVE = String.fromCharCode(0x0306)
+
+test("a non-breaking space becomes the plain space the user types in an import", () => {
+  expect(sanitizeAssetName(`итальянский${NBSP}сквер1.jpg`)).toBe("итальянский сквер1.jpg")
+  expect(sanitizeAssetName(`narrow${NARROW_NBSP}space.png`)).toBe("narrow space.png")
+})
+
+test("a decomposed name (what macOS hands out) composes to the same codepoints as typed text", () => {
+  // "й" as и + combining breve — indistinguishable on screen from the single U+0439 codepoint.
+  const decomposed = `и${COMBINING_BREVE}ога.glb`
+  expect(decomposed).not.toBe("йога.glb")
+  expect(sanitizeAssetName(decomposed)).toBe("йога.glb")
+})
+
+test("zero-width and bidi characters are dropped", () => {
+  expect(sanitizeAssetName(`logo${ZERO_WIDTH}.png`)).toBe("logo.png")
+  expect(sanitizeAssetName(`${RTL_MARK}logo.png`)).toBe("logo.png")
+})
+
+test("path separators and Windows-illegal characters can't enter a name", () => {
+  expect(sanitizeAssetName("a/b.png")).toBe("a_b.png")
+  expect(sanitizeAssetName("a\\b.png")).toBe("a_b.png")
+  expect(sanitizeAssetName('q?:*"<>|.png')).toBe("q_______.png")
+})
+
+test("surrounding whitespace and trailing dots go; a leading dot stays", () => {
+  expect(sanitizeAssetName("  main.ts ")).toBe("main.ts")
+  expect(sanitizeAssetName("main.ts...")).toBe("main.ts")
+  expect(sanitizeAssetName(".gitignore")).toBe(".gitignore")
+  expect(sanitizeAssetName("two  spaces.png")).toBe("two spaces.png")
+})
+
+test("an ordinary name is returned untouched and sanitizing is idempotent", () => {
+  for (const name of [ "main.ts", "итальянский сквер1.jpg", "My Scene.scene", "ui-kit.mat" ]) {
+    expect(sanitizeAssetName(name)).toBe(name)
+    expect(isCanonicalAssetName(name)).toBe(true)
+    expect(sanitizeAssetName(sanitizeAssetName(name))).toBe(sanitizeAssetName(name))
+  }
+})
+
+test("a name with nothing printable left comes back empty (callers reject it)", () => {
+  expect(sanitizeAssetName(`  ${ZERO_WIDTH}${NBSP} `)).toBe("")
+  expect(isCanonicalAssetName(`x${ZERO_WIDTH}.png`)).toBe(false)
+})