lecodes-cli 0.7.0 → 0.7.2

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.

package/runtime/sdk/ui/UIButton.ts

@@ -1,5 +1,5 @@
-import { ClickEvent, TouchStartEvent } from "../runtime/touch"
-import type { ClickEvent as ClickEventType, TouchStartEvent as TouchStartEventType } from "../runtime/touch"
+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, type Style, ContainerElement, type DrawableStyle, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BaseStyle, type AnimateStyle, type Color } from "./UINode"
 
 export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & { rippleColor?: Color | "default" }
@@ -7,12 +7,16 @@ export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & { ri
 export interface UIButton {
   readonly type: "button",
 
-  style: Style<this, UIButtonStyle & { onPressed?: DrawableStyle & BaseStyle & { duration?: number } }>,
+  style: Style<this, UIButtonStyle & { onPressed?: UIButtonStyle & { duration?: number } }>,
   animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>,
   animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
 
   onClick(callback: (ev: ClickEventType<UIButton>) => void): this,
   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,
   isPressed(): boolean,
 
   append(...nodes: UINodeChild[]): this
@@ -35,6 +39,7 @@ class ButtonElement extends ContainerElement<"button"> {
 
   readonly clickListeners: any[] = []
   readonly touchStartListeners: any[] = []
+  readonly longPressListeners: any[] = []
 
   onClick (callback: any): this {
     this.clickListeners.push(callback)
@@ -65,6 +70,24 @@ class ButtonElement extends ContainerElement<"button"> {
     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)

package/runtime/sdk/ui/UIInput.ts

@@ -8,7 +8,7 @@ export interface UIInput {
 
   value: string
 
-  style: Style<this, UIInputStyle & { onFocused?: DrawableStyle & BaseStyle & { duration?: number } }>,
+  style: Style<this, UIInputStyle & { onFocused?: UIInputStyle & { duration?: number } }>,
   animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
   animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
 
@@ -28,7 +28,7 @@ export interface UITextArea {
 
   value: string
 
-  style: Style<this, UIInputStyle & { onFocused?: DrawableStyle & BaseStyle & { duration?: number } }>,
+  style: Style<this, UIInputStyle & { onFocused?: UIInputStyle & { duration?: number } }>,
   // styleV: StyleFn<this, UIInputStyle>,
   // styleH: StyleFn<this, UIInputStyle>,
 

package/runtime/sdk/ui/UINode.ts

@@ -245,13 +245,38 @@ export type Reactive<T> = { [K in keyof T]: NonNullable<T[K]> extends object ? T
 
 // User-defined style classes: any `$`-prefixed key in .style() declares a state block (like
 // onPressed, but with any name), toggled from code via setClass/toggleClass. `duration`/`delay`
-// make the swap transition.
+// make the swap transition. Class state INHERITS down the tree (CSS-`.dark`-on-body style): a
+// class set on a node also activates same-name `$` blocks on all descendants within the same
+// root — see docs/style-class-cascade-plan.md. `$pressed`/`$focused` are reserved: hosts toggle
+// them on press/focus (they beat other classes, lose to onPressed/onFocused), so children can
+// react to an ancestor's press. Instantiate with the node's own style `T` (see StyleFn below) — a
+// class block accepts everything the node's `.style()` does (e.g. `color` on text, layout on any
+// node), exactly like `onLandscape`/`onPortrait`. Narrowing it (it once was `DrawableStyle &
+// BaseStyle`) wrongly rejected valid props such as `$active: { color }`. Guarded by
+// tests/ui-types.test.ts.
 export type ClassStyles<T> = { [key: `$${string}`]: T & { duration?: number, delay?: number } }
 
-export type StyleFn <R, T extends object> = ((this: R, style: Reactive<T> & { onLandscape?: T, onPortait?: T } & ClassStyles<DrawableStyle & BaseStyle>) => R)
-export type Style <R, T extends object> = StyleFn<R,T> & T & { onLandscape?: T, onPortait?: T } & ClassStyles<DrawableStyle & BaseStyle>
+// NB: do NOT annotate `this: R` here. `this` is a parameter position, so it makes R contravariant,
+// which makes every node type INVARIANT in its own type params (and in `this`). That is what made
+// `UIScreen<false>` unassignable to `UIScreen<boolean>` / `HostedScreen`, and would block any
+// UINode subtype from being assignable to its base. Runtime `this` is already fixed by the
+// `styleFunction.bind(this)` in the `style` getter — the annotation bought nothing and cost variance.
+// R stays only in the (covariant) return, so `.style()` still returns the concrete node type for
+// chaining. Guarded by the type tests in tests/ui-types.test-d.ts.
+// Orientation state blocks — override props applied only in landscape / portrait (like a `$`-class,
+// keyed by device orientation instead of setClass). Same full-`T` rule as class blocks.
+export type OrientationStyles<T> = {
+  onLandscape?: T,
+  onPortrait?: T,
+  /** @deprecated Misspelling of `onPortrait` (no second "r"). Kept so existing projects and published
+   *  bundles keep working — hosts still honour it — but new code should use `onPortrait`. */
+  onPortait?: T,
+}
+
+export type StyleFn <R, T extends object> = ((style: Reactive<T> & OrientationStyles<T> & ClassStyles<T>) => R)
+export type Style <R, T extends object> = StyleFn<R,T> & T & OrientationStyles<T> & ClassStyles<T>
 
-export type AnimateStyle<R, T extends object> = ((this: R, style: T & { duration?: number, delay?: number, layer?: number, commit?: boolean }) => R)
+export type AnimateStyle<R, T extends object> = ((style: T & { duration?: number, delay?: number, layer?: number, commit?: boolean }) => R)
 
 export type AppearStyle <R, T> = (arg: { from: T, duration?: number, delay?: number }) => R
 export type DisappearStyle <R, T> = (arg: { to: T, duration?: number, delay?: number }) => R
@@ -321,7 +346,10 @@ export class Element<T extends string> {
    *  re-assign _id on every open). */
   protected _classes?: Set<string>
 
-  /** Activate/deactivate a `$`-class declared in .style() (accepts the name with or without `$`). */
+  /** Activate/deactivate a `$`-class declared in .style() (accepts the name with or without `$`).
+   *  The class cascades: it is also active on every descendant (their same-name `$` blocks light
+   *  up), until the subtree's root — hosted screens/widgets don't inherit. `hasClass`/`toggleClass`
+   *  reflect only THIS node's own classes; there is no opt-out below an active ancestor. */
   setClass(name: string, enabled: boolean): this {
     if (name[0] === "$") name = name.slice(1)
     if (enabled) {

package/runtime/sdk/ui/UIScreen.ts

@@ -1,35 +1,41 @@
 import { TouchStartEvent } from "../runtime/touch"
+import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
 import { ContainerElement, type AnimateStyle, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type PaddingStyle, type ScrollStyle, type Style, type UINodeChild, type ChildrenFn, } from "./UINode"
 
 export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & ScrollStyle & BaseStyle & ScrollStyle & { refreshControlColor?: Color }
 
-// Default to `false`: a bare `UIScreen` means the non-scrollable screen the `UIScreen(...)`
-// constructor returns, so `const s: UIScreen = UIScreen([...])` type-checks. The type is invariant
-// in `Scrollable` (the fluent `style()` puts `this` in a contravariant position), so a `boolean`
-// default wouldn't accept the constructor's `UIScreen<false>`. Opt into scrolling via
-// `.makeScrollable(): UIScreen<true>`; write `UIScreen<boolean>` explicitly when you need the union.
-export interface UIScreen <Scrollable extends boolean = false> {
+// A screen — the root the router/host mounts, sized to its slot. Two flavours share one contract: a
+// plain `UIScreen`, and a `UIScrollableScreen` (a screen that also scrolls). `makeScrollable()`
+// upgrades a plain screen to the scrollable one, where `onScroll`/`onOverscroll`/`onRefresh` live —
+// they mean nothing without scrolling. `UIScrollableScreen extends UIScreen`, so anywhere a
+// `UIScreen` / `HostedScreen` is accepted, a scrollable one works too.
+//
+// This is a subtype split, NOT a `UIScreen<Scrollable>` generic: a generic can't work while `style`
+// is `Style<this,…>`, because `this` is then contravariant and the type becomes invariant in its own
+// params — that was the old `UIScreen<false>`-not-assignable-to-`HostedScreen` bug. See the StyleFn
+// note in UINode.ts; the contract is pinned by tests/ui-types.test.ts.
+export interface UIScreen {
   readonly type: "screen",
-  scrollable: Scrollable,
+  readonly scrollable: boolean,
   style: Style<this, UIScreenStyle>,
   animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
   animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
 
-  open(): void,
+  /** Show this screen as the current destination (replaces whatever is visible — a screen, a
+   *  scene, a native view — suspending an active Router until `Router.restore()`). */
+  open(options?: PresentOptions): void,
   close(): void
 
   append(...nodes: UINodeChild[]): this
   insert(index: number, ...nodes: UINodeChild[]): this
   remove(...nodes: UINodeChild[]): this
   setContent(nodes: UINodeChild[] | ChildrenFn): this
-  
+
   readonly children: UINodeChild[],
 
-  makeScrollable(): UIScreen<true>,
-  onScroll: Scrollable extends true? (callback: (scrollPosition: number) => void) => void: never,
-  onOverscroll: Scrollable extends true? (callback: (scrollPosition: number) => void) => void: never,
+  /** Upgrade this screen into a scroll view, unlocking `onScroll`/`onOverscroll`/`onRefresh`. */
+  makeScrollable(): UIScrollableScreen,
   onBackPressed(callback: () => void): this
-  onRefresh: Scrollable extends true? ((callback: () => void | Promise<void>) => this): never,
 
   onOpen(callback: () => void): this
   onClose(callback: () => void): this
@@ -52,16 +58,46 @@ export interface UIScreen <Scrollable extends boolean = false> {
   hasClass(name: string): boolean
   bindClass(name: string, fn: () => boolean): this
 
-  onTouchStart(callback: (ev: TouchStartEvent<UIScreen<boolean>>) => void): this,
+  onTouchStart(callback: (ev: TouchStartEvent<UIScreen>) => void): this,
+}
+
+/**
+ * A `UIScreen` in scroll mode — what `makeScrollable()` returns. Adds the scroll lifecycle that a
+ * plain screen doesn't carry. A subtype of `UIScreen`, so it's accepted anywhere a screen /
+ * `HostedScreen` is (router pages, `UIScreenHost`, `UITabs`).
+ */
+export interface UIScrollableScreen extends UIScreen {
+  readonly scrollable: true,
+  /** Fires as the content scrolls; the offset is logical px from the start edge. Chainable. */
+  onScroll(callback: (scrollPosition: number) => void): this,
+  /** Fires while the user drags past an edge (rubber-band). Chainable. */
+  onOverscroll(callback: (scrollPosition: number) => void): this,
+  /** Pull-to-refresh: the spinner stays until the returned promise resolves. Chainable. */
+  onRefresh(callback: () => void | Promise<void>): this,
+  /** Already scrollable — returns itself. */
+  makeScrollable(): UIScrollableScreen,
 }
 
 export class ScreenElement extends ContainerElement<"screen"> {
-  scrollable = false as const
-  open(): void {
-    _creatorUI.openScreen(this) 
+  scrollable = false
+  open(options?: PresentOptions): void {
+    _bumpNavEpoch()
+    if (_navSupported()) {
+      _creatorUI.openView!(this, options?.transition ?? "none")
+    } else {
+      // Legacy host: no destination navigation — transition is dropped.
+      _creatorUI.openScreen(this)
+    }
+    _setCurrent(this as any)
   }
   close(): void {
-    _creatorUI.closeScreen()
+    _bumpNavEpoch()
+    if (_navSupported()) {
+      _creatorUI.closeView!()
+    } else {
+      _creatorUI.closeScreen()
+    }
+    if (Presentable.current === (this as any)) _setCurrent(null)
   }
   protected ol: (() => void)[] = []
   onOpen(callback: () => void): this {
@@ -103,8 +139,8 @@ export class ScreenElement extends ContainerElement<"screen"> {
     }
     return null
   }
-  makeScrollable(): UIScreen<true> {
-    this.scrollable = true as any
+  makeScrollable(): UIScrollableScreen {
+    this.scrollable = true
 
     Object.assign(this, {
       sl: [] as any[],
@@ -123,24 +159,22 @@ export class ScreenElement extends ContainerElement<"screen"> {
       }
     })
 
-    return this as any as UIScreen<true>
+    return this as any as UIScrollableScreen
   }
   _backButtonCallback?: () => void
   onBackPressed(callback: any): this {
     this._backButtonCallback = callback
     return this
   }
+  // Set by the onRefresh method that makeScrollable() grafts on; read by the host at mount.
   declare _refreshCallback: any
-  declare onRefresh: never
-  declare onScroll: never
-  declare onOverscroll: never
 }
 
-export function UIScreen(): UIScreen<false>;
-export function UIScreen(children: UINodeChild[] | ChildrenFn): UIScreen<false>;
-export function UIScreen(style: UIScreenStyle): UIScreen<false>;
-export function UIScreen(style: UIScreenStyle, children: UINodeChild[]): UIScreen<false>;
-export function UIScreen(...args: [] | [UINodeChild[] | ChildrenFn | UIScreenStyle] | [UIScreenStyle, children: UINodeChild[] | ChildrenFn]): UIScreen<false> {
+export function UIScreen(): UIScreen;
+export function UIScreen(children: UINodeChild[] | ChildrenFn): UIScreen;
+export function UIScreen(style: UIScreenStyle): UIScreen;
+export function UIScreen(style: UIScreenStyle, children: UINodeChild[]): UIScreen;
+export function UIScreen(...args: [] | [UINodeChild[] | ChildrenFn | UIScreenStyle] | [UIScreenStyle, children: UINodeChild[] | ChildrenFn]): UIScreen {
   if (args.length === 0) {
     return new ScreenElement("screen", {}, [])
   } else if (args.length === 1) {

package/runtime/sdk/ui/UIScreenHost.ts

@@ -12,8 +12,9 @@ import type { UIScreen } from "./UIScreen"
 // implements exactly one page kind: mount the screen root in the slot, lay it out to the slot size.
 // To host a plain element, wrap it: UIScreenHost(UIScreen([el])).
 
-/** A hosted page: any UIScreen, scrollable or not. Sizing styles on it are ignored (screens are roots sized by their host). */
-export type HostedScreen = UIScreen<boolean>
+/** A hosted page: any UIScreen (a `UIScrollableScreen` is a subtype, so it's accepted too). Sizing
+ *  styles on it are ignored — screens are roots sized by their host. */
+export type HostedScreen = UIScreen
 /** Reactive pages — ChildrenFn narrowed to screens. */
 export type ScreensFn = () => (HostedScreen | null | undefined | false)[]
 

package/runtime/sdk/ui/UIText.ts

@@ -1,7 +1,7 @@
 import { createBinding } from "../core/signals"
 import { Element, type AnimateStyle, type BaseStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type Style, type TextStyle } from "./UINode"
 
-export type UITextStyle = ElementStyle & TextStyle
+export type UITextStyle = ElementStyle & TextStyle & DrawableStyle
 
 export interface UIText {
   readonly type: "text",

package/runtime/sdk/ui/UIVideo.ts

@@ -1,4 +1,5 @@
 import type { VideoPlayer } from "../runtime/media"
+import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
 import { Element, type AnimateStyle, type AppearStyle, type BaseStyle, type DisappearStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type Style, type StyleFn } from "./UINode"
 
 export type UIVideoStyle = ElementStyle & DrawableStyle & { objectFit?: "cover" | "contain" | "fill" }
@@ -10,6 +11,14 @@ export interface UIVideo {
   animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
   animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
 
+  /** Show fullscreen as the current destination. Promotion: if this video is mounted in a screen,
+   *  the SAME native player moves fullscreen — playback uninterrupted; a pop moves it back. */
+  open(options?: PresentOptions): void
+  close(): void
+  onOpen(callback: () => void): this
+  onClose(callback: () => void): this
+  onBackPressed(callback: () => void): this
+
   onLayout(onLayout: OnLayoutCallback): this
 
   setClass(name: string, enabled: boolean): this
@@ -18,7 +27,7 @@ export interface UIVideo {
   bindClass(name: string, fn: () => boolean): this
 }
 
-class VideoElement extends Element<"video"> {
+class VideoElement extends Element<"video"> implements Presentable {
   private _playerId: number
   private _player: VideoPlayer
   constructor(style: any, player: VideoPlayer) {
@@ -30,6 +39,43 @@ class VideoElement extends Element<"video"> {
   get player() {
     return this._player
   }
+
+  // ---- Presentable (docs/navigation-presentable-plan.md) ----
+  readonly ol: (() => void)[] = []
+  readonly cl: (() => void)[] = []
+  _backButtonCallback?: () => void
+  private _vd?: object
+
+  /** @internal wire descriptor — type "videoView" (distinct from the "video" node type). */
+  _viewDesc(): object {
+    return this._vd ??= { type: "videoView", node: this, _p: this }
+  }
+
+  open(options?: PresentOptions): void {
+    if (!_navSupported()) {
+      throw new Error("Fullscreen video 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
+  }
 }
 
 export function UIVideo(player: VideoPlayer): UIVideo
@@ -40,4 +86,4 @@ export function UIVideo(...args: [VideoPlayer] | [UIVideoStyle, VideoPlayer]): U
   } else {
     return new VideoElement(args[0], args[1])
   }
-}
+}

package/runtime/sdk/ui/UIWidget.ts

@@ -1,4 +1,5 @@
 import { TouchStartEvent } from "../runtime/touch"
+import { _descOf, _navSupported, Presentable } from "./presentable"
 import { ContainerElement, type AnimateStyle, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type PaddingStyle, type PositionStyle, type Style, type UINodeChild, type ChildrenFn } from "./UINode"
 
 
@@ -15,7 +16,23 @@ export interface UIWidget {
   animateTo: AnimateStyle<this, DrawableStyle & BaseStyle & { overlayColor?: Color | null }>
   animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle & { overlayColor?: Color | null }>
 
+  /**
+   * Pre-bind this widget to a destination (a `Scene`, a `UIScreen`, …) that is not current yet —
+   * e.g. HUD for an `ARScene` built before opening it, so it's in place from the first frame.
+   * `show()` binds to the *current* destination automatically, so this is only needed ahead of
+   * time (or to target a non-current owner). Sticky: an explicit owner wins over the automatic
+   * one until `attachTo(null)` (= back to automatic). Set it while the widget is hidden.
+   */
+  attachTo(owner: Presentable | null): this,
+
+  /** Show the widget, attached to the current destination (or the `attachTo` owner): it mounts
+   *  inside that page, shows/hides with it and rides its transition — a dialog opened on a screen
+   *  disappears when the user navigates away. For an overlay that survives navigation use
+   *  `showDetached()`. */
   show(): void,
+  /** Show the widget as a global overlay above every destination — it stays visible across
+   *  navigation (mini-player, global loader). */
+  showDetached(): void,
   hide(): void,
 
   readonly isShow: boolean,
@@ -41,8 +58,24 @@ export interface UIWidget {
 
 export class WidgetElement extends ContainerElement<"widget"> {
   scrollable = false as const
+  _owner?: Presentable
+  attachTo(owner: Presentable | null): this {
+    this._owner = owner ?? undefined
+    return this
+  }
   show(): void {
-    _creatorUI.showWidget(this) 
+    // Explicit attachTo() wins; otherwise bind to whatever is on screen right now — re-showing
+    // the same widget from another page re-attaches it there.
+    const owner = this._owner ?? Presentable.current
+    if (owner && _navSupported()) {
+      _creatorUI.showWidget(this, _descOf(owner))
+    } else {
+      // Legacy host (or nothing presented yet): global overlay.
+      _creatorUI.showWidget(this)
+    }
+  }
+  showDetached(): void {
+    _creatorUI.showWidget(this)
   }
   hide(): void {
     _creatorUI.hideWidget(this)