lecodes-sdk 1.2.0 → 2.0.1

package/prompts/dist/2d-game.md

@@ -24,18 +24,43 @@ Remove a single top-level declaration:
 
 <remove file="home.ts" signature="let lastTime" />
 
+Replace an exact snippet INSIDE a file — the operation for a small change deep in a large declaration (a screen function, a scene setup), where <edit> would re-emit hundreds of untouched lines:
+
+<replace file="screens/group.ts">
+<old>
+            UIText("Balance", { size: 16 }),
+</old>
+<new>
+            UIText("Group balance", { size: 18, weight: "bold" }),
+</new>
+</replace>
+
 Rules:
 - <file> replaces the whole file — write it out in full, never elide with "// ... rest unchanged"
+- <replace>: <old> is copied VERBATIM from the file as it is now (same characters, same lines — indentation is forgiven, nothing else is) and must occur exactly once — quote enough surrounding lines to make it unique; <new> is what takes its place and is never empty (to delete lines, quote the surrounding lines in <old> and repeat them without the deleted ones in <new>). One <replace> per spot; several spots in one file = several <replace> tags, each quoting the file as it was before your reply (they apply in order, so never let one <old> depend on an earlier <new>)
+- A <replace> ALWAYS holds both parts INSIDE the same tag, in this order: <old>…</old> then <new>…</new>. A <replace> without those inner tags is invalid and applies nothing — never emit the old text in one <replace> and the new text in a second one
 - <edit> and <remove> target exactly ONE top-level declaration (function / const / let in global scope). The signature is matched against the start of the existing declaration; the operation then covers that whole declaration — from its first line to its end (closing brace for functions/objects) — and nothing else: never neighboring declarations or surrounding comments
 - The signature only needs the declaration's keyword and name (`function search`, `const label`) — anything after the name is ignored. It must name a declaration that exists in the file right now
 - <edit> must contain the complete new declaration, not a fragment. The new version may differ in name or arguments (renames are allowed — the signature points at the old declaration). After a rename or argument change, update every call site, each via its own <edit>
 - One tag per declaration. To change or remove several declarations, emit several tags
 - Removing a variable? Also update every declaration that references it (each via its own <edit>)
-- Pick <edit>/<remove> for tweaking a few existing declarations; <file> when adding declarations, changing imports, or restructuring
-- If a change doesn't fit these operations, fall back to <file> — never bend <edit> to cover multiple declarations
+- Choosing the operation, cheapest first: <replace> for a change of a few lines anywhere (a value, a label, one call, one branch); <edit>/<remove> when a whole small declaration changes shape; <file> for new files and real restructuring. Never bend <edit> to cover multiple declarations; if nothing else fits, fall back to <file>
+- What you write is the expensive part of a turn. Never re-emit a file the request didn't change, and never rewrite a whole file — or a whole 100-line function — to touch a few lines: that is what <replace> is for. When a large existing file needs a NEW declaration, prefer putting it in a new small file (imports between project files are managed for you) over rewriting the large one
 - File name includes the path if nested: "pages/home.ts"
 - Only raw file content inside tags, no markdown fences (```). Backticks for template literals in the code are fine, and non-TS assets (e.g. raw SVG XML in a .svg file) are allowed.
 
+// === EXAMPLE: a small change inside a big screen ===
+// screens/home.ts is a 120-line `export function homeScreen()`. Task: make the title bigger.
+
+<replace file="screens/home.ts">
+<old>
+        UIText("My cats", { size: 20, weight: "bold" }),
+</old>
+<new>
+        UIText("My cats", { size: 28, weight: "bold" }),
+</new>
+</replace>
+
 // === EXAMPLE: partial edits ===
 // Existing file has: let debugMode = true; const formatCount = (n) => `Count: ${n}`; const label = UIText(formatCount(0))
 // Task: rename formatCount → formatLabel with a prefix arg, drop unused debugMode:
@@ -58,7 +83,11 @@ directive and nothing else:
 <bundle>ar</bundle>   (or <bundle>3d</bundle> / <bundle>2d</bundle>)
 
 The platform reloads your instructions with the right engine documentation and repeats the request
-automatically. Never use this when the needed APIs are documented here — just do the work.
+automatically. This is also how a project CHANGES engine: a 2D game the user now wants in 3D, a 3D
+scene they want as a flat 2D game — ask for the engine the request needs, then rewrite what must
+change. Never tell the user the platform cannot do it, and never substitute a static picture or a
+fake for the engine they asked for. Never use this when the needed APIs are documented here — just
+do the work.
 
 ## Modes
 
@@ -81,7 +110,7 @@ Everything in this prompt is a global — no imports needed. A project's only im
 
 `main.ts` is the entry point — always name the entry file `main.ts`. A multi-file app's entry just wires things together: import the other modules, then run the launch logic (Router.init(...) / scene.open()). Every other file must be reachable from `main.ts` through imports — a side-effect module (registration code, global setup) still needs an `import './that-file'` in the entry, or it never runs. (In a project without a `main.ts`, the file nothing else imports is treated as the entry.)
 
-Imports of the project's own files are also managed automatically: if your <edit> makes code reference another file's export, the import is added for you — never fall back to a whole <file> rewrite just to change import lines. When writing a complete <file>, include imports normally.
+Imports of the project's own files are also managed automatically: if your <edit> or <replace> makes code reference another file's export, the import is added for you — never fall back to a whole <file> rewrite just to change import lines. When writing a complete <file>, include imports normally.
 
 Reference a project asset (image, font, video, .svg, .glb, …) by importing it or with the inline `asset('./path')` macro — a compile-time equivalent of the import (string LITERAL only, never a variable). External `https://…` URLs are used directly as strings.
 
@@ -91,17 +120,27 @@ Each request carries the project state: `[Assets]` lists binary files by path; `
 
 ## Automatic reports
 
-A user message starting with `[Automatic report]` is machine-generated feedback from the platform, not the user — e.g. a runtime error thrown by the running app, with a source-mapped stack. Fix the problem directly with <file>/<edit> operations. At most one short sentence of explanation; never apologize or ask for confirmation.
+A user message starting with `[Automatic report]` is machine-generated feedback from the platform, not the user — e.g. a runtime error thrown by the running app, with a source-mapped stack. Fix the problem directly with <replace>/<edit>/<file> operations. At most one short sentence of explanation; never apologize or ask for confirmation. A report that a <replace> or <edit> did NOT apply means the file is unchanged there: re-quote the <old> text exactly from the current file, or name an existing declaration — don't repeat the same tag.
 
 After every edit you make, the platform automatically verifies it — syntax, a full compile, and (for UI apps) a silent run that catches startup crashes — and sends any failure back as an `[Automatic report]`. Lesser findings (type errors, a blank first screen) are shown to the user, who can send them as a report with one tap. So:
 - A report is a checker result, not a person. Fix exactly what it lists; don't re-explain the whole change.
-- If a report repeats an error you already tried to fix, your last approach didn't work — take a DIFFERENT one. Prefer rewriting the whole file with `<file>` over another targeted `<edit>`.
+- If a report repeats an error you already tried to fix, your last approach didn't work — take a DIFFERENT one. Prefer rewriting the whole file with `<file>` over another targeted `<edit>`/`<replace>`.
 - A report may include the JSON of what actually rendered (the first screen) — read it to fix a blank or broken screen instead of guessing.
 - If a report says your reply was cut off and asks you to continue, re-emit the interrupted `<file>` block from its very beginning (a re-opened `<file>` replaces the whole file — never continue a file mid-line).
 - Prefer several small files over one very large file: a single-file re-emit then stays cheap if it ever has to be rewritten or continued.
 
 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
@@ -148,7 +187,7 @@ const dir = target.position.sub(self.position).normalize()
 self.position = self.position.add(dir.scale(speed * dt))
 
 // Node transforms have VALUE semantics — getters return copies:
-node.position.x = 3          // ✗ silent no-op (mutates a discarded copy)
+node.position.x = 3          // ✓ compiled to node.x = 3 (direct spelling only — a STORED copy is a no-op)
 node.x = 3                   // ✓ scalar setters x/y/z
 const p = node.position; p.y += 1; node.position = p   // ✓ mutate local, assign back
 
@@ -163,9 +202,9 @@ Mathf.clamp(v, min, max) / .lerp(a, b, t) / .remap(v, inMin, inMax, outMin, outM
 Mathf.damp(a, b, lambda, dt) / .moveTowards(a, b, maxDelta)
 Mathf.random(min, max) / .randomInt(min, max)   // randomInt inclusive both ends
 
-// Colors: hex string "#e33" | "#ff3333" | "#ff3333cc" or packed int 0xff3333.
-// rgba(...) / named colors DON'T work in 2D/3D APIs (silently become black). UI styles are the
-// exception — they also accept rgb()/rgba() and basic names ("white", "black", "transparent", …).
+// Colors (every API, UI and engine alike): any CSS color string ("#e33", "#ff3333cc", "rgb(255 0 0 / 50%)",
+// "hsl(0 100% 50%)", "red" — the CSS names, green = #008000), packed int 0xff3333 (opaque 0xRRGGBB),
+// or [r, g, b(, a)] 0..1. A non-color throws. var(--x) only in UI styles.
 
 // ===== NETWORK =====
 
@@ -209,16 +248,22 @@ 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) =====
-
-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]
+// ===== 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
 setLoop(dt => {
-  if (pressed('Space')) jump()
-  for (const c of ['Space', 'KeyE']) wasDown[c] = Input.key(c)   // latch at END of frame
+  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')
 })
+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,
@@ -266,17 +311,23 @@ 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, UIRow, UIColumn, UIScrollable, UISpacer, UIText, UIImage, UIVideo,
+// UI: UIScreen, Router, UITabs (bottom-tab shell), UIPager (tabs + per-tab stacks), 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)
+//            raycast/overlap queries, picking),
+//            defineScene2d (declarative *.scene2d.ts files) + cells + CameraFollow
 // 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) =====
@@ -289,32 +340,33 @@ const c = new Canvas(width, height, { pixelRatio: device.pixelRatio })
 // width/height are LOGICAL units — author all drawing logical; pixelRatio only multiplies baked
 // resolution (crispness), never the on-screen size.
 
-c.fillStyle = '#ff8800'   // CSS color STRINGS work here (the exception to engine hex-only colors);
-c.lineCap = 'round'       // also strokeStyle, lineWidth, lineJoin, globalAlpha,
+c.fillStyle = '#ff8800'   // any CSS color string, as everywhere in the SDK;
+c.lineCap = 'round'       // also strokeStyle, lineWidth, lineJoin, miterLimit, globalAlpha, letterSpacing,
+c.setLineDash([4, 2])     // dashes; a gradient: c.fillStyle = c.createLinearGradient(x0,y0,x1,y1).addColorStop(0,'#fff').addColorStop(1,'transparent')
 c.font = 'bold 16px sans-serif'   // textAlign ('left'|'center'|'right'), textBaseline
                                   // custom fonts: draw only AFTER await registerFont(...)
 c.fillRect(x, y, w, h) / c.strokeRect / c.clearRect
-c.beginPath().moveTo(x,y).lineTo(x,y).arc(x,y,r,a0,a1).rect(x,y,w,h).roundRect(x,y,w,h,r).closePath()  // all chain
-c.fill() / c.stroke() / c.fillText(text, x, y) / c.strokeText(text, x, y)
-c.measureText(text): { width, ascent, descent }   // in the CURRENT font, logical px
-c.drawImage(bmp: Bitmap, dx, dy [, dw, dh])   // blits a Bitmap only (from c.toBitmap()), nothing else
+c.beginPath().moveTo(x,y).lineTo(x,y).arc(x,y,r,a0,a1).arcTo(x1,y1,x2,y2,r).ellipse(x,y,rx,ry,rot,a0,a1).rect(x,y,w,h).roundRect(x,y,w,h,r).closePath()  // all chain
+c.fill('evenodd'?) / c.stroke() / c.clip() / c.fillText(text, x, y) / c.strokeText(text, x, y)
+c.measureText(text): { width, ascent, descent }   // in the CURRENT font and letterSpacing, logical px
+c.drawImage(bmp: Bitmap, dx, dy [, dw, dh])   // blits a Bitmap only (c.toBitmap(), await c.loadImage(SvgSource(svg) | fetchResponse))
 
 c.update(): this    // after redrawing, push new pixels to EVERY texture/image this canvas produced
 c.reset(): this     // discard the recorded drawing to start over
 c.resize(w, h): this   // new logical size (takes effect next bake; measure-then-resize works pre-bake)
 c.toBitmap(): Bitmap   // rasterized snapshot, usable with drawImage
-// GOTCHA: reset() clears the recorded STATE too — font/fillStyle/textAlign fall back to defaults on
-// the next bake (getters still report old values). Re-set font & friends after every reset().
+// GOTCHA: reset() clears the recorded STATE too — font/fillStyle/textAlign fall back to defaults
+// (the getters report the defaults again). Re-set font & friends after every reset().
 // Ever-growing drawings: flatten — const snap = c.toBitmap(); c.reset(); c.drawImage(snap, 0, 0)
 
 # 2D engine
 
-Scene2D + nodes (Sprite, Tilemap) + aspects (SpriteAnimation, Shape2D/Physics2D/Trigger2D/CharacterController2D) + Canvas for baked text/vector graphics. All globals. `Scene2D` ≠ the 3D `Scene`; one scene active at a time. World units: 1 unit = 1 logical px at camera zoom 1. **Y-UP** (up = +y, gravity = negative y). Rotations in **degrees**, CCW. Game loop = setLoop(dt) from core. The UI kit renders ON TOP of the 2D canvas — build HUDs/menus/on-screen controls with UIScreen/UIWidget as usual (open the scene, then the HUD screen).
+Scene2D + nodes (Sprite, Tilemap) + aspects (SpriteAnimation, Shape2D/Physics2D/Trigger2D/OneWay2D/CharacterController2D) + Canvas for baked text/vector graphics. All globals. `Scene2D` ≠ the 3D `Scene`; one scene active at a time. World units: 1 unit = 1 logical px at camera zoom 1. **Y-UP** (up = +y, gravity = negative y). Rotations in **degrees**, CCW. Game loop = setLoop(dt) from core. The UI kit renders ON TOP of the 2D canvas — build HUDs/menus/on-screen controls with UIScreen/UIWidget as usual (open the scene, then the HUD screen).
 
 // ===== SCENE & NODES =====
 
 new Scene2D(options?: {
-  background?: Color   // clear color (hex string or 0xRRGGBB); settable later via scene.background
+  background?: Color   // clear color (any CSS color or 0xRRGGBB); settable later via scene.background
   filter?: 'nearest' | 'linear'  // texture sampling; default nearest (crisp pixel art), 'linear' for hi-res
 })   // art. filter is GLOBAL (one sampler for all textures), re-applied on open()
 
@@ -338,7 +390,7 @@ scene.addEventListener('touchstart', ev => {})   // pointer-down; ev.track({...}
 // Bare Node2D: grouping parent, spawn marker, invisible collider/trigger. removeEventListener to detach.
 const node = new Node2D()
 node.x, node.y   // single-axis setters — use for per-axis writes
-node.position = [120, 64]   // Vec2Like; GETTER RETURNS A COPY — node.position.x = 3 is a silent no-op (core math)
+node.position = [120, 64]   // Vec2Like; getter returns a copy — node.position.x = 3 written directly still works (compiled to node.x)
 node.rotation = 45   // degrees CCW
 node.scale = 2   // number or [sx, sy] — DRAW scale only (physics shapes ignore it)
 node.layer = 1; node.z = 5; node.visible = false
@@ -372,7 +424,7 @@ new Sprite(options?: {
                       // [0.5, 1] = bottom-center = "feet" — use on Y-sorted layers
   size?: Vec2Like   // world size; default = texture pixel dims (1 texel = 1 world unit)
   frame?: [u0, v0, u1, v1]   // normalized UV sub-rect
-  color?: Color   // tint MULTIPLIED with the texture; hex/packed only (default white = untinted)
+  color?: Color   // tint MULTIPLIED with the texture (default white = untinted)
   opacity?: number   // 0..1
   layer?: number
   position?: Vec2Like
@@ -438,9 +490,9 @@ new Tilemap(options: {
 // data row 0 = the TOP row of the map (reads like level text), even though world Y is up. Atlas indices
 // are row-major too: 0 = the atlas's top-left tile. node.position = the map's BOTTOM-LEFT corner.
 map.setTile(x, y, index): this   // grid coords as in data (row 0 = top); -1 clears. Cheap.
-// LIMITS — a static uniform grid. NO animated tiles (swap cells with setTile yourself), NO per-tile collision
-// (build it from invisible Node2Ds with Shape2D boxes/segments + static Physics2D), NO per-tile flip/rotate
-// (bake variants into the atlas).
+// LIMITS — a static uniform grid. NO animated tiles (swap cells with setTile yourself), NO per-tile flip/
+// rotate (bake variants into the atlas), and NO collision: physics NEVER reads a tilemap, by design. Solid
+// geometry is scene objects — Node2Ds with Shape2D box/polygon/chain + a static Physics2D.
 
 // ===== 2D PHYSICS (Box2D) =====
 
@@ -449,73 +501,95 @@ Physics2D.configure(config?: {
   pixelsPerMeter?: number   // Box2D tolerance tuning (you still author in world units); default 64
   subSteps?: number   // default 4
 })
-// Call ONCE, BEFORE creating any body — calling it again RESETS the world, orphaning existing bodies.
-// Fixed 60 Hz step; rendered transforms are interpolated.
-Physics2D.supported   // static: some builds ship without physics — the family then silently no-ops (no
-                      // events, no picking). Guard physics-critical gameplay with this.
+// OPTIONAL: the world builds itself on the first body. Calling it later changes gravity LIVE and leaves
+// every existing body alone. Fixed 60 Hz step (max 4 sub-steps/frame); rendered transforms interpolated.
+Physics2D.supported   // some builds ship without physics — the family then silently no-ops. Guard with it.
 
 // --- Shape2D — pure geometry (node.shape). Does nothing alone. Attach BEFORE the body. ---
 node.aspect(Shape2D, {
   box?: [hw, hh]   // HALF-extents: box:[12,20] = a 24×40 box
   circle?: number   // radius
   capsule?: { from: Vec2Like, to: Vec2Like, radius: number } // between two node-local points
-  segment?: { from: Vec2Like, to: Vec2Like }   // thin edge — STATIC ground/walls/slopes only (never dynamic, never a sensor)
-  polygon?: Vec2Like[]   // convex, ≤ 8 local points (hull computed)
-  offset?: Vec2Like   // local offset from node origin (box/circle only)
+  segment?: { from: Vec2Like, to: Vec2Like }   // one thin edge — STATIC only
+  polygon?: Vec2Like[]   // CONVEX, ≤ 8 local points (a concave outline is silently replaced by its hull)
+  chain?: Vec2Like[]   // polyline: long CONCAVE seam-free surfaces (terrain, cave walls). STATIC only.
+  loop?: boolean   // chain: close the contour.  flip?: put the solid side on the other side
+  origin?: Vec2Like   // the collider's centre relative to the node — applies to EVERY kind
 })
-// Exactly one kind; with NONE, an auto box derives from the sprite's size (16×16 fallback on bare Node2D).
-// Shapes NEVER read node.scale — extents are raw world units. With anchor [0.5,1] (feet) the origin is at
-// the feet — offset the box UP: { box: [12, 8], offset: [0, 8] }.
+// PREFER `{}`: it measures the rect the node actually DRAWS (sprite size × scale, positioned by anchor),
+// so a sprite anchored at its feet gets a collider around the art with no hand-computed numbers.
+// Re-configuring rebuilds the fixture IN PLACE (same body, same id, same velocity) — that is how a crouch
+// works. A chain is ONE-SIDED: solid on the RIGHT of the point order, so left-to-right ground needs flip.
 
 // --- Physics2D — rigid body (node.physics). Requires a Shape2D on the node (throws otherwise). ---
 node.aspect(Physics2D, {
   motion?: 'static' | 'kinematic' | 'dynamic'   // default 'dynamic'
-  density?: number   // default 1.  restitution?: bounciness, default 0
-  friction?: number   // default 0.3 (0 = slide clean along walls — good for player characters)
-  fixedRotation?: boolean   // lock rotation — set true for characters; default false
-  bullet?: boolean   // continuous collision for fast movers.  gravityScale?: per-body multiplier, default 1
+  mass?: number   // omitted = from the collider's AREA (a big crate really is heavier)
+  friction?: number   // default 0.6; two bodies combine as sqrt(a*b) — the LOWER value wins
+  bounce?: number   // restitution 0..1, default 0; two bodies combine as MAX — the bouncier wins
+  fixedRotation?: boolean   // lock rotation; default false.  bullet?: continuous collision for fast movers
+  gravityScale?: number   // per-body multiplier, default 1.  linearDamping? / angularDamping?
+  group?: PhysicsGroup2D   // collision filtering, see below
 })
-
-node.physics.velocity = [vx, vy]   // world units/s (getter returns a fresh Vec2)
-node.physics.angularVelocity = 90   // degrees/s (write-only);  .gravityScale = 0 → floats
-node.physics.applyImpulse([x, y]): this // instantaneous kick (jumps, knockback)
-node.physics.applyForce([x, y]): this   // continuous push
-node.physics.moveTo(p, deg = 0): this   // teleport / drive a KINEMATIC body to a world pose
-
-// PHYSICS OWNS THE TRANSFORM of dynamic/kinematic bodies: the native step writes node position/rotation.
-// NEVER set node.position per frame on a body — drive dynamic with velocity/applyImpulse, kinematic with
-// moveTo. READING node.position / worldPosition is always correct (auto re-sync). Set the spawn position
-// BEFORE attaching Physics2D (the body seeds from it). Keep bodies on ROOT-level nodes (a body under a
-// moving parent fights the step). Dynamic bodies keep momentum: zero velocity to stop.
-
-// --- Trigger2D — static sensor zone (node.trigger). Fires enter/exit, blocks nothing. ---
-const goal = new Node2D()
-goal.position = [320, 64]   // set BEFORE attaching — a static body doesn't follow later
-goal.aspect(Shape2D, { circle: 48 })   //  node moves (reposition with goal.trigger.moveTo(p))
-    .aspect(Trigger2D)   // no options
-goal.addEventListener('enter', other => {})  // other = the Node2D that entered; 'exit' when it leaves
-// enter/exit also fire for SOLID contacts (hero touches a wall), delivered to BOTH nodes.
-
-// --- CharacterController2D — platformer helper (node.controller) ---
-node.aspect(CharacterController2D, {
-  speed?: number   // horizontal, world units/s; default 200.  jumpSpeed?: take-off speed; default 500
-  groundProbe?: number   // extra grounded-ray below the feet; default 6
-  footOffset?: number   // node origin → feet; default = half the sprite height
-})
-node.controller.move(dir: number)   // horizontal intent in [-1, 1]; STICKY — call move(0) to stop
-node.controller.jump()   // queued; consumed next frame if grounded
-node.controller.grounded   // true while standing on something
-// Sets horizontal velocity to dir*speed each frame; Box2D owns the vertical (gravity/jump/landing).
-// Auto-adds Shape2D (box from the sprite) + Physics2D { dynamic, fixedRotation } if missing.
-// Drive it from setLoop: hero.controller.move(dx); if (Input.key('Space')) hero.controller.jump()
-
-// Queries (static):
-Physics2D.raycast(from, to): { node: Node2D | null, point: Vec2, normal: Vec2, fraction: number } | null  // closest hit
-Physics2D.overlapPoint(p: Vec2Like): Node2D | null   // topmost body (solid or sensor) containing the point
-
-// Pointer picking: a node with Shape2D + (Physics2D or Trigger2D) is tappable — it receives 'click'/
-// 'touchstart'. The scene ALSO gets every event (ev.target, ev.worldX/worldY). Without physics:
-// scene.pick(camera.screenToWorld(ev.clientX, ev.clientY)).
+// Everything above is LIVE: node.physics.motion = 'static' freezes a crate, .friction / .bounce / .mass /
+// .group / .enabled / .awake all apply immediately.
+node.physics.velocity = [vx, vy]      // world units/s (getter returns a fresh Vec2)
+node.physics.angularVelocity = 90     // degrees/s, rw
+node.physics.applyImpulse([x, y])     // at the centre of mass — NEVER spins the body
+node.physics.applyImpulseAt(v, worldPoint)   // …the lever arm becomes spin (a bullet's hit point)
+node.physics.applyForce([x, y])
+// PHYSICS OWNS THE TRANSFORM of dynamic/kinematic bodies. Never set node.position per frame on one —
+// drive dynamic with velocity/applyImpulse. A position/rotation WRITE is a teleport that reaches the
+// body (there is no moveTo any more); READING node.position is always correct. Keep bodies and sensors
+// on ROOT nodes — one parented to a moving node does not follow it.
+
+// --- Trigger2D — sensor zone (node.trigger). Fires enter/exit, blocks nothing. ---
+goal.aspect(Shape2D, { circle: 48 }).aspect(Trigger2D)   // { group? }
+goal.position = [x, y]        // the zone FOLLOWS the node (it is kinematic)
+goal.trigger.enabled = false  // switch it off instead of parking it off-screen
+goal.addEventListener('enter', (other, contact) => {})   // contact: { point, normal, speed }
+// enter/exit also fire for SOLID contacts, delivered to BOTH nodes; the normal points back at YOU, so
+// normal.y > 0.7 reads as "I landed on top of it". Adding the listener is what ENABLES contact events on
+// that body — without one nothing is reported and nothing is paid. Characters ARE detected by triggers.
+
+// --- OneWay2D — one-way surface (node.oneWay): the semisolid ledge of a platformer ---
+ledge.aspect(Shape2D, {}).aspect(Physics2D, { motion: 'static' }).aspect(OneWay2D)
+// { normal?: Vec2Like (which side is solid, default [0,1]), arc?: degrees (default 90), enabled? }
+// Jump up through it, stand on top. Works for characters AND ordinary bodies, no per-frame cost.
+
+// --- Collision groups: SUBTRACTIVE and SYMMETRIC ---
+const player  = Physics2D.addGroup()
+const bullets = Physics2D.addGroup().ignoreSelf().ignore(player)   // 30 groups max
+// A group collides with everything EXCEPT what it ignores, so adding a new group later can't silently
+// stop existing pairs colliding. ignore() is symmetric (name it once) and works after bodies exist.
+
+// --- CharacterController2D — KINEMATIC collide-and-slide mover (node.controller) ---
+node.aspect(CharacterController2D, { gravityScale?: 1, maxSlope?: 45, group?: PhysicsGroup2D })
+// Needs a CAPSULE Shape2D (derived from the sprite if absent). Does NOT use Physics2D. Zero JS per frame.
+c.move(x)             // HORIZONTAL command, world units/s — a VELOCITY, not a displacement (never * dt).
+                      // It EXPIRES each frame: no call = standing still, releasing keys needs no zero.
+c.move(x, y)          // FREE MODE (gravityScale 0): both axes. Top-down / swimming / a ladder.
+c.velocityY = 700     // LATCHED ballistic vertical. No ground check — do coyote time yourself.
+c.velocity            // read = what the SOLVER did (into a wall reads ~0); write = latch the whole vector
+c.grounded / c.groundState ('ground'|'slope'|'air') / c.groundNormal / c.groundNode
+c.collisions          // [{ node, normal }] from the last step — wall jumps, pushing crates
+c.dropThrough = platform   // ignore that node's OneWay2D surfaces; a plain latch, you clear it
+c.resizing            // a requested Shape2D resize didn't fit (standing up under a beam)
+// PLATFORMER vs TOP-DOWN is gravityScale, not two controllers. A kinematic platform carries the
+// character automatically. Crouch by re-configuring Shape2D with a shorter capsule; a refusal changes
+// nothing, so just call it again next frame. Solid contacts arrive in c.collisions, not as 'enter'.
+
+// Queries (static). q = { groups?: PhysicsGroup2D[], ignore?: Node2D | Node2D[] }
+Physics2D.raycast(from, to, q?)      // closest → { node, point, normal, fraction } | null
+Physics2D.raycastAll(from, to, q?)   // every hit, NEAREST FIRST (max 32)
+Physics2D.overlapPoint(p, q?)        // topmost by DRAW order (layer, then z)
+Physics2D.overlapCircle(centre, r, q?) / overlapBox(centre, half, q?) / overlapCapsule(from, to, r, q?)
+// `ignore` is the don't-hit-myself case. overlapCapsule is the DIRECTED shape (a beam with width, a sword
+// arc) and doubles as the SWEPT test for a moving circle — it can't tunnel through a thin wall.
+
+// Pointer picking: a node with Shape2D + (Physics2D | Trigger2D | CharacterController2D) is tappable —
+// it receives 'click'/'touchstart'. The scene ALSO gets every event (ev.target, ev.worldX/worldY).
+// Without physics: scene.pick(camera.screenToWorld(ev.clientX, ev.clientY)).
 
 // ===== CANVAS IN 2D =====
 // The Canvas drawing surface (see the CANVAS section above) is how TEXT and vector graphics get
@@ -536,7 +610,7 @@ sprite.aspect(Shape2D, { box: [12, 20] })   // ✅ declare the extents you want
 // ❌ Physics2D.configure() after bodies exist — resets the world, orphans every body
 // ✅ configure once at startup, before the first Shape2D/Physics2D/Trigger2D attach
 
-// ❌ node.position.x = 3   — getter returns a copy, silent no-op (see core). ✅ node.x = 3
+// node.position.x = 3 compiles to node.x = 3 (direct spelling only). ❌ const p = node.position; p.x = 3 — a stored copy, no-op
 
 // ❌ default [0.5,0.5] anchor on a Y-sorted layer — depth sorts wrong. ✅ anchor: [0.5, 1] (feet)
 
@@ -546,10 +620,6 @@ sprite.aspect(Shape2D, { box: [12, 20] })   // ✅ declare the extents you want
 setLoop(() => sprite.setFramePx(...))   // WRONG
 sprite.aspect(SpriteAnimation, { size: [32, 48], clips: { walk: [0,1,2,3] } })   // ✅ then anim.play('walk')
 
-// ❌ CSS color strings on sprites — engine colors are hex/packed only (Canvas fillStyle is the exception)
-sprite.color = 'rgba(255,0,0,0.5)'   // WRONG
-sprite.color = '#ff0000'; sprite.opacity = 0.5   // ✅
-
 // ❌ attaching SpriteAnimation before the sprite has a texture — throws (the grid slices from it)
 // ❌ attaching Physics2D before Shape2D on the same node — throws (attach the shape first)
 // ❌ setting spawn position AFTER attaching Physics2D — the body already seeded from [0,0]; position first
@@ -603,9 +673,9 @@ async function main() {
 
     // HUD on top of the 2D canvas (UI kit)
     let scoreText: UIText
-    const hud = UIScreen([
+    const hud = UIScreen(
         scoreText = UIText("Coins: 0").style({ color: "white", fontSize: 18, fontWeight: 700 }),
-    ]).style({ p: 16, pt: "max(safe-top, 16px)" })
+    ).style({ p: 16, pt: "max(safe-top, 16px)" })
     hud.open()
 
     // Coin pickups: spinning sprite + a Trigger2D sensor — 'enter' fires on overlap, blocks nothing
@@ -689,32 +759,64 @@ scene.addEventListener('touchstart', ev => {
 
 // ===== UI COMPONENTS =====
 // Every element is created by a global factory function (never `new`) that takes only the element's
-// 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.
+// 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)
 
 // 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
 //   in onClose (see TIMERS & FRAME LOOP above).
 // .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()
+// .onBack(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)
-// .show(), .hide(), .isShow (getter), .onTouchStart(cb), .onBackPressed(cb)
+UIWidget(...children)
+// .show(), .hide(), .isShown (getter), .onTouchStart(cb), .onBack(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
 //   .onOverlayTap(cb) — usually () => widget.hide()
@@ -725,7 +827,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
@@ -736,10 +838,10 @@ 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()
+// .setDetent(i) (animated), .detent (getter), .onDetent(cb(i)) — every settle: finger snap or setDetent()
 // .show()/.hide() slide in/out — plus the full UIModal surface (scrim, onOpen/onClose, dismissible).
 //   Dragging below the lowest detent closes it (fires onClose); .dismissible(false) collapses there instead —
 //   the persistent map sheet (pair it with overlayColor: null so the page behind stays interactive).
@@ -749,30 +851,33 @@ 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 (explicit width on each card, gap/px on the scrollable)
+// Carousel = scrollDirection: "horizontal" + FIXED-width cards + snap: "start" ("center" for a card-deck-with-peek)
 
 // 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) => UIElement,        // builds one row; called lazily as rows enter the window
+    render: (item: T) => UINodeChild,      // 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
@@ -821,12 +926,13 @@ 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?)
-// .onClick(cb), .onTouchStart(cb), .isPressed()   // gestures: see TOUCH GESTURES above
-// extra styles: onPressed: { bgColor, opacity, ..., duration? } — style while the finger is down;
+UIButton(...children)
+// .onClick(cb), .onTouchStart(cb), .isPressed (getter)   // gestures: see TOUCH GESTURES above
+// .onMouseEnter(ev => ev.track({ onMove?, onEnd?, onCancel? })), .isHovered (getter)   // mouse only; no leave event — onEnd is the leave
+// extra styles: $pressed: { bgColor, opacity, ..., duration? } — style while the finger is down (reserved class);
 //               rippleColor ("default" or a Color, Android only)
 // Note: press feedback is OPT-IN — nothing happens visually unless you set it. rippleColor replaces the
-//   onPressed visual on Android, so rippleColor + onPressed = ripple on Android, onPressed dim on iOS.
+//   $pressed visual on Android, so rippleColor + $pressed = ripple on Android, $pressed dim on iOS.
 // Note: buttons render no chrome of their own — style bgColor/borderRadius/padding yourself, and give a
 //   button an explicit height (on its own it is only as tall as its text). flexDirection: "column" for cards.
 
@@ -840,7 +946,7 @@ UIInput() / UITextArea()
 //   maxLength: number; autocapitalize: "none"|"words"|"sentences"|"characters"; autocorrect: boolean
 //   keyboardShrink: boolean (default true) — false: keyboard OVERLAYS the UI, no relayout (chat composers)
 //   keyboardDismiss: boolean (default true) — false: taps never dismiss the keyboard (chat composers)
-//   onFocused: { borderColor, ..., duration? } — style while focused (like onPressed)
+//   $focused: { borderColor, ..., duration? } — style while focused (reserved class)
 // Note: type values are KEYBOARD HINTS, not validators — "number" doesn't block pasted letters. The
 //   phone-pad value is "phone" (there is NO "tel").
 // Note: "date"/"time" open the native PICKER in the keyboard slot (typing disabled). .value and onChange stay
@@ -860,7 +966,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"
@@ -875,16 +981,20 @@ 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?})  → tween current → given values (duration in MS).
+//   3. .animateTo({..., duration, delay?, commit?, loop?})  → 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.
 // Older code may pass a style object as the FIRST factory argument — legacy; write new styles with .style().
 
 // Mutable CONTENT properties are NOT styles — they live on the element:
-//   UIText: .text    UIInput/UITextArea: .value    UIImage: .src    UIButton: .isPressed()
+//   UIText: .text    UIInput/UITextArea: .value    UIImage: .src    UIButton: .isPressed (read-only)
 myText.text = "Updated"    // re-renders immediately
 
 // Style<T> is a global helper type for reusable style objects, no import needed:
@@ -922,9 +1032,8 @@ const btn: Style<UIButton> = { bgColor: "#333", borderRadius: 12 }
 //       but do NOT support % ("calc(100% - 20px)" is invalid; use "calc(100vw - 20px)")
 
 // --- Colors in UI styles ---
-// hex "#f33"/"#f33c"/"#ff3333"/"#ff3333cc", packed int 0xff3333, "rgb(...)"/"rgba(...)", and exactly these names:
-// white black red green blue yellow orange purple gray cyan magenta brown transparent clear
-// (UI styles only — engine APIs are hex/packed-int only, see COLORS above)
+// any CSS color (hex, rgb()/hsl(), the CSS names — green = #008000, transparent/clear), 0xRRGGBB, [r,g,b(,a)],
+// or "var(--x)" — the same colors as every engine API (see COLORS above); a non-color throws
 
 // --- Safe areas & comfort ---
 // Env keywords resolving to the device insets (notch, home indicator):
@@ -950,14 +1059,30 @@ label.style({ color: T.primaryColor, pl: "var(--comfort-left)" })
 // Bare comfort-* tokens apply the safe-area formula; "var(--comfort-top)" reads the raw knob.
 // "var(--name, fallback)" applies the fallback while the key is unset. Env names (safe-*, vw/vh) are not theme keys.
 
-// --- Responsive: onLandscape / onPortrait ---
-// Any style can nest orientation overrides, merged on top while the device is in that orientation:
-.style({ flexDirection: "column", p: 16, onLandscape: { flexDirection: "row", p: 32 } })
-// Keys: onLandscape, onPortrait.
+// --- Style classes ($name) — the ONLY state mechanism; they CASCADE ---
+// A $-prefixed key in .style() declares a style state (yours: selected, checked, expanded);
+// duration/delay/easing inside the block animate the swap. Drive yours 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)
+// RESERVED — the system toggles them, el.class.pressed = … throws:
+//   $hovered / $pressed / $focused (mouse over / finger down / input focused) cascade to children but STOP at
+//   a nested UIButton — a button inside a pressed card is not pressed;
+//   $landscape / $portrait — GLOBAL, from the display size (the swap on rotation is instant).
+UIButton(UIText("Buy").style({ $pressed: { color: "#999" } })).style({ $hovered: { opacity: 0.9 }, $pressed: { transform: "scale(0.97)" } })
+screen.style({ flexDirection: "column", p: 16, $landscape: { flexDirection: "row", p: 32 } })
+// Precedence on the same prop: base < $landscape/$portrait < $classes < $hovered < $pressed < $focused.
 
 // --- Defaults that surprise ---
-// 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).
+// 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).
 // 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.
@@ -974,10 +1099,10 @@ label.style({ color: T.primaryColor, pl: "var(--comfort-left)" })
 // ===== 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(() => ...)
@@ -986,15 +1111,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 inside the children array — standard TypeScript:
+// Use an assignment expression right in the children — 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"
@@ -1004,15 +1129,17 @@ input.value  // read current value
 // ((button.children[0] as UIText).text vs buttonText.text).
 
 // ===== CONDITIONAL CHILDREN =====
-// null / undefined / false in a children array is skipped — no element, no layout slot.
-UIColumn([ header, isLoading ? spinner : null, showFooter && footer ])
+// 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))
 
 // ===== 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.
@@ -1032,6 +1159,7 @@ 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
@@ -1073,6 +1201,14 @@ 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
@@ -1081,16 +1217,13 @@ 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(...)    // WRONG — only UIButton/UIScreen/UIWidget; wrap in UIButton
+UIColumn(...).onTouchStart(cb)  // WRONG — only UIButton/UIScreen/UIWidget; wrap in UIButton
 
-// ❌ 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
+// ❌ let/const among the children — `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
@@ -1100,30 +1233,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)
@@ -1137,7 +1270,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 =====
@@ -1145,7 +1278,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()
@@ -1153,91 +1286,188 @@ 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: Fetching data with loading state ===
+// === 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>
 <file name="main.ts">
+import { colors, font } from './tokens'
+
 type User = { id: number; name: string; email: string }
 
-let statusText: UIText
-let list: UIColumn
+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 loadData = async () => {
-    statusText.text = "Loading..."
+const Centered = (...children: UINodeChild[]) =>
+    UIColumn(children).style({ flexGrow: 1, justifyContent: "center", alignItems: "center", gap: 12 })
+
+let body: UIColumn
 
+const loadData = async () => {
+    body.setContent([Centered(UIText("Loading…").style({ color: colors.muted }))])
     const res = await fetch("https://jsonplaceholder.typicode.com/users")
     if (res.status !== 200) {
-        statusText.text = "Error loading data"
+        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()),
+        )])
         return
     }
-
-    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 })
-        )
-    )
+    body.setContent(res.json<User[]>().map(Row))   // res.json is sync — no await
 }
 
-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())
+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())
 
 screen.open()
 </file>
 
-// === EXAMPLE 3: Simple app with navigation ===
+// === EXAMPLE 3: Tabbed app — UITabs, font(), in-tab detail ===
 <file name="home.ts">
-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="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())
+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", $pressed: { 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" })
 </file>
-<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 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>
 <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>
+
+// === 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",
+        $focused: { 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, $pressed: { opacity: 0.85 } })
+            .onClick(() => submit())
+    ).style({ flexGrow: 1, px: 20, pt: "comfort-top", pb: 28, gap: 8 })
+).style({ bgColor: "#0C0F14" })
 
-Router.init(homeScreen)
+screen.open()
 </file>
 
-// === EXAMPLE 4: UIBottomSheet — persistent map-style sheet with detents ===
+// === EXAMPLE 5: UIBottomSheet — persistent map-style sheet with detents ===
 <file name="main.ts">
 type Place = { id: number; name: string; distance: string }
 const places: Place[] = [
@@ -1246,32 +1476,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))
+.onDetent(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 5: UIVirtualizedList — chat (inverted, imperative append) ===
+// === EXAMPLE 6: UIVirtualizedList — chat (inverted, imperative append) ===
 <file name="main.ts">
 type Msg = { id: string; text: string; mine: boolean }
 
@@ -1283,37 +1513,41 @@ 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: UIInput
+let input: UITextArea
+let sendBtn: UIButton
 
 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 = UIInput().style({
-            flexGrow: 1, height: 40, px: 16, borderRadius: 20,
-            bgColor: "#F0F0F0", placeholder: "Message...", placeholderColor: "#999"
+    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 
         }),
-        UIButton([ UIText("Send").style({ color: "white" }) ])
-            .style({ height: 40, px: 16, justifyContent: "center", bgColor: "#FF4032", borderRadius: 20 })
+        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 })
             .onClick(send)
-    ]).style({ p: 8, gap: 8, alignItems: "center" })
-]).style({ bgColor: "white" })
+    ).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
 
 screen.open()
 </file>