@unoverse-platform/studio 0.1.101 → 0.1.102

package/vendor/sdk/appEngine.tsx

@@ -10,10 +10,13 @@
  */
 import { useEffect, useMemo, useRef, useState } from "react";
 import { postToEmbedHost } from "./mcpAppBridge";
+import { PageInterfaces, type Binding } from "./pageInterfaces";
 import {
   UnoverseClient,
   ComponentStore,
   StreamedUnoverseApp,
+  INERT_VOICE,
+  useVoiceService,
   useUnoverseConnection,
   useUnoverseTheme,
   computeAppWidth,
@@ -23,6 +26,7 @@ import {
   setAnalyticsDebug,
   type UseVoiceServiceConfig,
   type UnoverseDefinition,
+  type ActionMeta,
 } from "./lib";
 
 export interface AppConfig {
@@ -184,6 +188,48 @@ export function AppEngine(cfg: AppConfig) {
     return store.subscribe(report);
   }, [store, def, theme]);
 
+  // VOICE (§2e-1): a `service: "voice"` app runs the native voice service — which now lives
+  // in the shared renderer (StreamedUnoverseApp), identical to Studio. The host only
+  // supplies the connection identity it already holds; startCall/endCall/toggleMute are
+  // answered inside the renderer, so this host wires NO voice buttons. Absent → inert.
+  const voiceConfig = useMemo<UseVoiceServiceConfig | undefined>(
+    () =>
+      // THE SERVICE NEEDS NO WORKFLOW OF ITS OWN. It is the page's microphone, speaker and
+      // audio lane; a call names the workflow it runs (a page template's binding,
+      // UNOVERSE_HOST_PAGE.md rule 4), and an app with a binding lends it as the default.
+      binding.service === "voice"
+        ? {
+            // START_CALL REST triggers the workflow on the gateway (user token). The audio
+            // WS lane is derived by the SDK from the client's server origin (see the renderer)
+            // — the host passes NO wsUrl (its srcdoc `location.origin` is "null").
+            apiUrl: apiUrl ?? serverUrl,
+            getAccessToken: getAccessToken as UseVoiceServiceConfig["getAccessToken"],
+            session: {
+              userId: userId ?? "",
+              conversationId,
+              chatId: conversationId,
+              workflowId: binding.workflow ?? "",
+              targetTriggerNode: binding.trigger ?? "",
+            },
+            // Producer: writes callState/isMuted into TEMPLATE STATE so the voice states switch.
+            store,
+          }
+        : undefined,
+    [binding.service, binding.workflow, binding.trigger, apiUrl, serverUrl, getAccessToken, userId, conversationId, store],
+  );
+
+  // ONE CALL FOR THE PAGE. The service runs here, once, so the app and the page's own
+  // templates (an avatar in the navigation) start, follow and end the same call.
+  const voice = useVoiceService(
+    voiceConfig ? { ...voiceConfig, wsUrl: client.serverOrigin.replace(/^http/, "ws") } : INERT_VOICE,
+  );
+
+  // CONNECTED TO THE TASK UNTIL THE PAGE CLOSES. The avatar is a button that starts a task's
+  // workflow; from that press the page is in the task (its steps, its submit) until the task
+  // closes or the visitor leaves. Whether the workflow has a voice is its own business, so
+  // nothing here waits on a call (UNOVERSE_HOST_PAGE.md rule 4).
+  const [inTask, setInTask] = useState(false);
+
   // SDK's native connection: opens /stream, register_session, feeds the store. Outbound
   // sendMessage fires the workflow DIRECTLY (REST, user token) — no server broker.
   const conn = useUnoverseConnection(
@@ -197,9 +243,16 @@ export function AppEngine(cfg: AppConfig) {
       appId,
     },
     store,
-    // Open only once BOTH are ready: the user identity AND the manifest binding (read async).
-    // Avoids the transient "connection missing workflowId/userId/conversationId" warning.
-    { enabled: !!userId && !!binding.workflow, onAppSwitch: switchApp },
+    // Open once the user is known AND there is something to hear from: the app's own workflow,
+    // or a task the page is in. An app with no workflow (a website's page app) connects when the
+    // avatar starts a task and stays connected to it; nothing is held open while the visitor
+    // only reads.
+    {
+      enabled: !!userId && (!!binding.workflow || voice.state.isCallActive || inTask),
+      onAppSwitch: switchApp,
+      // A voice in the running workflow asks the page in: join its call, never start one.
+      onJoinCall: (workflowId) => void voice.joinCall(workflowId),
+    },
   );
 
   // STATUS TO THE HOST. In native-host mode the iframe owns the only real
@@ -225,39 +278,59 @@ export function AppEngine(cfg: AppConfig) {
     });
   }, [conn.isReady, conn.isConnected, conn.refusal, failure]);
 
-  // VOICE (§2e-1): a `service: "voice"` app runs the native voice service — which now lives
-  // in the shared renderer (StreamedUnoverseApp), identical to Studio. The host only
-  // supplies the connection identity it already holds; startCall/endCall/toggleMute are
-  // answered inside the renderer, so this host wires NO voice buttons. Absent → inert.
-  const voiceConfig = useMemo<UseVoiceServiceConfig | undefined>(
-    () =>
-      binding.service === "voice" && binding.workflow
-        ? {
-            // START_CALL REST triggers the workflow on the gateway (user token). The audio
-            // WS lane is derived by the SDK from the client's server origin (see the renderer)
-            // — the host passes NO wsUrl (its srcdoc `location.origin` is "null").
-            apiUrl: apiUrl ?? serverUrl,
-            getAccessToken: getAccessToken as UseVoiceServiceConfig["getAccessToken"],
-            session: {
-              userId: userId ?? "",
-              conversationId,
-              chatId: conversationId,
-              workflowId: binding.workflow,
-              targetTriggerNode: binding.trigger ?? "",
-            },
-            // Producer: writes callState/isMuted into TEMPLATE STATE so the voice states switch.
-            store,
-          }
-        : undefined,
-    [binding.service, binding.workflow, binding.trigger, apiUrl, serverUrl, getAccessToken, userId, conversationId, store],
-  );
+  // THE SPEC'S ANSWERS, AND NOTHING ELSE (UNOVERSE_MCP_COMPLETE_GUIDE.md, "How the SDK answers an
+  // elicitation"): while the server is ELICITING on this session, a component's `submit` answers
+  // `accept` with its slice and its `cancel` answers `cancel`. Every other action (a state it
+  // enters, a step, a tab) is the component's own and goes to the server as usual. Without a
+  // pending elicitation, a submit falls back to the data-plane `user_action` waiter (a workflow
+  // node waiting on a component). One way for every component, the app's and the page's alike.
+  const toServer = (t: string, data: Record<string, unknown>, meta?: ActionMeta) => {
+    const state = (meta?.state ?? data) as Record<string, unknown>;
+    if ((t === "submit" || t === "cancel") && conn.resolveElicitation(state, t === "cancel" ? "cancel" : "accept")) return;
+    conn.sendAction(t, {
+      componentNodeId: meta?.nodeId,
+      componentType: meta?.type,
+      // The component's OWN chatId is the TURN id — the waiting node execution is
+      // keyed `<turn>:<nodeId>`, not the conversation-level chatId.
+      componentChatId: meta?.chatId,
+      componentState: state,
+    });
+  };
+
+  // A PAGE TEMPLATE'S TASK, started from its avatar: the template's own workflow, run at its
+  // trigger over REST with the user's token, as any request to a workflow (§5a). `metadata.task`
+  // names the task its Task Runner loads. From here the page is in the task.
+  const startTask = async (b: Binding, task: string) => {
+    if (!b.workflow) return;
+    setInTask(true);
+    const token = getAccessToken ? await getAccessToken() : null;
+    fetch(`${apiUrl ?? serverUrl}/api/workflows/${b.workflow}/execute`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+      body: JSON.stringify({
+        input: {
+          message: "Start",
+          chatId: conversationId,
+          conversationId,
+          userId,
+          providerId: "gravity-ds",
+          metadata: { targetTriggerNode: b.trigger, workflowId: b.workflow, task },
+        },
+        conversationId,
+      }),
+    }).catch((e) => console.error("[unoverse] task start failed", e));
+  };
 
   return (
+    <>
+    {/* The page's own templates, drawn into its elements by this one runtime (pageInterfaces.tsx). */}
+    <PageInterfaces org={appId.split("/")[0]} client={client} voice={voice} appStore={store} toServer={toServer} startTask={startTask} />
     <StreamedUnoverseApp
       client={client}
       store={store}
       uri={`unoverse://apps/${appId}/definition`}
       voice={voiceConfig}
+      voiceService={voice}
       onAction={(action, data, meta) => {
         const t = typeof action === "string" ? action : (action as any)?.type;
         if (t === "close") {
@@ -312,24 +385,9 @@ export function AppEngine(cfg: AppConfig) {
           store.setDraft(typeof (data as any)?.text === "string" ? (data as any).text : "");
           return;
         }
-        // THE SPEC'S ANSWERS, AND NOTHING ELSE (UNOVERSE_MCP_COMPLETE_GUIDE.md, "How the SDK
-        // answers an elicitation"): while the server is ELICITING on this session, the
-        // component's `submit` answers `accept` with its slice and its `cancel` answers
-        // `cancel`. Every other action (a state it enters, a step, a tab) is the component's
-        // own and goes to the server as usual. Without a pending elicitation, a submit falls
-        // back to the data-plane `user_action` waiter (a workflow node waiting on a component).
-        if (!t) return;
-        const state = (meta?.state ?? data) as Record<string, unknown>;
-        if ((t === "submit" || t === "cancel") && conn.resolveElicitation(state, t === "cancel" ? "cancel" : "accept")) return;
-        conn.sendAction(t, {
-          componentNodeId: meta?.nodeId,
-          componentType: meta?.type,
-          // The component's OWN chatId is the TURN id — the waiting node execution is
-          // keyed `<turn>:<nodeId>`, not the conversation-level chatId.
-          componentChatId: meta?.chatId,
-          componentState: state,
-        });
+        if (t) toServer(t, data, meta);
       }}
     />
+    </>
   );
 }

package/vendor/sdk/lib/UnoverseComponent.tsx

@@ -13,7 +13,7 @@
  * holding. It never mattered to the component: the same `renderNode` walks the same
  * definition, and `setValue` writes the same instance either way.
  */
-import { useCallback, useEffect, useMemo, useState, useSyncExternalStore, type CSSProperties } from "react";
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore, type CSSProperties, type ReactNode } from "react";
 import { dispatchAction, matches, type ComponentStore, type ResolvedTheme, type UnoverseClient, type UnoverseDefinition } from "./core";
 import { renderNode, keyframesCss, type ActionHandler, type SlotResolver } from "./render";
 import { useUnoverseTheme, ensureFontStylesheets } from "./theme";
@@ -74,9 +74,22 @@ export interface UnoverseComponentProps {
    * container. Flow/rail instances stay content-sized (never set there).
    */
   fill?: boolean;
+  /**
+   * WHAT A `Place` IN THIS DEFINITION DRAWS. An app's places are filled by the screen
+   * (app.tsx); a place inside a component or template is filled by its host, which alone
+   * knows what belongs there (a fullscreen template's place holds the page's avatar).
+   * Without it a place draws nothing.
+   */
+  place?: (name: string) => ReactNode;
+  /**
+   * THE APP'S STATE, when it lives in another store (live source only). A template a website
+   * page draws keeps its own slice in its own store, and shares one app state with the rest
+   * of the page: it reads that state beneath its own values, and `setAppValue` writes there.
+   */
+  appStore?: ComponentStore;
 }
 
-export function UnoverseComponent({ client, uri, data, store, chatId, nodeId, extraData, onAction, theme, isolate = true, fill = false }: UnoverseComponentProps) {
+export function UnoverseComponent({ client, uri, data, store, chatId, nodeId, extraData, onAction, theme, isolate = true, fill = false, place, appStore }: UnoverseComponentProps) {
   const [def, setDef] = useState<UnoverseDefinition | null>(null);
   const [error, setError] = useState<string | null>(null);
   // A component's OWN view state (a tab, a step, an expanded face) moves by writing its own
@@ -88,6 +101,10 @@ export function UnoverseComponent({ client, uri, data, store, chatId, nodeId, ex
   // LIVE SOURCE. The hook runs either way (hooks cannot be conditional) and no-ops without a
   // store, so one component serves both paths without a wrapper deciding for it.
   const live = useUnoverseInstance(store, chatId, nodeId);
+  const appState = useSyncExternalStore(
+    useCallback((cb: () => void) => (appStore ? appStore.subscribe(cb) : () => {}), [appStore]),
+    useCallback(() => appStore?.getAppState(), [appStore]),
+  );
   // The SERVER-SENT address first: an org component's URI is org-qualified
   // (`unoverse://components/<org>/<name>`) and the bare type cannot rebuild it once two
   // orgs share a name. The rebuild-from-type stays as the fallback for events that
@@ -150,6 +167,7 @@ export function UnoverseComponent({ client, uri, data, store, chatId, nodeId, ex
               store,
               chatId: chatId ?? "",
               nodeId: nodeId ?? "",
+              appStore,
               // Server actions carry the INSTANCE context (which component + its current
               // slice) so the channel can forward the submitted state with the action.
               sendToServer: onAction
@@ -174,9 +192,41 @@ export function UnoverseComponent({ client, uri, data, store, chatId, nodeId, ex
             }
             onAction?.(action, payload, meta);
           },
-    [store, chatId, nodeId, onAction, live.type],
+    [store, chatId, nodeId, onAction, live.type, appStore],
   );
 
+  // ARROW KEYS STEP A TEMPLATE. A template's steps (the served stateTree: `on` + its
+  // substates) move with Left and Right while it holds the main place, through the same
+  // setValue its own Back and Next make, so the step is saved and reported exactly as a
+  // click would be. Forms (components) are left alone: their steps are confirmations.
+  // Typing in a field never steps.
+  const slice = store ? sourceData : localSlice;
+  useEffect(() => {
+    const d = def as (UnoverseDefinition & {
+      kind?: string;
+      stateTree?: { name: string; on?: string; states?: { name: string }[] }[];
+      statePlaces?: Record<string, string>;
+    }) | null;
+    if (d?.kind !== "template") return;
+    const face = String((slice as Record<string, unknown> | undefined)?.state ?? d.state?.state ?? "");
+    const tree = (d.stateTree ?? []).find((s) => s.name === face);
+    const steps = tree?.states?.map((s) => s.name) ?? [];
+    if (!tree?.on || steps.length < 2 || d.statePlaces?.[face] !== "main") return;
+    const on = tree.on;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "ArrowRight" && e.key !== "ArrowLeft") return;
+      const t = e.target as HTMLElement | null;
+      if (t && (t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName))) return;
+      const cur = String((slice as Record<string, unknown> | undefined)?.[on] ?? d.state?.[on] ?? steps[0]);
+      const i = steps.indexOf(cur) + (e.key === "ArrowRight" ? 1 : -1);
+      if (i < 0 || i >= steps.length) return;
+      e.preventDefault();
+      handleAction({ type: "setValue", values: [{ key: on, value: steps[i] }] }, {});
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [def, slice, handleAction]);
+
   // Loading/error hints carry NO styling — the SDK owns zero styles (tokens or hints).
   if (error) return <div>Unoverse error: {error}</div>;
   if (store && !live.type) return <div>waiting for COMPONENT_INIT…</div>;
@@ -186,7 +236,7 @@ export function UnoverseComponent({ client, uri, data, store, chatId, nodeId, ex
   // when its actions write them. Props stay the EXTERNAL contract.
   // The local slice sits ON TOP: a value the component wrote itself is the current one.
   const merged = store
-    ? { ...propDefaults, ...(def?.state ?? {}), ...(sourceData ?? {}) }
+    ? { ...propDefaults, ...(appState ?? {}), ...(def?.state ?? {}), ...(sourceData ?? {}) }
     : { ...propDefaults, ...(def?.state ?? {}), ...(sourceData ?? {}), ...localSlice };
   // Inject the served keyframes + apply the SERVED base render-root (theme.root — DS typography
   // + font-smoothing). When ISOLATED, theme.root is applied to the shadow-root container inside
@@ -212,8 +262,10 @@ export function UnoverseComponent({ client, uri, data, store, chatId, nodeId, ex
   // belongs to the app's timeline, which scopes it to a single turn's unclaimed
   // components. Resolving it here too rendered every instance in the store a second time
   // — the composed page appeared in its surface AND in the chat beside it.
-  const resolveSlot: SlotResolver | undefined = store && (def as { sections?: unknown }).sections
+  const resolveSlot: SlotResolver | undefined = (store && (def as { sections?: unknown }).sections) || place
     ? (node, key) => {
+        if (node.type === "Place") return place?.(String((node as { name?: unknown }).name ?? "")) ?? null;
+        if (!store) return null;
         const claim = node.select?.where;
         const pointers = store
           .getResponses()
@@ -237,6 +289,7 @@ export function UnoverseComponent({ client, uri, data, store, chatId, nodeId, ex
               nodeId={n}
               onAction={onAction}
               theme={activeTheme}
+              appStore={appStore}
             />
           );
         });

package/vendor/sdk/lib/app.tsx

@@ -104,7 +104,7 @@ function FlipList({ items }: { items: { key: string; node: ReactNode }[] }) {
 }
 import { useUnoverseTheme, ensureFontStylesheets } from "./theme";
 import { IsolatedRoot } from "./isolate";
-import { useVoiceService, type UseVoiceServiceConfig } from "./voice";
+import { useVoiceService, type UseVoiceServiceConfig, type VoiceService } from "./voice";
 
 export interface StreamedUnoverseAppProps {
   client: UnoverseClient;
@@ -130,12 +130,15 @@ export interface StreamedUnoverseAppProps {
    *  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;
+  /** The voice service itself, when the host already runs one to share with the page's own
+   *  templates (appEngine). Given, the renderer uses it instead of starting a second. */
+  voiceService?: VoiceService;
 }
 
 /** 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 = {
+export const INERT_VOICE: UseVoiceServiceConfig = {
   apiUrl: "",
   session: { userId: "", conversationId: "", workflowId: "", targetTriggerNode: "" },
 };
@@ -156,7 +159,7 @@ function collectSlotPointers(node: unknown, store: ComponentStore, scope?: Set<s
   return [...new Set(out)];
 }
 
-export function StreamedUnoverseApp({ client, store, uri, onAction, theme: themeProp, props, isolate = true, voice: voiceConfig, templateChrome }: StreamedUnoverseAppProps) {
+export function StreamedUnoverseApp({ client, store, uri, onAction, theme: themeProp, props, isolate = true, voice: voiceConfig, voiceService, templateChrome }: StreamedUnoverseAppProps) {
   const [def, setDef] = useState<UnoverseDefinition | null>(null);
   const [error, setError] = useState<string | null>(null);
   // MOUNTED TEMPLATES: an app entry with `use:` names a template definition; it is
@@ -167,9 +170,10 @@ export function StreamedUnoverseApp({ client, store, uri, onAction, theme: theme
   // 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,
+  const own = useVoiceService(
+    voiceConfig && !voiceService ? { ...voiceConfig, wsUrl: client.serverOrigin.replace(/^http/, "ws") } : INERT_VOICE,
   );
+  const voice = voiceService ?? own;
   // 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

package/vendor/sdk/lib/connection.tsx

@@ -118,7 +118,7 @@ export function useUnoverseConnection(
   config: UnoverseConnectionConfig,
   session: UnoverseSessionParams,
   store: ComponentStore,
-  options: { enabled?: boolean; onAppSwitch?: (app: string) => void } = {},
+  options: { enabled?: boolean; onAppSwitch?: (app: string) => void; onJoinCall?: (workflowId?: string) => void } = {},
 ): UnoverseConnection {
   const enabled = options.enabled ?? true;
   // Read through a ref so a host's inline arrow does not tear down the stream on
@@ -126,6 +126,8 @@ export function useUnoverseConnection(
   const onAppSwitchRef = useRef(options.onAppSwitch);
   onAppSwitchRef.current = options.onAppSwitch;
   const onAppSwitch = (app: string) => onAppSwitchRef.current?.(app);
+  const onJoinCallRef = useRef(options.onJoinCall);
+  onJoinCallRef.current = options.onJoinCall;
   // Read through a ref too: the server follows app switches itself, so a new app must not
   // tear the stream down; the next registration simply names it.
   const appIdRef = useRef(session.appId);
@@ -152,8 +154,10 @@ export function useUnoverseConnection(
   // ---- connection lifecycle (MCP stream) ----
   useEffect(() => {
     if (!enabled) return; // mock mode — no live stream
-    if (!workflowId || !userId || !conversationId) {
-      console.warn("[unoverse] connection missing workflowId/userId/conversationId");
+    // No workflowId is fine: a page app with none still hears its conversation (the server
+    // takes a signed-in session without one; a guest's still needs a public trigger).
+    if (!userId || !conversationId) {
+      console.warn("[unoverse] connection missing userId/conversationId");
       return;
     }
     let cancelled = false;
@@ -267,6 +271,13 @@ export function useUnoverseConnection(
           if (typeof next === "string" && next) onAppSwitch?.(next);
           return;
         }
+        // A VOICE IN THE WORKFLOW ASKS THE PAGE TO JOIN (VOICE_STREAMING_GUIDE.md, "Call
+        // Initialization"). The host's voice service joins; a host without one ignores it.
+        if (evt.type === "JOIN_CALL") {
+          const workflowId = (msg as unknown as { workflowId?: unknown }).workflowId;
+          onJoinCallRef.current?.(typeof workflowId === "string" ? workflowId : undefined);
+          return;
+        }
         applyServerMessage(store, msg, seenRef.current);
       };
 

package/vendor/sdk/lib/core/actions.ts

@@ -19,6 +19,9 @@ export interface ActionContext {
   nodeId: string;
   /** Route a non-`setValue` action to the workflow (channel-provided, e.g. USER_ACTION). */
   sendToServer?: (type: string, data: Record<string, unknown>) => void;
+  /** Where APP state lives, when it is not `store`: a template a website page draws keeps its
+   *  own slice in its own store and shares the app's state with everything on the page. */
+  appStore?: ComponentStore;
 }
 
 /** Resolve a value: a `"{{path}}"` template reads from `scope` (dot-path); anything
@@ -86,7 +89,7 @@ export function dispatchAction(
     // concept — only "write a key to component state" and "write a key to template state".
     const patch: Record<string, unknown> = {};
     for (const { key, value } of spec.values ?? []) patch[key] = resolveValue(value, scope);
-    ctx.store.mergeAppState(patch);
+    (ctx.appStore ?? ctx.store).mergeAppState(patch);
   } else if (spec.type === "input") {
     // A controlled Input changed — write its bound field back into the state bag that
     // OWNS this tree (local two-way binding; every keystroke is local, never a server
@@ -98,7 +101,7 @@ export function dispatchAction(
     const field = typeof scope.field === "string" ? scope.field : undefined;
     if (field) {
       if (ctx.nodeId) ctx.store.apply({ type: "COMPONENT_DATA", chatId: ctx.chatId, nodeId: ctx.nodeId, data: { [field]: scope.text } });
-      else ctx.store.mergeAppState({ [field]: scope.text });
+      else (ctx.appStore ?? ctx.store).mergeAppState({ [field]: scope.text });
     }
   } else {
     // SERVER — narrow the payload by `send` if given, else forward the whole scope.

package/vendor/sdk/lib/index.ts

@@ -2,10 +2,10 @@ export { UnoverseComponent } from "./UnoverseComponent";
 export type { UnoverseComponentProps } from "./UnoverseComponent";
 export { StreamedUnoverseComponent, useUnoverseInstance } from "./streamed";
 export type { StreamedUnoverseComponentProps } from "./streamed";
-export { StreamedUnoverseApp, selectPointers, computeAppWidth, resolveActiveLayout } from "./app";
+export { StreamedUnoverseApp, INERT_VOICE, selectPointers, computeAppWidth, resolveActiveLayout } from "./app";
 export type { StreamedUnoverseAppProps } from "./app";
 export { renderNode, styleToCss, keyframesCss } from "./render";
-export type { ActionHandler, SlotResolver } from "./render";
+export type { ActionHandler, ActionMeta, SlotResolver } from "./render";
 export { useUnoverseTheme } from "./theme";
 export { IsolatedRoot } from "./isolate";
 export { useUnoverseConnection } from "./connection";

package/vendor/sdk/lib/primitives.tsx

@@ -107,17 +107,28 @@ function nodeChrome(node: UnoverseNode, data: Record<string, unknown>, theme: Re
   // reacts to the space the grid actually has, not the viewport. A component in a narrow
   // panel on a wide screen stacks correctly, which a viewport breakpoint cannot do.
   //
-  // The threshold is SERVED (`theme.grid.stackBelow`), overridable per grid with
-  // `style.stackBelow`. The SDK holds no width of its own.
+  // The threshold is SERVED (`theme.grid.stackBelow`). The SDK holds no width of its own.
   if (s?.span) {
-    const raw = (s.stackBelow as string) ?? theme.grid?.stackBelow ?? "";
+    const raw = theme.grid?.stackBelow ?? "";
     const w = theme.space[raw] ?? theme.layout?.[raw] ?? raw;
     if (w) {
       const cls = `uno-stack-${hashStr(String(w))}`;
       classes.push(cls);
-      styleEls.push(<style key="span-stack">{`@container (max-width:${w}){.${cls}{grid-column:1 / -1 !important}}`}</style>);
+      styleEls.push(<style key="span-stack">{`@container (max-width:${w}){.${cls}:not(.uno-gridstack > *){grid-column:1 / -1 !important}}`}</style>);
     }
   }
+  // A GRID'S OWN `stackBelow` overrides the served threshold for that grid: below it, EVERY
+  // child takes the whole row, spanning or not, so a two-up list stacks as a 7/5 split does.
+  // The children query the grid itself (it is `container-type: inline-size`), and the
+  // served threshold above steps aside for them (`uno-gridstack`), so a grid may hold its
+  // shape longer as well as give it up sooner.
+  if (s?.columns && s.stackBelow) {
+    const raw = s.stackBelow as string;
+    const w = theme.space[raw] ?? theme.layout?.[raw] ?? raw;
+    const cls = `uno-gridstack-${hashStr(String(w))}`;
+    classes.push("uno-gridstack", cls);
+    styleEls.push(<style key="grid-stack">{`@container (max-width:${w}){.${cls} > *{grid-column:1 / -1 !important}}`}</style>);
+  }
   // `columns` AS A BREAKPOINT MAP — the responsive grid: column counts per named band
   // ({mobile: "1", tablet: "2", desktop: "3", full: "4"}), applied by CONTAINER width
   // (the nearest `container` ancestor — a grid in a narrow panel stacks on a wide
@@ -183,6 +194,29 @@ export function BoxView({ node, data, theme, children, onAction }: { node: Unove
   // A selection host must anchor its floating affordance; default to relative only when
   // the definition declared no position of its own (sticky/absolute roots keep theirs).
   const hostStyle = sel && !(style as CSSProperties).position ? ({ ...style, position: "relative" } as CSSProperties) : style;
+  // A STAGE (`style.stage: 1280x720`): the Box is drawn at that fixed size and scaled as one
+  // piece to the width it is given, the way slide tools render a slide. Its layout never
+  // reflows, so what is aligned stays aligned on every screen.
+  const stage = /^(\d+)x(\d+)$/.exec(String((node.style as { stage?: unknown } | undefined)?.stage ?? ""));
+  const stageW = stage ? Number(stage[1]) : 0;
+  const stageRef = useRef<HTMLDivElement>(null);
+  const [scale, setScale] = useState(1);
+  useLayoutEffect(() => {
+    const el = stageRef.current;
+    if (!stageW || !el) return;
+    const ro = new ResizeObserver(() => setScale(el.clientWidth / stageW));
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [stageW]);
+  if (stage)
+    return (
+      <div ref={stageRef} style={{ position: "relative", width: "100%", aspectRatio: `${stage[1]} / ${stage[2]}` }}>
+        <div className={className} style={{ ...hostStyle, position: "absolute", top: 0, left: 0, width: stageW, height: Number(stage[2]), transform: `scale(${scale})`, transformOrigin: "0 0" }} data-unoverse-id={inspectId(node)}>
+          {styleEls}
+          {children}
+        </div>
+      </div>
+    );
   return (
     <div ref={scrollRef ?? revealRef ?? selRef} className={className} style={hostStyle} data-unoverse-id={inspectId(node)}>
       {styleEls}

package/vendor/sdk/lib/realtime/useAudioPlayback.ts

@@ -30,6 +30,8 @@ export interface UseAudioPlaybackReturn {
   isPlaying: boolean;
   /** Mark that no more chunks are coming — isPlaying clears when the last finishes. */
   markAsLastChunk: () => void;
+  /** Wake the speaker, inside a click. */
+  unlock: () => void;
 }
 
 interface QueuedAudio {
@@ -148,5 +150,8 @@ export function useAudioPlayback(): UseAudioPlaybackReturn {
     };
   }, [stopAll]);
 
-  return { playAudio, stopAll, isPlaying, markAsLastChunk };
+  // Wakes the speaker. Called inside a click, because a browser plays nothing it was not woken for.
+  const unlock = useCallback(() => void getAudioContext(), [getAudioContext]);
+
+  return { playAudio, stopAll, isPlaying, markAsLastChunk, unlock };
 }