lecodes-sdk 1.1.0 → 2.0.0

package/src/scene/gizmos.ts

@@ -1,148 +1,154 @@
-// Editor gizmos: immediate-mode line drawing for code that runs while a scene is EDITED — a
-// generator aspect's `rebuild()`, a `make()` factory, an editor tool's hooks. Nothing here touches
-// the scene: calls accumulate WORLD-space line segments into the buffer of the run that is
-// currently executing (an ambient scope the scene loader opens around each synchronous call), and
-// the scene editor pushes those buffers to the lite engine's overlay layer, which draws them over
-// the picture — never outlined, never picked, never rendered by Filament, absent in play mode.
-//
-//   rebuild() {
-//     Gizmos.polyline(points, { color: "#5b8ef0", closed: true })
-//     for (const p of points) Gizmos.cross(p, 0.07)
-//   }
-//
-// Every run starts with an EMPTY buffer — what a call draws is the whole picture (like
-// `generated.clear()`, only implicit). Outside any scope (play mode, hand-attached aspects, a call
-// after an `await` inside rebuild) the calls are no-ops: rebuild is synchronous by contract.
-//
-// ANCHORED gizmos (`{ node }` in the style): points are in that node's LOCAL frame and the engine
-// follows the node live — through a gizmo drag, not only after it — with the node's scale
-// stripped (an empty scaled ×10 for its children keeps a normal-sized cross). An anchored picture
-// is the node's own: clicking it in the viewport selects the node, and it draws in the selection
-// accent while selected. World-space calls (path lines) are never pickable.
-
-import { Mat4, type Mat4Like } from "../math/mat4"
-import type { Vec3Like } from "../math/vec"
-
-/** The anchor of a gizmo call: any object with an engine entity id (a `Node`). */
-export type GizmoAnchor = { readonly id: number }
-
-export type GizmoStyle = {
-  /** CSS hex color (`#rgb` / `#rrggbb`); default a neutral light gray. */
-  color?: string
-  /** 0..1, default 1. */
-  alpha?: number
-  /** Anchor: points are in this node's LOCAL frame (scale ignored); the lines follow the node
-   *  live, are pickable (a click selects the node) and turn the selection accent when it is
-   *  selected. Omit for world-space lines (not pickable). */
-  node?: GizmoAnchor | null
-}
-
-/** One color batch of LINES (flat `[x,y,z, x,y,z]` per segment) — what a host hands the engine.
- *  With `entityId` the segments are in that entity's local frame (see GizmoStyle.node). */
-export type GizmoBatch = { color: string, alpha: number, segments: number[], entityId?: number }
-
-const DEFAULT_COLOR = "#cfd4dd"
-
-/** The per-run collector (owned by the scene loader's EditorRun). Batches are keyed by style so a
- *  hundred same-colored segments cost one draw. */
-export class GizmoBuffer {
-  batches: GizmoBatch[] = []
-  private _byStyle = new Map<string, GizmoBatch>()
-
-  clear(): void {
-    this.batches = []
-    this._byStyle.clear()
-  }
-
-  segments(style: GizmoStyle | undefined): number[] {
-    const color = style?.color ?? DEFAULT_COLOR
-    const alpha = Math.max(0, Math.min(1, style?.alpha ?? 1))
-    const entityId = style?.node?.id
-    const key = `${color}@${alpha}@${entityId ?? ""}`
-    let b = this._byStyle.get(key)
-    if (!b) {
-      b = entityId ? { color, alpha, segments: [], entityId } : { color, alpha, segments: [] }
-      this._byStyle.set(key, b)
-      this.batches.push(b)
-    }
-    return b.segments
-  }
-}
-
-let current: GizmoBuffer | null = null
-let warnedOutOfScope = false
-
-const xyz = (p: Vec3Like): [number, number, number] =>
-  Array.isArray(p) ? [ p[0] ?? 0, p[1] ?? 0, p[2] ?? 0 ] : [ (p as { x: number }).x, (p as { y: number }).y, (p as { z: number }).z ]
-
-const target = (style: GizmoStyle | undefined): number[] | null => {
-  if (current) return current.segments(style)
-  if (!warnedOutOfScope && (globalThis as { __lecodesSceneEdit?: boolean }).__lecodesSceneEdit) {
-    warnedOutOfScope = true
-    console.warn("[Gizmos] draw call outside an editor run — gizmos must be drawn synchronously inside rebuild() / a make() factory / a tool hook")
-  }
-  return null
-}
-
-/** @internal Run `fn` with `buffer` as the ambient gizmo target (cleared first). Nested scopes
- *  restore the outer one. */
-export const withGizmoScope = <T>(buffer: GizmoBuffer, fn: () => T): T => {
-  const prev = current
-  buffer.clear()
-  current = buffer
-  try { return fn() } finally { current = prev }
-}
-
-/**
- * Editor-only line drawing, available inside generator `rebuild()`, `make()` factories and editor
- * tool hooks. Points are WORLD space. Drawn by the scene editor's viewport overlay (depth-test
- * off — a path through a wall is still a path); invisible everywhere else.
- */
-export const Gizmos = {
-  /** One segment from `a` to `b`. */
-  line(a: Vec3Like, b: Vec3Like, style?: GizmoStyle): void {
-    const out = target(style)
-    if (!out) return
-    out.push(...xyz(a), ...xyz(b))
-  },
-
-  /** Consecutive segments through `points`; `closed` joins the last point back to the first. */
-  polyline(points: readonly Vec3Like[], style?: GizmoStyle & { closed?: boolean }): void {
-    if (points.length < 2) return
-    const out = target(style)
-    if (!out) return
-    const n = points.length
-    const last = style?.closed ? n : n - 1
-    for (let i = 0; i < last; i++) out.push(...xyz(points[i]!), ...xyz(points[(i + 1) % n]!))
-  },
-
-  /** A wireframe camera frustum looking down −Z: the four edges from the origin to a rect
-   *  `length` metres ahead sized by `fov` (vertical, degrees) × `aspect` (default 16:9), plus an
-   *  "up" fin above the rect. Anchor it (`{ node }`) for a camera node's marker — the frustum
-   *  then follows the node's pose; `matrix` places an unanchored one in world space. */
-  frustum(fov: number, style?: GizmoStyle & { aspect?: number, length?: number, matrix?: Mat4Like }): void {
-    const out = target(style)
-    if (!out) return
-    const aspect = style?.aspect ?? 16 / 9, length = style?.length ?? 0.6
-    const m = style?.matrix ? new Mat4(style.matrix) : null
-    const h = Math.tan((fov * Math.PI) / 360) * length, w = h * aspect, z = -length
-    const P = (x: number, y: number, zz: number): [number, number, number] => {
-      if (!m) return [ x, y, zz ]
-      const v = m.transformPoint([ x, y, zz ])
-      return [ v.x, v.y, v.z ]
-    }
-    const o = P(0, 0, 0)
-    const c = [ P(-w, -h, z), P(w, -h, z), P(w, h, z), P(-w, h, z) ]
-    for (const q of c) out.push(...o, ...q)
-    for (let i = 0; i < 4; i++) out.push(...c[i]!, ...c[(i + 1) % 4]!)
-    out.push(...P(-w * 0.4, h, z), ...P(0, h * 1.6, z), ...P(0, h * 1.6, z), ...P(w * 0.4, h, z))
-  },
-
-  /** A three-axis cross centred on `p` (a point marker); `size` = half extent, default 0.1. */
-  cross(p: Vec3Like, size = 0.1, style?: GizmoStyle): void {
-    const out = target(style)
-    if (!out) return
-    const [ x, y, z ] = xyz(p)
-    out.push(x - size, y, z, x + size, y, z, x, y - size, z, x, y + size, z, x, y, z - size, x, y, z + size)
-  },
-}
+// Editor gizmos: immediate-mode line drawing for code that runs while a scene is EDITED — a
+// generator aspect's `rebuild()`, a `make()` factory, an editor tool's hooks. Nothing here touches
+// the scene: calls accumulate WORLD-space line segments into the buffer of the run that is
+// currently executing (an ambient scope the scene loader opens around each synchronous call), and
+// the scene editor pushes those buffers to the lite engine's overlay layer, which draws them over
+// the picture — never outlined, never picked, never rendered by Filament, absent in play mode.
+//
+//   rebuild() {
+//     Gizmos.polyline(points, { color: "#5b8ef0", closed: true })
+//     for (const p of points) Gizmos.cross(p, 0.07)
+//   }
+//
+// Every run starts with an EMPTY buffer — what a call draws is the whole picture (like
+// `generated.clear()`, only implicit). Outside any scope (play mode, hand-attached aspects, a call
+// after an `await` inside rebuild) the calls are no-ops: rebuild is synchronous by contract. In a
+// shipped bundle they are no-ops by COMPILE: `target` folds to null with `EDITOR`, and the buffer
+// and the scope (the editor's — ./editor.ts) are not in the bundle.
+//
+// ANCHORED gizmos (`{ node }` in the style): points are in that node's LOCAL frame and the engine
+// follows the node live — through a gizmo drag, not only after it — with the node's scale
+// stripped (an empty scaled ×10 for its children keeps a normal-sized cross). An anchored picture
+// is the node's own: clicking it in the viewport selects the node, and it draws in the selection
+// accent while selected. World-space calls (path lines) are never pickable.
+
+import { Color, type ColorInput } from "../core/color"
+import { Mat4, type Mat4Like } from "../math/mat4"
+import type { Vec3Like } from "../math/vec"
+
+/** The anchor of a gizmo call: any object with an engine entity id (a `Node`). */
+export type GizmoAnchor = { readonly id: number }
+
+export type GizmoStyle = {
+  /** Any color (a CSS color string, `0xRRGGBB`, `[r, g, b(, a)]`; its alpha multiplies `alpha`);
+   *  default a neutral light gray. */
+  color?: ColorInput
+  /** 0..1, default 1. */
+  alpha?: number
+  /** Anchor: points are in this node's LOCAL frame (scale ignored); the lines follow the node
+   *  live, are pickable (a click selects the node) and turn the selection accent when it is
+   *  selected. Omit for world-space lines (not pickable). */
+  node?: GizmoAnchor | null
+}
+
+/** One color batch of LINES (flat `[x,y,z, x,y,z]` per segment) — what a host hands the engine
+ *  (`color` a CSS color string, '#rrggbbaa' from here). With `entityId` the segments are in that
+ *  entity's local frame (see GizmoStyle.node). */
+export type GizmoBatch = { color: string, alpha: number, segments: number[], entityId?: number }
+
+const DEFAULT_COLOR = "#cfd4ddff"
+
+/** The per-run collector (owned by the scene loader's EditorRun). Batches are keyed by style so a
+ *  hundred same-colored segments cost one draw. */
+export class GizmoBuffer {
+  batches: GizmoBatch[] = []
+  private _byStyle = new Map<string, GizmoBatch>()
+
+  clear(): void {
+    this.batches = []
+    this._byStyle.clear()
+  }
+
+  segments(style: GizmoStyle | undefined): number[] {
+    // one spelling per color, so 'red' and '#f00' share a batch
+    const color = style?.color != null ? Color.toHexString(style.color) : DEFAULT_COLOR
+    const alpha = Math.max(0, Math.min(1, style?.alpha ?? 1))
+    const entityId = style?.node?.id
+    const key = `${color}@${alpha}@${entityId ?? ""}`
+    let b = this._byStyle.get(key)
+    if (!b) {
+      b = entityId ? { color, alpha, segments: [], entityId } : { color, alpha, segments: [] }
+      this._byStyle.set(key, b)
+      this.batches.push(b)
+    }
+    return b.segments
+  }
+}
+
+let current: GizmoBuffer | null = null
+let warnedOutOfScope = false
+
+const xyz = (p: Vec3Like): [number, number, number] =>
+  Array.isArray(p) ? [ p[0] ?? 0, p[1] ?? 0, p[2] ?? 0 ] : [ (p as { x: number }).x, (p as { y: number }).y, (p as { z: number }).z ]
+
+const target = (style: GizmoStyle | undefined): number[] | null => {
+  if (EDITOR && current) return current.segments(style)
+  if (EDITOR && !warnedOutOfScope && (globalThis as { __lecodesSceneEdit?: boolean }).__lecodesSceneEdit) {
+    warnedOutOfScope = true
+    console.warn("[Gizmos] draw call outside an editor run — gizmos must be drawn synchronously inside rebuild() / a make() factory / a tool hook")
+  }
+  return null
+}
+
+/** @internal Run `fn` with `buffer` as the ambient gizmo target (cleared first). Nested scopes
+ *  restore the outer one. */
+export const withGizmoScope = <T>(buffer: GizmoBuffer, fn: () => T): T => {
+  const prev = current
+  buffer.clear()
+  current = buffer
+  try { return fn() } finally { current = prev }
+}
+
+/**
+ * Editor-only line drawing, available inside generator `rebuild()`, `make()` factories and editor
+ * tool hooks. Points are WORLD space. Drawn by the scene editor's viewport overlay (depth-test
+ * off — a path through a wall is still a path); invisible everywhere else.
+ */
+export const Gizmos = {
+  /** One segment from `a` to `b`. */
+  line(a: Vec3Like, b: Vec3Like, style?: GizmoStyle): void {
+    const out = target(style)
+    if (!out) return
+    out.push(...xyz(a), ...xyz(b))
+  },
+
+  /** Consecutive segments through `points`; `closed` joins the last point back to the first. */
+  polyline(points: readonly Vec3Like[], style?: GizmoStyle & { closed?: boolean }): void {
+    if (points.length < 2) return
+    const out = target(style)
+    if (!out) return
+    const n = points.length
+    const last = style?.closed ? n : n - 1
+    for (let i = 0; i < last; i++) out.push(...xyz(points[i]!), ...xyz(points[(i + 1) % n]!))
+  },
+
+  /** A wireframe camera frustum looking down −Z: the four edges from the origin to a rect
+   *  `length` metres ahead sized by `fov` (vertical, degrees) × `aspect` (default 16:9), plus an
+   *  "up" fin above the rect. Anchor it (`{ node }`) for a camera node's marker — the frustum
+   *  then follows the node's pose; `matrix` places an unanchored one in world space. */
+  frustum(fov: number, style?: GizmoStyle & { aspect?: number, length?: number, matrix?: Mat4Like }): void {
+    const out = target(style)
+    if (!out) return
+    const aspect = style?.aspect ?? 16 / 9, length = style?.length ?? 0.6
+    const m = style?.matrix ? new Mat4(style.matrix) : null
+    const h = Math.tan((fov * Math.PI) / 360) * length, w = h * aspect, z = -length
+    const P = (x: number, y: number, zz: number): [number, number, number] => {
+      if (!m) return [ x, y, zz ]
+      const v = m.transformPoint([ x, y, zz ])
+      return [ v.x, v.y, v.z ]
+    }
+    const o = P(0, 0, 0)
+    const c = [ P(-w, -h, z), P(w, -h, z), P(w, h, z), P(-w, h, z) ]
+    for (const q of c) out.push(...o, ...q)
+    for (let i = 0; i < 4; i++) out.push(...c[i]!, ...c[(i + 1) % 4]!)
+    out.push(...P(-w * 0.4, h, z), ...P(0, h * 1.6, z), ...P(0, h * 1.6, z), ...P(w * 0.4, h, z))
+  },
+
+  /** A three-axis cross centred on `p` (a point marker); `size` = half extent, default 0.1. */
+  cross(p: Vec3Like, size = 0.1, style?: GizmoStyle): void {
+    const out = target(style)
+    if (!out) return
+    const [ x, y, z ] = xyz(p)
+    out.push(x - size, y, z, x + size, y, z, x, y - size, z, x, y + size, z, x, y, z - size, x, y, z + size)
+  },
+}

package/src/server/db/marci/query.ts

@@ -7,7 +7,7 @@
 // per-model type bags and MODELS metadata this file is parametrised by.
 //
 // Keep it dependency-free: besides shipping in `marcidb-client/runtime`, this file is vendored verbatim
-// into the lecodes SDK (`packages/sdk/src/server/db/marci/query.ts`, `bun run sync:marcidb` there), which
+// into the lecodes SDK (`sdk/src/server/db/marci/query.ts`, `bun run sync:marcidb` there), which
 // derives its model types from TS builders instead of codegen and plugs them into the same generics.
 
 // ───────────────────────────── query language types ─────────────────────────────

package/src/server/host.ts

@@ -1,6 +1,6 @@
 /**
  * `sdk/server` — the HOST side of the app backend, imported normally by the runner
- * (packages/lecodes-runner), the backend and tests. Nothing here is bundled into project code; the
+ * (tools/runner), the backend and tests. Nothing here is bundled into project code; the
  * bundle carries its own SDK copy and meets this module only through the `globalThis.__lecodes*`
  * seams (see ./runtime.ts).
  */

package/src/server/runtime.ts

@@ -1,5 +1,5 @@
 /**
- * Host side of a compiled server bundle — used by the runner (packages/lecodes-runner) and by tests.
+ * Host side of a compiled server bundle — used by the runner (tools/runner) and by tests.
  * Imported normally (Node/Bun), NOT through chisel: the bundle carries its own SDK copy and talks
  * to this module only through globals (`__lecodesServer`, `__lecodesRequest`, `__lecodesPublish`).
  *

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)
 }