lecodes-web-shared 2.0.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "lecodes-web-shared",
+  "version": "2.0.0",
+  "description": "What every web renderer and host of LeCodes shares: the fetch-buffer and media-player registries, the presentation model (router, presentPlayer, native views, touch), svg/video leaves, fonts, source-map errors, the canvas host",
+  "type": "module",
+  "main": "src/sourcemapError.ts",
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "~5.8.3",
+    "vite": "^6.3.5"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/assets/Roboto-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2011 The Roboto Project Authors (https://github.com/googlefonts/roboto-classic)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/canvas/createCanvasHost.ts

@@ -0,0 +1,103 @@
+// The web PAINTER host for `_creatorCanvas`: the HostCanvas table of the wasm runtime (host.gen.ts
+// `WasmHostCanvas`) over OffscreenCanvas. The runtime's AnyCanvas core interprets the SDK's opcode
+// stream and SVG into a draw list; this host keeps one OffscreenCanvas per surface id and replays the
+// list with the vendored AnyCanvas web painter (./gen, `bun run vendor:canvas`). The browser gives text
+// shaping, emoji, font fallback and image decoding for free.
+//
+// `readSurface` / `getSurface` / `surfaceToDataUrl` are how the baked pixels reach the engines (a GPU
+// texture), the canvas UI renderer (`UIImage(canvas)` draws the live OffscreenCanvas) and the DOM
+// renderer (a data URL).
+
+import { readDrawList } from "./gen/drawlist"
+import { paint, cssFont } from "./gen/painter"
+
+export interface CanvasHost {
+  /** The HostCanvas table the wasm runtime calls (a web host's canvas table). */
+  table: {
+    paint(surfaceId: number, pw: number, ph: number, scale: number, words: Float32Array, strings: string[]): void
+    measureText(text: string, family: string, size: number, weight: number, italic: boolean, out: Float32Array): void
+    decodeImage(bufferId: number, surfaceId: number, size: Int32Array): boolean
+    readPixels(surfaceId: number, size: Int32Array): Uint8Array | null
+    releaseSurface(surfaceId: number): void
+  }
+  /** Straight (non-premultiplied) RGBA8 pixels of a baked surface, for engine texture upload. */
+  readSurface(surfaceId: number): { data: Uint8ClampedArray, width: number, height: number } | null
+  /** The baked surface as a drawable canvas (device px) — a `CanvasSurfaceProvider` for canvas-ui's
+   *  `UIImage(canvas)` (lecodes-headless BrowserHost). */
+  getSurface(surfaceId: number): { canvas: OffscreenCanvas, width: number, height: number } | null
+  /** The baked surface as a data-uri, for the DOM renderer's `<img>` (`UIImage(canvas)`). */
+  surfaceToDataUrl(surfaceId: number): string | null
+}
+
+/** `fontFamily` maps a draw-list family to what the page can render (a registered font's real name);
+ *  the default keeps the family as is. Image decoding is asynchronous in the browser while the table is
+ *  synchronous, so `decodeImage` answers false: `Canvas.loadImage(fetchResponse)` rejects on the web
+ *  (SVG goes through the core and works). */
+export const createCanvasHost = (fontFamily?: (family: string) => string): CanvasHost => {
+  const supported = typeof OffscreenCanvas !== "undefined"
+  const surfaces = new Map<number, OffscreenCanvas>()
+  let measureCtx: OffscreenCanvasRenderingContext2D | null = null
+
+  const ensure = (surfaceId: number, pw: number, ph: number): OffscreenCanvas | null => {
+    if (!supported) return null
+    let cv = surfaces.get(surfaceId)
+    if (!cv) { cv = new OffscreenCanvas(pw, ph); surfaces.set(surfaceId, cv) }
+    else if (cv.width !== pw || cv.height !== ph) { cv.width = pw; cv.height = ph }
+    return cv
+  }
+
+  const table: CanvasHost["table"] = {
+    paint: (surfaceId, pw, ph, _scale, words, strings) => {
+      const cv = ensure(surfaceId, Math.max(1, pw), Math.max(1, ph))
+      const ctx = cv?.getContext("2d")
+      if (!cv || !ctx) return
+      ctx.setTransform(1, 0, 0, 1, 0, 0)
+      ctx.clearRect(0, 0, cv.width, cv.height)
+      // `words` is a view into wasm memory, valid for this call only: decode before returning.
+      paint(ctx, readDrawList(words, strings), { image: id => surfaces.get(id) ?? null, fontFamily })
+    },
+    measureText: (text, family, size, weight, italic, out) => {
+      out[0] = 0; out[1] = 0; out[2] = 0
+      if (!supported) return
+      if (!measureCtx) measureCtx = new OffscreenCanvas(1, 1).getContext("2d")
+      if (!measureCtx) return
+      measureCtx.font = cssFont({ family, size, weight, italic }, fontFamily ? fontFamily(family) : family)
+      const m = measureCtx.measureText(text)
+      out[0] = m.width
+      out[1] = m.fontBoundingBoxAscent ?? m.actualBoundingBoxAscent
+      out[2] = m.fontBoundingBoxDescent ?? m.actualBoundingBoxDescent
+    },
+    decodeImage: () => false,
+    readPixels: (surfaceId, size) => {
+      const s = readSurface(surfaceId)
+      if (!s) return null
+      size[0] = s.width; size[1] = s.height
+      return new Uint8Array(s.data.buffer, s.data.byteOffset, s.data.byteLength)
+    },
+    releaseSurface: (surfaceId) => { surfaces.delete(surfaceId) },
+  }
+
+  const readSurface = (surfaceId: number) => {
+    const cv = surfaces.get(surfaceId)
+    const ctx = cv?.getContext("2d")
+    if (!cv || !ctx) return null
+    const img = ctx.getImageData(0, 0, cv.width, cv.height)   // straight RGBA8 per the Canvas2D spec
+    return { data: img.data, width: cv.width, height: cv.height }
+  }
+
+  const getSurface = (surfaceId: number) => {
+    const cv = surfaces.get(surfaceId)
+    return cv ? { canvas: cv, width: cv.width, height: cv.height } : null
+  }
+
+  const surfaceToDataUrl = (surfaceId: number): string | null => {
+    const cv = surfaces.get(surfaceId)
+    if (!cv || typeof document === "undefined") return null
+    const el = document.createElement("canvas")
+    el.width = cv.width; el.height = cv.height
+    el.getContext("2d")?.drawImage(cv, 0, 0)
+    return el.toDataURL()
+  }
+
+  return { table, readSurface, getSurface, surfaceToDataUrl }
+}

package/src/canvas/gen/drawlist.ts

@@ -0,0 +1,138 @@
+// GENERATED by scripts/vendor-canvas.ts from engines/canvas/painters/web/src/drawlist.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 draw list in TypeScript: the typed commands, the reader of the word buffer (spec/draw.h) and
+// the reader of the core's JSON dump. Both produce the same DrawCommand objects — the tests hold the
+// two readers against each other on every golden.
+import {
+  DRAW, Paint as PaintKind, PathVerb, LineJoinName, LineCapName, TextAlignName, TextBaselineName, FillRuleName, SpreadName,
+} from "./spec"
+
+export type Color = [number, number, number, number]
+export type Matrix6 = [number, number, number, number, number, number]
+export interface Stop { offset: number, color: Color }
+export interface ColorPaint { kind: "color", alpha: number, color: Color }
+export interface LinearPaint { kind: "linear", alpha: number, matrix: Matrix6, spread: string, stops: Stop[] }
+export interface RadialPaint { kind: "radial", alpha: number, matrix: Matrix6, fx: number, fy: number, r0: number, spread: string, stops: Stop[] }
+export type Paint = ColorPaint | LinearPaint | RadialPaint
+export interface Stroke { width: number, join: string, cap: string, miterLimit: number, dashOffset: number, dash: number[] }
+export interface Font { family: string, size: number, weight: number, italic: boolean }
+export type PathSeg = ["M", number, number] | ["L", number, number] | ["Q", number, number, number, number] | ["C", number, number, number, number, number, number] | ["Z"]
+
+export type DrawCommand =
+  | { cmd: "setTransform", matrix: Matrix6 }
+  | { cmd: "save" }
+  | { cmd: "restore" }
+  | { cmd: "clip", rule: string, path: PathSeg[] }
+  | { cmd: "fillPath", rule: string, paint: Paint, path: PathSeg[] }
+  | { cmd: "strokePath", stroke: Stroke, paint: Paint, path: PathSeg[] }
+  | { cmd: "fillText", text: string, x: number, y: number, maxWidth: number, font: Font, align: string, baseline: string, letterSpacing: number, paint: Paint }
+  | { cmd: "strokeText", text: string, x: number, y: number, maxWidth: number, font: Font, align: string, baseline: string, letterSpacing: number, stroke: Stroke, paint: Paint }
+  | { cmd: "drawImage", surface: number, src: [number, number, number, number], dst: [number, number, number, number], alpha: number }
+  | { cmd: "clearRect", rect: [number, number, number, number] }
+
+class Reader {
+  pos = 0
+  constructor(readonly w: Float32Array, readonly strings: readonly string[]) {}
+  f(): number { if (this.pos >= this.w.length) throw new Error("draw list: truncated"); return this.w[this.pos++] }
+  i(): number { return this.f() | 0 }
+  str(): string { const i = this.i(); if (i < 0 || i >= this.strings.length) throw new Error(`draw list: bad string index ${i}`); return this.strings[i] }
+  color(): Color { return [this.f(), this.f(), this.f(), this.f()] }
+  matrix(): Matrix6 { return [this.f(), this.f(), this.f(), this.f(), this.f(), this.f()] }
+  paint(): Paint {
+    const kind = this.i(), alpha = this.f()
+    if (kind === PaintKind.COLOR) return { kind: "color", alpha, color: this.color() }
+    const matrix = this.matrix()
+    let fx = 0, fy = 0, r0 = 0
+    if (kind === PaintKind.RADIAL) { fx = this.f(); fy = this.f(); r0 = this.f() }
+    const spread = SpreadName[this.i()] ?? "pad"
+    const n = this.i()
+    const stops: Stop[] = []
+    for (let k = 0; k < n; k++) stops.push({ offset: this.f(), color: this.color() })
+    return kind === PaintKind.RADIAL ? { kind: "radial", alpha, matrix, fx, fy, r0, spread, stops } : { kind: "linear", alpha, matrix, spread, stops }
+  }
+  stroke(): Stroke {
+    const width = this.f(), join = LineJoinName[this.i()] ?? "miter", cap = LineCapName[this.i()] ?? "butt"
+    const miterLimit = this.f(), dashOffset = this.f(), n = this.i()
+    const dash: number[] = []
+    for (let k = 0; k < n; k++) dash.push(this.f())
+    return { width, join, cap, miterLimit, dashOffset, dash }
+  }
+  font(): Font { return { family: this.str(), size: this.f(), weight: this.i(), italic: this.i() !== 0 } }
+  path(): PathSeg[] {
+    const n = this.i()
+    const end = this.pos + n
+    if (end > this.w.length) throw new Error("draw list: truncated path")
+    const segs: PathSeg[] = []
+    while (this.pos < end) {
+      switch (this.i()) {
+        case PathVerb.MOVE: segs.push(["M", this.f(), this.f()]); break
+        case PathVerb.LINE: segs.push(["L", this.f(), this.f()]); break
+        case PathVerb.QUAD: segs.push(["Q", this.f(), this.f(), this.f(), this.f()]); break
+        case PathVerb.CUBIC: segs.push(["C", this.f(), this.f(), this.f(), this.f(), this.f(), this.f()]); break
+        case PathVerb.CLOSE: segs.push(["Z"]); break
+        default: throw new Error("draw list: bad path verb")
+      }
+    }
+    return segs
+  }
+  rect4(): [number, number, number, number] { return [this.f(), this.f(), this.f(), this.f()] }
+}
+
+/** Decode a word buffer + string table into commands. A command this build does not know is skipped. */
+export const readDrawList = (words: Float32Array, strings: readonly string[]): DrawCommand[] => {
+  const r = new Reader(words, strings)
+  const out: DrawCommand[] = []
+  while (r.pos + 2 <= words.length) {
+    const cmd = r.i(), len = r.i()
+    const end = r.pos + len
+    if (len < 0 || end > words.length) throw new Error("draw list: truncated command")
+    switch (cmd) {
+      case DRAW.SET_TRANSFORM: out.push({ cmd: "setTransform", matrix: r.matrix() }); break
+      case DRAW.SAVE: out.push({ cmd: "save" }); break
+      case DRAW.RESTORE: out.push({ cmd: "restore" }); break
+      case DRAW.CLIP: { const rule = FillRuleName[r.i()] ?? "nonzero"; out.push({ cmd: "clip", rule, path: r.path() }); break }
+      case DRAW.FILL_PATH: { const rule = FillRuleName[r.i()] ?? "nonzero"; const paint = r.paint(); out.push({ cmd: "fillPath", rule, paint, path: r.path() }); break }
+      case DRAW.STROKE_PATH: { const stroke = r.stroke(); const paint = r.paint(); out.push({ cmd: "strokePath", stroke, paint, path: r.path() }); break }
+      case DRAW.FILL_TEXT: case DRAW.STROKE_TEXT: {
+        const text = r.str(), x = r.f(), y = r.f(), maxWidth = r.f(), font = r.font()
+        const align = TextAlignName[r.i()] ?? "start", baseline = TextBaselineName[r.i()] ?? "alphabetic", letterSpacing = r.f()
+        if (cmd === DRAW.STROKE_TEXT) { const stroke = r.stroke(); out.push({ cmd: "strokeText", text, x, y, maxWidth, font, align, baseline, letterSpacing, stroke, paint: r.paint() }) }
+        else out.push({ cmd: "fillText", text, x, y, maxWidth, font, align, baseline, letterSpacing, paint: r.paint() })
+        break
+      }
+      case DRAW.DRAW_IMAGE: { const surface = r.i(); const src = r.rect4(); const dst = r.rect4(); out.push({ cmd: "drawImage", surface, src, dst, alpha: r.f() }); break }
+      case DRAW.CLEAR_RECT: out.push({ cmd: "clearRect", rect: r.rect4() }); break
+      default: break   // unknown: skipped by len
+    }
+    if (r.pos !== end) {
+      if (r.pos > end) throw new Error(`draw list: command ${cmd} overran its length`)
+      r.pos = end
+    }
+  }
+  return out
+}
+
+/** The core's JSON dump (ac_drawlist_json / acdump) → commands. */
+export const parseDrawListJson = (text: string): DrawCommand[] => {
+  const v = JSON.parse(text)
+  if (!Array.isArray(v)) throw new Error("draw list JSON: expected an array")
+  for (const c of v) if (typeof c !== "object" || typeof c.cmd !== "string") throw new Error("draw list JSON: bad command")
+  return v as DrawCommand[]
+}
+
+/** The binary file acdump / the golden test write: u32 wordCount, f32 words, u32 stringCount, (u32 len, utf8)*. */
+export const readDrawListBinary = (bytes: Uint8Array): { words: Float32Array, strings: string[] } => {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  let pos = 0
+  const wordCount = dv.getUint32(pos, true); pos += 4
+  const words = new Float32Array(wordCount)
+  for (let i = 0; i < wordCount; i++) { words[i] = dv.getFloat32(pos, true); pos += 4 }
+  const stringCount = dv.getUint32(pos, true); pos += 4
+  const strings: string[] = []
+  const dec = new TextDecoder()
+  for (let i = 0; i < stringCount; i++) {
+    const len = dv.getUint32(pos, true); pos += 4
+    strings.push(dec.decode(bytes.subarray(pos, pos + len))); pos += len
+  }
+  return { words, strings }
+}

package/src/canvas/gen/painter.ts

@@ -0,0 +1,176 @@
+// GENERATED by scripts/vendor-canvas.ts from engines/canvas/painters/web/src/painter.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 web painter: replays a draw list on anything shaped like a CanvasRenderingContext2D — the
+// browser, an OffscreenCanvas, node-canvas / @napi-rs/canvas. A loop with one case per command, no
+// state of its own: the list carries absolute transforms and resolved paints.
+//
+// Platform limits, stated: Canvas2D gradients only PAD (reflect / repeat draw as pad); a gradient
+// under a non-similarity transform (skew, non-uniform scale — SVG objectBoundingBox on a non-square
+// shape) is drawn by transforming the context, which also distorts a STROKE's pen; letterSpacing
+// applies where the context supports it (Chrome 99+, Safari 17+; not node-canvas).
+import type { DrawCommand, Paint, Stroke, Font, PathSeg, Matrix6, Color } from "./drawlist"
+
+/** The subset of CanvasRenderingContext2D the painter uses. */
+export interface Canvas2DLike {
+  save(): void
+  restore(): void
+  setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void
+  transform(a: number, b: number, c: number, d: number, e: number, f: number): void
+  beginPath(): void
+  moveTo(x: number, y: number): void
+  lineTo(x: number, y: number): void
+  quadraticCurveTo(cx: number, cy: number, x: number, y: number): void
+  bezierCurveTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): void
+  closePath(): void
+  fill(rule?: "nonzero" | "evenodd"): void
+  stroke(): void
+  clip(rule?: "nonzero" | "evenodd"): void
+  fillStyle: any
+  strokeStyle: any
+  lineWidth: number
+  lineJoin: any
+  lineCap: any
+  miterLimit: number
+  setLineDash(segments: number[]): void
+  lineDashOffset: number
+  globalAlpha: number
+  font: string
+  textAlign: any
+  textBaseline: any
+  letterSpacing?: string
+  fillText(text: string, x: number, y: number, maxWidth?: number): void
+  strokeText(text: string, x: number, y: number, maxWidth?: number): void
+  drawImage(image: any, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void
+  clearRect(x: number, y: number, w: number, h: number): void
+  createLinearGradient(x0: number, y0: number, x1: number, y1: number): any
+  createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): any
+}
+
+export interface PainterHooks {
+  /** The drawable for a surface id (a canvas, an ImageBitmap, an Image); null skips the blit. */
+  image?(surface: number): any
+  /** Map a font family to what this context can render (a registered font's real name, a fallback). */
+  fontFamily?(family: string): string
+}
+
+const GENERIC_FAMILIES = new Set(["serif", "sans-serif", "monospace", "cursive", "fantasy", "system-ui", "ui-serif", "ui-sans-serif", "ui-monospace", "ui-rounded", "emoji", "math", "fangsong"])
+
+/** A draw-list color as CSS. */
+export const cssColor = (c: Color): string => `rgba(${Math.round(c[0] * 255)}, ${Math.round(c[1] * 255)}, ${Math.round(c[2] * 255)}, ${c[3]})`
+
+/** A draw-list font as a CSS font shorthand. */
+export const cssFont = (f: Font, family = f.family): string => {
+  const fam = GENERIC_FAMILIES.has(family) ? family : `"${family.replace(/"/g, "'")}"`
+  return `${f.italic ? "italic " : ""}${f.weight} ${f.size}px ${fam}`
+}
+
+const apply = (m: Matrix6, x: number, y: number): [number, number] => [m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]]
+
+// A similarity transform (uniform scale + rotation + translation) keeps circles circles, so the
+// gradient can be expressed in user space without transforming the context.
+const isSimilarity = (m: Matrix6): boolean => Math.abs(m[0] - m[3]) < 1e-6 && Math.abs(m[1] + m[2]) < 1e-6
+
+const buildPath = (ctx: Canvas2DLike, path: PathSeg[]): void => {
+  ctx.beginPath()
+  for (const s of path) {
+    switch (s[0]) {
+      case "M": ctx.moveTo(s[1], s[2]); break
+      case "L": ctx.lineTo(s[1], s[2]); break
+      case "Q": ctx.quadraticCurveTo(s[1], s[2], s[3], s[4]); break
+      case "C": ctx.bezierCurveTo(s[1], s[2], s[3], s[4], s[5], s[6]); break
+      case "Z": ctx.closePath(); break
+    }
+  }
+}
+
+const gradientStops = (g: any, paint: Paint & { stops: { offset: number, color: Color }[] }): void => {
+  for (const s of paint.stops) g.addColorStop(s.offset, cssColor(s.color))
+}
+
+// Sets fillStyle / strokeStyle + globalAlpha, then runs `draw`. A gradient with a general matrix is
+// drawn inside a context transform (the path, already built, is not affected — Canvas2D keeps paths
+// in device space).
+const withPaint = (ctx: Canvas2DLike, paint: Paint, which: "fill" | "stroke", draw: () => void): void => {
+  ctx.globalAlpha = paint.alpha
+  if (paint.kind === "color") {
+    ctx[which === "fill" ? "fillStyle" : "strokeStyle"] = cssColor(paint.color)
+    draw()
+    return
+  }
+  const m = paint.matrix
+  if (isSimilarity(m)) {
+    let g: any
+    if (paint.kind === "linear") {
+      const [x0, y0] = apply(m, 0, 0), [x1, y1] = apply(m, 1, 0)
+      g = ctx.createLinearGradient(x0, y0, x1, y1)
+    } else {
+      const s = Math.hypot(m[0], m[1])
+      const [cx, cy] = apply(m, 0, 0), [fx, fy] = apply(m, paint.fx, paint.fy)
+      g = ctx.createRadialGradient(fx, fy, paint.r0 * s, cx, cy, s)
+    }
+    gradientStops(g, paint)
+    ctx[which === "fill" ? "fillStyle" : "strokeStyle"] = g
+    draw()
+    return
+  }
+  ctx.save()
+  ctx.transform(m[0], m[1], m[2], m[3], m[4], m[5])
+  const g = paint.kind === "linear" ? ctx.createLinearGradient(0, 0, 1, 0) : ctx.createRadialGradient(paint.fx, paint.fy, paint.r0, 0, 0, 1)
+  gradientStops(g, paint)
+  ctx[which === "fill" ? "fillStyle" : "strokeStyle"] = g
+  draw()
+  ctx.restore()
+}
+
+const applyStroke = (ctx: Canvas2DLike, s: Stroke): void => {
+  ctx.lineWidth = s.width
+  ctx.lineJoin = s.join
+  ctx.lineCap = s.cap
+  ctx.miterLimit = s.miterLimit
+  ctx.setLineDash(s.dash)
+  ctx.lineDashOffset = s.dashOffset
+}
+
+const applyText = (ctx: Canvas2DLike, c: { font: Font, align: string, baseline: string, letterSpacing: number }, hooks: PainterHooks): void => {
+  ctx.font = cssFont(c.font, hooks.fontFamily ? hooks.fontFamily(c.font.family) : c.font.family)
+  ctx.textAlign = c.align
+  ctx.textBaseline = c.baseline
+  if ("letterSpacing" in ctx) ctx.letterSpacing = `${c.letterSpacing}px`
+}
+
+/** Replay `commands` on `ctx`. The context should start with the identity transform and an empty
+ *  save stack (the painter sets the identity itself); clearing the surface is the caller's decision.
+ *  The replay runs inside one save, so no clip, transform or style it sets outlives it (Canvas2D
+ *  keeps a clip set outside any save, and the next paint's clearRect would clear only that clip). */
+export const paint = (ctx: Canvas2DLike, commands: DrawCommand[], hooks: PainterHooks = {}): void => {
+  ctx.save()
+  let saves = 0   // a list restore never pops the wrapper save
+  try {
+    ctx.setTransform(1, 0, 0, 1, 0, 0)
+    ctx.globalAlpha = 1
+    for (const c of commands) {
+      switch (c.cmd) {
+        case "setTransform": ctx.setTransform(c.matrix[0], c.matrix[1], c.matrix[2], c.matrix[3], c.matrix[4], c.matrix[5]); break
+        case "save": ctx.save(); saves++; break
+        case "restore": if (saves > 0) { ctx.restore(); saves-- } break
+        case "clip": buildPath(ctx, c.path); ctx.clip(c.rule as "nonzero" | "evenodd"); break
+        case "fillPath": buildPath(ctx, c.path); withPaint(ctx, c.paint, "fill", () => ctx.fill(c.rule as "nonzero" | "evenodd")); break
+        case "strokePath": buildPath(ctx, c.path); applyStroke(ctx, c.stroke); withPaint(ctx, c.paint, "stroke", () => ctx.stroke()); break
+        case "fillText": applyText(ctx, c, hooks); withPaint(ctx, c.paint, "fill", () => c.maxWidth > 0 ? ctx.fillText(c.text, c.x, c.y, c.maxWidth) : ctx.fillText(c.text, c.x, c.y)); break
+        case "strokeText": applyText(ctx, c, hooks); applyStroke(ctx, c.stroke); withPaint(ctx, c.paint, "stroke", () => c.maxWidth > 0 ? ctx.strokeText(c.text, c.x, c.y, c.maxWidth) : ctx.strokeText(c.text, c.x, c.y)); break
+        case "drawImage": {
+          const img = hooks.image?.(c.surface)
+          if (!img) break
+          ctx.globalAlpha = c.alpha
+          ctx.drawImage(img, c.src[0], c.src[1], c.src[2], c.src[3], c.dst[0], c.dst[1], c.dst[2], c.dst[3])
+          break
+        }
+        case "clearRect": ctx.clearRect(c.rect[0], c.rect[1], c.rect[2], c.rect[3]); break
+        default: { const never: never = c; throw new Error(`unhandled draw command ${(never as DrawCommand).cmd}`) }
+      }
+    }
+  } finally {
+    for (; saves > 0; saves--) ctx.restore()
+    ctx.restore()
+  }
+}