lecodes-web-canvas 2.0.0

package/src/layout/creatorUi/loadCreatorUi.ts

@@ -0,0 +1,87 @@
+// Loads the reused creator-ui (Yoga + style parser) WASM. The glue is built `-sENVIRONMENT=web`,
+// so headless (Bun) needs a `window` shim and the wasm bytes handed in via `wasmBinary` (proven to
+// work in a probe: shim + wasmBinary → a full layout round-trip).
+//
+// This file is BROWSER-SAFE: it has no Node imports. The headless (fs-based) loader lives in
+// `loadCreatorUiNode.ts` so a browser bundle (viewer/frontend) never pulls `node:fs` into its graph.
+
+/** The subset of the emscripten module the adapter uses. */
+export interface CreatorUiModule {
+  _malloc(size: number): number
+  _free(ptr: number): void
+  stringToUTF8(str: string, ptr: number, maxBytes: number): void
+  UTF8ToString(ptr: number): string
+  lengthBytesUTF8(str: string): number
+  addFunction(fn: (...args: any[]) => any, sig: string): number
+  HEAPF32: Float32Array
+  HEAPU32: Uint32Array
+
+  _setMeasureFunc(funcPtr: number): void
+  // The paint state (creator-ui/paint.gen.h): the dirty records of the frame + a node's record in place.
+  _paintCollect(): number
+  _paintNodes(): number
+  _paintRecords(): number
+  _cuiPaintOf(nodePtr: number): number
+  _cuiStringOf(id: number): number
+  _cuiGradientOf(id: number, outCountPtr: number): number
+
+  _createNodeRoot(screenId: number): number
+  _createNode(parentId: number, index: number, hasMeasureFunc: number): number
+  _removeNode(parentId: number, nodeId: number): void
+  _freeNode(rootId: number): void
+  _freeWidget(rootId: number): void
+
+  _setFloatExt(layer: number, nodeId: number, keyPtr: number, value: number): void
+  _setStringExt(layer: number, nodeId: number, keyPtr: number, valuePtr: number): void
+  _resetProp(nodeId: number, keyPtr: number): void
+  // Layer-scoped clear (`prop: null` inside a `$class` block, `$landscape`/`$portrait` too): the
+  // null lives in `layer` (reset semantics while active); layer 256 keeps _resetProp's erase semantics.
+  _resetPropExt(layer: number, nodeId: number, keyPtr: number): void
+  _markNodeDirty(nodeId: number): void
+
+  _getLayer(nodeId: number, keyPtr: number): number
+  _enableNodeLayer(nodeId: number, layer: number): void
+  _disableNodeLayer(nodeId: number, layer: number): void
+
+  _calculate(rootId: number, width: number, height: number): void
+  _calculateWidget(rootId: number, width: number, height: number): void
+  _getLayoutPointer(nodeId: number, outPtr: number): number
+  _getPaddingPointer(nodeId: number, outPtr: number): number
+  _getScreenId(nodeId: number): number
+  _getContentHeight(nodeId: number): number
+  _getContentWidth(nodeId: number): number
+
+  _setConditionValue(width: number, height: number): void
+  // (top, right, bottom, left[, nodePtr]) — CSS order; passing a node re-applies the dynamic
+  // `safe-*` styles over that subtree immediately (recalcPaddings).
+  _setSafePaddings(top: number, right: number, bottom: number, left: number, nodePtr?: number): void
+  // Which edges are exact-height system bars (comfort-* adds its knob) vs clearance insets
+  // (comfort-* floors). Bitmask: top=1, right=2, bottom=4, left=8. Call before _setSafePaddings.
+  _setSafeAreaBars(barEdges: number): void
+
+  // Theme variables (docs/ui-theme-plan.md): stage one key (both args are C strings; value 0
+  // removes), then _applyTheme() re-resolves dynamic styles on every live root — returns 1 when
+  // anything re-dispatched (relayout + repaint wanted).
+  _setThemeValue(namePtr: number, valuePtr: number): void
+  _applyTheme(): number
+
+  // The core's color parser (color.h): CSS color string → packed 0xRRGGBBAA (web build). The
+  // SAME parser node color styles go through — used for theme color values that never ride a
+  // node (the themable default text color).
+  _getColor(valuePtr: number): number
+}
+
+type CreateModule = (opts: Record<string, unknown>) => Promise<CreatorUiModule>
+
+export type { CreateModule }
+
+/** Load the module from a caller-provided emscripten factory + wasm bytes (browser path). */
+export async function loadCreatorUiFromModule(
+  createModule: CreateModule,
+  wasmBinary: ArrayBuffer | Uint8Array,
+): Promise<CreatorUiModule> {
+  if (typeof (globalThis as any).window === "undefined") {
+    ;(globalThis as any).window = globalThis
+  }
+  return createModule({ wasmBinary, locateFile: () => "" })
+}

package/src/layout/creatorUi/paint-read.ts

@@ -0,0 +1,131 @@
+// The paint state reader (creator-ui/paint.gen.h, CuiPaint.gen.ts): the runtime keeps one resolved
+// paint record per node; this renderer READS it — the dirty records `_paintCollect` hands out once
+// per frame, or a node's record in place (`_cuiPaintOf`) whenever it measures. The per-prop style
+// handlers this file replaced (2026-09-24) wrote the same ResolvedStyle field by field; here one
+// record write fills it, and the text style arrives EFFECTIVE (the core inherits), so no ancestor
+// walk remains anywhere in the renderer.
+import type { ResolvedStyle } from "../../types"
+import { CUI_FIELDS, CUI_NAMES, CUI_PAINT_WORDS, CuiFontStyle, CuiOverflow, CuiScrollDirection, cuiBit } from "../CuiPaint.gen"
+import { readGradientStructs } from "./readGradient"
+
+/** The wasm module surface the reader needs (a subset of CreatorUiModule). */
+export interface PaintModule {
+  HEAPF32: Float32Array
+  HEAPU32: Uint32Array
+  UTF8ToString(ptr: number): string
+  _malloc(size: number): number
+  _paintCollect(): number
+  _paintNodes(): number
+  _paintRecords(): number
+  _cuiPaintOf(nodePtr: number): number
+  _cuiStringOf(id: number): number
+  _cuiGradientOf(id: number, outCountPtr: number): number
+}
+
+const F = CUI_FIELDS
+const ALIGN: ResolvedStyle["textAlign"][] = ["start", "center", "end", "start", "end"]   // start center end left right
+
+let countPtr = 0
+
+/** Read the record at `ptr` (a word-aligned CUIPaint) into `style`. */
+export function readPaintRecord(M: PaintModule, ptr: number, style: ResolvedStyle): void {
+  const u32 = M.HEAPU32, f32 = M.HEAPF32
+  const w = ptr >>> 2
+  const presentLo = u32[w], presentHi = u32[w + 1]
+  const has = (bit: number) => cuiBit(presentLo, presentHi, bit)
+  const str = (word: number): string | undefined => {
+    const id = u32[w + word]
+    return id === 0 ? undefined : M.UTF8ToString(M._cuiStringOf(id))
+  }
+
+  // box
+  style.backgroundColor = u32[w + F.backgroundColor.word] >>> 0
+  style.opacity = f32[w + F.opacity.word]
+  style.dim = f32[w + F.dim.word]
+  style.display = CUI_NAMES.display[u32[w + F.display.word]]
+  style.overflow = u32[w + F.overflow.word] === CuiOverflow.hidden ? "hidden" : "visible"
+  style.scrollAxis = u32[w + F.scrollDirection.word] === CuiScrollDirection.horizontal ? "x" : "y"
+  // borders: the core fans borderWidth / borderColor out into the four sides (paint.cpp)
+  style.border = {
+    top: { width: f32[w + F.borderTopWidth.word], color: u32[w + F.borderTopColor.word] >>> 0 },
+    right: { width: f32[w + F.borderRightWidth.word], color: u32[w + F.borderRightColor.word] >>> 0 },
+    bottom: { width: f32[w + F.borderBottomWidth.word], color: u32[w + F.borderBottomColor.word] >>> 0 },
+    left: { width: f32[w + F.borderLeftWidth.word], color: u32[w + F.borderLeftColor.word] >>> 0 },
+  }
+  style.borderRadius = {
+    tl: f32[w + F.borderTopLeftRadius.word], tr: f32[w + F.borderTopRightRadius.word],
+    br: f32[w + F.borderBottomRightRadius.word], bl: f32[w + F.borderBottomLeftRadius.word],
+  }
+  // background layers
+  style.backgroundImage = str(F.backgroundImage.word)
+  style.backgroundSize = CUI_NAMES.backgroundSize[u32[w + F.backgroundSize.word]] as ResolvedStyle["backgroundSize"]
+  const gradientId = u32[w + F.backgroundGradient.word]
+  if (gradientId === 0) style.backgroundGradients = undefined
+  else {
+    if (countPtr === 0) countPtr = M._malloc(4)
+    const gp = M._cuiGradientOf(gradientId, countPtr)
+    const count = M.HEAPU32[countPtr >>> 2]
+    style.backgroundGradients = gp !== 0 && count > 0 ? readGradientStructs(M.HEAPF32, M.HEAPU32, gp, count) : undefined
+  }
+  // transform: the 2D affine [a,b,c,d,e,f] of the 3x3 (column-major m0 m1 m3 m4 m6 m7); identity = absent
+  const t = w + F.transform.word
+  const a = f32[t], b = f32[t + 1], c = f32[t + 3], d = f32[t + 4], e = f32[t + 6], f = f32[t + 7]
+  style.transform = a === 1 && b === 0 && c === 0 && d === 1 && e === 0 && f === 0 ? undefined : [a, b, c, d, e, f]
+  const o = w + F.transformOrigin.word
+  style.transformOrigin = { x: f32[o], y: f32[o + 1], xPercent: u32[o + 2] !== 0, yPercent: u32[o + 3] !== 0 }
+
+  // text (effective; absent = the renderer default — core/text.ts DEFAULTS)
+  style.color = has(F.color.bit) ? u32[w + F.color.word] >>> 0 : undefined
+  style.fontFamily = has(F.fontFamily.bit) ? str(F.fontFamily.word) : undefined
+  style.fontSize = f32[w + F.fontSize.word]
+  style.fontWeight = f32[w + F.fontWeight.word]
+  style.fontStyle = u32[w + F.fontStyle.word] === CuiFontStyle.italic ? "italic" : "normal"
+  style.lineHeight = f32[w + F.lineHeight.word]
+  style.letterSpacing = f32[w + F.letterSpacing.word]
+  style.textAlign = ALIGN[u32[w + F.textAlign.word]] ?? "start"
+  style.textDecoration = CUI_NAMES.textDecoration[u32[w + F.textDecoration.word]] as ResolvedStyle["textDecoration"]
+  style.lineClamp = f32[w + F.lineClamp.word]
+  style.textOverflow = CUI_NAMES.textOverflow[u32[w + F.textOverflow.word]] as ResolvedStyle["textOverflow"]
+
+  // image / input / widget (presence props: absent = the renderer default)
+  style.objectFit = CUI_NAMES.objectFit[u32[w + F.objectFit.word]] as ResolvedStyle["objectFit"]
+  style.tintColor = has(F.tintColor.bit) ? u32[w + F.tintColor.word] >>> 0 : undefined
+  style.placeholder = str(F.placeholder.word)
+  style.placeholderColor = has(F.placeholderColor.bit) ? u32[w + F.placeholderColor.word] >>> 0 : undefined
+  style.inputType = CUI_NAMES.type[u32[w + F.type.word]]
+  style.overlayColor = has(F.overlayColor.bit) ? u32[w + F.overlayColor.word] >>> 0 : undefined
+}
+
+/** The node's record has changes the frame's sync has not taken yet. */
+export function paintPending(M: PaintModule, nodePtr: number): boolean {
+  const p = M._cuiPaintOf(nodePtr)
+  if (p === 0) return false
+  const w = p >>> 2
+  return M.HEAPU32[w + 2] !== 0 || M.HEAPU32[w + 3] !== 0
+}
+
+/** Read a live node's current record in place (a measure that runs before this frame's sync). */
+export function readPaintOf(M: PaintModule, nodePtr: number, style: ResolvedStyle): boolean {
+  const p = M._cuiPaintOf(nodePtr)
+  if (p === 0) return false
+  readPaintRecord(M, p, style)
+  return true
+}
+
+/**
+ * Once per frame, before layout: every record that changed since the last call, into its node's
+ * style via `apply`. Returns the number of records taken.
+ */
+export function syncPaint(M: PaintModule, apply: (nodePtr: number, read: (style: ResolvedStyle) => void) => void): number {
+  const n = M._paintCollect()
+  if (n === 0) return 0
+  const nodes = M._paintNodes() >>> 2
+  const records = M._paintRecords()
+  for (let i = 0; i < n; i++) {
+    const ptr = M.HEAPU32[nodes + i]
+    const rec = records + i * CUI_PAINT_WORDS * 4
+    apply(ptr, (style) => readPaintRecord(M, rec, style))
+  }
+  return n
+}
+

package/src/layout/creatorUi/readGradient.ts

@@ -0,0 +1,62 @@
+import type { Gradient, GradientStop, RadialExtent } from "../../types"
+
+// Decodes the creator-ui CUIGradient struct (creator-ui/include/creator-ui/creator-ui.h) out of the
+// wasm heap. wasm32 layout, all fields 4-byte aligned:
+//   CUIGradient { float angle@0; u32 type@4; u32 stopCount@8; u32 _pad@12; CUIGradientStop* stops@16;
+//                 u32 shape@20; u32 extent@24; float cx@28; float cy@32;
+//                 float rx@36; float ry@40; u32 rUnitX@44; u32 rUnitY@48 }
+//   CUIGradientStop { u32 color@0; float position@4 }  (8 bytes, tightly packed)
+// The radial fields are appended AFTER the 4-byte `stops` pointer, so the linear prefix
+// (angle/type/stopCount/stops) is byte-identical to before. `color` is COLOR_FORMAT = 0xRRGGBBAA on
+// web (== our RGBA), so no conversion is needed. extent == 4 means explicit rx/ry (rUnit 0 = px, 1 =
+// box-axis fraction). Pure (takes heap views) so it can be unit-tested with a synthetic buffer.
+
+const EXTENTS: RadialExtent[] = ["farthest-corner", "closest-side", "closest-corner", "farthest-side"]
+
+// sizeof(CUIGradient) on wasm32 (13 × 4-byte fields), pinned by a static_assert in gradient.h. The
+// multi-layer handler hands us a pointer to `count` of these laid out back-to-back.
+const CUI_GRADIENT_STRIDE = 52
+
+/** Decode a `count`-long CUIGradient array (the background-image layer stack, [0] = topmost). */
+export function readGradientStructs(f32: Float32Array, u32: Uint32Array, ptr: number, count: number): Gradient[] {
+  const out: Gradient[] = []
+  for (let k = 0; k < count; k++) out.push(readGradientStruct(f32, u32, ptr + k * CUI_GRADIENT_STRIDE))
+  return out
+}
+
+export function readGradientStruct(f32: Float32Array, u32: Uint32Array, ptr: number): Gradient {
+  const i = ptr >> 2
+  const angle = f32[i]
+  const type = u32[i + 1]
+  const stopCount = u32[i + 2]
+  const stopsPtr = u32[i + 4]
+
+  const stops: GradientStop[] = []
+  for (let s = 0; s < stopCount; s++) {
+    const b = (stopsPtr + s * 8) >> 2
+    stops.push({ color: u32[b] >>> 0, position: f32[b + 1] })
+  }
+
+  if (type === 1) {
+    const extentCode = u32[i + 6]
+    const base = {
+      type: "radial" as const,
+      shape: (u32[i + 5] === 1 ? "circle" : "ellipse") as "circle" | "ellipse",
+      cx: f32[i + 7],
+      cy: f32[i + 8],
+      stops,
+    }
+    if (extentCode === 4) {
+      return {
+        ...base,
+        extent: "explicit",
+        rx: f32[i + 9],
+        ry: f32[i + 10],
+        rxUnit: u32[i + 11] === 1 ? "fraction" : "px",
+        ryUnit: u32[i + 12] === 1 ? "fraction" : "px",
+      }
+    }
+    return { ...base, extent: EXTENTS[extentCode] ?? "farthest-corner" }
+  }
+  return { type: "linear", angle, stops }
+}

package/src/paint/Canvas2DPainter.ts

@@ -0,0 +1,258 @@
+import type { BorderRadius, Gradient, ImageInfo, RadialGradient, Rect, RGBA } from "../types"
+import type { FontSpec } from "../host/Host"
+import type { Borders, DrawImageOpts, Painter } from "./Painter"
+import { rgbaToCss } from "../core/util/colors"
+import { clampRadius, computeObjectFit, gradientLine, radialGeometry } from "../core/util/geometry"
+
+/** Painter backend over a CanvasRenderingContext2D (browser). */
+type AnyCtx = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D
+
+export class Canvas2DPainter implements Painter {
+  private ctx: AnyCtx
+  private dpr: number
+  // Stack of in-progress opacity groups: each captures the parent ctx + an offscreen layer + alpha.
+  private groups: { parent: AnyCtx; layer: HTMLCanvasElement | OffscreenCanvas; alpha: number }[] = []
+
+  constructor(ctx: CanvasRenderingContext2D, dpr = 1) {
+    this.ctx = ctx
+    this.dpr = dpr
+  }
+
+  beginGroup(alpha: number) {
+    const cur = this.ctx
+    const w = (cur.canvas as HTMLCanvasElement | OffscreenCanvas).width
+    const h = (cur.canvas as HTMLCanvasElement | OffscreenCanvas).height
+    let layer: HTMLCanvasElement | OffscreenCanvas
+    if (typeof OffscreenCanvas !== "undefined") {
+      layer = new OffscreenCanvas(w, h)
+    } else {
+      layer = document.createElement("canvas")
+      layer.width = w
+      layer.height = h
+    }
+    const lctx = (layer as any).getContext("2d") as AnyCtx
+    lctx.setTransform(cur.getTransform()) // paint the subtree in the same coordinate space
+    this.groups.push({ parent: cur, layer, alpha })
+    this.ctx = lctx
+  }
+
+  endGroup() {
+    const g = this.groups.pop()
+    if (!g) return
+    this.ctx = g.parent
+    this.ctx.save()
+    this.ctx.setTransform(1, 0, 0, 1, 0, 0) // composite the layer in device pixels
+    this.ctx.globalAlpha *= g.alpha
+    this.ctx.drawImage(g.layer as CanvasImageSource, 0, 0)
+    this.ctx.restore()
+  }
+
+  beginFrame(width: number, height: number) {
+    const { ctx, dpr } = this
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0)
+    ctx.clearRect(0, 0, width, height)
+    ctx.globalAlpha = 1
+  }
+  endFrame() {}
+
+  save() {
+    this.ctx.save()
+  }
+  restore() {
+    this.ctx.restore()
+  }
+  setAlpha(multiplier: number) {
+    this.ctx.globalAlpha *= multiplier
+  }
+  translate(x: number, y: number) {
+    this.ctx.translate(x, y)
+  }
+  scale(sx: number, sy: number) {
+    this.ctx.scale(sx, sy)
+  }
+  transform(a: number, b: number, c: number, d: number, e: number, f: number) {
+    this.ctx.transform(a, b, c, d, e, f)
+  }
+
+  /** Append a (rounded) rect sub-path to the current path — no beginPath, so callers can build
+   *  multi-subpath paths (e.g. an even-odd ring). */
+  private addRectPath(rect: Rect, radius?: BorderRadius) {
+    const ctx = this.ctx
+    if (radius && (radius.tl || radius.tr || radius.br || radius.bl)) {
+      ctx.roundRect(rect.x, rect.y, rect.width, rect.height, [radius.tl, radius.tr, radius.br, radius.bl])
+    } else {
+      ctx.rect(rect.x, rect.y, rect.width, rect.height)
+    }
+  }
+
+  private path(rect: Rect, radius?: BorderRadius) {
+    this.ctx.beginPath()
+    this.addRectPath(rect, radius)
+  }
+
+  clipRoundRect(rect: Rect, radius?: BorderRadius) {
+    this.path(rect, radius)
+    this.ctx.clip()
+  }
+
+  fillRoundRect(rect: Rect, radius: BorderRadius | undefined, color: RGBA) {
+    this.path(rect, radius)
+    this.ctx.fillStyle = rgbaToCss(color)
+    this.ctx.fill()
+  }
+
+  clearRoundRect(rect: Rect, radius: BorderRadius | undefined) {
+    const ctx = this.ctx
+    ctx.save()
+    ctx.globalCompositeOperation = "destination-out"
+    ctx.globalAlpha = 1
+    this.path(rect, radius)
+    ctx.fillStyle = "#000"
+    ctx.fill()
+    ctx.restore()
+  }
+
+  fillGradient(rect: Rect, radius: BorderRadius | undefined, gradient: Gradient) {
+    if (gradient.type === "radial") {
+      this.fillRadial(rect, radius, gradient)
+      return
+    }
+    const { x0, y0, x1, y1 } = gradientLine(gradient.angle, rect)
+    const grad = this.ctx.createLinearGradient(x0, y0, x1, y1)
+    for (const stop of gradient.stops) grad.addColorStop(Math.max(0, Math.min(1, stop.position)), rgbaToCss(stop.color))
+    this.path(rect, radius)
+    this.ctx.fillStyle = grad
+    this.ctx.fill()
+  }
+
+  private fillRadial(rect: Rect, radius: BorderRadius | undefined, gradient: RadialGradient) {
+    const { cx, cy, rx, ry } = radialGeometry(gradient, rect)
+    const ctx = this.ctx
+    // createRadialGradient only makes circles; scale the context anisotropically so a unit-radius
+    // circle becomes the rx×ry ellipse. Clip to the (rounded) rect first — the clip is captured in
+    // the pre-scale space, so it stays put while we paint the ellipse in the scaled space.
+    const sx = rx || 1e-6
+    const sy = ry || 1e-6
+    ctx.save()
+    this.path(rect, radius)
+    ctx.clip()
+    ctx.translate(cx, cy)
+    ctx.scale(sx, sy)
+    const grad = ctx.createRadialGradient(0, 0, 0, 0, 0, 1)
+    for (const stop of gradient.stops) grad.addColorStop(Math.max(0, Math.min(1, stop.position)), rgbaToCss(stop.color))
+    ctx.fillStyle = grad
+    // Cover the whole clipped rect in the scaled coordinate space (canvas extends the last stop
+    // outward, so pixels past the ellipse edge get the final color, matching CSS).
+    const u0 = (rect.x - cx) / sx
+    const u1 = (rect.x + rect.width - cx) / sx
+    const v0 = (rect.y - cy) / sy
+    const v1 = (rect.y + rect.height - cy) / sy
+    ctx.fillRect(u0, v0, u1 - u0, v1 - v0)
+    ctx.restore()
+  }
+
+  strokeBorder(rect: Rect, radius: BorderRadius | undefined, sides: Borders) {
+    const ctx = this.ctx
+    const present = (["top", "right", "bottom", "left"] as const).filter((s) => sides[s])
+    const uniform =
+      present.length === 4 &&
+      present.every((s) => sides[s]!.width === sides.top!.width && sides[s]!.color === sides.top!.color)
+
+    if (uniform) {
+      const w = sides.top!.width
+      // Border-box: the border lies fully INSIDE rect. Fill the ring between the outer rounded-rect
+      // and an inner rounded-rect inset by the border width (inner corner radius = outer − w), as an
+      // even-odd fill. We do NOT use a centred ctx.stroke(): a stroke straddles the path (half would
+      // sit outside the box), and the inset-path trick relied on roundRect clamping its radius — which
+      // @napi-rs/canvas (skia) does differently than browsers, so the border leaked outside the box.
+      const outer = clampRadius(radius, rect)
+      ctx.beginPath()
+      this.addRectPath(rect, outer)
+      const inner: Rect = { x: rect.x + w, y: rect.y + w, width: rect.width - 2 * w, height: rect.height - 2 * w }
+      if (inner.width > 0 && inner.height > 0) {
+        const innerRadius = outer && clampRadius(
+          {
+            tl: Math.max(0, outer.tl - w), tr: Math.max(0, outer.tr - w),
+            br: Math.max(0, outer.br - w), bl: Math.max(0, outer.bl - w),
+          },
+          inner,
+        )
+        this.addRectPath(inner, innerRadius || undefined)
+      }
+      ctx.fillStyle = rgbaToCss(sides.top!.color)
+      ctx.fill("evenodd")
+      return
+    }
+
+    // Per-side fallback: straight edges (radius ignored for mismatched borders).
+    for (const s of present) {
+      const { width, color } = sides[s]!
+      ctx.fillStyle = rgbaToCss(color)
+      if (s === "top") ctx.fillRect(rect.x, rect.y, rect.width, width)
+      else if (s === "bottom") ctx.fillRect(rect.x, rect.y + rect.height - width, rect.width, width)
+      else if (s === "left") ctx.fillRect(rect.x, rect.y, width, rect.height)
+      else ctx.fillRect(rect.x + rect.width - width, rect.y, width, rect.height)
+    }
+  }
+
+  private scratch?: OffscreenCanvas | HTMLCanvasElement
+  private scratchCtx?: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D
+  private getScratch(w: number, h: number) {
+    if (!this.scratch) {
+      this.scratch = typeof OffscreenCanvas !== "undefined" ? new OffscreenCanvas(w, h) : document.createElement("canvas")
+      this.scratchCtx = (this.scratch as any).getContext("2d")
+    }
+    if (this.scratch.width < w || this.scratch.height < h) {
+      this.scratch.width = Math.max(this.scratch.width, w)
+      this.scratch.height = Math.max(this.scratch.height, h)
+    }
+    return this.scratchCtx!
+  }
+
+  drawImage(image: ImageInfo, srcRect: Rect | null, dst: Rect, opts: DrawImageOpts) {
+    if (!image.handle) return
+    // An explicit crop fills the box; otherwise resolve object-fit.
+    const { src, dst: d } = srcRect
+      ? { src: srcRect, dst }
+      : computeObjectFit(image.naturalWidth, image.naturalHeight, dst, opts.fit)
+    // The destination in DEVICE pixels: what a vector source rasterizes at, and the tint scratch's
+    // size — the frame is painted under the dpr transform, so a CSS-px scratch would be upscaled.
+    const dw = Math.max(1, Math.ceil(d.width * this.dpr))
+    const dh = Math.max(1, Math.ceil(d.height * this.dpr))
+    const handle = (image.rasterize ? image.rasterize(dw, dh) : image.handle) as CanvasImageSource
+
+    // When we're drawing the WHOLE image (no atlas crop, not a cover-crop) draw it WITHOUT a source
+    // rect. A viewBox-only SVG `<img>` has the browser's default 300×150 raster, so a source crop
+    // (computed from the viewBox size) samples the wrong region and the icon vanishes — drawing the
+    // whole image straight into the box lets the backend re-rasterize the SVG to fit (matches the DOM,
+    // and keeps the working tinted/scratch path consistent with the direct path).
+    const whole = !srcRect && opts.fit !== "cover"
+
+    if (opts.tint === undefined) {
+      if (whole) this.ctx.drawImage(handle, d.x, d.y, d.width, d.height)
+      else this.ctx.drawImage(handle, src.x, src.y, src.width, src.height, d.x, d.y, d.width, d.height)
+      return
+    }
+    // Tint on an offscreen so `source-in` only recolors the image pixels.
+    const sc = this.getScratch(dw, dh)
+    sc.clearRect(0, 0, dw, dh)
+    sc.globalCompositeOperation = "source-over"
+    if (whole) sc.drawImage(handle, 0, 0, dw, dh)
+    else sc.drawImage(handle, src.x, src.y, src.width, src.height, 0, 0, dw, dh)
+    sc.globalCompositeOperation = "source-in"
+    sc.fillStyle = rgbaToCss(opts.tint)
+    sc.fillRect(0, 0, dw, dh)
+    sc.globalCompositeOperation = "source-over"
+    this.ctx.drawImage(sc.canvas as CanvasImageSource, 0, 0, dw, dh, d.x, d.y, d.width, d.height)
+  }
+
+  fillText(text: string, x: number, baselineY: number, font: FontSpec, color: RGBA) {
+    const ctx = this.ctx
+    ctx.font = `${font.italic ? "italic " : ""}${font.weight} ${font.size}px ${font.family}`
+    ctx.textBaseline = "alphabetic"
+    ctx.textAlign = "left"
+    if ("letterSpacing" in ctx) (ctx as any).letterSpacing = `${font.letterSpacing}px`
+    ctx.fillStyle = rgbaToCss(color)
+    ctx.fillText(text, x, baselineY)
+  }
+}

package/src/paint/Painter.ts

@@ -0,0 +1,62 @@
+import type { BorderRadius, BorderSide, Gradient, ImageInfo, Rect, RGBA } from "../types"
+import type { FontSpec } from "../host/Host"
+
+export type Borders = Partial<Record<"top" | "right" | "bottom" | "left", BorderSide>>
+
+export interface DrawImageOpts {
+  fit: "cover" | "contain" | "fill"
+  tint?: RGBA
+  radius?: BorderRadius
+}
+
+/**
+ * The low-level paint primitive interface. `paintTree` walks the render tree and replays it into a
+ * Painter, so every backend (Canvas2D, the test RecordingPainter, the future tgfx painter) shares
+ * the SAME paint logic and only the leaf primitives differ. All coordinates are ABSOLUTE px — the
+ * render tree is already absolute-positioned, so no transform stack is needed.
+ */
+export interface Painter {
+  beginFrame(width: number, height: number): void
+  endFrame(): void
+
+  /** Save/restore the clip + alpha + transform state. */
+  save(): void
+  restore(): void
+
+  /** Multiply the current alpha (composes through save/restore). */
+  setAlpha(multiplier: number): void
+
+  /** Begin a compositing group: subsequent paint is collected into an offscreen layer and composited
+   *  once at `alpha` on `endGroup` — true CSS group opacity (a translucent container fades as a unit,
+   *  not per-primitive). Pair with `endGroup`. */
+  beginGroup(alpha: number): void
+  endGroup(): void
+
+  /** Translate the coordinate system (composes through save/restore). */
+  translate(x: number, y: number): void
+  /** Scale the coordinate system (composes through save/restore). */
+  scale(sx: number, sy: number): void
+  /** Multiply in a 2D affine matrix [a,b,c,d,e,f] (composes through save/restore). */
+  transform(a: number, b: number, c: number, d: number, e: number, f: number): void
+
+  /** Intersect the clip with a (possibly rounded) rectangle. */
+  clipRoundRect(rect: Rect, radius?: BorderRadius): void
+
+  fillRoundRect(rect: Rect, radius: BorderRadius | undefined, color: RGBA): void
+
+  /** Take away what is painted in a (possibly rounded) rect, down to transparent: the window a
+   *  surface UNDER the painted picture is seen through (a native view, a video). What is painted
+   *  after it goes over the surface. */
+  clearRoundRect(rect: Rect, radius: BorderRadius | undefined): void
+
+  /** Fill a (possibly rounded) rect with a linear or radial gradient. */
+  fillGradient(rect: Rect, radius: BorderRadius | undefined, gradient: Gradient): void
+
+  /** Per-side borders, drawn inside `rect`, honoring `radius`. */
+  strokeBorder(rect: Rect, radius: BorderRadius | undefined, sides: Borders): void
+
+  drawImage(image: ImageInfo, src: Rect | null, dst: Rect, opts: DrawImageOpts): void
+
+  /** A single, already-wrapped line of text drawn at its baseline. */
+  fillText(text: string, x: number, baselineY: number, font: FontSpec, color: RGBA): void
+}