lecodes-sdk 2.0.4 → 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/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/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()

package/src/compile/compileProject.ts

@@ -7,7 +7,7 @@ import { bundleProjectWithMap, scanModulesChisel, type MemoryFiles } from "./bun
 import { detectEntry } from "./detectEntry"
 import { buildHeader } from "./header"
 import { inlineSourceMapComment, offsetSourceMap } from "./sourcemap"
-import { stubServerEntries } from "./serverSplit"
+import { ClientPublishError, clientPublishes, stubServerEntries } from "./serverSplit"
 
 export type CompileFileType = "text" | "resource" | "shader"
 
@@ -185,6 +185,8 @@ export const pluginsOfBundle = (mapJson: string): string[] => {
 
 export const compileProjectWithMap = async (opts: CompileOptions): Promise<CompileResult> => {
   // Client bundle: every *.server.ts becomes its RPC/channel stub (server code stays server-side).
+  const published = clientPublishes(opts.entries)
+  if (published.length) throw new ClientPublishError(published)
   const entries = stubServerEntries(opts.entries, opts.serverUrl ?? "")
   const entry = opts.entryOverride ?? detectEntry(entries, scanModulesChisel).entry
   if (!entry) {

package/src/compile/index.ts

@@ -4,6 +4,8 @@
 export { bundleProject, bundleProjectWithMap, scanModulesChisel, CLIENT_INJECT, SERVER_INJECT, type MemoryFiles } from "./bundler"
 export {
   compileServerBundle,
+  clientPublishes,
+  ClientPublishError,
   scanServerExports,
   scanServerModules,
   stubServerEntries,
@@ -17,7 +19,7 @@ export {
   type ServerExportKind,
   type ServerManifest,
 } from "./serverSplit"
-export { deriveEndpointParams, EndpointTypeError, type DeriveResult } from "./serverTypes"
+export { deriveEndpointParams, EndpointTypeError, SyncEndpointError, UnawaitedUserQueryError, WrongSideGlobalError, type DeriveResult } from "./serverTypes"
 export {
   detectEntry,
   scanModulesFallback,

package/src/compile/serverSplit.ts

@@ -9,7 +9,7 @@
  * side effects, not entry exports) — the runner reads that (src/server/runtime.ts).
  *
  * Export kinds are found by a static scan (no TS program needed): a function export is an
- * endpoint, a `channel(...)` export is a channel, anything else is server-only.
+ * endpoint, a `channel<…>()…` export is a channel, anything else is server-only.
  */
 
 import type { AppConfig } from "../server/auth/appConfig"
@@ -129,25 +129,70 @@ export const serverStubSource = (path: string, exports: ServerExport[], serverUr
   return `// client stub of ${mod} — generated by the lecodes compiler\n${lines.join("\n")}\n`
 }
 
+// ───────────────────────────── a channel in the app ─────────────────────────────
+
+/** A channel export has ONE type on both sides, so `publish` type-checks in the app — where the
+ *  export is the subscribing proxy. Said at compile time, with what to do instead. */
+export class ClientPublishError extends Error {
+  readonly problems: string[]
+  constructor(problems: string[]) {
+    super(`a channel goes from the server to the app — the app subscribes; to send, call a server function that publishes:\n  ${problems.join("\n  ")}`)
+    this.name = "ClientPublishError"
+    this.problems = problems
+  }
+}
+
+/** `<channel>.publish(` in the project's client files, for every channel imported from a `*.server.ts`. */
+export const clientPublishes = (entries: CompileEntry[]): string[] => {
+  const channels = new Map<string, Set<string>>()
+  for (const [path, exports] of Object.entries(scanServerModules(entries))) {
+    const names = exports.filter(e => e.kind === "channel").map(e => e.name)
+    if (names.length) channels.set(path.replace(/\.[tj]s$/, ""), new Set(names))
+  }
+  if (channels.size === 0) return []
+  const out: string[] = []
+  for (const e of entries) {
+    if (e.type !== "text" || isServerPath(e.path) || !/\.[tj]sx?$/.test(e.path)) continue
+    const src = e.text ?? ""
+    const dir = normalizePath(e.path).replace(/\/[^/]*$/, "")
+    const locals: string[] = []
+    for (const m of src.matchAll(/import\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g)) {
+      if (!m[2].startsWith(".")) continue
+      const names = channels.get(normalizePath(`${dir}/${m[2]}`).replace(/\.[tj]s$/, ""))
+      if (!names) continue
+      for (const part of m[1].split(",")) {
+        const [imported, local] = part.split(/\s+as\s+/).map(s => s.trim())
+        if (imported && names.has(imported)) locals.push(local ?? imported)
+      }
+    }
+    if (!locals.length) continue
+    const code = blankCommentsAndStrings(src)
+    for (const local of locals) {
+      for (const m of code.matchAll(new RegExp(`(?<![\\w$.])${local.replace(/\$/g, "\\$")}\\s*\\.\\s*publish\\s*\\(`, "g"))) {
+        out.push(`${serverModuleId(e.path)}:${code.slice(0, m.index).split("\n").length}: ${local}.publish(…)`)
+      }
+    }
+  }
+  return out
+}
+
 // ───────────────────────────── server entry ─────────────────────────────
 
 export const SERVER_ENTRY_PATH = "/.server-entry.ts"
 /** The SDK's app-config placeholder (src/server/auth/appConfig.ts) — the compile overrides it in the file map
- *  with the project's real values (project files win over SDK files), so `auth.model.user()` and friends see
+ *  with the project's real values (project files win over SDK files), so an SDK module that imports it sees
  *  app.json as an ordinary import. */
 export const APP_CONFIG_PATH = "/__sdk/server/auth/appConfig.ts"
 
 /** Compile-time manifest embedded in the server bundle (validators land here — see serverTypes.ts). */
 export type ServerManifest = {
   modules: Record<string, ServerExport[]>
-  /** endpoint id → JSON-schema-ish param list (filled by the TS-checker pass; absent = unvalidated). */
+  /** endpoint id → JSON-schema-ish param list (filled by the TS-checker pass; absent = unvalidated).
+   *  A channel id → the parameters of its `groupBy` (what the app passes to `subscribe`). */
   params?: Record<string, unknown[]>
-  /** The `app.json` subset the server runtime reads (name, auth providers); the bundle itself gets it as the
+  /** The `app.json` subset the server runtime reads (the app's name); the bundle itself gets it as the
    *  compiled-in `appConfig` module (APP_CONFIG_PATH). */
   app?: AppConfig
-  /** Some server file references the `auth` global: the runner then resolves a device session on every
-   *  request (minting one on first contact). Projects that never touch `auth` pay nothing. */
-  usesAuth?: boolean
 }
 
 /** The synthetic entry: imports every export by name (chisel has no namespace imports) and registers
@@ -196,12 +241,15 @@ export type CompileServerOptions = {
   /** Derive per-endpoint argument validators from the TS parameter types (serverTypes.ts) and embed
    *  them in the manifest. Default true; throws `EndpointTypeError` on non-JSON parameter types. */
   validate?: boolean
+  /** The TypeScript the validators are derived with, for a caller that brings its own (the CLI takes
+   *  the project's); absent = the `typescript` package this module can import. */
+  typescript?: typeof import("typescript")
   /** Precomputed param schemas to embed instead of deriving them. */
   params?: Record<string, unknown[]>
   /** Server bundles are readable by default (stack traces in the server console). */
   minify?: boolean
   sourcemap?: boolean
-  /** The project's `app.json` (name + auth providers) — embedded in the manifest and exposed to the bundle. */
+  /** The project's `app.json` subset (its name) — embedded in the manifest and exposed to the bundle. */
   app?: AppConfig
 }
 
@@ -224,12 +272,11 @@ export const compileServerBundle = async (opts: CompileServerOptions): Promise<{
   }
   let params = opts.params
   if (!params && opts.validate !== false) {
-    const derived = await deriveEndpointParams(opts.entries, modules)
+    const derived = await deriveEndpointParams(opts.entries, modules, opts.typescript)
     for (const w of derived.warnings) console.warn(`warning: ${w}`)
     params = derived.params
   }
-  const usesAuth = opts.entries.some(e => e.type === "text" && isServerPath(e.path) && /\bauth\s*\./.test(blankCommentsAndStrings(e.text ?? "")))
-  const manifest: ServerManifest = { modules: Object.fromEntries(Object.entries(modules).map(([p, ex]) => [serverModuleId(p), ex])), params, app: opts.app, usesAuth }
+  const manifest: ServerManifest = { modules: Object.fromEntries(Object.entries(modules).map(([p, ex]) => [serverModuleId(p), ex])), params, app: opts.app }
   if (opts.app) files[APP_CONFIG_PATH] = `export const app = ${JSON.stringify(opts.app)}\n`
   files[SERVER_ENTRY_PATH] = serverEntrySource(modules, manifest)
   const { code } = await bundleProjectWithMap(