lecodes-web-canvas 2.0.0

package/src/paint/RecordingPainter.ts

@@ -0,0 +1,101 @@
+import type { BorderRadius, Gradient, ImageInfo, Rect, RGBA } from "../types"
+import type { FontSpec } from "../host/Host"
+import type { Borders, DrawImageOpts, Painter } from "./Painter"
+import { rgbaToHex } from "../core/util/colors"
+
+/**
+ * A Painter that records primitive ops instead of drawing — Bun-testable and a readable low-level
+ * "display list" dump. Proves the paintTree walk without a canvas, and doubles as a golden oracle.
+ */
+export class RecordingPainter implements Painter {
+  ops: string[] = []
+  private precision: number
+
+  constructor(precision = 2) {
+    this.precision = precision
+  }
+
+  private n(v: number): number {
+    const f = 10 ** this.precision
+    return Math.round(v * f) / f
+  }
+  private r(rect: Rect): string {
+    return `[${this.n(rect.x)}, ${this.n(rect.y)}, ${this.n(rect.width)}, ${this.n(rect.height)}]`
+  }
+  private rad(radius?: BorderRadius): string {
+    if (!radius || (!radius.tl && !radius.tr && !radius.br && !radius.bl)) return ""
+    return ` r=${this.n(radius.tl)},${this.n(radius.tr)},${this.n(radius.br)},${this.n(radius.bl)}`
+  }
+
+  beginFrame(width: number, height: number) {
+    this.ops.push(`beginFrame ${this.n(width)}x${this.n(height)}`)
+  }
+  endFrame() {
+    this.ops.push("endFrame")
+  }
+  save() {
+    this.ops.push("save")
+  }
+  restore() {
+    this.ops.push("restore")
+  }
+  setAlpha(multiplier: number) {
+    this.ops.push(`setAlpha ${this.n(multiplier)}`)
+  }
+  beginGroup(alpha: number) {
+    this.ops.push(`beginGroup ${this.n(alpha)}`)
+  }
+  endGroup() {
+    this.ops.push("endGroup")
+  }
+  translate(x: number, y: number) {
+    this.ops.push(`translate ${this.n(x)},${this.n(y)}`)
+  }
+  scale(sx: number, sy: number) {
+    this.ops.push(`scale ${this.n(sx)},${this.n(sy)}`)
+  }
+  transform(a: number, b: number, c: number, d: number, e: number, f: number) {
+    this.ops.push(`transform ${this.n(a)},${this.n(b)},${this.n(c)},${this.n(d)},${this.n(e)},${this.n(f)}`)
+  }
+  clipRoundRect(rect: Rect, radius?: BorderRadius) {
+    this.ops.push(`clip ${this.r(rect)}${this.rad(radius)}`)
+  }
+  fillRoundRect(rect: Rect, radius: BorderRadius | undefined, color: RGBA) {
+    this.ops.push(`fillRect ${this.r(rect)}${this.rad(radius)} ${rgbaToHex(color)}`)
+  }
+  clearRoundRect(rect: Rect, radius: BorderRadius | undefined) {
+    this.ops.push(`clearRect ${this.r(rect)}${this.rad(radius)}`)
+  }
+  fillGradient(rect: Rect, radius: BorderRadius | undefined, gradient: Gradient) {
+    const stops = gradient.stops.map((s) => `${rgbaToHex(s.color)}@${this.n(s.position)}`).join(",")
+    let shape: string
+    if (gradient.type === "radial") {
+      const size =
+        gradient.extent === "explicit"
+          ? `r=${this.n(gradient.rx ?? 0)}${gradient.rxUnit === "fraction" ? "f" : ""},${this.n(gradient.ry ?? 0)}${gradient.ryUnit === "fraction" ? "f" : ""}`
+          : gradient.extent
+      shape = `radial ${gradient.shape} ${size} at=${this.n(gradient.cx)},${this.n(gradient.cy)}`
+    } else {
+      shape = `angle=${this.n(gradient.angle)}`
+    }
+    this.ops.push(`gradient ${this.r(rect)}${this.rad(radius)} ${shape} [${stops}]`)
+  }
+  strokeBorder(rect: Rect, radius: BorderRadius | undefined, sides: Borders) {
+    const parts = (["top", "right", "bottom", "left"] as const)
+      .filter((s) => sides[s])
+      .map((s) => `${s}=${this.n(sides[s]!.width)}/${rgbaToHex(sides[s]!.color)}`)
+    this.ops.push(`border ${this.r(rect)}${this.rad(radius)} ${parts.join(" ")}`)
+  }
+  drawImage(image: ImageInfo, src: Rect | null, dst: Rect, opts: DrawImageOpts) {
+    const tint = opts.tint !== undefined ? ` tint=${rgbaToHex(opts.tint)}` : ""
+    const crop = src ? ` src=${this.r(src)}` : ""
+    this.ops.push(`image "${image.src}" dst=${this.r(dst)}${crop} fit=${opts.fit}${tint}`)
+  }
+  fillText(text: string, x: number, baselineY: number, font: FontSpec, color: RGBA) {
+    this.ops.push(`text ${JSON.stringify(text)} @ ${this.n(x)},${this.n(baselineY)} ${font.size}px ${rgbaToHex(color)}`)
+  }
+
+  toText(): string {
+    return this.ops.join("\n")
+  }
+}

package/src/paint/paintTree.ts

@@ -0,0 +1,314 @@
+import type { BorderRadius, Layer, RenderNode, UITransform } from "../types"
+import type { Host, FontSpec } from "../host/Host"
+import type { Borders, Painter } from "./Painter"
+import { clampRadius, hasRadius } from "../core/util/geometry"
+import { isTransparent } from "../core/util/colors"
+import { isSvgLikeSrc } from "../core/util/svgSrc"
+import { wrapText } from "../core/text"
+
+/** What the host shows ITSELF, so the painter leaves it out. */
+export type PaintOptions = {
+  /** A native view and a video are surfaces UNDER the picture: their box is a window onto them
+   *  (absent: a video is a placeholder, a native view nothing). */
+  surfaces?: boolean
+  /** The field being edited, by node id: a live <input> stands over it, with the text and the caret. */
+  editing?: number
+}
+
+/**
+ * Walk the render tree and replay it into a Painter. All paint *logic* (clip-on-radius, border
+ * stacking, text alignment + baseline) lives here, so every backend shares it and only the leaf
+ * primitives differ. `host` is used for text metrics (deterministic across backends).
+ */
+export function paintTree(tree: RenderNode | null, painter: Painter, host: Host, options: PaintOptions = {}) {
+  if (!tree) return
+  painter.beginFrame(tree.rect.width, tree.rect.height)
+  paintNode(tree, painter, host, options)
+  painter.endFrame()
+}
+
+/**
+ * Paint a full frame of compositing layers (main screen + widget overlays) in one begin/end. A
+ * widget's `backdrop` is a full-viewport fill painted behind it.
+ */
+export function paintFrame(
+  layers: Layer[],
+  painter: Painter,
+  host: Host,
+  width: number,
+  height: number,
+  transform?: UITransform,
+  options: PaintOptions = {},
+) {
+  painter.beginFrame(width, height)
+  // The simulated keyboard rescales the whole UI into the band above it (the keyboard itself is the
+  // host's — DOM on web). The bottom band is left empty for the host to draw over.
+  if (transform) {
+    painter.save()
+    painter.translate(transform.tx, transform.ty)
+    painter.scale(transform.scale, transform.scale)
+  }
+  // z-order (matches the DOM): the base screen(s) first, then ALL widget backdrops, then ALL widget
+  // bodies — so with ≥2 overlays a later widget's backdrop never covers an earlier widget.
+  const widgets = layers.filter((l) => l.widget)
+  for (const l of layers) if (!l.widget) paintNode(l.tree, painter, host, options)
+  for (const l of widgets) if (l.backdrop) painter.fillRoundRect({ x: 0, y: 0, width, height }, undefined, l.backdrop.color)
+  for (const l of widgets) paintNode(l.tree, painter, host, options)
+  if (transform) painter.restore()
+  painter.endFrame()
+}
+
+function paintNode(node: RenderNode, painter: Painter, host: Host, options: PaintOptions) {
+  const { style, rect } = node
+  painter.save()
+  // A translucent container fades as a GROUP (composited offscreen, then faded once) so overlapping
+  // children blend like the DOM's CSS opacity; a leaf uses cheap per-primitive alpha (identical for a
+  // single fill, no offscreen needed).
+  const opacity = style.opacity !== undefined && style.opacity < 1 ? style.opacity : undefined
+  const grouped = opacity !== undefined && node.children.length > 0
+  if (grouped) painter.beginGroup(opacity!)
+  else if (opacity !== undefined) painter.setAlpha(opacity)
+
+  // 2D transform about `transformOrigin` (the node centre by default), affecting the node + its subtree.
+  if (style.transform) {
+    const [a, b, c, d, e, f] = style.transform
+    const o = style.transformOrigin
+    const cx = rect.x + (o ? (o.xPercent ? rect.width * o.x / 100 : o.x) : rect.width / 2)
+    const cy = rect.y + (o ? (o.yPercent ? rect.height * o.y / 100 : o.y) : rect.height / 2)
+    painter.translate(cx, cy)
+    painter.transform(a, b, c, d, e, f)
+    painter.translate(-cx, -cy)
+  }
+
+  const radius = clampRadius(style.borderRadius, rect)
+
+  // background color
+  if (!isTransparent(style.backgroundColor)) {
+    painter.fillRoundRect(rect, radius, style.backgroundColor!)
+  }
+
+  // background image (string url, painted behind content)
+  if (style.backgroundImage) {
+    const bg = host.getImage(style.backgroundImage)
+    if (bg && bg.naturalWidth > 0 && bg.naturalHeight > 0) {
+      painter.save()
+      if (hasRadius(radius)) painter.clipRoundRect(rect, radius)
+      painter.drawImage(bg, null, rect, { fit: bgSizeToFit(style.backgroundSize) })
+      painter.restore()
+    }
+  }
+
+  // background gradient layers (painted over the background image, like the DOM layer order).
+  // CSS paints the first-listed layer on top, so paint the stack back-to-front (last → first).
+  if (style.backgroundGradients) {
+    for (let i = style.backgroundGradients.length - 1; i >= 0; i--) {
+      const g = style.backgroundGradients[i]
+      if (g.stops.length > 0) painter.fillGradient(rect, radius, g)
+    }
+  }
+
+  // image (clipped to the radius if any). A source crop overrides object-fit (the frame fills the box).
+  if (node.image && node.image.naturalWidth > 0 && node.image.naturalHeight > 0) {
+    const crop = node.sourceRect
+    painter.save()
+    if (hasRadius(radius)) painter.clipRoundRect(rect, radius)
+    painter.drawImage(node.image, crop ? { x: crop[0], y: crop[1], width: crop[2], height: crop[3] } : null, rect, {
+      // DOM default: `img { object-fit: contain }`. A sourceRect crop always fills its box.
+      fit: crop ? "fill" : (style.objectFit ?? "contain"),
+      // tintColor recolors a mask-capable (SVG) image; on an opaque raster the DOM no-ops it, so
+      // only tint SVG sources — otherwise a photo would become a flat silhouette.
+      tint: isSvgLikeSrc(node.image.src) ? style.tintColor : undefined,
+      radius,
+    })
+    painter.restore()
+  }
+
+  // text
+  if (node.type === "text" && node.lines && node.lines.length > 0) {
+    paintText(node, painter, host)
+  }
+
+  // input / textarea: the value (or placeholder), single line, clipped, with a caret when focused
+  if ((node.type === "input" || node.type === "textarea") && node.id !== options.editing) {
+    paintInput(node, painter, host, radius)
+  }
+
+  // a surface under the picture: its box is a window onto it. Without one, a video is a sized
+  // placeholder
+  if (node.type === "video" || node.type === "native") {
+    if (options.surfaces) painter.clearRoundRect(rect, radius)
+    else if (node.type === "video") paintVideoPlaceholder(node, painter, host, radius)
+  }
+
+  // clip children to the viewport (scrollable / overflow:hidden)
+  if (node.clip) painter.clipRoundRect(rect, radius)
+
+  // children
+  for (const child of node.children) paintNode(child, painter, host, options)
+
+  // a screen's dim: black over its content and children (a transition's pose)
+  if (style.dim !== undefined && style.dim > 0) {
+    painter.fillRoundRect(rect, radius, Math.round(Math.min(1, style.dim) * 255) >>> 0)
+  }
+
+  // border on top
+  const sides = visibleBorders(style.border)
+  if (sides) painter.strokeBorder(rect, radius, sides)
+
+  if (grouped) painter.endGroup()
+  painter.restore()
+}
+
+function bgSizeToFit(size: "cover" | "contain" | "tile" | undefined): "cover" | "contain" | "fill" {
+  // tile isn't supported yet — fall back to cover.
+  return size === "contain" ? "contain" : "cover"
+}
+
+function visibleBorders(border: RenderNode["style"]["border"]): Borders | null {
+  if (!border) return null
+  const out: Borders = {}
+  let any = false
+  for (const side of ["top", "right", "bottom", "left"] as const) {
+    const sd = border[side]
+    if (sd && sd.width > 0 && (sd.color >>> 0) % 256 !== 0) {
+      out[side] = sd
+      any = true
+    }
+  }
+  return any ? out : null
+}
+
+// The painter gets a raw ctx (no host), so the host's family mapping (CSS-generic aliases,
+// headless concrete faces) is applied here, when the FontSpec is built.
+const familyOf = (host: Host, family: string | undefined) => {
+  const fam = family ?? "Roboto"
+  return host.resolveFontFamily?.(fam) ?? fam
+}
+
+function paintText(node: RenderNode, painter: Painter, host: Host) {
+  const s = node.style
+  const font: FontSpec = {
+    family: familyOf(host, s.fontFamily),
+    size: s.fontSize ?? 14,
+    weight: s.fontWeight ?? 400,
+    italic: s.fontStyle === "italic",
+    letterSpacing: s.letterSpacing ?? 0,
+  }
+  const color = s.color ?? 0x000000ff
+  const lineHeight = s.lineHeight
+  const align = s.textAlign ?? "start"
+  const metrics = host.fontMetrics(font)
+  const { rect, lines } = node
+  // The rect is the border box; inset by the node's own padding (the lines were already wrapped to
+  // this content width in renderTree). Matches the DOM, which applies padding via box-sizing.
+  const pl = node.padding?.[0] ?? 0
+  const pt = node.padding?.[1] ?? 0
+  const pr = node.padding?.[2] ?? 0
+  const contentX = rect.x + pl
+  const contentW = rect.width - pl - pr
+
+  for (let i = 0; i < lines!.length; i++) {
+    const line = lines![i]
+    const lineTop = rect.y + pt + i * lineHeight
+    const baselineY = lineTop + (lineHeight - (metrics.ascent + metrics.descent)) / 2 + metrics.ascent
+
+    const lineWidth = host.measureText(line, font)
+    const x =
+      align === "center"
+        ? contentX + (contentW - lineWidth) / 2
+        : align === "end"
+          ? contentX + contentW - lineWidth
+          : contentX
+
+    painter.fillText(line, x, baselineY, font, color)
+
+    if (s.textDecoration === "underline" || s.textDecoration === "line-through") {
+      const thickness = Math.max(1, font.size / 14)
+      const y = s.textDecoration === "underline" ? baselineY + thickness : baselineY - font.size * 0.3
+      painter.fillRoundRect({ x, y, width: lineWidth, height: thickness }, undefined, color)
+    }
+  }
+}
+
+function paintVideoPlaceholder(node: RenderNode, painter: Painter, host: Host, radius: BorderRadius | undefined) {
+  const { rect } = node
+  // Dark placeholder fill (unless the author set a background), so the video reads as a sized box.
+  if (isTransparent(node.style.backgroundColor)) painter.fillRoundRect(rect, radius, 0x111317ff)
+  // Centred play glyph.
+  const size = Math.min(rect.width, rect.height) * 0.3
+  if (size >= 6) {
+    const font: FontSpec = { family: "Roboto", size, weight: 400, italic: false, letterSpacing: 0 }
+    const metrics = host.fontMetrics(font)
+    const w = host.measureText("▶", font)
+    const x = rect.x + (rect.width - w) / 2
+    const baselineY = rect.y + (rect.height - (metrics.ascent + metrics.descent)) / 2 + metrics.ascent
+    painter.fillText("▶", x, baselineY, font, 0xffffffcc)
+  }
+}
+
+function paintInput(node: RenderNode, painter: Painter, host: Host, radius: BorderRadius | undefined) {
+  const s = node.style
+  const font: FontSpec = {
+    family: familyOf(host, s.fontFamily),
+    size: s.fontSize ?? 14,
+    weight: s.fontWeight ?? 400,
+    italic: s.fontStyle === "italic",
+    letterSpacing: s.letterSpacing ?? 0,
+  }
+  const value = node.value ?? ""
+  const empty = value.length === 0
+  const masked = s.inputType === "password" && !empty
+  const display = empty ? (s.placeholder ?? "") : masked ? "•".repeat(value.length) : value
+  const color = empty ? (s.placeholderColor ?? 0x999999ff) : (s.color ?? 0x000000ff)
+  const { rect } = node
+  // Inset the value/placeholder/caret by the field's own padding (rect is the border box).
+  const pl = node.padding?.[0] ?? 0
+  const pt = node.padding?.[1] ?? 0
+  const pr = node.padding?.[2] ?? 0
+  const pb = node.padding?.[3] ?? 0
+  const contentX = rect.x + pl
+  const contentW = rect.width - pl - pr
+  const contentY = rect.y + pt
+  const contentH = rect.height - pt - pb
+  const metrics = host.fontMetrics(font)
+  const lineHeight = s.lineHeight
+  const align = s.textAlign ?? "start"
+
+  // A textarea wraps to the content width and top-aligns its lines; an input is a single line,
+  // vertically centred in the field.
+  const multiline = node.type === "textarea"
+  const lines = multiline ? wrapText(display, contentW, (t) => host.measureText(t, font)).lines : [display]
+  const lineX = (w: number) =>
+    align === "center" ? contentX + (contentW - w) / 2 : align === "end" ? contentX + contentW - w : contentX
+  const lineBaseline = (i: number) =>
+    multiline
+      ? contentY + i * lineHeight + (lineHeight - (metrics.ascent + metrics.descent)) / 2 + metrics.ascent
+      : contentY + (contentH - (metrics.ascent + metrics.descent)) / 2 + metrics.ascent
+
+  painter.save()
+  painter.clipRoundRect(rect, radius) // keep content inside the field
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (line.length > 0) painter.fillText(line, lineX(host.measureText(line, font)), lineBaseline(i), font, color)
+  }
+
+  // Caret at the end of the real value (or the start when empty) while focused. Static (no blink).
+  if (node.state?.focused) {
+    const valueLines = empty
+      ? [""]
+      : multiline
+        ? wrapText(masked ? "•".repeat(value.length) : value, contentW, (t) => host.measureText(t, font)).lines
+        : [display]
+    const i = valueLines.length - 1
+    const lineW = host.measureText(valueLines[i], font)
+    const caretX = empty ? lineX(0) : lineX(lineW) + lineW
+    const baselineY = lineBaseline(i)
+    const caretW = Math.max(1, font.size / 14)
+    painter.fillRoundRect(
+      { x: caretX, y: baselineY - metrics.ascent, width: caretW, height: metrics.ascent + metrics.descent },
+      undefined,
+      s.color ?? 0x000000ff,
+    )
+  }
+  painter.restore()
+}