lecodes-sdk 1.2.0 → 2.0.1

package/src/canvas/Canvas.ts

@@ -1,16 +1,19 @@
-// 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).
+// A core 2D drawing surface that bakes to a texture. 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.
 //
-// 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.
+// The drawing API is the AnyCanvas recorder (engines/canvas, vendored into ./gen by `bun run
+// vendor:canvas`): a Canvas2D-shaped API that RECORDS an opcode stream. `_bakeSurface` flushes the
+// stream to `_creatorCanvas` ONCE per bake (one bridge crossing, not one per lineTo); the runtime's
+// AnyCanvas core turns it into a draw list the host's painter replays. Colors and fonts are CSS
+// strings, resolved by the core. 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).
+// `scale(sx, sy)` is a transform). Gradients (`createLinearGradient` / `createRadialGradient`),
+// `setLineDash`, `clip`, `arcTo`, `ellipse`, `roundRect`, `letterSpacing` all work everywhere.
 //
 //   const c = new Canvas(160, 40, { pixelRatio: 2 })
 //   c.font = 'bold 24px Inter'
@@ -19,39 +22,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
+//
+// A surface is an owned resource (docs/owned.md): a Canvas / Bitmap keeps the runtime's Handle as `_h`
+// and puts `_h.id` on the wire. Once the wrapper is dropped AND no UIImage shows the surface, the
+// runtime frees it; `destroy()` is the optional early free. No freed-channel registration
+// (registerFreedKind): the runtime never reports a canvas free — a drop needs no report, destroy() is
+// the wrapper's own call, and a world's teardown only frees surfaces whose wrappers die with it.
 
+import { DEAD_HANDLE } from "../core/pins"
 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
+import { Recorder, Gradient, type ImageRef, type TextAlignName, type TextBaselineName, type LineJoinName, type LineCapName, type FillRuleName } from "./gen/recorder"
+
+export { Gradient }
+export type TextAlign = TextAlignName
+export type TextBaseline = TextBaselineName
+export type LineJoin = LineJoinName
+export type LineCap = LineCapName
+export type FillRule = FillRuleName
+export interface CanvasTextMetrics { width: number, ascent: number, descent: number }
 
 // Above this many buffered values, a buffer that is STILL growing between bakes is a leak, not a
 // drawing (a dense static picture is a few thousand; a 15 Hz graph without reset() passes this in
 // seconds and doubles its frame cost every minute).
 const CMD_GROWTH_WARN = 20000
 
-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 }
+/** The runtime's answer for a surface → the handle a wrapper keeps. A Handle from a runtime with the
+ *  canvas kind; a plain id from one built before it (the committed wasm blobs, an installed phone lib,
+ *  a stale server) or a test stub → `{ id }`, which nothing finalizes (freed by destroy() or the
+ *  world's teardown, as before); 0 / null → DEAD_HANDLE. */
+const surfaceHandle = (r: Handle | number | null | undefined): Handle =>
+  typeof r === "number" ? (r > 0 ? { id: r } : DEAD_HANDLE) : (r ?? DEAD_HANDLE)
 
-export class Canvas {
+export class Canvas extends Recorder {
   /** Brand so `Sprite`/`UIImage`/`Material` can accept a Canvas anywhere a texture source is expected. */
   readonly __canvas = true as const
 
@@ -60,25 +64,18 @@ export class Canvas {
   /** 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
+  /** @internal The surface's owned handle (`_h.id` = the surface id; DEAD_HANDLE until the first bake
+   *  and after destroy()). */
+  _h: Handle = DEAD_HANDLE
+  // The Bitmaps a recorded DRAW_IMAGE names: every bake replays the recording, so each must outlive
+  // the op (a dropped Bitmap's surface would go on the drain). Cleared by reset(), which drops the ops.
+  private _drawn?: Set<Bitmap>
   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
+  // also refreshes the on-screen image node(s) via _creatorTree — 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
   // Growth watch: the command buffer is a RECORDING that every bake replays in full, so a canvas
@@ -88,127 +85,66 @@ export class Canvas {
   private _warnedGrowth = false
 
   constructor(width: number, height: number, opts: { pixelRatio?: number } = {}) {
+    super()
     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:
+  /** Blit a `Bitmap` (a snapshot from `toBitmap()` or `loadImage()`) 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; the canvas keeps the
+   *  Bitmap alive until `reset()` removes the op. 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
+  drawImage(img: Bitmap | ImageRef, dx: number, dy: number): this
+  drawImage(img: Bitmap | ImageRef, dx: number, dy: number, dw: number, dh: number): this
+  drawImage(img: Bitmap | ImageRef, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): this
+  drawImage(img: Bitmap | ImageRef, a: number, b: number, c?: number, d?: number, e?: number, f?: number, g?: number, h?: number): this {
+    if (!isBitmap(img)) return super.drawImage(img, a, b, c!, d!, e!, f!, g!, h!)
+    ;(this._drawn ??= new Set()).add(img)
+    const ref: ImageRef = { surface: img._h.id, width: img.pixelWidth, height: img.pixelHeight }
+    if (e === undefined) return super.drawImage(ref, 0, 0, ref.width, ref.height, a, b, c ?? img.width, d ?? img.height)
+    const pr = img.pixelRatio   // the sub-rect is logical → device px
+    return super.drawImage(ref, a * pr, b * pr, c! * pr, d! * pr, e, f!, g!, h!)
   }
 
   /** 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:
+   *  `SvgSource(...)` (drawn by the core, painted by the host) or a `FetchResponse` holding already-fetched
+   *  image bytes (decoded; an SVG file is detected). This is async because the web host decodes with the
+   *  browser; `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), freed
+   *  once nothing references the Bitmap (`destroy()` frees it early). 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
+    const bufferId = isSvg ? -1 : (source as any)._h.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)
+      _creatorCanvas.loadImage(svg, bufferId, (surface, w, h) => res(new Bitmap(surface, w, h, 1)), rej)
     })
   }
 
-  /** Measure `text` in the current font on THIS platform. The one synchronous round-trip. */
+  /** Measure `text` in the current font and letterSpacing 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] }
+    const o = _creatorCanvas.measureText(text, this.font)
+    // Like the browser: letterSpacing is added after every character (spec/ops.h; the painters draw it so).
+    const ls = this.letterSpacing
+    const extra = ls && Number.isFinite(ls) ? ls * [...text].length : 0
+    return { width: o[0] + extra, ascent: o[1], descent: o[2] }
   }
 
   /** @internal — rasterize the recorded commands into the surface; returns the surface id. */
   _bakeSurface(): number {
-    const len = this._cmd.length
+    const len = this.length
     if (!this._warnedGrowth && len > CMD_GROWTH_WARN && this._lastBakeLen > 0 && len > this._lastBakeLen) {
       this._warnedGrowth = true
       console.warn(
@@ -219,9 +155,19 @@ export class Canvas {
       )
     }
     this._lastBakeLen = len
-    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
+    const { cmd, refs } = this.stream()
+    const r = _creatorCanvas.rasterize(this._h.id, this.width, this.height, this.pixelRatio, cmd, cmd.length, refs)
+    // A Handle = a surface made now. A number = a re-bake (or an older runtime / a stub): the same id
+    // keeps the Handle OBJECT — replacing it would drop the real handle and free the surface under us.
+    if (typeof r === "object" && r !== null) this._h = r
+    else if (r !== this._h.id) this._h = surfaceHandle(r)
+    return this._h.id
+  }
+
+  /** Discard the recording (and the Bitmaps its drawImage ops kept alive). */
+  reset(): this {
+    this._drawn = undefined
+    return super.reset()
   }
 
   /** @internal — bake for a `UIImage(canvas)` source: same as `_bakeSurface()` but also flags this
@@ -245,18 +191,19 @@ export class Canvas {
     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)
+    // draw-only, no relayout (the surface keeps its id and size). Feature-detected so a host without
+    // the hook just no-ops (fall back to re-assigning UIImage.src).
+    if (this._uiBound) _creatorTree.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. */
+   *  `toFile()`, or use it to "flatten" an ever-growing drawing so re-bakes stay O(1):
+   *    const next = canvas.toBitmap()                 // bakes with the previous snapshot still alive
+   *    canvas.reset(); canvas.drawImage(next, 0, 0)   // one op replaces the whole history
+   *  The canvas keeps a drawn Bitmap alive while its drawImage is recorded, and the old snapshot goes
+   *  on its own once reset() dropped it — no destroy() needed. */
   toBitmap(): Bitmap {
     return new Bitmap(_creatorCanvas.snapshot(this._bakeSurface()), this.width, this.height, this.pixelRatio)
   }
@@ -271,12 +218,14 @@ export class Canvas {
     })
   }
 
+  /** Free the surface now instead of when the canvas is dropped (an image still showing it goes blank).
+   *  The recording stays: a later bake makes a new surface. */
   destroy(): void {
-    if (this._surfaceId) _creatorCanvas.destroySurface(this._surfaceId)
+    if (this._h.id) _creatorCanvas.destroySurface(this._h.id)
+    this._h = DEAD_HANDLE
     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
   }
@@ -286,21 +235,23 @@ export class Canvas {
 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. */
+/** An immutable RGBA8 snapshot of a canvas, produced by `Canvas.toBitmap()` / `loadImage()`. 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.toFile()`), or as a
+ *  cheap "layer" you composite. Its surface is freed once nothing references the Bitmap (a canvas that
+ *  drew it keeps it until `reset()`); `destroy()` frees it early. */
 export class Bitmap {
   readonly __bitmap = true as const
-  /** @internal — a standalone `_creatorCanvas` surface (RGBA8), independent of any Canvas. */
-  readonly _surfaceId: number
+  /** @internal — the owned handle of a standalone `_creatorCanvas` surface (RGBA8), independent of any
+   *  Canvas (`_h.id` = the surface id; DEAD_HANDLE after destroy()). */
+  _h: Handle
   /** 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
+  constructor(surface: Handle | number | null, width: number, height: number, pixelRatio: number) {
+    this._h = surfaceHandle(surface)
     this.width = width
     this.height = height
     this.pixelRatio = pixelRatio
@@ -313,12 +264,16 @@ export class Bitmap {
   /** 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)
+      _creatorCanvas.toFile(this._h.id, 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) }
+  /** Free the native surface now instead of when the bitmap is dropped. It must not be drawn or encoded
+   *  afterwards (a canvas whose recording still draws it blits nothing). */
+  destroy(): void {
+    if (this._h.id) _creatorCanvas.destroySurface(this._h.id)
+    this._h = DEAD_HANDLE
+  }
 }
 
 /** Duck-type guard for a Bitmap (see `isCanvas`). */

package/src/canvas/gen/cssColor.ts

@@ -0,0 +1,224 @@
+// GENERATED by scripts/vendor-canvas.ts from engines/canvas/recorders/ts/src/cssColor.ts @ ae6bc30b952b — do not edit here.
+// Bump the submodule and run `bun run vendor:canvas`; `bun run check:canvas-ops` fails when this copy is stale.
+// The CSS color parser — the TypeScript twin of core/include/anycanvas/css_color.h: the same grammar,
+// the same name table, float32 emulated op for op (Math.fround, in the header's order), so both give
+// the same bits; tests/golden/colors holds them equal (tests/ts/cssColor.test.ts). Standalone: no
+// imports, no DOM, nothing at the top level but const declarations (the SDK vendors this file, and
+// its bundler drops top-level side effects).
+//
+// Grammar (the header has the full text): #rgb #rgba #rrggbb #rrggbbaa · rgb() / rgba() · hsl() /
+// hsla() · the 148 CSS Color 4 names · transparent · clear (the ONE non-CSS alias, = transparent).
+// Case-insensitive, surrounding ASCII whitespace ignored; a string stops at an embedded NUL, like the
+// C string the header reads. Numbers are CSS number tokens (nan / inf / hex reject), units only
+// deg / rad / grad / turn, out-of-range values clamp. Anything else is null.
+
+/** A color: straight float32 RGBA, 0..1. */
+export interface CssRgba { r: number, g: number, b: number, a: number }
+
+/** The named colors as 0xRRGGBBAA: the 148 CSS Color 4 names, transparent and clear (= transparent). */
+export const CSS_COLOR_NAMES: Readonly<Record<string, number>> = {
+  aliceblue: 0xf0f8ffff, antiquewhite: 0xfaebd7ff, aqua: 0x00ffffff, aquamarine: 0x7fffd4ff, azure: 0xf0ffffff, beige: 0xf5f5dcff,
+  bisque: 0xffe4c4ff, black: 0x000000ff, blanchedalmond: 0xffebcdff, blue: 0x0000ffff, blueviolet: 0x8a2be2ff, brown: 0xa52a2aff,
+  burlywood: 0xdeb887ff, cadetblue: 0x5f9ea0ff, chartreuse: 0x7fff00ff, chocolate: 0xd2691eff, coral: 0xff7f50ff, cornflowerblue: 0x6495edff,
+  cornsilk: 0xfff8dcff, crimson: 0xdc143cff, cyan: 0x00ffffff, darkblue: 0x00008bff, darkcyan: 0x008b8bff, darkgoldenrod: 0xb8860bff,
+  darkgray: 0xa9a9a9ff, darkgreen: 0x006400ff, darkgrey: 0xa9a9a9ff, darkkhaki: 0xbdb76bff, darkmagenta: 0x8b008bff, darkolivegreen: 0x556b2fff,
+  darkorange: 0xff8c00ff, darkorchid: 0x9932ccff, darkred: 0x8b0000ff, darksalmon: 0xe9967aff, darkseagreen: 0x8fbc8fff, darkslateblue: 0x483d8bff,
+  darkslategray: 0x2f4f4fff, darkslategrey: 0x2f4f4fff, darkturquoise: 0x00ced1ff, darkviolet: 0x9400d3ff, deeppink: 0xff1493ff, deepskyblue: 0x00bfffff,
+  dimgray: 0x696969ff, dimgrey: 0x696969ff, dodgerblue: 0x1e90ffff, firebrick: 0xb22222ff, floralwhite: 0xfffaf0ff, forestgreen: 0x228b22ff,
+  fuchsia: 0xff00ffff, gainsboro: 0xdcdcdcff, ghostwhite: 0xf8f8ffff, gold: 0xffd700ff, goldenrod: 0xdaa520ff, gray: 0x808080ff,
+  green: 0x008000ff, greenyellow: 0xadff2fff, grey: 0x808080ff, honeydew: 0xf0fff0ff, hotpink: 0xff69b4ff, indianred: 0xcd5c5cff,
+  indigo: 0x4b0082ff, ivory: 0xfffff0ff, khaki: 0xf0e68cff, lavender: 0xe6e6faff, lavenderblush: 0xfff0f5ff, lawngreen: 0x7cfc00ff,
+  lemonchiffon: 0xfffacdff, lightblue: 0xadd8e6ff, lightcoral: 0xf08080ff, lightcyan: 0xe0ffffff, lightgoldenrodyellow: 0xfafad2ff, lightgray: 0xd3d3d3ff,
+  lightgreen: 0x90ee90ff, lightgrey: 0xd3d3d3ff, lightpink: 0xffb6c1ff, lightsalmon: 0xffa07aff, lightseagreen: 0x20b2aaff, lightskyblue: 0x87cefaff,
+  lightslategray: 0x778899ff, lightslategrey: 0x778899ff, lightsteelblue: 0xb0c4deff, lightyellow: 0xffffe0ff, lime: 0x00ff00ff, limegreen: 0x32cd32ff,
+  linen: 0xfaf0e6ff, magenta: 0xff00ffff, maroon: 0x800000ff, mediumaquamarine: 0x66cdaaff, mediumblue: 0x0000cdff, mediumorchid: 0xba55d3ff,
+  mediumpurple: 0x9370dbff, mediumseagreen: 0x3cb371ff, mediumslateblue: 0x7b68eeff, mediumspringgreen: 0x00fa9aff, mediumturquoise: 0x48d1ccff, mediumvioletred: 0xc71585ff,
+  midnightblue: 0x191970ff, mintcream: 0xf5fffaff, mistyrose: 0xffe4e1ff, moccasin: 0xffe4b5ff, navajowhite: 0xffdeadff, navy: 0x000080ff,
+  oldlace: 0xfdf5e6ff, olive: 0x808000ff, olivedrab: 0x6b8e23ff, orange: 0xffa500ff, orangered: 0xff4500ff, orchid: 0xda70d6ff,
+  palegoldenrod: 0xeee8aaff, palegreen: 0x98fb98ff, paleturquoise: 0xafeeeeff, palevioletred: 0xdb7093ff, papayawhip: 0xffefd5ff, peachpuff: 0xffdab9ff,
+  peru: 0xcd853fff, pink: 0xffc0cbff, plum: 0xdda0ddff, powderblue: 0xb0e0e6ff, purple: 0x800080ff, rebeccapurple: 0x663399ff,
+  red: 0xff0000ff, rosybrown: 0xbc8f8fff, royalblue: 0x4169e1ff, saddlebrown: 0x8b4513ff, salmon: 0xfa8072ff, sandybrown: 0xf4a460ff,
+  seagreen: 0x2e8b57ff, seashell: 0xfff5eeff, sienna: 0xa0522dff, silver: 0xc0c0c0ff, skyblue: 0x87ceebff, slateblue: 0x6a5acdff,
+  slategray: 0x708090ff, slategrey: 0x708090ff, snow: 0xfffafaff, springgreen: 0x00ff7fff, steelblue: 0x4682b4ff, tan: 0xd2b48cff,
+  teal: 0x008080ff, thistle: 0xd8bfd8ff, tomato: 0xff6347ff, turquoise: 0x40e0d0ff, violet: 0xee82eeff, wheat: 0xf5deb3ff,
+  white: 0xffffffff, whitesmoke: 0xf5f5f5ff, yellow: 0xffff00ff, yellowgreen: 0x9acd32ff,
+  transparent: 0x00000000, clear: 0x00000000,
+}
+
+// float32 arithmetic: every operation of the header, rounded as it rounds (a double op on two float32
+// operands, rounded once to float32, is the float32 op).
+const f = Math.fround
+const T13 = f(1 / 3), T16 = f(1 / 6), T23 = f(2 / 3), PI = f(3.14159265), GRAD = f(0.9)
+
+// ASCII only, by char code (no toLowerCase / trim: they know Unicode, the header does not).
+const isSpace = (c: number): boolean => c === 32 || (c >= 9 && c <= 13)
+const isDigit = (c: number): boolean => c >= 48 && c <= 57
+const lower = (c: number): number => c >= 65 && c <= 90 ? c + 32 : c
+const isLetter = (c: number): boolean => { const l = lower(c); return l >= 97 && l <= 122 }
+const hexNibble = (c: number): number => {
+  const l = lower(c)
+  return l >= 48 && l <= 57 ? l - 48 : l >= 97 && l <= 102 ? l - 87 : -1
+}
+const equalsLower = (s: string, at: number, n: number, word: string): boolean => {
+  if (n !== word.length) return false
+  for (let i = 0; i < n; i++) if (lower(s.charCodeAt(at + i)) !== word.charCodeAt(i)) return false
+  return true
+}
+
+// The CSS number token at s[at..end): [+-]? (digits (. digits*)? | . digits) ([eE] [+-]? digits)? → its
+// length, 0 when there is none.
+const numberLength = (s: string, at: number, end: number): number => {
+  let i = at
+  if (i < end && (s.charCodeAt(i) === 43 || s.charCodeAt(i) === 45)) i++
+  let intDigits = 0, fracDigits = 0
+  while (i < end && isDigit(s.charCodeAt(i))) { i++; intDigits++ }
+  if (i < end && s.charCodeAt(i) === 46) {
+    let j = i + 1
+    while (j < end && isDigit(s.charCodeAt(j))) { j++; fracDigits++ }
+    if (intDigits > 0 || fracDigits > 0) i = j
+  }
+  if (intDigits === 0 && fracDigits === 0) return 0
+  if (i < end && (s.charCodeAt(i) === 101 || s.charCodeAt(i) === 69)) {
+    let j = i + 1
+    if (j < end && (s.charCodeAt(j) === 43 || s.charCodeAt(j) === 45)) j++
+    if (j < end && isDigit(s.charCodeAt(j))) {
+      while (j < end && isDigit(s.charCodeAt(j))) j++
+      i = j
+    }
+  }
+  return i - at
+}
+
+interface Arg { v: number, percent: boolean }
+
+// The arguments between the parentheses, s[at..end): 3 or 4 numbers with a % flag each, or null.
+const parseArgs = (s: string, at: number, end: number): Arg[] | null => {
+  const out: Arg[] = []
+  let i = at
+  while (i < end) {
+    while (i < end && (isSpace(s.charCodeAt(i)) || s.charCodeAt(i) === 44 || s.charCodeAt(i) === 47)) i++
+    if (i >= end) break
+    const len = numberLength(s, i, end)
+    if (len === 0 || len >= 64) return null   // the header's stack buffer
+    let v = f(parseFloat(s.slice(i, i + len)))
+    i += len
+    let percent = false
+    if (i < end && s.charCodeAt(i) === 37) {
+      percent = true
+      i++
+    } else if (i < end && isLetter(s.charCodeAt(i))) {
+      const u = i
+      while (i < end && isLetter(s.charCodeAt(i))) i++
+      const ul = i - u
+      if (equalsLower(s, u, ul, "deg")) {
+        // degrees: the number as it is
+      } else if (equalsLower(s, u, ul, "rad")) {
+        v = f(v * 180)
+        v = f(v / PI)
+      } else if (equalsLower(s, u, ul, "turn")) {
+        v = f(v * 360)
+      } else if (equalsLower(s, u, ul, "grad")) {
+        v = f(v * GRAD)
+      } else {
+        return null
+      }
+    }
+    if (!Number.isFinite(v)) return null
+    if (out.length === 4) return null
+    out.push({ v, percent })
+  }
+  return out.length >= 3 ? out : null
+}
+
+const clamp01 = (v: number): number => v < 0 ? 0 : v > 1 ? 1 : v
+
+const hueToRgb = (p: number, q: number, t: number): number => {
+  if (t < 0) t = f(t + 1)
+  if (t > 1) t = f(t - 1)
+  const d = f(q - p)
+  if (t < T16) return f(p + f(f(d * 6) * t))
+  if (t < 0.5) return q
+  if (t < T23) return f(p + f(f(d * f(T23 - t)) * 6))
+  return p
+}
+
+const fromBytes = (r: number, g: number, b: number, a: number): CssRgba => ({ r: f(r / 255), g: f(g / 255), b: f(b / 255), a: f(a / 255) })
+
+/** A CSS color → straight float32 RGBA, or null when `input` is not a color. */
+export const parseCssColor = (input: string): CssRgba | null => {
+  if (typeof input !== "string") return null
+  const nul = input.indexOf("\0")
+  const s = nul < 0 ? input : input.slice(0, nul)
+  let b = 0, e = s.length
+  while (b < e && isSpace(s.charCodeAt(b))) b++
+  while (e > b && isSpace(s.charCodeAt(e - 1))) e--
+  const n = e - b
+  if (n === 0) return null
+
+  if (s.charCodeAt(b) === 35) {   // #
+    const digits = n - 1
+    if (digits !== 3 && digits !== 4 && digits !== 6 && digits !== 8) return null
+    const v: number[] = []
+    for (let i = 0; i < digits; i++) {
+      const h = hexNibble(s.charCodeAt(b + 1 + i))
+      if (h < 0) return null
+      v.push(h)
+    }
+    return digits <= 4
+      ? fromBytes(v[0] * 17, v[1] * 17, v[2] * 17, digits === 4 ? v[3] * 17 : 255)
+      : fromBytes(v[0] * 16 + v[1], v[2] * 16 + v[3], v[4] * 16 + v[5], digits === 8 ? v[6] * 16 + v[7] : 255)
+  }
+
+  const paren = s.indexOf("(", b)
+  if (paren >= 0 && paren < e && s.charCodeAt(e - 1) === 41) {
+    const args = parseArgs(s, paren + 1, e - 1)
+    if (!args) return null
+    const alpha = args.length === 4 ? clamp01(args[3].percent ? f(args[3].v / 100) : args[3].v) : 1
+    const fnLen = paren - b
+    if (equalsLower(s, b, fnLen, "rgb") || equalsLower(s, b, fnLen, "rgba")) {
+      const channel = (x: Arg): number => clamp01(x.percent ? f(x.v / 100) : f(x.v / 255))
+      return { r: channel(args[0]), g: channel(args[1]), b: channel(args[2]), a: alpha }
+    }
+    if (equalsLower(s, b, fnLen, "hsl") || equalsLower(s, b, fnLen, "hsla")) {
+      let h = args[0].v % 360   // fmodf: exact, the sign of the dividend
+      if (h < 0) h = f(h + 360)
+      h = f(h / 360)
+      const sat = clamp01(f(args[1].v / 100))
+      const l = clamp01(f(args[2].v / 100))
+      if (sat <= 0) return { r: l, g: l, b: l, a: alpha }
+      const q = l < 0.5 ? f(l * f(1 + sat)) : f(f(l + sat) - f(l * sat))
+      const p = f(f(2 * l) - q)
+      return {
+        r: clamp01(hueToRgb(p, q, f(h + T13))),
+        g: clamp01(hueToRgb(p, q, h)),
+        b: clamp01(hueToRgb(p, q, f(h - T13))),
+        a: alpha,
+      }
+    }
+    return null
+  }
+
+  // A name: looked up only when it can be one ('lightgoldenrodyellow' is the longest, 20).
+  if (n > 20) return null
+  let name = ""
+  for (let i = b; i < e; i++) name += String.fromCharCode(lower(s.charCodeAt(i)))
+  if (!Object.prototype.hasOwnProperty.call(CSS_COLOR_NAMES, name)) return null
+  const v = CSS_COLOR_NAMES[name]
+  return fromBytes(v >>> 24, (v >>> 16) & 255, (v >>> 8) & 255, v & 255)
+}
+
+/** A float channel → a byte, as the header's toByte: float32, clamp (NaN → 0), round half up (0.5 → 128). */
+export const cssToByte = (v: number): number => {
+  const x = f(v)
+  if (!(x > 0)) return 0
+  if (x >= 1) return 255
+  const s = f(x * 255)
+  return Math.floor(f(s + 0.5))
+}
+
+/** 0xRRGGBBAA (unsigned). */
+export const cssRgba8 = (c: CssRgba): number =>
+  ((cssToByte(c.r) << 24) | (cssToByte(c.g) << 16) | (cssToByte(c.b) << 8) | cssToByte(c.a)) >>> 0
+
+/** '#rrggbbaa', lower-case. */
+export const cssHex8 = (c: CssRgba): string => "#" + cssRgba8(c).toString(16).padStart(8, "0")