lecodes-cli 0.7.0 → 0.7.1

package/runtime/sdk/runtime/app.ts

@@ -0,0 +1,37 @@
+// The app's own lifecycle + how it was opened (docs/app-lifecycle-plan.md). Events are semantic —
+// "pause"/"resume", never Activity/Scene vocabulary — and the current values are synchronous pulls
+// so render-loop code can read them without subscribing.
+
+import { appEventsOn, appEventsOff } from "./appEvents"
+
+export type AppState = "active" | "background"
+
+type AppEventMap = {
+  /** The app left the foreground (home button, tab hidden, another app on top). Delivered before
+   *  the host halts the frame loop — the last chance to persist state / pause work. */
+  pause: () => void
+  /** The app returned to the foreground; frames are running again. */
+  resume: () => void
+  /** A link arrived while the app was running (warm deep link). `app.launchUrl` is already
+   *  updated to the same value when this fires. */
+  url: (url: string) => void
+}
+
+export const app = {
+  /** Current lifecycle state. `"background"` while the app is not the foreground app / the tab is
+   *  hidden. `"active"` on hosts that don't track it. */
+  get state(): AppState {
+    return _creatorUtils.appState?.() === "background" ? "background" : "active"
+  },
+  /** The URL the app was (most recently) opened with — the deep link — or `null` for a plain
+   *  launch. Warm links update it and fire the `"url"` event. */
+  get launchUrl(): string | null {
+    return _creatorUtils.getLaunchUrl?.() ?? null
+  },
+  addEventListener<E extends keyof AppEventMap>(event: E, callback: AppEventMap[E]): void {
+    appEventsOn(event, callback as (data?: string) => void)
+  },
+  removeEventListener<E extends keyof AppEventMap>(event: E, callback: AppEventMap[E]): void {
+    appEventsOff(event, callback as (data?: string) => void)
+  },
+}

package/runtime/sdk/runtime/appEvents.ts

@@ -0,0 +1,29 @@
+// The shared app-event dispatcher. The host exposes ONE registerAppEvent slot per JS world
+// (docs/app-lifecycle-plan.md), so every SDK consumer (the `app` global's pause/resume/url, the
+// `device` global's online/offline) subscribes here and this module registers with the host once,
+// lazily on the first subscription — no top-level side effect, tree-shaking drops it when unused.
+
+type AppEventCallback = (data?: string) => void
+
+const listeners: Record<string, AppEventCallback[]> = {}
+let registered = false
+
+const dispatch = (event: string, data?: string): void => {
+  const arr = listeners[event]
+  if (arr) for (const cb of arr.slice()) cb(data)
+}
+
+export const appEventsOn = (event: string, cb: AppEventCallback): void => {
+  ;(listeners[event] ??= []).push(cb)
+  if (!registered) {
+    registered = true
+    _creatorUtils.registerAppEvent?.(dispatch)
+  }
+}
+
+export const appEventsOff = (event: string, cb: AppEventCallback): void => {
+  const arr = listeners[event]
+  if (!arr) return
+  const i = arr.indexOf(cb)
+  if (i >= 0) arr.splice(i, 1)
+}

package/runtime/sdk/runtime/channel.ts

@@ -0,0 +1,50 @@
+// The JSON wire protocol shared by the two host plugin channels — NativeView
+// (`_creatorUI.viewCall`, see ui/NativeView.ts) and headless services
+// (`_creatorUtils.serviceCall`, see runtime/service.ts). One protocol, two transports:
+// `args`, results, and event payloads travel as JSON strings, and an absent/empty string
+// decodes to `undefined`. Typed plugins (QRScanner, CameraView, Geolocation) layer methods
+// over this — see src/plugins/.
+
+/** @internal event-name → listeners. NativeView exposes it as `nvl` (host contract). */
+export type ChannelListeners = Record<string, ((data?: any) => void)[]>
+
+/** @internal */
+export const _channelOn = (listeners: ChannelListeners, event: string, callback: (data?: any) => void): void => {
+  (listeners[event] ??= []).push(callback)
+}
+
+/** @internal */
+export const _channelOff = (listeners: ChannelListeners, event: string, callback: (data?: any) => void): void => {
+  const list = listeners[event]
+  if (!list) return
+  const i = list.indexOf(callback)
+  if (i >= 0) list.splice(i, 1)
+}
+
+/** @internal deliver a host event: decode the JSON payload, fan out (copy-before-iterate). */
+export const _channelEmit = (listeners: ChannelListeners, event: string, dataJson?: string): void => {
+  const list = listeners[event]
+  if (!list || list.length === 0) return
+  const data = dataJson === undefined || dataJson === "" ? undefined : JSON.parse(dataJson)
+  for (const cb of [...list]) cb(data)
+}
+
+type ChannelCallBridge = (
+  id: number, method: string, args: string,
+  onComplete: (result?: string) => void, onError: (err: string) => void,
+) => void
+
+/** @internal one JSON call over a channel bridge; `bridge` may be absent (optional ABI member). */
+export const _channelCall = (
+  bridge: ChannelCallBridge | undefined, unsupportedError: string,
+  id: number, method: string, args: any[],
+): Promise<any> =>
+  new Promise((res, rej) => {
+    if (typeof bridge !== "function") {
+      rej(new Error(unsupportedError))
+      return
+    }
+    bridge(id, method, JSON.stringify(args),
+      (result?: string) => res(result === undefined || result === "" ? undefined : JSON.parse(result)),
+      (err: string) => rej(new Error(err)))
+  })

package/runtime/sdk/runtime/clipboard.ts

@@ -0,0 +1,20 @@
+// System clipboard (docs/app-lifecycle-plan.md). Write is fire-and-forget; read is async because
+// web gates it behind a permission prompt (native hosts complete synchronously).
+
+export const clipboard = {
+  /** Put `text` on the system clipboard. Silent no-op on hosts without clipboard access. */
+  write(text: string): void {
+    _creatorUtils.clipboardWrite?.(text)
+  },
+  /** Read text from the system clipboard. Rejects when the platform has no clipboard access, the
+   *  user denied it, or there is nothing readable. */
+  read(): Promise<string> {
+    return new Promise((resolve, reject) => {
+      if (typeof _creatorUtils.clipboardRead !== "function") {
+        reject(new Error("Clipboard is not supported on this platform"))
+        return
+      }
+      _creatorUtils.clipboardRead(resolve, (err: string) => reject(new Error(err)))
+    })
+  },
+}

package/runtime/sdk/runtime/datetime.ts

@@ -243,10 +243,8 @@ export class DateValue {
   startOf(unit: Unit): DateValue {
     const d = new Date(this.t)
     switch (unit) {
-      case "year": d.setMonth(0)
-      // falls through
-      case "month": d.setDate(1)
-      // falls through
+      case "year": d.setMonth(0); d.setDate(1); d.setHours(0, 0, 0, 0); break
+      case "month": d.setDate(1); d.setHours(0, 0, 0, 0); break
       case "day": d.setHours(0, 0, 0, 0); break
       case "hour": d.setMinutes(0, 0, 0); break
       case "minute": d.setSeconds(0, 0); break

package/runtime/sdk/runtime/device.ts

@@ -1,8 +1,20 @@
 // Platform info + the host resize event. The resize listener registers with the host lazily on the
 // first subscription (no top-level side effect, so tree-shaking can drop this entirely if unused).
 
+import { Quat } from "../math/quat"
+import { Vec3 } from "../math/vec"
+import { appEventsOn, appEventsOff } from "./appEvents"
+
 type ResizeCallback = (width: number, height: number) => void
 
+type DeviceEventMap = {
+  resize: ResizeCallback
+  /** Connectivity came back (best-effort, navigator.onLine semantics). */
+  online: () => void
+  /** Connectivity was lost. */
+  offline: () => void
+}
+
 const resizeListeners: ResizeCallback[] = []
 let resizeRegistered = false
 
@@ -10,6 +22,49 @@ const onResize = (width: number, height: number): void => {
   for (const cb of resizeListeners.slice()) cb(width, height)
 }
 
+/** Semantic haptic styles for `device.vibrate`. Impact styles (`light`/`medium`/`heavy`/`soft`/
+ *  `rigid`) are a physical "tap" of varying weight; notification styles (`success`/`warning`/`error`)
+ *  cue an outcome; `selection` is a light tick for a value change. Chosen to map 1:1 onto iOS
+ *  `UIFeedbackGenerator` and, on Android, `HapticFeedbackConstants` / `VibrationEffect` — so the same
+ *  call feels native everywhere, rather than a duration that only web/Android can honor. */
+export type HapticStyle =
+  | "light" | "medium" | "heavy" | "soft" | "rigid"
+  | "success" | "warning" | "error"
+  | "selection"
+
+/** Options for `device.motion.start`. */
+export interface MotionOptions {
+  /** Sensor update interval in seconds (default 1/60). The sensor fuses at ≥ this rate in the
+   *  background; you poll the freshest sample each frame, so this is a floor, not a sync. */
+  interval?: number
+  /** Frame the readables are delivered in. "world" (default): engine Y-up, screen-oriented — drops
+   *  straight into `camera.quaternion` / any node. "device": the raw sensor frame, no conversion. */
+  frame?: "world" | "device"
+}
+
+// --- device.motion state (pull-per-frame model) ---
+let motionEnabled = false
+let motionFrame: "world" | "device" = "world"
+let motionYawOffset = 0   // radians about world up, captured by recenter()
+
+// Calibration constants — VERIFY ON A PHYSICAL DEVICE (the simulator reports no motion).
+//  • CM_TO_WORLD: Core Motion's reference frame is Z-up; the engine world is Y-up. If a level horizon
+//    reads tilted ~90°, this is the term to check.
+//  • ORIENTATION_ROLL: roll about the view axis so camera-up tracks screen-up, indexed by the native
+//    interface-orientation code [portrait, landscapeLeft, landscapeRight, upsideDown]. If landscape is
+//    upside-down or rolled the wrong way, flip the ±π/2 signs.
+// If the whole panorama turns the wrong way (look right → view goes left), conjugate `raw` below.
+const CM_TO_WORLD = Quat.fromAxisAngle([1, 0, 0], -Math.PI / 2)
+const ORIENTATION_ROLL = [0, Math.PI / 2, -Math.PI / 2, Math.PI]
+
+// Device attitude → engine world frame, with the interface-orientation roll folded in (yaw NOT yet
+// recentered). Shared by `attitude` (which adds the recenter) and `gravity` (which is yaw-invariant).
+const orientedAttitude = (s: ArrayLike<number>): Quat => {
+  const raw = new Quat(s[0], s[1], s[2], s[3])
+  const roll = Quat.fromAxisAngle([0, 0, 1], ORIENTATION_ROLL[s[7]] ?? 0)
+  return CM_TO_WORLD.mul(raw).mul(roll)
+}
+
 export const device = {
   get platform(): "web" | "android" | "ios" | string {
     return _creatorUtils.platform
@@ -43,17 +98,95 @@ export const device = {
   setPreciseTouch(enabled: boolean): void {
     _creatorUtils.setPreciseTouch?.(enabled)
   },
-  addEventListener(channel: "resize", callback: ResizeCallback): void {
+  /** Fire a one-shot haptic of the given semantic `style` (default `"medium"`) — a physical tap on
+   *  supported hardware (iOS Taptic Engine, Android vibrator). Chosen by meaning, not duration, so it
+   *  feels native on each platform; see {@link HapticStyle}. Host-gated: a silent no-op where there's
+   *  no haptic hardware (iPad, older iPhones, web, headless). */
+  vibrate(style: HapticStyle = "medium"): void {
+    _creatorUtils.vibrate?.(style)
+  },
+  /** Device-orientation sensor (gyro + accelerometer, fused) for tilt/steering and magic-window /
+   *  360° panoramas. Poll `attitude` / `gravity` inside setLoop; they return the freshest fused
+   *  sample, so the sensor rate need not match your frame rate. Host-gated: a no-op with no sensor. */
+  motion: {
+    /** Whether this device has the motion sensors at all (no gyro → false; iPad/older, web, headless). */
+    get available(): boolean {
+      return _creatorUtils.motionAvailable?.() ?? false
+    },
+    /** Whether updates are currently running (start succeeded and stop hasn't been called). */
+    get enabled(): boolean {
+      return motionEnabled
+    },
+    /** Begin sensor updates. Resolves to whether it actually started (false = no sensor / denied).
+     *  Async so a web host can await its permission prompt; native resolves immediately. */
+    async start(options: MotionOptions = {}): Promise<boolean> {
+      motionFrame = options.frame ?? "world"
+      motionEnabled = !!(await (_creatorUtils.motionStart?.(options.interval ?? 1 / 60) ?? false))
+      return motionEnabled
+    },
+    /** Stop sensor updates and release the sensor (battery). */
+    stop(): void {
+      _creatorUtils.motionStop?.()
+      motionEnabled = false
+    },
+    /** Capture the current heading as "forward" — a yaw-only recenter (pitch/roll stay gravity-
+     *  referenced, so the horizon stays level). No-op in the "device" frame. */
+    recenter(): void {
+      const s = _creatorUtils.getMotionSample?.()
+      if (!s || motionFrame === "device") { motionYawOffset = 0; return }
+      const f = orientedAttitude(s).rotateVec3([0, 0, -1])   // world-space camera forward
+      motionYawOffset = Math.atan2(-f.x, -f.z)               // heading about world up
+    },
+    /** The device's current orientation as a `Quat`. In the "world" frame (default) it's engine Y-up
+     *  and screen-oriented, so `camera.quaternion = device.motion.attitude` is a complete magic-window
+     *  / panorama camera. `Quat.identity` until the first sample arrives / when not running. */
+    get attitude(): Quat {
+      const s = _creatorUtils.getMotionSample?.()
+      if (!s) return Quat.identity
+      if (motionFrame === "device") return new Quat(s[0], s[1], s[2], s[3])
+      const q = orientedAttitude(s)
+      return Quat.fromAxisAngle([0, 1, 0], -motionYawOffset).mul(q)   // yaw recenter (world-frame)
+    },
+    /** Gravity direction for tilt controls. In the "world" frame it's SCREEN space (x → right, y →
+     *  down, matching clientX/clientY), orientation-aware — a 2D game reads `gravity.x / gravity.y`.
+     *  `(0,0,0)` when not running. */
+    get gravity(): Vec3 {
+      const s = _creatorUtils.getMotionSample?.()
+      if (!s) return new Vec3(0, 0, 0)
+      if (motionFrame === "device") return new Vec3(s[4], s[5], s[6])
+      // Re-express the raw device-frame gravity in screen space: undo the interface roll (about the
+      // screen normal), then flip Y to screen-down. Uses the unambiguous CMDeviceMotion.gravity, so
+      // it stays correct regardless of the attitude-quaternion convention above.
+      const unroll = Quat.fromAxisAngle([0, 0, 1], -(ORIENTATION_ROLL[s[7]] ?? 0))
+      const g = new Vec3(s[4], s[5], s[6]).rotate(unroll)
+      return new Vec3(g.x, -g.y, g.z)
+    },
+  },
+  /** Current connectivity — best-effort navigator.onLine semantics: `false` only when the platform
+   *  is sure there's no network. `true` on hosts that don't track it. Change events: `"online"` /
+   *  `"offline"`. */
+  get online(): boolean {
+    return _creatorUtils.isOnline?.() ?? true
+  },
+  addEventListener<E extends keyof DeviceEventMap>(channel: E, callback: DeviceEventMap[E]): void {
+    if (channel === "online" || channel === "offline") {
+      appEventsOn(channel, callback as () => void)
+      return
+    }
     if (channel !== "resize") return
-    resizeListeners.push(callback)
+    resizeListeners.push(callback as ResizeCallback)
     if (!resizeRegistered) {
       resizeRegistered = true
       _creatorUI.registerResizeEvent(onResize)
     }
   },
-  removeEventListener(channel: "resize", callback: ResizeCallback): void {
+  removeEventListener<E extends keyof DeviceEventMap>(channel: E, callback: DeviceEventMap[E]): void {
+    if (channel === "online" || channel === "offline") {
+      appEventsOff(channel, callback as () => void)
+      return
+    }
     if (channel !== "resize") return
-    const i = resizeListeners.indexOf(callback)
+    const i = resizeListeners.indexOf(callback as ResizeCallback)
     if (i >= 0) resizeListeners.splice(i, 1)
   },
 }

package/runtime/sdk/runtime/misc.ts

@@ -3,6 +3,10 @@
 /** Show a transient toast notification. */
 export const toast = (msg: string): void => _creatorUI.toast(msg)
 
+/** Open `url` in the system browser / external handler (fire-and-forget, like `share`). Silent
+ *  no-op on hosts without one (headless). */
+export const openURL = (url: string): void => _creatorUtils.openUrl?.(url)
+
 export type SvgSourceValue = {
   readonly svg: string
   tintColor: string | null

package/runtime/sdk/runtime/service.ts

@@ -0,0 +1,82 @@
+// A host-registered headless service (geolocation, bluetooth, contacts, …) — the UI-less sibling
+// of NativeView (docs/service-channel-plan.md). The host registers a *capability*
+// (`registerService("geolocation") { params, channel -> ... }`); the SDK talks to it over the
+// shared JSON call/event protocol (runtime/channel.ts) via `_creatorUtils.service*`.
+//
+// Not a public global: apps meet services only through typed plugin wrappers (Geolocation —
+// src/plugins/), which subclass or wrap this exactly like QRScanner wraps NativeViewElement.
+
+import { _channelCall, _channelEmit, _channelOff, _channelOn, type ChannelListeners } from "./channel"
+
+/** @internal Base for typed service plugins. The host session opens lazily on the first `call()`
+ *  (`on()` only records listeners), and `close()` releases it — a later `call()` reopens a fresh
+ *  session. Session ids are host-allocated (websocket model): the `onEvent` callback is handed
+ *  over at open, so no SDK-side ref registry is needed. */
+export class ServiceClient {
+  readonly serviceName: string
+  readonly params: any
+  private _serviceId: number | null = null
+  private readonly _listeners: ChannelListeners = {}
+
+  constructor(serviceName: string, params: any = {}) {
+    this.serviceName = serviceName
+    this.params = params
+  }
+
+  /** Whether this host registered a `registerService` factory under `name`. */
+  static isSupported(name: string): boolean {
+    return typeof _creatorUtils !== "undefined" && typeof _creatorUtils.isServiceSupported === "function"
+      && _creatorUtils.isServiceSupported(name)
+  }
+
+  /** @internal open (or reuse) the host session; throws when the host has no channel/factory. */
+  private _ensureOpen(): number {
+    if (this._serviceId !== null) return this._serviceId
+    if (typeof _creatorUtils === "undefined" || typeof _creatorUtils.serviceOpen !== "function") {
+      throw new Error(`Service("${this.serviceName}") is not supported on this host (requires _creatorUtils.serviceOpen)`)
+    }
+    const id = _creatorUtils.serviceOpen(this.serviceName, JSON.stringify(this.params ?? {}),
+      (event: string, dataJson?: string) => _channelEmit(this._listeners, event, dataJson))
+    if (id < 0) {
+      throw new Error(`Service("${this.serviceName}") is not registered on this host`)
+    }
+    this._serviceId = id
+    return id
+  }
+
+  /** Invoke a method on the service (`geo.call("getCurrent", options)`). Args and the result are
+   *  JSON-serialized. Rejects if the host has no such service/method. */
+  call(method: string, ...args: any[]): Promise<any> {
+    let id: number
+    try {
+      id = this._ensureOpen()
+    } catch (e) {
+      return Promise.reject(e)
+    }
+    return _channelCall(
+      typeof _creatorUtils !== "undefined" ? _creatorUtils.serviceCall : undefined,
+      `Service("${this.serviceName}") is not supported on this host (requires _creatorUtils.serviceCall)`,
+      id, method, args)
+  }
+
+  /** Subscribe to an event the service emits (`geo.on("position", cb)`). */
+  on(event: string, callback: (data?: any) => void): this {
+    _channelOn(this._listeners, event, callback)
+    return this
+  }
+  off(event: string, callback: (data?: any) => void): this {
+    _channelOff(this._listeners, event, callback)
+    return this
+  }
+
+  /** Close the host session (stops whatever the service was doing). Listeners stay registered —
+   *  a later `call()` opens a fresh session that delivers to them again. */
+  close(): void {
+    if (this._serviceId === null) return
+    const id = this._serviceId
+    this._serviceId = null
+    if (typeof _creatorUtils !== "undefined" && typeof _creatorUtils.serviceClose === "function") {
+      _creatorUtils.serviceClose(id)
+    }
+  }
+}

package/runtime/sdk/runtime/touch.ts

@@ -48,3 +48,29 @@ export class TouchStartEvent<T = any> {
     this._trackHandler = handler
   }
 }
+
+/** Delivered to a `UIButton` `onLongPress` handler when a finger is held on the button past the
+ *  host's long-press threshold. Like `TouchStartEvent` it can `track(...)` the rest of the gesture —
+ *  so the common "press-and-hold, then drag to move" flow is one handler: start the drag from here. */
+export class LongPressEvent<T = any> {
+  readonly type = "longpress"
+  readonly pointerId: number
+  readonly clientX: number
+  readonly clientY: number
+  /** World-space hit position (2D scenes only; undefined in 3D). */
+  worldX?: number
+  worldY?: number
+  target!: T
+  /** @internal — read by the dispatch system after the handler runs. */
+  _trackHandler?: TrackHandler
+  constructor(clientX: number, clientY: number, pointerId: number) {
+    this.clientX = clientX
+    this.clientY = clientY
+    this.pointerId = pointerId
+  }
+
+  /** Capture subsequent moves/end for this pointer — drag the element after the hold. */
+  track(handler: TrackHandler): void {
+    this._trackHandler = handler
+  }
+}

package/runtime/sdk/ui/NativeView.ts

@@ -0,0 +1,144 @@
+// 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 AnimateStyle, type BaseStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type Style } from "./UINode"
+
+export type UINativeViewStyle = ElementStyle & DrawableStyle
+
+export interface NativeView {
+  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,
+  style: Style<this, UINativeViewStyle>,
+  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
+  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
+
+  /** Show fullscreen as the current destination (see Presentable). */
+  open(options?: PresentOptions): void,
+  close(): void,
+
+  onOpen(callback: () => void): this
+  onClose(callback: () => void): this
+  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
+
+  onLayout(onLayout: OnLayoutCallback): this
+  setClass(name: string, enabled: boolean): this
+  toggleClass(name: string): this
+  hasClass(name: string): boolean
+  bindClass(name: string, fn: () => boolean): 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.viewCall : undefined,
+      `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/runtime/sdk/ui/UI.ts

@@ -1,7 +1,7 @@
 // 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 { UIScreen, type UIScreenStyle, type UIScrollableScreen } from './UIScreen'
 export { UISpacer, type UISpacerStyle } from './UISpacer'
 export { UIText, type UITextStyle } from './UIText'
 export { registerFont } from './fonts'
@@ -18,6 +18,10 @@ export { UIScreenHost, type UIScreenHostStyle } from './UIScreenHost'
 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.