lecodes-cli 0.7.0 → 0.7.2

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