lecodes-cli 0.10.4 → 0.12.0

package/runtime/sdk/scene/grammar.ts

@@ -0,0 +1,85 @@
+// The scene-file literal grammar markers, shared by `.scene.ts` (defineScene, 3D) and
+// `.scene2d.ts` (defineScene2d, 2D): `use(Ctor, props)` aspect entries, `ref('name')` node
+// references, `make(fn, args)` code-built sources — plus the ref-resolution helpers both loaders
+// run. One implementation so the two formats can't drift; the engine-specific node/def types stay
+// in their own modules (defineScene.ts / defineScene2d.ts), which re-export these for user code.
+
+import type { Aspect, AspectCtor } from "../core/Aspect"
+import type { Node } from "../gl/Node"
+
+/** One aspect to attach, created by `use(Ctor, props)`. */
+export type AspectEntry<A extends Aspect<any, any> = Aspect<any, any>> = {
+  /** @internal grammar marker. */
+  readonly __use: true
+  ctor: AspectCtor<A>
+  props?: Partial<A>
+}
+
+/** Reference an aspect in a scene file: `aspects: [use(Physics, { motion: 'static' })]`. Props are
+ *  typechecked against the aspect's fields, exactly like `node.aspect(Ctor, props)`. */
+export const use = <A extends Aspect<any, any>>(ctor: AspectCtor<A>, props?: Partial<A>): AspectEntry<A> =>
+  ({ __use: true, ctor, props })
+
+/** A `make(fn, args)` source entry — see {@link make}. `N` is the node family the factory returns
+ *  (3D `Node` by default; a `.scene2d.ts` file's factories return `Node2D`). */
+export type MakeEntry<A extends Record<string, unknown> = Record<string, unknown>, N = Node> = {
+  /** @internal grammar marker. */
+  readonly __make: true
+  fn: (args: A) => N | Promise<N>
+  args?: A
+}
+
+/**
+ * A code-created source in a scene file: `tower: { make: make(buildTower, { floors: 5 }), … }`.
+ * The factory runs after every scene node exists (so `ref()` args resolve, forward references
+ * included) and its returned subtree mounts under the def node — the def's transform stays
+ * editor-owned, so moving the node never re-calls the factory. Args must be literal data (same
+ * grammar as aspect props); in the editor they edit as fields, and an arg change re-CALLS the
+ * factory live — the code is already in the bundle, so no compile happens. Keep factories pure
+ * builders: same args → same subtree, no side effects outside the returned nodes.
+ */
+export const make = <A extends Record<string, unknown>, N>(
+  fn: (args: A) => N | Promise<N>, args?: A,
+): MakeEntry<A, N> => ({ __make: true, fn, args })
+
+/**
+ * Reference another scene node by name in an aspect's props:
+ * `use(Road, { from: ref('pointA'), to: ref('pointB') })`. Resolves to the live node when aspects
+ * attach — after EVERY node of the scene exists, so forward references work. An unknown name
+ * resolves to `null` (type your aspect field `Node | null`). Scene files only — hand-written code
+ * passes nodes directly: `node.aspect(Road, { from: nodes.pointA })`.
+ */
+export const ref = <T = Node>(name: string): T => ({ $ref: name } as unknown as T)
+
+export const isNodeRef = (v: unknown): v is { $ref: string } =>
+  typeof v === "object" && v !== null && typeof (v as { $ref?: unknown }).$ref === "string"
+
+/** Swap `ref()` markers in aspect props for the live nodes (top level + one array level deep). */
+export const resolveRefs = <N>(
+  props: Record<string, unknown> | undefined, nodes: Record<string, N>,
+): Record<string, unknown> | undefined => {
+  if (!props) return props
+  let out: Record<string, unknown> | undefined
+  for (const [ k, v ] of Object.entries(props)) {
+    if (isNodeRef(v)) {
+      ;(out ??= { ...props })[k] = nodes[v.$ref] ?? null
+    } else if (Array.isArray(v) && v.some(isNodeRef)) {
+      ;(out ??= { ...props })[k] = v.map((el) => (isNodeRef(el) ? nodes[el.$ref] ?? null : el))
+    }
+  }
+  return out ?? props
+}
+
+/** Names of the nodes a props record's ref() values point at (editor dep tracking). */
+export const collectRefDeps = (props: Record<string, unknown>): Set<string> => {
+  const deps = new Set<string>()
+  for (const v of Object.values(props)) {
+    if (isNodeRef(v)) deps.add(v.$ref)
+    else if (Array.isArray(v)) for (const el of v) if (isNodeRef(el)) deps.add(el.$ref)
+  }
+  return deps
+}
+
+/** The edit-mode flag an editor host sets before running the bundle (shared by both formats). */
+export const EDIT_FLAG = "__lecodesSceneEdit"
+export const isEditMode = (): boolean => (globalThis as Record<string, unknown>)[EDIT_FLAG] === true

package/runtime/sdk/ui/NativeView.ts

@@ -11,26 +11,30 @@
 
 import { _channelCall, _channelEmit, _channelOff, _channelOn, type ChannelListeners } from "../runtime/channel"
 import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "./presentable"
-import { Element, type AnimateStyle, type BaseStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style } from "./UINode"
+import { Element, type BaseStyle, type DrawableStyle, type ElementStyle, type UIElementBase } from "./UINode"
 
 export type UINativeViewStyle = ElementStyle & DrawableStyle
 
-export interface NativeView {
+/** An instance of a host-registered platform view (map, QR scanner, camera preview, …) —
+ *  embeddable among a screen's children AND fullscreen-presentable (`open()`); one instance lives
+ *  in one place at a time. Talk to it via the `call`/`on` channel. */
+export interface NativeView extends UIElementBase<UINativeViewStyle, DrawableStyle & BaseStyle> {
   readonly type: "native",
   /** The registered view kind this instance resolves to (the `registerView` name). */
   readonly viewName: string,
   /** Creation params, passed to the host factory (JSON-serializable). */
   readonly params: any,
-  style: Style<this, UINativeViewStyle>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
 
   /** Show fullscreen as the current destination (see Presentable). */
   open(options?: PresentOptions): void,
+  /** Dismiss if this is the visible destination. */
   close(): void,
 
+  /** Became the visible destination. */
   onOpen(callback: () => void): this
+  /** Stopped being the visible destination. */
   onClose(callback: () => void): this
+  /** Hardware/system back while current. */
   onBackPressed(callback: () => void): this
 
   /** Invoke a method on the native view (`map.call("setCenter", [lng, lat])`). Args and the
@@ -39,13 +43,6 @@ export interface NativeView {
   /** Subscribe to an event the native view emits (`map.on("markerTap", cb)`). */
   on(event: string, callback: (data?: any) => void): this
   off(event: string, callback: (data?: any) => void): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  getBoundingClientRect(): BoundingClientRect | null
-  /** Style-class proxy — read `el.class.checked`, set `el.class.checked = true`, toggle with
-   *  `!el.class.checked`, bind `el.class.done = () => sig.value`, batch/chain `el.class({ … })`.
-   *  Classes cascade to descendants. See {@link Classes}. */
-  readonly class: Classes<this>
 }
 
 let nextViewId = 1

package/runtime/sdk/ui/UI.ts

@@ -17,6 +17,7 @@ export { UIPopover, type UIPopoverStyle, type UIPopoverAnchor } from './UIPopove
 export { UIRow, UIColumn, UIBox, type UIContainerStyle } from './UIContainer'
 export { UIScrollable, type UIScrollableStyle } from './UIScrollable'
 export { UIPager, type UIPagerStyle } from './UIPager'
+export { UITabs, type UITabDef } from './UITabs'
 
 export { UIVirtualizedList } from './UIVirtualizedList'
 
@@ -28,4 +29,11 @@ export type { PresentOptions, Transition, TransitionName, TransitionSpec, Transi
 
 // Internal: memoized map for reactive children — the chisel `reactiveUi` pass rewrites
 // `list.map(fn)` inside children bindings to `__uiMap(list, fn, slot)` calls.
-export { __uiMap } from './UINode'
+export { __uiMap } from './UINode'
+// Compiler fast paths (chisel `flatten_ui` raw lowering): dispatch-free construction for calls
+// whose arguments the compiler proved to be plain children. Never written by hand.
+export { __UIColumn, __UIRow, __UIBox } from './UIContainer'
+export { __UIButton } from './UIButton'
+export { __UIScreen } from './UIScreen'
+export { __UIScrollable } from './UIScrollable'
+export { __UIWidget } from './UIWidget'

package/runtime/sdk/ui/UIBottomSheet.ts

@@ -1,6 +1,6 @@
 import { ModalElement, type UIModalStyle } from "./UIModal"
 import type { UIWidget } from "./UIWidget"
-import type { ChildrenFn, UINodeChild } from "./UINode"
+import { buildUI, type ChildrenFn, type UIChildArg, type UINodeChild } from "./UINode"
 
 export type UIBottomSheetStyle = UIModalStyle
 
@@ -51,10 +51,6 @@ export interface UIBottomSheet extends UIWidget {
   /** `dismissible(false)`: scrim taps, the back button and dragging below the lowest detent no
    *  longer close the sheet (a drag collapses to the lowest detent instead). Default `true`. */
   dismissible(enabled: boolean): this,
-
-  append(...nodes: UINodeChild[]): this
-  insert(index: number, ...nodes: UINodeChild[]): this
-  remove(...nodes: UINodeChild[]): this
 }
 
 export class BottomSheetElement extends ModalElement {
@@ -130,20 +126,14 @@ export class BottomSheetElement extends ModalElement {
   }
 }
 
-export function UIBottomSheet(): UIBottomSheet;
+const makeBottomSheet = (style: any, children: any) => new BottomSheetElement(style, children)
+
+/** Create a bottom sheet (see {@link UIBottomSheet}) — content-sized by default; call
+ *  `.detents([...])` for snap positions. Same argument forms as `UIColumn`. */
+export function UIBottomSheet(...children: UIChildArg[]): UIBottomSheet;
 export function UIBottomSheet(children: UINodeChild[] | ChildrenFn): UIBottomSheet;
-export function UIBottomSheet(style: UIBottomSheetStyle): UIBottomSheet;
-export function UIBottomSheet(style: UIBottomSheetStyle, children: UINodeChild[] | ChildrenFn): UIBottomSheet;
-export function UIBottomSheet(...args: [] | [UINodeChild[] | ChildrenFn | UIBottomSheetStyle] | [UIBottomSheetStyle, children: UINodeChild[] | ChildrenFn]): UIBottomSheet {
-  if (args.length === 0) {
-    return new BottomSheetElement({}, [])
-  } else if (args.length === 1) {
-    if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new BottomSheetElement({}, args[0])
-    } else {
-      return new BottomSheetElement(args[0], [])
-    }
-  } else {
-    return new BottomSheetElement(args[0], args[1])
-  }
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIBottomSheet(style: UIBottomSheetStyle, children?: UINodeChild[] | ChildrenFn): UIBottomSheet;
+export function UIBottomSheet(...args: any[]): UIBottomSheet {
+  return buildUI(args, null, makeBottomSheet)
 }

package/runtime/sdk/ui/UIButton.ts

@@ -1,38 +1,24 @@
 import { ClickEvent, TouchStartEvent, LongPressEvent } from "../runtime/touch"
 import type { ClickEvent as ClickEventType, TouchStartEvent as TouchStartEventType, LongPressEvent as LongPressEventType } from "../runtime/touch"
-import { type ElementStyle, type ContainerStyle, type Classes, type Style, ContainerElement, type DrawableStyle, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BoundingClientRect, type BaseStyle, type AnimateStyle, type Color } from "./UINode"
+import { type ElementStyle, type ContainerStyle, ContainerElement, buildUI, type DrawableStyle, type UIChildArg, type UIContainerBase, type UINodeChild, type ChildrenFn, type BaseStyle, type Color } from "./UINode"
 
 export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & { rippleColor?: Color | "default" }
 
-export interface UIButton {
+/** A tappable container — row + centered children by default. Press feedback via the `onPressed`
+ *  style block, the `$pressed` class, or `rippleColor`. */
+export interface UIButton extends UIContainerBase<UIButtonStyle & { onPressed?: UIButtonStyle & { duration?: number } }, DrawableStyle & BaseStyle> {
   readonly type: "button",
 
-  style: Style<this, UIButtonStyle & { onPressed?: UIButtonStyle & { duration?: number } }>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>,
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
-
+  /** Fired on a completed tap/click. */
   onClick(callback: (ev: ClickEventType<UIButton>) => void): this,
+  /** Fired when a touch begins; `ev.track(...)` takes over the rest of the gesture (dragging). */
   onTouchStart(callback: (ev: TouchStartEventType<UIButton>) => void): this,
   /** Fired when a finger is held on the button past the long-press threshold. The event can
    *  `ev.track(...)` the rest of the gesture (like `onTouchStart`), so a hold can flow straight into
    *  dragging the element. A handled long-press suppresses the click that would follow the release. */
   onLongPress(callback: (ev: LongPressEventType<UIButton>) => void): this,
+  /** Is a finger currently down on the button? */
   isPressed(): boolean,
-
-  append(...nodes: UINodeChild[]): this
-  insert(index: number, ...nodes: UINodeChild[]): this
-  remove(...nodes: UINodeChild[]): this
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  getBoundingClientRect(): BoundingClientRect | null
-
-  /** Style-class proxy — read `el.class.checked`, set `el.class.checked = true`, toggle with
-   *  `!el.class.checked`, bind `el.class.done = () => sig.value`, batch/chain `el.class({ … })`.
-   *  Classes cascade to descendants. See {@link Classes}. */
-  readonly class: Classes<this>
-
-  readonly children: UINodeChild[],
 }
 
 
@@ -99,20 +85,17 @@ class ButtonElement extends ContainerElement<"button"> {
 // default was a recurring authoring/codegen trap.
 const BUTTON_DEFAULTS = { flexDirection: "row", justifyContent: "center", alignItems: "center" } as const
 
-export function UIButton(): UIButton;
+const makeButton = (style: any, children: any) => new ButtonElement("button", style, children)
+
+/** @internal Compiler fast path (chisel `flatten_ui` raw lowering) — see UIContainer. */
+export const __UIButton = (children: UINodeChild[] | ChildrenFn): UIButton => makeButton({ ...BUTTON_DEFAULTS }, children)
+
+/** Create a button (row + centered by default — the icon+label shape). Same argument forms as
+ *  `UIColumn`; attach behavior with `.onClick(...)`. */
+export function UIButton(...children: UIChildArg[]): UIButton;
 export function UIButton(children: UINodeChild[] | ChildrenFn): UIButton;
-export function UIButton(style: UIButtonStyle): UIButton;
-export function UIButton(style: UIButtonStyle, children: UINodeChild[]): UIButton;
-export function UIButton(...args: [] | [UINodeChild[] | ChildrenFn | UIButtonStyle] | [UIButtonStyle, children: UINodeChild[] | ChildrenFn]): UIButton {
-  if (args.length === 0) {
-    return new ButtonElement("button", { ...BUTTON_DEFAULTS }, [])
-  } else if (args.length === 1) {
-    if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new ButtonElement("button", { ...BUTTON_DEFAULTS }, args[0])
-    } else {
-      return new ButtonElement("button", { ...BUTTON_DEFAULTS, ...args[0] }, [])
-    }
-  } else {
-    return new ButtonElement("button", { ...BUTTON_DEFAULTS, ...args[0] }, args[1])
-  }
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIButton(style: UIButtonStyle, children?: UINodeChild[] | ChildrenFn): UIButton;
+export function UIButton(...args: any[]): UIButton {
+  return buildUI(args, BUTTON_DEFAULTS, makeButton)
 }

package/runtime/sdk/ui/UIContainer.ts

@@ -1,122 +1,60 @@
-import { ContainerElement, type AnimateStyle, type AppearStyle, type ChildrenFn, type ContainerStyle, type DisappearStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style, type StyleFn, type UINode, type UINodeChild } from "./UINode"
+import { ContainerElement, buildUI, type ChildrenFn, type ContainerStyle, type DrawableStyle, type ElementStyle, type UIChildArg, type UIContainerBase, type UINodeChild } from "./UINode"
 
 export type UIContainerStyle = ElementStyle & DrawableStyle & ContainerStyle
 
-export interface UIColumn {
+/** A vertical flex container — children stack top to bottom. */
+export interface UIColumn extends UIContainerBase<UIContainerStyle> {
   readonly type: "column",
-  style: Style<this, UIContainerStyle>,
-  animateTo: AnimateStyle<this, UIContainerStyle>
-  animateFrom: AnimateStyle<this, UIContainerStyle>
-
-  append(...nodes: UINodeChild[]): UIColumn
-  insert(index: number, ...nodes: UINodeChild[]): UIColumn
-  remove(...nodes: UINodeChild[]): UIColumn
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-  
-  onLayout(onLayout: OnLayoutCallback): this
-  getBoundingClientRect(): BoundingClientRect | null
-
-  /** Style-class proxy — read `el.class.checked`, set `el.class.checked = true`, toggle with
-   *  `!el.class.checked`, bind `el.class.done = () => sig.value`, batch/chain `el.class({ … })`.
-   *  Classes cascade to descendants. See {@link Classes}. */
-  readonly class: Classes<this>
-
-  readonly children: UINodeChild[]
 }
-export function UIColumn(): UIColumn
+const makeColumn = (style: any, children: any) => new ContainerElement("column", style, children)
+
+/** @internal Compiler fast path (chisel `flatten_ui` raw lowering): construction with a proven
+ *  plain-children array — or a reactive ChildrenFn (the Element constructor branches on
+ *  `typeof === "function"` either way) — skipping the buildUI argument dispatch entirely. */
+export const __UIColumn = (children: UINodeChild[] | ChildrenFn): UIColumn => makeColumn({}, children)
+export const __UIRow = (children: UINodeChild[] | ChildrenFn): UIRow => makeRow({ flexDirection: "row" }, children)
+export const __UIBox = (children: UINodeChild[] | ChildrenFn): UIBox => makeBox({ ...BOX_DEFAULTS }, children)
+
+/** Create a vertical flex container. Children are variadic — arrays flatten one level, falsy
+ *  entries are skipped; a lone function makes the children reactive. */
+export function UIColumn(...children: UIChildArg[]): UIColumn
 export function UIColumn(children: UINodeChild[] | ChildrenFn): UIColumn
-export function UIColumn(style: UIContainerStyle): UIColumn
-export function UIColumn(style: UIContainerStyle, children: UINodeChild[]): UIColumn
-export function UIColumn(...args: [] | [UINodeChild[] | ChildrenFn | UIContainerStyle] | [UIContainerStyle, children: UINodeChild[] | ChildrenFn]): UIColumn {
-  if (args.length === 0) {
-    return new ContainerElement("column", {}, [])
-  } else if (args.length === 1) {
-    if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new ContainerElement("column", {}, args[0])
-    } else {
-      return new ContainerElement("column", args[0], [])
-    }
-  } else {
-    return new ContainerElement("column", args[0], args[1])
-  }
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIColumn(style: UIContainerStyle, children?: UINodeChild[] | ChildrenFn): UIColumn
+export function UIColumn(...args: any[]): UIColumn {
+  return buildUI(args, null, makeColumn)
 }
 
-export interface UIRow {
+/** A horizontal flex container — children flow left to right. */
+export interface UIRow extends UIContainerBase<UIContainerStyle> {
   readonly type: "row",
-  style: Style<this, UIContainerStyle>,
-  animateTo: AnimateStyle<this, UIContainerStyle>,
-  animateFrom: AnimateStyle<this, UIContainerStyle>,
-
-  append(...nodes: UINodeChild[]): UIRow
-  insert(index: number, ...nodes: UINodeChild[]): UIRow
-  remove(...nodes: UINodeChild[]): UIRow
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  getBoundingClientRect(): BoundingClientRect | null
-
-  /** Style-class proxy — read `el.class.checked`, set `el.class.checked = true`, toggle with
-   *  `!el.class.checked`, bind `el.class.done = () => sig.value`, batch/chain `el.class({ … })`.
-   *  Classes cascade to descendants. See {@link Classes}. */
-  readonly class: Classes<this>
-
-  readonly children: UINodeChild[],
 }
-export function UIRow(): UIRow
+const ROW_DEFAULTS = { flexDirection: "row" } as const
+const makeRow = (style: any, children: any) => new ContainerElement("row", style, children)
+
+/** Create a horizontal flex container (same argument forms as `UIColumn`). */
+export function UIRow(...children: UIChildArg[]): UIRow
 export function UIRow(children: UINodeChild[] | ChildrenFn): UIRow
-export function UIRow(style: UIContainerStyle): UIRow
-export function UIRow(style: UIContainerStyle, children: UINodeChild[]): UIRow
-export function UIRow(...args: [] | [UINodeChild[] | ChildrenFn | UIContainerStyle] | [UIContainerStyle, children: UINodeChild[] | ChildrenFn]): UIRow {
-  if (args.length === 0) {
-    return new ContainerElement("row", { flexDirection: "row" }, [])
-  } else if (args.length === 1) {
-    if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new ContainerElement("row", { flexDirection: "row" }, args[0])
-    } else {
-      return new ContainerElement("row", { flexDirection: "row", ...args[0] }, [])
-    }
-  } else {
-    return new ContainerElement("row", { flexDirection: "row", ...args[0] }, args[1])
-  }
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIRow(style: UIContainerStyle, children?: UINodeChild[] | ChildrenFn): UIRow
+export function UIRow(...args: any[]): UIRow {
+  return buildUI(args, ROW_DEFAULTS, makeRow)
 }
 
-export interface UIBox {
+/** A centering container — `justifyContent`/`alignItems` default to center. */
+export interface UIBox extends UIContainerBase<UIContainerStyle> {
   readonly type: "box",
-  style: Style<this, UIContainerStyle>,
-  animateTo: AnimateStyle<this, UIContainerStyle>,
-  animateFrom: AnimateStyle<this, UIContainerStyle>,
-
-  append(...nodes: UINodeChild[]): this
-  insert(index: number, ...nodes: UINodeChild[]): this
-  remove(...nodes: UINodeChild[]): this
-  setContent(nodes: UINodeChild[] | ChildrenFn): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  getBoundingClientRect(): BoundingClientRect | null
-
-  /** Style-class proxy — read `el.class.checked`, set `el.class.checked = true`, toggle with
-   *  `!el.class.checked`, bind `el.class.done = () => sig.value`, batch/chain `el.class({ … })`.
-   *  Classes cascade to descendants. See {@link Classes}. */
-  readonly class: Classes<this>
-
-  readonly children: UINodeChild[],
 }
 const BOX_DEFAULTS = { justifyContent: "center", alignItems: "center" } as const
 
-export function UIBox(): UIBox
+const makeBox = (style: any, children: any) => new ContainerElement("box", style, children)
+
+/** Create a centering container — children are centered on both axes by default (icon badges,
+ *  avatars, empty states). Same argument forms as `UIColumn`. */
+export function UIBox(...children: UIChildArg[]): UIBox
 export function UIBox(children: UINodeChild[] | ChildrenFn): UIBox
-export function UIBox(style: UIContainerStyle): UIBox
-export function UIBox(style: UIContainerStyle, children: UINodeChild[]): UIBox
-export function UIBox(...args: [] | [UINodeChild[] | ChildrenFn | UIContainerStyle] | [UIContainerStyle, children: UINodeChild[] | ChildrenFn]): UIBox {
-  if (args.length === 0) {
-    return new ContainerElement("box", { ...BOX_DEFAULTS }, [])
-  } else if (args.length === 1) {
-    if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new ContainerElement("box", { ...BOX_DEFAULTS }, args[0])
-    } else {
-      return new ContainerElement("box", { ...BOX_DEFAULTS, ...args[0] }, [])
-    }
-  } else {
-    return new ContainerElement("box", { ...BOX_DEFAULTS, ...args[0] }, args[1])
-  }
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIBox(style: UIContainerStyle, children?: UINodeChild[] | ChildrenFn): UIBox
+export function UIBox(...args: any[]): UIBox {
+  return buildUI(args, BOX_DEFAULTS, makeBox)
 }

package/runtime/sdk/ui/UIImage.ts

@@ -2,7 +2,7 @@ import type { FetchResponse } from "../runtime/fetch"
 import type { SvgSourceValue as SvgSource } from "../runtime/misc"
 import type { File } from "../runtime/fetch"
 import { Canvas, isCanvas } from "../canvas/Canvas"
-import { Element, type AnimateStyle, type Color, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style } from "./UINode"
+import { Element, type Color, type ElementStyle, type UIElementBase } from "./UINode"
 
 export type UIImageStyle = ElementStyle & { borderRadius?: number, objectFit?: "cover" | "contain" | "fill", tintColor?: Color }
 
@@ -21,28 +21,18 @@ const toSrc = (src: ImageSource): string | FetchResponse | File | SvgSource | Ca
 /** The stored/resolved image source (a Canvas is resolved to a surface marker). */
 export type ResolvedImageSource = string | FetchResponse | File | SvgSource | CanvasImageSource
 
-export interface UIImage {
+/** An image element. Sources: URL / `asset(...)`, fetch response / File, an SVG source
+ *  (`assetIcon`), or a live Canvas (`canvas.update()` refreshes the node in place). */
+export interface UIImage extends UIElementBase<UIImageStyle> {
   readonly type: "image",
+  /** The image source — writable to swap the picture in place. */
   get src(): ResolvedImageSource
   set src(value: ImageSource)
-  style: Style<this, UIImageStyle>
-  animateTo: AnimateStyle<this, UIImageStyle>
-  animateFrom: AnimateStyle<this, UIImageStyle>
 
-  // Render only a sub-rectangle of the source texture (coords/size in texture pixels).
-  // This is the atlas / spritesheet primitive: the initial crop is the first call, sprite
-  // animation is swapping the rect per frame. The rect's w/h become the node's intrinsic
-  // size (one frame, not the whole atlas) and it overrides objectFit — the cropped frame
-  // always fills the box.
+  /** Render only a sub-rectangle of the source texture (texture pixels) — the atlas/spritesheet
+   *  primitive: crop once, then swap the rect per frame for sprite animation. The rect's w/h
+   *  become the node's intrinsic size and override `objectFit` — the cropped frame fills the box. */
   setSourceRect(x: number, y: number, w: number, h: number): this
-
-  onLayout(onLayout: OnLayoutCallback): this
-  getBoundingClientRect(): BoundingClientRect | null
-
-  /** Style-class proxy — read `el.class.checked`, set `el.class.checked = true`, toggle with
-   *  `!el.class.checked`, bind `el.class.done = () => sig.value`, batch/chain `el.class({ … })`.
-   *  Classes cascade to descendants. See {@link Classes}. */
-  readonly class: Classes<this>
 }
 
 class ImageElement extends Element<"image"> {
@@ -80,7 +70,9 @@ class ImageElement extends Element<"image"> {
   }
 }
 
+/** Create an image element from a source (see {@link ImageSource}). */
 export function UIImage(src: ImageSource): UIImage
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
 export function UIImage(style: UIImageStyle, src: ImageSource): UIImage
 export function UIImage(...args: [ImageSource] | [UIImageStyle, ImageSource]): UIImage {
   if (args.length === 1) {

package/runtime/sdk/ui/UIInput.ts

@@ -1,4 +1,4 @@
-import { type ElementStyle, type DrawableStyle, type Classes, type Style, type StyleFn, type AppearStyle, type DisappearStyle, Element, type TextStyle, type Color, type OnLayoutCallback, type BoundingClientRect, type BaseStyle, type AnimateStyle } from "./UINode";
+import { type ElementStyle, type DrawableStyle, Element, type TextStyle, type Color, type BaseStyle, type UIElementBase } from "./UINode";
 
 type InputStyle = {
   placeholder?: string,
@@ -49,7 +49,9 @@ type SubmitStyle = {
   enterKey?: "done" | "go" | "next" | "search" | "send",
 }
 
-export interface UIInput {
+/** A single-line text input. Keyboard/picker kind via the `type` style, return-key behavior via
+ *  `enterKey` + `onSubmit`; keyboard policy on `keyboardShrink`/`keyboardDismiss`. */
+export interface UIInput extends UIElementBase<UIInputStyle & SubmitStyle & { onFocused?: UIInputStyle & { duration?: number } }, DrawableStyle & BaseStyle> {
   readonly type: "input",
 
   /**
@@ -60,55 +62,39 @@ export interface UIInput {
    */
   value: string
 
-  style: Style<this, UIInputStyle & SubmitStyle & { onFocused?: UIInputStyle & { duration?: number } }>,
-  animateTo: AnimateStyle<this, DrawableStyle & BaseStyle>
-  animateFrom: AnimateStyle<this, DrawableStyle & BaseStyle>
-
+  /** The text changed — fires on every user edit. */
   onChange(callback: (value: string) => void): UIInput
+  /** Gained focus (keyboard opens). */
   onFocus(callback: () => void): UIInput
+  /** Lost focus. */
   onBlur(callback: () => void): UIInput
   /** The keyboard's return key was pressed. `value` is the current text. See `enterKey`. */
   onSubmit(callback: (value: string) => void): UIInput
-  onLayout(onLayout: OnLayoutCallback): this
-  getBoundingClientRect(): BoundingClientRect | null
 
   /** Focus the input (opens the keyboard). No-op before mount. */
   focus(): void
   /** Release focus (dismisses the keyboard when this input held it). */
   blur(): void
-
-  /** Style-class proxy — read `el.class.checked`, set `el.class.checked = true`, toggle with
-   *  `!el.class.checked`, bind `el.class.done = () => sig.value`, batch/chain `el.class({ … })`.
-   *  Classes cascade to descendants. See {@link Classes}. */
-  readonly class: Classes<this>
 }
 
-export interface UITextArea {
+/** A multi-line text field — see the {@link UITextArea} factory for the auto-grow contract. */
+export interface UITextArea extends UIElementBase<UIInputStyle & { onFocused?: UIInputStyle & { duration?: number } }, DrawableStyle & BaseStyle> {
   readonly type: "textarea",
 
   /** The field's text — same contract as {@link UIInput.value}: settable before mount to pre-fill. */
   value: string
 
-  style: Style<this, UIInputStyle & { onFocused?: UIInputStyle & { duration?: number } }>,
-  // styleV: StyleFn<this, UIInputStyle>,
-  // styleH: StyleFn<this, UIInputStyle>,
-
-  // appear: AppearStyle<this, UIInputStyle>
-  // disappear: DisappearStyle<this, UIInputStyle>
-
+  /** The text changed — fires on every user edit. */
   onChange(callback: (value: string) => void): UITextArea
+  /** Gained focus (keyboard opens). */
   onFocus(callback: () => void): UITextArea
+  /** Lost focus. */
   onBlur(callback: () => void): UITextArea
 
   /** Focus the text area (opens the keyboard). No-op before mount. */
   focus(): void
   /** Release focus (dismisses the keyboard when this text area held it). */
   blur(): void
-
-  /** Style-class proxy — read `el.class.checked`, set `el.class.checked = true`, toggle with
-   *  `!el.class.checked`, bind `el.class.done = () => sig.value`, batch/chain `el.class({ … })`.
-   *  Classes cascade to descendants. See {@link Classes}. */
-  readonly class: Classes<this>
 }
 
 class InputElement<T extends "input" | "textarea"> extends Element<T> {
@@ -175,6 +161,8 @@ class InputElement<T extends "input" | "textarea"> extends Element<T> {
   }
 }
 
+/** Create a single-line text input. Read/write the text via `.value`, listen with
+ *  `onChange`/`onSubmit`; style keys `placeholder`, `type`, `enterKey`, … configure it. */
 export function UIInput(): UIInput;
 export function UIInput(style: UIInputStyle): UIInput;
 export function UIInput(style?: UIInputStyle): UIInput {

package/runtime/sdk/ui/UIModal.ts

@@ -1,5 +1,5 @@
 import { type UIWidget, type UIWidgetStyle, WidgetElement } from "./UIWidget"
-import type { BaseStyle, ChildrenFn, Color, DrawableStyle, UINodeChild } from "./UINode"
+import { buildUI, type BaseStyle, type ChildrenFn, type Color, type DrawableStyle, type UIChildArg, type UINodeChild } from "./UINode"
 
 export type UIModalStyle = UIWidgetStyle
 
@@ -50,10 +50,6 @@ export interface UIModal extends UIWidget {
   /** `dismissible(false)` keeps scrim taps and the back button from closing the modal
    *  (forced-choice dialogs). Default `true`. */
   dismissible(enabled: boolean): this,
-
-  append(...nodes: UINodeChild[]): this
-  insert(index: number, ...nodes: UINodeChild[]): this
-  remove(...nodes: UINodeChild[]): this
 }
 
 export class ModalElement extends WidgetElement {
@@ -130,20 +126,14 @@ export class ModalElement extends WidgetElement {
   }
 }
 
-export function UIModal(): UIModal;
+const makeModal = (style: any, children: any) => new ModalElement(style, children)
+
+/** Create a modal dialog (see {@link UIModal}) — create once at module scope, then
+ *  `show()`/`hide()`. Same argument forms as `UIColumn`. */
+export function UIModal(...children: UIChildArg[]): UIModal;
 export function UIModal(children: UINodeChild[] | ChildrenFn): UIModal;
-export function UIModal(style: UIModalStyle): UIModal;
-export function UIModal(style: UIModalStyle, children: UINodeChild[] | ChildrenFn): UIModal;
-export function UIModal(...args: [] | [UINodeChild[] | ChildrenFn | UIModalStyle] | [UIModalStyle, children: UINodeChild[] | ChildrenFn]): UIModal {
-  if (args.length === 0) {
-    return new ModalElement({}, [])
-  } else if (args.length === 1) {
-    if (Array.isArray(args[0]) || typeof args[0] === "function") {
-      return new ModalElement({}, args[0])
-    } else {
-      return new ModalElement(args[0], [])
-    }
-  } else {
-    return new ModalElement(args[0], args[1])
-  }
+/** @deprecated Style as the first argument is legacy — use chained `.style({...})`. */
+export function UIModal(style: UIModalStyle, children?: UINodeChild[] | ChildrenFn): UIModal;
+export function UIModal(...args: any[]): UIModal {
+  return buildUI(args, null, makeModal)
 }