@unoverse-platform/studio 0.1.0

package/vendor/sdk/lib/template.tsx

@@ -0,0 +1,521 @@
+/**
+ * <StreamedUnoverseTemplate> — renders a TEMPLATE definition (the layout) and
+ * fills its ComponentSlots from the store's timeline.
+ *
+ * A template owns nothing (UNOVERSE_SPEC.md §2e-0): it reads the shared state
+ * and arranges what it finds. This component is that arrangement —
+ *   - reads the template recipe by URI (resources/read, via the client),
+ *   - subscribes to the store so it re-renders as components stream in,
+ *   - resolves each ComponentSlot against the timeline and renders the matched
+ *     leaves with the SAME StreamedUnoverseComponent used everywhere else.
+ *
+ * This slice handles ComponentSlot + Skeleton (Tier-1, e.g. KeyService). The
+ * chat primitives (Conversation/Input/…) come in later slices.
+ */
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore, type CSSProperties, type ReactNode } from "react";
+import { dispatchAction, type ComponentStore, type ResolvedTheme, type UnoverseClient, type UnoverseDefinition, type UnoverseNode } from "./core";
+import { renderNode, styleToCss, keyframesCss, cssWidth, type ActionHandler, type SlotResolver } from "./render";
+import { StreamedUnoverseComponent } from "./streamed";
+import { useUnoverseTheme, ensureFontStylesheets } from "./theme";
+import { IsolatedRoot } from "./isolate";
+import { useVoiceService, type UseVoiceServiceConfig } from "./voice";
+
+export interface StreamedUnoverseTemplateProps {
+  client: UnoverseClient;
+  store: ComponentStore;
+  /** e.g. "unoverse://templates/KeyService" */
+  uri: string;
+  onAction?: ActionHandler;
+  theme?: ResolvedTheme;
+  /** Channel overrides for the template's declared props (e.g. per-tenant logoUrl/brandName).
+   *  Merged OVER the definition's own `props` defaults into the root data scope. */
+  props?: Record<string, unknown>;
+  /** Render inside a Shadow DOM for full CSS isolation (default true). See UnoverseComponent. */
+  isolate?: boolean;
+  /** The `voice` NATIVE SERVICE config (UNOVERSE_SPEC §2e-1). Present ONLY for a
+   *  `service: "voice"` app — the host supplies the connection identity (apiUrl/wsUrl/
+   *  token/session) it already holds; the renderer OWNS the service so every host is
+   *  identical. Absent → the service is inert (no mic/WS ever opens). This is the ONE
+   *  shared home for the voice buttons: `startCall`/`endCall`/`toggleMute` are answered
+   *  HERE, not hand-wired per host (that drift is what broke the demo's Start Call). */
+  voice?: UseVoiceServiceConfig;
+}
+
+/** Inert voice config for non-voice templates — the hook is called unconditionally
+ *  (rules of hooks) but nothing opens until a `startCall` this template never fires.
+ *  No `store` → not a producer, so it writes no callState into ordinary templates. */
+const INERT_VOICE: UseVoiceServiceConfig = {
+  apiUrl: "",
+  session: { userId: "", conversationId: "", workflowId: "", targetTriggerNode: "" },
+};
+
+/** The author's declared prop defaults (def.props[k].default) → a flat data object. Content, not policy. */
+function propDefaults(props?: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(props ?? {})) {
+    if (v && typeof v === "object" && "default" in (v as Record<string, unknown>)) {
+      out[k] = (v as { default: unknown }).default;
+    }
+  }
+  return out;
+}
+
+/** Format a turn timestamp as relative copy ("just now" / "5 min ago"). Neutral
+ *  projection of a model value (like `text`), not UX policy. Mirrors legacy
+ *  ChatHistoryItem.formatRelativeTime. Empty string when unstamped. */
+function formatRelative(ts?: number): string {
+  if (!ts) return "";
+  const diff = Math.floor((Date.now() - ts) / 1000);
+  if (diff < 60) return "just now";
+  if (diff < 3600) return `${Math.floor(diff / 60)} min ago`;
+  if (diff < 86400) return `${Math.floor(diff / 3600)} hr ago`;
+  return new Date(ts).toLocaleDateString();
+}
+
+/**
+ * Walk a template tree and collect every VIEW a reaction surface claims — the `eq`
+ * value of each `ComponentSlot.select.where { field: "defaultState" }`. State-selected
+ * UI (STATE_MODEL §5b): a component instance renders in exactly ONE placeholder. If a
+ * surface shows a given view, the conversation flow (the `inline` placeholder) must NOT
+ * also render instances in that view — else the same instance paints twice. A view no
+ * surface claims is absent from this set, so it stays in the flow (the fallback).
+ * Exported for testing.
+ */
+export function collectSurfacedViews(node: unknown, out: Set<string> = new Set()): Set<string> {
+  if (Array.isArray(node)) {
+    for (const n of node) collectSurfacedViews(n, out);
+    return out;
+  }
+  if (!node || typeof node !== "object") return out;
+  const n = node as Record<string, unknown>;
+  const sel = n.select as { where?: { field?: string; eq?: unknown } } | undefined;
+  if (n.type === "ComponentSlot" && sel?.where?.field === "defaultState" && typeof sel.where.eq === "string") {
+    out.add(sel.where.eq);
+  }
+  for (const v of Object.values(n)) if (v && typeof v === "object") collectSurfacedViews(v, out);
+  return out;
+}
+
+/**
+ * STATE-OWNED APP WIDTH (docs/design/05, layouts era): the app's outer width is
+ * declared by its LAYOUT's data, never the manifest. Two declaration points, both
+ * the neutral `appWidth` key (a named app size resolved via theme.appSize):
+ *   - a plain node's `appWidth` = an always-open panel (the core column) — the
+ *     layout's constant term.
+ *   - a ComponentSlot surface's `appWidth` = its panel width, counted only while
+ *     the surface is OCCUPIED (its view is the active state).
+ * The caller passes the ACTIVE layout (resolveActiveLayout) — layout swaps are
+ * whole-arrangement swaps, so the width is always the active layout's total.
+ * Activation is DERIVED, never stored. No declared width → undefined: the host
+ * keeps its own default, the sizing twin of "unmatched view falls back to inline".
+ * There is no other path.
+ */
+export function computeAppWidth(root: unknown, store: ComponentStore, appSize?: Record<string, string>): string | undefined {
+  // Resolve a declared width: a NAMED SIZE via theme.appSize (like any token), else raw
+  // CSS — guarded so an unresolvable name can never emit invalid CSS.
+  const rw = (w: unknown): string | undefined => cssWidth(typeof w === "string" ? (appSize?.[w] ?? w) : undefined);
+  const r = root as Record<string, unknown> | null | undefined;
+  const widths: string[] = [];
+  // Gather the tree's width-bearing nodes: always-open core panels and the reaction
+  // SURFACES (view → panel width).
+  const surfaces = new Map<string, string | undefined>();
+  const walk = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      for (const c of node) walk(c);
+      return;
+    }
+    if (!node || typeof node !== "object") return;
+    const n = node as Record<string, unknown> & { appWidth?: string; type?: string; select?: { where?: { field?: string; eq?: unknown } } };
+    if (n !== r) {
+      if (n.type === "ComponentSlot") {
+        const claim = n.select?.where;
+        if (claim?.field === "defaultState" && typeof claim.eq === "string") surfaces.set(claim.eq, rw(n.appWidth));
+      } else if (n.appWidth !== undefined) {
+        const w = rw(n.appWidth);
+        if (w) widths.push(w); // a plain panel (the core column) is ALWAYS open
+      }
+    }
+    for (const v of Object.values(n)) if (v && typeof v === "object") walk(v);
+  };
+  walk(r);
+  // ONE STATE AT A TIME (docs/design/04): the app = core + the ACTIVE state's panel —
+  // the most recently surfaced view. Panel combinations cannot exist, so the width is
+  // always one of a small known set, bounded by construction.
+  let active = "";
+  let activeAt = -1;
+  for (const turn of store.getResponses())
+    for (const p of turn.components) {
+      const { chatId, nodeId } = store.split(p);
+      const view = (store.get(chatId, nodeId) as Record<string, unknown>)?.defaultState;
+      if (typeof view === "string" && surfaces.has(view) && store.touchOf(p) > activeAt) {
+        activeAt = store.touchOf(p);
+        active = view;
+      }
+    }
+  const activePanel = active ? surfaces.get(active) : undefined;
+  if (activePanel) widths.push(activePanel);
+  if (!widths.length) return undefined;
+  return widths.length === 1 ? widths[0] : `calc(${widths.join(" + ")})`;
+}
+
+/**
+ * TEMPLATE LAYOUTS — name-sync (docs/design/05). A template with `layouts` is a set
+ * of full arrangements, the template-tier twin of a component's faces: the ACTIVE
+ * layout is the one whose NAME matches the latest surfaced component view, falling
+ * back to `defaultLayout` when nothing (or nothing matching) is surfaced. Same
+ * derivation as the active state — read off the store, never stored. Single-layout
+ * templates (`layouts` absent) resolve to `root`: the classic behavior, untouched.
+ */
+export function resolveActiveLayout(def: UnoverseDefinition | null | undefined, store: ComponentStore): UnoverseNode | undefined {
+  if (!def) return undefined;
+  const layouts = def.layouts;
+  if (!layouts) return def.root;
+  const { view } = resolveActiveView(def, store, new Set(Object.keys(layouts)));
+  return layouts[view] ?? layouts[def.defaultLayout ?? "main"] ?? def.root;
+}
+
+/**
+ * THE ACTIVE VIEW — the ONE derivation every consumer shares (docs/design/04 + the
+ * guest-control law). The latest surfaced component view among `validViews`, with
+ * PINNED enforcement: while a pinned layout's view is surfaced, a background arrival
+ * cannot displace it — only a guest write anywhere can. Layout choice and surface
+ * gating MUST both read this function: two loops that each pick "the latest view"
+ * disagree the moment pin overrides one of them — the layout renders view A while
+ * every surface inside it gates against view B, and the whole panel goes blank.
+ */
+export function resolveActiveView(
+  def: UnoverseDefinition | null | undefined,
+  store: ComponentStore,
+  validViews: Set<string>,
+): { view: string; byGuest: boolean } {
+  let view = "";
+  let at = -1;
+  let byGuest = false;
+  let pinnedView = "";
+  let pinnedAt = -1;
+  for (const turn of store.getResponses())
+    for (const p of turn.components) {
+      const { chatId, nodeId } = store.split(p);
+      const v = (store.get(chatId, nodeId) as Record<string, unknown>)?.defaultState;
+      if (typeof v !== "string" || !validViews.has(v)) continue;
+      const t = store.touchOf(p);
+      if (t > at) {
+        at = t;
+        view = v;
+        byGuest = store.interactionTouchOf(p) >= t;
+      }
+      if ((def?.layouts?.[v] as { pinned?: boolean } | undefined)?.pinned && t > pinnedAt) {
+        pinnedAt = t;
+        pinnedView = v;
+      }
+    }
+  if (pinnedView && view !== pinnedView && !byGuest) return { view: pinnedView, byGuest: false };
+  return { view, byGuest };
+}
+
+/** Resolve a ComponentSlot's `select` against the store → ordered pointers. Exported for testing. */
+export function selectPointers(store: ComponentStore, node: UnoverseNode): string[] {
+  const sel = node.select ?? {};
+  let pointers =
+    sel.from === "all"
+      ? store.getResponses().flatMap((r) => r.components)
+      : (store.latestResponse()?.components ?? []);
+
+  // `where` — select by COMPONENT STATE (the reaction contract, STATE_MODEL §5b): any
+  // component whose own slice matches, ordered newest state-write first so `limit: 1`
+  // = "most recent wins". The generic replacement for type-pinned surfaces — a
+  // template reacts to whatever component enters the state, never to a named type.
+  if (sel.where) {
+    const { field, eq, ne } = sel.where;
+    pointers = pointers.filter((p) => {
+      const { chatId, nodeId } = store.split(p);
+      const v = (store.get(chatId, nodeId) as Record<string, unknown>)[field];
+      return ne !== undefined ? v !== ne : v === eq;
+    });
+    pointers = [...pointers].sort((a, b) => store.touchOf(b) - store.touchOf(a));
+  }
+  if (sel.limit != null) pointers = pointers.slice(0, sel.limit);
+  return pointers;
+}
+
+export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme: themeProp, props, isolate = true, voice: voiceConfig }: StreamedUnoverseTemplateProps) {
+  const [def, setDef] = useState<UnoverseDefinition | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  // The voice native service lives HERE (shared), not in each host. Called every render
+  // (rules of hooks); inert until a `startCall` only a voice template has a button for.
+  // The audio WS lane travels WITH the SDK: derive it from the client's own server origin
+  // (same server that hosts /mcp + /stream + /ws/gravity), NEVER from the host — a host's
+  // `location.origin` is "null" in a sandboxed srcdoc iframe. Overrides any host wsUrl.
+  const voice = useVoiceService(
+    voiceConfig ? { ...voiceConfig, wsUrl: client.serverOrigin.replace(/^http/, "ws") } : INERT_VOICE,
+  );
+  // No theme passed → fetch from the server (the SDK owns zero token values). The
+  // theme REF comes from the definition itself: a template belongs to a client org,
+  // and that org names its theme — `<org>/light`. Wait for the def before fetching
+  // (null = no fetch) so the wrong theme never flashes.
+  const fetched = useUnoverseTheme(client, themeProp ? null : def ? (def.org ? `${def.org}/light` : "light") : null);
+  const theme = themeProp ?? fetched;
+  // Register the theme's webfonts (served DATA) at document level — see ensureFontStylesheets.
+  useEffect(() => ensureFontStylesheets(theme), [theme]);
+
+  // Re-render on STRUCTURE changes only (turns placed/completed, template state,
+  // lifecycle). COMPONENT_DATA merges don't move the timeline — the leaves subscribe
+  // to their own slices — so streaming chunks never re-walk the whole template tree.
+  // Stable subscribe fn: an inline arrow would tear down + re-create the subscription
+  // every render.
+  useSyncExternalStore(
+    useCallback((cb) => store.subscribe(cb), [store]),
+    useCallback(() => store.getStructureVersion(), [store]),
+  );
+
+  useEffect(() => {
+    let alive = true;
+    setDef(null);
+    setError(null);
+    client
+      .readDefinition(uri)
+      .then((d) => alive && setDef(d))
+      .catch((e) => alive && setError(String(e?.message ?? e)));
+    return () => {
+      alive = false;
+    };
+  }, [client, uri]);
+
+  // NAME-SYNC: the tree this template presents — the layout matching the latest
+  // surfaced component view (multi-layout templates), else the classic root. The
+  // resolved node is a stable per-def object, so downstream memos key off it.
+  const activeRoot = def ? resolveActiveLayout(def, store) : undefined;
+
+  // The set of VIEWS this template's reaction surfaces claim — computed per active
+  // layout: layout NAMES claim their view (name-sync) alongside the surfaces inside.
+  // The timeline uses it to keep a claimed instance out of the flow (one instance → one
+  // placeholder).
+  const surfacedViews = useMemo(() => {
+    const views = activeRoot ? collectSurfacedViews(activeRoot) : new Set<string>();
+    for (const name of Object.keys(def?.layouts ?? {})) views.add(name);
+    return views;
+  }, [activeRoot, def]);
+
+  // Loading/error hints carry NO styling — the SDK owns zero styles.
+  if (error) return <div>Unoverse error: {error}</div>;
+  if (!def || !theme) return <div>Loading {uri}…</div>;
+
+  // ONE action interpreter for the whole tree: template chrome runs the same
+  // `dispatchAction` (core/actions.ts) every leaf runs — `setTemplateValue` writes
+  // template state, `then` chains, anything else routes to the channel. Template
+  // chrome has NO component slice, so `setValue` here is an authoring error (it
+  // belongs on the component); the empty ids make that write inert.
+  const dispatch: ActionHandler = (action, data, meta) => {
+    // VOICE NATIVE-SERVICE actions are answered by the shared service (§2e-1) — never
+    // forwarded to the host/workflow. This is the single wiring point that makes every
+    // host behave identically; audio rides the /ws/gravity lane, not the component stream.
+    if (typeof action === "string") {
+      if (action === "startCall") return void voice.startCall();
+      if (action === "endCall") return void voice.endCall();
+      if (action === "toggleMute") return void voice.toggleMute();
+      // "back to chat" leaves the voice surface — tear the call down first, then let the
+      // host handle any navigation it owns (falls through).
+      if (action === "backToChat") voice.endCall();
+    }
+    // GUEST CLOSE from TEMPLATE CHROME: a ✕ on the layout itself (a rail/panel header —
+    // not inside a single card) fires the CloseButton atom's `setValue defaultState:"inline"`.
+    // Template chrome has no card slice to write, so that write would be inert; instead it
+    // means "un-surface the current view" → the store retracts every surface to base (the
+    // same reset a new turn runs). A card that closes ITSELF keeps using the plain component
+    // write (real ids), untouched. `then` still chains via dispatchAction below.
+    if (
+      action && typeof action === "object" &&
+      (action as { type?: string }).type === "setValue" &&
+      (action as { values?: { key?: string; value?: unknown }[] }).values?.some(
+        (v) => v.key === "defaultState" && v.value === "inline",
+      )
+    ) {
+      store.closeSurfaces();
+      return;
+    }
+    dispatchAction(action as Parameters<typeof dispatchAction>[0], (data ?? {}) as Record<string, unknown>, {
+      store,
+      chatId: "",
+      nodeId: "",
+      sendToServer: onAction ? (t, payload) => onAction(t, payload, meta) : undefined,
+    });
+  };
+
+  const leaf = (pointer: string, extraData?: Record<string, unknown>, fill?: boolean) => {
+    const { chatId, nodeId } = store.split(pointer);
+    return <StreamedUnoverseComponent key={pointer} client={client} store={store} chatId={chatId} nodeId={nodeId} onAction={dispatch} theme={theme} extraData={extraData} fill={fill} />;
+  };
+
+  // THE ACTIVE STATE (docs/design/04): a template is in exactly ONE state at a time —
+  // the most recently surfaced view ("" = the conversation/welcome base). DERIVED off
+  // the store, never stored. Exactly one reaction surface renders: the active state's.
+  //
+  // PINNED LAYOUTS — the guest-control law: a layout authored `"pinned": true` changes
+  // ONLY by the guest's hand. While a pinned view is surfaced, background arrivals
+  // (cards from later searches, streamed renders) cannot displace it (observed live:
+  // the panel flapped between a card rail and the composing page). It yields to a
+  // GUEST write anywhere (tap-to-focus, its own ✕), to its component leaving the view,
+  // or to a template swap. Authored in the layout file — the SDK only enforces it.
+  // SAME derivation as resolveActiveLayout (resolveActiveView) — the layout on screen
+  // and the state its surfaces gate against must NEVER come from two different loops.
+  const surfacedView = resolveActiveView(def, store, surfacedViews).view;
+
+  // ComponentSlot — filter the timeline to matching component pointers (KeyService).
+  const resolveSlot = (node: UnoverseNode, key?: React.Key): ReactNode => {
+    // ONE STATE AT A TIME: a reaction surface renders ONLY while its view IS the
+    // template's active state. Everything else is not part of this interface — its
+    // data is untouched and re-presents the moment its state is active again.
+    // Surfaces never stack; panel combinations cannot exist.
+    const claim = node.select?.where;
+    if (claim?.field === "defaultState" && typeof claim.eq === "string" && claim.eq !== surfacedView) {
+      return node.fallback ? renderNode(node.fallback, {}, dispatch, theme, key ?? "fallback") : null;
+    }
+    const pointers = selectPointers(store, node);
+    if (pointers.length === 0) {
+      return node.fallback ? renderNode(node.fallback, {}, dispatch, theme, key ?? "fallback") : null;
+    }
+    // `frame` — chrome that exists ONLY because the slot matched (fallback's twin).
+    // The frame subtree renders with a slot resolver that serves the outer slot's
+    // matches to any bare nested ComponentSlot — so a focus overlay is BORN when a
+    // component enters the state and DIES when it leaves (§5b: derived, not stored).
+    if (node.frame) {
+      // A SURFACE'S SINGLE OCCUPANT FILLS THE SURFACE (docs/design/05): a limit-1
+      // surface (detail panel, focus overlay) gives its occupant the frame's full
+      // height — the component's `height: "full"` finally has a definite container,
+      // with zero per-face styling. Multi-occupant surfaces (a rail) stay content-sized.
+      const fill = node.select?.limit === 1;
+      const innerSlot: SlotResolver = () => pointers.map((p) => leaf(p, undefined, fill));
+      // A panel declares its width ONCE (docs/design/05): `appWidth` grows the app
+      // (computeAppWidth) AND sizes the frame box here — the two can never disagree.
+      // Named sizes resolve via theme.appSize like any token; unresolvable → no width.
+      // `flex: 0 0 auto` — a panel is its declared width ALWAYS. A container that
+      // can't fit the sum clips at the edge; panels never compress into garbage.
+      const declared = (node as { appWidth?: string }).appWidth;
+      const appWidth = cssWidth(typeof declared === "string" ? (theme.appSize?.[declared] ?? declared) : undefined);
+      const frame = appWidth
+        ? ({ ...node.frame, style: { ...(node.frame.style ?? {}), width: appWidth, flex: "0 0 auto" } } as UnoverseNode)
+        : node.frame;
+      return renderNode(frame, store.getTemplateState() as Record<string, unknown>, dispatch, theme, key ?? "frame", innerSlot);
+    }
+    return pointers.map((p) => leaf(p));
+  };
+
+  // Timeline — GENERIC iterator. Walks the timeline and renders the `user` / `assistant`
+  // DATA sub-tree per turn. Zero chat UX in the SDK: bubbles, alignment, structure all live
+  // in those sub-trees (rx/templates/chatlayout/*.json). The assistant sub-tree's ComponentSlot
+  // is scoped to THAT turn's components.
+  const resolveTimeline = (node: UnoverseNode, key?: React.Key): ReactNode => {
+    return (
+      <div key={key} style={styleToCss(node.style, theme)}>
+        {store.getTimeline().map((turn) => {
+          const sub = turn.role === "user" ? node.user : node.assistant;
+          if (!sub) return null;
+          // One instance → one placeholder (STATE_MODEL §5b). An instance whose active
+          // VIEW a reaction surface is showing is CLAIMED — the flow (the `inline`
+          // placeholder) must not render it too, or the same card paints twice. Instances
+          // in a view no surface claims stay here (the fallback). This is what makes "a
+          // component lifts into its surface" true instead of double-rendering it inline.
+          const shown =
+            turn.role === "assistant"
+              ? turn.components.filter((p) => {
+                  const { chatId, nodeId } = store.split(p);
+                  const view = (store.get(chatId, nodeId) as Record<string, unknown> | undefined)?.defaultState;
+                  return typeof view !== "string" || !surfacedViews.has(view);
+                })
+              : [];
+          // Slot scoped to this turn's UNCLAIMED components (assistant turns only).
+          const turnSlot: SlotResolver = (slotNode, k) => {
+            let ptrs = [...shown];
+            if (slotNode.select?.limit != null) ptrs = ptrs.slice(0, slotNode.select.limit);
+            if (ptrs.length === 0) return slotNode.fallback ? renderNode(slotNode.fallback, {}, dispatch, theme, k ?? "fb") : null;
+            // Pass the turn's streaming state into each component's scope so a streamed
+            // component (e.g. StreamingText) can stop its own loading dots when complete.
+            const streaming = turn.role === "assistant" && turn.streamingState === "streaming";
+            return ptrs.map((p) => leaf(p, { streaming }));
+          };
+          // Data scope per turn = author's static data (avatarUrl, thinkingText…)
+          // + NEUTRAL projections of the timeline model. The SDK exposes facts, never
+          // UX policy: `text` (user message), `streaming` (the turn's streamingState),
+          // `empty` (no components yet). It does NOT decide "show a thinking indicator" —
+          // the definition composes that from `streaming` + `empty` (nested visibleWhen =
+          // AND). Static author data is forwarded verbatim; the SDK interprets none of it.
+          const time = formatRelative(turn.createdAt);
+          const data =
+            turn.role === "user"
+              ? { ...(node.userData ?? {}), text: turn.text, time }
+              : {
+                  ...(node.assistantData ?? {}),
+                  time,
+                  streaming: turn.streamingState === "streaming",
+                  // `empty`/`active` count only UNCLAIMED components: a turn whose sole card
+                  // lifted into a surface goes inactive (the definition hides it) rather than
+                  // leaving an empty avatar behind; a still-streaming turn stays active.
+                  empty: shown.length === 0,
+                  // `active` = in progress OR has visible content. A completed-empty turn is
+                  // inactive → the definition hides it (legacy ChatHistoryItem null-returns).
+                  active: turn.streamingState === "streaming" || shown.length > 0,
+                };
+          return renderNode(sub, data, dispatch, theme, turn.id, turnSlot);
+        })}
+      </div>
+    );
+  };
+
+  // One resolver for all store-backed template primitives.
+  const resolve: SlotResolver = (node, key) =>
+    node.type === "Timeline" ? resolveTimeline(node, key) : resolveSlot(node, key);
+
+  // Root data scope = the author's declared prop defaults (logoUrl, brandName, suggestions…)
+  // + channel overrides + NEUTRAL conversation-level facts derived from the store (isEmpty/
+  // hasMessages). This is what lets the page AROUND the message list (header, welcome screen,
+  // suggestion cards) bind + show/hide — the whole-template counterpart of the per-turn scope
+  // Timeline injects. The SDK adds no UX policy: just author content + model projections.
+  const isEmpty = store.getTimeline().length === 0;
+  const rootData: Record<string, unknown> = {
+    ...propDefaults(def.props),
+    ...((def as { state?: Record<string, unknown> }).state ?? {}),
+    ...(props ?? {}),
+    // The active template's OWN state — one generic bag of the DEV's chosen keys (draft,
+    // openPanel, suggestions data, focusMode, voice call state, …). No per-feature
+    // projections; the engine knows no key names (UNOVERSE_STATE_MODEL §2).
+    ...store.getTemplateState(),
+    // Conversation-derived facts — READ OFF the timeline / lifecycle, never stored.
+    isEmpty,
+    hasMessages: !isEmpty,
+    surfacedView,
+    lifecycle: store.getLifecycle(),
+    isThinking: store.getLifecycle() === "thinking",
+    isStreaming: store.getLifecycle() === "thinking" || store.getLifecycle() === "streaming",
+  };
+
+  // Inject the served keyframes ONCE for this render root so any `style.animation` in a
+  // definition resolves (the SDK animates generically — no per-animation primitive).
+  // The wrapper applies the SERVED base render settings (theme.root — font-smoothing, etc.):
+  // `display: contents` keeps it out of layout while its inherited props cascade to the tree.
+  // The SDK authors only `display: contents` (structure); every value comes from theme.root.
+  // Isolated → theme.root on the shadow-root container (reliable cascade); else → display:contents.
+  const keyframes = <style>{keyframesCss(theme)}</style>;
+  // A layout root never carries `appWidth` (guard-enforced) — panels inside it do.
+  const rootNode = (activeRoot ?? def.root) as UnoverseNode;
+  const tree = renderNode(rootNode, rootData, dispatch, theme, undefined, resolve);
+  // A template is a SURFACE: its render-root fills the box the host gives it, so a root
+  // that declares `height: "full"` (DATA) can resolve. This only fills when the host's box
+  // is definite-height; when the host sizes to content the 100% resolves to content — so a
+  // content-sized app (fluidHeight:false) still wraps its component. The SDK adds no layout
+  // policy beyond "a template fills its container"; the template DATA owns everything else.
+  const surfaceRoot = { ...(theme.root as CSSProperties), height: "100%" };
+  if (isolate) {
+    return (
+      <IsolatedRoot rootStyle={surfaceRoot}>
+        {keyframes}
+        {tree}
+      </IsolatedRoot>
+    );
+  }
+  return (
+    <>
+      {keyframes}
+      <div style={{ display: "contents", ...surfaceRoot }}>{tree}</div>
+    </>
+  );
+}

package/vendor/sdk/lib/theme.ts

@@ -0,0 +1,55 @@
+/**
+ * useUnoverseTheme — fetch the RESOLVED theme from the MCP server by name.
+ *
+ * The SDK owns ZERO token values. The server owns the visual (apps/unoverse/
+ * rx/styles, resolved live) and serves it at `unoverse://theme/{name}`; this hook
+ * fetches it (cached in the client). A brand change in rx/styles is refresh-only
+ * — there is no baked theme in this bundle to rebuild (UNOVERSE_SPEC §2d-1).
+ */
+import { useEffect, useState } from "react";
+import type { ResolvedTheme, UnoverseClient } from "./core";
+
+/**
+ * Ensure the theme's webfont stylesheets are loaded ONCE in the document head.
+ * `theme.fonts` is SERVED DATA (`fonts.stylesheets` in an org's styles) — the SDK
+ * authors no font choices, it just registers what the server serves. Fonts must live
+ * at document level: a shadow root cannot register @font-face, but faces declared in
+ * the document apply inside shadow trees via the font cascade.
+ */
+export function ensureFontStylesheets(theme: ResolvedTheme | null): void {
+  if (!theme?.fonts?.length || typeof document === "undefined") return;
+  for (const href of theme.fonts) {
+    if (document.head.querySelector(`link[data-unoverse-font="${CSS.escape(href)}"]`)) continue;
+    const link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = href;
+    link.setAttribute("data-unoverse-font", href);
+    document.head.appendChild(link);
+  }
+}
+
+/** Returns the resolved theme (null until the first fetch resolves).
+ *  `name: null` = don't fetch yet (the caller is still deriving the name — e.g. waiting
+ *  for the definition whose `org` names its pack's theme). An unknown name falls back to
+ *  the neutral `light` so a pack without a theme still renders. */
+export function useUnoverseTheme(client: UnoverseClient, name: string | null = "light"): ResolvedTheme | null {
+  const [theme, setTheme] = useState<ResolvedTheme | null>(null);
+  useEffect(() => {
+    if (!name) return;
+    let alive = true;
+    client
+      .readTheme(name)
+      .then((t) => alive && setTheme(t))
+      .catch(() => {
+        if (!alive || name === "light") return;
+        client
+          .readTheme("light")
+          .then((t) => alive && setTheme(t))
+          .catch(() => {});
+      });
+    return () => {
+      alive = false;
+    };
+  }, [client, name]);
+  return theme;
+}