lecodes-cli 0.10.4 → 0.11.0

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,41 +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).
-// 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
 }
 
+/** 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
 
@@ -47,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
@@ -65,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
 
@@ -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)
 }

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>,
@@ -33,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
@@ -47,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
@@ -120,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
 }

package/runtime/sdk/ui/theme.ts

@@ -1,29 +1,7 @@
-// theme() — app theme variables (docs/ui-theme-plan.md).
-//
-// One global variable table lives in the UI core. Styles reference entries with CSS syntax —
-// `color: "var(--primaryColor)"` — resolved at style-apply time in the core, so re-calling
-// theme() with new values re-styles the LIVE UI (dark mode is just a second call). Two access
-// forms with one rule: bare style tokens (`pt: "comfort-top"`) are keywords that may expand to
-// formulas (max(safe-top, knob)); `var(--comfort-top)` always reads the raw table value (the
-// knob itself).
-//
-// theme(values) MERGES into the table and returns typed accessors whose values ARE the var()
-// strings — define once in a module, import where custom keys need typing:
-//
-//   export const T = theme({ primaryColor: "#0A84FF", cardBg: "#1C1C1E" })
-//   card.style({ bgColor: T.cardBg })            // T.cardBg === "var(--cardBg)"
-//
-// System vars need no import — they're static properties on the callable itself:
-// theme.primaryColor, theme.fontFamily, theme["comfort-top"], …
-//
-// Values: strings pass through (colors, fonts, expressions like "max(safe-top, 24px)");
-// numbers are LENGTHS (px). `null` removes a key (comfort knobs reset to their defaults:
-// 12 vertical, 16 horizontal — the page gutter). Env names (safe-*, vw/vh/vmin/vmax) are
-// host-owned facts, never theme keys — they're skipped with a warning.
-//
-// One key is not a style var: `replaceTransition` — the app-wide default for
-// `Router.replace` (any Transition, name or custom spec; `null` resets to "none"). The
-// router resolves it in the SDK, so it's consumed here and never sent to the host table.
+// theme() — app theme variables (docs/ui-theme-plan.md). One global var table lives in the UI
+// core; `var(--key)` references resolve at style-apply time, so re-calling theme() re-styles the
+// LIVE UI. Bare style tokens (`pt: "comfort-top"`) are keywords that may expand to formulas
+// (max(safe-top, knob)); `var(--comfort-top)` always reads the raw table value.
 
 import type { Transition } from "./presentable"
 
@@ -41,10 +19,20 @@ export type ThemeAccessors<T> = {
 
 const RESERVED = ["safe-top", "safe-bottom", "safe-left", "safe-right", "vw", "vh", "vmin", "vmax"]
 
-/** Merge app theme variables and get typed `var(--key)` accessors back. Strings/numbers are
- *  style values (numbers = px); `null` removes a key. One special key: `replaceTransition` —
- *  the app-wide default transition for `Router.replace` (any transition name or custom spec;
- *  out of the box `"none"`). */
+/**
+ * Merge app theme variables into the live table and get typed `var(--key)` accessors back:
+ *
+ * ```ts
+ * export const T = theme({ primaryColor: "#0A84FF", cardBg: "#1C1C1E" })
+ * card.style({ bgColor: T.cardBg })   // T.cardBg === "var(--cardBg)"
+ * ```
+ *
+ * Strings pass through (colors, fonts, expressions like `"max(safe-top, 24px)"`); numbers are
+ * lengths (px); `null` removes a key (comfort knobs reset to their defaults). Env names
+ * (`safe-*`, `vw`/`vh`/…) are host-owned — skipped with a warning. One special key:
+ * `replaceTransition` — the app-wide default transition for `Router.replace` (consumed SDK-side,
+ * never sent to the host table).
+ */
 const setTheme = <T extends Record<string, string | number | Transition | null>>(
   // Only `replaceTransition` may carry a Transition — every other key is a style value.
   values: T & { [K in Exclude<keyof T, "replaceTransition">]: string | number | null }
@@ -73,6 +61,9 @@ const setTheme = <T extends Record<string, string | number | Transition | null>>
   return accessors as ThemeAccessors<Omit<T, "replaceTransition">>
 }
 
+/** App theme: callable to merge variables (`theme({...})` — re-calling re-styles the live UI, so
+ *  dark mode is just a second call), with the system vars as static properties
+ *  (`theme.primaryColor`, `theme["comfort-top"]`, …). */
 export const theme = Object.assign(setTheme, {
   /** The app accent color. Kit components will read it via `var(--primaryColor, <fallback>)`. */
   primaryColor: "var(--primaryColor)",