lecodes-cli 0.10.4 → 0.11.0

package/runtime/sdk/ui/UINode.ts

@@ -10,10 +10,19 @@ export interface UINode {
   readonly class: Classes<this>
 }
 
+/** A child slot value: a node, or falsy (conditional rendering — falsy entries are skipped). */
 export type UINodeChild = UINode | null | undefined | false
 
+/** A factory child argument: a node (or falsy for conditionals), or an array of them — arrays are
+ *  flattened one level at the argument position, so `UIColumn(header, items.map(row), footer)`
+ *  needs no spread. */
+export type UIChildArg = UINodeChild | UINodeChild[]
+
+/** A color: CSS-style string (`"#1c1c1e"`, `"rgba(0,0,0,0.5)"`, `"var(--primaryColor)"`) or
+ *  packed number; `null` clears. */
 export type Color = number | string | null
 
+/** Style props every element accepts. */
 export type BaseStyle = {
   opacity?: number | `${number}`,
   transform?: string | null,
@@ -29,6 +38,7 @@ export type BaseStyle = {
   name?: string,
 }
 
+/** Painted-box props: background, gradient, border, radius. */
 export type DrawableStyle = {
   backgroundImage?: FetchResponse | File | string | null,
   bgGradient?: string,
@@ -62,6 +72,7 @@ export type DrawableStyle = {
   pointerEvents?: "all" | "none",
 }
 
+/** Flex-layout props of a container (how it lays out its children). */
 export type ContainerStyle = {
   flexDirection?: "row" | "column",
   justifyContent?: "flex-start" | "center" | "flex-end" | "space-between" | "space-evenly",
@@ -70,6 +81,7 @@ export type ContainerStyle = {
   flexWrap?: "nowrap" | "wrap" | "wrap-reverse"
 }
 
+/** A dimension: a number (logical px) or a CSS-style unit / function string. */
 type UIValue = number |
   `${number}px` |
   `${number}vw` |
@@ -84,6 +96,8 @@ type UIValue = number |
   `clamp(${string})` |
   `var(--${string})`
 
+/** Padding, with `p`/`px`/`pl`… shorthands. `safe-*` insets by the device safe area,
+ *  `comfort-*` by the theme's comfort knobs (max of both). */
 export type PaddingStyle = {
   paddingLeft?: UIValue | "safe-left" | "comfort-left",
   paddingTop?: UIValue | "safe-top" | "comfort-top",
@@ -102,8 +116,7 @@ export type PaddingStyle = {
   py?: UIValue | "comfort-y",
 }
 
-
-
+/** Margin, with `m`/`mx`/`ml`… shorthands; `"auto"` centers/pushes like CSS. */
 export type MarginStyle = {
   marginLeft?: UIValue | "auto" | "safe-left" | "comfort-left",
   marginTop?: UIValue | "auto" | "safe-top" | "comfort-top",
@@ -122,6 +135,7 @@ export type MarginStyle = {
   my?: UIValue | "auto" | "comfort-y",
 }
 
+/** Box position (for `position: "absolute"`) and size constraints. */
 export type PositionStyle = {
   top?: UIValue | `${number}%` | 'safe-top' | 'comfort-top',
   left?: UIValue | `${number}%` | 'safe-left' | 'comfort-left',
@@ -137,6 +151,7 @@ export type PositionStyle = {
   minHeight?: UIValue | `${number}%` | "auto",
 }
 
+/** The base style of every element: box + flex-child props. */
 export type ElementStyle = PaddingStyle & MarginStyle & BaseStyle & PositionStyle & {
   position?: "absolute" | "static" | "relative",
   aspectRatio?: number,
@@ -148,6 +163,7 @@ export type ElementStyle = PaddingStyle & MarginStyle & BaseStyle & PositionStyl
   display?: "none" | "flex"
 }
 
+/** Typography props. */
 export type TextStyle =  {
   textAlign?: "start" | "center" | "end" | "left" | "right"
   fontFamily?: string,
@@ -189,7 +205,7 @@ function applyBindings(el: any, fns: [string, () => any][]) {
   }
 }
 
-// Не надо переписывать эту функцию 10 раз, обрати внимание, что у тебя тут возвращается this
+// NB: returns `this` — `.style()` must chain. Don't rewrite.
 function styleFunction(this: any, newStyle: any) {
   // `name` is a JS-node selector (read by hosts off el.name), not a layout property — extract it
   // exactly like the constructor so `.style({ name })` is equivalent to the first-arg style. Left
@@ -305,26 +321,21 @@ const classHandler: ProxyHandler<any> = {
   }
 }
 
-function Style() {
-
-}
-
-// Reactive style input: every primitive-valued prop also accepts a `() => value` binding that
-// re-applies when a signal it read changes. Nested state blocks (onPressed, onLandscape, …) stay
-// static — bindings are extracted at the top level only.
+/** Reactive style input: every primitive-valued prop also accepts a `() => value` binding that
+ *  re-applies when a signal it read changes. Nested state blocks (onPressed, onLandscape, …) stay
+ *  static — bindings are extracted at the top level only. */
 export type Reactive<T> = { [K in keyof T]: NonNullable<T[K]> extends object ? T[K] : T[K] | (() => T[K]) }
 
-// User-defined style classes: any `$`-prefixed key in .style() declares a state block (like
-// onPressed, but with any name), toggled from code via the `el.class` proxy. `duration`/`delay`
-// make the swap transition. Class state INHERITS down the tree (CSS-`.dark`-on-body style): a
-// class set on a node also activates same-name `$` blocks on all descendants within the same
-// root — see docs/style-class-cascade-plan.md. `$pressed`/`$focused` are reserved: hosts toggle
-// them on press/focus (they beat other classes, lose to onPressed/onFocused), so children can
-// react to an ancestor's press. Instantiate with the node's own style `T` (see StyleFn below) — a
-// class block accepts everything the node's `.style()` does (e.g. `color` on text, layout on any
-// node), exactly like `onLandscape`/`onPortrait`. Narrowing it (it once was `DrawableStyle &
-// BaseStyle`) wrongly rejected valid props such as `$active: { color }`. Guarded by
-// tests/ui-types.test.ts.
+/** User-defined style classes: any `$`-prefixed key in `.style()` declares a state block toggled
+ *  from code via the `el.class` proxy; `duration`/`delay` animate the swap. Class state INHERITS
+ *  down the tree (CSS-`.dark`-on-body style): a class set on a node also activates same-name `$`
+ *  blocks on all descendants within the same root (docs/style-class-cascade-plan.md).
+ *  `$pressed`/`$focused` are reserved — hosts toggle them on press/focus (they beat other
+ *  classes, lose to onPressed/onFocused), so children can react to an ancestor's press.
+ *
+ *  Instantiated with the node's FULL style `T` — a class block accepts everything the node's
+ *  `.style()` does, like `onLandscape`. Narrowing it wrongly rejects valid props such as
+ *  `$active: { color }`; guarded by tests/ui-types.test.ts. */
 export type ClassStyles<T> = { [key: `$${string}`]: T & { duration?: number, delay?: number } }
 
 /** Value accepted by a `el.class` write: a boolean sets the class, a `() => boolean` binds it —
@@ -351,15 +362,9 @@ export type ClassValue = boolean | (() => boolean)
  *  single-key writes are runtime-coerced with `!!`. */
 export type Classes<R> = ((classes: Record<string, ClassValue>) => R) & { [key: string]: any }
 
-// NB: do NOT annotate `this: R` here. `this` is a parameter position, so it makes R contravariant,
-// which makes every node type INVARIANT in its own type params (and in `this`). That is what made
-// `UIScreen<false>` unassignable to `UIScreen<boolean>` (a navigator page), and would block any
-// UINode subtype from being assignable to its base. Runtime `this` is already fixed by the
-// `styleFunction.bind(this)` in the `style` getter — the annotation bought nothing and cost variance.
-// R stays only in the (covariant) return, so `.style()` still returns the concrete node type for
-// chaining. Guarded by the type tests in tests/ui-types.test-d.ts.
-// Orientation state blocks — override props applied only in landscape / portrait (like a `$`-class,
-// keyed by device orientation instead of `el.class`). Same full-`T` rule as class blocks.
+/** Orientation state blocks — override props applied only in landscape / portrait (like a
+ *  `$`-class, keyed by device orientation instead of `el.class`). Same full-`T` rule as class
+ *  blocks. */
 export type OrientationStyles<T> = {
   onLandscape?: T,
   onPortrait?: T,
@@ -368,11 +373,19 @@ export type OrientationStyles<T> = {
   onPortait?: T,
 }
 
+// NB: do NOT annotate `this: R` on StyleFn. As a parameter it makes R contravariant, turning every
+// node type INVARIANT (UIScreen<false> stopped being assignable to UIScreen<boolean>). Runtime
+// `this` is already fixed by `styleFunction.bind(this)`; R stays covariant in the return, so
+// `.style()` still chains. Guarded by tests/ui-types.test-d.ts.
 export type StyleFn <R, T extends object> = ((style: Reactive<T> & OrientationStyles<T> & ClassStyles<T>) => R)
+
+/** The `el.style` surface: callable — `.style({...})` merges and returns the element for
+ *  chaining — and per-key readable/writable (`el.style.opacity = 0.5`; a `() => value` write
+ *  installs a reactive binding). */
 export type Style <R, T extends object> = StyleFn<R,T> & T & OrientationStyles<T> & ClassStyles<T>
 
-// The options bag of animateTo/animateFrom: the target style plus flat meta keys. Meta keys are
-// stripped before the commit into _style and skipped by the hosts' style staging.
+/** The `animateTo`/`animateFrom` surface: target style props plus the flat meta keys below
+ *  (stripped before the commit into the element's style). */
 export type AnimateStyle<R, T extends object> = ((style: T & {
   /** Tween length in **milliseconds** (default 225). */
   duration?: number,
@@ -397,10 +410,11 @@ const ANIMATE_META = new Set(["duration", "delay", "layer", "commit", "loop", "l
 export type AppearStyle <R, T> = (arg: { from: T, duration?: number, delay?: number }) => R
 export type DisappearStyle <R, T> = (arg: { to: T, duration?: number, delay?: number }) => R
 
+/** `onLayout` payload — the node's box in PARENT-relative coordinates. */
 export type OnLayoutCallback = (layout: { left: number, top: number, width: number, height: number }) => void
 
-// Web-DOMRect shape on purpose (getBoundingClientRect priors must hold): all eight fields, with
-// right/bottom/x/y derived SDK-side so hosts only report [left, top, width, height].
+/** Web-DOMRect shape on purpose (getBoundingClientRect priors must hold): all eight fields, with
+ *  right/bottom/x/y derived SDK-side — hosts only report [left, top, width, height]. */
 export type BoundingClientRect = {
   x: number, y: number,
   left: number, top: number, right: number, bottom: number,
@@ -462,10 +476,10 @@ export class Element<T extends string> {
     return proxy
   }
 
+  /** Tween to the target style and commit it (unless `commit: false` or looping — a loop is an
+   *  effect, not a state change). Meta keys: `duration`/`delay`/`loop`/… — see {@link AnimateStyle}. */
   animateTo(style: any): this{
     _creatorUI.animateTo(this._id, style)
-    // A loop is an effect, not a state change — looping animations never commit. Meta keys
-    // (duration/delay/…) stay out of the stored style.
     if (style.commit !== false && !style.loop) {
       for (const key in style) {
         if (!ANIMATE_META.has(key)) this._style[key] = style[key]
@@ -473,6 +487,7 @@ export class Element<T extends string> {
     }
     return this
   }
+  /** Tween FROM the given style to the element's current one (entrance animations). */
   animateFrom(style: any): this{
     _creatorUI.animateFrom(this._id, style)
     return this
@@ -511,6 +526,7 @@ export class Element<T extends string> {
   }
 
   protected ll?: OnLayoutCallback[]
+  /** Observe layout: fires after every host layout pass with the parent-relative box. */
   onLayout(onLayout: OnLayoutCallback): this {
     if (this.ll) {
       this.ll.push(onLayout)
@@ -536,6 +552,8 @@ export class Element<T extends string> {
 
 // ---- reactive children --------------------------------------------------------------------------
 
+/** Reactive children: re-runs when a signal it read changes; the result is reconciled against
+ *  the mounted children (kept nodes stay mounted, state intact). */
 export type ChildrenFn = () => UINodeChild[]
 
 // The container whose children binding is currently executing. __uiMap uses it as the cache owner;
@@ -580,6 +598,53 @@ export function __uiMap(list: any, render: (item: any, index: number) => any, sl
   return out
 }
 
+// ---- factory argument dispatch ------------------------------------------------------------------
+
+/** @internal Shared argument dispatch for the UI factories (`UIRow(...)`, `UIButton(...)`, …).
+ *  Children are variadic; an array argument is flattened one level, so both the legacy
+ *  `UIColumn([a, b])` and `UIColumn(header, items.map(row), footer)` work. A lone function
+ *  argument is a reactive {@link ChildrenFn}. A plain non-node object in first position is the
+ *  legacy style bag: it is spread over `defaults`, or — when `defaults` is null — stored as-is
+ *  (the Element constructor mutates it in place, matching the old path). The rest-args array is
+ *  taken over as the children array when nothing needs flattening — callers must hand it off. */
+export function buildUI<R>(args: any[], defaults: any, make: (style: any, children: any[] | ChildrenFn) => R): R {
+  const n = args.length
+  const a0 = n > 0 ? args[0] : undefined
+  let style: any
+  let start = 0
+  if (a0 !== null && typeof a0 === "object" && !Array.isArray(a0) && !(a0 instanceof Element)) {
+    style = defaults ? { ...defaults, ...a0 } : a0
+    start = 1
+  } else {
+    style = defaults ? { ...defaults } : {}
+  }
+  if (n === start + 1) {
+    const a = args[start]
+    // lone function → reactive children; lone array → used as the children array directly
+    // (the legacy zero-copy path — nested arrays inside it are NOT flattened)
+    if (typeof a === "function" || Array.isArray(a)) return make(style, a)
+  }
+  // Single pass: reuse the rest-args array as the children array until the first array argument
+  // shows up, then copy the prefix once and flatten from there. Falsy entries stay — they are
+  // compacted at mount like always.
+  let flat: any[] | undefined
+  for (let i = start; i < n; i++) {
+    const a = args[i]
+    if (flat === undefined) {
+      if (Array.isArray(a)) {
+        flat = args.slice(start, i)
+        for (let j = 0; j < a.length; j++) flat.push(a[j])
+      }
+    } else if (Array.isArray(a)) {
+      for (let j = 0; j < a.length; j++) flat.push(a[j])
+    } else {
+      flat.push(a)
+    }
+  }
+  if (flat !== undefined) return make(style, flat)
+  return make(style, start === 0 ? args : args.slice(1))
+}
+
 export class ContainerElement<T extends string> extends Element<T> {
   children: any[] = []
 
@@ -641,6 +706,7 @@ export class ContainerElement<T extends string> extends Element<T> {
     }
   }
 
+  /** Append children (falsy entries are kept in the array but never mounted). */
   append(...nodes: UINodeChild[]): this {
     if (this._id === 0) {
       this.children.push(...nodes)
@@ -660,6 +726,7 @@ export class ContainerElement<T extends string> extends Element<T> {
     this.children.push(...nodes)
     return this
   }
+  /** Insert children at `index` of the children array. */
   insert(index: number, ...nodes: UINodeChild[]): this {
     if (this._id === 0) {
       this.children.splice(index, 0, ...nodes)
@@ -680,6 +747,7 @@ export class ContainerElement<T extends string> extends Element<T> {
     this.children.splice(index, 0, ...nodes)
     return this
   }
+  /** Remove (unmount) the given children. */
   remove(...nodesToDelete: UINode[]): this {
     const set = new Set(nodesToDelete)
 
@@ -704,6 +772,7 @@ export class ContainerElement<T extends string> extends Element<T> {
     return this
   }
   
+  /** Replace all children — a plain array, or a function for reactive children. */
   setContent(children: UINodeChild[] | ChildrenFn): this {
     if (typeof children === "function") {
       this._bindChildren(children)   // createBinding replaces a previous "#children" binding

package/runtime/sdk/ui/UIPager.ts

@@ -104,7 +104,10 @@ export class PagerElement extends ContainerElement<"pager"> {
   private ncl: ((depth: number) => void)[] = []   // onChange listeners
 
   constructor(style: UIPagerStyle | null, tabs: UIScreen[]) {
-    super("pager", style ?? {}, tabs as any)
+    // flexShrink: 1 default (SDK-owned, like UIScrollable's): pages are separate layout roots
+    // sized to the pager's box, so yoga sees no shrinkable content — without this a pager in a
+    // flex column overflows the screen instead of leaving room for the tab bar.
+    super("pager", { flexShrink: 1, ...style }, tabs as any)
     this._lens = tabs.map(() => 1)
     for (const s of this.children) this._track(s)
   }
@@ -294,13 +297,13 @@ const isScreenArg = (v: any): boolean => v != null && typeof v === "object" && v
 /** Callable factory + ambient statics. The name `UIPager` is a value (this factory) and a type
  *  (the instance interface above) — a standard value/type merge. */
 interface UIPagerConstructor {
-  /** One tab — a plain navigation stack rooted at `root` (push/pop, no tab swiping). */
-  (root: UIScreen): UIPager
-  /** Sibling tabs, one per screen, in order — swipe (or `select`) between them. Tabs are fixed
-   *  at construction; each starts as its own one-screen stack. */
-  (tabs: UIScreen[]): UIPager
-  /** Styled pager + content (a single root screen or an array of tab screens). */
-  (style: UIPagerStyle, content: UIScreen | UIScreen[]): UIPager
+  /** Tabs — each argument is a screen or an array of screens (arrays flatten one level, falsy
+   *  entries are skipped). One screen → a plain navigation stack rooted at it (push/pop, no tab
+   *  swiping); several → swipeable sibling tabs, fixed at construction, each starting as its own
+   *  one-screen stack. */
+  (...tabs: (UIScreen | UIScreen[] | false | null | undefined)[]): UIPager
+  /** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+  (style: UIPagerStyle, content?: UIScreen | UIScreen[]): UIPager
   /** The pager that owns the currently visible screen, or `null` when the visible screen isn't
    *  hosted by one. With pagers nested inside pages, resolves to the **innermost** — so ambient
    *  calls act on the pager the user is actually looking at. */
@@ -316,14 +319,23 @@ interface UIPagerConstructor {
 }
 
 function pagerFactory(...args: any[]): UIPager {
-  if (args.length === 1) {
-    const a = args[0]
-    if (Array.isArray(a)) return new PagerElement(null, a) as unknown as UIPager
-    if (isScreenArg(a)) return new PagerElement(null, [a]) as unknown as UIPager
-    return new PagerElement(a, []) as unknown as UIPager
+  let style: any = null
+  let start = 0
+  const a0 = args.length > 0 ? args[0] : undefined
+  if (a0 != null && typeof a0 === "object" && !Array.isArray(a0) && !isScreenArg(a0)) {
+    style = a0
+    start = 1
   }
-  const content = args[1]
-  return new PagerElement(args[0] ?? null, Array.isArray(content) ? content : content ? [content] : []) as unknown as UIPager
+  const tabs: any[] = []
+  for (let i = start; i < args.length; i++) {
+    const a = args[i]
+    if (Array.isArray(a)) {
+      for (let j = 0; j < a.length; j++) if (a[j]) tabs.push(a[j])
+    } else if (a) {
+      tabs.push(a)
+    }
+  }
+  return new PagerElement(style, tabs) as unknown as UIPager
 }
 
 /**

package/runtime/sdk/ui/UIPopover.ts

@@ -1,7 +1,7 @@
 import { ModalElement, type UIModal, type UIModalStyle } from "./UIModal"
 import { Presentable } from "./presentable"
 import { device } from "../runtime/device"
-import type { BoundingClientRect, ChildrenFn, UINodeChild } from "./UINode"
+import { buildUI, type BoundingClientRect, type ChildrenFn, type UIChildArg, type UINodeChild } from "./UINode"
 
 export type UIPopoverStyle = UIModalStyle
 
@@ -87,20 +87,14 @@ export class PopoverElement extends ModalElement {
   }
 }
 
-export function UIPopover(): UIPopover;
+const makePopover = (style: any, children: any) => new PopoverElement(style, children)
+
+/** Create an anchored popover (see {@link UIPopover}) — create once at module scope, then
+ *  `show(anchor)` next to an element or `{x, y}` point. Same argument forms as `UIColumn`. */
+export function UIPopover(...children: UIChildArg[]): UIPopover;
 export function UIPopover(children: UINodeChild[] | ChildrenFn): UIPopover;
-export function UIPopover(style: UIPopoverStyle): UIPopover;
-export function UIPopover(style: UIPopoverStyle, children: UINodeChild[] | ChildrenFn): UIPopover;
-export function UIPopover(...args: [] | [UINodeChild[] | ChildrenFn | UIPopoverStyle] | [UIPopoverStyle, children: UINodeChild[] | ChildrenFn]): UIPopover {
-  if (args.length === 0) {
-    return new PopoverElement({}, [])
-  } else if (args.length === 1) {
-    if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new PopoverElement({}, args[0])
-    } else {
-      return new PopoverElement(args[0], [])
-    }
-  } else {
-    return new PopoverElement(args[0], args[1])
-  }
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIPopover(style: UIPopoverStyle, children?: UINodeChild[] | ChildrenFn): UIPopover;
+export function UIPopover(...args: any[]): UIPopover {
+  return buildUI(args, null, makePopover)
 }

package/runtime/sdk/ui/UIScreen.ts

@@ -1,14 +1,13 @@
 import { TouchStartEvent } from "../runtime/touch"
 import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
-import { ContainerElement, type AnimateStyle, type BaseStyle, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type Classes, type Style, type UINodeChild, type ChildrenFn, } from "./UINode"
+import { ContainerElement, buildUI, type AnimateStyle, type BaseStyle, type ContainerStyle, type DrawableStyle, type OnLayoutCallback, type BoundingClientRect, type PaddingStyle, type Classes, type Style, type UIChildArg, type UINodeChild, type ChildrenFn, } from "./UINode"
 
 export type UIScreenStyle = ContainerStyle & DrawableStyle & PaddingStyle & BaseStyle
 
-// A screen — the root the router/host mounts, sized to its slot. A screen NEVER scrolls: it is
-// fixed chrome (header, tab bar) plus, when the content overflows, one `UIScrollable` body child
-// (`flexGrow: 1`). Scroll events and pull-to-refresh live on the scroll containers
-// (`UIScrollable`, `UIVirtualizedList`) — see docs/scroll-forms-plan.md (the former
-// `makeScrollable()` screen mode was removed 2026-07-22).
+/** A screen — the root the router/host mounts, sized to its slot. A screen NEVER scrolls: it is
+ *  fixed chrome (header, tab bar) plus, when the content overflows, one `UIScrollable` body child
+ *  (`flexGrow: 1`). Scroll events and pull-to-refresh live on the scroll containers
+ *  (`UIScrollable`, `UIVirtualizedList`). */
 export interface UIScreen {
   readonly type: "screen",
   style: Style<this, UIScreenStyle>,
@@ -27,9 +26,12 @@ export interface UIScreen {
 
   readonly children: UINodeChild[],
 
+  /** Hardware/system back while this screen is current. */
   onBackPressed(callback: () => void): this
 
+  /** The screen became the visible destination (first open, or revealed by a pop). */
   onOpen(callback: () => void): this
+  /** The screen stopped being visible — closed, replaced, or covered by a push. */
   onClose(callback: () => void): this
 
   /**
@@ -121,20 +123,17 @@ export class ScreenElement extends ContainerElement<"screen"> {
   }
 }
 
-export function UIScreen(): UIScreen;
+const makeScreen = (style: any, children: any) => new ScreenElement("screen", style, children)
+
+/** @internal Compiler fast path (chisel `flatten_ui` raw lowering) — see UIContainer. */
+export const __UIScreen = (children: UINodeChild[] | ChildrenFn): UIScreen => makeScreen({}, children)
+
+/** Create a screen. Present it with `.open()`, or via `Router` / `UIPager`. Same argument forms
+ *  as `UIColumn`. */
+export function UIScreen(...children: UIChildArg[]): UIScreen;
 export function UIScreen(children: UINodeChild[] | ChildrenFn): UIScreen;
-export function UIScreen(style: UIScreenStyle): UIScreen;
-export function UIScreen(style: UIScreenStyle, children: UINodeChild[]): UIScreen;
-export function UIScreen(...args: [] | [UINodeChild[] | ChildrenFn | UIScreenStyle] | [UIScreenStyle, children: UINodeChild[] | ChildrenFn]): UIScreen {
-  if (args.length === 0) {
-    return new ScreenElement("screen", {}, [])
-  } else if (args.length === 1) {
-    if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new ScreenElement("screen", {}, args[0])
-    } else {
-      return new ScreenElement("screen", args[0], [])
-    }
-  } else {
-    return new ScreenElement("screen", args[0], args[1])
-  }
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIScreen(style: UIScreenStyle, children?: UINodeChild[] | ChildrenFn): UIScreen;
+export function UIScreen(...args: any[]): UIScreen {
+  return buildUI(args, null, makeScreen)
 }

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 {