lecodes-web-canvas 2.0.0

package/src/serialize/serializeRenderTree.ts

@@ -0,0 +1,150 @@
+import type { BorderRadius, RenderNode, ResolvedStyle } from "../types"
+import { rgbaToHex } from "../core/util/colors"
+
+export interface SerializeOptions {
+  /** Decimal places for rects (default 2). */
+  precision?: number
+  /** Include the `id` (creator-ui node id) — off by default; ids are unstable across runs. */
+  includeIds?: boolean
+}
+
+/**
+ * Serialize a render tree into a plain, JSON-friendly object — the primary text output. Colors
+ * become "#rrggbbaa", rects are rounded, and only meaningful fields appear, so the result is
+ * readable for AI feedback and stable for snapshot assertions.
+ */
+export function serializeRenderTree(tree: RenderNode | null, opts: SerializeOptions = {}): unknown {
+  if (!tree) return null
+  return serializeNode(tree, opts.precision ?? 2, opts.includeIds ?? false)
+}
+
+/** Convenience: the serialized tree as pretty JSON text. */
+export function renderTreeToText(tree: RenderNode | null, opts?: SerializeOptions): string {
+  return JSON.stringify(serializeRenderTree(tree, opts), null, 2)
+}
+
+/**
+ * Serialize a whole frame — the main screen plus any widget overlays — so the JSON describes
+ * everything painted (PNG/JSON parity). Widget trees are attached as an `overlays` array on the main
+ * root (they composite above it). With no widgets this returns the bare main tree, unchanged; with no
+ * main screen but live widgets it returns `{ type: "frame", overlays }`.
+ */
+export function serializeFrame(main: RenderNode | null, widgets: RenderNode[] = [], opts: SerializeOptions = {}): unknown {
+  const precision = opts.precision ?? 2
+  const includeIds = opts.includeIds ?? false
+  const root = main ? serializeNode(main, precision, includeIds) : null
+  if (widgets.length === 0) return root
+  const overlays = widgets.map((w) => serializeNode(w, precision, includeIds))
+  if (root) {
+    root.overlays = overlays
+    return root
+  }
+  return { type: "frame", overlays }
+}
+
+/** Convenience: the serialized frame (screen + overlays) as pretty JSON text. */
+export function frameToText(main: RenderNode | null, widgets: RenderNode[] = [], opts?: SerializeOptions): string {
+  return JSON.stringify(serializeFrame(main, widgets, opts), null, 2)
+}
+
+function round(n: number, p: number): number {
+  const f = 10 ** p
+  return Math.round(n * f) / f
+}
+
+function serializeNode(node: RenderNode, precision: number, includeIds: boolean): any {
+  const r = node.rect
+  const out: any = { type: node.type }
+  if (node.name) out.name = node.name
+  out.rect = [round(r.x, precision), round(r.y, precision), round(r.width, precision), round(r.height, precision)]
+  if (includeIds) out.id = node.id
+
+  const style = serializeStyle(node.style)
+  if (style) out.style = style
+
+  if (node.text !== undefined) out.text = node.text
+  if (node.lines && (node.lines.length !== 1 || node.lines[0] !== node.text)) out.lines = node.lines
+  // Editables: show what the field says — its typed value, or the placeholder an empty field
+  // renders (also the AI-facing selector for label-less inputs).
+  if (node.value !== undefined && node.value !== "") out.value = node.value
+  if (node.style.placeholder !== undefined) out.placeholder = node.style.placeholder
+  if (node.image) {
+    out.image = { src: node.image.src, natural: [node.image.naturalWidth, node.image.naturalHeight] }
+  }
+  if (node.sourceRect) out.sourceRect = node.sourceRect
+  if (node.state && (node.state.pressed || node.state.classes?.length)) {
+    out.state = {
+      ...(node.state.pressed ? { pressed: true } : {}),
+      ...(node.state.classes?.length ? { classes: node.state.classes } : {}),
+    }
+  }
+  if (node.scroll) {
+    out.scroll = { offset: round(node.scroll.offset, precision), content: round(node.scroll.content, precision) }
+  }
+
+  if (node.children.length > 0) {
+    out.children = node.children.map((c) => serializeNode(c, precision, includeIds))
+  }
+  return out
+}
+
+function radiusObj(radius: BorderRadius) {
+  if (radius.tl === radius.tr && radius.tr === radius.br && radius.br === radius.bl) return radius.tl
+  return [radius.tl, radius.tr, radius.br, radius.bl]
+}
+
+function serializeStyle(s: ResolvedStyle): Record<string, unknown> | undefined {
+  const out: Record<string, unknown> = {}
+  if (s.backgroundColor !== undefined) out.backgroundColor = rgbaToHex(s.backgroundColor)
+  if (s.opacity !== undefined) out.opacity = s.opacity
+  if (s.color !== undefined) out.color = rgbaToHex(s.color)
+  if (s.fontSize !== undefined) out.fontSize = s.fontSize
+  if (s.fontFamily !== undefined) out.fontFamily = s.fontFamily
+  if (s.fontWeight !== undefined) out.fontWeight = s.fontWeight
+  if (s.fontStyle !== undefined && s.fontStyle !== "normal") out.fontStyle = s.fontStyle
+  if (s.lineHeight !== undefined) out.lineHeight = s.lineHeight
+  if (s.letterSpacing) out.letterSpacing = s.letterSpacing
+  if (s.textAlign !== undefined && s.textAlign !== "start") out.textAlign = s.textAlign
+  if (s.textDecoration !== undefined && s.textDecoration !== "none") out.textDecoration = s.textDecoration
+  // Only an ACTIVE clamp is worth showing: `lines` already carries the visible result (with its "…"),
+  // and `textOverflow` means nothing without a clamp.
+  if (s.lineClamp) {
+    out.lineClamp = s.lineClamp
+    if (s.textOverflow === "clip") out.textOverflow = s.textOverflow
+  }
+  if (s.objectFit !== undefined) out.objectFit = s.objectFit
+  if (s.tintColor !== undefined) out.tintColor = rgbaToHex(s.tintColor)
+  if (s.overlayColor !== undefined) out.overlayColor = rgbaToHex(s.overlayColor)
+  if (s.backgroundImage !== undefined) out.backgroundImage = s.backgroundImage
+  if (s.backgroundSize !== undefined) out.backgroundSize = s.backgroundSize
+  if (s.backgroundGradients !== undefined && s.backgroundGradients.length > 0) {
+    out.backgroundGradients = s.backgroundGradients.map((g) => {
+      const stops = g.stops.map((st) => ({ color: rgbaToHex(st.color), position: st.position }))
+      if (g.type === "radial") {
+        const rad: Record<string, unknown> = { type: "radial", shape: g.shape, extent: g.extent, cx: g.cx, cy: g.cy, stops }
+        if (g.extent === "explicit") {
+          rad.rx = g.rx
+          rad.ry = g.ry
+          rad.rxUnit = g.rxUnit
+          rad.ryUnit = g.ryUnit
+        }
+        return rad
+      }
+      return { angle: g.angle, stops } // linear stays shape-compatible with the pre-radial output
+    })
+  }
+
+  if (s.borderRadius && (s.borderRadius.tl || s.borderRadius.tr || s.borderRadius.br || s.borderRadius.bl)) {
+    out.borderRadius = radiusObj(s.borderRadius)
+  }
+  if (s.border) {
+    const b: Record<string, unknown> = {}
+    for (const side of ["top", "right", "bottom", "left"] as const) {
+      const sd = s.border[side]
+      if (sd && sd.width > 0) b[side] = { width: sd.width, color: rgbaToHex(sd.color) }
+    }
+    if (Object.keys(b).length > 0) out.border = b
+  }
+
+  return Object.keys(out).length > 0 ? out : undefined
+}

package/src/types.ts

@@ -0,0 +1,299 @@
+// Shared, platform-agnostic types for the renderer.
+
+/** An axis-aligned rectangle in CSS pixels. */
+export interface Rect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/**
+ * A color packed as 0xRRGGBBAA (the same layout creator-ui hands back to the uint color handlers,
+ * and the same RGBA packing the desktop tgfx renderer uses). `null`/absent = no color.
+ */
+export type RGBA = number
+
+export interface BorderSide {
+  width: number
+  color: RGBA
+}
+
+export interface BorderRadius {
+  tl: number
+  tr: number
+  br: number
+  bl: number
+}
+
+export interface GradientStop {
+  color: RGBA
+  /** 0..1 */
+  position: number
+}
+
+/** A linear gradient. `angle` is CSS degrees (0 = to top, 90 = to right, clockwise). */
+export interface LinearGradient {
+  type: "linear"
+  angle: number
+  stops: GradientStop[]
+}
+
+/** CSS `<extent-keyword>` for a radial gradient (default `farthest-corner`). */
+export type RadialExtent = "closest-side" | "closest-corner" | "farthest-side" | "farthest-corner"
+
+/**
+ * A radial gradient — the frequently-used subset creator-ui resolves into geometry: shape, size, and
+ * a keyword/percent center (`cx`/`cy` as a fraction of the box, 0..1). Size is either a CSS extent
+ * keyword or `"explicit"` — the latter carries `rx`/`ry` (CSS px, or a box-axis fraction when the
+ * matching unit is `"fraction"`, from a `%` radius).
+ */
+export interface RadialGradient {
+  type: "radial"
+  shape: "circle" | "ellipse"
+  extent: RadialExtent | "explicit"
+  cx: number
+  cy: number
+  rx?: number
+  ry?: number
+  rxUnit?: "px" | "fraction"
+  ryUnit?: "px" | "fraction"
+  stops: GradientStop[]
+}
+
+export type Gradient = LinearGradient | RadialGradient
+
+/**
+ * Paint-ready style for one node. Filled by the layout engine's per-prop style handlers, plus
+ * text-property inheritance resolved while building the render tree. Only paint-relevant props
+ * live here — layout props (flex, padding, width…) are consumed inside creator-ui.
+ */
+export interface ResolvedStyle {
+  backgroundColor?: RGBA
+  opacity?: number
+  /** A screen: black over its content and children, 0..1 (a transition's pose). */
+  dim?: number
+
+  border?: Partial<Record<"top" | "right" | "bottom" | "left", BorderSide>>
+  borderRadius?: BorderRadius
+  overflow?: "visible" | "hidden"
+
+  /** `"none"` removes the node (and its subtree) from the render tree; anything else shows it. */
+  display?: string
+
+  // text (resolved with inheritance)
+  color?: RGBA
+  fontSize?: number
+  fontFamily?: string
+  fontWeight?: number
+  fontStyle?: "normal" | "italic"
+  /** Always set by the record: the core resolves `normal` (fontSize × 1.2) and every explicit form. */
+  lineHeight: number
+  letterSpacing?: number
+  textAlign?: "start" | "center" | "end"
+  textDecoration?: "underline" | "line-through" | "none"
+  /** Cap the text at N lines (0 / undefined = unbounded). NOT inherited, unlike the props above —
+   *  it belongs to the text node that carries it (registry `nodes: ["text"]`). */
+  lineClamp?: number
+  /** How a clamped line ends. Only meaningful together with `lineClamp`; default "ellipsis". */
+  textOverflow?: "ellipsis" | "clip"
+
+  // image
+  objectFit?: "cover" | "contain" | "fill"
+  tintColor?: RGBA
+
+  // input / textarea
+  placeholder?: string
+  placeholderColor?: RGBA
+  inputType?: string
+
+  // background image (string url) painted behind content
+  backgroundImage?: string
+  backgroundSize?: "cover" | "contain" | "tile"
+
+  // background gradient layer stack (parsed from the CSS string the wasm forwards). `[0]` is the
+  // topmost layer — CSS paints the first-listed background-image layer on top. Usually one entry.
+  backgroundGradients?: Gradient[]
+
+  /** Scroll axis for a scrollable node ("x" = horizontal, "y" = vertical, the default). */
+  scrollAxis?: "x" | "y"
+
+  // widget: a full-screen backdrop behind the widget that intercepts taps (onOverlayTap)
+  overlayColor?: RGBA
+
+  /** 2D affine transform [a,b,c,d,e,f] (creator-ui parses the `transform` string → matrix). Applied
+   *  about the node's centre (CSS default), to the node + its subtree. Undefined = identity. */
+  transform?: [number, number, number, number, number, number]
+  /** Pivot of `transform`, per axis a % of the box (`percent`) or px (creator-ui parses the
+   *  `transformOrigin` string and dispatches it typed on its origin channel). Undefined = the centre. */
+  transformOrigin?: { x: number, y: number, xPercent: boolean, yPercent: boolean }
+}
+
+export type NodeType =
+  | "screen"
+  | "box"
+  | "row"
+  | "column"
+  | "text"
+  | "image"
+  | "button"
+  | string
+
+/**
+ * The authoring-layer (worker) node the renderer consumes — the other end of the `_creatorUI`
+ * contract. The renderer never mutates it for layout (it mirrors it into a `SceneNode`); it only reads
+ * these fields and, once, writes back `_id`. The single-letter listener arrays and `_`-prefixed fields
+ * are the stable wire names the worker emits (chisel's method-DCE keeps `_*` members) — documented once
+ * here so Renderer / Screen / SceneNode / TouchSystem don't each re-discover them. The index signature
+ * keeps forward-compatibility with fields not yet enumerated.
+ */
+export interface WorkerNode {
+  type: string
+  /** The creator-ui (Yoga) node id — assigned by the renderer at mount, 0 once released. */
+  _id: number
+  /** The raw authoring style object (primitives + `$`-class state blocks like `$pressed`). */
+  _style?: Record<string, any>
+  /** Active user style classes (names without the leading `$`), set via `setClass`. Kept on the
+   *  node so a re-mounted node (screens re-assign `_id` on every open) comes back with them active. */
+  _classes?: Set<string>
+  children?: (WorkerNode | null | undefined)[]
+  /** Author-given semantic name (LeCodes `name`). */
+  name?: string
+
+  // ----- content (read the `_`-backing first; the public getter is DCE'd outside the bundle) -----
+  text?: string
+  _text?: string
+  src?: unknown
+  _src?: unknown
+  /** Image source crop (atlas frame), texture px, stashed before mount. */
+  _sourceRect?: [number, number, number, number]
+  /** Current input/textarea value (the worker's `input.value`). */
+  value?: unknown
+  /** Input/textarea value as last set by code, stashed before mount (pre-filled form). */
+  _value?: string
+
+  // ----- flags -----
+  scrollable?: boolean
+  /** vlist: an inverted (chat) list — starts scrolled to the end; appends stick to the bottom. */
+  _inverted?: boolean
+
+  // ----- vlist windowing (the renderer drives `_syncWindow`; the worker re-renders items) -----
+  _keys?: string[]
+  _estimates?: number[]
+  _syncWindow?: (removed: string[], keys: string[]) => void
+  _endThreshold?: number
+  _startThreshold?: number
+
+  // ----- interaction (node-level dispatch, like the Android views) -----
+  _emitClick?: (fingerId: number, x: number, y: number) => any
+  _emitTouchStart?: (fingerId: number, x: number, y: number) => any
+  touchStartListeners?: any[]
+
+  // ----- listeners (worker wire names) -----
+  ol?: (() => void)[] // onOpen (screen)
+  cl?: ((...args: any[]) => void)[] // onClose (screen) OR onChange (input) — overloaded by type
+  ll?: ((layout: { left: number; top: number; width: number; height: number }) => void)[] // onLayout
+  fl?: (() => void)[] // onFocus (input)
+  bl?: (() => void)[] // onBlur (input)
+  sl?: ((offset: number) => void)[] // onScroll
+  osl?: ((over: number) => void)[] // onOverscroll
+  srl?: (() => void)[] // onScrollRelease
+  otl?: (() => void)[] // onOverlayTap (widget)
+  erl?: (() => void)[] // onEndReached (vlist)
+  strl?: (() => void)[] // onStartReached (vlist)
+
+  /** Escape hatch for worker fields not yet enumerated here. */
+  [key: string]: any
+}
+
+/** Decoded image info, produced by the host. */
+export interface ImageInfo {
+  src: string
+  naturalWidth: number
+  naturalHeight: number
+  /** Opaque backend handle (e.g. an HTMLImageElement / ImageBitmap) for the canvas painter. */
+  handle?: unknown
+  /** A vector source (SVG) the host can re-rasterize: the painter asks for the handle at the DEVICE
+   *  size it is about to draw (w × h px), so an icon is never a stretched bitmap. Absent when the
+   *  backend already draws the source at the destination scale (a browser's SVG `<img>`). */
+  rasterize?(w: number, h: number): unknown
+}
+
+/**
+ * The render tree: the resolved, absolute-positioned snapshot of one screen. It is BOTH the
+ * semantic description (serialized to JSON for AI feedback / tests) AND the paint source
+ * (walked by paintTree into a Painter). Fully resolved — no inheritance or wrapping left to do.
+ */
+export interface RenderNode {
+  /** The creator-ui (Yoga) node id. */
+  id: number
+  type: NodeType
+  /** Author-given semantic name (LeCodes `name`): a stable selector for tests + AI review feedback. */
+  name?: string
+  /** Absolute rectangle, in CSS pixels. */
+  rect: Rect
+  style: ResolvedStyle
+
+  text?: string
+  /** Text after wrapping to the node's content width (its width minus padding). */
+  lines?: string[]
+
+  /** Resolved padding `[left, top, right, bottom]` (px), present on text/input nodes that have it.
+   *  The rect is the border box; self-rendered content (text / input value) is inset by this. */
+  padding?: [number, number, number, number]
+
+  /** Current text of an input/textarea node ("" when empty → the placeholder is shown). */
+  value?: string
+
+  image?: ImageInfo
+  /** Per-node source crop (atlas/spritesheet), in texture px — overrides object-fit. */
+  sourceRect?: [number, number, number, number]
+
+  state?: { pressed?: boolean; focused?: boolean; classes?: string[] }
+
+  /** Set when the node clips its children (scrollable, or overflow:hidden). */
+  clip?: boolean
+  /** Present for scrollable nodes: scroll axis + current offset + total content size along it. */
+  scroll?: { offset: number; content: number; axis: "x" | "y" }
+
+  children: RenderNode[]
+}
+
+/**
+ * One compositing layer: the main screen, the screen that LEFT and is still shown (the runtime
+ * moves both through their own transform / opacity / dim until it drops it), or a widget overlay.
+ * A widget with `overlayColor` carries a full-screen `backdrop` painted behind it (and which
+ * intercepts taps → onOverlayTap).
+ */
+export interface Layer {
+  tree: RenderNode
+  /** True for the screen that left: painted, never the target of input or of a semantic read. */
+  leaving?: boolean
+  /** True for a widget overlay (composited above the main screen). */
+  widget?: boolean
+  backdrop?: { color: RGBA; jsNode: WorkerNode }
+}
+
+/**
+ * @deprecated A uniform transform that used to scale the whole UI into the band above the keyboard.
+ * The UI is now re-laid-out into the reduced height instead, so this is no longer produced.
+ */
+export interface UITransform {
+  scale: number
+  tx: number
+  ty: number
+}
+
+/**
+ * Simulated on-screen keyboard state. The keyboard *visual* is the host's (DOM on web); Core owns
+ * this state. When an input is focused the UI is RE-LAID-OUT into the area above `rect` (like
+ * iOS/Android), not scaled. Emitted to the host via `onKeyboardChange`.
+ */
+export interface KeyboardState {
+  /** The bottom band the keyboard occupies (host draws its keyboard here); the UI lays out above it. */
+  rect: Rect
+  /** @deprecated No longer set — the UI is re-laid-out above the keyboard, not scaled. */
+  transform?: UITransform
+  /** The focused input: its absolute rect, current value, and type (for the host's capture field). */
+  input: { nodeId: number; rect: Rect; value: string; type: string }
+}

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />