lecodes-sdk 0.19.0

package/src/ui/NativeView.ts

@@ -0,0 +1,142 @@
+// A host-registered platform view (map, QR scanner, camera preview, …) — the plugin surface of
+// the Presentable model (docs/navigation-presentable-plan.md). The host registers a *capability*
+// (`engine.registerView("map") { params, channel -> MapView(...) }`); when and with what to show
+// it is app code. Dual-natured like every Presentable: a fullscreen destination
+// (`Router.push(map)` / `map.open()`) AND an embeddable layout node (wire type `"native"` — place
+// it among a screen's children, sized by its styles). One instance lives in one place at a time;
+// pushing a mounted instance fullscreen is promotion (the native view reparents, state intact).
+//
+// Plugins ship a typed TS wrapper over the raw `call`/`on` channel — see QRScanner for the
+// wrapper convention.
+
+import { _channelCall, _channelEmit, _channelOff, _channelOn, type ChannelListeners } from "../runtime/channel"
+import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
+import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode"
+
+export type UINativeViewStyle = ElementStyle & DrawableStyle
+
+/** An instance of a host-registered platform view (map, QR scanner, camera preview, …) —
+ *  embeddable among a screen's children AND fullscreen-presentable (`open()`); one instance lives
+ *  in one place at a time. Talk to it via the `call`/`on` channel. */
+export interface NativeView extends UIElementBase<UINativeViewStyle, DrawableStyle & BaseStyle> {
+  readonly type: "native",
+  /** The registered view kind this instance resolves to (the `registerView` name). */
+  readonly viewName: string,
+  /** Creation params, passed to the host factory (JSON-serializable). */
+  readonly params: any,
+
+  /** Show fullscreen as the current destination (see Presentable). */
+  open(options?: PresentOptions): void,
+  /** Dismiss if this is the visible destination. */
+  close(): void,
+
+  /** Became the visible destination. */
+  onOpen(callback: () => void): this
+  /** Stopped being the visible destination. */
+  onClose(callback: () => void): this
+  /** Hardware/system back while current. */
+  onBackPressed(callback: () => void): this
+
+  /** Invoke a method on the native view (`map.call("setCenter", [lng, lat])`). Args and the
+   *  result are JSON-serialized. Rejects if the host has no such view/method. */
+  call(method: string, ...args: any[]): Promise<any>
+  /** Subscribe to an event the native view emits (`map.on("markerTap", cb)`). */
+  on(event: string, callback: (data?: any) => void): this
+  off(event: string, callback: (data?: any) => void): this
+}
+
+let nextViewId = 1
+
+/** @internal Base for typed plugin wrappers (QRScanner, CameraView — src/plugins/): subclass it,
+ *  pin the viewName/params, and layer typed methods over the raw `call`/`on` channel. Not a
+ *  public global — apps use the `NativeView(name)` factory below. */
+export class NativeViewElement extends Element<"native"> implements Presentable {
+  readonly viewName: string
+  readonly params: any
+  /** @internal stable per-instance handle for the viewCall channel + promotion identity. */
+  readonly _viewId: number
+  /** @internal event listeners by event name — the host invokes these (vlist pcl/psl convention)
+   *  or calls _emitViewEvent. */
+  readonly nvl: ChannelListeners = {}
+  readonly ol: (() => void)[] = []
+  readonly cl: (() => void)[] = []
+  _backButtonCallback?: () => void
+  private _vd?: object
+
+  constructor(viewName: string, params: any) {
+    super("native", {})
+    this.viewName = viewName
+    this.params = params
+    this._viewId = nextViewId++
+  }
+
+  /** @internal stable wire descriptor; hosts hand it back via router onChange (`_p` = this). */
+  _viewDesc(): object {
+    return this._vd ??= { type: "native", viewName: this.viewName, params: this.params, viewId: this._viewId, _p: this }
+  }
+
+  open(options?: PresentOptions): void {
+    if (!_navSupported()) {
+      throw new Error(`NativeView("${this.viewName}") is not supported on this host (requires _creatorUI.openView)`)
+    }
+    _bumpNavEpoch()
+    _creatorUI.openView!(this._viewDesc(), options?.transition ?? "none")
+    _setCurrent(this)
+  }
+  close(): void {
+    _bumpNavEpoch()
+    if (_navSupported()) _creatorUI.closeView!()
+    if (Presentable.current === this) _setCurrent(null)
+  }
+
+  onOpen(callback: () => void): this {
+    this.ol.push(callback)
+    return this
+  }
+  onClose(callback: () => void): this {
+    this.cl.push(callback)
+    return this
+  }
+  onBackPressed(callback: () => void): this {
+    this._backButtonCallback = callback
+    return this
+  }
+
+  call(method: string, ...args: any[]): Promise<any> {
+    return _channelCall(
+      typeof _creatorUI !== "undefined" ? _creatorUI : undefined, "viewCall",
+      `NativeView("${this.viewName}") is not supported on this host (requires _creatorUI.viewCall)`,
+      this._viewId, method, args)
+  }
+
+  on(event: string, callback: (data?: any) => void): this {
+    _channelOn(this.nvl, event, callback)
+    return this
+  }
+  off(event: string, callback: (data?: any) => void): this {
+    _channelOff(this.nvl, event, callback)
+    return this
+  }
+  /** @internal host entry: deliver a native event (payload as a JSON string, or omitted). */
+  _emitViewEvent(event: string, dataJson?: string): void {
+    _channelEmit(this.nvl, event, dataJson)
+  }
+}
+
+/**
+ * Create an instance of a host-registered platform view. `NativeView.isSupported(name)` reports
+ * whether this host registered a factory for it. Style via the chained `.style()`.
+ */
+// PURE IIFE (not a plain function + expando assignment) so an app that never uses NativeView
+// tree-shakes it away — top-level property assignments read as side effects to the bundler.
+export const NativeView: {
+  (name: string, params?: object): NativeView
+  /** Whether this host registered a `registerView` factory under `name`. */
+  isSupported(name: string): boolean
+} = /*#__PURE__*/ (() => {
+  const factory = (name: string, params: object = {}): NativeView =>
+    new NativeViewElement(name, params) as unknown as NativeView
+  factory.isSupported = (name: string): boolean =>
+    typeof _creatorUI !== "undefined" && typeof _creatorUI.isViewSupported === "function" && _creatorUI.isViewSupported(name)
+  return factory
+})()

package/src/ui/UI.ts

@@ -0,0 +1,39 @@
+// Renderer-side contract + per-renderer status (DOM / canvas-ui / desktop) for every component
+// below is tracked in packages/canvas-ui/COMPONENTS.md.
+export { UIButton, type UIButtonStyle } from './UIButton'
+export { UIScreen, type UIScreenStyle } from './UIScreen'
+export { UISpacer, type UISpacerStyle } from './UISpacer'
+export { UIText, type UITextStyle } from './UIText'
+export { registerFont } from './fonts'
+export { UIImage, type UIImageStyle } from './UIImage'
+export { UIVideo, type UIVideoStyle } from './UIVideo'
+export { UIInput, UITextArea, type UIInputStyle } from './UIInput'
+
+export { UIWidget, type UIWidgetStyle } from './UIWidget'
+export { UIModal, type UIModalStyle } from './UIModal'
+export { UIBottomSheet, type UIBottomSheetStyle } from './UIBottomSheet'
+export { UIPopover, type UIPopoverStyle, type UIPopoverAnchor } from './UIPopover'
+
+export { UIRow, UIColumn, UIBox, type UIContainerStyle } from './UIContainer'
+export { UIScrollable, type UIScrollableStyle } from './UIScrollable'
+export { UIPager, type UIPagerStyle } from './UIPager'
+export { UITabs, type UITabDef, defineTabs, type TabDef, type TabsHandle } from './UITabs'
+
+export { UIVirtualizedList } from './UIVirtualizedList'
+
+export { Router } from './router'
+export { NativeView, type UINativeViewStyle } from './NativeView'
+// Presentable is both the interface and its runtime companion (Presentable.current).
+export { Presentable } from './presentable'
+export type { PresentOptions, Transition, TransitionName, TransitionSpec, TransitionTransform } from './presentable'
+
+// Internal: memoized map for reactive children — the chisel `reactiveUi` pass rewrites
+// `list.map(fn)` inside children bindings to `__uiMap(list, fn, slot)` calls.
+export { __uiMap } from './UINode'
+// Compiler fast paths (chisel `flatten_ui` raw lowering): dispatch-free construction for calls
+// whose arguments the compiler proved to be plain children. Never written by hand.
+export { __UIColumn, __UIRow, __UIBox } from './UIContainer'
+export { __UIButton } from './UIButton'
+export { __UIScreen } from './UIScreen'
+export { __UIScrollable } from './UIScrollable'
+export { __UIWidget } from './UIWidget'

package/src/ui/UIBottomSheet.ts

@@ -0,0 +1,139 @@
+import { ModalElement, type UIModalStyle } from "./UIModal"
+import type { UIWidget } from "./UIWidget"
+import { buildUI, type ChildrenFn, type UIChildArg, type UINodeChild } from "./UINode"
+
+export type UIBottomSheetStyle = UIModalStyle
+
+const SHEET_ANIM_MS = 250
+
+/**
+ * A bottom sheet: a `UIWidget` pinned to the bottom edge. By default it is **content-sized** —
+ * as tall as what's inside (capped at the screen), one position, drag down to dismiss (the
+ * action-sheet shape). Call `detents()` for the multi-position map-app model instead: snap
+ * positions the user drags between on native hosts. Ships as a widget node on the wire (no new
+ * node type — docs/bottom-sheet-plan.md): hosts without sheet support show a static bottom panel.
+ *
+ * With detents, content lays out at the HIGHEST detent's size; lower detents show the top
+ * slice. The scrim, `onOpen`/`onClose`, back-button and scrim-tap dismissal all come from the
+ * modal machinery.
+ *
+ * ```ts
+ * const actions = UIBottomSheet({ bgColor: "#1c1c1e", borderRadius: 16 }, [rows])   // content-sized
+ *
+ * const mapSheet = UIBottomSheet({ bgColor: "#1c1c1e", borderRadius: 16 }, [results])
+ *   .detents([0.3, 0.6, 1])
+ *   .onDetentChange(i => map.setPadding(...))
+ * ```
+ */
+export interface UIBottomSheet extends UIWidget {
+  /** Snap positions as fractions of screen height, ascending. Also sizes the sheet: its box is
+   *  the last (highest) detent; set this before `show()`. Without a `detents()` call the sheet
+   *  is CONTENT-SIZED instead — one position, as tall as its children (up to the screen). */
+  detents(list: number[]): this,
+  /** Snap to a detent (animated). Clamped to the detents range; fires `onDetentChange`. */
+  setDetent(index: number): void,
+  /** Current detent index. */
+  readonly detent: number,
+  /** Fires on every settle: a finger snap on native hosts, or a `setDetent()` call. */
+  onDetentChange(callback: (index: number) => void): this,
+
+  /** Mount and slide in to the current detent. No-op while already open. */
+  show(): void,
+  /** Slide out, fade the scrim, then unmount. No-op while closed. */
+  hide(): void,
+  /** True from `show()` until `hide()` starts. */
+  readonly isOpen: boolean,
+
+  /** Called when `show()` mounts the sheet. */
+  onOpen(callback: () => void): this,
+  /** Called when the sheet starts closing — scrim tap, back button, drag-dismiss, or `hide()`. */
+  onClose(callback: () => void): this,
+  /** `dismissible(false)`: scrim taps, the back button and dragging below the lowest detent no
+   *  longer close the sheet (a drag collapses to the lowest detent instead). Default `true`. */
+  dismissible(enabled: boolean): this,
+}
+
+export class BottomSheetElement extends ModalElement {
+  _detents: number[] = [1]
+  _detent = 0
+  /** Host-facing (the `sl`/`otl` contract): hosts read `dtl` at mount and call it with the
+   *  settled detent index for GESTURE settles only — programmatic `setDetent` fires JS-side.
+   *  `-1` = dragged below the lowest detent while dismissible. */
+  readonly dtl: any[] = []
+  readonly _detentListeners: ((index: number) => void)[] = []
+
+  constructor(style: UIBottomSheetStyle, children: UINodeChild[] | ChildrenFn) {
+    // No default height: an absolute node with only bottom set is CONTENT-sized by yoga. A
+    // single detent makes the geometry height-independent on every host (shown = offset 0,
+    // hidden = own height), so content mode needs no host support beyond the detents path.
+    super({ left: 0, right: 0, bottom: 0, maxHeight: "100%", sheetDetents: "1", ...style } as UIModalStyle, children)
+    // The inherited show/hide pose animates ONLY the scrim: sheet geometry rides the
+    // sheetDetent style key, never the pose system.
+    this._transition = { duration: SHEET_ANIM_MS }
+    this.dtl.push((index: number) => {
+      if (index < 0) { this.hide(); return }
+      this._detent = index
+      for (const callback of this._detentListeners) callback(index)
+    })
+  }
+
+  detents(list: number[]): this {
+    const sorted = [...list].filter(d => d > 0).sort((a, b) => a - b)
+    if (sorted.length === 0) return this
+    this._detents = sorted
+    if (this._detent >= sorted.length) this._detent = sorted.length - 1
+    this.style({
+      height: `${sorted[sorted.length - 1] * 100}%`,
+      sheetDetents: sorted.join(","),
+    } as UIBottomSheetStyle)
+    return this
+  }
+
+  get detent(): number {
+    return this._detent
+  }
+
+  setDetent(index: number): void {
+    const clamped = Math.max(0, Math.min(Math.floor(index), this._detents.length - 1))
+    this._detent = clamped
+    if (!this._open) return                     // applied by the next show()
+    this.style({ sheetDetent: clamped } as UIBottomSheetStyle)
+    for (const callback of this._detentListeners) callback(clamped)
+  }
+
+  onDetentChange(callback: (index: number) => void): this {
+    this._detentListeners.push(callback)
+    return this
+  }
+
+  show(): void {
+    if (this._open) return
+    // Before the mount, so the built node carries the target and hosts play the entrance to it.
+    this.style({ sheetDetent: this._detent } as UIBottomSheetStyle)
+    super.show()
+  }
+
+  hide(): void {
+    if (!this._open) return
+    this.style({ sheetDetent: -1 } as UIBottomSheetStyle)   // hosts slide out; unmount follows
+    super.hide()
+  }
+
+  dismissible(enabled: boolean): this {
+    super.dismissible(enabled)
+    this.style({ sheetDismissible: enabled ? 1 : 0 } as UIBottomSheetStyle)
+    return this
+  }
+}
+
+const makeBottomSheet = (style: any, children: any) => new BottomSheetElement(style, children)
+
+/** Create a bottom sheet (see {@link UIBottomSheet}) — content-sized by default; call
+ *  `.detents([...])` for snap positions. Same argument forms as `UIColumn`. */
+export function UIBottomSheet(...children: UIChildArg[]): UIBottomSheet;
+export function UIBottomSheet(children: UINodeChild[] | ChildrenFn): UIBottomSheet;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIBottomSheet(style: UIBottomSheetStyle, children?: UINodeChild[] | ChildrenFn): UIBottomSheet;
+export function UIBottomSheet(...args: any[]): UIBottomSheet {
+  return buildUI(args, null, makeBottomSheet)
+}

package/src/ui/UIButton.ts

@@ -0,0 +1,101 @@
+import { ClickEvent, TouchStartEvent, LongPressEvent } from "../runtime/touch"
+import type { ClickEvent as ClickEventType, TouchStartEvent as TouchStartEventType, LongPressEvent as LongPressEventType } from "../runtime/touch"
+import { type ElementStyle, type ContainerStyle, ContainerElement, buildUI, type DrawableStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type BaseStyle, type Color } from "./UINode"
+
+export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & { rippleColor?: Color | "default" }
+
+/** A tappable container — row + centered children by default. Press feedback via the `onPressed`
+ *  style block, the `$pressed` class, or `rippleColor`. */
+export interface UIButton extends UIContainerBase<UIButtonStyle & { onPressed?: UIButtonStyle & { duration?: number } }, DrawableStyle & BaseStyle> {
+  readonly type: "button",
+
+  /** Fired on a completed tap/click. */
+  onClick(callback: (ev: ClickEventType<UIButton>) => void): this,
+  /** Fired when a touch begins; `ev.track(...)` takes over the rest of the gesture (dragging). */
+  onTouchStart(callback: (ev: TouchStartEventType<UIButton>) => void): this,
+  /** Fired when a finger is held on the button past the long-press threshold. The event can
+   *  `ev.track(...)` the rest of the gesture (like `onTouchStart`), so a hold can flow straight into
+   *  dragging the element. A handled long-press suppresses the click that would follow the release. */
+  onLongPress(callback: (ev: LongPressEventType<UIButton>) => void): this,
+  /** Is a finger currently down on the button? */
+  isPressed(): boolean,
+}
+
+
+class ButtonElement extends ContainerElement<"button"> {
+
+  readonly clickListeners: any[] = []
+  readonly touchStartListeners: any[] = []
+  readonly longPressListeners: any[] = []
+
+  onClick (callback: any): this {
+    this.clickListeners.push(callback)
+    return this
+  }
+  _emitClick(pointerId: number, clientX: number, clientY: number) {
+    const touchEvent = new ClickEvent(clientX, clientY, pointerId)
+    touchEvent.target = this
+    for (let callback of this.clickListeners) {
+      callback(touchEvent)
+    }
+    return null
+  }
+
+  onTouchStart (callback: any): this {
+    this.touchStartListeners.push(callback)
+    return this
+  }
+  _emitTouchStart(pointerId: number, clientX: number, clientY: number): any {
+    const touchEvent = new TouchStartEvent(clientX, clientY, pointerId)
+    touchEvent.target = this
+    for (let callback of this.touchStartListeners) {
+      callback(touchEvent)
+      if ((touchEvent as any)._trackHandler) {
+        return (touchEvent as any)._trackHandler
+      }
+    }
+    return null
+  }
+
+  onLongPress (callback: any): this {
+    this.longPressListeners.push(callback)
+    return this
+  }
+  // Fired by the host when the finger is held past the long-press threshold. Returns null when
+  // nothing is listening — the host then lets the trailing click through as usual. Otherwise it
+  // returns an object whose presence tells the host to swallow that click, carrying the optional
+  // drag handler a listener registered via `ev.track(...)` for the host to drive the gesture.
+  _emitLongPress(pointerId: number, clientX: number, clientY: number): any {
+    if (this.longPressListeners.length === 0) return null
+    const longPressEvent = new LongPressEvent(clientX, clientY, pointerId)
+    longPressEvent.target = this
+    for (let callback of this.longPressListeners) {
+      callback(longPressEvent)
+    }
+    return { track: (longPressEvent as any)._trackHandler ?? null }
+  }
+
+  isPressed(): boolean {
+    if (!this._id) return false
+    return _creatorUI.isButtonPressed(this._id)
+  }
+}
+
+// Buttons are row + centered by default: the icon+label button is the norm, and yoga's column
+// default was a recurring authoring/codegen trap.
+const BUTTON_DEFAULTS = { flexDirection: "row", justifyContent: "center", alignItems: "center" } as const
+
+const makeButton = (style: any, children: any) => new ButtonElement("button", style, children)
+
+/** @internal Compiler fast path (chisel `flatten_ui` raw lowering) — see UIContainer. */
+export const __UIButton = (children: UINodeChild[] | ChildrenFn): UIButton => makeButton({ ...BUTTON_DEFAULTS }, children)
+
+/** Create a button (row + centered by default — the icon+label shape). Same argument forms as
+ *  `UIColumn`; attach behavior with `.onClick(...)`. */
+export function UIButton(...children: UIChildArg[]): UIButton;
+export function UIButton(children: UINodeChild[] | ChildrenFn): UIButton;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIButton(style: UIButtonStyle, children?: UINodeChild[] | ChildrenFn): UIButton;
+export function UIButton(...args: any[]): UIButton {
+  return buildUI(args, BUTTON_DEFAULTS, makeButton)
+}

package/src/ui/UIContainer.ts

@@ -0,0 +1,60 @@
+import { ContainerElement, buildUI, type ChildrenFn, type ContainerStyle, type DrawableStyle, type ElementStyle, type UIChildArg, type UIContainerBase, type UINodeChild } from "./UINode"
+
+export type UIContainerStyle = ElementStyle & DrawableStyle & ContainerStyle
+
+/** A vertical flex container — children stack top to bottom. */
+export interface UIColumn extends UIContainerBase<UIContainerStyle> {
+  readonly type: "column",
+}
+const makeColumn = (style: any, children: any) => new ContainerElement("column", style, children)
+
+/** @internal Compiler fast path (chisel `flatten_ui` raw lowering): construction with a proven
+ *  plain-children array — or a reactive ChildrenFn (the Element constructor branches on
+ *  `typeof === "function"` either way) — skipping the buildUI argument dispatch entirely. */
+export const __UIColumn = (children: UINodeChild[] | ChildrenFn): UIColumn => makeColumn({}, children)
+export const __UIRow = (children: UINodeChild[] | ChildrenFn): UIRow => makeRow({ flexDirection: "row" }, children)
+export const __UIBox = (children: UINodeChild[] | ChildrenFn): UIBox => makeBox({ ...BOX_DEFAULTS }, children)
+
+/** Create a vertical flex container. Children are variadic — arrays flatten one level, falsy
+ *  entries are skipped; a lone function makes the children reactive. */
+export function UIColumn(...children: UIChildArg[]): UIColumn
+export function UIColumn(children: UINodeChild[] | ChildrenFn): UIColumn
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIColumn(style: UIContainerStyle, children?: UINodeChild[] | ChildrenFn): UIColumn
+export function UIColumn(...args: any[]): UIColumn {
+  return buildUI(args, null, makeColumn)
+}
+
+/** A horizontal flex container — children flow left to right. */
+export interface UIRow extends UIContainerBase<UIContainerStyle> {
+  readonly type: "row",
+}
+const ROW_DEFAULTS = { flexDirection: "row" } as const
+const makeRow = (style: any, children: any) => new ContainerElement("row", style, children)
+
+/** Create a horizontal flex container (same argument forms as `UIColumn`). */
+export function UIRow(...children: UIChildArg[]): UIRow
+export function UIRow(children: UINodeChild[] | ChildrenFn): UIRow
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIRow(style: UIContainerStyle, children?: UINodeChild[] | ChildrenFn): UIRow
+export function UIRow(...args: any[]): UIRow {
+  return buildUI(args, ROW_DEFAULTS, makeRow)
+}
+
+/** A centering container — `justifyContent`/`alignItems` default to center. */
+export interface UIBox extends UIContainerBase<UIContainerStyle> {
+  readonly type: "box",
+}
+const BOX_DEFAULTS = { justifyContent: "center", alignItems: "center" } as const
+
+const makeBox = (style: any, children: any) => new ContainerElement("box", style, children)
+
+/** Create a centering container — children are centered on both axes by default (icon badges,
+ *  avatars, empty states). Same argument forms as `UIColumn`. */
+export function UIBox(...children: UIChildArg[]): UIBox
+export function UIBox(children: UINodeChild[] | ChildrenFn): UIBox
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIBox(style: UIContainerStyle, children?: UINodeChild[] | ChildrenFn): UIBox
+export function UIBox(...args: any[]): UIBox {
+  return buildUI(args, BOX_DEFAULTS, makeBox)
+}

package/src/ui/UIImage.ts

@@ -0,0 +1,83 @@
+import type { FetchResponse } from "../runtime/fetch"
+import type { SvgSourceValue as SvgSource } from "../runtime/misc"
+import type { File } from "../runtime/fetch"
+import { Canvas, isCanvas } from "../canvas/Canvas"
+import { Element, type Color, type ElementStyle, type UIElementBase } from "./UINode"
+
+export type UIImageStyle = ElementStyle & { borderRadius?: number, objectFit?: "cover" | "contain" | "fill", tintColor?: Color }
+
+/** A baked Canvas surface as an image source. The UI backend resolves it to a UI texture — see
+ *  docs/canvas-contract.md ("Pending"). */
+export type CanvasImageSource = { canvasSurface: number }
+
+/** Accepted image sources. A Canvas is baked to a surface marker on assign. */
+export type ImageSource = string | FetchResponse | File | SvgSource | Canvas
+
+const toSrc = (src: ImageSource): string | FetchResponse | File | SvgSource | CanvasImageSource =>
+  // _bakeSurfaceForUI (not _bakeSurface) also flags the canvas UI-bound, so canvas.update() later
+  // refreshes this image node in place — that's what makes an animated UIImage(canvas) update.
+  isCanvas(src) ? { canvasSurface: src._bakeSurfaceForUI() } : src
+
+/** The stored/resolved image source (a Canvas is resolved to a surface marker). */
+export type ResolvedImageSource = string | FetchResponse | File | SvgSource | CanvasImageSource
+
+/** An image element. Sources: URL / `asset(...)`, fetch response / File, an SVG source
+ *  (`assetIcon`), or a live Canvas (`canvas.update()` refreshes the node in place). */
+export interface UIImage extends UIElementBase<UIImageStyle> {
+  readonly type: "image",
+  /** The image source — writable to swap the picture in place. */
+  get src(): ResolvedImageSource
+  set src(value: ImageSource)
+
+  /** Render only a sub-rectangle of the source texture (texture pixels) — the atlas/spritesheet
+   *  primitive: crop once, then swap the rect per frame for sprite animation. The rect's w/h
+   *  become the node's intrinsic size and override `objectFit` — the cropped frame fills the box. */
+  setSourceRect(x: number, y: number, w: number, h: number): this
+}
+
+class ImageElement extends Element<"image"> {
+  private _src: ResolvedImageSource
+  // Current source sub-rect; undefined until the first setSourceRect. Kept on the node (not
+  // just sent as a command) so a crop set while detached (_id == 0) is reapplied at mount —
+  // the viewer reads it when it creates the element.
+  private _sourceRect?: [number, number, number, number]
+  constructor(style: any, src: ImageSource) {
+    super("image", style)
+    this._src = toSrc(src)
+  }
+
+  get src(): ResolvedImageSource {
+    return this._src
+  }
+  set src(value: ImageSource) {
+    this._src = toSrc(value)
+    if (this._id !== 0) {
+      _creatorUI.updateNode(this._id, "src", this._src)
+    }
+  }
+
+  setSourceRect(x: number, y: number, w: number, h: number): this {
+    // Stash on the node so a crop set before mount is reapplied when the element is created.
+    this._sourceRect = [x, y, w, h]
+    // Live mutation: fast channel (not _style → no PX_VALUE density scaling: these are texture
+    // pixels, a different coordinate space). On a detached node there is nothing to mutate yet —
+    // the stash above carries it to mount. The viewer decides relayout vs draw-only by comparing
+    // w/h against the rect it has stashed on the element.
+    if (this._id !== 0) {
+      _creatorUI.setSourceRect(this._id, x, y, w, h)
+    }
+    return this
+  }
+}
+
+/** Create an image element from a source (see {@link ImageSource}). */
+export function UIImage(src: ImageSource): UIImage
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIImage(style: UIImageStyle, src: ImageSource): UIImage
+export function UIImage(...args: [ImageSource] | [UIImageStyle, ImageSource]): UIImage {
+  if (args.length === 1) {
+    return new ImageElement({}, args[0])
+  } else {
+    return new ImageElement(args[0], args[1])
+  }
+}