lecodes-cli 0.7.1 → 0.8.0

package/runtime/sdk/ui/UINode.ts

@@ -73,62 +73,63 @@ export type ScrollStyle = {
   scrollY?: "auto" | "all" | "none"
 }
 
-type UIValue = number | 
-  `${number}px` | 
-  `${number}vw` | 
-  `${number}vh` | 
-  `${number}vmin` | 
-  `${number}vmax` | 
-  `${number}em` | 
+type UIValue = number |
+  `${number}px` |
+  `${number}vw` |
+  `${number}vh` |
+  `${number}vmin` |
+  `${number}vmax` |
+  `${number}em` |
   `calc(${string})` |
   `min(${string})` |
   `max(${string})` |
   `${string}%` |
-  `clamp(${string})`
+  `clamp(${string})` |
+  `var(--${string})`
 
 export type PaddingStyle = {
-  paddingLeft?: UIValue | "safe-left" | "safe-left-comfort",
-  paddingTop?: UIValue | "safe-top" | "safe-top-comfort",
-  paddingRight?: UIValue | "safe-right" | "safe-right-comfort",
-  paddingBottom?: UIValue | "safe-bottom" | "safe-bottom-comfort",
-  padding?: UIValue | "safe-all" | "safe-all-comfort",
-  paddingHorizontal?: UIValue,
-  paddingVertical?: UIValue,
-
-  pl?: UIValue | "safe-left" | "safe-left-comfort",
-  pt?: UIValue | "safe-top" | "safe-top-comfort",
-  pr?: UIValue | "safe-right" | "safe-right-comfort",
-  pb?: UIValue | "safe-bottom" | "safe-bottom-comfort",
-  p?: UIValue | "safe-all" | "safe-all-comfort",
-  px?: UIValue,
-  py?: UIValue,
+  paddingLeft?: UIValue | "safe-left" | "comfort-left",
+  paddingTop?: UIValue | "safe-top" | "comfort-top",
+  paddingRight?: UIValue | "safe-right" | "comfort-right",
+  paddingBottom?: UIValue | "safe-bottom" | "comfort-bottom",
+  padding?: UIValue | "safe-all" | "comfort-all",
+  paddingHorizontal?: UIValue | "comfort-x",
+  paddingVertical?: UIValue | "comfort-y",
+
+  pl?: UIValue | "safe-left" | "comfort-left",
+  pt?: UIValue | "safe-top" | "comfort-top",
+  pr?: UIValue | "safe-right" | "comfort-right",
+  pb?: UIValue | "safe-bottom" | "comfort-bottom",
+  p?: UIValue | "safe-all" | "comfort-all",
+  px?: UIValue | "comfort-x",
+  py?: UIValue | "comfort-y",
 }
 
 
 
 export type MarginStyle = {
-  marginLeft?: UIValue | "auto" | "safe-left" | "safe-left-comfort",
-  marginTop?: UIValue | "auto" | "safe-top" | "safe-top-comfort",
-  marginRight?: UIValue | "auto" | "safe-right" | "safe-right-comfort",
-  marginBottom?: UIValue | "auto" | "safe-bottom" | "safe-bottom-comfort",
-  margin?: UIValue | "auto" | "safe-all" | "safe-all-comfort",
-  marginHorizontal?: UIValue | "auto",
-  marginVertical?: UIValue | "auto",
-
-  ml?: UIValue | "auto" | "safe-left" | "safe-left-comfort",
-  mt?: UIValue | "auto" | "safe-top" | "safe-top-comfort",
-  mr?: UIValue | "auto" | "safe-right" | "safe-right-comfort",
-  mb?: UIValue | "auto" | "safe-bottom" | "safe-bottom-comfort",
-  m?: UIValue | "auto" | "safe-all" | "safe-all-comfort",
-  mx?: UIValue | "auto",
-  my?: UIValue | "auto",
+  marginLeft?: UIValue | "auto" | "safe-left" | "comfort-left",
+  marginTop?: UIValue | "auto" | "safe-top" | "comfort-top",
+  marginRight?: UIValue | "auto" | "safe-right" | "comfort-right",
+  marginBottom?: UIValue | "auto" | "safe-bottom" | "comfort-bottom",
+  margin?: UIValue | "auto" | "safe-all" | "comfort-all",
+  marginHorizontal?: UIValue | "auto" | "comfort-x",
+  marginVertical?: UIValue | "auto" | "comfort-y",
+
+  ml?: UIValue | "auto" | "safe-left" | "comfort-left",
+  mt?: UIValue | "auto" | "safe-top" | "comfort-top",
+  mr?: UIValue | "auto" | "safe-right" | "comfort-right",
+  mb?: UIValue | "auto" | "safe-bottom" | "comfort-bottom",
+  m?: UIValue | "auto" | "safe-all" | "comfort-all",
+  mx?: UIValue | "auto" | "comfort-x",
+  my?: UIValue | "auto" | "comfort-y",
 }
 
 export type PositionStyle = {
-  top?: UIValue | `${number}%` | 'safe-top' | 'safe-top-comfort',
-  left?: UIValue | `${number}%` | 'safe-left' | 'safe-left-comfort',
-  bottom?: UIValue | `${number}%` | 'safe-bottom' | 'safe-bottom-comfort',
-  right?: UIValue | `${number}%` | 'safe-right' | 'safe-right-comfort',
+  top?: UIValue | `${number}%` | 'safe-top' | 'comfort-top',
+  left?: UIValue | `${number}%` | 'safe-left' | 'comfort-left',
+  bottom?: UIValue | `${number}%` | 'safe-bottom' | 'comfort-bottom',
+  right?: UIValue | `${number}%` | 'safe-right' | 'comfort-right',
   width?: UIValue | `${number}%` | "auto",
   height?: UIValue | `${number}%` | "auto",
   maxWidth?: UIValue | `${number}%` | "auto",
@@ -195,6 +196,7 @@ function styleFunction(this: any, newStyle: any) {
     this.name = newStyle.name
     delete newStyle.name
   }
+  if (newStyle) this._mapStyle?.(newStyle)
   const fns = extractBindings(this, newStyle)
   Object.assign(this._style, newStyle)
   if (this._id !== 0) {
@@ -220,10 +222,16 @@ const handler: ProxyHandler<any> = {
       createBinding(el, key, () => { el.style[key] = fn() })
       return true
     }
-    if (target._el._id !== 0) {
-      _creatorUI.updateStyle(target._el._id, key, value)
+    const el = target._el
+    if (el._mapStyle !== undefined) {
+      const mapped = { [key]: value }
+      el._mapStyle(mapped)
+      value = mapped[key]
     }
-    target._el._style[key] = value
+    if (el._id !== 0) {
+      _creatorUI.updateStyle(el._id, key, value)
+    }
+    el._style[key] = value
     return true
   },
   getOwnPropertyDescriptor(target, p) {
@@ -245,15 +253,20 @@ 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. 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.
+// 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 } }
 
 // 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
+// `UIScreen<false>` unassignable to `UIScreen<boolean>` (a navigator page), 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
@@ -271,13 +284,42 @@ export type OrientationStyles<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> = ((style: T & { duration?: number, delay?: number, layer?: number, commit?: boolean }) => R)
+// The options bag of animateTo/animateFrom: the target style plus flat meta keys. Meta keys are
+// stripped before the commit into _style and skipped by the hosts' style staging.
+export type AnimateStyle<R, T extends object> = ((style: T & {
+  /** Tween length in **milliseconds** (default 225). */
+  duration?: number,
+  /** Wait before starting, in **milliseconds**. A looping animation delays once, not per cycle. */
+  delay?: number,
+  /** Escape hatch: target an internal style layer (the onPressed/orientation mechanism). Not part of the supported surface. */
+  layer?: number,
+  /** `false` = animate without writing the targets into the element's style (e.g. a fade-out right before `.hide()`). */
+  commit?: boolean,
+  /** Repeat the animation: `true` = forever, a number = that many cycles. A looping animation is an
+   *  effect, not a state change — it never commits, and the element ends back at its base style.
+   *  The loop stops when a later `animateTo`/`animateFrom` runs on the element or it leaves the screen. */
+  loop?: boolean | number,
+  /** `"ping-pong"` (default) animates there and back each cycle — no jump. `"restart"` snaps back and
+   *  replays forward — for full-turn spinners (`transform: "rotate(360deg)"`) and shimmers. Only meaningful with `loop`. */
+  loopMode?: "restart" | "ping-pong",
+}) => R)
+
+/** Meta keys of the animateTo/animateFrom options bag — everything that is not a style target. */
+const ANIMATE_META = new Set(["duration", "delay", "layer", "commit", "loop", "loopMode"])
 
 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
 
 export type OnLayoutCallback = (layout: { left: number, top: number, width: number, height: number }) => void
 
+// Web-DOMRect shape on purpose (getBoundingClientRect priors must hold): all eight fields, with
+// right/bottom/x/y derived SDK-side so hosts only report [left, top, width, height].
+export type BoundingClientRect = {
+  x: number, y: number,
+  left: number, top: number, right: number, bottom: number,
+  width: number, height: number,
+}
+
 export class Element<T extends string> {
   readonly type: T
   /** Author-given semantic name (LeCodes `name`) — see BaseStyle.name. Extracted from the options
@@ -294,12 +336,21 @@ export class Element<T extends string> {
    *  is the effect's only strong owner, so discarding a subtree lets its bindings collect with it. */
   _fx?: Map<string, any>
 
+  /** @internal Per-subclass style normalization (SDK-name → wire-name, e.g. UIInput's
+   *  `type: "phone"` → `"tel"`), mutating the style in place before it is stored or sent. Runs on
+   *  every entry point: the first-arg style, `.style()`, and single-key `el.style.k =` writes. */
+  _mapStyle?(style: any): void
+
+  // Per-type default styles are inlined at each component's construction site (spread UNDER the
+  // user's style — e.g. UIRow's `flexDirection: "row"`), so every node reaches the host with
+  // explicit values and hosts keep no per-type style opinions of their own.
   constructor(type: T, style: any) {
     this.type = type
     if (style && typeof style.name === "string" && style.name.length > 0) {
       this.name = style.name
       delete style.name
     }
+    if (style) this._mapStyle?.(style)
     this._style = style
     if (style) {
       const fns = extractBindings(this, style)
@@ -326,8 +377,12 @@ export class Element<T extends string> {
 
   animateTo(style: any): this{
     _creatorUI.animateTo(this._id, style)
-    if (style.commit !== false) {
-      Object.assign(this._style, style)
+    // A loop is an effect, not a state change — looping animations never commit. Meta keys
+    // (duration/delay/…) stay out of the stored style.
+    if (style.commit !== false && !style.loop) {
+      for (const key in style) {
+        if (!ANIMATE_META.has(key)) this._style[key] = style[key]
+      }
     }
     return this
   }
@@ -341,7 +396,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) {
@@ -372,7 +430,7 @@ export class Element<T extends string> {
   }
 
   protected ll?: OnLayoutCallback[]
-  onLayout(onLayout: OnLayoutCallback): this { 
+  onLayout(onLayout: OnLayoutCallback): this {
     if (this.ll) {
       this.ll.push(onLayout)
     } else {
@@ -380,6 +438,19 @@ export class Element<T extends string> {
     }
     return this
   }
+
+  /** Absolute rect in device space — the space `UIWidget` positions in and touch events report
+   *  `clientX`/`clientY` in — including scroll offsets, read live at call time (unlike `onLayout`,
+   *  whose coordinates are parent-relative and go stale when an ancestor scrolls). `null` before
+   *  the element is mounted and on hosts without the bridge read. Anchor popovers position-once
+   *  at open; don't poll per frame. */
+  getBoundingClientRect(): BoundingClientRect | null {
+    if (this._id === 0) return null
+    const rect = _creatorUI.getBoundingClientRect?.(this._id)
+    if (!rect) return null
+    const [left, top, width, height] = rect
+    return { x: left, y: top, left, top, right: left + width, bottom: top + height, width, height }
+  }
 }
 
 // ---- reactive children --------------------------------------------------------------------------

package/runtime/sdk/ui/UIPager.ts

@@ -0,0 +1,297 @@
+import { ContainerElement, type AnimateStyle, type BaseStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Style } from "./UINode"
+import type { UIScreen } from "./UIScreen"
+
+// UIPager — the system's ONE screen-navigation element (docs/pager-component-plan.md): sibling
+// tabs that swipe natively side to side, with a native navigation STACK per tab. `push` opens a
+// screen on top of the currently open tab (within the pager); `pop` / the interactive edge
+// back-swipe unwinds it; `replace` swaps the top. A pager with one tab is a plain stack.
+//
+// Reachable from any scope as a global: `UIPager.push(screen)` pushes onto the pager that owns
+// the current screen (UIPager.current) — no reference threading into child screens. Router stays
+// distinct: `Router.push` opens ON TOP of the pager (bars and all), the pager navigates within.
+//
+// Wire node type "pager": children are separate layout roots (full UIScreens), NOT yoga children.
+// The wire shape is `children` flat in TAB-MAJOR order (tab 0's stack root→top, then tab 1's, …)
+// partitioned by `_lens` (per-tab stack lengths) with `_index` = selected tab. State is mutated
+// BEFORE each command, so the host reconciles against the node; commands only name the native
+// transition to play. Host-driven changes come back via `_hostDidSelect` / `_hostDidPop` — both
+// idempotent no-ops when the logical state already matches.
+
+/** Styles a pager accepts — layout box + drawable (background, borders, …). Pages style
+ *  themselves; the pager only owns its own slot. */
+export type UIPagerStyle = ElementStyle & DrawableStyle
+
+/** The pagers whose screen is currently visible, outermost → innermost. `UIPager.current` is the
+ *  last (innermost). Maintained by each owned screen's onOpen/onClose via _activate/_deactivate. */
+const _activeStack: PagerElement[] = []
+
+/**
+ * The screen-navigation element: sibling **tabs** that swipe natively side to side, each with its
+ * own navigation **stack**. `push` opens a screen on top of the current tab (within the pager);
+ * `pop` / the native edge back-swipe unwinds it. A one-tab pager is a plain navigation stack.
+ *
+ * ```ts
+ * const pager = UIPager([ HomeScreen(), ProfileScreen() ])   // two tabs, side by side
+ * Router.init(UIScreen([ pager.style({ flexGrow: 1 }), tabBar ]))
+ *
+ * // from anywhere inside a hosted screen — no reference threading:
+ * UIPager.push(PostScreen(id))
+ * ```
+ *
+ * To open something over *everything* (above bars, above the pager), use `Router.push` instead.
+ */
+export interface UIPager {
+  readonly type: "pager",
+  style: Style<this, UIPagerStyle>,
+  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>,
+  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>,
+
+  /** Switch to tab `index`. **Instant by default** — the tab-bar convention (tabs are parallel
+   *  modes, not neighbors); pass `animated: true` for the direction-aware slide of top-tab /
+   *  pager UIs. Out-of-range and same-index calls are no-ops. Tabs keep their stacks: selecting
+   *  away and back restores the tab exactly where it was, pushed screens included. */
+  select(index: number, animated?: boolean): this,
+  /** The selected tab index (0-based). */
+  readonly index: number,
+  /** Fires when the selected tab changes and has settled — a user swipe or `select()`. */
+  onSelect(callback: (index: number) => void): this,
+
+  /** Push `screen` on top of the **current tab** — slides in natively; the edge back-swipe (or
+   *  `pop()`) removes it. Other tabs are unaffected. */
+  push(screen: UIScreen): this,
+  /** Pop the current tab's top screen (no-op at the tab root — the root never pops). The
+   *  programmatic twin of the native edge back-swipe. */
+  pop(): this,
+  /** Unwind the current tab back to its root screen in one step. */
+  popToRoot(): this,
+  /** Swap the current tab's top screen for `screen` without growing the stack (at depth 1 this
+   *  swaps the tab's root). */
+  replace(screen: UIScreen): this,
+  /** The current tab's screens, root → top (read-only snapshot). */
+  readonly stack: UIScreen[],
+  /** The current tab's stack depth — 1 means only the root. While `depth > 1`, swiping between
+   *  tabs is disabled (the horizontal gesture belongs to the back-swipe). */
+  readonly depth: number,
+  /** Fires when the current tab's depth changes — push, pop, replace, or a back-swipe. */
+  onChange(callback: (depth: number) => void): this,
+
+  onLayout(onLayout: OnLayoutCallback): this,
+  getBoundingClientRect(): BoundingClientRect | null,
+
+  setClass(name: string, enabled: boolean): this,
+  toggleClass(name: string): this,
+  hasClass(name: string): boolean,
+  bindClass(name: string, fn: () => boolean): this,
+}
+
+export class PagerElement extends ContainerElement<"pager"> {
+  /** Per-tab stack lengths — partitions the flat tab-major `children`. Named `_*` so chisel
+   *  keeps it (the host reads it live). */
+  _lens: number[]
+  /** Selected tab. */
+  _index = 0
+  // >0 while a screen owned by this pager is the visible one (its onOpen fired, onClose hasn't).
+  // Only one owned screen is ever open, so this is effectively 0/1 — the count only makes the
+  // transient during a transition's old-close/new-open pair order-independent.
+  _openCount = 0
+  private scl: ((index: number) => void)[] = []   // onSelect listeners
+  private ncl: ((depth: number) => void)[] = []   // onChange listeners
+
+  constructor(style: UIPagerStyle | null, tabs: UIScreen[]) {
+    super("pager", style ?? {}, tabs as any)
+    this._lens = tabs.map(() => 1)
+    for (const s of this.children) this._track(s)
+  }
+
+  /** Start offset of tab `i`'s segment in the flat `children`. */
+  private _offset(i: number): number {
+    let off = 0
+    for (let t = 0; t < i; t++) off += this._lens[t]
+    return off
+  }
+
+  get index(): number {
+    return this._index
+  }
+  get stack(): UIScreen[] {
+    const off = this._offset(this._index)
+    return this.children.slice(off, off + (this._lens[this._index] ?? 0))
+  }
+  get depth(): number {
+    return this._lens[this._index] ?? 0
+  }
+
+  onSelect(callback: (index: number) => void): this {
+    this.scl.push(callback)
+    return this
+  }
+  onChange(callback: (depth: number) => void): this {
+    this.ncl.push(callback)
+    return this
+  }
+
+  select(index: number, animated = false): this {
+    if (index < 0 || index >= this._lens.length || index === this._index) return this
+    this._index = index
+    if (this._id !== 0) _creatorUI.command(this, "select", animated)
+    this._emitSelect()
+    return this
+  }
+
+  push(screen: UIScreen): this {
+    if (this._lens.length === 0) {
+      console.warn("UIPager.push: pager has no tabs")
+      return this
+    }
+    this.children.splice(this._offset(this._index) + this._lens[this._index], 0, screen)
+    this._lens[this._index]++
+    this._track(screen)
+    if (this._id !== 0) _creatorUI.command(this, "push")
+    this._emitChange()
+    return this
+  }
+
+  pop(): this {
+    if ((this._lens[this._index] ?? 0) <= 1) return this
+    this.children.splice(this._offset(this._index) + this._lens[this._index] - 1, 1)
+    this._lens[this._index]--
+    if (this._id !== 0) _creatorUI.command(this, "pop")
+    this._emitChange()
+    return this
+  }
+
+  popToRoot(): this {
+    const len = this._lens[this._index] ?? 0
+    if (len <= 1) return this
+    this.children.splice(this._offset(this._index) + 1, len - 1)
+    this._lens[this._index] = 1
+    if (this._id !== 0) _creatorUI.command(this, "popToRoot")
+    this._emitChange()
+    return this
+  }
+
+  replace(screen: UIScreen): this {
+    if (this._lens.length === 0) {
+      console.warn("UIPager.replace: pager has no tabs")
+      return this
+    }
+    this.children[this._offset(this._index) + this._lens[this._index] - 1] = screen
+    this._track(screen)
+    if (this._id !== 0) _creatorUI.command(this, "replace")
+    this._emitChange()
+    return this
+  }
+
+  // Host-driven tab change (committed swipe): the native pager already moved — sync the logical
+  // index + fire onSelect. Named `_*` so chisel keeps it (hosts call it).
+  _hostDidSelect(index: number): void {
+    if (index < 0 || index >= this._lens.length || index === this._index) return
+    this._index = index
+    this._emitSelect()
+  }
+
+  // Host-driven pop on the current tab (interactive edge back-swipe): the native stack already
+  // popped — sync the logical stack + fire onChange. Idempotent, safe after every transition.
+  _hostDidPop(depth: number): void {
+    if (depth < 1) depth = 1
+    const len = this._lens[this._index] ?? 0
+    if (depth >= len) return
+    this.children.splice(this._offset(this._index) + depth, len - depth)
+    this._lens[this._index] = depth
+    this._emitChange()
+  }
+
+  private _emitSelect(): void {
+    const i = this._index
+    for (const cb of this.scl) cb(i)
+  }
+  private _emitChange(): void {
+    const d = this._lens[this._index] ?? 0
+    for (const cb of this.ncl) cb(d)
+  }
+
+  // Register a screen for `current` tracking: while a screen owned by this pager is the visible
+  // top, this pager is active. The hook reads screen._pagerOwner LIVE (not a captured `this`), so
+  // re-homing a screen into another pager activates the right one.
+  private _track(screen: any): void {
+    screen._pagerOwner = this
+    if (!screen._pagerHooked) {
+      screen._pagerHooked = true
+      screen.onOpen(() => screen._pagerOwner?._activate())
+      screen.onClose(() => screen._pagerOwner?._deactivate())
+    }
+  }
+  _activate(): void {
+    if (++this._openCount === 1 && _activeStack.indexOf(this) < 0) _activeStack.push(this)
+  }
+  _deactivate(): void {
+    if (--this._openCount <= 0) {
+      this._openCount = 0
+      const i = _activeStack.indexOf(this)
+      if (i >= 0) _activeStack.splice(i, 1)
+    }
+  }
+}
+
+const isScreenArg = (v: any): boolean => v != null && typeof v === "object" && v.type === "screen"
+
+/** Callable factory + ambient statics. The name `UIPager` is a value (this factory) and a type
+ *  (the instance interface above) — a standard value/type merge. */
+interface UIPagerConstructor {
+  /** One tab — a plain navigation stack rooted at `root` (push/pop, no tab swiping). */
+  (root: UIScreen): UIPager
+  /** Sibling tabs, one per screen, in order — swipe (or `select`) between them. Tabs are fixed
+   *  at construction; each starts as its own one-screen stack. */
+  (tabs: UIScreen[]): UIPager
+  /** Styled pager + content (a single root screen or an array of tab screens). */
+  (style: UIPagerStyle, content: UIScreen | UIScreen[]): UIPager
+  /** The pager that owns the currently visible screen, or `null` when the visible screen isn't
+   *  hosted by one. With pagers nested inside pages, resolves to the **innermost** — so ambient
+   *  calls act on the pager the user is actually looking at. */
+  readonly current: UIPager | null
+  /** `UIPager.current.push(screen)` — push onto the pager owning the visible screen, no
+   *  reference threading. No-op with a console warning when there is no current pager. */
+  push(screen: UIScreen): void
+  /** `UIPager.current.pop()` — pop the visible pager's current tab (no-op at the tab root, or
+   *  with a warning when there is no current pager). */
+  pop(): void
+  /** `UIPager.current.popToRoot()` — unwind the visible pager's current tab to its root. */
+  popToRoot(): void
+}
+
+function pagerFactory(...args: any[]): UIPager {
+  if (args.length === 1) {
+    const a = args[0]
+    if (Array.isArray(a)) return new PagerElement(null, a) as unknown as UIPager
+    if (isScreenArg(a)) return new PagerElement(null, [a]) as unknown as UIPager
+    return new PagerElement(a, []) as unknown as UIPager
+  }
+  const content = args[1]
+  return new PagerElement(args[0] ?? null, Array.isArray(content) ? content : content ? [content] : []) as unknown as UIPager
+}
+
+/**
+ * Create a pager — THE screen-navigation element: an array of screens becomes swipeable sibling
+ * tabs, a single screen becomes a plain stack. Navigate within it via `pager.push/pop/replace`
+ * (per-tab) and `pager.select(i)` (between tabs), or from any child screen via the ambient
+ * `UIPager.push` / `UIPager.pop` / `UIPager.current`. Pages are full `UIScreen`s (own
+ * `onOpen`/`onClose`, `makeScrollable()`); give the pager `flexGrow: 1` or a size so it doesn't
+ * collapse. `Router` stays the way to open a destination ON TOP of the pager.
+ */
+export const UIPager = pagerFactory as unknown as UIPagerConstructor
+
+const _resolveCurrent = (): UIPager | null => {
+  const cur = _activeStack[_activeStack.length - 1]
+  if (!cur) {
+    console.warn("UIPager.push/pop: no active pager on the current screen")
+    return null
+  }
+  return cur as unknown as UIPager
+}
+
+Object.defineProperty(UIPager, "current", {
+  get: () => (_activeStack[_activeStack.length - 1] ?? null) as unknown as UIPager | null,
+})
+;(UIPager as any).push = (screen: UIScreen) => { _resolveCurrent()?.push(screen) }
+;(UIPager as any).pop = () => { _resolveCurrent()?.pop() }
+;(UIPager as any).popToRoot = () => { _resolveCurrent()?.popToRoot() }