lecodes-sdk 1.2.0 → 2.0.0

package/src/ui/NativeView.ts

@@ -10,8 +10,10 @@
 // wrapper convention.
 
 import { _channelCall, _channelEmit, _channelOff, _channelOn, type ChannelListeners } from "../runtime/channel"
-import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
+import { _bumpNavEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "./presentable"
+import { _transitionId, TRANSITION_NONE } from "./transitions"
 import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode"
+import { TREE_DEST_NATIVE, registerDest, registerNativeView, tree, unregisterNativeView } from "./tree"
 
 export type UINativeViewStyle = ElementStyle & DrawableStyle
 
@@ -28,25 +30,30 @@ export interface NativeView extends UIElementBase<UINativeViewStyle, DrawableSty
   /** Show fullscreen as the current destination (see Presentable). */
   open(options?: PresentOptions): void,
   /** Dismiss if this is the visible destination. */
-  close(): void,
+  close(options?: DismissOptions): 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
+  onBack(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. */
+   *  result are plain data (and Uint8Array). 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
+  /** @internal The destination tuple (Presentable). */
+  _dest(): DestTuple
 }
 
 let nextViewId = 1
 
+const PRESENTED = 1
+const MOUNTED = 2
+
 /** @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. */
@@ -55,37 +62,41 @@ export class NativeViewElement extends Element<"native"> implements Presentable
   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. */
+  /** @internal event listeners by event name (host → view events come through the tree emitter). */
   readonly nvl: ChannelListeners = {}
   readonly ol: (() => void)[] = []
   readonly cl: (() => void)[] = []
-  _backButtonCallback?: () => void
-  private _vd?: object
+  private _backButtonCallback?: () => void
+  private readonly _paramsJson: string
+  /** @internal Where the host has a view of this instance: PRESENTED | MOUNTED. */
+  private _shown = 0
 
   constructor(viewName: string, params: any) {
     super("native", {})
     this.viewName = viewName
     this.params = params
     this._viewId = nextViewId++
+    this._paramsJson = JSON.stringify(params ?? {})
+    tree().setString(this._h.id, "viewName", viewName)
+    tree().setString(this._h.id, "viewParams", this._paramsJson)
+    tree().setInt(this._h.id, "viewId", this._viewId)
+    registerDest(TREE_DEST_NATIVE, this._viewId, this)
   }
 
-  /** @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 }
-  }
+  /** @internal */
+  _dest(): DestTuple { return [TREE_DEST_NATIVE, this._viewId, this.viewName, this._paramsJson] }
 
   open(options?: PresentOptions): void {
-    if (!_navSupported()) {
-      throw new Error(`NativeView("${this.viewName}") is not supported on this host (requires _creatorUI.openView)`)
+    if (!tree().isViewSupported(this.viewName)) {
+      throw new Error(`NativeView("${this.viewName}") is not supported on this host (no registered view)`)
     }
     _bumpNavEpoch()
-    _creatorUI.openView!(this._viewDesc(), options?.transition ?? "none")
+    tree().open(TREE_DEST_NATIVE, this._viewId, this.viewName, this._paramsJson, _transitionId(options?.transition, TRANSITION_NONE))
     _setCurrent(this)
   }
-  close(): void {
+  close(options?: DismissOptions): void {
     _bumpNavEpoch()
-    if (_navSupported()) _creatorUI.closeView!()
+    tree().close(TREE_DEST_NATIVE, this._viewId, _transitionId(options?.transition, TRANSITION_NONE))
     if (Presentable.current === this) _setCurrent(null)
   }
 
@@ -97,15 +108,47 @@ export class NativeViewElement extends Element<"native"> implements Presentable
     this.cl.push(callback)
     return this
   }
-  onBackPressed(callback: () => void): this {
+  onBack(callback: () => void): this {
     this._backButtonCallback = callback
     return this
   }
+  /** @internal */
+  // The host has a view that can send events while the instance is presented OR mounted among a
+  // screen's children: findable by viewId while it is either (owned handles) — a promoted view that
+  // closes is still the embedded one.
+  private _reach(where: number, on: boolean): void {
+    const was = this._shown
+    this._shown = on ? was | where : was & ~where
+    if (was === 0 && this._shown !== 0) registerNativeView(this._viewId, this)
+    else if (was !== 0 && this._shown === 0) unregisterNativeView(this._viewId)
+  }
+  /** @internal */
+  _emitOpen(): void { this._reach(PRESENTED, true); for (const cb of this.ol.slice()) cb() }
+  /** @internal */
+  _emitClose(): void { this._reach(PRESENTED, false); for (const cb of this.cl.slice()) cb() }
+  /** @internal */
+  _pinned(): void { this._reach(MOUNTED, true) }
+  /** @internal */
+  _unpinned(): void { this._reach(MOUNTED, false) }
+  /** @internal */
+  override _freed(): void {
+    this._reach(MOUNTED, false)
+    super._freed()
+  }
+  /** @internal */
+  _emitBack(): boolean {
+    if (!this._backButtonCallback) return false
+    this._backButtonCallback()
+    return true
+  }
+
+  call(method: string, ...args: any[]): Promise<any> { return this._channelSend(method, args) }
 
-  call(method: string, ...args: any[]): Promise<any> {
+  /** @internal One call over the channel (runtime/channel.ts). */
+  _channelSend(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)`,
+      typeof _creatorTree !== "undefined" ? _creatorTree : undefined, "viewCall",
+      `NativeView("${this.viewName}") is not supported on this host (requires _creatorTree.viewCall)`,
       this._viewId, method, args)
   }
 
@@ -117,9 +160,9 @@ export class NativeViewElement extends Element<"native"> implements Presentable
     _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)
+  /** @internal host entry: deliver a native event (its payload, or none). */
+  _emitViewEvent(event: string, data?: unknown): void {
+    _channelEmit(this.nvl, event, data)
   }
 }
 
@@ -133,10 +176,14 @@ export const NativeView: {
   (name: string, params?: object): NativeView
   /** Whether this host registered a `registerView` factory under `name`. */
   isSupported(name: string): boolean
+  /** The contract version of the host's view `name`: 0 when it has none, 1 for one written by hand. */
+  version(name: string): number
 } = /*#__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)
+    typeof _creatorTree !== "undefined" && _creatorTree.isViewSupported(name)
+  factory.version = (name: string): number =>
+    typeof _creatorTree !== "undefined" ? _creatorTree.viewVersion(name) : 0
   return factory
 })()

package/src/ui/UI.ts

@@ -1,5 +1,5 @@
-// Renderer-side contract + per-renderer status (DOM / canvas-ui / desktop) for every component
-// below is tracked in packages/canvas-ui/COMPONENTS.md.
+// The UI surface: every element the SDK exports. The host side of each is the runtime's tree
+// (docs/tree.md); the renderers implement HostUI over node ids.
 export { UIButton, type UIButtonStyle } from './UIButton'
 export { UIScreen, type UIScreenStyle } from './UIScreen'
 export { UISpacer, type UISpacerStyle } from './UISpacer'
@@ -25,7 +25,7 @@ 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'
+export type { DismissOptions, PresentOptions, Transition, TransitionName, TransitionPose, TransitionSpec } 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.

package/src/ui/UIBottomSheet.ts

@@ -1,6 +1,7 @@
 import { ModalElement, type UIModalStyle } from "./UIModal"
 import type { UIWidget } from "./UIWidget"
 import { buildUI, type ChildrenFn, type UIChildArg, type UINodeChild } from "./UINode"
+import { TREE_FLAG_DETENT } from "./tree"
 
 export type UIBottomSheetStyle = UIModalStyle
 
@@ -18,11 +19,11 @@ const SHEET_ANIM_MS = 250
  * modal machinery.
  *
  * ```ts
- * const actions = UIBottomSheet({ bgColor: "#1c1c1e", borderRadius: 16 }, [rows])   // content-sized
+ * const actions = UIBottomSheet(rows).style({ bgColor: "#1c1c1e", borderRadius: 16 })   // content-sized
  *
- * const mapSheet = UIBottomSheet({ bgColor: "#1c1c1e", borderRadius: 16 }, [results])
+ * const mapSheet = UIBottomSheet(results).style({ bgColor: "#1c1c1e", borderRadius: 16 })
  *   .detents([0.3, 0.6, 1])
- *   .onDetentChange(i => map.setPadding(...))
+ *   .onDetent(i => map.setPadding(...))
  * ```
  */
 export interface UIBottomSheet extends UIWidget {
@@ -30,12 +31,12 @@ export interface UIBottomSheet extends UIWidget {
    *  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`. */
+  /** Snap to a detent (animated). Clamped to the detents range; fires `onDetent`. */
   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,
+  onDetent(callback: (index: number) => void): this,
 
   /** Mount and slide in to the current detent. No-op while already open. */
   show(): void,
@@ -56,10 +57,6 @@ export interface UIBottomSheet extends UIWidget {
 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) {
@@ -70,11 +67,15 @@ export class BottomSheetElement extends ModalElement {
     // 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)
-    })
+    this._addFlags(TREE_FLAG_DETENT)
+  }
+
+  /** @internal The host's GESTURE settles only (programmatic `setDetent` fires JS-side); `-1` =
+   *  dragged below the lowest detent while dismissible. */
+  _emitDetent(index: number): void {
+    if (index < 0) { this.hide(); return }
+    this._detent = index
+    for (const callback of this._detentListeners) callback(index)
   }
 
   detents(list: number[]): this {
@@ -101,7 +102,7 @@ export class BottomSheetElement extends ModalElement {
     for (const callback of this._detentListeners) callback(clamped)
   }
 
-  onDetentChange(callback: (index: number) => void): this {
+  onDetent(callback: (index: number) => void): this {
     this._detentListeners.push(callback)
     return this
   }
@@ -132,8 +133,6 @@ const makeBottomSheet = (style: any, children: any) => new BottomSheetElement(st
  *  `.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

@@ -1,12 +1,13 @@
-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, type LayerEasing } from "./UINode"
+import { ClickEvent, TouchStartEvent, LongPressEvent, MouseEnterEvent } from "../runtime/touch"
+import type { ClickEvent as ClickEventType, TouchStartEvent as TouchStartEventType, LongPressEvent as LongPressEventType, MouseEnterEvent as MouseEnterEventType } 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"
+import { TREE_FLAG_CLICK, TREE_FLAG_HOVER, TREE_FLAG_INTERACTIVE, TREE_FLAG_LONG_PRESS, tree } from "./tree"
 
 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, delay?: number, easing?: LayerEasing } }, DrawableStyle & BaseStyle> {
+/** A tappable container — row + centered children by default. Press feedback via the `$pressed`
+ *  class block or `rippleColor`. */
+export interface UIButton extends UIContainerBase<UIButtonStyle, DrawableStyle & BaseStyle> {
   readonly type: "button",
 
   /** Fired on a completed tap/click. */
@@ -17,8 +18,14 @@ export interface UIButton extends UIContainerBase<UIButtonStyle & { onPressed?:
    *  `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,
+  /** Fired when a mouse cursor (no button) enters the button — desktop / web; touch never fires it.
+   *  There is no leave event: `ev.track({ onMove, onEnd, onCancel })` follows the hover to its
+   *  end. The visual state is the reserved `$hovered` class (cascades like `$pressed`). */
+  onMouseEnter(callback: (ev: MouseEnterEventType<UIButton>) => void): this,
   /** Is a finger currently down on the button? */
-  isPressed(): boolean,
+  readonly isPressed: boolean,
+  /** Is a mouse cursor currently over the button (the topmost interactive node under it)? */
+  readonly isHovered: boolean,
 }
 
 
@@ -27,11 +34,19 @@ class ButtonElement extends ContainerElement<"button"> {
   readonly clickListeners: any[] = []
   readonly touchStartListeners: any[] = []
   readonly longPressListeners: any[] = []
+  readonly mouseEnterListeners: any[] = []
+
+  constructor(type: "button", style: any, children: any) {
+    super(type, style, children)
+    this._addFlags(TREE_FLAG_INTERACTIVE)   // a button is a touch target from the start (press feedback)
+  }
 
   onClick (callback: any): this {
     this.clickListeners.push(callback)
+    this._addFlags(TREE_FLAG_CLICK)
     return this
   }
+  /** @internal */
   _emitClick(pointerId: number, clientX: number, clientY: number) {
     const touchEvent = new ClickEvent(clientX, clientY, pointerId)
     touchEvent.target = this
@@ -45,6 +60,7 @@ class ButtonElement extends ContainerElement<"button"> {
     this.touchStartListeners.push(callback)
     return this
   }
+  /** @internal */
   _emitTouchStart(pointerId: number, clientX: number, clientY: number): any {
     const touchEvent = new TouchStartEvent(clientX, clientY, pointerId)
     touchEvent.target = this
@@ -59,12 +75,13 @@ class ButtonElement extends ContainerElement<"button"> {
 
   onLongPress (callback: any): this {
     this.longPressListeners.push(callback)
+    this._addFlags(TREE_FLAG_LONG_PRESS)
     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.
+  /** @internal Fired by the host when the finger is held past the long-press threshold. Returns
+   *  null when nothing is listening — the trailing click then goes through as usual. Otherwise the
+   *  wrapper whose presence swallows that click, carrying the optional drag handler a listener
+   *  registered via `ev.track(...)`. */
   _emitLongPress(pointerId: number, clientX: number, clientY: number): any {
     if (this.longPressListeners.length === 0) return null
     const longPressEvent = new LongPressEvent(clientX, clientY, pointerId)
@@ -75,9 +92,32 @@ class ButtonElement extends ContainerElement<"button"> {
     return { track: (longPressEvent as any)._trackHandler ?? null }
   }
 
-  isPressed(): boolean {
-    if (!this._id) return false
-    return _creatorUI.isButtonPressed(this._id)
+  get isPressed(): boolean {
+    if (!this._h.id) return false
+    return tree().isButtonPressed(this._h.id)
+  }
+
+  onMouseEnter (callback: any): this {
+    this.mouseEnterListeners.push(callback)
+    this._addFlags(TREE_FLAG_HOVER)   // the runtime crosses into JS for hover only on flagged nodes
+    return this
+  }
+  /** @internal Fired by the runtime when the cursor enters (TREE_EVENT_HOVER_ENTER). Returns the
+   *  hover track handler a listener registered via `ev.track(...)`, or null — the emitter keeps it
+   *  in its one hover slot and answers whether moves are wanted. */
+  _emitMouseEnter(clientX: number, clientY: number): any {
+    const ev = new MouseEnterEvent(clientX, clientY)
+    ev.target = this
+    for (let callback of this.mouseEnterListeners) {
+      callback(ev)
+      if ((ev as any)._trackHandler) return (ev as any)._trackHandler
+    }
+    return null
+  }
+
+  get isHovered(): boolean {
+    if (!this._h.id) return false
+    return tree().isHovered(this._h.id)
   }
 }
 
@@ -94,8 +134,6 @@ export const __UIButton = (children: UINodeChild[] | ChildrenFn): UIButton => ma
  *  `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

@@ -19,8 +19,6 @@ export const __UIBox = (children: UINodeChild[] | ChildrenFn): UIBox => makeBox(
  *  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)
 }
@@ -35,8 +33,6 @@ const makeRow = (style: any, children: any) => new ContainerElement("row", style
 /** 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)
 }
@@ -53,8 +49,6 @@ const makeBox = (style: any, children: any) => new ContainerElement("box", style
  *  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

@@ -4,11 +4,12 @@ import type { File } from "../runtime/fetch"
 import { Canvas, isCanvas } from "../canvas/Canvas"
 import type { Scene2D } from "../g2/Scene2D"
 import { Element, type Color, type ElementStyle, type UIElementBase } from "./UINode"
+import { wireColor } from "./styleColor"
+import { tree } from "./tree"
 
 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"). */
+/** A baked Canvas surface as an image source. The UI backend resolves it to a UI texture. */
 export type CanvasImageSource = { canvasSurface: number }
 
 /** A live 2D scene as an image source: the host draws the scene into the node's box every frame
@@ -50,48 +51,51 @@ export interface UIImage extends UIElementBase<UIImageStyle> {
 }
 
 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]
+  private _src!: ResolvedImageSource
   constructor(style: any, src: ImageSource) {
     super("image", style)
-    this._src = toSrc(src)
+    this.src = 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)
+    const next = toSrc(value)
+    // A source tint that is not a colour throws BEFORE anything is applied, like a style colour.
+    const n: any = next
+    const tint = n && typeof n === "object" && "svg" in n && n.tintColor != null ? wireColor("tintColor", n.tintColor) as string : null
+    this._src = next
+    if (this._h.id === 0) return
+    // The wire spellings of a source (the host resolves each prefix): a url as is, "id:<bufferId>"
+    // for a fetch / asset buffer, "svg:<source>" (+ "srcTintColor", '#rrggbbaa' or a var(), AFTER
+    // the src: a src write resets the source tint), "canvas:<surfaceId>", "scene2d:<sceneId>".
+    const s: any = this._src
+    if (typeof s === "string") {
+      tree().setString(this._h.id, "src", s)
+    } else if (s && typeof s === "object") {
+      if ("svg" in s) {
+        tree().setString(this._h.id, "src", "svg:" + s.svg)
+        if (tint != null) tree().setString(this._h.id, "srcTintColor", tint)
+      } else if ("canvasSurface" in s) {
+        tree().setString(this._h.id, "src", "canvas:" + s.canvasSurface)
+      } else if ("scene2d" in s) {
+        tree().setString(this._h.id, "src", "scene2d:" + s.scene2d)
+      } else if ("_h" in s) {
+        tree().setString(this._h.id, "src", "id:" + s._h.id)
+      }
     }
   }
 
   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)
-    }
+    // Texture pixels (not a style → no density scaling); the host decides relayout vs draw-only by
+    // comparing w/h against the rect it has.
+    if (this._h.id !== 0) tree().setString(this._h.id, "sourceRect", `${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])
-  }
-}
+export function UIImage(src: ImageSource): UIImage {
+  return new ImageElement({}, src)
+}