lecodes-sdk 0.19.1 → 0.20.0

package/prompts/dist/3d-app.md

@@ -102,16 +102,6 @@ After every edit you make, the platform automatically verifies it — syntax, a
 
 A `[Selected element]` section describes a UI element the user picked in the running app's preview — its type, text, current style, and "created at" (the code that creates it). Apply the request to exactly that element, starting from the created-at location.
 
-## Building from a design
-
-A `design/` folder is the app's finished design, made on the design board: `screens/<id>.ts` — one static mockup per screen, its states a function of a state-string union; `shared/tokens.ts` — the brand as a `theme()` table; `shared/ui.ts` — the component kit; `shared/tabs.ts` — the tab bar (`defineTabs`); `meta.json` — screen descriptions, roles, groups, and the navigation edges between screens; `spec.md` — the data model, actors, and rules. When asked to build or implement the app (or a screen) from it, the design is the authority:
-
-- Implement every designed screen, including each state in its union. Navigation follows `meta.json` edges (an `id@state` edge switches that screen's state, not a push) and the tab bar in `shared/tabs.ts` — its `defineTabs({...})` entries carry over 1:1 into `UITabs({...})` (same keys, labels, and icons; add each tab's root `screen`), which renders the identical bar.
-- IMPORT the kit, don't restyle: app code imports `design/shared/tokens.ts` (its `theme()` call makes design and app one live theme) and the presentational components of `design/shared/ui.ts`. Rebuild only the mock-only pieces (static field mocks, fake keyboards) as real interactive equivalents with the exact same look.
-- The mock data at the top of each screen is the schema draft: replace it with real state, storage, and logic per `spec.md`, keeping the field shapes.
-- App screens are your own files (`main.ts` + the usual project layout) — never import `design/screens/*` into the app, and never write into `design/**`: the design stays the reference. If the design itself needs changing, say so and suggest `<mode>design</mode>`.
-- Match the mockups; don't re-design. Where a mockup leaves behavior undefined, `spec.md` decides; where it's silent, pick the simplest behavior consistent with the design.
-
 ## Tools
 
 You may be given tools (they appear in the API request, each with its own description). Default to
@@ -219,22 +209,16 @@ const sfx = new AudioPlayer(src)   // src: asset('./x.mp3') or URL; same API: ne
 // .dispose() — frees the native player; ANY use after dispose throws
 // No pitch control, no auto-pooling: for overlapping SFX create several players up front and rotate.
 
-// ===== INPUT (keyboard / mouse / gamepad) =====
-// A mouse button IS a key; so is a gamepad button. One code vocabulary: KeyboardEvent.code ('KeyW',
-// 'Space', 'ArrowLeft'), 'MouseLeft|Right|Middle', 'GamepadSouth|East|West|North|L1|R1|L2|R2|Start|…'.
-Input.key(code): boolean              // held NOW — poll in setLoop for continuous movement (multiply by dt)
-Input.on('keydown', e => …)           // one-shot actions: e.code, e.repeat (auto-repeat), e.gamepad (pad index)
-Input.on('keyup', e => …)             // release (charged shots); Input.off(name, fn) to remove
-Input.mouse.delta                     // { x, y } motion during the previous frame — FPS look; works while locked
-Input.mouse.position / .wheel         // cursor in logical px / wheel notches this frame
-Input.mouse.lock() / unlock() / locked   // hide + confine the cursor (call lock() from a keydown — web needs a gesture)
-Input.gamepad(0).axis('leftX' | 'leftY' | 'rightX' | 'rightY' | 'leftTrigger' | 'rightTrigger')   // −1..1 / 0..1
+// ===== INPUT (keyboard) =====
+
+Input.key(code: string): boolean   // is the key held NOW; KeyboardEvent.code names: 'KeyW', 'Space', 'ArrowLeft'
+// Poll-only — there are NO key events. For "pressed this frame", latch previous state:
+const wasDown: Record<string, boolean> = {}
+const pressed = (c: string) => Input.key(c) && !wasDown[c]
 setLoop(dt => {
-  yaw -= Input.mouse.delta.x * 0.003 + Input.gamepad(0).axis('rightX') * 2 * dt
-  const x = (Input.key('KeyD') ? 1 : 0) - (Input.key('KeyA') ? 1 : 0) + Input.gamepad(0).axis('leftX')
+  if (pressed('Space')) jump()
+  for (const c of ['Space', 'KeyE']) wasDown[c] = Input.key(c)   // latch at END of frame
 })
-Input.on('keydown', e => { if (e.code === 'Space' || e.code === 'GamepadSouth') jump() })
-// No one-frame "pressed" polls (keyDown/actionDown) — discrete = event, continuous = poll.
 
 // ===== TOUCH GESTURES =====
 // 'click' fires on pointer-up over a target; 'touchstart' on pointer-down. ev: { clientX, clientY,
@@ -282,23 +266,17 @@ implement what you can with the loaded ones.
 // Canvas: Canvas (retained 2D drawing baked to a texture — sprites/UI images), Bitmap
 // Aspects: Aspect base — attachable node capabilities: node.aspect(Class, opts), custom aspects
 //          with per-frame update(dt)
-// UI: UIScreen, Router, UITabs (bottom-tab shell), UIPager (tabs + per-tab stacks), UIRow,
-//     UIColumn, UIScrollable, UISpacer, UIText, UIImage, UIVideo,
+// UI: UIScreen, Router, UIRow, UIColumn, UIScrollable, UISpacer, UIText, UIImage, UIVideo,
 //     UIButton, UIInput, UITextArea, UIWidget/UIModal/UIPopover/UIBottomSheet (floating
 //     overlays: HUD / dialog / anchored menu / draggable sheet), UIVirtualizedList,
 //     registerFont; UIBox (deprecated)
 // 2D engine: Scene2D, Node2D, Camera2D, Sprite, SpriteAnimation, Tilemap, Texture2D,
 //            Shape2D + Physics2D + Trigger2D + CharacterController2D (Box2D physics, sensors,
-//            raycast/overlap queries, picking),
-//            defineScene2d (declarative *.scene2d.ts files) + cells + CameraFollow
+//            raycast/overlap queries, picking)
 // 3D engine: Scene, Node, Camera, Mesh (box/sphere/cylinder/plane), Model (.glb) + ModelAnimation,
 //            Geometry, Material (lit/unlit/custom shaders), Texture, Light.sun(),
 //            Shape + Physics + Trigger + CharacterController (Jolt physics, raycast),
 //            Particles + dynamic/dynamicColor, Ray, Plane, Noise
-// 3D scene files: defineScene (declarative *.scene.ts read/written by the visual scene editor;
-//            default export is a SceneHandle: load()/open()) + use/ref/make in the def,
-//            scenario aspects MoveTo/FollowPath/Spin/LookAt/PlayAnimation;
-//            *.editor.ts + EDITOR/InspectorUI are editor-plugin files — never edit or import them
 // AR: ARScene (camera passthrough, anchors, placement gestures via addControls)
 
 // ===== CANVAS — retained drawing baked to a texture (engine-independent) =====
@@ -377,13 +355,15 @@ node.lookAt(point: Vec3Like, mode = '-z', up = [0, 1, 0]): this   // aim a local
 // 'click'                  pointer-up over the node — REQUIRES a Shape aspect (pick body)
 // 'touchstart'             pointer-down over the node (ev.track() drags) — requires Shape
 // 'enter' / 'exit'         (other: Node) physics contact / trigger overlap began/ended — Shape + Physics/Trigger
+// 'completed'              (clip: number) non-looping GLB clip finished — Model only
+// 'loopReached'            (clip: number) looping GLB clip wrapped — Model only
 // Without a Shape a node is INVISIBLE to taps — only scene listeners fire (ev.target === null).
 
 // ===== ASPECTS =====
 // Capabilities attach to nodes as aspects and chain; each adds a named accessor:
 node.aspect(Class, opts?)          // attach + configure; returns the node (typed with the accessor)
 node.get(Class) / node.has(Class) / node.removeAspect(Class)
-// Named accessors: node.physics, node.trigger, node.controller, node.shape, node.anim
+// Named accessors: node.physics, node.trigger, node.controller, node.shape, model.anim
 // Custom game logic = your own aspect with per-frame update(dt seconds):
 class Spin extends Aspect<'spin', Node> {        // <accessor name, node kind>
     speed = 90                                   // class fields = configurable defaults (opts override)
@@ -451,34 +431,24 @@ const hero = await Model.load(asset('./hero.glb'))   // asset path | https URL |
 scene.add(hero)                    // a Model IS a Node — transform/events/aspects all apply
 hero.traverse(n => { if (n.name === 'Sword') n.visible = false })   // GLB internals are plain child Nodes
 
-// Animation — every Model has an Animator pre-attached at model.anim (clip list = the glb's clips). A layer
-// has a LOOP (what it rests on) and ONE-SHOTS played over it; any call overrides what's there over its own fade:
-hero.anim.clips / hero.anim.clip('Run') / hero.anim.clip(0)   // AnimationClip[] (file order) / by name / by index; unnamed clips = 'animation_0', …
-hero.anim.playLoop('Idle', { fade: 0.2 })                     // rest on a looping clip (crossfades from whatever plays); hero.anim.loop reads it
-const loco = hero.anim.playLoop({ Idle: 0, Walking: 2, 'Fast Run': 6 })   // a BLEND as the loop (1D; [x, y] positions = 2D)
-loco.value = speed                                            // position on the axis — members stay in phase (no foot sliding)
-const ok = await hero.anim.play('slash', { fadeIn: 0.1, fadeOut: 0.3 })   // one-shot over the loop, returns to it
-// fades default to 0 (cut): fade = both ends, fadeIn / fadeOut = one end. Unknown name warns, plays nothing.
-// The await resolves at the HAND-OVER (end − fadeOut) with true (false = cut short) — what you start right after is what
-// the clip fades into: chains crossfade: if (ok) await hero.anim.play('slash2', { fadeIn: 0.3, fadeOut: 0.3 })
-// then hero.anim.playLoop('Crouch', { fade: 0.3 }) — or nothing = back to the current loop.
-if (!hero.anim.busy) hero.anim.play('kick')    // busy = a one-shot hasn't handed over; play() always takes over otherwise
-hero.anim.stop({ fade: 0.2 })                  // everything off → rest;  hero.anim.busy;  hero.anim.speed = 0.3 (0 = pause)
-// p = play(): p.done (return THIS from async fns) / p.playing / p.progress / p.weight / p.stop({ fade }) / p.seek(t)
-// Clips from other files (Mixamo: one GLB per animation), procedural, sliced — add by name:
-const [idle, slash] = await Promise.all([AnimationClip.load(asset('./idle.glb')), AnimationClip.load(asset('./attacks.glb'), 'Slash')])
-hero.anim.addClip('slash', slash).addClip('kick', hero.anim.clip('Kick').slice(0.2, 1.1))   // slice = a sub-range, re-timed
-AnimationClip.from({ tracks: { Hips: { position: [[0, [0,0,0]], [1, [0,0.05,0]]] } } })   // curves in code, binds by node NAME
-// Clip events live on the CLIP, in SECONDS: slash.addEvent(0.4, 'hit') → hero.anim.on('hit', (clip, layer) => dealDamage())
-// Layers (legs walk, arms aim): const upper = hero.anim.addLayer({ mask: 'Spine1' }); upper.playLoop('Aim', { fade: 0.3 }); upper.stop()
-//   { additive: true } = each clip's DELTA vs its first frame on top (recoil, breathe); upper.weight = 0.5
-// Root motion (clips whose hips travel — Mixamo without 'In Place', rolls): hero.anim.rootMotion = true → the node moves
-//   (or its CharacterController, as a velocity — it collides); the bone stays put
-hero.bone('RightHand')?.add(sword)  // bones are Nodes — sockets
-// FBX assets (Mixamo exports FBX): `lecodes assets convert hero.fbx --clips Idle.fbx Run.fbx -o hero.glb` → one GLB, clips merged by bone name
-// IK — late-phase aspects ON BONES (over the Animator's pose): TwoBone on the END bone, LookAt on the bone itself
-hero.bone('LeftFoot').aspect(IK.TwoBone, { target: footPoint, pole: kneeHint }).ik.weight = grounded ? 1 : 0
-hero.bone('Head').aspect(IK.LookAt, { target: camera, limit: 70 })   // axis = bone-local forward, default [0,0,-1]
+// Animation — every Model has the ModelAnimation aspect pre-attached at model.anim:
+hero.anim.clips                    // { name: string, duration: number }[] baked into the glb
+hero.anim.play(clip?: string | number, options?: { loop?: boolean }): this   // no arg = replay current
+hero.anim.stop(): this
+hero.anim.playing = true           // get/set pause/resume
+hero.anim.speed = 1.5              // playback rate
+hero.anim.time = 0.5               // seek, seconds
+// Clip-end events fire on the NODE (not on .anim), payload = clip index:
+hero.addEventListener('completed', clip => {})     // non-looping clip finished (playing flips false)
+hero.addEventListener('loopReached', clip => {})   // looping clip wrapped
+
+// LIMITS — plan around these:
+// - No cross-fade/blending: play() hard-switches clips next frame; one clip at a time.
+// - play('BadName') is SILENTLY ignored — the old clip keeps playing. Check model.anim.clips.
+// - Models CANNOT be cloned. A spawn pool = load N copies UP FRONT and recycle them:
+const POOL = 8
+const stones = await Promise.all(Array.from({ length: POOL }, () => Model.load(asset('./stone.glb'))))
+const spawn = () => { const s = stones[next++ % POOL]; s.position = [rx(), 8, rz()]; scene.add(s) }
 
 // ===== PHYSICS (Jolt) =====
 
@@ -494,18 +464,9 @@ node.aspect(Shape, {
     sphere?: number,                                    // radius
     cylinder?: { halfHeight: number, radius: number },  // Y-aligned
     capsule?: { halfHeight: number, radius: number },   // halfHeight = cylinder section only
-    mesh?: true | 'convex',                             // the node's OWN triangles (Mesh geometry or Model GLB, × world scale)
-    origin?: Vec3Like,                                  // collider centre, offset from the node's pivot (world units, node rotation, NOT scaled)
     raycast?: boolean,                                  // default true; false = invisible to taps & raycasts
 })
-// mesh: true = exact triangle mesh → level geometry / terrain / ramps: static or kinematic Physics, Trigger,
-// pick bodies, character ground. NEVER dynamic (Physics throws). mesh: 'convex' = convex hull → dynamic props.
-// A Model collider is its bind pose (skinned parts skipped) — animated characters keep a capsule.
 node.aspect(Shape, {})             // auto: box from the mesh AABB × world scale — right for most meshes
-// origin: art modelled ABOVE its pivot (a character on its feet, a barrel on its base) needs the
-// collider lifted: { capsule: {…}, origin: [0, 0.9, 0] }. An auto shape already centres on its mesh.
-node.shape.fit(kind?)              // measure dimensions + origin from what the node RENDERS (subtree,
-// so a Model root works where {} can't) and rebuild the live collider. Fit AFTER Model.load resolves.
 // A bare Shape (no Physics) creates a STATIC pick-only body → the node gets 'click'/'touchstart'.
 // It snapshots the transform at attach time — a MOVING pickable object needs a Physics body too.
 
@@ -515,14 +476,11 @@ node.aspect(Shape, {}).aspect(Physics, {
     mass?: number,                                 // kg, dynamic only; default 1
 })
 node.physics.velocity              // Vec3 world units/s — get (fresh copy) / set
-node.physics.angularVelocity       // Vec3 DEGREES/s about each world axis — get / set
 node.physics.applyImpulse(v): this // instant impulse, wakes the body
-node.position = [x, y, z]          // place / teleport — moves the node AND its body (no moveTo())
-node.eulerAngles = [0, 90, 0]      // orientation is routed to the body too (NOT for a CharacterController)
-// A teleport keeps BOTH velocities: putting an object down is velocity = 0, angularVelocity = 0, position = p
-// PHYSICS OWNS a dynamic body's transform: a position write teleports, but the sim takes over again —
-// drive motion with velocity / applyImpulse. READING node.position/worldPosition is always correct.
-// static = never moves (floors, walls); kinematic = write position each frame, pushes but isn't pushed.
+node.physics.moveTo(p): this       // drive a kinematic body (or teleport)
+// PHYSICS OWNS a dynamic body's transform: never set node.position per frame — drive velocity /
+// applyImpulse instead. READING node.position/worldPosition is always correct.
+// static = never moves (floors, walls); kinematic = script-driven via moveTo, pushes but isn't pushed.
 
 // Contact events — on BOTH nodes of a contact/overlap, arg = the other node:
 crate.addEventListener('enter', (other: Node) => {})
@@ -566,8 +524,7 @@ sparks.destroy()                             // from Node — removes the system
 
 scene.camera                       // a Node — never constructed; every scene owns one.
                                    // (Who MOVES it is mode-specific — see the Scene/AR section.)
-camera.fov / .near / .far          // lens: vertical FOV degrees (60), clip 0.01 / 1000 — SETTABLE.
-camera.setProjection({ fov, near, far })   // any subset; .horizontalFov, .displaySize stay read-only
+camera.fov                         // vertical FOV, DEGREES (read-only); .horizontalFov, .displaySize
 camera.getViewDirection(screenX, screenY): Vec3   // world dir through a screen point (logical px = ev.clientX/Y)
 camera.getRay(screenX, screenY): Ray              // origin = camera.worldPosition + that direction
 
@@ -742,129 +699,14 @@ setLoop(() => {
     if (Input.key('Space')) hero.controller.jump()
 })
 
-// HUD over the 3D view: a UIWidget ATTACHED to the scene. (A UIScreen would REPLACE the scene —
-// exactly one Presentable is visible at a time.)
+// Transparent HUD over the 3D view (see UI section)
 let scoreLabel: UIText
-const hud = UIWidget(
+const hud = UIScreen([
     scoreLabel = UIText('Score: 0').style({ color: 'white', fontSize: 24, fontWeight: 700 }),
-).style({ top: 'max(safe-top, 16px)', right: 16 })
+]).style({ p: 16, pt: 'max(safe-top, 16px)', alignItems: 'flex-end' })
 
 scene.open()
-hud.attachTo(scene).show()
-</file>
-
-## Scene files (.scene.ts)
-
-Projects may contain `*.scene.ts` files: declarative scenes that the platform's VISUAL scene
-editor reads and writes. The user may have built them by dragging models around — treat the file
-as their artwork. You may edit values and add nodes/aspects, but keep the `defineScene({...})`
-literal-object shape; an imperative rewrite (`new Scene()` + `scene.add(...)`) destroys their
-ability to keep editing it visually. `defineScene`, `use`, `ref` and `make` are globals.
-
-// ===== DEFINE SCENE =====
-
-// Default-export exactly one defineScene call per .scene.ts file.
-export default defineScene({
-  env?: SceneOptions,        // same options object as `new Scene(...)` above (skybox, ibl, bloom…)
-  nodes?: {
-    name: {                  // names are sibling-unique, no '/' or ':' in them
-      // -- source: AT MOST ONE of these per node; none = empty group node --
-      mesh?: { kind: 'box', size?: n | [x,y,z] } | { kind: 'sphere' | 'cylinder' | 'plane', ... },
-      model?: string,        // GLB via the asset macro: asset('./hero.glb')
-      light?: { kind: 'sun', direction?, intensity?, shadowsQuality? },  // 'sun' is the ONLY kind
-      camera?: { fov?, near?, far? },  // this node IS the scene camera (defaults 60 / 0.01 / 1000)
-      make?: make(factoryFn, { ...literalArgs }),  // code-built subtree from a user function
-      prefab?: SceneHandle,  // another .scene.ts's default export (import it)
-      // -- for a mesh source --
-      material?: { lit: { color?, metallic?, roughness? } } | { unlit: { color? } },
-      // -- transform / render --
-      position?: [x,y,z], eulerAngles?: [x,y,z], scale?: [x,y,z] | n,
-      visible?, castShadows?, receiveShadows?,
-      locked?: boolean,      // editor-only flag, zero runtime effect — leave it alone
-      // -- behavior / hierarchy --
-      aspects?: [ use(AspectClass, { ...props }) ],  // props may use ref('otherNode') for node refs
-      children?: { name: { ...same shape } },
-      // pose parts INSIDE a model/prefab, and attach a child node to such a part:
-      overrides?: { 'Bone/Path': { position?, eulerAngles?, scale?, visible? } },
-      mount?: 'Bone/Path',   // parents this node to that part of the PARENT node's asset
-    },
-  },
-})
-
-// ===== USING A SCENE FROM APP CODE =====
-
-import city from './city.scene'            // extension-less specifier; default export: SceneHandle
-
-const { scene, nodes, get } = await city.open()  // load (fetches GLBs) + become the active view
-// city.load() — instantiate without showing; both are idempotent (same instance every call)
-nodes.crate                          // typed by source: model → Model, mesh → Mesh, light → Light
-nodes['props/lamp']                  // keys are absolute '/'-joined paths; get(path) for dynamic
-nodes.crate.position = [1, 0.5, 2]   // plain SDK nodes — assign vectors, or scalar axes: node.y = 2
-nodes.hero.anim.play('walk')         // a model node is a Model: animations, parts — all there
-scene.close()                        // closing goes through the scene (there is NO handle.close())
-
-// ===== BEHAVIOR & INPUT =====
-
-// Put per-frame behavior in ASPECTS attached in the file — not in code that mutates the doc:
-//   aspects: [use(Spin, { speed: 40 })]
-// Built-in no-code aspects: MoveTo, FollowPath ({ path: ref('waypoints'), duration }), Spin,
-// LookAt, PlayAnimation. Custom ones are ~5 lines (see Aspects; update(dt) — dt in SECONDS):
-export class Spinner extends Aspect<'spinner'> {
-  speed = 30                                   // class fields = props settable from use(...)
-  update(dt: number) { this.node.eulerAngles = [0, this.node.eulerAngles.y + this.speed * dt, 0] }
-}
-// Clicks/taps: a node is pickable only with a Shape aspect — aspects: [use(Shape, {})] — then
-// nodes.crate.addEventListener('click', ev => ...). Catch-all with target (null on miss):
-// scene.addEventListener('click', ev => ev.target). Shape alone = static pick body; moving
-// clickables also need Physics.
-
-// ===== UI OVER AN OPEN SCENE =====
-
-// Exactly one Presentable is visible at a time: UIScreen(...).open() REPLACES the scene. A HUD is
-// a UIWidget attached to the scene — it shows/hides and transitions together with it:
-const hud = UIWidget(UIText('Score: 0').style({ color: 'white', fontSize: 24 }))
-    .style({ top: 'max(safe-top, 16px)', left: 16 })
-hud.attachTo(scene).show()
-
-// ===== SCENE FILE MISTAKES — DO NOT DO THESE =====
-
-// - Rebuilding a .scene.ts imperatively, or moving its content into main.ts. Edit the def in
-//   place; logic goes into aspect classes or app code around handle.open().
-// - scene.ref(...), handle.close(), onTap — none exist. It's nodes[path] / get(path),
-//   loaded.scene.close(), addEventListener('click').
-// - Two source keys on one node (e.g. mesh + model) — throws at load.
-// - Expecting clicks without use(Shape, {}) on the node.
-// - node.position.x = 3 — silent NO-OP (position returns a copy). Assign node.x = 3 or the vector.
-// - env HDRI paths or light kinds other than 'sun' — not supported; ibl is just a boolean.
-
-## Scene file wiring example
-
-// A scene built in the visual editor, wired up with a click counter and a HUD.
-
-<file name="main.scene.ts">
-export default defineScene({
-  env: { skybox: '#a9b6c8' },
-  nodes: {
-    camera: { camera: {}, position: [0, 4, 9], eulerAngles: [-22, 0, 0] },
-    sun: { light: { kind: 'sun', shadowsQuality: 1 } },
-    ground: { mesh: { kind: 'box', size: [12, 0.4, 12] }, material: { lit: { color: '#3d4351' } },
-              position: [0, -0.2, 0], locked: true },
-    crate: { mesh: { kind: 'box' }, material: { lit: { color: '#8a8f98' } }, position: [0, 0.5, 0],
-             aspects: [use(Shape, {}), use(Spin, { speed: 25 })] },
-  },
-})
-</file>
-
-<file name="main.ts">
-import mainScene from './main.scene'
-
-const { scene, nodes } = await mainScene.open()
-
-let taps = 0
-const label = UIText('Tap the crate').style({ color: 'white', fontSize: 20, fontWeight: 700 })
-UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 }).attachTo(scene).show()
-
-nodes.crate.addEventListener('click', () => { label.text = `Taps: ${++taps}` })
+hud.open()
 </file>
 
 // ===== UI RULES =====
@@ -875,22 +717,18 @@ nodes.crate.addEventListener('click', () => { label.text = `Taps: ${++taps}` })
 
 // ===== UI COMPONENTS =====
 // Every element is created by a global factory function (never `new`) that takes only the element's
-// CONTENT — children as plain arguments (or text/src/...). Everything else — styles, handlers — is
-// configured by chaining: every configuring method returns the element itself, so construction reads
-// as one chain.
-UIColumn(UIText("Title"), UIButton(UIText("Go")))
-// An ARRAY argument is flattened into the children — pass items.map(Row) directly, no spread:
-UIColumn(header, items.map(Row), footer)
+// CONTENT (children array, text, src, ...). Everything else — styles, handlers — is configured by chaining:
+// every configuring method returns the element itself, so construction reads as one chain.
 
 // UIRow, UIColumn — containers (UIColumn stacks vertically, UIRow horizontally)
-UIRow(...children) / UIColumn(...children)
+UIRow(children) / UIColumn(children)
 // Child management — imperative, no diffing; works before and after the element is on screen:
 //   .append(...nodes), .insert(index, ...nodes), .remove(...nodes), .setContent(nodes), .children (readonly)
 // .setContent is the "re-render" primitive — build a fresh array (items.map(Row)) and swap it in.
 // For long or unbounded data use UIVirtualizedList instead of setContent over a big array.
 
 // UIScreen — root screen, always fills the device. Behaves as a UIColumn.
-UIScreen(...children)
+UIScreen(children)
 // .open() / .close() — show/close directly (single-screen apps; open() while a Router is active hides the router)
 // .onOpen(cb), .onClose(cb) — fire on EVERY activation, not just the first: Router.push away fires onClose,
 //   popping back fires onOpen again. Anything started in onOpen (loops, intervals, sockets) MUST be stopped
@@ -898,40 +736,12 @@ UIScreen(...children)
 // .onTouchStart(cb) — fires for touches anywhere on the screen; use for full-screen gestures (see TOUCH GESTURES above)
 // .onBackPressed(cb) — Android hardware/gesture back; typically Router.pop()
 // Screens NEVER scroll — the canonical screen is fixed chrome (header, tab bar) + ONE UIScrollable body
-//   with flexGrow: 1: UIScreen(Header(), UIScrollable(content).style({ flexGrow: 1 }))
+//   with flexGrow: 1: UIScreen([ Header(), UIScrollable([...content]).style({ flexGrow: 1 }) ])
 // Note: a screen always fills the device — sizing styles on it (width, height, flexGrow, flexShrink, position) are no-ops
 
-// UITabs — THE bottom-tab app shell: swipeable tabs (a UIPager) + a themed tab bar, as one UIScreen.
-// USE THIS for every tabbed app — never hand-build a tab bar. Keys are tab ids, in tab order:
-const tabs = UITabs({
-    home:    { label: "Home",    icon: assetIcon("lucide:house"), screen: homeScreen },
-    profile: { label: "Profile", icon: assetIcon("lucide:user"),  screen: profileScreen },
-})
-Router.init(tabs)          // UITabs IS a UIScreen — present it directly
-// .select(id), .tab (getter), .onSelect(cb(id, i)) — fires on a bar tap, swipe, or select()
-// .badge(id, value) — true = dot, number/string = count pill, false/null/0 clears
-// .pager — the UIPager underneath; UIPager.push(detail) from any screen keeps the bar
-// Styling is THEME-driven: theme({ primaryColor, mutedColor, tabbarBg, tabbarBorder, badgeColor })
-//   restyles the bar app-wide (dark fallbacks built in). For a custom bar layout use UIPager below.
-
-// UIPager — the navigation primitive under UITabs: sibling tabs that swipe natively, each tab its
-// OWN push/pop stack. Reach for it directly for a plain stack (one-screen pager) or a fully custom
-// tab bar. Renders no bar — build your own next to it; give the pager flexGrow: 1.
-UIPager(...tabs)   // the tab root screens (arrays flatten); tabs are FIXED at construction
-// .select(i, animated?) (instant by default), .index, .onSelect(cb(i)) — fires for taps AND swipes: sync the
-//   bar highlight here. Tabs keep their stack/scroll state when switched away and back.
-// .push(screen) — slides onto the CURRENT tab; edge back-swipe / Android back pops natively.
-//   .pop(), .popToRoot(), .replace(screen), .depth (tab swiping is disabled while > 1), .onChange(cb(depth))
-// Ambient from any screen, no reference needed: UIPager.push(screen) / UIPager.pop() / UIPager.current
-// pager.push = detail INSIDE the tab (bar stays); Router.push = above the whole shell (bar covered).
-// Note: tab screens are built up front, but onOpen fires only when the tab becomes visible (maybe never) —
-//   load initial data at build time, keep onOpen for re-entry.
-const pager = UIPager(homeTab, searchTab, profileTab).style({ flexGrow: 1 })
-Router.init(UIScreen(pager, tabBar))   // bar buttons: .onClick(() => pager.select(i))
-
 // UIWidget — floating overlay, independent of screens, always position: fixed in device coordinates
 // Persists across Router navigation — create ONCE at module scope, reuse; hidden by default.
-UIWidget(...children)
+UIWidget(children)
 // .show(), .hide(), .isShow (getter), .onTouchStart(cb), .onBackPressed(cb)
 // extra style: overlayColor — full-screen scrim BEHIND the widget that blocks taps underneath, turning it into
 //   a modal; null (default) = no layer, "transparent" = invisible but still blocks. A scrim tap fires
@@ -943,7 +753,7 @@ UIWidget(...children)
 // UIModal — a UIWidget prewired as a dialog: USE THIS for confirm/alert dialogs
 // Scrim on by default (overlayColor "rgba(0,0,0,0.5)"), animated show/hide (200ms fade), scrim tap and
 // back button close it automatically. Create ONCE at module scope, like any widget.
-UIModal(...children)
+UIModal(children)
 // .show(), .hide() (animated on a modal), .isOpen (getter), .onOpen(cb), .onClose(cb), .dismissible(false)
 //   — plus the full UIWidget surface
 // .transition(hidden) — replace the show/hide animation: `hidden` is the off-screen pose (show animates FROM
@@ -954,7 +764,7 @@ UIModal(...children)
 // UIBottomSheet — a UIModal pinned to the bottom edge: USE THIS for every bottom sheet, never hand-build one
 // Content-sized by default (as tall as its children, capped at the screen) — one position, drag down to
 // dismiss: the action-sheet shape. Native hosts own the drag (snap, velocity, scroll handoff); web shows it static.
-UIBottomSheet(...children)
+UIBottomSheet(children)
 // .detents([0.3, 0.6, 1]) — snap positions, ascending fractions of screen height (the map-app model). Call
 //   BEFORE show(); sizes the sheet to the HIGHEST detent — lower detents show the top slice of the content.
 // .setDetent(i) (animated), .detent (getter), .onDetentChange(cb(i)) — every settle: finger snap or setDetent()
@@ -967,33 +777,30 @@ UIBottomSheet(...children)
 // Transparent intercepting scrim (outside tap dismisses; content under it can't scroll), 120ms fade,
 // automatic placement: below the anchor, flips above near the bottom edge, clamped into the viewport.
 // Attaches itself to Presentable.current (hides with the page it opened on).
-UIPopover(...children)
+UIPopover(children)
 // .show(anchor?) — anchor: any element, or { x: ev.clientX, y: ev.clientY } for long-press context menus
 // .hide() — plus the full UIModal surface (isOpen, onOpen/onClose, dismissible, transition)
 // Style the menu box yourself (width, bgColor, borderRadius); do NOT set left/top — show(anchor) owns them.
 
 // UIScrollable — THE scroll container: a screen's scrolling body, a list under a pinned header, a carousel
-UIScrollable(...children)
+UIScrollable(children)
 // extra styles: scrollDirection ("horizontal" | "vertical", default vertical), showScrollbar: boolean,
 //               overscrollMode ("none" | "absorb" | "default"), refreshControlColor — tints the pull-to-refresh spinner,
 //               keyboardDismissMode ("interactive" | "scroll" | "none") — "scroll": any drag dismisses the keyboard at once (search lists)
-//               snap ("none" | "start" | "center" | "end", default "none") — paging: a released drag settles on a
-//                 direct child's boundary; the value picks where the child rests in the viewport. Snap targets are
-//                 the children themselves, so item widths can differ. (Mobile hosts; web degrades to free scrolling.)
 // .onScroll(cb(pos)), .onScrollRelease(cb), .onOverscroll(cb(delta))
 // .onRefresh(async cb) — pull-to-refresh; spinner stays until the returned promise settles. Attach BEFORE the
 //   element mounts; vertical only; native hosts (web preview: no-op). UIVirtualizedList has the same contract.
 // Note: NO programmatic scrolling (no scrollTo) — if you need scrollTo/scrollToEnd, use UIVirtualizedList
 // Note: defaults flexShrink: 1 (scrolls instead of overflowing); wrapping ancestors still need flexShrink: 1
 //   themselves. flexGrow: 1 to fill the remaining space is still yours to set.
-// Carousel = scrollDirection: "horizontal" + FIXED-width cards + snap: "start" ("center" for a card-deck-with-peek)
+// Carousel = scrollDirection: "horizontal" + FIXED-width cards (explicit width on each card, gap/px on the scrollable)
 
 // UIVirtualizedList<T> — windowed list for LONG or unbounded data (feeds, chats, search results): only the
 // visible rows (plus a buffer) are mounted. Use it instead of UIScrollable + map() whenever the item count
 // is large, grows over time, or is unknown.
 UIVirtualizedList<T>({
     keyOf: (item: T) => string,            // STABLE unique id per item (never the array index)
-    render: (item: T) => UINodeChild,      // builds one row; called lazily as rows enter the window
+    render: (item: T) => UIElement,        // builds one row; called lazily as rows enter the window
     estimatedHeight: number | ((item: T) => number),  // px guess per row (real height measured after mount)
     overscan?: number,                     // extra px mounted above/below the viewport (default: one viewport)
     inverted?: boolean,                    // true = chat mode: starts scrolled to the end, append at bottom auto-scrolls
@@ -1042,7 +849,7 @@ player.play()   // stop playback in the screen's onClose; .dispose() when gone f
 
 // UIButton — the only TAPPABLE container: a UIRow with children centered on both axes by default.
 // To make anything clickable (a card, a list row, an icon) — wrap it in a UIButton.
-UIButton(...children)
+UIButton(children?)
 // .onClick(cb), .onTouchStart(cb), .isPressed()   // gestures: see TOUCH GESTURES above
 // extra styles: onPressed: { bgColor, opacity, ..., duration? } — style while the finger is down;
 //               rippleColor ("default" or a Color, Android only)
@@ -1081,7 +888,7 @@ UIInput() / UITextArea()
 
 // UISpacer — flexible empty space (defaults flexGrow: 1), eats free space along the main axis.
 // Only when plain alignment can't express it (one item pushed to the far end while the rest stay put):
-UIRow(title, UISpacer(), closeButton)
+UIRow([ title, UISpacer(), closeButton ])
 // If ALL children move together, justifyContent ("space-between", "flex-end", ...) does it with no extra element.
 
 // @deprecated UIBox — legacy centered container: defaults justifyContent AND alignItems to "center"
@@ -1096,13 +903,9 @@ UIText("Hi").style({ color: "white" }).style({ fontSize: 20 }).onClick(...)
 //   1. .style({...})           → declarative merge, the default. Use this 99% of the time.
 //   2. el.style.foo = bar      → direct single-property mutation after creation (hot paths),
 //                                e.g. el.style.transform = `translateY(${y}px)`; el.style.foo reads it back.
-//   3. .animateTo({..., duration, delay?, commit?, loop?})  → tween current → given values (duration in MS).
+//   3. .animateTo({..., duration, delay?, commit?})  → tween current → given values (duration in MS).
 //        Targets are COMMITTED into the style immediately; pass commit: false to play without persisting —
 //        the exit-animation pattern (fade an overlay, then .hide(); next show() starts from the intact style).
-//        loop: true | n repeats the tween — loopMode: "ping-pong" (default: there and back) or "restart"
-//        (snap back + replay — full-turn spinners via transform: "rotate(360deg)", shimmers). A looping
-//        animation is an effect, not a state change: it never commits, delay applies once, and it stops on
-//        the element's next animateTo/animateFrom or when it leaves the screen. (web/iOS/desktop; Android plays once until its next runtime.)
 //   4. .animateFrom({..., duration, delay?})          → snap to given values, animate back to current (fade-in).
 //        Never modifies the stored style.
 // For free-value tweens use animate() — see ANIMATION above.
@@ -1180,28 +983,9 @@ label.style({ color: T.primaryColor, pl: "var(--comfort-left)" })
 .style({ flexDirection: "column", p: 16, onLandscape: { flexDirection: "row", p: 32 } })
 // Keys: onLandscape, onPortrait.
 
-// --- Style classes ($name) — named states that CASCADE ---
-// A $-prefixed key in .style() declares a named style state (like onPressed, but yours: selected,
-// checked, expanded); duration/delay inside the block animate the swap. Drive it via el.class:
-const item = UIButton(UIText("Wi-Fi")).style({ bgColor: "#151515", $selected: { bgColor: "#1d2b45", duration: 150 } })
-item.onClick(ev => ev.target.class.selected = !ev.target.class.selected)
-// el.class.selected reads/writes a boolean; el.class({ a: true, b: false }) is the chainable batch
-// form; names work with or without the $. Class state persists across screen close/reopen.
-// CASCADE: a class set on an element also activates same-name $ blocks on ALL its descendants —
-// one toggle restyles a whole composite control, each part declaring its own reaction:
-UIButton(
-    UIImage(icon).style({ tintColor: "#888", $selected: { tintColor: "#5b8cff" } }),
-    UIText("Label").style({ color: "#888", $selected: { color: "#5b8cff" } }),
-)   // .class.selected = true → icon AND label restyle (the cascade stops at hosted screens/widgets)
-// $pressed / $focused are RESERVED — the system toggles them (finger down / input focused) and they
-// CASCADE, so a button's children can restyle during its press. onPressed/onFocused stay
-// own-element-only — use those on nested interactives (a button inside a clickable card):
-UIButton(UIText("Buy").style({ $pressed: { color: "#999" } })).style({ $pressed: { transform: "scale(0.97)" } })
-// Precedence on the same prop: base < $classes < $pressed/$focused < onPressed/onFocused.
-
 // --- Defaults that surprise ---
-// flexShrink: 0 — elements don't shrink to fit (exception: UIScrollable, UIVirtualizedList and UIPager
-//   default flexShrink: 1 so they shrink/scroll instead of overflowing; wrapping ancestors still default to 0).
+// flexShrink: 0 — elements don't shrink to fit (exception: UIScrollable and UIVirtualizedList default
+//   flexShrink: 1 so they scroll instead of overflowing; wrapping ancestors still default to 0).
 // flexGrow: 0 — nothing grows along the main axis without asking; no implicit min-sizes either.
 // alignItems: "stretch" — children FILL the cross axis by default; set a size or alignSelf to opt out.
 // overflow: "hidden" — children are clipped to the parent's box; set overflow: "visible" to let them escape.
@@ -1218,10 +1002,10 @@ UIButton(UIText("Buy").style({ $pressed: { color: "#999" } })).style({ $pressed:
 // ===== REUSABLE COMPONENTS =====
 // Extract repeated UI into factory functions — they return elements you can chain methods on:
 
-const ClickableCard = (title: string, subtitle: string) => UIButton(
+const ClickableCard = (title: string, subtitle: string) => UIButton([
     UIText(title).style({ fontWeight: 700, color: "white" }),
     UIText(subtitle).style({ color: "#888", fontSize: 13 })
-).style({ px: 16, py: 12, gap: 4, flexDirection: "column", alignItems: "flex-start" })
+]).style({ px: 16, py: 12, gap: 4, flexDirection: "column", alignItems: "flex-start" })
 
 // Use like any other element — chain after the call:
 ClickableCard("Title", "Subtitle").style({ bgColor: "#111" }).onClick(() => ...)
@@ -1230,15 +1014,15 @@ ClickableCard("Title", "Subtitle").style({ bgColor: "#111" }).onClick(() => ...)
 const headingStyle: Style<UIText> = { color: "#ffffff", fontSize: 24, fontWeight: 700 }
 
 // ===== CAPTURING ELEMENT REFERENCES =====
-// Use an assignment expression right in the children — standard TypeScript:
+// Use an assignment expression inside the children array — standard TypeScript:
 
 let label: UIText
 let input: UIInput
 
-UIColumn(
+UIColumn([
     label = UIText("Hello"),   // = both assigns the variable AND adds the element to the column
     input = UIInput(),
-)
+])
 
 // Later:
 label.text = "Updated"
@@ -1248,17 +1032,15 @@ input.value  // read current value
 // ((button.children[0] as UIText).text vs buttonText.text).
 
 // ===== CONDITIONAL CHILDREN =====
-// A null / undefined / false child is skipped — no element, no layout slot.
-UIColumn(header, isLoading ? spinner : null, showFooter && footer)
-// Works for whole blocks too — a falsy argument is skipped, an array argument is flattened:
-UIColumn(header, showList && items.map(Row))
+// null / undefined / false in a children array is skipped — no element, no layout slot.
+UIColumn([ header, isLoading ? spinner : null, showFooter && footer ])
 
 // ===== SIZING: the two axes behave differently =====
 // MAIN axis (row → width, column → height): elements stay as small as their content — nothing grows
 //   without flexGrow: 1 (no implicit min-sizes).
 // CROSS axis: children fill the parent by default (alignItems defaults to "stretch"); set an explicit size
 //   or alignSelf to opt out.
-// So UIRow(UIInput()) leaves the input at placeholder width — give it flexGrow: 1 to fill the row.
+// So UIRow([ UIInput() ]) leaves the input at placeholder width — give it flexGrow: 1 to fill the row.
 // EQUAL-width children (tab bars, button pairs): flex: 1 on each — it grows from a ZERO basis, so they end up
 //   equal. flexGrow: 1 alone splits only the LEFTOVER space on top of content-sized bases — the child with the
 //   longer label stays wider.
@@ -1278,7 +1060,6 @@ UIButton().onLayout(({ width }) => { buttonWidth = width })
 // Position once at an interaction — never poll per frame.
 
 // ===== ROUTER (multi-page apps) =====
-// Tabs are UITabs' job, in-tab stacks UIPager's (see UI COMPONENTS) — the Router owns what sits ABOVE the shell.
 Router.init(homeScreen, opts?: { showDefaultBackButton?: boolean })  // call once in the entry file (default false)
 Router.push(screen)      // push onto the stack, screen becomes active
 Router.pop(to?: number)  // default -1 = one back; negative = relative (-2 = back two), 0/positive = absolute
@@ -1320,14 +1101,6 @@ import heart from './assets/heart.svg'        // or inline: asset('./assets/hear
 UIImage(heart).style({ width: 24, height: 24, tintColor: "#666" })  // tintColor recolors the icon
 // Keep inline SvgSource(`...`) only for SVG generated dynamically from data.
 
-// ===== ICONS (assetIcon) =====
-// Use real icons instead of emoji. assetIcon("pack:name") resolves the icon at COMPILE time and
-// inlines it as an image source (same shape as SvgSource) — no imports, no project files, offline.
-UIImage(assetIcon("lucide:bell")).style({ width: 24, height: 24, tintColor: "#8a8f98" })
-// The id must be a string literal; an unknown id is a compile error (with name suggestions).
-// Recolor via the tintColor style or the { color } option (hex literal bakes in; expression tints).
-// Packs: lucide, tabler, heroicons, feather, bi, carbon, mdi, ri, solar.
-
 // ===== COMMON MISTAKES — DO NOT DO THESE =====
 
 // ❌ CSS that doesn't exist here
@@ -1336,13 +1109,16 @@ calc(100% - 20px)                    // WRONG — calc() can't mix with %
 lineHeight: 1.5                      // WRONG — number is px (=1.5px); for a multiplier use "1.5em"
 
 // ❌ touch handler on a non-touch element
-UIColumn(...).onTouchStart(cb)  // WRONG — only UIButton/UIScreen/UIWidget; wrap in UIButton
+UIColumn([...]).onTouchStart(...)    // WRONG — only UIButton/UIScreen/UIWidget; wrap in UIButton
 
-// ❌ let/const among the children — `let` is a statement, not an expression
-UIRow(let input = UIInput())         // WRONG
+// ❌ scrollable that overflows the screen
+// A wrapping container between the scrollable and the screen is missing flexShrink: 1
+
+// ❌ let/const inside children array — `let` is a statement, not an expression
+UIRow([ let input = UIInput() ])         // WRONG
 // ✅ declare outside, assign inside (assignment both sets the var AND appends)
 let input: UIInput
-UIRow(input = UIInput())
+UIRow([ input = UIInput() ])
 
 // ❌ setting a UIImage's content through bgImage
 const img = UIImage("")            // WRONG — empty source as a placeholder
@@ -1352,30 +1128,30 @@ const img = UIImage(url)
 img.src = newUrl                   // updates the displayed image
 
 // ❌ expecting an input to fill width like in CSS
-UIRow(UIInput())                         // WRONG — collapses to placeholder width
+UIRow([ UIInput() ])                         // WRONG — collapses to placeholder width
 // ✅ stretch it explicitly
-UIColumn(UIInput().style({ width: "100%" }))              // cross axis
-UIRow(input = UIInput().style({ flexGrow: 1 }), sendBtn)  // main axis
+UIColumn([ UIInput().style({ width: "100%" }) ])              // cross axis
+UIRow([ input = UIInput().style({ flexGrow: 1 }), sendBtn ])  // main axis
 
 // ❌ a button that should match the input's height but shrinks to its text
-UIRow(input.style({ height: 40 }), UIButton())    // button ends up shorter
+UIRow([ input.style({ height: 40 }), UIButton([...]) ])    // button ends up shorter
 // ✅ give controls the same explicit height
-UIRow(input.style({ height: 40 }), UIButton().style({ height: 40 }))
+UIRow([ input.style({ height: 40 }), UIButton([...]).style({ height: 40 }) ])
 
 // ❌ flexGrow: 1 for equal-width children — it splits only the LEFTOVER space, bases stay content-sized
-UIRow(yes.style({ flexGrow: 1 }), no.style({ flexGrow: 1 }))   // longer label = wider button
+UIRow([ yes.style({ flexGrow: 1 }), no.style({ flexGrow: 1 }) ])   // longer label = wider button
 // ✅ flex: 1 — grows from a zero basis, children end up equal
-UIRow(yes.style({ flex: 1 }), no.style({ flex: 1 }))
+UIRow([ yes.style({ flex: 1 }), no.style({ flex: 1 }) ])
 
 // ❌ empty containers as spacers to align children (web habit)
-UIRow(UIColumn().style({ flexGrow: 1 }), label)   // WRONG
+UIRow([ UIColumn([]).style({ flexGrow: 1 }), label ])   // WRONG
 // ✅ alignment is a CONTAINER property, not an extra element
-UIRow(label).style({ justifyContent: "flex-end" })
+UIRow([ label ]).style({ justifyContent: "flex-end" })
 
 // ❌ empty element as a placeholder for a conditional child
-UIRow(isGroup ? button : UIColumn())              // WRONG
+UIRow([ isGroup ? button : UIColumn([]) ])              // WRONG
 // ✅ null is skipped in children — no phantom element
-UIRow(isGroup ? button : null)
+UIRow([ isGroup ? button : null ])
 
 // ❌ pointing UIImage / bgImage at a project file by bare path — it won't resolve to the bundled asset
 UIImage("./photo.png")                              // WRONG (a plain string works only for remote http(s) URLs)
@@ -1389,7 +1165,7 @@ list.onEndReached(loadNextPage)                     // WRONG — threshold is th
 list.onEndReached(600, loadNextPage)
 
 // ❌ re-creating a UIWidget or UIVirtualizedList to "re-render"
-const openSheet = () => UIWidget(...).show()        // WRONG — leaks a new widget every call
+const openSheet = () => UIWidget([...]).show()      // WRONG — leaks a new widget every call
 // ✅ create once at module scope; show()/hide() the widget, setData/append/update the list
 
 // ===== EXAMPLES =====
@@ -1397,7 +1173,7 @@ const openSheet = () => UIWidget(...).show()        // WRONG — leaks a new wid
 // === EXAMPLE 1: Single-file app ===
 <file name="main.ts">
 let text: UIText
-const screen = UIScreen(
+const screen = UIScreen([
     text = UIText("Hello, world!").style({ mb: 16, fontWeight: 700, fontSize: 24, textAlign: "center" }),
     UIText("Your name:").style({ textAlign: "center" }),
     UIInput()
@@ -1405,188 +1181,91 @@ const screen = UIScreen(
     .onChange(str => {
         text.text = `Hello, ${str}!`
     })
-).style({ justifyContent: "center", p: 20, gap: 8 })
+]).style({ justifyContent: "center", p: 20, gap: 8 })
 
 screen.open()
 </file>
 
-// === EXAMPLE 2: Theme tokens + fetched list with loading / error states ===
-// A tokens module every screen imports, light-themed: theme({ color }) sets the default text
-// color ONCE — no color: "#111" on every label.
-<file name="tokens.ts">
-const palette = {
-    bg: "#F4F6F5", card: "#FFFFFF", border: "#E4E8E6",
-    text: "#131A17", muted: "#606B65",
-    accent: "#15A34A", accentSoft: "#E7F6ED", onAccent: "#FFFFFF",
-}
-theme({ color: palette.text, primaryColor: palette.accent })
-// Accessors ARE "var(--x)" strings — re-calling theme() with new values restyles the live app.
-export const colors: { [K in keyof typeof palette]: string } = theme(palette)
-export const font = {   // type scale — spread into styles: .style({ ...font.h2 })
-    h2: { fontSize: 22, fontWeight: 700 }, bodyStrong: { fontSize: 16, fontWeight: 600 },
-    small: { fontSize: 14 }, tiny: { fontSize: 12, fontWeight: 500 },
-}
-</file>
+// === EXAMPLE 2: Fetching data with loading state ===
 <file name="main.ts">
-import { colors, font } from './tokens'
-
 type User = { id: number; name: string; email: string }
 
-const Row = (u: User) => UIRow(
-    UIColumn(UIText(u.name[0]).style({ ...font.bodyStrong, color: colors.accent }))
-        .style({ width: 44, height: 44, borderRadius: 22, bgColor: colors.accentSoft,
-                 justifyContent: "center", alignItems: "center" }),
-    UIColumn(
-        UIText(u.name).style({ ...font.bodyStrong }),
-        UIText(u.email).style({ ...font.small, color: colors.muted }),
-    ).style({ flexGrow: 1, flexShrink: 1, gap: 2, alignItems: "flex-start" }),
-).style({ alignItems: "center", gap: 12, bgColor: colors.card, borderRadius: 16,
-          border: `1px solid ${colors.border}`, p: 14 })
-
-const Centered = (...children: UINodeChild[]) =>
-    UIColumn(children).style({ flexGrow: 1, justifyContent: "center", alignItems: "center", gap: 12 })
-
-let body: UIColumn
+let statusText: UIText
+let list: UIColumn
 
 const loadData = async () => {
-    body.setContent([Centered(UIText("Loading…").style({ color: colors.muted }))])
+    statusText.text = "Loading..."
+
     const res = await fetch("https://jsonplaceholder.typicode.com/users")
     if (res.status !== 200) {
-        body.setContent([Centered(
-            UIText("Couldn't load users"),
-            UIButton(UIText("Retry").style({ color: colors.onAccent, fontWeight: 600 }))
-                .style({ height: 44, px: 24, borderRadius: 12, bgColor: colors.accent })
-                .onClick(() => loadData()),
-        )])
+        statusText.text = "Error loading data"
         return
     }
-    body.setContent(res.json<User[]>().map(Row))   // res.json is sync — no await
+
+    const users = res.json<User[]>()  // sync — no await
+
+    statusText.text = ""
+    list.setContent(
+        users.map(user =>
+            UIColumn([
+                UIText(user.name).style({ fontWeight: 700, color: "white" }),
+                UIText(user.email).style({ color: "#888", fontSize: 13 })
+            ]).style({ px: 16, py: 12, gap: 4 })
+        )
+    )
 }
 
-const screen = UIScreen(
-    UIText("Users").style({ ...font.h2, pb: 8, px: 16 }),
-    UIScrollable(
-        body = UIColumn().style({ flexGrow: 1, gap: 8 })
-    ).style({ flexGrow: 1, p: 16, pt: 0 })                 // the ONE scrolling body — the screen itself never scrolls
-    .onRefresh(() => loadData()),            // pull-to-refresh; attached before screen.open()
-).style({ bgColor: colors.bg, pt: "comfort-top" })
-    .onOpen(() => loadData())
+const screen = UIScreen([
+    UIText("Users").style({ fontSize: 24, fontWeight: 700, color: "white", mb: 8 }),
+    statusText = UIText("").style({ color: "#888" }),
+    UIScrollable([
+        list = UIColumn([])
+    ]).style({ flexGrow: 1 })                 // the ONE scrolling body — the screen itself never scrolls
+    .onRefresh(() => loadData())              // pull-to-refresh; attached before screen.open()
+])
+.style({ bgColor: "black", p: 16, pt: "max(safe-top, 24px)" })
+.onOpen(() => loadData())
 
 screen.open()
 </file>
 
-// === EXAMPLE 3: Tabbed app — UITabs, font(), in-tab detail ===
+// === EXAMPLE 3: Simple app with navigation ===
 <file name="home.ts">
-const detailScreen = (name: string) => UIScreen(
-    UIButton(
-        UIImage(assetIcon("lucide:chevron-left")).style({ width: 20, height: 20, tintColor: "white" }),
-        UIText("Back")
-    ).style({ alignSelf: "flex-start", height: 32, gap: 4 }).onClick(() => UIPager.pop()),
-    UIText(name).style({ fontSize: 24, fontWeight: 700 }),
-    UIButton(
-        UIImage(assetIcon("lucide:heart")).style({ width: 18, height: 18, tintColor: "#8a919e", $fav: { tintColor: "#ff453a" } }),
-        UIText("Favorite").style({ color: "#8a919e", $fav: { color: "#ff453a" } })
-    ).style({ name: "fav", alignSelf: "flex-start", height: 36, px: 12, gap: 6, borderRadius: 18, bgColor: "#17181c", $fav: { bgColor: "#2a181a", duration: 150 } })
-    .onClick(ev => ev.target.class.fav = !ev.target.class.fav)   // one toggle — the $fav blocks on icon + label light up too (cascade)
-).style({ p: 16, pt: "comfort-top", gap: 16, bgColor: "black" })
-
-const Item = (name: string) => UIButton(UIText(name).style({ color: "white" }))
-    .style({ height: 52, px: 16, justifyContent: "flex-start", borderRadius: 12, bgColor: "#151515", onPressed: { opacity: 0.7 } })
-    .onClick(() => UIPager.push(detailScreen(name)))          // in-tab push: tab bar stays, back-swipe pops
-
-export const homeScreen = UIScreen(
-    UIText("Home").style({ fontSize: 28, fontWeight: 700, fontFamily: font("unbounded") }),  // display face
-    UIScrollable(["Alpha", "Beta", "Gamma"].map(Item)).style({ flexGrow: 1, gap: 8 })
-).style({ p: 16, pt: "comfort-top", gap: 16, bgColor: "black" })
+import { detailScreen } from './detail'
+
+export const homeScreen = UIScreen([
+    UIText("Home").style({ fontSize: 24, fontWeight: 700 }),
+    UIButton([
+        UIText("Go to detail").style({ color: "white" })
+    ]).style({ bgColor: "#FF4032", borderRadius: 12, p: 16, rippleColor: "default", onPressed: { opacity: 0.7 } })
+    .onClick(() => Router.push(detailScreen))
+]).style({ p: 20, pt: "max(safe-top, 24px)", gap: 16 })
 </file>
-<file name="profile.ts">
-export const profileScreen = UIScreen(
-    UIText("Profile").style({ fontSize: 28, fontWeight: 700, fontFamily: font("unbounded") })
-).style({ p: 16, pt: "comfort-top", bgColor: "black" })
+<file name="detail.ts">
+import chevronLeft from './assets/chevron-left.svg'
+
+export const detailScreen = UIScreen([
+    UIButton([
+        UIImage(chevronLeft).style({ width: 18, height: 18, tintColor: "#FF4032" }),
+        UIText("Back").style({ color: "#FF4032" })
+    ]).style({ alignSelf: "flex-start", flexDirection: "row", height: 32, gap: 4 }).onClick(() => Router.pop()),
+    UIText("Detail Screen").style({ fontSize: 24, fontWeight: 700 })
+])
+.style({ p: 20, pt: "max(safe-top, 24px)", gap: 20 })
+.onBackPressed(() => Router.pop())
 </file>
-<file name="main.ts">
-import { homeScreen } from './home'
-import { profileScreen } from './profile'
-
-theme({ fontFamily: font("manrope") })   // app-wide default text font — one line, no loading code
-
-const tabs = UITabs({
-    home:    { label: "Home",    icon: assetIcon("lucide:house"), screen: homeScreen },
-    profile: { label: "Profile", icon: assetIcon("lucide:user"),  screen: profileScreen },
-})
-tabs.badge("profile", true)              // notification dot on the tab
-Router.init(tabs)
+<file name="assets/chevron-left.svg">
+<svg viewBox="0 0 24 24">
+<path d="M15 18l-6-6 6-6" fill="none" stroke="#000" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
 </file>
-
-// === EXAMPLE 4: Form — field factory, return-key chain, validation, busy submit ===
-// The keyboard needs NO code beyond the enterKey chain: the host scrolls the focused field into
-// view and handles dismissal itself.
 <file name="main.ts">
-// Field anatomy: label above, styled input, a RESERVED message line below (minHeight — an
-// appearing error never jumps the form). Typing in an errored field clears it.
-const Field = (label: string, style: Style<UIInput> = {}) => {
-    const input = UIInput().style({ height: 50, px: 14, borderRadius: 12, bgColor: "#161A22",
-        border: "1px solid #262C3A", color: "white", placeholderColor: "#5A6272",
-        onFocused: { borderColor: "#4C8DFF" }, ...style })
-    const message = UIText("").style({ fontSize: 13, minHeight: 18, color: "#FF6B6B" })
-    input.onChange(() => message.text = "")
-    return {
-        node: UIColumn(
-            UIText(label).style({ fontSize: 13, fontWeight: 600, color: "#8A93A6" }),
-            input, message,
-        ).style({ gap: 6 }),
-        input,
-        error: (text: string) => { message.text = text },
-    }
-}
-
-const name = Field("Name", { placeholder: "Jane Appleseed", autocapitalize: "words" })
-const email = Field("Email", { type: "email", placeholder: "you@example.com" })
-const password = Field("Password", { type: "password" })
-
-// The return key walks the form; the last field submits. This is ALL the keyboard code.
-name.input.style({ enterKey: "next" }).onSubmit(() => email.input.focus())
-email.input.style({ enterKey: "next" }).onSubmit(() => password.input.focus())
-password.input.style({ enterKey: "go" }).onSubmit(() => submit())
-
-let btnLabel: UIText
-let busy = false
-
-// The submit button is never disabled — a tap on a bad form PAINTS the errors and focuses the
-// first offender, which beats a dead button that explains nothing. `busy` swallows double-taps.
-const submit = async () => {
-    if (busy) return
-    let bad: ReturnType<typeof Field> | null = null   // checked bottom-up, so `bad` ends at the FIRST invalid field
-    if (password.input.value.length < 8) { password.error("At least 8 characters"); bad = password }
-    if (!email.input.value.includes("@")) { email.error("Enter a valid email"); bad = email }
-    if (name.input.value.trim() === "") { name.error("Name is required"); bad = name }
-    if (bad) { bad.input.focus(); return }
-    busy = true
-    btnLabel.text = "Creating…"
-    const res = await fetch("https://api.example.com/register", {
-        method: "POST", headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ name: name.input.value.trim(), email: email.input.value, password: password.input.value }),
-    })
-    busy = false
-    btnLabel.text = "Create account"
-    if (res.status !== 200) { email.error("Registration failed — try again"); return }
-    toast("Welcome!")
-}
-
-const screen = UIScreen(
-    UIScrollable(   // no fixed chrome — the keyboard leaves ~460px of screen and a form wants all of them
-        UIText("Create account").style({ fontSize: 28, fontWeight: 700, mb: 12 }),
-        name.node, email.node, password.node,
-        UIButton(btnLabel = UIText("Create account").style({ fontSize: 16, fontWeight: 700 }))
-            .style({ name: "submit", height: 52, borderRadius: 14, bgColor: "#4C8DFF", mt: 8, onPressed: { opacity: 0.85 } })
-            .onClick(() => submit())
-    ).style({ flexGrow: 1, px: 20, pt: "comfort-top", pb: 28, gap: 8 })
-).style({ bgColor: "#0C0F14" })
+import { homeScreen } from './home'
 
-screen.open()
+Router.init(homeScreen)
 </file>
 
-// === EXAMPLE 5: UIBottomSheet — persistent map-style sheet with detents ===
+// === EXAMPLE 4: UIBottomSheet — persistent map-style sheet with detents ===
 <file name="main.ts">
 type Place = { id: number; name: string; distance: string }
 const places: Place[] = [
@@ -1595,32 +1274,32 @@ const places: Place[] = [
     { id: 3, name: "Riverside Park", distance: "1.2 km" },
 ]
 
-const Row = (p: Place) => UIRow(
+const Row = (p: Place) => UIRow([
     UIText(p.name).style({ color: "#111", fontSize: 16 }),
     UIText(p.distance).style({ color: "#888", fontSize: 14 })
-).style({ px: 16, height: 52, alignItems: "center", justifyContent: "space-between" })
+]).style({ px: 16, height: 52, alignItems: "center", justifyContent: "space-between" })
 
-const sheet = UIBottomSheet(
-    UIColumn().style({ width: 50, height: 6, borderRadius: 3, bgColor: "#D9D9D9", mx: "auto", my: 12 }),
+const sheet = UIBottomSheet([
+    UIColumn([]).style({ width: 50, height: 6, borderRadius: 3, bgColor: "#D9D9D9", mx: "auto", my: 12 }),
     UIText("Nearby").style({ px: 16, fontWeight: 700, fontSize: 20, mb: 8, color: "black" }),
     UIScrollable(places.map(Row)).style({ flexGrow: 1 })   // scrolls at the top detent, drags the sheet below it
-)
+])
 .style({ bgColor: "white", borderRadius: 20, overlayColor: null })  // no scrim — the map stays interactive
 .detents([0.25, 0.6, 1])            // collapsed / half / full
 .dismissible(false)                 // drag below the lowest detent collapses, never closes
 .onDetentChange(i => console.log("detent", i))
 
-const mapScreen = UIScreen(
+const mapScreen = UIScreen([
     // the map / page content behind the sheet
-).onOpen(() => sheet.show()).onClose(() => sheet.hide())
+]).onOpen(() => sheet.show()).onClose(() => sheet.hide())
 
 mapScreen.open()
 
-// An action sheet is even less: content-sized, no detents() — UIBottomSheet(rows).show(),
+// An action sheet is even less: content-sized, no detents() — UIBottomSheet([ ...rows ]).show(),
 // scrim and drag-down-to-dismiss included.
 </file>
 
-// === EXAMPLE 6: UIVirtualizedList — chat (inverted, imperative append) ===
+// === EXAMPLE 5: UIVirtualizedList — chat (inverted, imperative append) ===
 <file name="main.ts">
 type Msg = { id: string; text: string; mine: boolean }
 
@@ -1632,41 +1311,37 @@ const list = UIVirtualizedList<Msg>({
     keyOf: m => m.id,
     estimatedHeight: m => 44 + Math.ceil(m.text.length / 34) * 20,
     inverted: true,                                                  // newest at the bottom
-    render: m => UIRow(
-        UIRow(
+    render: m => UIRow([
+        UIRow([
             UIText(m.text).style({ color: m.mine ? "white" : "#111" })
-        ).style({
+        ]).style({
             bgColor: m.mine ? "#FF4032" : "#EEE",
             px: 12, py: 8, borderRadius: 16, maxWidth: "75%"
         })
-    ).style({ px: 12, py: 4, justifyContent: m.mine ? "flex-end" : "flex-start" })
+    ]).style({ px: 12, py: 4, justifyContent: m.mine ? "flex-end" : "flex-start" })
 }).style({ flexGrow: 1 })
 
-let input: UITextArea
-let sendBtn: UIButton
+let input: UIInput
 
 const send = () => {
     const text = input.value.trim()
     if (!text) return
     list.append({ id: idOf(), text, mine: true })   // O(1); inverted list auto-scrolls to it
     input.value = ""
-    sendBtn.style.opacity = 0.4
 }
 
-const screen = UIScreen(
+const screen = UIScreen([
     list,
-    UIRow(
-        input = UITextArea().style({ placeholder: "Message...", placeholderColor: "#999",
-            color: "#111", flexGrow: 1, flexShrink: 1, px: 16, py: 10, bgColor: "#F0F0F0", borderRadius: 20, maxHeight: 110, 
-            keyboardDismiss: false 
+    UIRow([
+        input = UIInput().style({
+            flexGrow: 1, height: 40, px: 16, borderRadius: 20,
+            bgColor: "#F0F0F0", placeholder: "Message...", placeholderColor: "#999"
         }),
-        sendBtn = UIButton(UIImage(assetIcon("lucide:arrow-up")).style({ width: 20, height: 20, tintColor: "white" }))
-            .style({ width: 40, height: 40, borderRadius: 20, bgColor: "#FF4032", opacity: 0.4 })
+        UIButton([ UIText("Send").style({ color: "white" }) ])
+            .style({ height: 40, px: 16, justifyContent: "center", bgColor: "#FF4032", borderRadius: 20 })
             .onClick(send)
-    ).style({ p: 8, pb: "comfort-bottom", gap: 8, alignItems: "flex-end" })
-).style({ bgColor: "white" })
-
-input.onChange(v => { sendBtn.style.opacity = v.trim() ? 1 : 0.4 })   // direct style write — the hot-path form
+    ]).style({ p: 8, gap: 8, alignItems: "center" })
+]).style({ bgColor: "white" })
 
 screen.open()
 </file>