lecodes-cli 0.10.4 → 0.12.0

package/runtime/sdk/ui/UIScrollable.ts

@@ -1,46 +1,38 @@
 import type { UIContainerStyle } from "./UIContainer"
-import { type Classes, type Style, type AnimateStyle, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BoundingClientRect, type Color, ContainerElement } from "./UINode"
+import { type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type Color, ContainerElement, buildUI } from "./UINode"
 
-// refreshControlColor tints the native pull-to-refresh spinner (pairs with onRefresh).
-// keyboardDismissMode: how a scroll gesture in THIS scrollable dismisses the keyboard.
-// "interactive" (default) — dragging over the keyboard slides it away (chat composer feel);
-// "scroll" — any drag dismisses the moment it starts (search-results feel);
-// "none" — scrolling never dismisses (tap-outside policy still applies).
-// snap: paging — when the drag ends, rest on a direct child's boundary along the scroll axis
-// (a carousel/pager is a horizontal scrollable of full-width children + snap:"start"). 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).
-export type ScrollStyle = { showScrollbar?: boolean, overscrollMode?: "none" | "absorb" | "default", refreshControlColor?: Color, keyboardDismissMode?: "interactive" | "scroll" | "none", snap?: "none" | "start" | "center" | "end" }
+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" }
 
-export interface UIScrollable {
+/** 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",
-  style: Style<this, UIScrollableStyle>,
-  animateTo: AnimateStyle<this, UIScrollableStyle>,
-  animateFrom: AnimateStyle<this, UIScrollableStyle>,
-  
-  append(...nodes: UINodeChild[]): UIScrollable
-  insert(index: number, ...nodes: UINodeChild[]): UIScrollable
-  remove(...nodes: UINodeChild[]): UIScrollable
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  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>
 
+  /** 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
-
-  readonly children: UINodeChild[]
 }
 
 class ScrollableElement extends ContainerElement<"scrollable"> {
@@ -76,22 +68,20 @@ class ScrollableElement extends ContainerElement<"scrollable"> {
   }
 }
 
-export function UIScrollable(): UIScrollable
+// flexShrink: 1 default (SDK-owned, like UIRow's flexDirection): without it a scrollable in a
+// flex parent grows to its content height and overflows instead of scrolling.
+const SCROLLABLE_DEFAULTS = { flexShrink: 1 } as const
+const makeScrollable = (style: any, children: any) => new ScrollableElement("scrollable", style, children)
+
+/** @internal Compiler fast path (chisel `flatten_ui` raw lowering) — see UIContainer. */
+export const __UIScrollable = (children: UINodeChild[] | ChildrenFn): UIScrollable => makeScrollable({ ...SCROLLABLE_DEFAULTS }, children)
+
+/** Create a scroll container (same argument forms as `UIColumn`). As a screen body, pair with
+ *  `flexGrow: 1`. */
+export function UIScrollable(...children: UIChildArg[]): UIScrollable
 export function UIScrollable(children: UINodeChild[] | ChildrenFn): UIScrollable
-export function UIScrollable(style: UIScrollableStyle): UIScrollable
-export function UIScrollable(style: UIScrollableStyle, children: UINodeChild[]): UIScrollable
-export function UIScrollable(...args: [] | [UINodeChild[] | ChildrenFn | UIScrollableStyle] | [UIScrollableStyle, children: UINodeChild[] | ChildrenFn]): UIScrollable {
-  // flexShrink: 1 default (SDK-owned, like UIRow's flexDirection): without it a scrollable in a
-  // flex parent grows to its content height and overflows instead of scrolling.
-  if (args.length === 0) {
-    return new ScrollableElement("scrollable", { flexShrink: 1 }, [])
-  } else if (args.length === 1) {
-    if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new ScrollableElement("scrollable", { flexShrink: 1 }, args[0])
-    } else {
-      return new ScrollableElement("scrollable", { flexShrink: 1, ...args[0] }, [])
-    }
-  } else {
-    return new ScrollableElement("scrollable", { flexShrink: 1, ...args[0] }, args[1])
-  }
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIScrollable(style: UIScrollableStyle, children?: UINodeChild[] | ChildrenFn): UIScrollable
+export function UIScrollable(...args: any[]): UIScrollable {
+  return buildUI(args, SCROLLABLE_DEFAULTS, makeScrollable)
 }

package/runtime/sdk/ui/UISpacer.ts

@@ -1,16 +1,12 @@
-import { Element, type ElementStyle, type Classes, type Style, type StyleFn } from "./UINode"
+import { Element, type ElementStyle, type UIElementBase } from "./UINode"
 
 export type UISpacerStyle = ElementStyle
 
-export interface UISpacer {
+/** A flexible gap — `flexGrow: 1` by default, pushes its siblings apart. */
+export interface UISpacer extends UIElementBase<UISpacerStyle> {
   readonly type: "spacer",
-  style: Style<this, UISpacerStyle>,
-
-  /** 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>
 }
+/** 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 {

package/runtime/sdk/ui/UITabs.ts

@@ -0,0 +1,175 @@
+import { PagerElement, type UIPager } from "./UIPager"
+import { ScreenElement, type 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"
+
+// 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.
+// The build-mode twin of the design scaffold's `defineTabs` (lecodes-design/tabbar-surface.md):
+// same keyed config, same `tab-<id>` button names, same theme variables with the same fallbacks,
+// 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
+}

package/runtime/sdk/ui/UIText.ts

@@ -1,22 +1,13 @@
 import { createBinding } from "../core/signals"
-import { Element, type AnimateStyle, type BaseStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style, type TextStyle } from "./UINode"
+import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type TextStyle, type UIElementBase } from "./UINode"
 
 export type UITextStyle = ElementStyle & TextStyle & DrawableStyle
 
-export interface UIText {
+/** A text label. */
+export interface UIText extends UIElementBase<UITextStyle, DrawableStyle & BaseStyle & TextStyle> {
   readonly type: "text",
+  /** The displayed string — writable at any time. */
   text: string,
-  style: Style<this, UITextStyle>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle & TextStyle>
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle & TextStyle>
-
-  onLayout(onLayout: OnLayoutCallback): this
-  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>
 }
 
 export class TextElement extends Element<"text"> {
@@ -46,7 +37,10 @@ export 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 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) {

package/runtime/sdk/ui/UIVideo.ts

@@ -1,31 +1,27 @@
 import type { VideoPlayer } from "../runtime/media"
 import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
-import { Element, type AnimateStyle, type AppearStyle, type BaseStyle, type DisappearStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style, type StyleFn } from "./UINode"
+import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode"
 
 export type UIVideoStyle = ElementStyle & DrawableStyle & { objectFit?: "cover" | "contain" | "fill" }
 
-export interface UIVideo {
+/** 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
-  style: Style<this, UIVideoStyle>
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
 
   /** 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
-
-  onLayout(onLayout: OnLayoutCallback): this
-  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>
 }
 
 class VideoElement extends Element<"video"> implements Presentable {
@@ -79,7 +75,9 @@ class VideoElement extends Element<"video"> implements Presentable {
   }
 }
 
+/** 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) {

package/runtime/sdk/ui/UIVirtualizedList.ts

@@ -1,75 +1,78 @@
-import { Element, type Color, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type Classes, type Style, type UINodeChild } from "./UINode"
+import { Element, type Color, type DrawableStyle, type ElementStyle, type UIElementBase, type UINodeChild } from "./UINode"
 
-// refreshControlColor tints the native pull-to-refresh spinner (pairs with onRefresh).
-// keyboardDismissMode: same key and semantics as UIScrollable's — hosts treat a vlist as a scroll
-// container, so it always honored this; only the type was missing. A chat is the reason it exists:
-// "none" keeps the composer's keyboard up no matter how the history is scrolled.
 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
-    /**
-     * Оценка высоты (px) до первого измерения. Число — или функция от айтема,
-     * например для чата: msg => 40 + Math.ceil(msg.text.length / 35) * 20
-     * Вычисляется один раз при добавлении айтема, в нативку уходит готовое число.
-     */
+    /** 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)
-    /** px вокруг вьюпорта, которые держим смонтированными. Default: высота вьюпорта */
+    /** Extra px around the viewport kept mounted. Default: one viewport height. */
     overscan?: number
-    /** Чат-режим: первый layout проскроллен в конец, append при положении внизу автоскроллит */
+    /** Chat mode: the first layout starts scrolled to the end, and appends auto-scroll while the
+     *  list sits at the bottom. */
     inverted?: boolean
 }
 
-export interface UIVirtualizedList<T = unknown> {
+/** 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"
-    style: Style<this, UIVirtualizedListStyle>
 
-    /** Полная замена данных. Нативка сама размонтирует исчезнувшие ключи через _syncWindow */
+    /** 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
-    /** Обновить айтемы с теми же ключами: re-render, если смонтированы. Высота в кэше сохраняется до повторного измерения */
+    /** 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: спиннер держится, пока не разрешится промис. Навесить ДО маунта
-     *  (нативка читает при создании ноды). Только native-хосты; на вебе no-op. */
+    /** 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
-    /** Порог в px от нижнего края контента. Срабатывает один раз до ухода от края (защёлка в нативке) */
+    /** 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
-    onLayout(onLayout: OnLayoutCallback): this
-    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>
 }
 
 export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedList<T> {
 
-    // --- читается нативкой в createUINode (copyProperty / copyNodePtr) ---
-    _overscan: number               // -1 = "высота вьюпорта", резолвится в нативке
+    // --- read by native side in createUINode (copyProperty / copyNodePtr) ---
+    _overscan: number
     _inverted: boolean
-    _keys: string[] = []            // начальное состояние до маунта ноды
-    _estimates: number[] = []       // параллельно _keys
+    _keys: string[] = [] 
+    _estimates: number[] = [] 
     _endThreshold = 0
     _startThreshold = 0
 
@@ -123,12 +126,8 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
         this._keys = keys
         this._estimates = estimates
         if (this.isAttached) {
-            // нативка диффает по ключам: исчезнувшие смонтированные ключи придут в _syncWindow как unmount
             _creatorUI.vlistSetKeys(this, keys, estimates)
-            // setKeys диффает ТОЛЬКО по ключам — пережившие replace смонтированные айтемы сохраняют
-            // старое поддерево. Если объект данных изменился, перерисовываем их (как update), иначе
-            // строки остаются со старым содержимым. На вебе экран в истории держит айтемы
-            // смонтированными, поэтому без этого повторный setData их не обновлял.
+
             for (const k of prevMounted) {
                 if (this.mounted.has(k) && this.items.get(k) !== prevItems.get(k)) {
                     _creatorUI.vlistInvalidate(this, k)
@@ -143,7 +142,6 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
         this._keys.push(...keys)
         this._estimates.push(...estimates)
         if (this.isAttached) {
-            // inverted + позиция внизу → нативка автоскроллит к концу
             _creatorUI.vlistInsertKeys(this, -1, keys, estimates)
         }
         return this
@@ -154,7 +152,6 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
         this._keys.unshift(...keys)
         this._estimates.unshift(...estimates)
         if (this.isAttached) {
-            // нативка компенсирует scrollY на сумму estimates — позиция не прыгает
             _creatorUI.vlistInsertKeys(this, 0, keys, estimates)
         }
         return this
@@ -166,8 +163,6 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
             if (!this.items.has(k)) continue
             this.items.set(k, item)
             if (this.isAttached && this.mounted.has(k)) {
-                // unmount+mount, кэш высоты сохраняется до повторного измерения.
-                // Несмонтированный айтем перерендерится сам при входе в окно
                 _creatorUI.vlistInvalidate(this, k)
             }
         }
@@ -221,12 +216,9 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
         return this
     }
 
-    /**
-     * Единственный колбэк из нативки (через jsPtr, как у button).
-     * Вызывается ТОЛЬКО когда окно пересекло границу — не на каждый кадр скролла.
-     * Порядок: сначала unmount (нативка уже снесла поддеревья и обнулила _id,
-     * здесь только чистим JS-ссылки), потом mount.
-     */
+    /** @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)
@@ -242,6 +234,8 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
     }
 }
 
+/** 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)
 }