lecodes-web-canvas 2.0.0

package/src/core/util/svgSrc.ts

@@ -0,0 +1,141 @@
+// Image-source resolution, shared by every Host. The authoring layer (worker) hands an image `src`
+// (or `backgroundImage`) as one of: a string url, an inline `SvgSource` ({ svg }), or a host buffer
+// handle ({ _id } — an SDK `FetchResponse`/`File`, both carrying the buffer id under `_id`). A raw
+// DOM `File` is a separate, browser-embed-only case. Only the string case is platform-free; the rest
+// need a host-provided URL (asset bytes / object URL), so each Host wires those callbacks in.
+
+/** An inline SVG source (`SvgSource(...)` in the worker). */
+export function isSvgSource(src: unknown): src is { svg: string } {
+  return typeof src === "object" && src !== null && "svg" in (src as Record<string, unknown>)
+}
+
+/** A host buffer handle: an SDK `FetchResponse` / `File` / uploaded asset, keyed by its buffer id.
+ *  Checked BEFORE isFileLike — an SDK `File` is a plain object with `_id`, not a DOM File. */
+function hasId(src: unknown): src is { _id: number } {
+  return typeof src === "object" && src !== null && "_id" in (src as Record<string, unknown>)
+}
+
+/** A baked `_creatorCanvas` surface (UIImage(canvas)) — resolved to a texture via a CanvasSurfaceProvider. */
+function hasCanvasSurface(src: unknown): src is { canvasSurface: number } {
+  return typeof src === "object" && src !== null && "canvasSurface" in (src as Record<string, unknown>)
+}
+
+/** Synthetic url a `{ canvasSurface }` src resolves to; the host turns it back into a baked surface. */
+export const CANVAS_SRC_PREFIX = "lecodes-canvas://"
+/** Parse a `lecodes-canvas://N` url back to its surface id, or undefined. */
+export function canvasSurfaceId(src: string): number | undefined {
+  return src.startsWith(CANVAS_SRC_PREFIX) ? Number(src.slice(CANVAS_SRC_PREFIX.length)) : undefined
+}
+
+/** A raw DOM `File` — only ever reaches here from a browser embed handing one in directly. The SDK's
+ *  `File` is NOT one of these: it's a `{ _id, name, size }` buffer handle caught by hasId above. */
+function isFileLike(src: unknown): boolean {
+  return typeof File !== "undefined" && src instanceof File
+}
+
+/** Inline SVG → a `data:image/svg+xml` URI an `<img>` / decoder can load (mirrors the DOM viewer). */
+export function svgToDataUri(svg: string): string {
+  let s = svg.trim()
+  // A data: URI is parsed as a standalone XML document — xmlns is mandatory there (inline DOM <svg>
+  // tolerates its absence; a data-uri image without it renders broken).
+  if (!/\sxmlns\s*=/.test(s)) s = s.replace(/<svg\b/, '<svg xmlns="http://www.w3.org/2000/svg"')
+  const bytes = new TextEncoder().encode(s)
+  let binary = ""
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return `data:image/svg+xml;base64,${btoa(binary)}`
+}
+
+/** True if a *resolved* src is an SVG (data-uri or `.svg` url) — i.e. a mask-capable, tintable image.
+ *  Used to gate `tintColor`: SVG recolors (mask), an opaque raster does not (the DOM no-ops it). */
+export function isSvgLikeSrc(src: string | undefined): boolean {
+  return !!src && (src.startsWith("data:image/svg+xml") || /\.svg(\?|#|$)/i.test(src))
+}
+
+/**
+ * Intrinsic size of an inline SVG, taken from its `viewBox` ("min-x min-y width height"), or its
+ * `<svg>` width/height attributes, or null. SVG is a vector, so this is the size to lay out at (and
+ * it may upscale). Matches the DOM, which reads the viewBox into `data-viewbox` for measuring.
+ */
+export function extractSvgViewBox(svg: string): { width: number; height: number } | null {
+  // Only read the opening <svg> tag, so child element width/height never leak in.
+  const tag = svg.match(/<svg\b[^>]*>/i)?.[0] ?? ""
+  const vb = tag.match(/viewBox\s*=\s*["']\s*[\d.+-]+\s+[\d.+-]+\s+([\d.+-]+)\s+([\d.+-]+)\s*["']/i)
+  if (vb) {
+    const w = parseFloat(vb[1]), h = parseFloat(vb[2])
+    if (w > 0 && h > 0) return { width: w, height: h }
+  }
+  const w = parseFloat(tag.match(/\bwidth\s*=\s*["']?([\d.]+)/i)?.[1] ?? "")
+  const h = parseFloat(tag.match(/\bheight\s*=\s*["']?([\d.]+)/i)?.[1] ?? "")
+  if (w > 0 && h > 0) return { width: w, height: h }
+  return null
+}
+
+/** Decode an `data:image/svg+xml` URI (base64 or text/url-encoded) back to its markup, or null. */
+export function decodeSvgDataUri(src: string): string | null {
+  const m = /^data:image\/svg\+xml(;[^,]*)?,([\s\S]*)$/.exec(src)
+  if (!m) return null
+  const data = m[2]
+  try {
+    if (/;base64/i.test(m[1] ?? "")) {
+      const bin = atob(data)
+      const bytes = new Uint8Array(bin.length)
+      for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
+      return new TextDecoder().decode(bytes)
+    }
+    return decodeURIComponent(data)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The intrinsic (viewBox) size of an SVG from its resolved src. SVGs without explicit width/height
+ * have NO intrinsic size, so a browser `<img>` reports the CSS default 300×150 — wrong for layout +
+ * object-fit. Reading the viewBox instead makes canvas/native size SVGs to their box like the DOM
+ * does. Inline data-uris are decoded synchronously; a remote/blob `.svg` url needs `fetchText`.
+ */
+export async function svgIntrinsicSize(
+  src: string,
+  fetchText?: (url: string) => Promise<string | null>,
+): Promise<{ width: number; height: number } | null> {
+  if (!isSvgLikeSrc(src)) return null
+  const inline = decodeSvgDataUri(src)
+  if (inline) return extractSvgViewBox(inline)
+  if (!fetchText) return null
+  const text = await fetchText(src).catch(() => null)
+  return text ? extractSvgViewBox(text) : null
+}
+
+export interface SrcResolverOptions {
+  /** Resolve a host buffer handle ({ _id } — SDK `FetchResponse` / `File`) to a url (e.g. a blob url
+   *  for the fetched bytes). */
+  assetUrl?: (id: number) => string | undefined
+  /** Resolve a raw DOM `File` to a url (browser: `URL.createObjectURL`). Not the SDK `File` — that
+   *  one is a buffer handle and goes through `assetUrl`. */
+  fileUrl?: (file: unknown) => string | undefined
+}
+
+/**
+ * Build a memoized `resolveSrc(rawSrc) → string | undefined`. Strings pass through; `SvgSource` →
+ * data-uri; `{ _id }` (SDK `FetchResponse`/`File`) and a raw DOM `File` go through the injected
+ * callbacks (undefined when not wired, e.g. headless). Memoized by object identity so SVG
+ * data-uris / blob urls are created once per source.
+ */
+export function createSrcResolver(opts: SrcResolverOptions = {}): (src: unknown) => string | undefined {
+  const cache = new WeakMap<object, string>()
+  return (src: unknown): string | undefined => {
+    if (src == null) return undefined
+    if (typeof src === "string") return src
+    if (typeof src !== "object") return undefined
+    const obj = src as object
+    const cached = cache.get(obj)
+    if (cached !== undefined) return cached
+    let out: string | undefined
+    if (isSvgSource(obj)) out = svgToDataUri(obj.svg)
+    else if (hasCanvasSurface(obj)) out = CANVAS_SRC_PREFIX + obj.canvasSurface
+    else if (hasId(obj)) out = opts.assetUrl?.(obj._id)
+    else if (isFileLike(obj)) out = opts.fileUrl?.(obj)
+    if (out !== undefined) cache.set(obj, out)
+    return out
+  }
+}

package/src/host/BrowserHost.ts

@@ -0,0 +1,132 @@
+import type { ImageInfo } from "../types"
+import { resolveCanvasImage, type CanvasSurfaceProvider, type FontSpec, type Host } from "./Host"
+import { createSrcResolver, isSvgLikeSrc, svgIntrinsicSize } from "../core/util/svgSrc"
+
+// The SDK spells the fixed-width system family "monospaced" (the iOS name); CSS spells it
+// "monospace". Other generics ("serif", "sans-serif") are real CSS keywords and resolve natively.
+const cssFamily = (family: string) => (family === "monospaced" ? "monospace" : family)
+
+function fontCss(font: FontSpec): string {
+  return `${font.italic ? "italic " : ""}${font.weight} ${font.size}px ${cssFamily(font.family)}`
+}
+
+export interface BrowserHostOptions {
+  /** Resolve an uploaded asset ({ _id }) to a url — the app injects this (e.g. the viewer's
+   *  `getUrl(id)` blob-url resolver). Without it, `{ _id }` image sources don't render. */
+  resolveAssetUrl?: (id: number) => string | undefined
+  /** Resolve `UIImage(canvas)` sources (baked `_creatorCanvas` surfaces) to textures. */
+  canvasSurfaces?: CanvasSurfaceProvider
+}
+
+/** Browser host: text metrics via a measuring 2D context, image decode via HTMLImageElement. */
+export class BrowserHost implements Host {
+  private ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D
+  private images = new Map<string, ImageInfo>()
+  private pending = new Map<string, Promise<ImageInfo>>()
+  private resolver: (src: unknown) => string | undefined
+  private canvasSurfaces?: CanvasSurfaceProvider
+
+  constructor(opts: BrowserHostOptions = {}) {
+    // Measure on a DOM canvas whenever a document exists: a main-thread OffscreenCanvas context
+    // does not reliably resolve document.fonts faces in every browser (Safari), which would keep
+    // measuring custom faces with the fallback while the visible canvas paints the real one.
+    // OffscreenCanvas stays for workers, where there is no document.
+    const canvas =
+      typeof document !== "undefined"
+        ? (document.createElement("canvas") as HTMLCanvasElement)
+        : new OffscreenCanvas(8, 8)
+    this.ctx = (canvas as any).getContext("2d")
+    this.canvasSurfaces = opts.canvasSurfaces
+    // Inline SVG → data-uri; uploaded assets via the app's resolver; File → object url.
+    this.resolver = createSrcResolver({
+      assetUrl: opts.resolveAssetUrl,
+      fileUrl: (file) => URL.createObjectURL(file as File),
+    })
+  }
+
+  resolveSrc(src: unknown): string | undefined {
+    return this.resolver(src)
+  }
+
+  /** Image decodes still in flight — lets a host idle its paint loop until they land (the
+   *  headless NodeCanvasHost exposes the same probe). */
+  pendingImages(): number {
+    return this.pending.size
+  }
+
+  resolveFontFamily(family: string): string {
+    return cssFamily(family)
+  }
+
+  measureText(text: string, font: FontSpec): number {
+    this.ctx.font = fontCss(font)
+    ;(this.ctx as any).letterSpacing = `${font.letterSpacing}px`
+    return this.ctx.measureText(text).width
+  }
+
+  fontMetrics(font: FontSpec) {
+    this.ctx.font = fontCss(font)
+    const m = this.ctx.measureText("Mg")
+    // The FONT's ascent/descent — the metrics CSS line-box layout centers inside line-height.
+    // The ink extent (actualBoundingBox of the sample glyphs) is smaller, which would place the
+    // baseline ~1px higher than the DOM/native render of the same text.
+    const ascent = m.fontBoundingBoxAscent || m.actualBoundingBoxAscent || font.size * 0.8
+    const descent = m.fontBoundingBoxDescent || m.actualBoundingBoxDescent || font.size * 0.2
+    return { ascent, descent }
+  }
+
+  getImage(src: string): ImageInfo | undefined {
+    return resolveCanvasImage(src, this.canvasSurfaces) ?? this.images.get(src)
+  }
+
+  loadImage(src: string): Promise<ImageInfo> {
+    const canvasImg = resolveCanvasImage(src, this.canvasSurfaces)
+    if (canvasImg) return Promise.resolve(canvasImg)   // baked surface — already rasterized, no decode
+    const cached = this.images.get(src)
+    if (cached) return Promise.resolve(cached)
+    const inFlight = this.pending.get(src)
+    if (inFlight) return inFlight
+
+    const promise = (async (): Promise<ImageInfo> => {
+      const img = await this.decode(src)
+      let naturalWidth = img.naturalWidth
+      let naturalHeight = img.naturalHeight
+      // A browser gives a viewBox-only SVG the CSS default 300×150 intrinsic size, which breaks layout
+      // + object-fit (the icon won't size to its box). Use the real viewBox instead — matching the DOM
+      // (which reads the viewBox) and the native renderers.
+      if (isSvgLikeSrc(src)) {
+        const vb = await svgIntrinsicSize(src, (url) => fetch(url).then((r) => (r.ok ? r.text() : null)))
+        if (vb) { naturalWidth = vb.width; naturalHeight = vb.height }
+      }
+      const info: ImageInfo = { src, naturalWidth, naturalHeight, handle: img }
+      this.images.set(src, info)
+      this.pending.delete(src)
+      return info
+    })()
+    this.pending.set(src, promise)
+    promise.catch(() => this.pending.delete(src)) // a decode failure must clear the in-flight slot
+    return promise
+  }
+
+  /** Decode an image url into an HTMLImageElement (resolves on load, rejects on error). */
+  private decode(src: string): Promise<HTMLImageElement> {
+    return new Promise((resolve, reject) => {
+      const img = new Image()
+      img.onload = () => resolve(img)
+      img.onerror = (e) => reject(e)
+      img.src = src
+    })
+  }
+
+  // Browser host: CDN faces should come as woff2 (the font() macro's generated code reads this).
+  fontFormat = "woff2" as const
+
+  async loadFont(family: string, url: string, options: { weight?: number; style?: string }): Promise<void> {
+    if (typeof (globalThis as any).FontFace === "undefined") return
+    const face = new FontFace(family, `url(${url})`, options as FontFaceDescriptors)
+    // Added before load resolves: text swaps in the moment the bytes land, whether or not
+    // anything awaits the legacy completion callback (Renderer purges wrap caches on resolve).
+    ;(document as any).fonts.add(face)
+    await face.load()
+  }
+}

package/src/host/HeadlessHost.ts

@@ -0,0 +1,64 @@
+import type { ImageInfo } from "../types"
+import { resolveCanvasImage, type CanvasSurfaceProvider, type FontSpec, type Host } from "./Host"
+import { createSrcResolver } from "../core/util/svgSrc"
+
+export interface HeadlessHostOptions {
+  /** Per-character advance as a fraction of font size (default 0.5 — a stable monospace-ish model). */
+  charWidthFactor?: number
+  /** Preloaded intrinsic image sizes, keyed by src, so layout is deterministic with no I/O. */
+  images?: Record<string, { width: number; height: number }>
+  /** Resolve `UIImage(canvas)` sources (baked `_creatorCanvas` surfaces) to textures. */
+  canvasSurfaces?: CanvasSurfaceProvider
+}
+
+/**
+ * Deterministic, I/O-free host for headless runs and tests. Text metrics follow a simple, stable
+ * model (so snapshots don't depend on installed fonts), and image sizes come from a preloaded map.
+ */
+export class HeadlessHost implements Host {
+  private factor: number
+  private images = new Map<string, ImageInfo>()
+  private canvasSurfaces?: CanvasSurfaceProvider
+
+  constructor(opts: HeadlessHostOptions = {}) {
+    this.factor = opts.charWidthFactor ?? 0.5
+    this.canvasSurfaces = opts.canvasSurfaces
+    for (const [src, size] of Object.entries(opts.images ?? {})) {
+      this.images.set(src, { src, naturalWidth: size.width, naturalHeight: size.height })
+    }
+  }
+
+  /** Register an intrinsic image size after construction. */
+  setImageSize(src: string, width: number, height: number) {
+    this.images.set(src, { src, naturalWidth: width, naturalHeight: height })
+  }
+
+  measureText(text: string, font: FontSpec): number {
+    if (text.length === 0) return 0
+    return text.length * (font.size * this.factor + font.letterSpacing)
+  }
+
+  fontMetrics(font: FontSpec) {
+    return { ascent: font.size * 0.8, descent: font.size * 0.2 }
+  }
+
+  getImage(src: string): ImageInfo | undefined {
+    return resolveCanvasImage(src, this.canvasSurfaces) ?? this.images.get(src)
+  }
+
+  loadImage(src: string): Promise<ImageInfo> {
+    return Promise.resolve(resolveCanvasImage(src, this.canvasSurfaces) ?? this.images.get(src) ?? { src, naturalWidth: 0, naturalHeight: 0 })
+  }
+
+  /** No real fonts headless — metrics are synthetic, so this is a no-op. */
+  loadFont(): Promise<void> {
+    return Promise.resolve()
+  }
+
+  // Inline SVG → data-uri; uploaded `{ _id }` / `File` have no bytes headless → undefined (project
+  // image assets compile to string urls in the CLI, so this is the rare case).
+  private resolver = createSrcResolver()
+  resolveSrc(src: unknown): string | undefined {
+    return this.resolver(src)
+  }
+}

package/src/host/Host.ts

@@ -0,0 +1,85 @@
+import type { ImageInfo } from "../types"
+import { canvasSurfaceId } from "../core/util/svgSrc"
+
+/**
+ * Access to baked `_creatorCanvas` surfaces, so a `UIImage(canvas)` resolves to a texture. `canvas` is
+ * a drawable the painter can `drawImage` (an OffscreenCanvas on web, a napi canvas headless); width/
+ * height are the surface's device pixels. Injected into a Host so it can turn a `lecodes-canvas://N`
+ * src into an ImageInfo.
+ */
+export interface CanvasSurfaceProvider {
+  getSurface(surfaceId: number): { canvas: unknown, width: number, height: number } | null
+}
+
+/** If `src` is a `lecodes-canvas://N` url, resolve it to an ImageInfo via the provider (the baked
+ *  surface is already rasterized → synchronous). Returns undefined for any other src. */
+export function resolveCanvasImage(src: string, provider: CanvasSurfaceProvider | undefined): ImageInfo | undefined {
+  if (!provider) return undefined
+  const id = canvasSurfaceId(src)
+  if (id === undefined) return undefined
+  const surf = provider.getSurface(id)
+  if (!surf) return undefined
+  return { src, naturalWidth: surf.width, naturalHeight: surf.height, handle: surf.canvas }
+}
+
+/** A fully-resolved font, as the core asks the host to measure it. */
+export interface FontSpec {
+  family: string
+  size: number
+  weight: number
+  italic: boolean
+  letterSpacing: number
+}
+
+/**
+ * Platform capabilities the portable core can't implement itself. Injected so the core runs
+ * headless under Bun (HeadlessHost) and in the browser (BrowserHost) unchanged.
+ */
+export interface Host {
+  /** Advance width of a single line of text, in CSS pixels. */
+  measureText(text: string, font: FontSpec): number
+
+  /** Vertical metrics for a font (used for line-height fallback and the text baseline). */
+  fontMetrics(font: FontSpec): { ascent: number; descent: number }
+
+  /**
+   * Synchronous cache lookup for an image's intrinsic size. Returns undefined until the image is
+   * decoded — the core then measures it as 0×0 (collapsed), exactly like the DOM renderer before
+   * `naturalWidth` is known.
+   */
+  getImage(src: string): ImageInfo | undefined
+
+  /**
+   * Begin (or reuse) an async decode. Resolves with the intrinsic size; the caller marks the
+   * owning screen dirty so the next render picks up the now-known size. May resolve synchronously
+   * via the cache in HeadlessHost.
+   */
+  loadImage(src: string): Promise<ImageInfo>
+
+  /**
+   * Load a custom font so subsequent `measureText`/painting use it. Web: `FontFace`; headless:
+   * disk/network bytes into the canvas backend (NodeCanvasHost) or a no-op (synthetic metrics);
+   * desktop: a tgfx typeface load. Resolves once the font is usable (or has fallen back).
+   */
+  loadFont(family: string, url: string, options: { weight?: number; style?: string }): Promise<void>
+
+  /** Preferred CDN face container (`_creatorUI.fontFormat`): browser hosts "woff2"; absent = ttf. */
+  fontFormat?: "woff2" | "ttf"
+
+  /**
+   * Map a style-level fontFamily to what this host's text stack can actually resolve — the CSS
+   * generic families, mostly: browser hosts alias the SDK's "monospaced" to the CSS keyword
+   * "monospace"; headless pins every generic to a vendored concrete face (genericFamilies.ts),
+   * because Skia has no generic resolution. Applied by paintTree when building a FontSpec; hosts
+   * also apply it inside their own measureText/fontMetrics so layout and paint always agree.
+   */
+  resolveFontFamily?(family: string): string
+
+  /**
+   * Resolve an authoring image source to a loadable url string, or undefined if it can't be. The
+   * source is a string url, an inline `SvgSource` ({ svg }), an uploaded asset ({ _id }), or a
+   * `File`. String + SVG are platform-free; `{ _id }`/`File` need platform url resolution, which only
+   * some hosts wire (e.g. the browser host with the app's asset resolver). Memoized per source.
+   */
+  resolveSrc(src: unknown): string | undefined
+}

package/src/layout/CuiPaint.gen.ts

@@ -0,0 +1,121 @@
+// AUTO-GENERATED from engines/ui/properties.mjs — DO NOT EDIT. Regenerate: bun run gen:ui-props
+//
+// The CUIPaint record layout (engines/ui/include/creator-ui/paint.gen.h) for a reader over the wasm
+// heap: `HEAPU32[(ptr >> 2) + word]` / `HEAPF32[...]`. Bits index the present / dirty masks
+// (two u32 words each: lo at word 0 / 2, hi at word 1 / 3).
+
+export const CUI_PAINT_WORDS = 78
+export const CUI_PRESENT_LO = 0, CUI_PRESENT_HI = 1, CUI_DIRTY_LO = 2, CUI_DIRTY_HI = 3
+export const CUI_INHERIT_MASK_LO = 4096, CUI_INHERIT_MASK_HI = 4080
+export const CUI_MEASURE_MASK_LO = 0, CUI_MEASURE_MASK_HI = 5104   // a dirty measure field re-measures a text leaf
+
+export type CuiKind = "float" | "color" | "enum" | "str" | "matrix" | "origin" | "gradient"
+
+export const CUI_FIELDS = {
+  display: { bit: 0, word: 4, kind: "enum" },
+  overflow: { bit: 1, word: 5, kind: "enum" },
+  scrollDirection: { bit: 2, word: 6, kind: "enum" },
+  borderWidth: { bit: 3, word: 7, kind: "float" },
+  borderTopWidth: { bit: 4, word: 8, kind: "float" },
+  borderRightWidth: { bit: 5, word: 9, kind: "float" },
+  borderBottomWidth: { bit: 6, word: 10, kind: "float" },
+  borderLeftWidth: { bit: 7, word: 11, kind: "float" },
+  borderHorizontalWidth: { bit: 8, word: 12, kind: "float" },
+  borderVerticalWidth: { bit: 9, word: 13, kind: "float" },
+  borderStartWidth: { bit: 10, word: 14, kind: "float" },
+  borderEndWidth: { bit: 11, word: 15, kind: "float" },
+  color: { bit: 12, word: 16, kind: "color" },
+  backgroundColor: { bit: 13, word: 17, kind: "color" },
+  borderColor: { bit: 14, word: 18, kind: "color" },
+  borderTopColor: { bit: 15, word: 19, kind: "color" },
+  borderRightColor: { bit: 16, word: 20, kind: "color" },
+  borderBottomColor: { bit: 17, word: 21, kind: "color" },
+  borderLeftColor: { bit: 18, word: 22, kind: "color" },
+  placeholderColor: { bit: 19, word: 23, kind: "color" },
+  refreshControlColor: { bit: 20, word: 24, kind: "color" },
+  tintColor: { bit: 21, word: 25, kind: "color" },
+  rippleColor: { bit: 22, word: 26, kind: "color" },
+  overlayColor: { bit: 23, word: 27, kind: "color" },
+  backgroundImage: { bit: 24, word: 28, kind: "str" },
+  backgroundSize: { bit: 25, word: 29, kind: "enum" },
+  backgroundGradient: { bit: 26, word: 30, kind: "gradient" },
+  borderRadius: { bit: 27, word: 31, kind: "float" },
+  borderTopLeftRadius: { bit: 28, word: 32, kind: "float" },
+  borderTopRightRadius: { bit: 29, word: 33, kind: "float" },
+  borderBottomRightRadius: { bit: 30, word: 34, kind: "float" },
+  borderBottomLeftRadius: { bit: 31, word: 35, kind: "float" },
+  opacity: { bit: 32, word: 36, kind: "float" },
+  transform: { bit: 33, word: 37, kind: "matrix" },
+  transformOrigin: { bit: 34, word: 46, kind: "origin" },
+  pointerEvents: { bit: 35, word: 50, kind: "enum" },
+  fontSize: { bit: 36, word: 51, kind: "float" },
+  fontWeight: { bit: 37, word: 52, kind: "float" },
+  fontStyle: { bit: 38, word: 53, kind: "enum" },
+  fontFamily: { bit: 39, word: 54, kind: "str" },
+  lineHeight: { bit: 40, word: 55, kind: "float" },
+  letterSpacing: { bit: 41, word: 56, kind: "float" },
+  textAlign: { bit: 42, word: 57, kind: "enum" },
+  textDecoration: { bit: 43, word: 58, kind: "enum" },
+  lineClamp: { bit: 44, word: 59, kind: "float" },
+  textOverflow: { bit: 45, word: 60, kind: "enum" },
+  objectFit: { bit: 46, word: 61, kind: "enum" },
+  placeholder: { bit: 47, word: 62, kind: "str" },
+  type: { bit: 48, word: 63, kind: "enum" },
+  enterKey: { bit: 49, word: 64, kind: "enum" },
+  autocapitalize: { bit: 50, word: 65, kind: "enum" },
+  autocorrect: { bit: 51, word: 66, kind: "float" },
+  maxLength: { bit: 52, word: 67, kind: "float" },
+  keyboardShrink: { bit: 53, word: 68, kind: "float" },
+  keyboardDismiss: { bit: 54, word: 69, kind: "float" },
+  showScrollbar: { bit: 55, word: 70, kind: "float" },
+  overscrollMode: { bit: 56, word: 71, kind: "enum" },
+  keyboardDismissMode: { bit: 57, word: 72, kind: "enum" },
+  snap: { bit: 58, word: 73, kind: "enum" },
+  sheetDetents: { bit: 59, word: 74, kind: "str" },
+  sheetDetent: { bit: 60, word: 75, kind: "float" },
+  sheetDismissible: { bit: 61, word: 76, kind: "float" },
+  dim: { bit: 62, word: 77, kind: "float" },
+} as const satisfies Record<string, { bit: number, word: number, kind: CuiKind }>
+
+export type CuiFieldKey = keyof typeof CUI_FIELDS
+
+export const CuiDisplay = { "flex": 0, "none": 1 } as const
+export const CuiOverflow = { "visible": 0, "hidden": 1, "scroll": 2 } as const
+export const CuiScrollDirection = { "vertical": 0, "horizontal": 1, "all": 2 } as const
+export const CuiBackgroundSize = { "cover": 0, "contain": 1, "fill": 2, "tile": 3 } as const
+export const CuiPointerEvents = { "all": 0, "none": 1 } as const
+export const CuiFontStyle = { "normal": 0, "italic": 1 } as const
+export const CuiTextAlign = { "start": 0, "center": 1, "end": 2, "left": 3, "right": 4 } as const
+export const CuiTextDecoration = { "underline": 0, "line-through": 1, "none": 2 } as const
+export const CuiTextOverflow = { "ellipsis": 0, "clip": 1 } as const
+export const CuiObjectFit = { "cover": 0, "contain": 1, "fill": 2 } as const
+export const CuiType = { "text": 0, "password": 1, "tel": 2, "email": 3, "number": 4, "decimal": 5, "url": 6, "search": 7, "date": 8, "time": 9 } as const
+export const CuiEnterKey = { "done": 0, "go": 1, "next": 2, "search": 3, "send": 4 } as const
+export const CuiAutocapitalize = { "none": 0, "sentences": 1, "words": 2, "characters": 3 } as const
+export const CuiOverscrollMode = { "default": 0, "none": 1, "absorb": 2 } as const
+export const CuiKeyboardDismissMode = { "interactive": 0, "scroll": 1, "none": 2 } as const
+export const CuiSnap = { "none": 0, "start": 1, "center": 2, "end": 3 } as const
+
+/** The registry spelling of each enum code, by field. */
+export const CUI_NAMES = {
+  display: ["flex", "none"],
+  overflow: ["visible", "hidden", "scroll"],
+  scrollDirection: ["vertical", "horizontal", "all"],
+  backgroundSize: ["cover", "contain", "fill", "tile"],
+  pointerEvents: ["all", "none"],
+  fontStyle: ["normal", "italic"],
+  textAlign: ["start", "center", "end", "left", "right"],
+  textDecoration: ["underline", "line-through", "none"],
+  textOverflow: ["ellipsis", "clip"],
+  objectFit: ["cover", "contain", "fill"],
+  type: ["text", "password", "tel", "email", "number", "decimal", "url", "search", "date", "time"],
+  enterKey: ["done", "go", "next", "search", "send"],
+  autocapitalize: ["none", "sentences", "words", "characters"],
+  overscrollMode: ["default", "none", "absorb"],
+  keyboardDismissMode: ["interactive", "scroll", "none"],
+  snap: ["none", "start", "center", "end"],
+} as const
+
+/** present / dirty bit test on the (lo, hi) word pair. */
+export const cuiBit = (lo: number, hi: number, bit: number): boolean =>
+  bit < 32 ? ((lo >>> bit) & 1) === 1 : ((hi >>> (bit - 32)) & 1) === 1

package/src/layout/LayoutEngine.ts

@@ -0,0 +1,78 @@
+import type { Rect, ResolvedStyle } from "../types"
+
+/** Returns the intrinsic size of a measured leaf (text / image), given the constraints. */
+export type MeasureCallback = (
+  screenId: number,
+  nodeId: number,
+  width: number,
+  height: number,
+) => { width: number; height: number }
+
+/**
+ * How the layout engine reaches a node's paint-ready style object so its per-prop style handlers
+ * (color, border, fontSize, …) can write resolved values into it.
+ */
+export interface StyleSink {
+  getStyle(screenId: number, nodeId: number): ResolvedStyle | undefined
+}
+
+/** One safe-area edge, in the CSS inset order the tuples use. */
+export type SafeEdge = "top" | "right" | "bottom" | "left"
+
+/**
+ * The layout-engine seam. The core depends only on this; `CreatorUiLayout` implements it over the
+ * reused creator-ui (Yoga) WASM, and the C++ port implements it over the native creator-ui lib.
+ */
+export interface LayoutEngine {
+  /** Create a screen/widget root node owned by `screenId`. Returns the node id. */
+  createRoot(screenId: number): number
+  /** Create a child of `parentId` at `index`. `hasMeasureFunc` for text/image leaves. */
+  createChild(parentId: number, index: number, hasMeasureFunc: boolean): number
+  removeChild(parentId: number, nodeId: number): void
+  freeTree(rootId: number, isWidget: boolean): void
+
+  /** Apply one style prop. `value: null` resets it. Layout props are consumed internally; paint
+   *  props are forwarded to the registered handlers (→ the StyleSink's ResolvedStyle). */
+  setStyle(nodeId: number, key: string, value: number | string | boolean | null, layer?: number): void
+  markDirty(nodeId: number): void
+
+  /** The creator-ui layer a `$`-class style key maps to (`$hovered` / `$pressed` / `$focused` → the
+   *  fixed interaction class layers 60267–60269, `$landscape` / `$portrait` → the global orientation
+   *  layers 258 / 257, any other `$name` → its app-global layer allocated on first sight from 272);
+   *  a key without `$` is not a state block → CUI_LAYER_NONE (0). */
+  getLayer(nodeId: number, key: string): number
+  /** Activate a layer's styles for a node (re-fires the style handlers with the layer's values). */
+  enableNodeLayer(nodeId: number, layer: number): void
+  /** Deactivate a layer's styles (re-fires the handlers with the remaining active layers). */
+  disableNodeLayer(nodeId: number, layer: number): void
+
+  calculate(rootId: number, width: number, height: number, isWidget: boolean): void
+  /** Parent-relative computed layout, or null if the node has none (e.g. display:none). */
+  getLayout(nodeId: number): Rect | null
+  /** Resolved padding edges `[left, top, right, bottom]` (px). The laid-out rect is the border box,
+   *  so self-rendered content (text / input value) must be inset by these — Yoga gives no other hook. */
+  getPadding(nodeId: number): [number, number, number, number]
+  getScreenId(nodeId: number): number
+
+  /** Total laid-out content size of a node (incl. padding) — for scroll extent. */
+  getContentHeight(nodeId: number): number
+  getContentWidth(nodeId: number): number
+
+  setConditionValue(width: number, height: number): void
+  /** Safe-area insets in CSS order (top, right, bottom, left) — the values the `safe-*` padding/margin
+   *  keywords resolve to. Passing `nodeId` re-applies those dynamic styles over that subtree now (so a
+   *  live change takes effect without an orientation change); omit it to only update the globals. */
+  setSafePaddings(top: number, right: number, bottom: number, left: number, nodeId?: number): void
+  /** Declares which safe-area edges are exact-height system BARS (Android status bar / 3-button nav
+   *  bar — content at the inset touches the chrome) vs clearance insets (iOS notch/home indicator,
+   *  gesture nav). `comfort-*` ADDS its knob past a bar edge and floors (max) a clearance edge.
+   *  Call before `setSafePaddings` — the paddings call is what re-resolves dynamic styles. */
+  setSafeAreaBars(bars: readonly SafeEdge[]): void
+  /** Merge app theme values (docs/ui-theme-plan.md): `var(--name)` refs + the comfort-* knobs.
+   *  Numbers are lengths (px), null removes. Returns true when live styles re-dispatched —
+   *  the caller should relayout + repaint. */
+  setTheme(values: Record<string, string | number | null>): boolean
+
+  setStyleSink(sink: StyleSink): void
+  setMeasureCallback(cb: MeasureCallback): void
+}