lecodes-sdk 1.2.0 → 2.0.0

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

@@ -1,10 +1,12 @@
 import type { FetchResponse } from "../runtime/fetch";
+import type { ColorInput } from "../core/color";
 import type { Animation } from "../animate/tween/Animation";
 import { type TweenMeta } from "../animate/tween/spec";
+import { type TreeElement } from "./tree";
 export interface UINode {
     readonly type: string;
     /** Author-given semantic name (a stable selector for tests + AI review feedback). */
-    readonly name?: string;
+    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>;
@@ -15,9 +17,11 @@ export type UINodeChild = UINode | null | undefined | false;
  *  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;
+/** A color: any CSS color string (`"#1c1c1e"`, `"rgba(0,0,0,0.5)"`, `"green"`, `"hsl(210 50% 40%)"`),
+ *  a theme reference (`"var(--primaryColor)"`), an opaque `0xRRGGBB` number or `[r, g, b(, a)]` in
+ *  0..1; `null` clears. A string is the core's to parse (an unknown one is transparent, as in
+ *  CSS); a number or an array that is not a color throws at the write. */
+export type Color = ColorInput | null;
 /** Style props every element accepts. */
 export type BaseStyle = {
     opacity?: number | `${number}`;
@@ -30,12 +34,6 @@ export type BaseStyle = {
     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 = {
@@ -155,25 +153,32 @@ export type TextStyle = {
     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. */
+ *  re-applies when a signal it read changes. Nested `$class` blocks 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]);
 };
-/** The curve of a state block's swap (`$class` / `onPressed` / `onFocused` with a `duration`): a
- *  curve name (`outCubic`, `inOutSine`, `smoothstep` — the default — …), `cubic-bezier(x1,y1,x2,y2)`
- *  or `steps(n)`. A function cannot ride a style block; use `animateTo` for those. */
+/** The curve of a `$class` block's swap (with a `duration`): a curve name (`outCubic`,
+ *  `inOutSine`, `smoothstep` — the default — …), `cubic-bezier(x1,y1,x2,y2)` or `steps(n)`. A
+ *  function cannot ride a style block; use `animateTo` for those. */
 export type LayerEasing = string;
-/** User-defined style classes: any `$`-prefixed key in `.style()` declares a state block toggled
- *  from code via the `el.class` proxy; `duration`/`delay`/`easing` 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.
+/** Style states: any `$`-prefixed key in `.style()` declares a state block; `duration`/`delay`/
+ *  `easing` animate its swap. User classes (`$checked`, `$selected`, …) are toggled from code via the
+ *  `el.class` proxy and INHERIT 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 (sdk/docs/ui/classes.md).
+ *
+ *  Five classes are reserved — the system toggles them, `el.class` cannot:
+ *  - `$hovered` / `$pressed` / `$focused` — the host's hover (mouse only) / press / focus. They
+ *    cascade from the node the host toggled and STOP at the nearest interactive descendant (a
+ *    button inside a pressed card is not pressed; it has its own scope).
+ *  - `$landscape` / `$portrait` — the display orientation, GLOBAL: active on every node at once.
+ *
+ *  Precedence on the same prop: base < `$landscape`/`$portrait` < user `$classes` (later-declared
+ *  beats earlier) < `$hovered` < `$pressed` < `$focused`.
  *
  *  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. */
+ *  `.style()` does. 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;
@@ -196,8 +201,9 @@ export type ClassValue = boolean | (() => boolean);
  *  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()`.
+ *  Class names are accepted with or without the declaration-site `$` prefix. A write of a reserved
+ *  class (`hovered` `pressed` `focused` `landscape` `portrait`) throws — the system toggles those.
+ *  `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;
@@ -211,14 +217,25 @@ 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>;
+    /** Author-given semantic name — a stable selector for tests and for marking elements in the AI
+     *  code-review feedback loop; surfaced in the renderer's serialized output. Set it with `.named()`
+     *  (chainable) or assign it. */
+    name?: string;
+    /** Set the semantic name (chainable). */
+    named(name: string): this;
     /** 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. */
+    /** Absolute rect in device space, read live (includes scroll); `null` before layout. */
     getBoundingClientRect(): BoundingClientRect | null;
+    /** The parent element, or `null` for a root (a screen, a widget, an unmounted subtree's top). */
+    readonly parent: UINode | null;
+    /** Free this element's subtree now (views, layout, native state). Only for a DETACHED subtree —
+     *  remove / hide / close it first; an attached one is left alone. After it the element is dead. */
+    destroy(): void;
     /** 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}. */
@@ -234,24 +251,14 @@ export interface UIContainerBase<S extends object, A extends object = S> extends
     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[];
+    /** The children — a SNAPSHOT read from the runtime; mutate via `append`/`insert`/`remove`/`setContent`. */
+    readonly children: UINode[];
 }
-/** 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);
+export type StyleFn<R, T extends object> = ((style: Reactive<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>;
+ *  installs a reactive binding). Reads answer what the app set. */
+export type Style<R, T extends object> = StyleFn<R, T> & T & ClassStyles<T>;
 /** Style props of an animate bag: a single value (tween from the current value) or an array of
  *  KEYFRAMES (`opacity: [1, 0.3, 1]`, offsets via `times`). */
 export type AnimateProps<T extends object> = {
@@ -290,17 +297,14 @@ export type BoundingClientRect = {
     width: number;
     height: number;
 };
-export declare class Element<T extends string> {
+export declare class Element<T extends string> implements TreeElement {
     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;
+    private _name?;
     protected _styleProxy: any;
-    protected _appear: any;
-    protected _disappear: any;
     constructor(type: T, style: any);
+    get name(): string | undefined;
+    set name(value: string | undefined);
+    named(name: string): this;
     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). A prop value may be an array of keyframes; meta keys
@@ -324,7 +328,9 @@ export declare class Element<T extends string> {
      *  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. */
+     *  there is no opt-out below an active ancestor. `Object.keys(el.class)` lists the active names.
+     *  The reserved classes (`$hovered` `$pressed` `$focused` `$landscape` `$portrait`) are the
+     *  system's: writing one throws. */
     get class(): any;
     protected ll?: OnLayoutCallback[];
     /** Observe layout: fires after every host layout pass with the parent-relative box. */
@@ -332,9 +338,14 @@ export declare class Element<T extends string> {
     /** 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
+     *  the element is laid out and on hosts without the read. Anchor popovers position-once
      *  at open; don't poll per frame. */
     getBoundingClientRect(): BoundingClientRect | null;
+    /** The parent element, or `null`. Resolves while the parent is itself attached (mounted under a
+     *  presented / router-held screen, a shown widget, a pager page …); a loose subtree's root is
+     *  held only by its handle and is not findable from its children. */
+    get parent(): any;
+    destroy(): void;
 }
 /** Reactive children: re-runs when a signal it read changes; the result is reconciled against
  *  the mounted children (kept nodes stay mounted, state intact). */
@@ -349,14 +360,17 @@ export type ChildrenFn = () => UINodeChild[];
  */
 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). */
+    /** The children — a snapshot read from the runtime (falsy entries were never mounted). */
+    get children(): any[];
+    private _insertAt;
+    /** Append children (falsy entries are skipped). */
     append(...nodes: UINodeChild[]): this;
-    /** Insert children at `index` of the children array. */
+    /** Insert children at `index`. */
     insert(index: number, ...nodes: UINodeChild[]): this;
-    /** Remove (unmount) the given children. */
-    remove(...nodesToDelete: UINode[]): this;
+    /** Remove (unmount) the given children. The removed subtrees stay valid (re-appendable) as long
+     *  as you hold them; dropped ones are freed. */
+    remove(...nodesToDelete: UINodeChild[]): this;
     /** Replace all children — a plain array, or a function for reactive children. */
     setContent(children: UINodeChild[] | ChildrenFn): this;
 }

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

@@ -1,5 +1,6 @@
 import { ContainerElement, type BaseStyle, type ChildrenFn, type DrawableStyle, type ElementStyle, type UIElementBase, type UINodeChild } from "./UINode";
 import type { UIScreen } from "./UIScreen";
+import type { NavigateOptions, PopOptions } from "./router";
 /** Styles a pager accepts — layout box + drawable (background, borders, …). Pages style
  *  themselves; the pager only owns its own slot. */
 export type UIPagerStyle = ElementStyle & DrawableStyle;
@@ -33,17 +34,21 @@ export interface UIPager extends UIElementBase<UIPagerStyle, DrawableStyle & Bas
     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;
+    /** Push `screen` on top of the **current tab**; the edge back-swipe (or `pop()`) removes it.
+     *  Other tabs are unaffected. Transitions as in `Router.push`: `"push"` unless one is named, and
+     *  the screen remembers its way back (`popTransition`, or the mirror of the way it came). */
+    push(screen: UIScreen, opts?: NavigateOptions): 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;
+     *  programmatic twin of the native edge back-swipe. Plays the way back the screen remembers
+     *  unless a transition is named. */
+    pop(opts?: PopOptions): this;
+    /** Unwind the current tab back to its root screen in one step: the top screen leaves with its
+     *  way back (or the named transition), the ones between are never shown. */
+    popToRoot(opts?: PopOptions): 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;
+     *  swaps the tab's root). `"fade"` unless a transition is named; the way back stays the one of
+     *  the place in the stack unless `popTransition` names another. */
+    replace(screen: UIScreen, opts?: NavigateOptions): 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
@@ -51,37 +56,35 @@ export interface UIPager extends UIElementBase<UIPagerStyle, DrawableStyle & Bas
     readonly depth: number;
     /** Fires when the current tab's depth changes — push, pop, replace, or a back-swipe. */
     onChange(callback: (depth: number) => void): this;
+    /** The pages, tab-major (every tab's stack root → top). */
+    readonly children: UIScreen[];
 }
 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`. */
+    /** Start offset of tab `i`'s segment in the flat `_pages`. */
     private _offset;
+    /** Push the whole picture to the runtime. */
+    private _sync;
+    get children(): any[];
     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;
+    push(screen: UIScreen, opts?: NavigateOptions): this;
+    pop(opts?: PopOptions): this;
+    popToRoot(opts?: PopOptions): this;
+    replace(screen: UIScreen, opts?: NavigateOptions): this;
     private _rebuild;
     setContent(children: UINodeChild[] | ChildrenFn): this;
     append(...nodes: UINodeChild[]): this;
     insert(index: number, ...nodes: UINodeChild[]): this;
-    remove(...nodesToDelete: UIScreen[]): this;
+    remove(...nodesToDelete: UINodeChild[]): this;
     _reconcile(next: UINodeChild[]): void;
-    _hostDidSelect(index: number): void;
-    _hostDidPop(depth: number): void;
     private _emitSelect;
     private _emitChange;
     private _track;
@@ -96,20 +99,18 @@ interface UIPagerConstructor {
      *  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;
+    push(screen: UIScreen, opts?: NavigateOptions): 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;
+    pop(opts?: PopOptions): void;
     /** `UIPager.current.popToRoot()` — unwind the visible pager's current tab to its root. */
-    popToRoot(): void;
+    popToRoot(opts?: PopOptions): void;
 }
 /**
  * Create a pager — THE screen-navigation element: an array of screens becomes swipeable sibling

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

@@ -35,5 +35,3 @@ export declare class PopoverElement extends ModalElement {
  *  `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

@@ -1,5 +1,5 @@
 import { TouchStartEvent } from "../runtime/touch";
-import { type PresentOptions } from "./presentable";
+import { type DismissOptions, 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
@@ -12,46 +12,41 @@ export interface UIScreen extends UIContainerBase<UIScreenStyle, DrawableStyle &
      *  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;
+    close(options?: DismissOptions): void;
     /** Hardware/system back while this screen is current. */
+    onBack(callback: () => void): this;
+    /** @deprecated Renamed `onBack` (2026-09-26). An alias for the projects compiled before the
+     *  rename; removed with the release that recompiles them. */
     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.)
+     * Keep this screen's native state when a pager releases it: instead of dropping its view, the
+     * host keeps it (scroll position, input text), so re-pushing the SAME screen object restores it
+     * in place. `onClose`/`onOpen` still fire on detach/re-attach. Free it with `destroy()`.
      */
     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;
+    close(options?: DismissOptions): 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;
+    private _backButtonCallback?;
+    onBack(callback: any): this;
+    /** @deprecated see the interface */
     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

@@ -28,13 +28,10 @@ export interface UIScrollable extends UIContainerBase<UIScrollableStyle> {
     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. */
+    /** Pull-to-refresh: the spinner stays until the returned promise settles. Vertical only. */
     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/UIText.d.ts

@@ -15,5 +15,3 @@ export declare class TextElement extends Element<"text"> {
 /** Create a text label — a string, or `() => string` for reactive text that re-renders when a
  *  signal it read changes. */
 export declare function UIText(text: string | (() => string)): UIText;
-/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-export declare function UIText(style: UITextStyle, text: string | (() => string)): UIText;

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

@@ -1,5 +1,5 @@
 import type { VideoPlayer } from "../runtime/media";
-import { type PresentOptions } from "./presentable";
+import { type DismissOptions, type PresentOptions } from "./presentable";
 import { type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode";
 export type UIVideoStyle = ElementStyle & DrawableStyle & {
     objectFit?: "cover" | "contain" | "fill";
@@ -14,15 +14,13 @@ export interface UIVideo extends UIElementBase<UIVideoStyle, DrawableStyle & Bas
      *  the SAME native player moves fullscreen — playback uninterrupted; a pop moves it back. */
     open(options?: PresentOptions): void;
     /** Dismiss if this is the visible destination. */
-    close(): void;
+    close(options?: DismissOptions): void;
     /** Became the visible destination. */
     onOpen(callback: () => void): this;
     /** Stopped being the visible destination. */
     onClose(callback: () => void): this;
     /** Hardware/system back while current. */
-    onBackPressed(callback: () => void): this;
+    onBack(callback: () => void): this;
 }
 /** Create a video node showing `player`'s output. */
 export declare function UIVideo(player: VideoPlayer): UIVideo;
-/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-export declare function UIVideo(style: UIVideoStyle, player: VideoPlayer): UIVideo;

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

@@ -26,11 +26,11 @@ export interface VListConfig<T> {
  *  and chats. Items are keyed; feed it via `setData`/`append`/`prepend`. */
 export interface UIVirtualizedList<T = unknown> extends UIElementBase<UIVirtualizedListStyle> {
     readonly type: "vlist";
-    /** Replace the data wholesale — vanished keys are unmounted by the host's window sync. */
+    /** Replace the data wholesale — vanished keys are unmounted by the window sync. */
     setData(items: T[]): this;
     /** Append items to the end (auto-scrolls when `inverted` and resting at the bottom). */
     append(...items: T[]): this;
-    /** Insert at the start WITHOUT a scroll jump (the host compensates the offset). */
+    /** Insert at the start WITHOUT a scroll jump (the runtime compensates the offset). */
     prepend(...items: T[]): this;
     /** Update items with the same keys: mounted ones re-render; the cached height persists until
      *  re-measured. */
@@ -49,32 +49,31 @@ export interface UIVirtualizedList<T = unknown> extends UIElementBase<UIVirtuali
     scrollToEnd(animated?: boolean): void;
     /** Scroll position changed (px from the start edge). */
     onScroll(callback: (scrollPosition: number) => void): this;
-    /** Pull-to-refresh: the spinner stays until the returned promise settles. Attach BEFORE the
-     *  node mounts (hosts read it at creation). Native hosts only — no-op on web. */
+    /** Pull-to-refresh: the spinner stays until the returned promise settles. */
     onRefresh(callback: () => void | Promise<void>): this;
     /** Fires within `thresholdPx` of the content's bottom edge — once, re-armed after leaving the
-     *  edge (host-side latch). Infinite-scroll loading. */
+     *  edge (a runtime-side latch). Infinite-scroll loading. */
     onEndReached(thresholdPx: number, callback: () => void): this;
     /** Same, for the top edge — chat history loading. */
     onStartReached(thresholdPx: number, callback: () => void): this;
 }
 export declare class VListElement<T> extends Element<"vlist"> implements UIVirtualizedList<T> {
-    _overscan: number;
-    _inverted: boolean;
-    _keys: string[];
-    _estimates: number[];
-    _endThreshold: number;
-    _startThreshold: number;
-    protected sl: ((scrollPosition: number) => void)[];
-    protected erl: (() => void)[];
-    protected strl: (() => void)[];
+    private readonly sl;
+    private readonly erl;
+    private readonly strl;
+    private _refreshCallback?;
     private items;
     private mounted;
     private keyOf;
     private renderItem;
     private estimate;
+    private readonly _overscan;
+    private readonly _inverted;
+    private _endThreshold;
+    private _startThreshold;
+    private _inited;
     constructor(config: VListConfig<T>);
-    private get isAttached();
+    private _ensure;
     private register;
     setData(items: T[]): this;
     append(...items: T[]): this;
@@ -87,7 +86,6 @@ export declare class VListElement<T> extends Element<"vlist"> implements UIVirtu
     scrollToKey(key: string, animated?: boolean): void;
     scrollToEnd(animated?: boolean): void;
     onScroll(callback: (scrollPosition: number) => void): this;
-    _refreshCallback: any;
     onRefresh(callback: () => void | Promise<void>): this;
     onEndReached(thresholdPx: number, callback: () => void): this;
     onStartReached(thresholdPx: number, callback: () => void): this;

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

@@ -20,8 +20,7 @@ export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle &
      * (= back to a global overlay). Set it while the widget is hidden. The widget is always its own
      * overlay root mounted into the owner's page view — it never becomes a child of the owner, so it
      * stays topmost and its updates never trigger the owner's relayout. Works with a `UIScreen` that
-     * is a page inside a `UIPager`: the widget mounts into that tab and rides its swipe. (Web shows
-     * and hides it with the owner but does not yet ride the transition.)
+     * is a page inside a `UIPager`: the widget mounts into that tab and rides its swipe.
      */
     attachTo(owner: Presentable | null): this;
     /** Show the widget. By default it is a global overlay above every destination — it stays
@@ -32,34 +31,36 @@ export interface UIWidget extends UIContainerBase<UIWidgetStyle, DrawableStyle &
     /** Unmount the widget. */
     hide(): void;
     /** Mounted right now (`show()` ran, `hide()` hasn't). */
-    readonly isShow: boolean;
+    readonly isShown: boolean;
     /** Touch began on the widget; `ev.track(...)` takes over the rest of the gesture. */
     onTouchStart(callback: (ev: TouchStartEvent<UIWidget>) => void): this;
     /** Tap on the overlay layer (requires an `overlayColor`). */
     onOverlayTap(callback: () => void): this;
     /** Hardware/system back while the widget is shown. */
+    onBack(callback: () => void): this;
+    /** @deprecated Renamed `onBack` (2026-09-26). An alias for the projects compiled before the
+     *  rename; removed with the release that recompiles them. */
     onBackPressed(callback: () => void): this;
 }
 export declare class WidgetElement extends ContainerElement<"widget"> {
     scrollable: false;
     _owner?: Presentable;
+    private _shown;
     constructor(type: "widget", style: UIWidgetStyle, children: UINodeChild[] | ChildrenFn);
     attachTo(owner: Presentable | null): this;
     show(): void;
     hide(): void;
-    get isShow(): boolean;
-    _interactive: boolean;
+    get isShown(): boolean;
     readonly touchStartListeners: any[];
     onTouchStart(callback: any): this;
-    _emitTouchStart(pointerId: number, clientX: number, clientY: number): any;
     readonly otl: (() => void)[];
     onOverlayTap(callback: () => void): this;
-    _backButtonCallback?: () => void;
+    private _backButtonCallback?;
+    onBack(callback: any): this;
+    /** @deprecated see the interface */
     onBackPressed(callback: any): this;
 }
 /** Create a widget (same argument forms as `UIColumn`). Position it with absolute-style props
  *  (`top`/`left`/`bottom`/`right`), then `show()`/`hide()`. */
 export declare function UIWidget(...children: UIChildArg[]): UIWidget;
 export declare function UIWidget(children: UINodeChild[] | ChildrenFn): UIWidget;
-/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
-export declare function UIWidget(style: UIWidgetStyle, children?: UINodeChild[] | ChildrenFn): UIWidget;

package/dist/types/ui/colorKeys.gen.d.ts

@@ -0,0 +1,9 @@
+/** The keys whose value IS a color — every color property with its aliases: normalize the value
+ *  to '#rrggbbaa'. Pass-throughs: null / undefined (a reset), any string containing "var(" (the
+ *  core resolves theme vars), rippleColor's "default" (a core keyword). */
+export declare const COLOR_KEYS: ReadonlySet<string>;
+/** The shorthands that expand into a color property. A color is only ONE of their value forms:
+ *  never normalize the value whole — "2px solid red", a gradient or an image path go to the core
+ *  raw (its shorthand parsers read the colors inside with the same grammar), a number on
+ *  `border*` is a WIDTH; only a number / color array on `background` is a color. */
+export declare const COLOR_SHORTHAND_KEYS: ReadonlySet<string>;