lecodes-cli 0.10.3 → 0.11.0

package/runtime/sdk/ui/UIScrollable.ts

@@ -1,19 +1,26 @@
 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"
-
-// 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" }
+import { type Classes, type Style, type AnimateStyle, type UIChildArg, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BoundingClientRect, type Color, ContainerElement, buildUI } 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 {
   readonly type: "scrollable",
   style: Style<this, UIScrollableStyle>,
@@ -33,8 +40,11 @@ export interface UIScrollable {
    *  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. */
@@ -76,22 +86,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

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

@@ -3,8 +3,10 @@ import { Element, type AnimateStyle, type BaseStyle, type DrawableStyle, type El
 
 export type UITextStyle = ElementStyle & TextStyle & DrawableStyle
 
+/** A text label. */
 export interface UIText {
   readonly type: "text",
+  /** The displayed string — writable at any time. */
   text: string,
   style: Style<this, UITextStyle>,
   animateTo: AnimateStyle<this, DrawableStyle & BaseStyle & TextStyle>
@@ -46,7 +48,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

@@ -4,8 +4,11 @@ import { Element, type AnimateStyle, type AppearStyle, type BaseStyle, type Disa
 
 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 {
   readonly type: "video",
+  /** The player driving this surface (playback control lives on it). */
   player: VideoPlayer
   style: Style<this, UIVideoStyle>
   animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
@@ -79,7 +82,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,35 +1,43 @@
 import { Element, type Color, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type Classes, type Style, type UINodeChild } from "./UINode"
 
-// refreshControlColor tints the native pull-to-refresh spinner (pairs with onRefresh).
-export type UIVirtualizedListStyle = DrawableStyle & ElementStyle & { refreshControlColor?: Color }
+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
 }
 
+/** 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> {
     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: 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
     removeByKey(...keys: string[]): this
 
@@ -41,12 +49,13 @@ export interface UIVirtualizedList<T = unknown> {
     scrollToEnd(animated?: boolean): void
 
     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
@@ -59,11 +68,11 @@ export interface UIVirtualizedList<T = unknown> {
 
 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
 
@@ -117,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)
@@ -137,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
@@ -148,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
@@ -160,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)
             }
         }
@@ -215,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)
@@ -236,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)
 }

package/runtime/sdk/ui/UIWidget.ts

@@ -1,15 +1,18 @@
 import { TouchStartEvent } from "../runtime/touch"
 import { _descOf, _navSupported, Presentable } from "./presentable"
-import { ContainerElement, type AnimateStyle, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type PositionStyle, type Classes, type Style, type UINodeChild, type ChildrenFn } from "./UINode"
+import { ContainerElement, buildUI, type AnimateStyle, type BaseStyle, type Color, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type PositionStyle, type Classes, type Style, type UIChildArg, type UINodeChild, type ChildrenFn } from "./UINode"
 
 
 export type UIWidgetStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle & PositionStyle & {
-  // A layer behind the widget that intercepts clicks. "transparent" still intercepts;
-  // null removes the layer. A tap on it fires onOverlayTap.
+  /** A layer behind the widget that intercepts clicks — `"transparent"` still intercepts, `null`
+   *  removes the layer. A tap on it fires `onOverlayTap`. */
   overlayColor?: Color | null
 }
 
 
+/** A floating overlay — absolutely positioned in device coordinates, mounted above the page as
+ *  its own layout root (never a child of what's underneath). The base of dialogs, toasts,
+ *  mini-players and scene HUDs; `UIModal`/`UIPopover`/`UIBottomSheet` build on it. */
 export interface UIWidget {
   readonly type: "widget",
   style: Style<this, UIWidgetStyle>,
@@ -23,7 +26,8 @@ export interface UIWidget {
    * (= 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.
+   * 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.)
    */
   attachTo(owner: Presentable | null): this,
 
@@ -32,8 +36,10 @@ export interface UIWidget {
    *  widget was attached via `attachTo(owner)`, it mounts on that page's layer instead and is
    *  only visible while the owner is presented. */
   show(): void,
+  /** Unmount the widget. */
   hide(): void,
 
+  /** Mounted right now (`show()` ran, `hide()` hasn't). */
   readonly isShow: boolean,
 
   append(...nodes: UINodeChild[]): UIWidget
@@ -46,7 +52,9 @@ export interface UIWidget {
   onLayout(onLayout: OnLayoutCallback): this
   getBoundingClientRect(): BoundingClientRect | null
   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. */
   onBackPressed(callback: () => void): this
 
   /** Style-class proxy — read `el.class.checked`, set `el.class.checked = true`, toggle with
@@ -119,20 +127,17 @@ export class WidgetElement extends ContainerElement<"widget"> {
 }
 
 
-export function UIWidget(): UIWidget;
+const makeWidget = (style: any, children: any) => new WidgetElement("widget", style, children)
+
+/** @internal Compiler fast path (chisel `flatten_ui` raw lowering) — see UIContainer. */
+export const __UIWidget = (children: UINodeChild[] | ChildrenFn): UIWidget => makeWidget({}, children)
+
+/** Create a widget (same argument forms as `UIColumn`). Position it with absolute-style props
+ *  (`top`/`left`/`bottom`/`right`), then `show()`/`hide()`. */
+export function UIWidget(...children: UIChildArg[]): UIWidget;
 export function UIWidget(children: UINodeChild[] | ChildrenFn): UIWidget;
-export function UIWidget(style: UIWidgetStyle): UIWidget;
-export function UIWidget(style: UIWidgetStyle, children: UINodeChild[]): UIWidget;
-export function UIWidget(...args: [] | [UINodeChild[] | ChildrenFn | UIWidgetStyle] | [UIWidgetStyle, children: UINodeChild[] | ChildrenFn]): UIWidget {
-  if (args.length === 0) {
-    return new WidgetElement("widget", {}, [])
-  } else if (args.length === 1) {
-    if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new WidgetElement("widget", {}, args[0])
-    } else {
-      return new WidgetElement("widget", args[0], [])
-    }
-  } else {
-    return new WidgetElement("widget", args[0], args[1])
-  }
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIWidget(style: UIWidgetStyle, children?: UINodeChild[] | ChildrenFn): UIWidget;
+export function UIWidget(...args: any[]): UIWidget {
+  return buildUI(args, null, makeWidget)
 }

package/runtime/sdk/ui/fonts.ts

@@ -3,6 +3,9 @@ type FontOptions = {
   style?: "normal" | "italic"
 }
 
+/** Register a font face from a URL at runtime under `fontFamily`; resolves once it's ready to
+ *  use in styles. For registry/project fonts prefer the compile-time `font()` macro — this is the
+ *  dynamic escape hatch. */
 export async function registerFont (fontFamily: string, url: string, options: FontOptions = {}): Promise<void> {
   return new Promise<void>((res, rej) => {
     _creatorUI.registerFont(fontFamily, url, options, res, rej)

package/runtime/sdk/ui/router.ts

@@ -11,8 +11,13 @@ type NavigateOptions = {
   transition?: Transition
 }
 
+/** Stack navigation over `Presentable` destinations. `init` once with the home page, then
+ *  `push`/`replace`/`pop`; the back gesture/button pops natively. A direct `page.open()` suspends
+ *  the router until `restore()`. */
 type Router = {
+  /** The top of the router stack (not necessarily what's on screen — see `Presentable.current`). */
   get current(): Presentable
+  /** Mount the router with `homePage` as the stack root — the app's navigation entry point. */
   init(homePage: Presentable, opts?: RouterOptions): void
   /** Push a destination onto the stack — a `UIScreen`, a `Scene`, a `Scene2D`, a `NativeView`,
    *  or a `UIVideo`. The back gesture/button pops it. Destinations with async preparation
@@ -20,11 +25,19 @@ type Router = {
    *  visible until they're ready, and a rejection (permission denied / superseded) leaves the
    *  stack untouched. */
   push(page: Presentable, opts?: NavigateOptions): void | Promise<void>
+  /** Swap the top of the stack for `page` — no back entry to the replaced one. */
   replace(page: Presentable, opts?: NavigateOptions): void | Promise<void>
+  /** Pop the top destination (the programmatic twin of the back gesture); `to` unwinds to a
+   *  stack index in one step. */
   pop(to?: number, opts?: NavigateOptions): void
+  /** Blank the router's page, keeping the stack — `restore()` brings it back. A destination
+   *  opened directly stays visible. */
   hide(): void
+  /** Re-present the stack top after `hide()` or a direct `open()` suspended the router. */
   restore(): void
 
+  /** `"change"` fires on every stack change — pushes, pops, and native back gestures — with the
+   *  new top destination. */
   addEventListener(channel: "change", callback: (page: Presentable) => void): void
   removeEventListener(channel: "change", callback: (page: Presentable) => void): void
 }