lecodes-sdk 2.0.3 → 2.0.5

package/prompts/dist/design.md

@@ -191,7 +191,7 @@ const label: Style<UIText> = { fontSize: 12, fontWeight: 600, letterSpacing: 2 }
 // 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; UIText/UIImage/UISpacer have bgColor only):
-//   bgColor, bgImage (string | imported asset), bgSize ("cover"|"contain"|"tile"), bgGradient
+//   bgColor, bgImage (string | imported asset), 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)".
 //   Layers paint bottom-to-top: bgColor → bgImage → bgGradient (gradient over image = text scrim).
 //   bgImage is decoration BEHIND children — an image that IS the content belongs in UIImage.
@@ -221,10 +221,11 @@ const label: Style<UIText> = { fontSize: 12, fontWeight: 600, letterSpacing: 2 }
 
 // --- Theme variables ---
 // theme({...}) merges app vars into one table; styles read them with "var(--name)" (numbers are px):
-const T = theme({ primaryColor: "#0A84FF" })
-label.style({ color: T.primaryColor })          // or "var(--primaryColor)"
-// theme({ color, fontFamily }) drive the DEFAULT text color/font app-wide. "var(--name, fallback)"
-// applies the fallback while the key is unset — how the SDK tab bar (defineTabs) stays themeable.
+const T = theme({ accent: "#0A84FF" })
+label.style({ color: T.accent })                // or "var(--accent)"
+// ROLES the SDK reads itself: bg (screens) · surface / border (the tab bar) · text / fontFamily
+// (text that names none) · textMuted (inactive tabs) · accent (the active tab). "var(--name,
+// fallback)" applies the fallback while the key is unset.
 
 // --- Defaults that surprise ---
 // flexShrink: 0 — elements don't shrink to fit (exception: UIScrollable defaults flexShrink: 1 so it scrolls
@@ -327,20 +328,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 }
 ```
@@ -350,7 +351,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 } })
 
@@ -361,7 +362,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 })
@@ -380,9 +381,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 })
 ```
 
@@ -479,8 +480,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/ui-app.md

@@ -403,8 +403,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
@@ -620,7 +620,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).
@@ -647,23 +647,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.
 
@@ -695,7 +699,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.
 
@@ -769,14 +773,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
@@ -798,7 +813,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 ...>`)).
@@ -900,17 +915,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 },
@@ -927,9 +941,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[]) =>
@@ -938,7 +952,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/ui-design.md

@@ -92,7 +92,7 @@ const label: Style<UIText> = { fontSize: 12, fontWeight: 600, letterSpacing: 2 }
 // 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; UIText/UIImage/UISpacer have bgColor only):
-//   bgColor, bgImage (string | imported asset), bgSize ("cover"|"contain"|"tile"), bgGradient
+//   bgColor, bgImage (string | imported asset), 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)".
 //   Layers paint bottom-to-top: bgColor → bgImage → bgGradient (gradient over image = text scrim).
 //   bgImage is decoration BEHIND children — an image that IS the content belongs in UIImage.
@@ -122,10 +122,11 @@ const label: Style<UIText> = { fontSize: 12, fontWeight: 600, letterSpacing: 2 }
 
 // --- Theme variables ---
 // theme({...}) merges app vars into one table; styles read them with "var(--name)" (numbers are px):
-const T = theme({ primaryColor: "#0A84FF" })
-label.style({ color: T.primaryColor })          // or "var(--primaryColor)"
-// theme({ color, fontFamily }) drive the DEFAULT text color/font app-wide. "var(--name, fallback)"
-// applies the fallback while the key is unset — how the SDK tab bar (defineTabs) stays themeable.
+const T = theme({ accent: "#0A84FF" })
+label.style({ color: T.accent })                // or "var(--accent)"
+// ROLES the SDK reads itself: bg (screens) · surface / border (the tab bar) · text / fontFamily
+// (text that names none) · textMuted (inactive tabs) · accent (the active tab). "var(--name,
+// fallback)" applies the fallback while the key is unset.
 
 // --- Defaults that surprise ---
 // flexShrink: 0 — elements don't shrink to fit (exception: UIScrollable defaults flexShrink: 1 so it scrolls

package/prompts/ui.md

@@ -42,8 +42,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
@@ -259,7 +259,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).
@@ -298,11 +298,15 @@ const btn: Style<UIButton> = { bgColor: "#333", borderRadius: 12 }
 // --- 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.
 
@@ -334,7 +338,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.
 
@@ -448,7 +452,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 ...>`)).
@@ -550,17 +554,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 },
@@ -577,9 +580,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[]) =>
@@ -588,7 +591,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/src/animate/tween/read.ts

@@ -0,0 +1,146 @@
+// The READER of the tween blob: `buildBlob`'s layout (./spec.ts) back into tracks and keys. For a
+// host that plays an animation with no creator-tween in it (Web Lite hands the tracks to the
+// browser's animations) — creator-tween reads the same layout in C (blob.h).
+//
+// The reader is the builder's twin and lives beside it: tests/animate/blob.test.ts builds a spec,
+// reads it back and holds the two against each other, so a change of the layout that reaches one
+// side only fails there.
+
+import { EASE_TABLE, EASE_TABLE_SIZE, evalEasing, type EasingSpec } from "./easing"
+
+/** The version of the layout this reader knows (./spec.ts BLOB_VERSION). */
+const VERSION = 1
+// The kinds whose one lane is an index into the string table (./spec.ts KIND_*).
+const KIND_TRANSFORM_MATRIX = 4, KIND_DISCRETE = 8, KIND_STRING = 9
+
+export type BlobKey = {
+  /** 0..1 within the track. */
+  t: number
+  easing: EasingSpec
+  /** Absent = the target's value when the animation first plays. */
+  value?: { lanes: number[] } | { str: string }
+}
+
+export type BlobTrack = {
+  domain: number
+  /** An index into the `targets` handed over next to the blob (a role, in a transition's blob). */
+  target: number
+  prop: string
+  kind: number
+  lanes: number
+  /** The unit of a FLOAT_UNIT, the function list of a TRANSFORM. */
+  sig?: string
+  atMs: number
+  durMs: number
+  commit: boolean
+  keys: BlobKey[]
+}
+
+export type ReadBlob = {
+  clock: number
+  /** One iteration, ms. */
+  durationMs: number
+  delayMs: number
+  /** -1 = forever. */
+  iterations: number
+  pingPong: boolean
+  rate: number
+  /** Time-callbacks, ms; the index is what the host reports. */
+  calls: number[]
+  tracks: BlobTrack[]
+}
+
+/** The blob as tracks, or null for data that is not a blob of this version (or is cut short). */
+export const readBlob = (data: ArrayLike<number>, strings: readonly string[]): ReadBlob | null => {
+  if (data.length < 10 || data[0] !== VERSION) return null
+  const nTracks = data[7]!, nCalls = data[8]!, nTables = data[9]!
+  let at = 10
+  if (at + nCalls + nTables * EASE_TABLE_SIZE > data.length) return null
+  const calls: number[] = []
+  for (let i = 0; i < nCalls; i++) calls.push(data[at++]!)
+  const tables: Float32Array[] = []
+  for (let i = 0; i < nTables; i++) {
+    const table = new Float32Array(EASE_TABLE_SIZE)
+    for (let k = 0; k < EASE_TABLE_SIZE; k++) table[k] = data[at++]!
+    tables.push(table)
+  }
+  const str = (index: number): string | undefined => (index >= 0 ? strings[index] : undefined)
+
+  const tracks: BlobTrack[] = []
+  for (let t = 0; t < nTracks; t++) {
+    if (at + 10 > data.length) return null
+    const kind = data[at + 3]!, lanes = data[at + 4]!, nKeys = data[at + 8]!
+    const track: BlobTrack = {
+      domain: data[at]!, target: data[at + 1]!, prop: str(data[at + 2]!) ?? "", kind, lanes,
+      sig: str(data[at + 9]!), atMs: data[at + 5]!, durMs: data[at + 6]!, commit: data[at + 7]! !== 0, keys: [],
+    }
+    at += 10
+    if (at + nKeys * (7 + lanes) > data.length) return null
+    const stringLane = kind === KIND_TRANSFORM_MATRIX || kind === KIND_DISCRETE || kind === KIND_STRING
+    for (let k = 0; k < nKeys; k++) {
+      const easeKind = data[at + 1]!
+      const p: [number, number, number, number] = [data[at + 2]!, data[at + 3]!, data[at + 4]!, data[at + 5]!]
+      const easing: EasingSpec = easeKind === EASE_TABLE ? { kind: easeKind, p, table: tables[p[0]] } : { kind: easeKind, p }
+      const key: BlobKey = { t: data[at]!, easing }
+      if (data[at + 6]! !== 0) {
+        if (stringLane) key.value = { str: str(data[at + 7]!) ?? "" }
+        else {
+          const values: number[] = []
+          for (let l = 0; l < lanes; l++) values.push(data[at + 7 + l]!)
+          key.value = { lanes: values }
+        }
+      }
+      at += 7 + lanes
+      track.keys.push(key)
+    }
+    tracks.push(track)
+  }
+  if (at !== data.length) return null
+  return { clock: data[1]!, durationMs: data[2]!, delayMs: data[3]!, iterations: data[4]!, pingPong: data[5]! !== 0, rate: data[6]!, calls, tracks }
+}
+
+// ---- a track's value at a time -------------------------------------------------------------------
+
+const KIND_QUAT = 6, KIND_MAT4 = 11
+
+const slerp = (out: number[], o: number, a: number[], b: number[], s: number): void => {
+  let bx = b[o] ?? 0, by = b[o + 1] ?? 0, bz = b[o + 2] ?? 0, bw = b[o + 3] ?? 1
+  const ax = a[o] ?? 0, ay = a[o + 1] ?? 0, az = a[o + 2] ?? 0, aw = a[o + 3] ?? 1
+  let cosom = ax * bx + ay * by + az * bz + aw * bw
+  if (cosom < 0) { cosom = -cosom; bx = -bx; by = -by; bz = -bz; bw = -bw }
+  let k0 = 1 - s, k1 = s
+  if (1 - cosom > 1e-6) {
+    const omega = Math.acos(Math.min(1, cosom)), sinom = Math.sin(omega)
+    k0 = Math.sin((1 - s) * omega) / sinom
+    k1 = Math.sin(s * omega) / sinom
+  }
+  out[o] = k0 * ax + k1 * bx; out[o + 1] = k0 * ay + k1 * by; out[o + 2] = k0 * az + k1 * bz; out[o + 3] = k0 * aw + k1 * bw
+}
+
+/** The two keys around the local time `ms` of a track and how far between them the track is,
+ *  eased: the first key holds before the track, the last one after it. */
+export const segmentAt = (track: BlobTrack, ms: number): { from: BlobKey, to: BlobKey, s: number } | null => {
+  const keys = track.keys
+  if (keys.length === 0) return null
+  const u = track.durMs <= 0 ? (ms >= track.atMs ? 1 : 0) : Math.min(1, Math.max(0, (ms - track.atMs) / track.durMs))
+  const first = keys[0]!, last = keys[keys.length - 1]!
+  if (keys.length === 1 || u <= first.t) return { from: first, to: first, s: 0 }
+  if (u >= last.t) return { from: last, to: last, s: 0 }
+  let i = 0
+  while (i + 1 < keys.length && keys[i + 1]!.t <= u) i++
+  const from = keys[i]!, to = keys[i + 1]!
+  const span = to.t - from.t
+  return { from, to, s: evalEasing(from.easing, span > 0 ? (u - from.t) / span : 1) }
+}
+
+/** The lanes of a numeric track at the local time `ms`, into `out` (a key with no value reads as zeros). */
+export const sampleTrack = (track: BlobTrack, ms: number, out: number[]): void => {
+  const at = segmentAt(track, ms)
+  if (!at) return
+  const lanesOf = (key: BlobKey): number[] => (key.value && "lanes" in key.value ? key.value.lanes : [])
+  const a = lanesOf(at.from), b = lanesOf(at.to), s = at.s
+  const lerp = (from: number, to: number) => { for (let k = from; k < to; k++) out[k] = (a[k] ?? 0) + ((b[k] ?? 0) - (a[k] ?? 0)) * s }
+  if (track.kind === KIND_QUAT) { slerp(out, 0, a, b, s); return }
+  if (track.kind === KIND_MAT4) { lerp(0, 3); slerp(out, 3, a, b, s); lerp(7, 10); return }
+  lerp(0, track.lanes)
+}

package/src/bridges/device.d.ts

@@ -28,6 +28,15 @@ declare global {
     /** Fire a one-shot semantic haptic (device.vibrate). `style` is a HapticStyle string. Optional:
      *  hosts without haptic hardware (web, headless, iPad / older iPhones) simply don't implement it. */
     vibrate?(style: string): void
+    /** The HOST's performance overlay (device.statsOverlay): frames per second as the display got
+     *  them, how evenly, the GPU's and the main thread's milliseconds — a line the host draws over
+     *  everything itself, about once a second, with no JS, tree or layout behind it. It is the
+     *  host's state, not a world's: it stays through `_creatorApp.run()`, so a launcher turns it
+     *  on for whatever it opens next. Optional, as a pair: a host with no overlay (web, headless)
+     *  leaves both out and the SDK reads `false`. */
+    setStatsOverlay?(enabled: boolean): void
+    /** Whether the overlay is on. */
+    statsOverlay?(): boolean
 
     // ---- device.motion (orientation sensor; pull-per-frame model) --------------------------------
     /** Does this device have the motion sensors (gyro)? Surfaced as device.motion.available. */

package/src/bridges/tree.d.ts

@@ -67,6 +67,11 @@ declare global {
     // Theme variables: MERGES `values` (null removes a key, numbers are px lengths, a color is a
     // string) and re-resolves live styles. Env names (safe-*, vw/vh/…) are reserved.
     setTheme(values: Record<string, string | f64 | null>): void
+    // The same for ONE node's subtree (`el.theme({...})`): a SCOPE. A `var(--name)` on a node reads
+    // the nearest scope up its tree — the node, its ancestors, and for a pager's page or a vlist's
+    // item the pager / list it is in — then the app's table. A destination pushed over the node and
+    // a widget are roots of their own: no scope reaches them. The comfort-* knobs stay app-wide.
+    setNodeTheme(id: TreeNodeId, values: Record<string, string | f64 | null>): void
 
     // ---- presentation -------------------------------------------------------------------------
     // A transition (sdk/src/ui/transitions.ts): a tween blob whose targets are ROLES — `roles[i]` is

package/src/canvas/gen/cssColor.ts

@@ -1,4 +1,4 @@
-// GENERATED by scripts/vendor-canvas.ts from engines/canvas/recorders/ts/src/cssColor.ts @ ae6bc30b952b — do not edit here.
+// GENERATED by scripts/vendor-canvas.ts from engines/canvas/recorders/ts/src/cssColor.ts @ 72e545dab1f5 — do not edit here.
 // Bump the submodule and run `bun run vendor:canvas`; `bun run check:canvas-ops` fails when this copy is stale.
 // The CSS color parser — the TypeScript twin of core/include/anycanvas/css_color.h: the same grammar,
 // the same name table, float32 emulated op for op (Math.fround, in the header's order), so both give

package/src/canvas/gen/recorder.ts

@@ -1,4 +1,4 @@
-// GENERATED by scripts/vendor-canvas.ts from engines/canvas/recorders/ts/src/recorder.ts @ ae6bc30b952b — do not edit here.
+// GENERATED by scripts/vendor-canvas.ts from engines/canvas/recorders/ts/src/recorder.ts @ 72e545dab1f5 — do not edit here.
 // Bump the submodule and run `bun run vendor:canvas`; `bun run check:canvas-ops` fails when this copy is stale.
 // The TypeScript recorder: a Canvas2D-shaped API whose calls WRITE the opcode stream of spec/ops.h.
 // Nothing is drawn here — the stream goes to the core interpreter (native, or wasm on the web), which

package/src/canvas/gen/spec.ts

@@ -1,4 +1,4 @@
-// GENERATED by scripts/vendor-canvas.ts from engines/canvas/spec/gen/spec.ts @ ae6bc30b952b — do not edit here.
+// GENERATED by scripts/vendor-canvas.ts from engines/canvas/spec/gen/spec.ts @ 72e545dab1f5 — do not edit here.
 // Bump the submodule and run `bun run vendor:canvas`; `bun run check:canvas-ops` fails when this copy is stale.
 // GENERATED by spec/generate.ts from spec/*.h — do not edit.
 

package/src/chisel.ts

@@ -123,7 +123,7 @@ export const chiselVocab: ChiselVocab = {
     // Exactly the builder methods that return the node (tests/compile/chisel-vocab.test.ts proves it against
     // the interfaces): `animateTo` / `animateFrom` return an Animation, so they are NOT here.
     chain: [
-      "style", "class", "named",
+      "style", "class", "named", "theme",
       "onClick", "onTouchStart", "onLongPress", "onMouseEnter", "onLayout", "onOpen", "onClose", "onBack",
       "onScroll", "onScrollRelease", "onOverscroll", "onRefresh", "onSubmit",
       "onSelect", "onChange", "onFocus", "onBlur", "onOverlayTap", "onDetent",

package/src/compile/bundler.ts

@@ -69,6 +69,12 @@ export const SERVER_INJECT = "/__sdk/server/inject.ts"
  *  contract, `__sceneEditor` (src/inject.editor.ts → src/scene/editor.ts). Never in a shipped bundle. */
 export const EDITOR_INJECT = "/__sdk/inject.editor.ts"
 
+/** The text of the two inject modules — the lists of what is a global on each side (serverTypes.ts). */
+export const readInjectSources = (): { client: string, server: string } => {
+  const client = resolveInject()
+  return { client: readFileSync(client, "utf8"), server: readFileSync(join(dirname(client), "server", "inject.ts"), "utf8") }
+}
+
 /** The SDK source root (parent of `inject.ts`). chisel needs the source tree, not a prebuilt bundle. */
 const resolveSdkSrc = (): string => {
   const inject = resolveInject()