lecodes-sdk 0.19.0

package/src/ui/UISpacer.ts

@@ -0,0 +1,14 @@
+import { Element, 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 function UISpacer(): UISpacer
+export function UISpacer(style: UISpacerStyle): UISpacer
+export function UISpacer(style?: UISpacerStyle): UISpacer {
+  return new Element("spacer", { flexGrow: 1, ...style })
+}

package/src/ui/UITabs.ts

@@ -0,0 +1,236 @@
+import { PagerElement, type UIPager } from "./UIPager"
+import { ScreenElement, UIScreen } from "./UIScreen"
+import { UIButton } from "./UIButton"
+import { UIRow, UIColumn, type UIRow as UIRowType } from "./UIContainer"
+import { UIText } from "./UIText"
+import { UIImage, type ImageSource } from "./UIImage"
+import type { UIChildArg } from "./UINode"
+
+// UITabs — the standard bottom-tab shell, prewired: a UIScreen composing [ UIPager (flexGrow: 1),
+// tab bar ]. Pure SDK composition over the pager — zero new ABI, works wherever UIPager does.
+// `defineTabs` (below) is its design-stage twin (lecodes-design/tabbar-surface.md): the same keyed
+// config without screens, mounted per-file with a literal tab id. They share the constants and bar
+// geometry in this file, so a designed mockup and the built app render identically.
+
+/** Active/inactive/bar colors ride the theme — one `theme({ primaryColor, mutedColor, tabbarBg })`
+ *  call restyles the bar app-wide; the fallbacks keep an unthemed app looking right. */
+const ACTIVE = "var(--primaryColor, #5b8cff)"
+const INACTIVE = "var(--mutedColor, #8a919e)"
+const BAR_BG = "var(--tabbarBg, #15171c)"
+const BAR_BORDER = "var(--tabbarBorder, #23262e)"
+const SCREEN_BG = "var(--screenBg, #101114)"
+const BADGE_BG = "var(--badgeColor, #ff453a)"
+
+export type UITabDef = {
+  label: string,
+  /** Tab icon — typically `assetIcon("lucide:…")`. Tinted active/inactive by the bar. */
+  icon?: ImageSource,
+  /** The tab's root screen. Tabs are fixed at construction (like UIPager's). */
+  screen: UIScreen,
+}
+
+/**
+ * A bottom-tab app shell: swipeable tabs (a `UIPager`) plus a themed tab bar, as one
+ * `UIScreen` — present it directly (`Router.init(tabs)`). Keys are tab ids, in tab order:
+ *
+ * ```ts
+ * const tabs = UITabs({
+ *   home:    { label: "Home",    icon: assetIcon("lucide:house"), screen: homeScreen },
+ *   profile: { label: "Profile", icon: assetIcon("lucide:user"),  screen: profileScreen },
+ * })
+ * Router.init(tabs)
+ * ```
+ *
+ * In-tab navigation stays the pager's: `UIPager.push(detail)` from any screen (bar stays);
+ * `Router.push` opens above the shell (bar covered). Restyle via `theme()` (primaryColor,
+ * mutedColor, tabbarBg, …) or the `bar` handle; for a fully custom bar build on `UIPager`.
+ */
+export interface UITabs extends UIScreen {
+  /** The active tab id. */
+  readonly tab: string,
+  /** Switch tabs (instant, the tab-bar convention; `animated: true` slides). */
+  select(id: string, animated?: boolean): this,
+  /** Fires when the active tab changes and has settled — a bar tap, swipe, or `select()`. */
+  onSelect(callback: (id: string, index: number) => void): this,
+  /** Show a badge on a tab: `true` = dot, a number/string = count pill, `false`/`null`/`0` clears. */
+  badge(id: string, value: number | string | boolean | null): this,
+  /** The pager under the bar — in-tab stacks (`push`/`pop`/`depth`). */
+  readonly pager: UIPager,
+  /** The bar row (named "tabbar") — for restyling beyond the theme variables. */
+  readonly bar: UIRowType,
+}
+
+export class TabsElement extends ScreenElement {
+  private readonly ids: string[]
+  private readonly _pagerEl: PagerElement
+  private readonly _bar: any
+  private readonly _icons: (any | null)[] = []
+  private readonly _labels: any[] = []
+  private readonly _badges: any[] = []
+  private readonly _badgeTexts: any[] = []
+  private readonly _buttons: any[] = []
+  private readonly _selectListeners: ((id: string, index: number) => void)[] = []
+
+  constructor(defs: Record<string, UITabDef>) {
+    super("screen", { bgColor: SCREEN_BG }, [])
+    this.ids = Object.keys(defs)
+    if (this.ids.length === 0) console.warn("UITabs: no tabs declared")
+
+    this._pagerEl = new PagerElement({ flexGrow: 1 }, this.ids.map((id) => defs[id].screen))
+
+    const buttons = this.ids.map((id, i) => {
+      const def = defs[id]
+      const icon = def.icon ? UIImage(def.icon).style({ width: 22, height: 22, tintColor: INACTIVE }) : null
+      const label = UIText(def.label).style({ fontSize: 10, color: INACTIVE })
+      const badgeText = UIText("").style({ fontSize: 9, fontWeight: 700, color: "white" })
+      const badge = UIRow(badgeText).style({
+        position: "absolute", top: -3, right: -6, display: "none",
+        bgColor: BADGE_BG, borderRadius: 99, justifyContent: "center", alignItems: "center",
+      })
+      // The badge anchors to the icon (or the label when there is none) — its wrap must not clip.
+      const anchor = UIColumn(icon ?? label, badge).style({ overflow: "visible", alignItems: "center" })
+      this._icons.push(icon)
+      this._labels.push(label)
+      this._badges.push(badge)
+      this._badgeTexts.push(badgeText)
+      const button = UIButton(anchor, icon ? label : null)
+        .style({ name: `tab-${id}`, flexDirection: "column", gap: 3, flex: 1, pt: 8, pb: 6 })
+        .onClick(() => this.select(id))
+      this._buttons.push(button)
+      return button
+    })
+
+    this._bar = UIRow(buttons).style({
+      name: "tabbar", bgColor: BAR_BG, pb: "comfort-bottom",
+      borderTopWidth: 1, borderTopColor: BAR_BORDER,
+    })
+
+    this._pagerEl.onSelect((i) => {
+      this._applyActive(i)
+      for (const cb of this._selectListeners) cb(this.ids[i], i)
+    })
+    this._applyActive(0)
+    this.append(this._pagerEl as any, this._bar)
+  }
+
+  private _applyActive(index: number): void {
+    for (let i = 0; i < this.ids.length; i++) {
+      const on = i === index
+      const color = on ? ACTIVE : INACTIVE
+      // Imperative writes carry the visual on every host; the class is the styling hook — custom
+      // content inside a tab button can declare `$active` blocks (class state cascades down).
+      this._buttons[i].class.active = on
+      if (this._icons[i]) this._icons[i].style.tintColor = color
+      this._labels[i].style.color = color
+    }
+  }
+
+  get tab(): string {
+    return this.ids[this._pagerEl.index]
+  }
+  get pager(): any {
+    return this._pagerEl
+  }
+  get bar(): any {
+    return this._bar
+  }
+
+  select(id: string, animated = false): this {
+    const index = this.ids.indexOf(id)
+    if (index < 0) {
+      console.warn(`UITabs.select: unknown tab "${id}"`)
+      return this
+    }
+    this._pagerEl.select(index, animated)
+    return this
+  }
+
+  onSelect(callback: (id: string, index: number) => void): this {
+    this._selectListeners.push(callback)
+    return this
+  }
+
+  badge(id: string, value: number | string | boolean | null | undefined): this {
+    const i = this.ids.indexOf(id)
+    if (i < 0) {
+      console.warn(`UITabs.badge: unknown tab "${id}"`)
+      return this
+    }
+    if (value === null || value === undefined || value === false || value === 0 || value === "") {
+      this._badges[i].style.display = "none"
+    } else if (value === true) {
+      this._badgeTexts[i].text = ""
+      this._badges[i].style({ display: "flex", width: 9, height: 9, minWidth: 0, px: 0 })
+    } else {
+      this._badgeTexts[i].text = String(value)
+      this._badges[i].style({ display: "flex", width: "auto", height: 14, minWidth: 14, px: 4 })
+    }
+    return this
+  }
+}
+
+/** Create the standard bottom-tab shell — see {@link UITabs}. Keys are tab ids in tab order;
+ *  each tab needs a `label` and its root `screen` (plus an optional `icon`). */
+export function UITabs(tabs: Record<string, UITabDef>): UITabs {
+  return new TabsElement(tabs) as unknown as UITabs
+}
+
+// ---- defineTabs — the design-stage twin ---------------------------------------------------------
+
+/** A `defineTabs` tab: `label` + optional `icon` (an `assetIcon("lucide:…")` call — never a
+ *  hand-written source object). `UITabDef` is this plus the tab's root `screen`. */
+export type TabDef = Omit<UITabDef, "screen">
+
+/** What `defineTabs` returns: the bar (mount it yourself when the screen owns its whole layout)
+ *  and the standard screen shell around it. `active` must be a declared tab id, as a literal. */
+export type TabsHandle<T extends Record<string, TabDef>> = {
+  /** Tab ids in declaration order. */
+  ids: (keyof T & string)[]
+  /** The bar alone — one button per tab, the `active` one highlighted. */
+  bar(active: keyof T & string): UIRowType
+  /** A screen sitting ON the bar: `[ padded content column, bar ]`. */
+  screen(active: keyof T & string, ...children: UIChildArg[]): UIScreen
+}
+
+/**
+ * Declare a tab bar WITHOUT screens — the design-stage twin of {@link UITabs} (same keys, same
+ * `tab-<id>` button names, same theme variables), for mockups where every screen is its own file
+ * and mounts the bar with a literal tab id:
+ *
+ * ```ts
+ * export const mainTabs = defineTabs({
+ *   home:    { label: "Home",    icon: assetIcon("lucide:house") },
+ *   profile: { label: "Profile", icon: assetIcon("lucide:user") },
+ * })
+ * // in a screen file:
+ * export default () => mainTabs.screen("home", [ ...content ])
+ * ```
+ *
+ * Restyle through the theme — `theme({ primaryColor, mutedColor, tabbarBg, screenBg })` recolors
+ * every bar at once. The built app passes the same keys (plus each tab's root screen) to `UITabs`,
+ * which renders the identical bar interactively.
+ */
+export function defineTabs<T extends Record<string, TabDef>>(tabs: T): TabsHandle<T> {
+  const ids = Object.keys(tabs) as (keyof T & string)[]
+
+  const bar = (active: keyof T & string) =>
+    UIRow(ids.map((id) => {
+      const def = tabs[id]
+      const color = id === active ? ACTIVE : INACTIVE
+      return UIButton(
+        def.icon ? UIImage(def.icon).style({ width: 22, height: 22, tintColor: color }) : null,
+        UIText(def.label).style({ fontSize: 10, color }),
+      ).style({ name: `tab-${id}`, flexDirection: "column", gap: 3, flex: 1, pt: 8, pb: 6 })
+    })).style({
+      name: "tabbar", bgColor: BAR_BG, pb: "comfort-bottom",
+      borderTopWidth: 1, borderTopColor: BAR_BORDER,
+    })
+
+  const screen = (active: keyof T & string, ...children: UIChildArg[]) =>
+    UIScreen(
+      UIColumn(...children).style({ flexGrow: 1, p: 16, pt: "safe-top" }),
+      bar(active),
+    ).style({ bgColor: SCREEN_BG })
+
+  return { ids, bar, screen }
+}

package/src/ui/UIText.ts

@@ -0,0 +1,51 @@
+import { createBinding } from "../core/signals"
+import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type TextStyle, type UIElementBase } from "./UINode"
+
+export type UITextStyle = ElementStyle & TextStyle & DrawableStyle
+
+/** A text label. */
+export interface UIText extends UIElementBase<UITextStyle, DrawableStyle & BaseStyle & TextStyle> {
+  readonly type: "text",
+  /** The displayed string — writable at any time. */
+  text: string,
+}
+
+export class TextElement extends Element<"text"> {
+  private _text: string
+  constructor(style: any, text: string | (() => string)) {
+    super("text", style)
+    if (typeof text === "function") {
+      // Reactive content: re-runs when a signal `text()` read changes; the setter routes to
+      // _creatorUI.updateNode when mounted and just keeps _text current when not.
+      this._text = ""
+      createBinding(this, "#text", () => {
+        const value = text()
+        if (value !== this._text) this.text = value
+      })
+    } else {
+      this._text = text
+    }
+  }
+  get text(): string {
+    return this._text
+  }
+  set text(value) {
+    this._text = value
+    if (this._id !== 0) {
+      _creatorUI.updateNode(this._id, "text", value)
+    }
+  }
+}
+
+/** Create a text label — a string, or `() => string` for reactive text that re-renders when a
+ *  signal it read changes. */
+export function UIText(text: string | (() => string)): UIText;
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIText(style: UITextStyle, text: string | (() => string)): UIText;
+export function UIText(...args: [string | (() => string)] | [UITextStyle, string | (() => string)]): UIText {
+  if (args.length === 1) {
+    return new TextElement({}, args[0])
+  } else {
+    return new TextElement(args[0], args[1])
+  }
+}

package/src/ui/UIVideo.ts

@@ -0,0 +1,88 @@
+import type { VideoPlayer } from "../runtime/media"
+import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
+import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode"
+
+export type UIVideoStyle = ElementStyle & DrawableStyle & { objectFit?: "cover" | "contain" | "fill" }
+
+/** A video surface showing a `VideoPlayer`'s output — embeddable in a screen AND
+ *  fullscreen-presentable (`open()`), with seamless promotion between the two. */
+export interface UIVideo extends UIElementBase<UIVideoStyle, DrawableStyle & BaseStyle> {
+  readonly type: "video",
+  /** The player driving this surface (playback control lives on it). */
+  player: VideoPlayer
+
+  /** Show fullscreen as the current destination. Promotion: if this video is mounted in a screen,
+   *  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
+  /** 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
+}
+
+class VideoElement extends Element<"video"> implements Presentable {
+  private _playerId: number
+  private _player: VideoPlayer
+  constructor(style: any, player: VideoPlayer) {
+    super("video", style)
+    this._player = player
+    this._playerId = (player as any)._id
+  }
+
+  get player() {
+    return this._player
+  }
+
+  // ---- Presentable (docs/navigation-presentable-plan.md) ----
+  readonly ol: (() => void)[] = []
+  readonly cl: (() => void)[] = []
+  _backButtonCallback?: () => void
+  private _vd?: object
+
+  /** @internal wire descriptor — type "videoView" (distinct from the "video" node type). */
+  _viewDesc(): object {
+    return this._vd ??= { type: "videoView", node: this, _p: this }
+  }
+
+  open(options?: PresentOptions): void {
+    if (!_navSupported()) {
+      throw new Error("Fullscreen video is not supported on this host (requires _creatorUI.openView)")
+    }
+    _bumpNavEpoch()
+    _creatorUI.openView!(this._viewDesc(), options?.transition ?? "none")
+    _setCurrent(this)
+  }
+  close(): void {
+    _bumpNavEpoch()
+    if (_navSupported()) _creatorUI.closeView!()
+    if (Presentable.current === this) _setCurrent(null)
+  }
+  onOpen(callback: () => void): this {
+    this.ol.push(callback)
+    return this
+  }
+  onClose(callback: () => void): this {
+    this.cl.push(callback)
+    return this
+  }
+  onBackPressed(callback: () => void): this {
+    this._backButtonCallback = callback
+    return this
+  }
+}
+
+/** Create a video node showing `player`'s output. */
+export function UIVideo(player: VideoPlayer): UIVideo
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIVideo(style: UIVideoStyle, player: VideoPlayer): UIVideo
+export function UIVideo(...args: [VideoPlayer] | [UIVideoStyle, VideoPlayer]): UIVideo {
+    if (args.length === 1) {
+    return new VideoElement({}, args[0])
+  } else {
+    return new VideoElement(args[0], args[1])
+  }
+}

package/src/ui/UIVirtualizedList.ts

@@ -0,0 +1,241 @@
+import { Element, type Color, type DrawableStyle, type ElementStyle, type UIElementBase, type UINodeChild } from "./UINode"
+
+export type UIVirtualizedListStyle = DrawableStyle & ElementStyle & {
+  /** Tint of the native pull-to-refresh spinner (pairs with `onRefresh`). */
+  refreshControlColor?: Color,
+  /** Same key and semantics as UIScrollable's; `"none"` keeps a chat composer's keyboard up no
+   *  matter how the history is scrolled. */
+  keyboardDismissMode?: "interactive" | "scroll" | "none",
+}
+
+export interface VListConfig<T> {
+    /** Stable unique key of an item. */
+    keyOf: (item: T) => string
+    /** Subtree factory — called when the item enters the window; the subtree lives until it
+     *  leaves. */
+    render: (item: T) => UINodeChild
+    /** Height estimate (px) used before the first measurement — a number, or a per-item function
+     *  (chat: `msg => 40 + Math.ceil(msg.text.length / 35) * 20`). Computed once when the item is
+     *  added. */
+    estimatedHeight: number | ((item: T) => number)
+    /** Extra px around the viewport kept mounted. Default: one viewport height. */
+    overscan?: number
+    /** Chat mode: the first layout starts scrolled to the end, and appends auto-scroll while the
+     *  list sits at the bottom. */
+    inverted?: boolean
+}
+
+/** A windowed (virtualized) list: only the items near the viewport are mounted — for long feeds
+ *  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. */
+    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). */
+    prepend(...items: T[]): this
+    /** Update items with the same keys: mounted ones re-render; the cached height persists until
+     *  re-measured. */
+    update(...items: T[]): this
+    /** Remove items by key. */
+    removeByKey(...keys: string[]): this
+
+    /** Number of data items (mounted or not). */
+    readonly itemCount: number
+    /** The data item under `key`, if any. */
+    getItem(key: string): T | undefined
+
+    /** Scroll to `offset` px. */
+    scrollTo(offset: number, animated?: boolean): void
+    /** Scroll to the item with `key`. */
+    scrollToKey(key: string, animated?: boolean): void
+    /** Scroll to the end of the content. */
+    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. */
+    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. */
+    onEndReached(thresholdPx: number, callback: () => void): this
+    /** Same, for the top edge — chat history loading. */
+    onStartReached(thresholdPx: number, callback: () => void): this
+}
+
+export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedList<T> {
+
+    // --- read by native side in createUINode (copyProperty / copyNodePtr) ---
+    _overscan: number
+    _inverted: boolean
+    _keys: string[] = [] 
+    _estimates: number[] = [] 
+    _endThreshold = 0
+    _startThreshold = 0
+
+    // --- списки слушателей, нативка забирает через copyPropertyListPtr ---
+    protected sl: ((scrollPosition: number) => void)[] = []     // scroll
+    protected erl: (() => void)[] = []                          // endReached
+    protected strl: (() => void)[] = []                         // startReached
+
+    // --- приватное состояние JS-стороны ---
+    private items = new Map<string, T>()
+    private mounted = new Map<string, UINodeChild>()
+    private keyOf: (item: T) => string
+    private renderItem: (item: T) => UINodeChild
+    private estimate: (item: T) => number
+
+    constructor(config: VListConfig<T>) {
+        // flexShrink: 1 default (SDK-owned, same as UIScrollable): an explicit height/flexBasis
+        // larger than the available space shrinks to fit instead of overflowing. The vlist's own
+        // yoga basis is 0 (items live in detached roots), so this is inert until a size is set.
+        super("vlist", { flexShrink: 1 })
+        this.keyOf = config.keyOf
+        this.renderItem = config.render
+        this.estimate = typeof config.estimatedHeight === "function"
+            ? config.estimatedHeight
+            : () => config.estimatedHeight as number
+        this._overscan = config.overscan ?? -1
+        this._inverted = config.inverted ?? false
+    }
+
+    private get isAttached(): boolean {
+        return !!this._id && this._id !== 0
+    }
+
+    private register(items: T[]): [string[], number[]] {
+        const keys: string[] = []
+        const estimates: number[] = []
+        for (const item of items) {
+            const k = this.keyOf(item)
+            this.items.set(k, item)
+            keys.push(k)
+            estimates.push(this.estimate(item))
+        }
+        return [keys, estimates]
+    }
+
+    setData(items: T[]): this {
+        const prevItems = new Map(this.items)
+        const prevMounted = [...this.mounted.keys()]
+        this.items.clear()
+        const [keys, estimates] = this.register(items)
+        this._keys = keys
+        this._estimates = estimates
+        if (this.isAttached) {
+            _creatorUI.vlistSetKeys(this, keys, estimates)
+
+            for (const k of prevMounted) {
+                if (this.mounted.has(k) && this.items.get(k) !== prevItems.get(k)) {
+                    _creatorUI.vlistInvalidate(this, k)
+                }
+            }
+        }
+        return this
+    }
+
+    append(...items: T[]): this {
+        const [keys, estimates] = this.register(items)
+        this._keys.push(...keys)
+        this._estimates.push(...estimates)
+        if (this.isAttached) {
+            _creatorUI.vlistInsertKeys(this, -1, keys, estimates)
+        }
+        return this
+    }
+
+    prepend(...items: T[]): this {
+        const [keys, estimates] = this.register(items)
+        this._keys.unshift(...keys)
+        this._estimates.unshift(...estimates)
+        if (this.isAttached) {
+            _creatorUI.vlistInsertKeys(this, 0, keys, estimates)
+        }
+        return this
+    }
+
+    update(...items: T[]): this {
+        for (const item of items) {
+            const k = this.keyOf(item)
+            if (!this.items.has(k)) continue
+            this.items.set(k, item)
+            if (this.isAttached && this.mounted.has(k)) {
+                _creatorUI.vlistInvalidate(this, k)
+            }
+        }
+        return this
+    }
+
+    removeByKey(...keys: string[]): this {
+        for (const k of keys) {
+            if (!this.items.delete(k)) continue
+            const i = this._keys.indexOf(k)
+            if (i >= 0) { this._keys.splice(i, 1); this._estimates.splice(i, 1) }
+        }
+        if (this.isAttached) {
+            _creatorUI.vlistRemoveKeys(this, keys)
+        }
+        return this
+    }
+
+    get itemCount(): number { return this.items.size }
+    getItem(key: string): T | undefined { return this.items.get(key) }
+
+    // --- команды: офсеты и позиции знает только нативка (префикс-суммы) ---
+    scrollTo(offset: number, animated = true): void {
+        _creatorUI.command(this, "scrollTo", offset, animated)
+    }
+    scrollToKey(key: string, animated = true): void {
+        _creatorUI.command(this, "scrollToKey", key, animated)
+    }
+    scrollToEnd(animated = true): void {
+        _creatorUI.command(this, "scrollToEnd", animated)
+    }
+
+    onScroll(callback: (scrollPosition: number) => void): this {
+        this.sl.push(callback)
+        return this
+    }
+    // Читается нативкой при маунте (тот же контракт, что у UIScrollable).
+    declare _refreshCallback: any
+    onRefresh(callback: () => void | Promise<void>): this {
+        this._refreshCallback = callback
+        return this
+    }
+    onEndReached(thresholdPx: number, callback: () => void): this {
+        this._endThreshold = thresholdPx
+        this.erl.push(callback)
+        return this
+    }
+    onStartReached(thresholdPx: number, callback: () => void): this {
+        this._startThreshold = thresholdPx
+        this.strl.push(callback)
+        return this
+    }
+
+    /** @internal The one host→JS callback (via jsPtr, like button). Fires ONLY when the window
+     *  crossed a boundary — not per scroll frame. Order: unmounts first (the host already tore the
+     *  subtrees down and zeroed _id; only JS refs are cleaned here), then mounts. */
+    _syncWindow(unmountKeys: string[], mountKeys: string[]): void {
+        for (const k of unmountKeys) {
+            this.mounted.delete(k)
+        }
+        for (const k of mountKeys) {
+            const item = this.items.get(k)
+            if (item === undefined) continue
+            const node = this.renderItem(item)
+            this.mounted.set(k, node)
+            // createUINode в detached yoga root + измерение (width, NaN) + кэш высоты
+            _creatorUI.vlistMount(this, k, node)
+        }
+    }
+}
+
+/** Create a virtualized list from a config (`keyOf` + `render` + `estimatedHeight` required),
+ *  then feed it via `setData`/`append`/`prepend`. Give it a size (`flexGrow: 1` as a screen body). */
+export function UIVirtualizedList<T>(config: VListConfig<T>): UIVirtualizedList<T> {
+    return new VListElement<T>(config)
+}