lecodes-web-canvas 2.0.0

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "lecodes-web-canvas",
+  "version": "2.0.0",
+  "description": "The tree UI of LeCodes' web renderers: the runtime's HostUI in TypeScript (TreeUI) + the render tree, painted to a 2D canvas — in the browser (web/renderer) or headless (lecodes-headless)",
+  "type": "module",
+  "license": "MIT",
+  "main": "src/runtime/TreeUI.ts",
+  "dependencies": {
+    "lecodes-sdk": "2.0.0",
+    "lecodes-web-runtime": "2.0.0",
+    "lecodes-web-shared": "2.0.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.8.3",
+    "vite": "^6.3.5"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/contract.d.ts

@@ -0,0 +1,16 @@
+// The host contract's globals (`_creatorTree`, `Handle`, …) come from sdk/src/bridges/*.d.ts; the
+// tree UI references this file so the SDK's tree constants type-check here.
+import "lecodes-sdk/bridges/tree"
+import "lecodes-sdk/bridges/app"
+import "lecodes-sdk/bridges/gl"
+import "lecodes-sdk/bridges/2d"
+import "lecodes-sdk/bridges/nav"
+import "lecodes-sdk/bridges/canvas"
+import "lecodes-sdk/bridges/device"
+import "lecodes-sdk/bridges/fetch"
+import "lecodes-sdk/bridges/files"
+import "lecodes-sdk/bridges/storage"
+import "lecodes-sdk/bridges/socket"
+import "lecodes-sdk/bridges/service"
+import "lecodes-sdk/bridges/input"
+import "lecodes-sdk/bridges/media"

package/src/core/SceneNode.ts

@@ -0,0 +1,109 @@
+import type { NodeType, Rect, ResolvedStyle, WorkerNode } from "../types"
+
+/**
+ * A retained renderer node, mirroring one authoring-layer (worker) node. It owns the creator-ui
+ * (Yoga) id, the resolved paint style (mutated in place by the layout engine's style handlers),
+ * and the tree links. `jsNode` is the original authoring node — read for `text`, image `src`,
+ * `_sourceRect`, and the touch/click listeners; never mutated for layout.
+ */
+export class SceneNode {
+  id: number
+  type: NodeType
+  jsNode: WorkerNode
+  parent: SceneNode | null = null
+  children: SceneNode[] = []
+  style: ResolvedStyle = { lineHeight: 14 * 1.2 }   // the core's fresh-node record; the first paint sync replaces it
+
+  /**
+   * The last-known parent-relative layout. creator-ui's getLayoutPointer is a *consume-new-layout*
+   * call (returns nothing once read, until the next calculate), so we snapshot it here after each
+   * calculate and build the render tree from this cache — making the build idempotent.
+   */
+  layoutRect: Rect | null = null
+
+  /** text / image leaves carry a measure function in creator-ui. */
+  readonly measured: boolean
+
+  /** Vertical scroll offset (px) for scrollable nodes; 0 otherwise. */
+  scrollOffset = 0
+
+  /** Image source crop (atlas frame), texture px. Set via setSourceRect or from `_sourceRect`. */
+  sourceRect?: [number, number, number, number]
+
+  /** Author-given semantic name (LeCodes `name`): a stable selector for tests + AI review feedback. */
+  readonly name?: string
+
+  /** Current text of an input/textarea node (the renderer owns it, like the DOM `<input>.value`). */
+  value = ""
+
+  /** Memoized text wrap (text nodes): the last wrap result keyed by text + content width + font. The
+   *  render tree is rebuilt every frame while scrolling/animating, and re-wrapping calls the host's
+   *  measureText per line — caching skips that when nothing about the text changed. Cleared globally on
+   *  registerFont (a new face changes metrics without changing the key). */
+  wrapCache?: { key: string; lines: string[] }
+
+  constructor(id: number, type: NodeType, jsNode: WorkerNode) {
+    this.id = id
+    this.type = type
+    this.jsNode = jsNode
+    // Keep in sync with Screen.addNode's hasMeasure (createChild flag). Editables are measured
+    // leaves: an input is one intrinsic line, a textarea's height follows its content.
+    this.measured = type === "text" || type === "image" || type === "input" || type === "textarea"
+    if (typeof jsNode?.name === "string" && jsNode.name.length > 0) this.name = jsNode.name
+    // A crop set before mount is stashed on the authoring node — pick it up here.
+    if (type === "image" && Array.isArray(jsNode?._sourceRect)) {
+      this.sourceRect = jsNode._sourceRect.slice() as [number, number, number, number]
+    }
+    // Same stash for a value set before mount (a pre-filled form): the SDK's `input.value =` writes
+    // `_value` whether or not the node is mounted, and the host seeds the field from it here.
+    if ((type === "input" || type === "textarea") && typeof jsNode?._value === "string") {
+      this.value = jsNode._value
+    }
+  }
+
+  // Read the `_`-prefixed backing fields, not the public accessors: chisel's method-DCE keeps
+  // `_*` members but drops the `text`/`src` getter pair when no *bundled* code references the
+  // name (the renderer is outside the bundle). Same convention as the DOM viewer (`node._text`).
+  get text(): string | undefined {
+    return this.type === "text" ? (this.jsNode?._text ?? this.jsNode?.text ?? "") : undefined
+  }
+
+  /** The raw authoring image source (string url / `SvgSource` / `{ _id }` asset / `File`), or
+   *  undefined. Resolve it to a loadable url with `Host.resolveSrc` at the point of use. */
+  get imageSrcRaw(): unknown {
+    return this.type === "image" ? (this.jsNode?._src ?? this.jsNode?.src) : undefined
+  }
+
+  /** True if this node scrolls its content (`scrollable`, a `vlist`, or a `makeScrollable` screen). */
+  get scrollable(): boolean {
+    return this.type === "scrollable" || this.type === "vlist" || this.jsNode?.scrollable === true
+  }
+
+  /** True if this node is an editable field (input / textarea). */
+  get editable(): boolean {
+    return this.type === "input" || this.type === "textarea"
+  }
+
+  /** Scroll axis for a scrollable node ("x" horizontal, "y" vertical — the default). */
+  get scrollAxis(): "x" | "y" {
+    return this.style.scrollAxis === "x" ? "x" : "y"
+  }
+
+  /** True if this node has any pointer listeners (button / interactive screen). */
+  get interactive(): boolean {
+    const n = this.jsNode
+    if (!n) return false
+    // A screen/widget SURFACE is pointer-transparent unless the app registered a root-level touch
+    // listener — the web host's `.screen { pointer-events: none }` + `.interactive` rule. Every SDK
+    // screen carries the `_emitTouchStart` METHOD, so testing for the method alone would make any
+    // open screen swallow the taps meant for the 2D/3D scene beneath it (HUD-over-game).
+    if (n.type === "screen" || n.type === "widget") {
+      return Array.isArray(n.touchStartListeners) && n.touchStartListeners.length > 0
+    }
+    return (
+      typeof n._emitClick === "function" ||
+      typeof n._emitTouchStart === "function" ||
+      (Array.isArray(n.touchStartListeners) && n.touchStartListeners.length > 0)
+    )
+  }
+}

package/src/core/hitTest.ts

@@ -0,0 +1,30 @@
+import type { RenderNode } from "../types"
+
+function contains(node: RenderNode, x: number, y: number): boolean {
+  const r = node.rect
+  return x >= r.x && x < r.x + r.width && y >= r.y && y < r.y + r.height
+}
+
+/**
+ * Find the topmost node satisfying `accept` (e.g. interactive) under a point. Walks in paint order
+ * and returns the last match — later siblings and deeper children paint on top, so they win, which
+ * matches the DOM event-bubbling target the worker buttons expect.
+ */
+export function hitTest(
+  root: RenderNode,
+  x: number,
+  y: number,
+  accept: (node: RenderNode) => boolean,
+): RenderNode | null {
+  let found: RenderNode | null = null
+  const walk = (node: RenderNode) => {
+    const inside = contains(node, x, y)
+    if (inside && accept(node)) found = node
+    // A clipping node (scrollable / overflow:hidden) hides children outside its rect — so a child
+    // scrolled out of view isn't hittable, matching the DOM's overflow clipping.
+    if (node.clip && !inside) return
+    for (const child of node.children) walk(child)
+  }
+  walk(root)
+  return found
+}

package/src/core/text.ts

@@ -0,0 +1,259 @@
+import type { ResolvedStyle, RGBA } from "../types"
+import type { FontSpec, Host } from "../host/Host"
+import type { SceneNode } from "./SceneNode"
+import { extractSvgViewBox, isSvgSource } from "./util/svgSrc"
+
+/** Effective, fully-defaulted text style for a node (after walking inheritance). */
+export interface EffectiveText {
+  color: RGBA
+  fontSize: number
+  fontFamily: string
+  fontWeight: number
+  fontStyle: "normal" | "italic"
+  lineHeight: number
+  letterSpacing: number
+  textAlign: "start" | "center" | "end"
+  textDecoration: "underline" | "line-through" | "none"
+}
+
+// The last-resort values for a node whose record carries no color / font (the runtime inherits
+// text style and the theme's defaults core-side; these only fill what is absent there).
+const DEFAULTS = {
+  color: 0x000000ff as RGBA,
+  fontSize: 14,
+  fontFamily: "Roboto",
+  fontWeight: 400,
+  fontStyle: "normal" as const,
+  letterSpacing: 0,
+  textAlign: "start" as const,
+  textDecoration: "none" as const,
+}
+
+/**
+ * A node's text style: its ResolvedStyle already holds the EFFECTIVE values (the runtime's paint
+ * record inherits text style core-side), so this only fills the defaults for absent fields. The
+ * measure callback and the render-tree build both call this, so layout and paint never disagree.
+ */
+export function resolveTextStyle(node: SceneNode): EffectiveText {
+  const s = node.style
+  const { color, fontSize, fontFamily, fontWeight, fontStyle, lineHeight, letterSpacing, textAlign, textDecoration } = s
+
+  const size = fontSize ?? DEFAULTS.fontSize
+  return {
+    color: color ?? DEFAULTS.color,
+    fontSize: size,
+    fontFamily: fontFamily ?? DEFAULTS.fontFamily,
+    fontWeight: fontWeight ?? DEFAULTS.fontWeight,
+    fontStyle: fontStyle ?? DEFAULTS.fontStyle,
+    lineHeight,
+    letterSpacing: letterSpacing ?? DEFAULTS.letterSpacing,
+    textAlign: textAlign ?? DEFAULTS.textAlign,
+    textDecoration: textDecoration ?? DEFAULTS.textDecoration,
+  }
+}
+
+export function toFontSpec(t: EffectiveText): FontSpec {
+  return {
+    family: t.fontFamily,
+    size: t.fontSize,
+    weight: t.fontWeight,
+    italic: t.fontStyle === "italic",
+    letterSpacing: t.letterSpacing,
+  }
+}
+
+/**
+ * Greedy word-wrap to `maxWidth` (honoring explicit \n, and breaking over-long words). Returns the
+ * lines and the widest line. Ported from the DOM measure system, but measuring via the host so it
+ * works headless. `maxWidth = Infinity` yields intrinsic (no-wrap) sizing.
+ */
+export function wrapText(
+  text: string,
+  maxWidth: number,
+  measure: (s: string) => number,
+): { lines: string[]; maxWidth: number } {
+  const result: string[] = []
+  let widest = 0
+
+  for (const rawLine of text.split("\n")) {
+    if (rawLine.length === 0) {
+      result.push("")
+      continue
+    }
+    let current = rawLine
+    while (current) {
+      if (measure(current) <= maxWidth) {
+        result.push(current)
+        widest = Math.max(widest, measure(current))
+        break
+      }
+
+      let splitPos = 0
+      let lastSpace = -1
+      let spaceIdx = 0
+      while ((spaceIdx = current.indexOf(" ", spaceIdx + 1)) !== -1) {
+        if (measure(current.substring(0, spaceIdx)) > maxWidth) break
+        lastSpace = spaceIdx
+      }
+
+      if (lastSpace > 0) {
+        splitPos = lastSpace
+      } else {
+        let wordEnd = current.indexOf(" ")
+        if (wordEnd === -1) wordEnd = current.length
+        const firstWord = current.substring(0, wordEnd)
+        if (measure(firstWord) > maxWidth) {
+          for (let i = 1; i <= firstWord.length; i++) {
+            if (measure(firstWord.substring(0, i)) > maxWidth) {
+              splitPos = i - 1
+              break
+            }
+          }
+        } else {
+          for (let i = wordEnd + 1; i <= current.length; i++) {
+            if (measure(current.substring(0, i)) > maxWidth) {
+              splitPos = i - 1
+              break
+            }
+          }
+        }
+      }
+
+      if (splitPos <= 0) splitPos = 1
+      const line = current.substring(0, splitPos)
+      result.push(line)
+      widest = Math.max(widest, measure(line))
+      current = current.substring(splitPos + (lastSpace > 0 ? 1 : 0))
+    }
+  }
+
+  return { lines: result, maxWidth: widest }
+}
+
+/** Appended to the last surviving line when a clamp cut the text and textOverflow is "ellipsis". */
+const ELLIPSIS = "…"
+
+/**
+ * Apply `lineClamp` / `textOverflow` to a wrapped line list. Returns the surviving lines — with the
+ * last one shortened so `…` fits the content width, unless `textOverflow: "clip"` asks for a hard
+ * cut. creator-ui touches neither prop (it changes no Yoga style), so clamping — including
+ * reporting the clamped box — is entirely the host's job: measure and the render tree both call
+ * this, so the measured height and the painted lines can't disagree.
+ *
+ * Returns the input array itself when nothing is clamped, so callers can skip the re-measure.
+ */
+export function clampLines(
+  lines: string[],
+  style: ResolvedStyle,
+  maxWidth: number,
+  measure: (s: string) => number,
+): string[] {
+  const clamp = style.lineClamp ?? 0
+  if (clamp <= 0 || lines.length <= clamp) return lines
+  const kept = lines.slice(0, clamp)
+  if (style.textOverflow === "clip") return kept
+  kept[clamp - 1] = ellipsize(kept[clamp - 1], maxWidth, measure)
+  return kept
+}
+
+/** Trim `line` (from the end, on whole characters) until `line…` fits `maxWidth`. */
+function ellipsize(line: string, maxWidth: number, measure: (s: string) => number): string {
+  // Unconstrained (intrinsic) measure: nothing to fit into, so the ellipsis just widens the box.
+  if (!isFinite(maxWidth)) return line + ELLIPSIS
+  const chars = [...line] // by code point — never cut a surrogate pair in half
+  let end = chars.length
+  while (end > 0 && measure(chars.slice(0, end).join("") + ELLIPSIS) > maxWidth) end--
+  return chars.slice(0, end).join("").trimEnd() + ELLIPSIS
+}
+
+/** Measure a text node for creator-ui (returns intrinsic/wrapped size for the given constraints). */
+export function measureTextNode(node: SceneNode, host: Host, width: number): { width: number; height: number } {
+  const t = resolveTextStyle(node)
+  const font = toFontSpec(t)
+  const measureWidth = isNaN(width) ? Infinity : width
+  const measure = (s: string) => host.measureText(s, font)
+  const wrapped = wrapText(node.text ?? "", measureWidth, measure)
+  const lines = clampLines(wrapped.lines, node.style, measureWidth, measure)
+  // A clamp reports the CLAMPED box, otherwise the layout would reflow around the full string and
+  // leave dead space under the last line. The width has to be recomputed over the surviving lines
+  // only — the widest line is often one of the ones that got cut.
+  let widest = wrapped.maxWidth
+  if (lines !== wrapped.lines) {
+    widest = 0
+    for (const line of lines) widest = Math.max(widest, measure(line))
+  }
+  return { width: Math.ceil(widest), height: Math.ceil(lines.length * t.lineHeight) }
+}
+
+/** Measure an editable field (input / textarea) for creator-ui. An input is one text line; a
+ *  textarea wraps its value at the given width (empty → one line), so a field with no explicit
+ *  height grows with its content — Yoga clamps via the node's minHeight/maxHeight styles. Font
+ *  fallbacks mirror paintInput: measure and paint must agree on the line grid. */
+export function measureEditableNode(node: SceneNode, host: Host, width: number): { width: number; height: number } {
+  const s = node.style
+  const font: FontSpec = {
+    family: s.fontFamily ?? "Roboto",
+    size: s.fontSize ?? 14,
+    weight: s.fontWeight ?? 400,
+    italic: s.fontStyle === "italic",
+    letterSpacing: s.letterSpacing ?? 0,
+  }
+  const lineHeight = s.lineHeight
+  const value = node.value ?? ""
+  if (node.type === "input") {
+    return { width: Math.ceil(host.measureText(value, font)), height: Math.ceil(lineHeight) }
+  }
+  const measureWidth = isNaN(width) ? Infinity : width
+  const wrapped = wrapText(value, measureWidth, (t) => host.measureText(t, font))
+  return { width: Math.ceil(wrapped.maxWidth), height: Math.ceil(Math.max(1, wrapped.lines.length) * lineHeight) }
+}
+
+/** Measure an image node for creator-ui (intrinsic size). A source crop (atlas frame) uses the crop's
+ *  w/h. An SVG is a vector → its size comes from the viewBox and it may upscale; a raster is clamped
+ *  to not upscale. */
+export function measureImageNode(
+  node: SceneNode,
+  host: Host,
+  width: number,
+  height: number,
+): { width: number; height: number } {
+  const raw = node.imageSrcRaw
+  let iw = 0
+  let ih = 0
+
+  if (node.sourceRect) {
+    iw = node.sourceRect[2]
+    ih = node.sourceRect[3]
+  } else if (isSvgSource(raw)) {
+    // Inline SVG: size from the viewBox (no decode needed — works on the headless/JSON path too).
+    const vb = extractSvgViewBox(raw.svg)
+    if (vb) {
+      iw = vb.width
+      ih = vb.height
+    } else {
+      const info = host.getImage(host.resolveSrc(raw) ?? "")
+      iw = info?.naturalWidth ?? 0
+      ih = info?.naturalHeight ?? 0
+    }
+  } else {
+    const src = host.resolveSrc(raw)
+    const info = src ? host.getImage(src) : undefined
+    iw = info?.naturalWidth ?? 0
+    ih = info?.naturalHeight ?? 0
+  }
+  if (iw === 0 || ih === 0) return { width: 0, height: 0 }
+
+  // Never past the intrinsic size under a constraint (the CSS rule, iOS's and the desktop's measure):
+  // an SVG scales without quality loss, but an unsized icon still lays out at its own size — a box
+  // that names a dimension is exact for yoga, which sizes past this answer anyway.
+  const fit = Math.min(width / iw, height / ih)
+  const k =
+    isNaN(width) && isNaN(height)
+      ? 1
+      : isNaN(width)
+        ? height / ih
+        : isNaN(height)
+          ? width / iw
+          : Math.min(fit, 1)
+  return { width: iw * k, height: ih * k }
+}

package/src/core/util/colors.ts

@@ -0,0 +1,30 @@
+import type { RGBA } from "../../types"
+
+export interface RGBAChannels {
+  r: number
+  g: number
+  b: number
+  a: number
+}
+
+/** Unpack a 0xRRGGBBAA color into channels (a in 0..255). */
+export function unpackRGBA(v: RGBA): RGBAChannels {
+  const u = v >>> 0
+  return { r: (u >>> 24) & 0xff, g: (u >>> 16) & 0xff, b: (u >>> 8) & 0xff, a: u & 0xff }
+}
+
+/** 0xRRGGBBAA → "#rrggbbaa" (lowercase), the readable form used in the JSON output. */
+export function rgbaToHex(v: RGBA): string {
+  return "#" + (v >>> 0).toString(16).padStart(8, "0")
+}
+
+/** 0xRRGGBBAA → a CSS/canvas "rgba(r, g, b, a)" string. */
+export function rgbaToCss(v: RGBA): string {
+  const { r, g, b, a } = unpackRGBA(v)
+  return `rgba(${r}, ${g}, ${b}, ${(a / 255).toFixed(4)})`
+}
+
+/** True if the color is fully transparent (skip painting). */
+export function isTransparent(v: RGBA | undefined): boolean {
+  return v === undefined || (v >>> 0 & 0xff) === 0
+}

package/src/core/util/genericFamilies.ts

@@ -0,0 +1,30 @@
+/*
+ * Skia (@napi-rs/canvas) does not resolve CSS generic font families at all — "serif",
+ * "sans-serif", "monospace" and the SDK's "monospaced" spelling all land on the same default
+ * fallback face (probe-verified, even with system fonts enumerated). Headless hosts therefore
+ * pin each generic to a vendored concrete family (registered in headless/fonts.ts), which keeps
+ * generic text real and deterministic on any machine — including fontless Linux render servers.
+ * Browser hosts don't use this map: CSS resolves generics natively there (they only alias the
+ * SDK's "monospaced" to the CSS keyword "monospace").
+ */
+export const HEADLESS_GENERIC_FAMILIES: Record<string, string> = {
+  "sans-serif": "Roboto",
+  "serif": "PT Serif",
+  "monospace": "JetBrains Mono",
+  "monospaced": "JetBrains Mono", // the SDK/iOS spelling
+}
+
+export const resolveHeadlessFamily = (family: string): string =>
+  HEADLESS_GENERIC_FAMILIES[family] ?? family
+
+// The family list of a `ctx.font` shorthand sits after the size token ("italic 500 16px/1.2 …").
+const SHORTHAND_FAMILIES = /^(.*?\S+px(?:\/\S+)?\s+)(.+)$/
+
+/** Rewrite generic families inside a canvas `ctx.font` shorthand ("16px serif" → "16px PT Serif"),
+ *  for the headless canvas replay. Unparseable strings pass through untouched. */
+export const resolveHeadlessFontShorthand = (font: string): string => {
+  const m = font.match(SHORTHAND_FAMILIES)
+  if (!m) return font
+  const families = m[2].split(",").map((f) => resolveHeadlessFamily(f.trim()))
+  return m[1] + families.join(", ")
+}

package/src/core/util/geometry.ts

@@ -0,0 +1,121 @@
+import type { BorderRadius, RadialGradient, Rect } from "../../types"
+
+/** Clamp the corner radii so opposite corners never overlap (CSS behavior). */
+export function clampRadius(radius: BorderRadius | undefined, rect: Rect): BorderRadius | undefined {
+  if (!radius) return undefined
+  const max = Math.min(rect.width, rect.height) / 2
+  return {
+    tl: Math.min(radius.tl, max),
+    tr: Math.min(radius.tr, max),
+    br: Math.min(radius.br, max),
+    bl: Math.min(radius.bl, max),
+  }
+}
+
+export function hasRadius(radius: BorderRadius | undefined): boolean {
+  return !!radius && (radius.tl > 0 || radius.tr > 0 || radius.br > 0 || radius.bl > 0)
+}
+
+/**
+ * Resolve object-fit into source (image px) + destination (screen px) rects, ready for a canvas
+ * drawImage(src.x, src.y, src.w, src.h, dst.x, dst.y, dst.w, dst.h).
+ */
+export function computeObjectFit(
+  naturalWidth: number,
+  naturalHeight: number,
+  box: Rect,
+  fit: "cover" | "contain" | "fill",
+): { src: Rect; dst: Rect } {
+  const full: Rect = { x: 0, y: 0, width: naturalWidth, height: naturalHeight }
+  if (fit === "fill" || naturalWidth === 0 || naturalHeight === 0) {
+    return { src: full, dst: box }
+  }
+
+  if (fit === "cover") {
+    // Crop the image so it fills the box without distortion.
+    const scale = Math.max(box.width / naturalWidth, box.height / naturalHeight)
+    const sw = box.width / scale
+    const sh = box.height / scale
+    return {
+      src: { x: (naturalWidth - sw) / 2, y: (naturalHeight - sh) / 2, width: sw, height: sh },
+      dst: box,
+    }
+  }
+
+  // contain: scale to fit inside, centered.
+  const scale = Math.min(box.width / naturalWidth, box.height / naturalHeight)
+  const dw = naturalWidth * scale
+  const dh = naturalHeight * scale
+  return {
+    src: full,
+    dst: { x: box.x + (box.width - dw) / 2, y: box.y + (box.height - dh) / 2, width: dw, height: dh },
+  }
+}
+
+/**
+ * Resolve a CSS gradient angle (0 = to top, 90 = to right, clockwise) into a gradient line through a
+ * rect (start = 0%, end = 100%), using the standard CSS endpoint projection.
+ */
+export function gradientLine(angle: number, rect: Rect) {
+  const rad = (angle * Math.PI) / 180
+  const dx = Math.sin(rad)
+  const dy = -Math.cos(rad)
+  const cx = rect.x + rect.width / 2
+  const cy = rect.y + rect.height / 2
+  const halfLen = (Math.abs(rect.width * dx) + Math.abs(rect.height * dy)) / 2
+  return {
+    x0: cx - dx * halfLen,
+    y0: cy - dy * halfLen,
+    x1: cx + dx * halfLen,
+    y1: cy + dy * halfLen,
+  }
+}
+
+/**
+ * Resolve a radial gradient's CSS geometry against a rect: the center (absolute px) and the two
+ * semi-axes `rx`/`ry` (px) of the ending ellipse. Implements the CSS extent keywords; a `circle`
+ * uses a single radius (equal axes). For the corner extents an ellipse keeps the matching side
+ * ellipse's aspect ratio and passes through that corner (the √2 factor for an axis-aligned box).
+ */
+export function radialGeometry(g: RadialGradient, rect: Rect) {
+  const cx = rect.x + g.cx * rect.width
+  const cy = rect.y + g.cy * rect.height
+
+  // Explicit radii: px used directly, a "fraction" (from a % radius) resolves against the box axis.
+  if (g.extent === "explicit") {
+    const rx = g.rxUnit === "fraction" ? (g.rx ?? 0) * rect.width : (g.rx ?? 0)
+    const ry = g.ryUnit === "fraction" ? (g.ry ?? 0) * rect.height : (g.ry ?? 0)
+    return { cx, cy, rx, ry }
+  }
+
+  // distances from the center to each side
+  const left = g.cx * rect.width
+  const right = (1 - g.cx) * rect.width
+  const top = g.cy * rect.height
+  const bottom = (1 - g.cy) * rect.height
+  const nearX = Math.min(left, right)
+  const farX = Math.max(left, right)
+  const nearY = Math.min(top, bottom)
+  const farY = Math.max(top, bottom)
+
+  let rx: number
+  let ry: number
+  if (g.shape === "circle") {
+    let r: number
+    switch (g.extent) {
+      case "closest-side": r = Math.min(nearX, nearY); break
+      case "farthest-side": r = Math.max(farX, farY); break
+      case "closest-corner": r = Math.hypot(nearX, nearY); break
+      default: r = Math.hypot(farX, farY); break // farthest-corner
+    }
+    rx = ry = r
+  } else {
+    switch (g.extent) {
+      case "closest-side": rx = nearX; ry = nearY; break
+      case "farthest-side": rx = farX; ry = farY; break
+      case "closest-corner": rx = nearX * Math.SQRT2; ry = nearY * Math.SQRT2; break
+      default: rx = farX * Math.SQRT2; ry = farY * Math.SQRT2; break // farthest-corner
+    }
+  }
+  return { cx, cy, rx, ry }
+}