lecodes-cli 0.10.4 → 0.11.0

package/runtime/sdk/compile/libraryImports.ts

@@ -0,0 +1,52 @@
+// Pre-chisel rewrite of user-library bare-specifier imports. chisel's resolver hard-errors on any
+// bare import (the whole SDK is globals), so a project that imports a component library by its slug
+// —`import { Card } from "acme-ui"`— is rewritten here to the injected library tree under
+// `/__lib/<slug>/…` BEFORE chisel runs. Only libraries present in the dependency map are known
+// slugs; any other bare specifier is an author error, surfaced with a friendly message instead of
+// chisel's generic one. Static string-literal specifiers only — dynamic `import()` is unsupported
+// (documented). Chisel itself is untouched. See docs/library-system-plan.md §4.
+
+/** Cheap pre-check so the regexes don't run over files with no imports at all. */
+export const hasImportStatement = (src: string): boolean => src.includes("import") || src.includes("from")
+
+// A static `from "…"` clause (import-from OR export-from). Anchored at a statement boundary
+// (line start / `;` / `}`) and disallowing quotes/backticks/semicolons between the keyword and
+// `from`, so it can never span into a string literal or a neighbouring statement. Named-import
+// lists may span multiple lines (newlines are allowed between the keyword and `from`).
+const IMPORT_FROM_RE = /(^|[;\n}])(\s*(?:import|export)\b[^"'`;]*?\bfrom\s*)(["'])([^"'\n]+)\3/g
+
+// A side-effect `import "…"` (a bare quote directly after the keyword — not `import x`, not `import(`).
+const SIDE_EFFECT_RE = /(^|[;\n}])(\s*import\s*)(["'])([^"'\n]+)\3/g
+
+const isRelativeOrAbsolute = (spec: string): boolean =>
+  spec.startsWith("/") || spec.startsWith("./") || spec.startsWith("../")
+
+/**
+ * Rewrite every known-library bare import in `src` to its `/__lib/<slug>/…` path. Relative and
+ * absolute specifiers pass through untouched; an unknown bare specifier throws a friendly Error.
+ * `slugs` is the set of library slugs available to this project (its dependency map's keys).
+ */
+export const rewriteLibraryImports = (src: string, slugs: Set<string>): string => {
+  const rewriteSpec = (spec: string): string => {
+    if (isRelativeOrAbsolute(spec)) return spec
+    const slash = spec.indexOf("/")
+    const slug = slash === -1 ? spec : spec.slice(0, slash)
+    if (slugs.has(slug)) {
+      // `acme-ui` → `/__lib/acme-ui/index`; `acme-ui/theme` → `/__lib/acme-ui/theme`.
+      const sub = slash === -1 ? "/index" : spec.slice(slash)
+      return `/__lib/${slug}${sub}`
+    }
+    // Legacy worker-module imports (`import { UIScreen } from "ui"`) predate the globals-only SDK —
+    // chisel would reject them anyway; say so here instead of "Unknown library".
+    if (slug === "ui" || slug === "creator" || slug === "utils") {
+      throw new Error(`import from "${slug}": the SDK needs no imports — UIScreen, Scene, etc. are globals; remove this import line.`)
+    }
+    throw new Error(`Unknown library "${slug}" — add it in Settings → Libraries, or use a relative path like "./${slug}".`)
+  }
+
+  let out = src.replace(IMPORT_FROM_RE, (_m, boundary, head, quote, spec) =>
+    `${boundary}${head}${quote}${rewriteSpec(spec)}${quote}`)
+  out = out.replace(SIDE_EFFECT_RE, (m, boundary, head, quote, spec) =>
+    isRelativeOrAbsolute(spec) ? m : `${boundary}${head}${quote}${rewriteSpec(spec)}${quote}`)
+  return out
+}

package/runtime/sdk/compile/sceneEditor.ts

@@ -0,0 +1,78 @@
+// The scene-editor compile composition, shared by every host that compiles an edit-mode bundle
+// for a .scene.ts file: the platform backend (src/scene/compileSceneEditor.ts), the standalone
+// scene-editor dev server, and (later) the lecodes CLI. One bundle on purpose: chisel's
+// method-granular DCE trims each bundle's SDK copy to its own calls, so a separately-compiled
+// harness could not call scene methods on objects the scene bundle created.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import type { CompileEntry } from "./compileProject"
+
+/** Where the harness sources land in the compile's file map. The dotfolder can't collide with
+ *  project assets (the tree forbids leading-dot names) and reads clearly in compile errors. */
+export const SCENE_HARNESS_DIR = "./.scene-editor"
+
+/** The virtual entrypoint path (`entryOverride`). */
+export const SCENE_ENTRY_PATH = "./.scene-entry.ts"
+
+/**
+ * Read the harness sources (packages/projects/src/scene-editor) from a directory:
+ * `LECODES_SCENE_HARNESS_DIR` env override first (deployments vendor the sources, like
+ * LECODES_SDK_INJECT does for the SDK), else the given fallback dir. Returns name → source.
+ */
+export const loadSceneHarness = (fallbackDir?: string): Record<string, string> => {
+  const override = process.env.LECODES_SCENE_HARNESS_DIR
+  const dir = override && existsSync(override) ? override
+    : fallbackDir && existsSync(fallbackDir) ? fallbackDir
+    : null
+  if (!dir) throw new Error("scene-editor harness sources not found (set LECODES_SCENE_HARNESS_DIR)")
+  const out: Record<string, string> = {}
+  for (const f of readdirSync(dir)) {
+    if (f.endsWith(".ts")) out[f] = readFileSync(join(dir, f), "utf8")
+  }
+  return out
+}
+
+/**
+ * The extra entries that turn a project compile into a scene-editor compile: the harness modules
+ * plus a virtual entry that (1) sets the edit-mode flag in its own module — imports hoist, so the
+ * flag must run as a module, first — (2) imports the scene, which registers its handle on
+ * `__lecodesScenes`, (3) imports the project's `*.editor.ts` plugin files (editor bundles ONLY —
+ * production compiles never import them, so they cost zero bytes in shipped `app.js`), and
+ * (4) imports the harness main, which installs `__lecodesSceneHarness`.
+ * FULL extensions everywhere — exact-match specifiers need no resolver guesswork on dotted names,
+ * so even the unpatched published chisel resolves the `.scene.ts` import.
+ *
+ * `scenePath` is the project path of the scene file ("./scenes/city.scene.ts"); `projectPaths` is
+ * the project's file list — `.editor.ts` entries are picked out of it. Compile with
+ * `entryOverride: SCENE_ENTRY_PATH`, `header: false`, `format: "iife"`, `editor: true`.
+ */
+export const sceneEditorEntries = (
+  scenePath: string,
+  harness: Record<string, string>,
+  projectPaths: string[] = [],
+): CompileEntry[] => {
+  const entries: CompileEntry[] = Object.entries(harness).map(([ name, text ]) => ({
+    path: `${SCENE_HARNESS_DIR}/${name}`,
+    type: "text" as const,
+    text,
+  }))
+  entries.push({
+    path: `${SCENE_HARNESS_DIR}/.edit-mode.ts`,
+    type: "text",
+    text: `;(globalThis as any).__lecodesSceneEdit = true\nexport {}\n`,
+  })
+  const editorImports = projectPaths
+    .filter((p) => p.endsWith(".editor.ts"))
+    .map((p) => `import "${p}"\n`)
+    .join("")
+  entries.push({
+    path: SCENE_ENTRY_PATH,
+    type: "text",
+    text: `import "${SCENE_HARNESS_DIR}/.edit-mode.ts"\n`
+      + `import "${scenePath}"\n`
+      + editorImports
+      + `import "${SCENE_HARNESS_DIR}/main.ts"\n`,
+  })
+  return entries
+}

package/runtime/sdk/compile/sfnt.ts

@@ -0,0 +1,98 @@
+// Minimal sfnt (TTF/OTF) reader for the `font()` compile macro: family name from the `name` table,
+// weight/italic from `OS/2` (with a `head.macStyle` fallback). Reads only what the macro needs —
+// this is not a font sanitizer or validator.
+
+export type SfntInfo = { family: string, weight: number, italic: boolean }
+
+const TAG_TTF = 0x00010000
+const TAG_OTTO = 0x4f54544f // 'OTTO' (CFF outlines)
+const TAG_TTCF = 0x74746366 // 'ttcf' (collection)
+const TAG_WOFF = 0x774f4646 // 'wOFF'
+const TAG_WOF2 = 0x774f4632 // 'wOF2'
+
+/** Parse a .ttf/.otf. Throws a message meant to surface verbatim in a compile error. */
+export const parseSfnt = (bytes: Uint8Array): SfntInfo => {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  if (bytes.byteLength < 12) throw new Error("not a font file (truncated)")
+  const version = dv.getUint32(0)
+  if (version === TAG_TTCF) throw new Error("font collections (.ttc) aren't supported — export a single face")
+  if (version === TAG_WOFF || version === TAG_WOF2) throw new Error("WOFF/WOFF2 project fonts aren't supported — use the .ttf/.otf")
+  if (version !== TAG_TTF && version !== TAG_OTTO) throw new Error("not a TTF/OTF font file")
+
+  const numTables = dv.getUint16(4)
+  const tables = new Map<string, { offset: number, length: number }>()
+  for (let i = 0; i < numTables; i++) {
+    const rec = 12 + i * 16
+    if (rec + 16 > bytes.byteLength) throw new Error("not a font file (truncated table directory)")
+    const tag = String.fromCharCode(bytes[rec], bytes[rec + 1], bytes[rec + 2], bytes[rec + 3])
+    tables.set(tag, { offset: dv.getUint32(rec + 8), length: dv.getUint32(rec + 12) })
+  }
+
+  const family = readFamily(dv, bytes, tables.get("name"))
+  if (!family) throw new Error("no family name in the font's `name` table")
+
+  let weight = 400
+  let italic = false
+  const os2 = tables.get("OS/2")
+  if (os2 && os2.offset + 64 <= bytes.byteLength) {
+    weight = dv.getUint16(os2.offset + 4) // usWeightClass
+    italic = (dv.getUint16(os2.offset + 62) & 1) === 1 // fsSelection ITALIC
+  } else {
+    const head = tables.get("head")
+    if (head && head.offset + 46 <= bytes.byteLength) {
+      const macStyle = dv.getUint16(head.offset + 44)
+      if (macStyle & 1) weight = 700
+      italic = (macStyle & 2) === 2
+    }
+  }
+  if (weight < 1 || weight > 1000) weight = 400
+
+  return { family, weight, italic }
+}
+
+/** Best family name: typographic family (nameID 16) over legacy family (1); Windows-English
+ *  records over the rest. Returns "" when the table yields nothing decodable. */
+const readFamily = (dv: DataView, bytes: Uint8Array, name?: { offset: number, length: number }): string => {
+  if (!name || name.offset + 6 > bytes.byteLength) return ""
+  const base = name.offset
+  const count = dv.getUint16(base + 2)
+  const stringOffset = base + dv.getUint16(base + 4)
+
+  let best = ""
+  let bestScore = -1
+  for (let i = 0; i < count; i++) {
+    const rec = base + 6 + i * 12
+    if (rec + 12 > bytes.byteLength) break
+    const platformID = dv.getUint16(rec)
+    const languageID = dv.getUint16(rec + 4)
+    const nameID = dv.getUint16(rec + 6)
+    const length = dv.getUint16(rec + 8)
+    const offset = stringOffset + dv.getUint16(rec + 10)
+    if (nameID !== 16 && nameID !== 1) continue
+    if (offset + length > bytes.byteLength) continue
+
+    // nameID 16 beats 1; within an id, Windows-English > Windows > Unicode > Mac.
+    let score = nameID === 16 ? 100 : 0
+    if (platformID === 3) score += languageID === 0x409 ? 30 : 20
+    else if (platformID === 0) score += 10
+    if (score <= bestScore) continue
+
+    const text = platformID === 1 ? decodeLatin1(bytes, offset, length) : decodeUtf16be(bytes, offset, length)
+    if (!text.trim()) continue
+    best = text.trim()
+    bestScore = score
+  }
+  return best
+}
+
+const decodeUtf16be = (bytes: Uint8Array, offset: number, length: number): string => {
+  let out = ""
+  for (let i = 0; i + 1 < length; i += 2) out += String.fromCharCode((bytes[offset + i] << 8) | bytes[offset + i + 1])
+  return out
+}
+
+const decodeLatin1 = (bytes: Uint8Array, offset: number, length: number): string => {
+  let out = ""
+  for (let i = 0; i < length; i++) out += String.fromCharCode(bytes[offset + i])
+  return out
+}

package/runtime/sdk/compile/sourcemap.ts

@@ -0,0 +1,25 @@
+// Helpers for serving the bundler's source map alongside the bundle. The map's generated positions
+// are relative to the bundle code; when the deploy/preview prepends a comment header, the map must be
+// shifted down by that many lines, then inlined into the bundle as a data URL (the preview executes
+// the bundle via `new Function(string)`, which has no URL identity, so an external `.map` can't be
+// fetched — it must be inline).
+
+/** Shift every generated position in `mapJson` down by `lines` (each VLQ line is `;`-separated). */
+export const offsetSourceMap = (mapJson: string, lines: number): string => {
+  if (lines <= 0) return mapJson
+  const map = JSON.parse(mapJson) as { mappings: string }
+  map.mappings = ";".repeat(lines) + map.mappings
+  return JSON.stringify(map)
+}
+
+/**
+ * Inline the map into a bundle string under a **non-standard** directive (`lecodesMap`, not
+ * `sourceMappingURL`), so the browser does NOT auto-apply it. The bundle runs via `new Function`, and
+ * the browser maps the raw stack position *including* the `new Function` wrapper (~2-3 lines) which the
+ * map can't subtract — so its native source location would be off by those lines. Our preview mapper
+ * reads `lecodesMap` and subtracts the (calibrated) wrapper itself, so its locations are correct.
+ */
+export const inlineSourceMapComment = (mapJson: string): string => {
+  const b64 = Buffer.from(mapJson, "utf8").toString("base64")
+  return `//# lecodesMap=data:application/json;charset=utf-8;base64,${b64}`
+}

package/runtime/sdk/inject.ts

@@ -63,6 +63,7 @@ export {
   UIInput, UITextArea, type UIInputStyle,
   UIScrollable, type UIScrollableStyle,
   UIPager, type UIPagerStyle,
+  UITabs, type UITabDef,
   UIWidget, type UIWidgetStyle,
   UIModal, type UIModalStyle,
   UIBottomSheet, type UIBottomSheetStyle,
@@ -73,6 +74,7 @@ export {
   NativeView, type UINativeViewStyle,
   registerFont,
   __uiMap,
+  __UIColumn, __UIRow, __UIBox, __UIButton, __UIScreen, __UIScrollable, __UIWidget,
 } from "./ui/UI"
 // The Presentable navigation contract (docs/navigation-presentable-plan.md). `Presentable` is
 // interface + runtime companion (declaration merging): `Presentable.current` = what's on screen.

package/runtime/sdk/ui/NativeView.ts

@@ -15,6 +15,9 @@ import { Element, type AnimateStyle, type BaseStyle, type DrawableStyle, type El
 
 export type UINativeViewStyle = ElementStyle & DrawableStyle
 
+/** 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 {
   readonly type: "native",
   /** The registered view kind this instance resolves to (the `registerView` name). */

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
 
@@ -130,20 +130,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,9 +1,11 @@
 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, type Classes, type Style, ContainerElement, buildUI, type DrawableStyle, type UIChildArg, type UINodeChild, type ChildrenFn, type OnLayoutCallback, type BoundingClientRect, type BaseStyle, type AnimateStyle, type Color } from "./UINode"
 
 export type UIButtonStyle = ElementStyle & DrawableStyle & ContainerStyle & { rippleColor?: Color | "default" }
 
+/** A tappable container — row + centered children by default. Press feedback via the `onPressed`
+ *  style block, the `$pressed` class, or `rippleColor`. */
 export interface UIButton {
   readonly type: "button",
 
@@ -11,12 +13,15 @@ export interface UIButton {
   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
@@ -99,20 +104,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,7 +1,8 @@
-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 AnimateStyle, type AppearStyle, type ChildrenFn, type ContainerStyle, type DisappearStyle, type DrawableStyle, type ElementStyle, type OnLayoutCallback, type BoundingClientRect, type Classes, type Style, type StyleFn, type UIChildArg, type UINode, type UINodeChild } from "./UINode"
 
 export type UIContainerStyle = ElementStyle & DrawableStyle & ContainerStyle
 
+/** A vertical flex container — children stack top to bottom. */
 export interface UIColumn {
   readonly type: "column",
   style: Style<this, UIContainerStyle>,
@@ -23,24 +24,26 @@ export interface UIColumn {
 
   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)
 }
 
+/** A horizontal flex container — children flow left to right. */
 export interface UIRow {
   readonly type: "row",
   style: Style<this, UIContainerStyle>,
@@ -62,24 +65,19 @@ export interface UIRow {
 
   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)
 }
 
+/** A centering container — `justifyContent`/`alignItems` default to center. */
 export interface UIBox {
   readonly type: "box",
   style: Style<this, UIContainerStyle>,
@@ -103,20 +101,14 @@ export interface UIBox {
 }
 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

@@ -21,19 +21,20 @@ 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
 
+/** 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 {
   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
@@ -80,7 +81,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, type Classes, type Style, Element, type TextStyle, type Color, type OnLayoutCallback, type BoundingClientRect, type BaseStyle, type AnimateStyle } from "./UINode";
 
 type InputStyle = {
   placeholder?: string,
@@ -49,6 +49,8 @@ type SubmitStyle = {
   enterKey?: "done" | "go" | "next" | "search" | "send",
 }
 
+/** 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 {
   readonly type: "input",
 
@@ -83,6 +85,7 @@ export interface UIInput {
   readonly class: Classes<this>
 }
 
+/** A multi-line text field — see the {@link UITextArea} factory for the auto-grow contract. */
 export interface UITextArea {
   readonly type: "textarea",
 
@@ -90,11 +93,6 @@ export interface UITextArea {
   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>
 
   onChange(callback: (value: string) => void): UITextArea
   onFocus(callback: () => void): UITextArea
@@ -175,6 +173,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
 
@@ -130,20 +130,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)
 }