lecodes-sdk 2.0.4 → 2.0.5

package/package.json

@@ -41,9 +41,10 @@
     "@types/bun": "^1.3.14",
     "@types/node": "^25.9.1",
     "typescript": "~5.8.3",
-    "gl-matrix": "^3.4.4"
+    "gl-matrix": "^3.4.4",
+    "marcidb-embedded": "^0.13.0"
   },
-  "version": "2.0.4",
+  "version": "2.0.5",
   "files": [
     "src",
     "dist",

package/prompts/README.md

@@ -136,7 +136,7 @@ escalation directive (above) lets it swap in the right engine module instead of
 - `index.md` must list every global exported from `sdk/src/inject.ts` — same contract as
   `docs/check.mjs`. When a global is added, update docs, then the module, then index.md.
 - Known corrections baked into these prompts (do not regress; see `docs/AUTHORING.md`):
-  `onEndReached(thresholdPx, cb)` (threshold first), `bgSize: cover|contain|tile` (no `fill`),
+  `onEndReached(thresholdPx, cb)` (threshold first), `bgSize: cover|contain|fill|tile`,
   track `deltaX/deltaY` are per-move, colors are CSS strings / 0xRRGGBB / [r,g,b(,a)] everywhere, `animate` can't
   tween strings/colors, `node.physics` (not `.body`), no `Camera2D.follow`, no
   `UIScrollable.scrollTo`, models can't be cloned.

package/prompts/design.md

@@ -25,20 +25,20 @@ composition:
 
 ```ts
 // design/shared/tokens.ts — surfaces dark-to-light, text in tiers, accents as a family.
-// ONE theme() call registers the vars and returns the accessors ("var(--x)" strings); the system
-// key `color` in the same table sets the app-wide default text color. Re-calling theme() with new
-// values (dark mode, brand swap) restyles every screen — and later the built app — live.
-const palette = {
-  bg: "#080808", card: "#161618", cardAlt: "#1d1d20", field: "#101012",
-  border: "#2a2a2e", text: "#ffffff", muted: "#8a8a93", faint: "#5a5b62",
-  accent: "#00BFC2", accentPressed: "#00999b", accentDeep: "#0c4e4f", onAccent: "#05201f",
+// ONE theme() call registers the vars and returns the accessors ("var(--x)" strings). Re-calling
+// theme() with new values (dark mode, brand swap) restyles every screen — and later the built app
+// — live.
+export const colors = theme({
+  // the ROLES — the SDK reads these too: bg = every screen's background, text = text that names
+  // no color, surface / border / textMuted / accent = the tab bar (defineTabs here, UITabs in the
+  // built app). Name the palette by them; there are no separate keys for the chrome.
+  bg: "#080808", surface: "#161618", border: "#2a2a2e",
+  text: "#ffffff", textMuted: "#8a8a93", accent: "#00BFC2",
+  // the design's own
+  surfaceAlt: "#1d1d20", field: "#101012", faint: "#5a5b62",
+  accentPressed: "#00999b", accentDeep: "#0c4e4f", onAccent: "#05201f",
   success: "#30D158", danger: "#F83131", scrim: "#000000b3",
-  // theme SYSTEM keys — SDK-rendered chrome reads these. `color` = default text color everywhere;
-  // the other four brand the tab bar (defineTabs here, UITabs in the built app). Mirror the brand:
-  color: "#ffffff",
-  primaryColor: "#00BFC2", mutedColor: "#8a8a93", tabbarBg: "#161618", screenBg: "#080808",
-}
-export const colors: { [K in keyof typeof palette]: string } = theme(palette)
+})
 export const spacing = { xs: 4, sm: 8, md: 12, lg: 16, xl: 20, xxl: 24 }
 export const radius = { sm: 8, md: 12, lg: 16, pill: 999 }
 ```
@@ -48,7 +48,7 @@ export const radius = { sm: 8, md: 12, lg: 16, pill: 999 }
 import { colors, spacing, radius } from "./tokens"
 
 export const PrimaryButton = (label: string, o: { name?: string, disabled?: boolean } = {}) =>
-  UIButton(UIText(label).style({ fontSize: 16, fontWeight: 700, color: o.disabled ? colors.muted : colors.onAccent }))
+  UIButton(UIText(label).style({ fontSize: 16, fontWeight: 700, color: o.disabled ? colors.textMuted : colors.onAccent }))
     .style({ height: 52, borderRadius: radius.md, bgColor: o.disabled ? colors.accentDeep : colors.accent,
              justifyContent: "center", alignItems: "center", name: o.name, $pressed: { bgColor: colors.accentPressed } })
 
@@ -59,7 +59,7 @@ export const SectionLabel = (t: string) =>
 export const Field = (o: { label?: string, value?: string, placeholder?: string, focused?: boolean }) =>
   UIColumn(
     o.label ? SectionLabel(o.label) : null,
-    UIRow(UIText(o.value ?? o.placeholder ?? "").style({ flexGrow: 1, fontSize: 16, color: o.value ? colors.text : colors.muted }))
+    UIRow(UIText(o.value ?? o.placeholder ?? "").style({ flexGrow: 1, fontSize: 16, color: o.value ? colors.text : colors.textMuted }))
       .style({ height: 52, px: 16, alignItems: "center", bgColor: colors.field, borderRadius: radius.md,
                border: `1px solid ${o.focused ? colors.accent : colors.border}` }),
   ).style({ gap: spacing.sm })
@@ -78,9 +78,9 @@ export const ConfirmDialog = (o: { title: string, body?: string, confirmLabel: s
   UIWidget(
     UIColumn(
       UIText(o.title).style({ fontSize: 17, fontWeight: 700, color: colors.text, textAlign: "center" }),
-      o.body ? UIText(o.body).style({ fontSize: 14, color: colors.muted, textAlign: "center", lineHeight: "1.4em" }) : null,
+      o.body ? UIText(o.body).style({ fontSize: 14, color: colors.textMuted, textAlign: "center", lineHeight: "1.4em" }) : null,
       PrimaryButton("Cancel", { name: "cancel" }),
-    ).style({ bgColor: colors.card, borderRadius: radius.lg, p: spacing.xl, gap: spacing.lg, width: "86%", maxWidth: 360 }),
+    ).style({ bgColor: colors.surface, borderRadius: radius.lg, p: spacing.xl, gap: spacing.lg, width: "86%", maxWidth: 360 }),
   ).style({ top: 0, left: 0, right: 0, bottom: 0, justifyContent: "center", alignItems: "center", overlayColor: colors.scrim })
 ```
 
@@ -177,8 +177,8 @@ export const mainTabs = defineTabs({
 A screen that shows the bar mounts it with a literal tab id — roots AND pushed details that keep
 the bar; a screen that doesn't mount it is a full-screen push. Mount the bar alone when the screen
 owns its layout (`mainTabs.bar("schedule")`, as above) or wrap content with
-`mainTabs.screen("home", [...])`. Restyle through the theme's system keys — `primaryColor`,
-`mutedColor`, `tabbarBg`, `screenBg`, set in `shared/tokens.ts` — never by reimplementing the
+`mainTabs.screen("home", [...])`. It is colored by the theme's roles — `accent`,
+`textMuted`, `surface`, `border`, `bg`, set in `shared/tokens.ts` — never by reimplementing the
 bar. Keep the `defineTabs({...})` declaration and `.screen("<tab>", ...)` / `.bar("<tab>")` call
 shapes intact — the board parses them.
 

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

@@ -795,8 +795,8 @@ 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.
+// The bar is colored by the theme's roles (accent, textMuted, surface, border) — no keys of its
+//   own; one bar's own colors: tabs.bar.theme({ accent, surface }). Custom layout: 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
@@ -1012,7 +1012,7 @@ const btn: Style<UIButton> = { bgColor: "#333", borderRadius: 12 }
 // Padding:    p, px, py, pt, pb, pl, pr        (≡ padding, paddingHorizontal, paddingVertical, paddingTop, ...)
 // Margin:     m, mx, my, mt, mb, ml, mr        — margins also accept "auto" (mx: "auto" centers a fixed-width element)
 // Background (containers/screen/button/input/video; UIText/UIImage/UISpacer have bgColor only):
-//   bgColor, bgImage (string | FetchResponse | File), bgSize ("cover"|"contain"|"tile"), bgGradient
+//   bgColor, bgImage (string | FetchResponse | File | SvgSource), bgSize ("cover"|"contain"|"fill"|"tile"), bgGradient
 //   bgGradient: a CSS linear-gradient() or radial-gradient() string, e.g. "linear-gradient(to top, rgba(0,0,0,0.7), transparent)"
 //   or "radial-gradient(circle at 50% 40%, #7B2FF7, #0a0a1a)". Comma-separate several gradients to stack them (first = on top).
 //   Layers paint bottom-to-top: bgColor → bgImage → bgGradient (gradient over image = text scrim).
@@ -1039,23 +1039,27 @@ const btn: Style<UIButton> = { bgColor: "#333", borderRadius: 12 }
 // 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
 
 // --- Theme variables ---
 // theme({...}) merges app vars into one table; styles read them with "var(--name)" (numbers are px
 // lengths, null removes a key). Re-calling re-styles the LIVE UI — dark mode is a second call.
-// Returned accessors ARE the var() strings; system vars are statics (theme.primaryColor, …):
-const T = theme({ primaryColor: "#0A84FF", "comfort-left": 20 })
-label.style({ color: T.primaryColor, pl: "var(--comfort-left)" })
-// SYSTEM DEFAULTS: theme({ color, fontFamily }) drive the DEFAULT text color/font — all text
-// without explicit values follows (light theme = set once, not color:"black" per label).
+// ONE call per app. Returned accessors ARE the var() strings:
+const T = theme({ accent: "#0A84FF", "comfort-left": 20 })
+label.style({ color: T.accent, pl: "var(--comfort-left)" })
+// ROLES — keys the SDK reads itself; use them as your palette and add your own keys beside them:
+//   bg (every screen's background) · surface (cards, bars; the tab bar) · border (hairlines)
+//   text (text with no color of its own) · textMuted (secondary; inactive tabs) · accent (active tab)
+//   fontFamily (text with no font of its own). Light theme = set text once, not a color per label.
+// SCOPE: el.theme({...}) — the same keys for ONE subtree (a card, tabs.bar, a whole screen); its
+// descendants read them first. A pushed screen / a widget is its own root: give it its own.
 // 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.
 
@@ -1087,7 +1091,7 @@ screen.style({ flexDirection: "column", p: 16, $landscape: { flexDirection: "row
 // 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.
 // boxSizing: "border-box" — width/height include padding & border.
-// Screen bg is black, default text is WHITE at fontSize 14 (retarget once via theme({ color, fontFamily })).
+// Screen bg is black, default text is WHITE at fontSize 14 (retarget once via theme({ bg, text, fontFamily })).
 // On any light surface — white cards, sheets, inputs — white text renders invisible: use dark text there
 // ("#111"/black), checking every UIText against the surface it actually sits on, not the screen.
 
@@ -1161,14 +1165,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
@@ -1190,7 +1205,7 @@ font("ibm-plex-sans", { weights: [400, 600], italic: true })  // narrow/extend t
 // A project's own file: font("./fonts/Brand.ttf") → real family name read from the file itself
 // (weight/italic too — no options); two weight files of one family return the same name.
 // registerFont(family, url, {weight, style}) survives ONLY for runtime-computed URLs — rare.
-// No style inheritance — set fontFamily per UIText or via theme() (extract a shared Style<UIText>).
+// The app's font: theme({ fontFamily }). A second family is set per UIText (extract a shared Style<UIText>).
 
 // ===== SVG IMAGES =====
 // SvgSource wraps raw SVG XML for use as an image source: UIImage(SvgSource(`<svg ...>`)).
@@ -1292,17 +1307,16 @@ screen.open()
 </file>
 
 // === EXAMPLE 2: Theme tokens + fetched list with loading / error states ===
-// A tokens module every screen imports, light-themed: theme({ color }) sets the default text
-// color ONCE — no color: "#111" on every label.
+// A tokens module every screen imports, light-themed. ONE theme() call: the roles (bg, surface,
+// border, text, textMuted, accent) color the screens, the default text and the tab bar — no
+// color: "#111" on every label — and the app's own keys sit beside them.
 <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 colors = theme({
+    bg: "#F4F6F5", surface: "#FFFFFF", border: "#E4E8E6",
+    text: "#131A17", textMuted: "#606B65", accent: "#15A34A",
+    accentSoft: "#E7F6ED", onAccent: "#FFFFFF",
+})
 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 },
@@ -1319,9 +1333,9 @@ const Row = (u: User) => UIRow(
                  justifyContent: "center", alignItems: "center" }),
     UIColumn(
         UIText(u.name).style({ ...font.bodyStrong }),
-        UIText(u.email).style({ ...font.small, color: colors.muted }),
+        UIText(u.email).style({ ...font.small, color: colors.textMuted }),
     ).style({ flexGrow: 1, flexShrink: 1, gap: 2, alignItems: "flex-start" }),
-).style({ alignItems: "center", gap: 12, bgColor: colors.card, borderRadius: 16,
+).style({ alignItems: "center", gap: 12, bgColor: colors.surface, borderRadius: 16,
           border: `1px solid ${colors.border}`, p: 14 })
 
 const Centered = (...children: UINodeChild[]) =>
@@ -1330,7 +1344,7 @@ const Centered = (...children: UINodeChild[]) =>
 let body: UIColumn
 
 const loadData = async () => {
-    body.setContent([Centered(UIText("Loading…").style({ color: colors.muted }))])
+    body.setContent([Centered(UIText("Loading…").style({ color: colors.textMuted }))])
     const res = await fetch("https://jsonplaceholder.typicode.com/users")
     if (res.status !== 200) {
         body.setContent([Centered(

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

@@ -937,8 +937,8 @@ 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.
+// The bar is colored by the theme's roles (accent, textMuted, surface, border) — no keys of its
+//   own; one bar's own colors: tabs.bar.theme({ accent, surface }). Custom layout: 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
@@ -1154,7 +1154,7 @@ const btn: Style<UIButton> = { bgColor: "#333", borderRadius: 12 }
 // Padding:    p, px, py, pt, pb, pl, pr        (≡ padding, paddingHorizontal, paddingVertical, paddingTop, ...)
 // Margin:     m, mx, my, mt, mb, ml, mr        — margins also accept "auto" (mx: "auto" centers a fixed-width element)
 // Background (containers/screen/button/input/video; UIText/UIImage/UISpacer have bgColor only):
-//   bgColor, bgImage (string | FetchResponse | File), bgSize ("cover"|"contain"|"tile"), bgGradient
+//   bgColor, bgImage (string | FetchResponse | File | SvgSource), bgSize ("cover"|"contain"|"fill"|"tile"), bgGradient
 //   bgGradient: a CSS linear-gradient() or radial-gradient() string, e.g. "linear-gradient(to top, rgba(0,0,0,0.7), transparent)"
 //   or "radial-gradient(circle at 50% 40%, #7B2FF7, #0a0a1a)". Comma-separate several gradients to stack them (first = on top).
 //   Layers paint bottom-to-top: bgColor → bgImage → bgGradient (gradient over image = text scrim).
@@ -1181,23 +1181,27 @@ const btn: Style<UIButton> = { bgColor: "#333", borderRadius: 12 }
 // 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
 
 // --- Theme variables ---
 // theme({...}) merges app vars into one table; styles read them with "var(--name)" (numbers are px
 // lengths, null removes a key). Re-calling re-styles the LIVE UI — dark mode is a second call.
-// Returned accessors ARE the var() strings; system vars are statics (theme.primaryColor, …):
-const T = theme({ primaryColor: "#0A84FF", "comfort-left": 20 })
-label.style({ color: T.primaryColor, pl: "var(--comfort-left)" })
-// SYSTEM DEFAULTS: theme({ color, fontFamily }) drive the DEFAULT text color/font — all text
-// without explicit values follows (light theme = set once, not color:"black" per label).
+// ONE call per app. Returned accessors ARE the var() strings:
+const T = theme({ accent: "#0A84FF", "comfort-left": 20 })
+label.style({ color: T.accent, pl: "var(--comfort-left)" })
+// ROLES — keys the SDK reads itself; use them as your palette and add your own keys beside them:
+//   bg (every screen's background) · surface (cards, bars; the tab bar) · border (hairlines)
+//   text (text with no color of its own) · textMuted (secondary; inactive tabs) · accent (active tab)
+//   fontFamily (text with no font of its own). Light theme = set text once, not a color per label.
+// SCOPE: el.theme({...}) — the same keys for ONE subtree (a card, tabs.bar, a whole screen); its
+// descendants read them first. A pushed screen / a widget is its own root: give it its own.
 // 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.
 
@@ -1229,7 +1233,7 @@ screen.style({ flexDirection: "column", p: 16, $landscape: { flexDirection: "row
 // 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.
 // boxSizing: "border-box" — width/height include padding & border.
-// Screen bg is black, default text is WHITE at fontSize 14 (retarget once via theme({ color, fontFamily })).
+// Screen bg is black, default text is WHITE at fontSize 14 (retarget once via theme({ bg, text, fontFamily })).
 // On any light surface — white cards, sheets, inputs — white text renders invisible: use dark text there
 // ("#111"/black), checking every UIText against the surface it actually sits on, not the screen.
 
@@ -1303,14 +1307,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
@@ -1332,7 +1347,7 @@ font("ibm-plex-sans", { weights: [400, 600], italic: true })  // narrow/extend t
 // A project's own file: font("./fonts/Brand.ttf") → real family name read from the file itself
 // (weight/italic too — no options); two weight files of one family return the same name.
 // registerFont(family, url, {weight, style}) survives ONLY for runtime-computed URLs — rare.
-// No style inheritance — set fontFamily per UIText or via theme() (extract a shared Style<UIText>).
+// The app's font: theme({ fontFamily }). A second family is set per UIText (extract a shared Style<UIText>).
 
 // ===== SVG IMAGES =====
 // SvgSource wraps raw SVG XML for use as an image source: UIImage(SvgSource(`<svg ...>`)).
@@ -1434,17 +1449,16 @@ screen.open()
 </file>
 
 // === EXAMPLE 2: Theme tokens + fetched list with loading / error states ===
-// A tokens module every screen imports, light-themed: theme({ color }) sets the default text
-// color ONCE — no color: "#111" on every label.
+// A tokens module every screen imports, light-themed. ONE theme() call: the roles (bg, surface,
+// border, text, textMuted, accent) color the screens, the default text and the tab bar — no
+// color: "#111" on every label — and the app's own keys sit beside them.
 <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 colors = theme({
+    bg: "#F4F6F5", surface: "#FFFFFF", border: "#E4E8E6",
+    text: "#131A17", textMuted: "#606B65", accent: "#15A34A",
+    accentSoft: "#E7F6ED", onAccent: "#FFFFFF",
+})
 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 },
@@ -1461,9 +1475,9 @@ const Row = (u: User) => UIRow(
                  justifyContent: "center", alignItems: "center" }),
     UIColumn(
         UIText(u.name).style({ ...font.bodyStrong }),
-        UIText(u.email).style({ ...font.small, color: colors.muted }),
+        UIText(u.email).style({ ...font.small, color: colors.textMuted }),
     ).style({ flexGrow: 1, flexShrink: 1, gap: 2, alignItems: "flex-start" }),
-).style({ alignItems: "center", gap: 12, bgColor: colors.card, borderRadius: 16,
+).style({ alignItems: "center", gap: 12, bgColor: colors.surface, borderRadius: 16,
           border: `1px solid ${colors.border}`, p: 14 })
 
 const Centered = (...children: UINodeChild[]) =>
@@ -1472,7 +1486,7 @@ const Centered = (...children: UINodeChild[]) =>
 let body: UIColumn
 
 const loadData = async () => {
-    body.setContent([Centered(UIText("Loading…").style({ color: colors.muted }))])
+    body.setContent([Centered(UIText("Loading…").style({ color: colors.textMuted }))])
     const res = await fetch("https://jsonplaceholder.typicode.com/users")
     if (res.status !== 200) {
         body.setContent([Centered(

package/prompts/dist/ar-app.md

@@ -813,8 +813,8 @@ 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.
+// The bar is colored by the theme's roles (accent, textMuted, surface, border) — no keys of its
+//   own; one bar's own colors: tabs.bar.theme({ accent, surface }). Custom layout: 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
@@ -1030,7 +1030,7 @@ const btn: Style<UIButton> = { bgColor: "#333", borderRadius: 12 }
 // Padding:    p, px, py, pt, pb, pl, pr        (≡ padding, paddingHorizontal, paddingVertical, paddingTop, ...)
 // Margin:     m, mx, my, mt, mb, ml, mr        — margins also accept "auto" (mx: "auto" centers a fixed-width element)
 // Background (containers/screen/button/input/video; UIText/UIImage/UISpacer have bgColor only):
-//   bgColor, bgImage (string | FetchResponse | File), bgSize ("cover"|"contain"|"tile"), bgGradient
+//   bgColor, bgImage (string | FetchResponse | File | SvgSource), bgSize ("cover"|"contain"|"fill"|"tile"), bgGradient
 //   bgGradient: a CSS linear-gradient() or radial-gradient() string, e.g. "linear-gradient(to top, rgba(0,0,0,0.7), transparent)"
 //   or "radial-gradient(circle at 50% 40%, #7B2FF7, #0a0a1a)". Comma-separate several gradients to stack them (first = on top).
 //   Layers paint bottom-to-top: bgColor → bgImage → bgGradient (gradient over image = text scrim).
@@ -1057,23 +1057,27 @@ const btn: Style<UIButton> = { bgColor: "#333", borderRadius: 12 }
 // 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
 
 // --- Theme variables ---
 // theme({...}) merges app vars into one table; styles read them with "var(--name)" (numbers are px
 // lengths, null removes a key). Re-calling re-styles the LIVE UI — dark mode is a second call.
-// Returned accessors ARE the var() strings; system vars are statics (theme.primaryColor, …):
-const T = theme({ primaryColor: "#0A84FF", "comfort-left": 20 })
-label.style({ color: T.primaryColor, pl: "var(--comfort-left)" })
-// SYSTEM DEFAULTS: theme({ color, fontFamily }) drive the DEFAULT text color/font — all text
-// without explicit values follows (light theme = set once, not color:"black" per label).
+// ONE call per app. Returned accessors ARE the var() strings:
+const T = theme({ accent: "#0A84FF", "comfort-left": 20 })
+label.style({ color: T.accent, pl: "var(--comfort-left)" })
+// ROLES — keys the SDK reads itself; use them as your palette and add your own keys beside them:
+//   bg (every screen's background) · surface (cards, bars; the tab bar) · border (hairlines)
+//   text (text with no color of its own) · textMuted (secondary; inactive tabs) · accent (active tab)
+//   fontFamily (text with no font of its own). Light theme = set text once, not a color per label.
+// SCOPE: el.theme({...}) — the same keys for ONE subtree (a card, tabs.bar, a whole screen); its
+// descendants read them first. A pushed screen / a widget is its own root: give it its own.
 // 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.
 
@@ -1105,7 +1109,7 @@ screen.style({ flexDirection: "column", p: 16, $landscape: { flexDirection: "row
 // 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.
 // boxSizing: "border-box" — width/height include padding & border.
-// Screen bg is black, default text is WHITE at fontSize 14 (retarget once via theme({ color, fontFamily })).
+// Screen bg is black, default text is WHITE at fontSize 14 (retarget once via theme({ bg, text, fontFamily })).
 // On any light surface — white cards, sheets, inputs — white text renders invisible: use dark text there
 // ("#111"/black), checking every UIText against the surface it actually sits on, not the screen.
 
@@ -1179,14 +1183,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
@@ -1208,7 +1223,7 @@ font("ibm-plex-sans", { weights: [400, 600], italic: true })  // narrow/extend t
 // A project's own file: font("./fonts/Brand.ttf") → real family name read from the file itself
 // (weight/italic too — no options); two weight files of one family return the same name.
 // registerFont(family, url, {weight, style}) survives ONLY for runtime-computed URLs — rare.
-// No style inheritance — set fontFamily per UIText or via theme() (extract a shared Style<UIText>).
+// The app's font: theme({ fontFamily }). A second family is set per UIText (extract a shared Style<UIText>).
 
 // ===== SVG IMAGES =====
 // SvgSource wraps raw SVG XML for use as an image source: UIImage(SvgSource(`<svg ...>`)).
@@ -1310,17 +1325,16 @@ screen.open()
 </file>
 
 // === EXAMPLE 2: Theme tokens + fetched list with loading / error states ===
-// A tokens module every screen imports, light-themed: theme({ color }) sets the default text
-// color ONCE — no color: "#111" on every label.
+// A tokens module every screen imports, light-themed. ONE theme() call: the roles (bg, surface,
+// border, text, textMuted, accent) color the screens, the default text and the tab bar — no
+// color: "#111" on every label — and the app's own keys sit beside them.
 <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 colors = theme({
+    bg: "#F4F6F5", surface: "#FFFFFF", border: "#E4E8E6",
+    text: "#131A17", textMuted: "#606B65", accent: "#15A34A",
+    accentSoft: "#E7F6ED", onAccent: "#FFFFFF",
+})
 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 },
@@ -1337,9 +1351,9 @@ const Row = (u: User) => UIRow(
                  justifyContent: "center", alignItems: "center" }),
     UIColumn(
         UIText(u.name).style({ ...font.bodyStrong }),
-        UIText(u.email).style({ ...font.small, color: colors.muted }),
+        UIText(u.email).style({ ...font.small, color: colors.textMuted }),
     ).style({ flexGrow: 1, flexShrink: 1, gap: 2, alignItems: "flex-start" }),
-).style({ alignItems: "center", gap: 12, bgColor: colors.card, borderRadius: 16,
+).style({ alignItems: "center", gap: 12, bgColor: colors.surface, borderRadius: 16,
           border: `1px solid ${colors.border}`, p: 14 })
 
 const Centered = (...children: UINodeChild[]) =>
@@ -1348,7 +1362,7 @@ const Centered = (...children: UINodeChild[]) =>
 let body: UIColumn
 
 const loadData = async () => {
-    body.setContent([Centered(UIText("Loading…").style({ color: colors.muted }))])
+    body.setContent([Centered(UIText("Loading…").style({ color: colors.textMuted }))])
     const res = await fetch("https://jsonplaceholder.typicode.com/users")
     if (res.status !== 200) {
         body.setContent([Centered(