lecodes-cli 0.7.0 → 0.7.1

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,33 @@ 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. 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

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)

package/runtime/sdk/ui/presentable.ts

@@ -0,0 +1,116 @@
+// The Presentable contract — the one navigation model (docs/navigation-presentable-plan.md).
+// Anything that can occupy the app's main slot implements it: UIScreen, Scene (+ARScene),
+// Scene2D, NativeView, UIVideo. Exactly one Presentable is visible at a time — a screen no
+// longer overlays a scene, it replaces it (with a transition); UI over a scene goes through
+// `UIWidget.attachTo(scene)`.
+//
+// This module is dependency-free on purpose: gl/ and g2/ import it, so it must not pull any UI
+// element code into engine-only bundles.
+
+/** Built-in transition catalog. `push`/`pop` are the stacked-navigation pair (slide + parallax +
+ *  dim + edge shadow); the rest are simple two-view moves. */
+export type TransitionName =
+  | "push" | "pop"
+  | "slide-from-left" | "slide-from-right" | "slide-from-top" | "slide-from-bottom"
+  | "zoom" | "zoom-in" | "zoom-out" | "fade" | "none"
+
+/** Start/end pose of one side of a custom transition. `x`/`y` are logical px, or a percentage of
+ *  the destination's size (e.g. `"100%"` = one full width to the right). */
+export type TransitionTransform = {
+  x?: number | `${number}%`
+  y?: number | `${number}%`
+  scale?: number
+  opacity?: number
+}
+
+/**
+ * A custom transition: declarative poses for the incoming/outgoing destination, played natively.
+ * Serializes onto each platform's existing transition machinery — there is no per-frame JS.
+ * Fields omitted keep the identity pose. Interactive back-swipe stays system-native (push/pop
+ * only); a spec applies to non-interactive transitions.
+ */
+export interface TransitionSpec {
+  /** Duration in ms (default 300). */
+  duration?: number
+  /** cubic-bezier control points (default ease-out). */
+  easing?: [number, number, number, number]
+  /** The entering destination animates FROM this pose to identity. */
+  incoming?: { from?: TransitionTransform }
+  /** The leaving destination animates from identity TO this pose. */
+  outgoing?: { to?: TransitionTransform }
+  /** Scrim alpha (0..1) painted over whichever destination is underneath. */
+  dim?: number
+  /** Which side stacks on top during the animation (default "incoming"). On Android, transitions
+   *  involving a scene always animate the screen side on top — the scene view itself never moves. */
+  onTop?: "incoming" | "outgoing"
+}
+
+export type Transition = TransitionName | TransitionSpec
+
+export type PresentOptions = {
+  /** Transition to play while this destination replaces the current one (default "none" for a
+   *  direct open(); the Router applies its own defaults — push/fade/pop). */
+  transition?: Transition
+}
+
+/**
+ * Anything that can be shown as the app's current destination: a `UIScreen`, a `Scene` /
+ * `ARScene`, a `Scene2D`, a `NativeView`, or a `UIVideo`. One Presentable is visible at a time;
+ * open it directly (`p.open()` — replaces the current destination, suspending an active Router
+ * until `Router.restore()`) or navigate with `Router.push/replace/pop`.
+ *
+ * `onOpen`/`onClose` are the presentation lifecycle (fired when the destination becomes / stops
+ * being the visible one — including router pushes covering it and pops revealing it).
+ */
+export interface Presentable {
+  // Return type covers the implementers: UIScreen → void, Scene2D → this, ARScene → Promise.
+  open(options?: PresentOptions): void | this | Promise<void>
+  close(): void
+  onOpen(callback: () => void): this
+  onClose(callback: () => void): this
+  onBackPressed(callback: () => void): this
+  /** @internal Async work that must finish BEFORE this destination replaces the current one
+   *  (camera permission, warm render, session launch — ARScene). The previous destination —
+   *  typically a loading screen — stays visible while it runs; `open()` and `Router.push/replace`
+   *  await it and skip the swap entirely if it rejects (permission denied, or superseded by
+   *  another navigation that happened while preparing). */
+  _prepare?(): Promise<void>
+}
+
+// The destination visible right now. Set optimistically by every successful open()/router
+// navigation, cleared by close(), and corrected by router onChange (hosts hand the wire desc
+// back on every stack change, including back gestures — `_p` resolves it to the SDK instance).
+let current: Presentable | null = null
+/** @internal Call whenever the visible destination changes. */
+export const _setCurrent = (p: Presentable | null): void => { current = p }
+
+/** Runtime companion of the `Presentable` interface (declaration merging): the navigation
+ *  state that isn't tied to the Router. */
+export const Presentable = /*#__PURE__*/ Object.freeze({
+  /** The destination visible right now (a `UIScreen`, `Scene`, `Scene2D`, `NativeView` or
+   *  `UIVideo`), or `null` before the first open. Distinct from `Router.current` — that is the
+   *  top of the router stack, which stays meaningful while the router is suspended by a direct
+   *  `open()`; this is what is actually on screen. `UIWidget.show()` attaches to it. */
+  get current(): Presentable | null { return current },
+})
+
+// Monotonic navigation epoch: every destination change (open/close/router nav) bumps it. Async
+// preparers capture the epoch before their awaits and reject as "superseded" if it moved — so a
+// slow AR prepare can't steal the screen from a navigation the user made in the meantime.
+let navEpoch = 0
+/** @internal */
+export const _navEpoch = (): number => navEpoch
+/** @internal Call on every action that changes the visible destination. */
+export const _bumpNavEpoch = (): void => { navEpoch++ }
+
+/** @internal Does this host implement the Presentable navigation surface? The SDK falls back to
+ *  the legacy openScreen/openScene bridges when it doesn't (screens keep working; scene/native
+ *  destinations in the Router then throw). */
+export const _navSupported = (): boolean =>
+  typeof _creatorUI !== "undefined" && typeof _creatorUI.openView === "function"
+
+/** @internal The wire descriptor for a Presentable. Screens (and anything without `_viewDesc`)
+ *  travel as themselves; scenes/native views/video provide a stable descriptor object carrying
+ *  `_p` (the SDK instance) so hosts can hand it back through router onChange / lifecycle. */
+export const _descOf = (p: Presentable): object =>
+  typeof (p as any)._viewDesc === "function" ? (p as any)._viewDesc() : (p as object)