lecodes-cli 0.7.0 → 0.7.1

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