lecodes-sdk 0.19.0

package/dist/types/ui/UINode.d.ts

@@ -0,0 +1,363 @@
+import type { FetchResponse } from "../runtime/fetch";
+export interface UINode {
+    readonly type: string;
+    /** Author-given semantic name (a stable selector for tests + AI review feedback). */
+    readonly name?: string;
+    style: Style<this, any>;
+    /** Style-class proxy — read/set/toggle/bind the `$`-classes declared in `.style()`. See {@link Classes}. */
+    readonly class: Classes<this>;
+}
+/** A child slot value: a node, or falsy (conditional rendering — falsy entries are skipped). */
+export type UINodeChild = UINode | null | undefined | false;
+/** A factory child argument: a node (or falsy for conditionals), or an array of them — arrays are
+ *  flattened one level at the argument position, so `UIColumn(header, items.map(row), footer)`
+ *  needs no spread. */
+export type UIChildArg = UINodeChild | UINodeChild[];
+/** A color: CSS-style string (`"#1c1c1e"`, `"rgba(0,0,0,0.5)"`, `"var(--primaryColor)"`) or
+ *  packed number; `null` clears. */
+export type Color = number | string | null;
+/** Style props every element accepts. */
+export type BaseStyle = {
+    opacity?: number | `${number}`;
+    transform?: string | null;
+    /** Pivot of `transform` (CSS `transform-origin` subset): one or two values, each a keyword
+     *  (`left`/`center`/`right`, `top`/`center`/`bottom`), a percentage of the box, or a px length
+     *  (bare numbers are px). One value sets x, y stays `50%`. Default `"50% 50%"` = the centre. */
+    transformOrigin?: string | null;
+    backgroundColor?: Color | null;
+    bgColor?: Color | null;
+    overflow?: "visible" | "hidden";
+    boxSizing?: "border-box" | "content-box";
+    /**
+     * Author-given semantic name — a stable selector for tests and for marking elements in the AI
+     * code-review feedback loop. NOT a style: it's extracted at construction (never sent to the layout
+     * engine) and surfaced on the node + in the renderer's serialized output. Available on every element.
+     */
+    name?: string;
+};
+/** Painted-box props: background, gradient, border, radius. */
+export type DrawableStyle = {
+    backgroundImage?: FetchResponse | File | string | null;
+    bgGradient?: string;
+    backgroundGradient?: string;
+    bgImage?: FetchResponse | File | string | null;
+    backgroundSize?: "cover" | "contain" | "tile";
+    bgSize?: "cover" | "contain" | "tile";
+    border?: string | number | null;
+    borderWidth?: number;
+    borderColor?: Color;
+    borderLeft?: string | number | null;
+    borderLeftWidth?: number;
+    borderLeftColor?: Color;
+    borderTop?: string | number | null;
+    borderTopWidth?: number;
+    borderTopColor?: Color;
+    borderRight?: string | number | null;
+    borderRightWidth?: number;
+    borderRightColor?: Color;
+    borderBottom?: string | number | null;
+    borderBottomWidth?: number;
+    borderBottomColor?: Color;
+    borderRadius?: UIValue | string;
+    borderTopLeftRadius?: UIValue;
+    borderTopRightRadius?: UIValue;
+    borderBottomLeftRadius?: UIValue;
+    borderBottomRightRadius?: UIValue;
+    pointerEvents?: "all" | "none";
+};
+/** Flex-layout props of a container (how it lays out its children). */
+export type ContainerStyle = {
+    flexDirection?: "row" | "column";
+    justifyContent?: "flex-start" | "center" | "flex-end" | "space-between" | "space-evenly";
+    alignItems?: "flex-start" | "center" | "flex-end" | "stretch";
+    gap?: UIValue;
+    flexWrap?: "nowrap" | "wrap" | "wrap-reverse";
+};
+/** A dimension: a number (logical px) or a CSS-style unit / function string. */
+type UIValue = number | `${number}px` | `${number}vw` | `${number}vh` | `${number}vmin` | `${number}vmax` | `${number}em` | `calc(${string})` | `min(${string})` | `max(${string})` | `${string}%` | `clamp(${string})` | `var(--${string})`;
+/** Padding, with `p`/`px`/`pl`… shorthands. `safe-*` insets by the device safe area,
+ *  `comfort-*` by the theme's comfort knobs (max of both). */
+export type PaddingStyle = {
+    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";
+};
+/** Margin, with `m`/`mx`/`ml`… shorthands; `"auto"` centers/pushes like CSS. */
+export type MarginStyle = {
+    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";
+};
+/** Box position (for `position: "absolute"`) and size constraints. */
+export type PositionStyle = {
+    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';
+    /** Shorthand for all four edges at one value. A longhand (`top`, `left`, …) overrides it. */
+    inset?: UIValue | `${number}%` | "auto";
+    width?: UIValue | `${number}%` | "auto";
+    height?: UIValue | `${number}%` | "auto";
+    maxWidth?: UIValue | `${number}%` | "auto";
+    maxHeight?: UIValue | `${number}%` | "auto";
+    minWidth?: UIValue | `${number}%` | "auto";
+    minHeight?: UIValue | `${number}%` | "auto";
+};
+/** The base style of every element: box + flex-child props. */
+export type ElementStyle = PaddingStyle & MarginStyle & BaseStyle & PositionStyle & {
+    position?: "absolute" | "static" | "relative";
+    aspectRatio?: number;
+    flex?: number | string;
+    flexGrow?: number;
+    flexShrink?: number;
+    flexBase?: UIValue | `${number}%` | "auto";
+    alignSelf?: "flex-start" | "center" | "flex-end" | "stretch";
+    display?: "none" | "flex";
+};
+/** Typography props. */
+export type TextStyle = {
+    textAlign?: "start" | "center" | "end" | "left" | "right";
+    fontFamily?: string;
+    fontSize?: UIValue;
+    lineHeight?: UIValue | "normal";
+    fontWeight?: number | `${number}` | "normal" | "bold";
+    fontStyle?: "normal" | "italic";
+    color?: Color;
+    textDecoration?: "underline" | "line-through" | "none";
+    letterSpacing?: UIValue;
+    /** Cap the text at N lines; the box is measured to the clamped height. 0 / omitted = unbounded. */
+    lineClamp?: number;
+    /** How a clamped line ends. Only meaningful together with `lineClamp`. Default "ellipsis". */
+    textOverflow?: "ellipsis" | "clip";
+};
+/** Reactive style input: every primitive-valued prop also accepts a `() => value` binding that
+ *  re-applies when a signal it read changes. Nested state blocks (onPressed, onLandscape, …) stay
+ *  static — bindings are extracted at the top level only. */
+export type Reactive<T> = {
+    [K in keyof T]: NonNullable<T[K]> extends object ? T[K] : T[K] | (() => T[K]);
+};
+/** User-defined style classes: any `$`-prefixed key in `.style()` declares a state block toggled
+ *  from code via the `el.class` proxy; `duration`/`delay` animate the swap. 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 (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.
+ *
+ *  Instantiated with the node's FULL style `T` — a class block accepts everything the node's
+ *  `.style()` does, like `onLandscape`. Narrowing it wrongly rejects valid props such as
+ *  `$active: { color }`; guarded by tests/ui-types.test.ts. */
+export type ClassStyles<T> = {
+    [key: `$${string}`]: T & {
+        duration?: number;
+        delay?: number;
+    };
+};
+/** Value accepted by a `el.class` write: a boolean sets the class, a `() => boolean` binds it —
+ *  the class then tracks the signals the function reads (re-evaluated on change). Reads through
+ *  the proxy always return a plain boolean, never the bound function. */
+export type ClassValue = boolean | (() => boolean);
+/** The `el.class` proxy — the runtime switch for `$`-class blocks declared in `.style()`
+ *  (see {@link ClassStyles}). One surface, mirroring `el.style`:
+ *
+ *  ```ts
+ *  el.class.checked                    // read: is it active on THIS element? → boolean
+ *  el.class.checked = true             // activate (false deactivates)
+ *  el.class.open = !el.class.open      // toggle
+ *  el.class.done = () => todo.done.value          // reactive binding (signals)
+ *  el.class({ checked: true, done: () => … })     // batch form — returns the element, chainable
+ *  ```
+ *
+ *  Class names are accepted with or without the declaration-site `$` prefix. `R` is the concrete
+ *  node type, so the batch form chains like `.style()`.
+ *
+ *  Typing note: property access is `any` because an index signature can't give reads (`boolean`)
+ *  and writes ({@link ClassValue}) different types — the batch form is the fully typed path;
+ *  single-key writes are runtime-coerced with `!!`. */
+export type Classes<R> = ((classes: Record<string, ClassValue>) => R) & {
+    [key: string]: any;
+};
+/** Members every UI element shares — element interfaces extend this so docs and types live in one
+ *  place. `S` is the element's style object; `A` is the subset `animateTo` accepts (defaults to `S`). */
+export interface UIElementBase<S extends object, A extends object = S> {
+    /** Style: `.style({...})` merges (chainable); `el.style.key = v` writes one prop, a `() => v`
+     *  value binds it to signals — see {@link Style}. */
+    style: Style<this, S>;
+    /** Tween to the target style — meta keys `duration`/`delay`/`loop`/…, see {@link AnimateStyle}. */
+    animateTo: AnimateStyle<this, A>;
+    /** Tween from the given style to the current one (entrance animations). */
+    animateFrom: AnimateStyle<this, A>;
+    /** Fires after every layout pass with the parent-relative box. */
+    onLayout(onLayout: OnLayoutCallback): this;
+    /** Absolute rect in device space, read live (includes scroll); `null` before mount. */
+    getBoundingClientRect(): BoundingClientRect | null;
+    /** Style-class proxy — read `el.class.checked`, set `el.class.checked = true`, toggle with
+     *  `!el.class.checked`, bind `el.class.done = () => sig.value`, batch/chain `el.class({ … })`.
+     *  Classes cascade to descendants. See {@link Classes}. */
+    readonly class: Classes<this>;
+}
+/** {@link UIElementBase} plus the child-management surface every container shares. */
+export interface UIContainerBase<S extends object, A extends object = S> extends UIElementBase<S, A> {
+    /** Append children. */
+    append(...nodes: UINodeChild[]): this;
+    /** Insert children at `index`. */
+    insert(index: number, ...nodes: UINodeChild[]): this;
+    /** Remove (unmount) the given children. */
+    remove(...nodes: UINodeChild[]): this;
+    /** Replace all children — an array, or a function for reactive children. */
+    setContent(nodes: UINodeChild[] | ChildrenFn): this;
+    /** The children array — mutate via `append`/`insert`/`remove`/`setContent`. */
+    readonly children: UINodeChild[];
+}
+/** Orientation state blocks — override props applied only in landscape / portrait (like a
+ *  `$`-class, keyed by device orientation instead of `el.class`). Same full-`T` rule as class
+ *  blocks. */
+export type OrientationStyles<T> = {
+    onLandscape?: T;
+    onPortrait?: T;
+    /** @deprecated Misspelling of `onPortrait` (no second "r"). Kept so existing projects and published
+     *  bundles keep working — hosts still honour it — but new code should use `onPortrait`. */
+    onPortait?: T;
+};
+export type StyleFn<R, T extends object> = ((style: Reactive<T> & OrientationStyles<T> & ClassStyles<T>) => R);
+/** The `el.style` surface: callable — `.style({...})` merges and returns the element for
+ *  chaining — and per-key readable/writable (`el.style.opacity = 0.5`; a `() => value` write
+ *  installs a reactive binding). */
+export type Style<R, T extends object> = StyleFn<R, T> & T & OrientationStyles<T> & ClassStyles<T>;
+/** The `animateTo`/`animateFrom` surface: target style props plus the flat meta keys below
+ *  (stripped before the commit into the element's style). */
+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);
+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;
+/** `onLayout` payload — the node's box in PARENT-relative coordinates. */
+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 — 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 declare class Element<T extends string> {
+    readonly type: T;
+    /** Author-given semantic name (LeCodes `name`) — see BaseStyle.name. Extracted from the options
+     *  object so it never reaches the layout engine; the renderer reads it off the node. */
+    readonly name?: string;
+    protected _style: any;
+    protected _id: number;
+    protected _styleProxy: any;
+    protected _appear: any;
+    protected _disappear: any;
+    constructor(type: T, style: any);
+    get style(): any;
+    /** Tween to the target style and commit it (unless `commit: false` or looping — a loop is an
+     *  effect, not a state change). Meta keys: `duration`/`delay`/`loop`/… — see {@link AnimateStyle}. */
+    animateTo(style: any): this;
+    /** Tween FROM the given style to the element's current one (entrance animations). */
+    animateFrom(style: any): this;
+    protected _classProxy?: any;
+    /** Style-class control — flips the `$`-class blocks declared in `.style()`. One proxy, same
+     *  contract as `el.style`:
+     *
+     *  - `el.class.checked` — read: is the class active on THIS element? → `boolean`
+     *  - `el.class.checked = true` / `= false` — activate / deactivate
+     *  - `el.class.open = !el.class.open` — toggle
+     *  - `el.class.done = () => todo.done.value` — reactive: the class tracks the signals the
+     *    function reads; a later write to the same class (plain or function) replaces the binding
+     *  - `el.class({ checked: true, done: () => … })` — batch form, returns the element (chainable)
+     *
+     *  Names are accepted with or without the leading `$`. A class set on an element 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. Reads reflect only this element's own classes;
+     *  there is no opt-out below an active ancestor. `Object.keys(el.class)` lists the active names. */
+    get class(): any;
+    protected ll?: OnLayoutCallback[];
+    /** Observe layout: fires after every host layout pass with the parent-relative box. */
+    onLayout(onLayout: OnLayoutCallback): 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;
+}
+/** Reactive children: re-runs when a signal it read changes; the result is reconciled against
+ *  the mounted children (kept nodes stay mounted, state intact). */
+export type ChildrenFn = () => UINodeChild[];
+/**
+ * Compiler-emitted memoized map for reactive children. The chisel `reactiveUi` pass rewrites
+ * `list.map(fn)` inside a children binding to `__uiMap(list, fn, "<file>:<offset>")`, so unchanged
+ * items keep their element identity across re-runs (the reconciler then leaves them mounted).
+ * Cache: per (binding owner, call-site slot), keyed by item reference; duplicate items consume
+ * cached nodes in order. Outside a children binding, for non-array inputs, or for non-element
+ * results it behaves exactly like Array.prototype.map — a wrong rewrite can't change behavior.
+ */
+export declare function __uiMap(list: any, render: (item: any, index: number) => any, slot: string): any[];
+export declare class ContainerElement<T extends string> extends Element<T> {
+    children: any[];
+    constructor(type: T, style: any, children: any[] | ChildrenFn);
+    /** Append children (falsy entries are kept in the array but never mounted). */
+    append(...nodes: UINodeChild[]): this;
+    /** Insert children at `index` of the children array. */
+    insert(index: number, ...nodes: UINodeChild[]): this;
+    /** Remove (unmount) the given children. */
+    remove(...nodesToDelete: UINode[]): this;
+    /** Replace all children — a plain array, or a function for reactive children. */
+    setContent(children: UINodeChild[] | ChildrenFn): this;
+}
+export {};

package/dist/types/ui/UIPager.d.ts

@@ -0,0 +1,123 @@
+import { ContainerElement, type BaseStyle, type ChildrenFn, type DrawableStyle, type ElementStyle, type UIElementBase, type UINodeChild } from "./UINode";
+import type { UIScreen } from "./UIScreen";
+/** 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 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 extends UIElementBase<UIPagerStyle, DrawableStyle & BaseStyle> {
+    readonly type: "pager";
+    /** Replace the pager's tabs — one screen per tab, in order. Every tab becomes a fresh
+     *  one-screen stack (pushed screens are dropped) and the selection is clamped into range;
+     *  screens that were already tabs keep their state. Pass a function for reactive tabs. */
+    setContent(tabs: UIScreen[] | (() => UIScreen[])): this;
+    /** 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;
+}
+export declare 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: number;
+    _openCount: number;
+    private scl;
+    private ncl;
+    constructor(style: UIPagerStyle | null, tabs: UIScreen[]);
+    /** Start offset of tab `i`'s segment in the flat `children`. */
+    private _offset;
+    get index(): number;
+    get stack(): UIScreen[];
+    get depth(): number;
+    onSelect(callback: (index: number) => void): this;
+    onChange(callback: (depth: number) => void): this;
+    select(index: number, animated?: boolean): this;
+    push(screen: UIScreen): this;
+    pop(): this;
+    popToRoot(): this;
+    replace(screen: UIScreen): this;
+    private _rebuild;
+    setContent(children: UINodeChild[] | ChildrenFn): this;
+    append(...nodes: UINodeChild[]): this;
+    insert(index: number, ...nodes: UINodeChild[]): this;
+    remove(...nodesToDelete: UIScreen[]): this;
+    _reconcile(next: UINodeChild[]): void;
+    _hostDidSelect(index: number): void;
+    _hostDidPop(depth: number): void;
+    private _emitSelect;
+    private _emitChange;
+    private _track;
+    _activate(): void;
+    _deactivate(): void;
+}
+/** 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 {
+    /** Tabs — each argument is a screen or an array of screens (arrays flatten one level, falsy
+     *  entries are skipped). One screen → a plain navigation stack rooted at it (push/pop, no tab
+     *  swiping); several → swipeable sibling tabs, fixed at construction, each starting as its own
+     *  one-screen stack. */
+    (...tabs: (UIScreen | UIScreen[] | false | null | undefined)[]): UIPager;
+    /** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+    (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;
+}
+/**
+ * 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`); 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 declare const UIPager: UIPagerConstructor;
+export {};

package/dist/types/ui/UIPopover.d.ts

@@ -0,0 +1,39 @@
+import { ModalElement, type UIModal, type UIModalStyle } from "./UIModal";
+import { type BoundingClientRect, type ChildrenFn, type UIChildArg, type 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;
+};
+/**
+ * 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 declare class PopoverElement extends ModalElement {
+    private _anchorRect?;
+    private _placedLeft?;
+    private _placedTop?;
+    constructor(style: UIPopoverStyle, children: UINodeChild[] | ChildrenFn);
+    show(anchor?: UIPopoverAnchor): void;
+    private _place;
+}
+/** Create an anchored popover (see {@link UIPopover}) — create once at module scope, then
+ *  `show(anchor)` next to an element or `{x, y}` point. Same argument forms as `UIColumn`. */
+export declare function UIPopover(...children: UIChildArg[]): UIPopover;
+export declare function UIPopover(children: UINodeChild[] | ChildrenFn): UIPopover;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export declare function UIPopover(style: UIPopoverStyle, children?: UINodeChild[] | ChildrenFn): UIPopover;

package/dist/types/ui/UIScreen.d.ts

@@ -0,0 +1,57 @@
+import { TouchStartEvent } from "../runtime/touch";
+import { type PresentOptions } from "./presentable";
+import { ContainerElement, type BaseStyle, type ContainerStyle, type DrawableStyle, type PaddingStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn } from "./UINode";
+export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle;
+/** A screen — the root the router/host mounts, sized to its slot. A screen NEVER scrolls: it is
+ *  fixed chrome (header, tab bar) plus, when the content overflows, one `UIScrollable` body child
+ *  (`flexGrow: 1`). Scroll events and pull-to-refresh live on the scroll containers
+ *  (`UIScrollable`, `UIVirtualizedList`). */
+export interface UIScreen extends UIContainerBase<UIScreenStyle, DrawableStyle & BaseStyle> {
+    readonly type: "screen";
+    /** Show this screen as the current destination (replaces whatever is visible — a screen, a
+     *  scene, a native view — suspending an active Router until `Router.restore()`). */
+    open(options?: PresentOptions): void;
+    /** Dismiss if this screen is the visible destination. */
+    close(): void;
+    /** Hardware/system back while this screen is current. */
+    onBackPressed(callback: () => void): this;
+    /** The screen became the visible destination (first open, or revealed by a pop). */
+    onOpen(callback: () => void): this;
+    /** The screen stopped being visible — closed, replaced, or covered by a push. */
+    onClose(callback: () => void): this;
+    /**
+     * Keep this screen's built native tree alive when a host detaches it: instead of being destroyed,
+     * its views + layout + live state (scroll position, input text) are retained, so re-hosting the
+     * SAME screen object restores it in place rather than rebuilding. `onClose`/`onOpen` still fire on
+     * detach/re-attach. You own the lifetime — a kept tree is freed only by `dispose()` or when the
+     * project unloads. (Native-only today; web rebuilds.)
+     */
+    keepAlive(enabled?: boolean): this;
+    /** Free a `keepAlive()` screen's retained tree now. No-op unless it's currently detached-and-kept. */
+    dispose(): this;
+    /** Touch began on the screen; `ev.track(...)` takes over the rest of the gesture. */
+    onTouchStart(callback: (ev: TouchStartEvent<UIScreen>) => void): this;
+}
+export declare class ScreenElement extends ContainerElement<"screen"> {
+    open(options?: PresentOptions): void;
+    close(): void;
+    protected ol: (() => void)[];
+    onOpen(callback: () => void): this;
+    protected cl: (() => void)[];
+    onClose(callback: () => void): this;
+    _keepAlive: boolean;
+    keepAlive(enabled?: boolean): this;
+    dispose(): this;
+    readonly touchStartListeners: any[];
+    _interactive: boolean;
+    onTouchStart(callback: any): this;
+    _emitTouchStart(pointerId: number, clientX: number, clientY: number): any;
+    _backButtonCallback?: () => void;
+    onBackPressed(callback: any): this;
+}
+/** Create a screen. Present it with `.open()`, or via `Router` / `UIPager`. Same argument forms
+ *  as `UIColumn`. */
+export declare function UIScreen(...children: UIChildArg[]): UIScreen;
+export declare function UIScreen(children: UINodeChild[] | ChildrenFn): UIScreen;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export declare function UIScreen(style: UIScreenStyle, children?: UINodeChild[] | ChildrenFn): UIScreen;

package/dist/types/ui/UIScrollable.d.ts

@@ -0,0 +1,40 @@
+import type { UIContainerStyle } from "./UIContainer";
+import { type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type Color } from "./UINode";
+export type ScrollStyle = {
+    showScrollbar?: boolean;
+    overscrollMode?: "none" | "absorb" | "default";
+    /** Tint of the native pull-to-refresh spinner (pairs with `onRefresh`). */
+    refreshControlColor?: Color;
+    /** How a scroll gesture in THIS scrollable dismisses the keyboard: `"interactive"` (default) —
+     *  dragging over the keyboard slides it away (chat feel); `"scroll"` — any drag dismisses
+     *  immediately; `"none"` — never (tap-outside policy still applies). */
+    keyboardDismissMode?: "interactive" | "scroll" | "none";
+    /** Paging: when the drag ends, rest on a direct child's boundary along the scroll axis — the
+     *  value picks where the child sits in the viewport; `"none"` (default) is free scrolling. Snap
+     *  targets are the children themselves, so item widths can differ (card-carousel-with-peek); a
+     *  carousel is a horizontal scrollable of full-width children + `snap: "start"`. */
+    snap?: "none" | "start" | "center" | "end";
+};
+export type UIScrollableStyle = UIContainerStyle & ScrollStyle & {
+    scrollDirection?: "horizontal" | "vertical";
+};
+/** A scroll container — vertical by default, `scrollDirection: "horizontal"` for carousels/chip
+ *  rows. The scrolling body of a screen (screens themselves never scroll). */
+export interface UIScrollable extends UIContainerBase<UIScrollableStyle> {
+    readonly type: "scrollable";
+    /** Scroll position changed (px from the start edge). */
+    onScroll(callback: (scrollPosition: number) => void): UIScrollable;
+    /** The scroll gesture ended (finger lifted). */
+    onScrollRelease(callback: () => void): UIScrollable;
+    /** Pulled past the content edge by `delta` px. */
+    onOverscroll(callback: (delta: number) => void): UIScrollable;
+    /** Pull-to-refresh: the spinner stays until the returned promise settles. Attach BEFORE the
+     *  node mounts (hosts read it at creation). Vertical only; native hosts — no-op on web. */
+    onRefresh(callback: () => void | Promise<void>): UIScrollable;
+}
+/** Create a scroll container (same argument forms as `UIColumn`). As a screen body, pair with
+ *  `flexGrow: 1`. */
+export declare function UIScrollable(...children: UIChildArg[]): UIScrollable;
+export declare function UIScrollable(children: UINodeChild[] | ChildrenFn): UIScrollable;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export declare function UIScrollable(style: UIScrollableStyle, children?: UINodeChild[] | ChildrenFn): UIScrollable;

package/dist/types/ui/UISpacer.d.ts

@@ -0,0 +1,9 @@
+import { type ElementStyle, type UIElementBase } from "./UINode";
+export type UISpacerStyle = ElementStyle;
+/** A flexible gap — `flexGrow: 1` by default, pushes its siblings apart. */
+export interface UISpacer extends UIElementBase<UISpacerStyle> {
+    readonly type: "spacer";
+}
+/** Create a flexible gap (`flexGrow: 1`) — e.g. between a header's title and its actions. */
+export declare function UISpacer(): UISpacer;
+export declare function UISpacer(style: UISpacerStyle): UISpacer;