lecodes-sdk 1.1.0 → 2.0.0

package/prompts/dist/ui-app.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,11 +120,11 @@ 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.
@@ -158,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
 
@@ -173,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 =====
 
@@ -311,22 +340,23 @@ 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)
 
 // ===== UI RULES =====
@@ -358,7 +388,7 @@ UIScreen(...children)
 //   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 }))
 // Note: a screen always fills the device — sizing styles on it (width, height, flexGrow, flexShrink, position) are no-ops
@@ -394,7 +424,7 @@ Router.init(UIScreen(pager, tabBar))   // bar buttons: .onClick(() => pager.sele
 // 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)
+// .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()
@@ -419,7 +449,7 @@ UIModal(...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).
@@ -505,11 +535,12 @@ 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;
+// .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.
 
@@ -523,7 +554,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
@@ -571,7 +602,7 @@ UIText("Hi").style({ color: "white" }).style({ fontSize: 20 }).onClick(...)
 // 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:
@@ -609,9 +640,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):
@@ -637,14 +667,9 @@ 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) — 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:
+// --- 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
@@ -655,11 +680,13 @@ 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.
+// 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, UIVirtualizedList and UIPager
@@ -953,7 +980,7 @@ const detailScreen = (name: string) => UIScreen(
 ).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 } })
+    .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(
@@ -989,7 +1016,7 @@ Router.init(tabs)
 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 })
+        $focused: { borderColor: "#4C8DFF" }, ...style })
     const message = UIText("").style({ fontSize: 13, minHeight: 18, color: "#FF6B6B" })
     input.onChange(() => message.text = "")
     return {
@@ -1040,7 +1067,7 @@ const screen = UIScreen(
         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 } })
+            .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" })
@@ -1070,7 +1097,7 @@ const sheet = UIBottomSheet(
 .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(
     // the map / page content behind the sheet

package/prompts/ui-design.md

@@ -57,7 +57,7 @@ UIImage(src)  // src: string url | SvgSource | imported asset
 // UIButton — the only TAPPABLE container: a UIRow with children centered on both axes by default.
 // Anything clickable in the prototype (a card, a list row, an icon) — wrap it in a UIButton.
 UIButton(...children)
-// extra styles: onPressed: { bgColor, opacity, ... } — style while the finger is down (press feedback is
+// extra styles: $pressed: { bgColor, opacity, ... } — style while the finger is down (press feedback is
 //   OPT-IN; set it so the live prototype feels real)
 // 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.
@@ -109,8 +109,7 @@ const label: Style<UIText> = { fontSize: 12, fontWeight: 600, letterSpacing: 2 }
 // Note: calc()/min()/max() do NOT support % ("calc(100% - 20px)" is invalid; use "calc(100vw - 20px)")
 
 // --- Colors in UI styles ---
-// hex "#f33"/"#f33c"/"#ff3333"/"#ff3333cc" (8 digits = alpha), packed int 0xff3333, "rgb(...)"/"rgba(...)",
-// and exactly these names: white black red green blue yellow orange purple gray cyan magenta brown transparent clear
+// any CSS color (hex, rgb()/hsl(), the CSS names — green = #008000, transparent/clear), 0xRRGGBB, [r,g,b(,a)], "var(--x)"
 
 // --- Safe areas ---
 // Env keywords resolving to the device insets (notch, home indicator):

package/prompts/ui.md

@@ -27,7 +27,7 @@ UIScreen(...children)
 //   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 }))
 // Note: a screen always fills the device — sizing styles on it (width, height, flexGrow, flexShrink, position) are no-ops
@@ -63,7 +63,7 @@ Router.init(UIScreen(pager, tabBar))   // bar buttons: .onClick(() => pager.sele
 // 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)
+// .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()
@@ -88,7 +88,7 @@ UIModal(...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).
@@ -174,11 +174,12 @@ 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;
+// .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.
 
@@ -192,7 +193,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
@@ -240,7 +241,7 @@ UIText("Hi").style({ color: "white" }).style({ fontSize: 20 }).onClick(...)
 // 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:
@@ -278,20 +279,19 @@ 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):
 //   "safe-top" | "safe-bottom" | "safe-left" | "safe-right";  "safe-all" — p / m shorthands only
 // Comfort tokens — where content comfortably starts, never collapse to 0: max(safe-edge, knob) on clearance
-// insets (iOS notch/home indicator, gesture nav); past exact-height system BARS (Android status/nav bar) the
-// knob ADDS instead. Knob defaults: 12 top, 4 bottom, 16 horizontal (the page gutter):
+// insets (iOS notch/home indicator); past exact-height system BARS (Android status/nav bar) the
+// knob ADDS instead. Knob defaults: 12 top, 8 bottom, 16 horizontal (the page gutter):
 //   "comfort-top" | "comfort-bottom" | "comfort-left" | "comfort-right"
 //   "comfort-x" — px/mx | "comfort-y" — py/my | "comfort-all" — p / m
 // Accepted on per-side padding & margin, position offsets (top/left/bottom/right), and inside calc()/min()/max():
-.style({ pb: "comfort-bottom" })        // bottom bar: 34 over a home indicator, 52 above Android's button bar, 4 on inset-less devices
+.style({ pb: "comfort-bottom" })        // bottom bar: 34 over a home indicator, 56 above Android's button bar, 8 on inset-less devices
 .style({ px: "comfort-x" })             // page gutter that also clears the notch in landscape
 .style({ pb: "calc(comfort-bottom + 56px)" })   // scroll content clearing a 56px floating bar
 
@@ -306,14 +306,9 @@ 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) — 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:
+// --- 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
@@ -324,11 +319,13 @@ 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.
+// 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, UIVirtualizedList and UIPager
@@ -411,14 +408,25 @@ UIButton().onLayout(({ width }) => { buttonWidth = width })
 // ===== 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
+Router.push(screen, opts?: { transition, popTransition })  // push onto the stack, screen becomes active (default "push")
+Router.pop(to?: number, opts?: { transition })
+                         // default -1 = one back; negative = relative (-2 = back two), 0/positive = absolute
                          // stack index (0 = home). Popped screens' native trees are destroyed; the UIScreen
-                         // object stays reusable (push remounts it).
-Router.replace(screen, opts?: { transition })  // swap the top screen; transition: "slide-from-left" |
-    // "slide-from-right" | "slide-from-top" | "slide-from-bottom" | "zoom" | "zoom-out" | "zoom-in" | "fade" | "none" (default "fade")
+                         // object stays reusable (push remounts it). Plays the way back the screen remembers.
+Router.replace(screen, opts?: { transition, popTransition })  // swap the top screen (default "none"; theme({ replaceTransition }))
 Router.current                   // the active UIScreen (getter)
-Router.hide() / Router.restore() // hide/restore the whole router — stack stays alive; fires the top screen's onClose/onOpen
+Router.hide(opts?) / Router.restore(opts?) // hide/restore the whole router — stack stays alive; fires the top screen's onClose/onOpen
+// TRANSITIONS — every call above, and open() / close() of any destination, takes { transition }:
+//   a name: "push" | "pop" | "slide-from-left" | "slide-from-right" | "slide-from-top" | "slide-from-bottom" |
+//           "zoom" | "zoom-in" | "zoom-out" | "fade" | "none"
+//   or your own: { enter?: pose, exit?: pose, onTop?: "enter" | "exit" } — the incoming screen comes FROM `enter`,
+//     the outgoing one goes TO `exit`. pose = { transform?, opacity?, dim?, duration? (ms, 300), delay?, easing? };
+//     arrays are keyframes; in a pose a % in translate is a percent of the screen ("translateY(100%)").
+//     e.g. Router.push(page, { transition: { enter: { transform: "translateY(100%)", duration: 400 }, exit: { dim: 0.3 } } })
+// popTransition = the way BACK the screen remembers (Router.pop(), the back gesture, the system's back play it).
+//   Default: the transition it came with, the other way round (a slide from the bottom leaves downwards;
+//   a zoom / a fade go back with a fade). A replace without one keeps the way back of the screen it replaces.
+// A screen's own transform / opacity are not seen while a transition moves it — style a child instead.
 Router.addEventListener("change", (screen: UIScreen) => ...) / .removeEventListener("change", cb)  // after every navigation
 // Screens BELOW the top stay mounted — element trees and state survive, they're just not rendered.
 // push fires the outgoing screen's onClose + the incoming one's onOpen; pop fires them in reverse and
@@ -622,7 +630,7 @@ const detailScreen = (name: string) => UIScreen(
 ).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 } })
+    .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(
@@ -658,7 +666,7 @@ Router.init(tabs)
 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 })
+        $focused: { borderColor: "#4C8DFF" }, ...style })
     const message = UIText("").style({ fontSize: 13, minHeight: 18, color: "#FF6B6B" })
     input.onChange(() => message.text = "")
     return {
@@ -709,7 +717,7 @@ const screen = UIScreen(
         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 } })
+            .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" })
@@ -739,7 +747,7 @@ const sheet = UIBottomSheet(
 .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(
     // the map / page content behind the sheet