@unoverse-platform/studio 0.1.0

package/vendor/sdk/lib/render.tsx

@@ -0,0 +1,178 @@
+/**
+ * ════════════════════════════════════════════════════════════════════════════
+ *  THE DISPATCHER: UnoverseNode → React.   ⛔ READ BEFORE EDITING ⛔
+ * ════════════════════════════════════════════════════════════════════════════
+ *
+ *  THIS FILE RENDERS NOTHING. It only WALKS the tree and DISPATCHES `node.type`
+ *  to a primitive component in ./primitives. There is NOT A SINGLE raw element
+ *  here — no `<div>`, `<span>`, `<button>`, `<img>`, `<input>`, `<svg>`. If you
+ *  are about to write one, STOP: it belongs in ./primitives. This is enforced by
+ *  test/dispatcher-only.test.mjs (the build fails if a raw element appears here),
+ *  so the engine/primitive split can't silently rot — which is exactly how
+ *  `Button` (and its styling logic) kept leaking back into the dispatcher.
+ *
+ *  THE FRAMEWORK IN ONE SENTENCE: this SDK is a FIXED, GENERIC interpreter. ALL
+ *  UX is built in DATA (rx/ definitions + the served theme) — an author creates
+ *  ANY interface WITHOUT editing this SDK. (See FRAMEWORK.md.)
+ *
+ *  WHERE THINGS LIVE:
+ *    • ./render     — this dispatcher (control flow: visibleWhen, Each, slots) ONLY.
+ *    • ./primitives — EVERY primitive (Box/Text/Image/Button/Icon/Skeleton/Input/
+ *                     Markdown/Unknown) + the shared per-element chrome.
+ *    • ./style      — the style + animation interpreter (styleToCss/keyframesCss).
+ *
+ *  Two laws (govern all three files + the whole package):
+ *    LAW 1 — OWN ZERO STYLE VALUES. No hex/px/rem/em/recipes; resolve token NAMES
+ *            against the SERVED theme. Enforced by test/golden-rule.test.mjs.
+ *    LAW 2 — OWN ZERO UX SHAPE. A primitive renders ONE generic element, nothing
+ *            about a specific UX. A composer/card/loader is a LAYOUT — compose it
+ *            in a DEFINITION. Never a per-UX primitive or per-UX config.
+ *
+ *  Need something the vocab can't express? Prefer extending the generic interpreter
+ *  ONCE (a new style-vocab key in ./style, a new model projection) over a primitive.
+ *  You almost never need to touch this file — build it in rx/ first.
+ * ════════════════════════════════════════════════════════════════════════════
+ */
+import type { ReactNode } from "react";
+import type { ActionSpec, ResolvedTheme, UnoverseNode } from "./core";
+import { visible, selectCase } from "./core";
+import { BoxView, TextView, ImageView, ButtonView, UnknownView, SkeletonView, InputView, MarkdownView, IconView } from "./primitives";
+
+// The style + animation interpreter lives in ./style; re-exported so consumers keep
+// importing it from "./render".
+export { styleToCss, keyframesCss } from "./style";
+
+// An action is a bare string (→ workflow) or a declarative envelope (§2e-3). The
+// binding layer (streamed.tsx) interprets it; primitives just forward node.action.
+/** Instance context riding with a bubbled server action — WHICH component fired and its
+ *  current slice, so the channel can forward the submitted state (e.g. a wizard's answers)
+ *  without reaching into the store. Pure transport metadata; the SDK interprets none of it. */
+export interface ActionMeta {
+  chatId?: string;
+  nodeId?: string;
+  state?: Record<string, unknown>;
+}
+
+export type ActionHandler = (action: string | ActionSpec, data: Record<string, unknown>, meta?: ActionMeta) => void;
+
+/**
+ * Resolves a `ComponentSlot` node against the store (provided by the template
+ * renderer). Returns the rendered leaves (or the slot's fallback). Components
+ * don't use slots, so this is undefined on the component render path.
+ */
+export type SlotResolver = (node: UnoverseNode, key?: React.Key) => ReactNode;
+
+/** A usable appWidth is CSS ("360px", "min(50vw, 760px)") — an UNRESOLVED size name
+ *  has no digits; treat it as absent rather than emitting invalid CSS. */
+export const cssWidth = (w: unknown): string | undefined => (typeof w === "string" && /\d/.test(w) ? w : undefined);
+
+export function renderNode(
+  node: UnoverseNode,
+  data: Record<string, unknown>,
+  onAction: ActionHandler | undefined,
+  theme: ResolvedTheme,
+  key?: React.Key,
+  slot?: SlotResolver,
+): ReactNode {
+  // visibleWhen — conditional visibility (§2e-3). A bare field name is a truthiness test
+  // (an empty array counts as empty); an object is a `Condition` (eq/ne/in, or truthy) so
+  // one field can drive tabs/wizard steps without a boolean per state. The predicate is
+  // shared with `Switch` and `style.when` (core/conditions.ts) — one state semantics.
+  if (node.visibleWhen != null && !visible(node.visibleWhen, data)) return null;
+
+  // `skeleton: true` — the protocol's LOADING semantic: while the node's bound field has
+  // no data yet, render its Skeleton ghost IN PLACE (inside the node's own styled box, so
+  // the ghost occupies exactly the space the content will). Variant inferred from the
+  // node type; the ghost's entire look is theme data (LAW 1). This is a generic BEHAVIOR
+  // (no data yet → ghost), not a style or a UX shape — the one judgment only the
+  // renderer can make, since only it watches binds resolve over time.
+  if (node.skeleton) {
+    const field = node.bind?.value ?? node.bind?.src ?? node.bind?.items;
+    if (field && !visible(field, data)) {
+      const variant = node.type === "Image" ? "image" : node.type === "Each" ? "card" : "text";
+      return (
+        <BoxView key={key} node={{ type: "Box", style: node.style }} data={data} theme={theme}>
+          <SkeletonView variant={variant} theme={theme} />
+        </BoxView>
+      );
+    }
+  }
+
+  // STATE-OWNED SIZING (docs/design/05): a plain node's `appWidth` = an ALWAYS-OPEN
+  // panel (e.g. the core chat column). The ONE declared value both grows the app
+  // (computeAppWidth) and fixes the panel's box here — they can never disagree, and
+  // nothing elastic remains for a resize to land on. Slot panels are injected at their
+  // frame (template.tsx); a layout root never carries appWidth (guard-enforced).
+  const panelW = (node as { appWidth?: string }).appWidth;
+  if (panelW && node.type !== "ComponentSlot") {
+    const w = cssWidth(theme.appSize?.[panelW] ?? panelW);
+    if (w) node = { ...node, appWidth: undefined, style: { ...(node.style ?? {}), width: w, flex: "0 0 auto" } } as UnoverseNode;
+  }
+
+  // Store-backed / leaf primitives → dispatch to ./primitives.
+  if (node.type === "Skeleton") return <SkeletonView key={key} variant={node.variant} theme={theme} />;
+  if (node.type === "Icon") return <IconView key={key} name={node.bind?.name ? (data[node.bind.name] as string) : node.icon} style={node.style} theme={theme} />;
+  if (node.type === "Input") return <InputView key={key} node={node} data={data} theme={theme} onAction={onAction} />;
+  if (node.type === "Markdown") return <MarkdownView key={key} node={node} data={data} theme={theme} />;
+  if (node.type === "ComponentSlot" || node.type === "Timeline") return slot ? slot(node, key) : null;
+
+  // `Switch` — control flow: render EXACTLY ONE branch, the case matching `data[on]`
+  // (else `cases.default`, else nothing). The declarative whole-view swap (wizard step,
+  // inline↔focused) — mutually exclusive in one place, vs. a `visibleWhen` per branch. No
+  // wrapper element: it is transparent, like an `if`, delegating straight to the branch.
+  if (node.type === "Switch") {
+    const branch = selectCase(node, data);
+    return branch ? renderNode(branch, data, onAction, theme, key, slot) : null;
+  }
+
+  // `Each` — control flow: map a bound array (bind.items) → the `template` subtree once
+  // per item (that item as the data scope), inside the node's own container (a Box).
+  // A PRIMITIVE item (string/number — e.g. a `string[]` of follow-up questions) is exposed
+  // as `{ value: item }`, so the template binds `value` like any field; object items pass
+  // through unchanged. This is what lets an `Each` iterate a plain list of strings.
+  if (node.type === "Each") {
+    // Literal `items` fallback: a microapp component hardcodes its static option lists
+    // in the def (props exist only for state — UNOVERSE_AUTHORING.md). bind wins.
+    const src = node.bind?.items ? data[node.bind.items] : node.items;
+    const items = Array.isArray(src) ? src : [];
+    const tpl = node.template;
+    const scopeOf = (item: unknown): Record<string, unknown> =>
+      item != null && typeof item === "object" ? (item as Record<string, unknown>) : { value: item };
+    const rendered = tpl ? items.map((item, i) => renderNode(tpl, scopeOf(item), onAction, theme, i, slot)) : null;
+    return (
+      <BoxView key={key} node={node} data={data} theme={theme}>
+        {rendered}
+      </BoxView>
+    );
+  }
+
+  // Element primitives → dispatch. Children are rendered here (control flow) and handed down.
+  const kids = (node.children ?? []).map((c, i) => renderNode(c, data, onAction, theme, i, slot));
+  switch (node.type) {
+    case "Box":
+    case "Stack":
+    case "Row":
+    case "Column":
+      return (
+        <BoxView key={key} node={node} data={data} theme={theme}>
+          {kids}
+        </BoxView>
+      );
+    case "Text":
+      return <TextView key={key} node={node} data={data} theme={theme} />;
+    case "Image":
+      return <ImageView key={key} node={node} data={data} theme={theme} />;
+    case "Button":
+      return (
+        <ButtonView key={key} node={node} data={data} theme={theme} onAction={onAction}>
+          {kids}
+        </ButtonView>
+      );
+    default:
+      return (
+        <UnknownView key={key} node={node} theme={theme}>
+          {kids}
+        </UnknownView>
+      );
+  }
+}

package/vendor/sdk/lib/streamed.tsx

@@ -0,0 +1,65 @@
+/**
+ * Streaming binding: subscribe to the merge-state store and render the
+ * component instance, re-rendering when COMPONENT_INIT/COMPONENT_DATA merge in.
+ */
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+import { dispatchAction, type ComponentStore, type ResolvedTheme, type UnoverseClient } from "./core";
+import { UnoverseComponent } from "./UnoverseComponent";
+import type { ActionHandler } from "./render";
+
+/** Subscribe to a component instance in the store (re-renders on merge).
+ *  Snapshots THIS instance's slice (merge() gives it a fresh identity per merge),
+ *  so chunks for other components bail out in React instead of re-rendering everyone. */
+export function useUnoverseInstance(store: ComponentStore, chatId: string, nodeId: string) {
+  const subscribe = useCallback((cb: () => void) => store.subscribe(cb), [store]);
+  const data = useSyncExternalStore(
+    subscribe,
+    useCallback(() => store.get(chatId, nodeId), [store, chatId, nodeId]),
+  );
+  const type = useSyncExternalStore(
+    subscribe,
+    useCallback(() => store.getType(chatId, nodeId), [store, chatId, nodeId]),
+  );
+  return { type, data };
+}
+
+export interface StreamedUnoverseComponentProps {
+  client: UnoverseClient;
+  store: ComponentStore;
+  chatId: string;
+  nodeId: string;
+  onAction?: ActionHandler;
+  theme?: ResolvedTheme;
+  /** Neutral turn state merged into the component's data scope (e.g. `streaming`), so a
+   *  component can reflect it — like legacy passing `streamingState` to StreamingText. */
+  extraData?: Record<string, unknown>;
+  /** A surface's single occupant fills the surface — see UnoverseComponent.fill. */
+  fill?: boolean;
+}
+
+/** Resolves `type` from the store → its definition → renders with merged data. */
+export function StreamedUnoverseComponent({ client, store, chatId, nodeId, onAction, theme, extraData, fill }: StreamedUnoverseComponentProps) {
+  const { type, data } = useUnoverseInstance(store, chatId, nodeId);
+  // Interpret the action envelope (§2e-3): `setValue` writes THIS instance's slice
+  // locally (the ported `updateData`); any other type routes to the channel handler
+  // (the workflow). `then` chains. The component never sees the store directly.
+  const handleAction = useMemo<ActionHandler>(
+    () => (action, scope) =>
+      dispatchAction(action, scope, {
+        store,
+        chatId,
+        nodeId,
+        // Server actions carry the INSTANCE context (which component + its current slice)
+        // so the channel can forward the submitted state — e.g. a wizard's collected
+        // answers — with the action. Transport metadata only; nothing is interpreted here.
+        sendToServer: onAction ? (t, payload) => onAction(t, payload, { chatId, nodeId, state: store.get(chatId, nodeId) }) : undefined,
+      }),
+    [store, chatId, nodeId, onAction],
+  );
+  if (!type) return <div>waiting for COMPONENT_INIT…</div>;
+  // No focus/displayState injection: a component's inline/focused look is its OWN state,
+  // written via the `setValue` action into this slice and read via `visibleWhen` — the SDK
+  // hardcodes no focus concept (UNOVERSE_STATE_MODEL §2). It's just another data field.
+  const merged = extraData ? { ...data, ...extraData } : data;
+  return <UnoverseComponent client={client} uri={`unoverse://components/${type}`} data={merged} onAction={handleAction} theme={theme} fill={fill} />;
+}

package/vendor/sdk/lib/style.ts

@@ -0,0 +1,227 @@
+/**
+ * The style + animation INTERPRETER — neutral vocab → CSS, resolving token NAMES
+ * against a theme FETCHED from the server. ⛔ OWNS ZERO STYLE VALUES (no hex, no
+ * px/rem/em, no recipes); every value lives in rx/styles and is served. See
+ * FRAMEWORK.md and render.tsx's header. Enforced by test/golden-rule.test.mjs.
+ */
+import type { CSSProperties } from "react";
+import { resolveValue, matches, type ResolvedTheme, type StyleVariant } from "./core";
+
+const WEIGHTS: Record<string, number> = { normal: 400, medium: 500, semibold: 600, bold: 700 };
+
+// Resolution cache: style objects come from CACHED definitions, so they are
+// referentially stable across renders — resolving the same (style, theme) pair per
+// element per render (the interpreter's hot inner loop) is pure waste. Data-BOUND
+// styles ({{field}} bindings or `when` variants) resolve against the live data scope
+// and bypass the cache; the one-time dependency check is itself memoized per object.
+// WeakMaps throughout — nothing here pins a def or theme in memory.
+const styleCache = new WeakMap<ResolvedTheme, WeakMap<Record<string, unknown>, CSSProperties>>();
+const dataDependent = new WeakMap<Record<string, unknown>, boolean>();
+// Stable default so styleless nodes hit the cache instead of keying a fresh {} per call.
+const EMPTY_STYLE: Record<string, unknown> = Object.freeze({});
+
+function isDataDependent(s: Record<string, unknown>): boolean {
+  let dep = dataDependent.get(s);
+  if (dep === undefined) {
+    dep = Array.isArray(s.when) || JSON.stringify(s).includes("{{");
+    dataDependent.set(s, dep);
+  }
+  return dep;
+}
+
+/**
+ * Map the neutral style vocab → CSS, resolving token names against the theme. Unknown
+ * values pass through. When `data` is given, a style value that is a `{{field}}` binding
+ * is first resolved from the data scope (e.g. a bar's `height: "{{pct}}"` ← data.pct =
+ * "72%") — the data-driven twin of token resolution. This is what lets bar/progress
+ * charts be DATA (Box + Each), not a primitive: the producer supplies the proportion,
+ * the SDK authors nothing. (Same `{{...}}` resolver the action vocab uses.)
+ */
+export function styleToCss(s: Record<string, unknown> = EMPTY_STYLE, theme: ResolvedTheme, data?: Record<string, unknown>): CSSProperties {
+  if (!data || !isDataDependent(s)) {
+    let byStyle = styleCache.get(theme);
+    if (!byStyle) {
+      byStyle = new WeakMap();
+      styleCache.set(theme, byStyle);
+    }
+    const hit = byStyle.get(s);
+    if (hit) return hit;
+    const css = computeCss(s, theme, undefined);
+    byStyle.set(s, css);
+    return css;
+  }
+  return computeCss(s, theme, data);
+}
+
+function computeCss(s: Record<string, unknown>, theme: ResolvedTheme, data?: Record<string, unknown>): CSSProperties {
+  if (data) {
+    const resolved: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(s)) resolved[k] = typeof v === "string" && v.includes("{{") ? resolveValue(v, data) : v;
+    s = resolved;
+    // `when` — data-driven style variants (the generalization of `style.disabled`). Each
+    // entry whose `Condition` holds against the data scope merges its `apply` OVER the
+    // base (later wins), so one element restyles by state instead of being cloned under
+    // opposite `visibleWhen`s. Same `matches()` predicate as visibleWhen/Switch. Folded
+    // here (render-time, like the {{}} pass); interaction states stay injected (chrome).
+    if (Array.isArray(s.when)) {
+      let merged: Record<string, unknown> = { ...s };
+      delete merged.when;
+      for (const variant of s.when as StyleVariant[]) {
+        if (variant && matches(variant, data)) merged = { ...merged, ...(variant.apply ?? {}) };
+      }
+      s = merged;
+    }
+  }
+  const css: CSSProperties = {};
+  const space = (v: string) => theme.space[v] ?? v;
+  // Resolve a dimension: a `space.*` scale step (e.g. "8" → 2rem) → its value; `full` → 100%;
+  // else pass through. ONE scale for spacing AND element sizes (Tailwind-style w-5/p-5).
+  const dim = (v: unknown) => theme.space[v as string] ?? (v === "full" ? "100%" : (v as CSSProperties["width"]));
+
+  if (s.width != null) css.width = dim(s.width);
+  if (s.height != null) css.height = dim(s.height);
+  if (s.maxWidth != null) css.maxWidth = dim(s.maxWidth) as CSSProperties["maxWidth"];
+  if (s.minWidth != null) css.minWidth = dim(s.minWidth) as CSSProperties["minWidth"];
+  if (s.minHeight != null) css.minHeight = dim(s.minHeight) as CSSProperties["minHeight"];
+  if (s.maxHeight != null) css.maxHeight = dim(s.maxHeight) as CSSProperties["maxHeight"];
+  if (s.flex != null) css.flex = s.flex as CSSProperties["flex"];
+  if (s.position) css.position = s.position as CSSProperties["position"];
+  if (s.inset != null) css.inset = s.inset as CSSProperties["inset"];
+  // Edge offsets (with `position`) — generic positioning, e.g. a bottom-anchored overlay
+  // panel that floats above without pushing siblings. Resolve like any dimension (`full`→100%).
+  if (s.top != null) css.top = dim(s.top) as CSSProperties["top"];
+  if (s.right != null) css.right = dim(s.right) as CSSProperties["right"];
+  if (s.bottom != null) css.bottom = dim(s.bottom) as CSSProperties["bottom"];
+  if (s.left != null) css.left = dim(s.left) as CSSProperties["left"];
+  if (s.zIndex != null) css.zIndex = s.zIndex as CSSProperties["zIndex"];
+  if (s.direction) {
+    css.display = "flex";
+    css.flexDirection = s.direction as CSSProperties["flexDirection"];
+  }
+  // `wrap` — flex-wrap, so a row of content-width items (e.g. FAQ chips, tag pills) sits
+  // side-by-side when there's room and wraps to the next line when there isn't. Generic
+  // layout vocab (any wrapping flex container); the value ("wrap"/"nowrap") is served/literal.
+  if (s.wrap) css.flexWrap = s.wrap as CSSProperties["flexWrap"];
+  if (s.gap) css.gap = space(s.gap as string);
+  if (s.padding) css.padding = Array.isArray(s.padding) ? (s.padding as string[]).map(space).join(" ") : space(s.padding as string);
+  if (s.margin) css.margin = Array.isArray(s.margin) ? (s.margin as string[]).map(space).join(" ") : space(s.margin as string);
+  if (s.display) css.display = s.display as CSSProperties["display"];
+  // `container` — establish a container-query context (e.g. "inline-size") so descendants
+  // can respond to THIS element's width via `hideBelow` (component-relative responsiveness,
+  // correct for SDUI: the component reacts to its slot, not the page viewport). Value served.
+  if (s.container) (css as Record<string, unknown>).containerType = s.container;
+  // `columns` → an equal-width CSS grid (generic layout; the welcome card grid uses it).
+  if (s.columns) {
+    css.display = "grid";
+    css.gridTemplateColumns = `repeat(${s.columns}, minmax(0, 1fr))`;
+    // Pack rows at the top. Without this, a columns-grid inside a flex:1 panel
+    // inherits CSS's default align-content:stretch and distributes the panel's
+    // leftover height BETWEEN rows — the phantom vertical gap between card rows.
+    css.alignContent = "start";
+  }
+  if (s.cursor) css.cursor = s.cursor as CSSProperties["cursor"];
+  if (s.align) css.alignItems = s.align === "start" ? "flex-start" : (s.align as CSSProperties["alignItems"]);
+  if (s.justify) css.justifyContent = s.justify as CSSProperties["justifyContent"];
+  // Explicit text alignment (inherited by children) — needed because a Button's
+  // user-agent stylesheet centers text, which flex `align` can't undo on wrapped lines.
+  if (s.textAlign) css.textAlign = (s.textAlign === "start" ? "left" : s.textAlign) as CSSProperties["textAlign"];
+  // Generic transform passthrough (values are DATA, e.g. a hover lift) — the SDK maps, never authors.
+  if (s.transform) css.transform = s.transform as CSSProperties["transform"];
+  if (s.background) css.background = theme.color[s.background as string] ?? (s.background as string);
+  // `radial` — a neutral dial/gauge fill: a `fill` token sweeps from 0 to `at` (a value
+  // or {{field}} binding, e.g. "72%"), the rest is the `track` token. The WEB realization
+  // is a conic-gradient; a native channel maps the same neutral intent to an arc. Authors
+  // ZERO values — both colours are served tokens, the stop is data. Enables radial gauges
+  // as DATA (a circular Box), not a primitive.
+  if (s.radial) {
+    const r = s.radial as { fill?: string; track?: string; at?: unknown };
+    const col = (t?: string) => (t ? (theme.color[t] ?? t) : "transparent");
+    const at = r.at != null ? String(resolveValue(r.at, data ?? {})) : "0%";
+    css.background = `conic-gradient(${col(r.fill)} ${at}, ${col(r.track)} 0)`;
+  }
+  // A border value → `<width> solid <color>`. `"subtle"` = thin subtle; an optional
+  // leading width token gives a thicker rule, e.g. `"thick action.primary"`.
+  const borderVal = (raw: string) => {
+    const parts = raw.split(" ");
+    const [wTok, cTok] = parts.length > 1 ? parts : ["thin", parts[0]];
+    const width = theme.borderWidth[wTok] ?? wTok;
+    const color = theme.color[`border.${cTok}`] ?? theme.color[cTok] ?? cTok;
+    return `${width} solid ${color}`;
+  };
+  if (s.border === "none") css.border = "none";
+  else if (s.border) css.border = borderVal(s.border as string);
+  // Per-side borders (a header rule, a hover edge-accent) — no fake divider Box needed.
+  if (s.borderTop) css.borderTop = borderVal(s.borderTop as string);
+  if (s.borderRight) css.borderRight = borderVal(s.borderRight as string);
+  if (s.borderBottom) css.borderBottom = borderVal(s.borderBottom as string);
+  if (s.borderLeft) css.borderLeft = borderVal(s.borderLeft as string);
+  // `outline` — pass-through (e.g. "none" to drop the input focus ring inside a pill).
+  if (s.outline != null) css.outline = s.outline as CSSProperties["outline"];
+  if (s.shadow) css.boxShadow = theme.shadow[s.shadow as string] ?? (s.shadow as string);
+  const rad = (v: string) => theme.radius[v] ?? v;
+  if (s.radius) css.borderRadius = rad(s.radius as string);
+  // Per-corner radius (a chat bubble squares the corner toward its sender).
+  if (s.radiusTopLeft) css.borderTopLeftRadius = rad(s.radiusTopLeft as string);
+  if (s.radiusTopRight) css.borderTopRightRadius = rad(s.radiusTopRight as string);
+  if (s.radiusBottomLeft) css.borderBottomLeftRadius = rad(s.radiusBottomLeft as string);
+  if (s.radiusBottomRight) css.borderBottomRightRadius = rad(s.radiusBottomRight as string);
+  if (s.overflow) css.overflow = s.overflow as CSSProperties["overflow"];
+  if (s.fit) css.objectFit = s.fit as CSSProperties["objectFit"];
+  if (s.font && theme.text[s.font as string]) Object.assign(css, theme.text[s.font as string]);
+  if (s.weight) css.fontWeight = WEIGHTS[s.weight as string] ?? (s.weight as CSSProperties["fontWeight"]);
+  // `lineHeight` — override the text style's line-height (e.g. tighten a single-line
+  // card title). Applied AFTER `font` so it wins. Resolves a lineHeight token (tight/…).
+  if (s.lineHeight != null) css.lineHeight = (theme.lineHeight[s.lineHeight as string] ?? s.lineHeight) as CSSProperties["lineHeight"];
+  if (s.color) css.color = theme.color[s.color as string] ?? (s.color as string);
+  // `transition` — smooth state changes (e.g. hover). The value is authored in the
+  // definition (e.g. "all 150ms ease"); the SDK passes it through, authoring nothing.
+  if (s.transition) css.transition = s.transition as CSSProperties["transition"];
+  // Animation — GENERIC vocab. `animation` names a served keyframe (theme.keyframes,
+  // injected once via keyframesCss); timing comes from the definition. The SDK authors
+  // no motion values, and there is NO per-animation primitive — any animated UX is data.
+  if (s.animation) {
+    const a = s.animation as { name: string; duration?: string; easing?: string; iteration?: string };
+    css.animation = `uno-${a.name} ${a.duration ?? ""} ${a.easing ?? ""} ${a.iteration ?? "infinite"}`.replace(/\s+/g, " ").trim();
+  }
+  if (s.animationDelay != null) css.animationDelay = s.animationDelay as string;
+  return css;
+}
+
+/**
+ * Serialize a resolved CSSProperties object → a CSS declaration string ("a-b:v;…").
+ * `important` is needed for injected state rules (hover/active): the base style is
+ * applied INLINE, and an inline style beats any class selector — so a `:hover` rule
+ * can only override it with `!important`.
+ */
+export function cssDecls(css: CSSProperties, important = false): string {
+  const flag = important ? " !important" : "";
+  return Object.entries(css)
+    .map(([k, v]) => `${k.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase())}:${v}${flag}`)
+    .join(";");
+}
+
+/**
+ * Serialize the SERVED keyframes (theme.keyframes ← rx/styles/semantic/keyframes.json)
+ * into a CSS string, injected ONCE per render root (<style>). This authors zero values —
+ * it only structures DATA into `@keyframes uno-<name>{ <stop>{ <prop>:<val> } }`. Adding a
+ * new animation = adding a keyframe to rx/ + a `style.animation` ref in a definition. No
+ * SDK edit, no new primitive. Keyframe decls use real CSS prop names (transform, opacity…).
+ */
+export function keyframesCss(theme: ResolvedTheme): string {
+  const hit = keyframesCache.get(theme);
+  if (hit !== undefined) return hit;
+  const kf = (theme.keyframes ?? {}) as Record<string, Record<string, Record<string, string>>>;
+  const css = Object.entries(kf)
+    .map(
+      ([name, stops]) =>
+        `@keyframes uno-${name}{${Object.entries(stops)
+          .map(([stop, decls]) => `${stop}{${Object.entries(decls).map(([p, v]) => `${p}:${v}`).join(";")}}`)
+          .join("")}}`,
+    )
+    .join("");
+  keyframesCache.set(theme, css);
+  return css;
+}
+
+// Pure function of the theme (stable per fetch) — serialize once, not per component render.
+const keyframesCache = new WeakMap<ResolvedTheme, string>();