lecodes-cli 0.6.4 → 0.7.1

package/runtime/sdk/ui/UIScreenHost.ts

@@ -0,0 +1,213 @@
+import { ContainerElement, type AnimateStyle, type BaseStyle, type ChildrenFn, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type Style, type UINodeChild } from "./UINode"
+import type { UIScreen } from "./UIScreen"
+
+// UIScreenHost — the system's ONE screen host: an element whose pages are full UIScreens, each laid
+// out to the host's box (the same mechanism screens use, with the "device" swapped for the slot).
+// With several screens it pages between them (wrapping each platform's native pager); with a single
+// screen it simply embeds it — a refreshable region under a fixed header, or a screen-swap slot via
+// setContent(next). UITabs is pure TS over a swipe-disabled UIScreenHost.
+//
+// Pages are screens ONLY — no plain elements. Every page then carries the full screen contract
+// (onOpen/onClose from the settle lifecycle, makeScrollable()/onRefresh), and every platform
+// 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 (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)[]
+
+/**
+ * Transition for `replace()`. The `Router.replace` catalogue, plus `"push"`/`"pop"` — the native
+ * UINavigationController feel (the incoming/outgoing screen slides full-width while the other
+ * parallaxes ~30% under a dim overlay with a soft edge shadow). Use `"push"` to go forward, `"pop"`
+ * to go back. (Animated transitions are native-only; web swaps instantly.)
+ */
+export type ScreenHostTransition =
+  | "push" | "pop"
+  | "slide-from-left" | "slide-from-right" | "slide-from-top" | "slide-from-bottom"
+  | "zoom" | "zoom-in" | "zoom-out" | "fade" | "none"
+
+export type UIScreenHostStyle = ElementStyle & DrawableStyle & {
+  // Paging axis. Default "horizontal". Read by the host at mount; live-updatable via .style().
+  scrollDirection?: "horizontal" | "vertical",
+  // false = programmatic-only paging (no user swipe) — the mode UITabs uses. Default true.
+  swipeEnabled?: boolean,
+}
+
+export interface UIScreenHost {
+  readonly type: "screenhost",
+  style: Style<this, UIScreenHostStyle>,
+  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>,
+  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>,
+
+  /** Current settled page index. */
+  readonly page: number,
+  /** Programmatic page switch. `animated` defaults to true (ignored when swipe physics can't run). */
+  setPage(index: number, animated?: boolean): this,
+  /** Fires when the settled page changes (after the swipe/scroll comes to rest). */
+  onPageChange(callback: (index: number) => void): this,
+  /** Continuous fractional scroll position (e.g. 1.35) — for tab-strip indicators / page dots. */
+  onPageScroll(callback: (position: number) => void): this,
+
+  append(...screens: HostedScreen[]): this,
+  insert(index: number, ...screens: HostedScreen[]): this,
+  remove(...screens: HostedScreen[]): this,
+  /** Replace the pages. A single screen swaps the hosted screen in place (old page onClose → new page onOpen). */
+  setContent(screens: HostedScreen | HostedScreen[] | ScreensFn): this,
+  /**
+   * Replace the page at `index` with a new screen, animating the swap when that page is the visible
+   * one (off-screen pages swap instantly). The settled page index is preserved — a replace is not a
+   * page change. This is the push/pop primitive: keep your own stack of screens and replace the
+   * visible slot with a forward transition to push, a backward one to pop.
+   */
+  replace(index: number, screen: HostedScreen, transition?: ScreenHostTransition): this,
+
+  readonly children: UINodeChild[],
+
+  onLayout(onLayout: OnLayoutCallback): this,
+
+  setClass(name: string, enabled: boolean): this,
+  toggleClass(name: string): this,
+  hasClass(name: string): boolean,
+  bindClass(name: string, fn: () => boolean): this,
+}
+
+export class ScreenHostElement extends ContainerElement<"screenhost"> {
+  // --- read by the host at mount (createScreenHostSystem) ---
+  _page = 0                                      // settled index; host writes it back on settle
+  _dir: "horizontal" | "vertical" = "horizontal"
+  _swipe = true
+
+  // --- listeners the host invokes directly (same pattern as UIScrollable.sl / vlist) ---
+  readonly pcl: ((index: number) => void)[] = []   // onPageChange
+  readonly psl: ((position: number) => void)[] = [] // onPageScroll
+
+  get page(): number {
+    return this._page
+  }
+
+  setPage(index: number, animated = true): this {
+    if (this._id !== 0) {
+      _creatorUI.command(this, "setPage", index, animated)
+    } else {
+      this._page = index   // remembered as the initial page until the host mounts
+    }
+    return this
+  }
+
+  onPageChange(callback: (index: number) => void): this {
+    this.pcl.push(callback)
+    return this
+  }
+  onPageScroll(callback: (position: number) => void): this {
+    this.psl.push(callback)
+    return this
+  }
+
+  // Pages are separate layout roots, not yoga children, so the generic insertNode/removeNode path
+  // doesn't apply. Keep `children` in sync and ask the host to reconcile pages by node identity.
+  append(...nodes: UINodeChild[]): this {
+    this.children.push(...nodes)
+    if (this._id !== 0) _creatorUI.command(this, "syncPages")
+    return this
+  }
+  insert(index: number, ...nodes: UINodeChild[]): this {
+    this.children.splice(index, 0, ...nodes)
+    if (this._id !== 0) _creatorUI.command(this, "syncPages")
+    return this
+  }
+  remove(...nodes: UINodeChild[]): this {
+    const set = new Set(nodes)
+    this.children = this.children.filter(c => !set.has(c as UINodeChild))
+    if (this._id !== 0) _creatorUI.command(this, "syncPages")
+    return this
+  }
+  setContent(nodes: UINodeChild | UINodeChild[] | ChildrenFn): this {
+    if (typeof nodes === "function") {
+      // Reactive pages: the base binding drives _reconcile, which calls our insert/remove above.
+      return super.setContent(nodes)
+    }
+    this.children = Array.isArray(nodes) ? [...nodes] : [nodes]
+    if (this._id !== 0) _creatorUI.command(this, "syncPages")
+    return this
+  }
+
+  // Replace one page in place, animated. The node travels via children[index] (the command channel
+  // carries only index + transition); the host reads it back and swaps the page, animating the swap
+  // when `index` is the visible page. Before mount it just seeds the initial content at that index.
+  replace(index: number, screen: UINodeChild, transition: ScreenHostTransition = "fade"): this {
+    if (index < 0 || index >= this.children.length) return this
+    this.children[index] = screen
+    if (this._id !== 0) _creatorUI.command(this, "replace", index, transition)
+    return this
+  }
+
+  // scrollDirection/swipeEnabled are host behavior, not layout — intercept them here so they never
+  // reach the layout engine, and forward live changes to the host. Everything else flows to the base
+  // style proxy unchanged (including property get/set via the forwarding Proxy below).
+  private _hostStyleProxy?: any
+  get style(): any {
+    if (this._hostStyleProxy) return this._hostStyleProxy
+    const base = super.style
+    const self = this
+    const apply = (s: any) => {
+      if (s && typeof s === "object") {
+        if ("scrollDirection" in s && typeof s.scrollDirection !== "function") {
+          self._dir = s.scrollDirection
+          delete s.scrollDirection
+          if (self._id !== 0) _creatorUI.command(self, "setDirection", self._dir)
+        }
+        if ("swipeEnabled" in s && typeof s.swipeEnabled !== "function") {
+          self._swipe = s.swipeEnabled
+          delete s.swipeEnabled
+          if (self._id !== 0) _creatorUI.command(self, "setSwipe", self._swipe)
+        }
+      }
+      return base(s)
+    }
+    this._hostStyleProxy = new Proxy(apply, {
+      apply: (_t, _thisArg, args) => apply(args[0]),
+      get: (_t, k) => (base as any)[k],
+      set: (_t, k, v) => { (base as any)[k] = v; return true },
+    })
+    return this._hostStyleProxy
+  }
+}
+
+function makeScreenHost(style: UIScreenHostStyle | null, children: UINodeChild[] | ChildrenFn): ScreenHostElement {
+  const dir = style?.scrollDirection
+  const swipe = style?.swipeEnabled
+  if (style) {
+    delete style.scrollDirection
+    delete style.swipeEnabled
+  }
+  const el = new ScreenHostElement("screenhost", style ?? {}, children)
+  if (dir !== undefined) el._dir = dir
+  if (swipe !== undefined) el._swipe = swipe
+  return el
+}
+
+// A screen is the only non-array, non-function, non-style argument the factory accepts.
+const isScreenArg = (v: any): boolean => v != null && typeof v === "object" && v.type === "screen"
+const asPages = (v: any): UINodeChild[] | ChildrenFn => (Array.isArray(v) || typeof v === "function") ? v : [v]
+
+export function UIScreenHost(): UIScreenHost
+export function UIScreenHost(screen: HostedScreen): UIScreenHost
+export function UIScreenHost(screens: HostedScreen[] | ScreensFn): UIScreenHost
+export function UIScreenHost(style: UIScreenHostStyle): UIScreenHost
+export function UIScreenHost(style: UIScreenHostStyle, screens: HostedScreen | HostedScreen[] | ScreensFn): UIScreenHost
+export function UIScreenHost(...args: [] | [HostedScreen | HostedScreen[] | ScreensFn | UIScreenHostStyle] | [UIScreenHostStyle, HostedScreen | HostedScreen[] | ScreensFn]): UIScreenHost {
+  if (args.length === 0) {
+    return makeScreenHost({}, [])
+  } else if (args.length === 1) {
+    if (Array.isArray(args[0]) || typeof args[0] === "function" || isScreenArg(args[0])) {
+      return makeScreenHost({}, asPages(args[0]))
+    } else {
+      return makeScreenHost(args[0] as UIScreenHostStyle, [])
+    }
+  } else {
+    return makeScreenHost(args[0] as UIScreenHostStyle, asPages(args[1]))
+  }
+}

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)

package/runtime/sdk/ui/router.ts

@@ -1,68 +1,112 @@
-import { UIScreen } from "./UIScreen";
+import { _bumpNavEpoch, _descOf, _navSupported, _setCurrent, Presentable, type Transition } from "./presentable"
 
 type RouterOptions = {
   showDefaultBackButton?: boolean
 }
 
+type NavigateOptions = {
+  /** Transition to play. Defaults: `"push"` for push, `"fade"` for replace, `"pop"` for pop. */
+  transition?: Transition
+}
+
 type Router = {
-  get current(): UIScreen<boolean>
-  init<T extends boolean>(homePage: UIScreen<T>, opts?: RouterOptions): void
-  push<T extends boolean>(screen: UIScreen<T>): void
-  replace<T extends boolean>(screen: UIScreen<T>, options?: ReplaceOptions): void
-  pop(to?: number): void
+  get current(): Presentable
+  init(homePage: Presentable, opts?: RouterOptions): void
+  /** Push a destination onto the stack — a `UIScreen`, a `Scene`, a `Scene2D`, a `NativeView`,
+   *  or a `UIVideo`. The back gesture/button pops it. Destinations with async preparation
+   *  (`ARScene`: camera permission + warm render) return a Promise — the current page stays
+   *  visible until they're ready, and a rejection (permission denied / superseded) leaves the
+   *  stack untouched. */
+  push(page: Presentable, opts?: NavigateOptions): void | Promise<void>
+  replace(page: Presentable, opts?: NavigateOptions): void | Promise<void>
+  pop(to?: number, opts?: NavigateOptions): void
   hide(): void
   restore(): void
 
-  addEventListener(channel: "change", callback: (screen: UIScreen<boolean>) => void): void
-  removeEventListener(channel: "change", callback: (screen: UIScreen<boolean>) => void): void
+  addEventListener(channel: "change", callback: (page: Presentable) => void): void
+  removeEventListener(channel: "change", callback: (page: Presentable) => void): void
 }
 
-let currentScreen: UIScreen<any> | null = null
-let onChange = <T extends boolean>(screen: UIScreen<T>) => {
-  currentScreen = screen;
+let currentPage: Presentable | null = null
+let onChange = (page: any) => {
+  // Hosts hand back the wire object: the screen itself, or a descriptor carrying `_p`.
+  currentPage = page && page._p ? page._p : page
+  // The router's page is the visible destination (hosts fire this on every stack change,
+  // including back gestures) — keep Presentable.current in sync.
+  _setCurrent(currentPage)
   for (let callback of (Router as any)._changeListeners) {
-    callback(screen)
+    callback(currentPage)
   }
 }
 
-type ReplaceOptions = {
-  transition: "slide-from-left" | "slide-from-right" | "slide-from-top" | "slide-from-bottom" | 
-    "zoom" | "zoom-out" | "zoom-in" | "fade" | "none"
+// Non-screen destinations have no legacy bridge to fall back to — surface that clearly instead
+// of letting an old host try to build a screen out of a scene descriptor.
+const wireDesc = (page: Presentable): object => {
+  const desc = _descOf(page)
+  if (desc !== page && !_navSupported()) {
+    throw new Error("This host does not support scene/native-view navigation (requires _creatorUI.openView)")
+  }
+  return desc
 }
 
 export const Router: Router = /*#__PURE__*/ Object.freeze({
 
-  init(homePage: UIScreen<any>, opts: RouterOptions = {}): void {
-    _creatorUI.routerOpen(homePage, onChange, opts.showDefaultBackButton ?? false)
-    currentScreen = homePage
+  init(homePage: Presentable, opts: RouterOptions = {}): void {
+    _bumpNavEpoch()
+    _creatorUI.routerOpen(wireDesc(homePage), onChange, opts.showDefaultBackButton ?? false)
+    currentPage = homePage
+    _setCurrent(homePage)
   },
-  push(screen: UIScreen<any>): void {
-    _creatorUI.routerPush(screen)
+  push(page: Presentable, opts?: NavigateOptions): void | Promise<void> {
+    const desc = wireDesc(page)   // throws early on unsupported hosts, before any async work
+    const go = () => {
+      _bumpNavEpoch()
+      // Legacy hosts ignore the extra transition argument.
+      _creatorUI.routerPush(desc, opts?.transition ?? "push")
+      _setCurrent(page)   // optimistic — host onChange confirms (async on native hosts)
+    }
+    // A preparing destination (ARScene) keeps the current page visible until it's ready; a
+    // rejection (camera denied / superseded) propagates to the caller and nothing is pushed.
+    const prep = page._prepare?.()
+    return prep ? prep.then(go) : go()
   },
-  replace(screen: UIScreen<any>, opts?: ReplaceOptions): void {
-    _creatorUI.routerReplace(screen, opts?.transition ?? "fade")
+  replace(page: Presentable, opts?: NavigateOptions): void | Promise<void> {
+    const desc = wireDesc(page)
+    const go = () => {
+      _bumpNavEpoch()
+      _creatorUI.routerReplace(desc, opts?.transition ?? "fade")
+      _setCurrent(page)   // optimistic — host onChange confirms (async on native hosts)
+    }
+    const prep = page._prepare?.()
+    return prep ? prep.then(go) : go()
   },
-  pop(to?: number): void {
-    _creatorUI.routerPop(to ?? -1)
+  pop(to?: number, opts?: NavigateOptions): void {
+    _bumpNavEpoch()
+    _creatorUI.routerPop(to ?? -1, opts?.transition ?? "pop")
   },
   hide() {
+    _bumpNavEpoch()
     _creatorUI.routerHide()
+    // hide() only blanks the router's own page — a directly-opened destination stays visible.
+    if (Presentable.current === currentPage) _setCurrent(null)
   },
   restore() {
+    _bumpNavEpoch()
     _creatorUI.routerRestore()
+    _setCurrent(currentPage)   // the stack top is visible again
   },
 
-  get current(): UIScreen<any> {
-    return currentScreen!
+  get current(): Presentable {
+    return currentPage!
   },
-  
+
   _changeListeners: [] as any[],
-  addEventListener(channel: "change", callback: (screen: UIScreen<boolean>) => void): void { 
+  addEventListener(channel: "change", callback: (page: Presentable) => void): void {
     if (channel === "change") {
       this._changeListeners.push(callback)
     }
   },
-  removeEventListener(channel: "change", callback: (screen: UIScreen<boolean>) => void): void {
+  removeEventListener(channel: "change", callback: (page: Presentable) => void): void {
     if (channel === "change") {
       let index = this._changeListeners.indexOf(callback)
       if (index >= 0) {