lecodes-cli 0.7.2 → 0.8.1

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) {
@@ -258,7 +266,7 @@ export type ClassStyles<T> = { [key: `$${string}`]: T & { duration?: number, del
 
 // 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
@@ -276,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
@@ -299,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)
@@ -331,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
   }
@@ -380,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 {
@@ -388,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() }

package/runtime/sdk/ui/UIPopover.ts

@@ -0,0 +1,106 @@
+import { ModalElement, type UIModal, type UIModalStyle } from "./UIModal"
+import { Presentable } from "./presentable"
+import { device } from "../runtime/device"
+import type { BoundingClientRect, ChildrenFn, UINodeChild } from "./UINode"
+
+export type UIPopoverStyle = UIModalStyle
+
+/** What a popover can anchor to: any element (it reads `getBoundingClientRect()`), or a raw
+ *  `{x, y}` point — a long-press context menu anchors to the touch position. */
+export type UIPopoverAnchor = { getBoundingClientRect(): BoundingClientRect | null } | { x: number, y: number }
+
+const POPOVER_ANIM_MS = 120
+const ANCHOR_GAP = 4       // between the anchor's edge and the popover
+const VIEWPORT_MARGIN = 8  // minimum distance kept to every screen edge
+
+/**
+ * An anchored menu: a `UIModal` whose scrim is transparent (invisible but still intercepting —
+ * an outside tap dismisses, and nothing underneath can scroll while it's open) and whose
+ * position comes from the anchor passed to `show(anchor)`: below the anchor's left edge,
+ * flipped above when there's no room, clamped into the viewport. Position is computed once per
+ * show — anchored popovers don't follow their anchor. Backs dropdowns, context menus, and
+ * tooltips; create it **once** at module scope and reuse it.
+ */
+export interface UIPopover extends UIModal {
+  /** Position next to `anchor` (an element or an `{x, y}` point), attach to
+   *  `Presentable.current` (unless an owner was set via `attachTo`), and play the entrance
+   *  transition. Without an anchor the popover shows wherever its own style puts it. */
+  show(anchor?: UIPopoverAnchor): void,
+}
+
+export class PopoverElement extends ModalElement {
+  private _anchorRect?: { left: number, top: number, right: number, bottom: number }
+  private _placedLeft?: number
+  private _placedTop?: number
+
+  constructor(style: UIPopoverStyle, children: UINodeChild[] | ChildrenFn) {
+    super({ overlayColor: "transparent", ...style }, children)
+    this.transition({ opacity: 0, duration: POPOVER_ANIM_MS })
+    // The flip/clamp decision needs the popover's measured size, which exists only after the
+    // mount lays it out — so placement is corrected on layout, inside the entrance fade.
+    this.onLayout(({ width, height }) => this._place(width, height))
+  }
+
+  show(anchor?: UIPopoverAnchor): void {
+    if (anchor) {
+      const r = "getBoundingClientRect" in anchor
+        ? anchor.getBoundingClientRect()
+        : { left: anchor.x, top: anchor.y, right: anchor.x, bottom: anchor.y }
+      if (r) {
+        this._anchorRect = { left: r.left, top: r.top, right: r.right, bottom: r.bottom }
+        this._placedLeft = undefined
+        this._placedTop = undefined
+        // Preliminary spot (below, left-aligned) so the first paint is already close; _place
+        // refines it once the size is known.
+        this.style({ left: r.left, top: r.bottom + ANCHOR_GAP })
+      }
+    } else {
+      this._anchorRect = undefined   // unanchored show: the user's own style owns the position
+    }
+    // A menu belongs to the page it opened on: it hides with it and rides its transition. An
+    // explicit attachTo() owner (e.g. a scene HUD's popover) is respected.
+    if (!this._owner) this.attachTo(Presentable.current)
+    super.show()
+  }
+
+  private _place(width: number, height: number): void {
+    const anchor = this._anchorRect
+    if (!anchor || !this._open) return
+    const displayWidth = device.width, displayHeight = device.height   // 0 on hosts without a size
+    let left = anchor.left
+    let top = anchor.bottom + ANCHOR_GAP
+    if (displayWidth > 0) {
+      left = Math.min(left, displayWidth - width - VIEWPORT_MARGIN)
+      left = Math.max(left, VIEWPORT_MARGIN)
+    }
+    if (displayHeight > 0 && top + height > displayHeight - VIEWPORT_MARGIN) {
+      const above = anchor.top - ANCHOR_GAP - height
+      top = above >= VIEWPORT_MARGIN ? above : Math.max(VIEWPORT_MARGIN, displayHeight - VIEWPORT_MARGIN - height)
+    }
+    // Idempotence guard: hosts re-fire onLayout on recalc, and writing the same position would
+    // trigger another recalc — only write when the target actually moved.
+    if (this._placedLeft !== undefined && Math.abs(left - this._placedLeft) < 0.5
+      && this._placedTop !== undefined && Math.abs(top - this._placedTop) < 0.5) return
+    this._placedLeft = left
+    this._placedTop = top
+    this.style({ left, top })
+  }
+}
+
+export function UIPopover(): UIPopover;
+export function UIPopover(children: UINodeChild[] | ChildrenFn): UIPopover;
+export function UIPopover(style: UIPopoverStyle): UIPopover;
+export function UIPopover(style: UIPopoverStyle, children: UINodeChild[] | ChildrenFn): UIPopover;
+export function UIPopover(...args: [] | [UINodeChild[] | ChildrenFn | UIPopoverStyle] | [UIPopoverStyle, children: UINodeChild[] | ChildrenFn]): UIPopover {
+  if (args.length === 0) {
+    return new PopoverElement({}, [])
+  } else if (args.length === 1) {
+    if (Array.isArray(args[0]) || typeof args[0] === "function") {
+      return new PopoverElement({}, args[0])
+    } else {
+      return new PopoverElement(args[0], [])
+    }
+  } else {
+    return new PopoverElement(args[0], args[1])
+  }
+}