@unoverse-platform/studio 0.1.101 → 0.1.102

package/vendor/sdk/lib/voice.tsx

@@ -77,10 +77,30 @@ export interface VoiceServiceState {
   error: string | null;
 }
 
+export interface StartCall {
+  message?: string;
+  metadata?: Record<string, unknown>;
+  workflowId?: string;
+  targetTriggerNode?: string;
+}
+
 export interface VoiceService {
   /** Spread into the template's data scope (channel overrides → rootData). */
   state: VoiceServiceState;
-  startCall: () => Promise<void>;
+  /** Start a call. `start` is what it starts with, as any request to the workflow: the text,
+   *  and metadata a trigger reads (`metadata.task` names the task). Omitted → "Start call".
+   *  `workflowId`/`targetTriggerNode` name the workflow to run, else the session's own: a page
+   *  template's binding (UNOVERSE_HOST_PAGE.md rule 4). Started while a call is live, it MOVES
+   *  the call: the same line, the new workflow, and the server closes the session before it
+   *  (VOICE_STREAMING_GUIDE.md, "One Live Session Per Conversation"). */
+  startCall: (start?: StartCall) => Promise<void>;
+  /** Join a call already running: the audio lane and the microphone for a workflow something
+   *  else started (a canvas Run, a button, `JOIN_CALL`), without starting it again. `workflowId`
+   *  is what the hang-up names; omitted, the session's own. Joining a call already joined is
+   *  nothing. */
+  joinCall: (workflowId?: string) => Promise<void>;
+  /** Wake the speaker. Call it inside the click that may start a call. */
+  unlock: () => void;
   endCall: () => Promise<void>;
   toggleMute: () => void;
 }
@@ -113,6 +133,11 @@ export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
   const [lookupTool, setLookupTool] = useState<string | null>(null);
 
   const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  /** The workflow the live call is on, which a hang-up names; null with no call. */
+  const callWorkflowRef = useRef<string | null>(null);
+  /** Lets go of the microphone and the audio lane when the server ends the call (set below,
+   *  once they exist). */
+  const releaseRef = useRef<() => void>(() => {});
   const sendAudioRef = useRef<(d: ArrayBuffer) => void>(() => {});
 
   const playback = useAudioPlayback();
@@ -134,6 +159,9 @@ export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
       } else if (state === "SESSION_READY") {
         setConnectionStatus("connected");
       } else if (state === "SESSION_ENDED") {
+        // THE SERVER ENDED THE CALL (the model hung up, a minute of silence, a timeout): the
+        // microphone stops and the lane closes, or the page streams to nobody.
+        releaseRef.current();
         setConnectionStatus("ended");
         setAssistantHint(false);
         setUserSpeaking(false);
@@ -168,55 +196,109 @@ export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
   }, [ws.sendAudio]);
 
   const capture = useAudioCapture({ onAudioData: handleAudioData });
+  useEffect(() => {
+    releaseRef.current = () => {
+      if (timerRef.current) {
+        clearInterval(timerRef.current);
+        timerRef.current = null;
+      }
+      callWorkflowRef.current = null;
+      void capture.stopCapture();
+      ws.disconnect();
+    };
+  }, [capture, ws]);
 
-  const startCall = useCallback(async () => {
-    setConnectionStatus("connecting");
-    setError(null);
-    setCallDuration(0);
+  const startCall = useCallback(async (start?: StartCall) => {
+    const workflowId = start?.workflowId || session.workflowId;
+    const targetTriggerNode = start?.targetTriggerNode || session.targetTriggerNode;
+    if (!workflowId) {
+      // NOTHING TO CALL: no workflow was named and the session has none. Never a default.
+      setError("No workflow to call");
+      setConnectionStatus("error");
+      return;
+    }
+    // A CALL ALREADY LIVE IS MOVED, not started again: the line and the microphone stay open,
+    // and only the workflow changes. The old voice is cut at once so two are never heard.
+    const moving = callWorkflowRef.current !== null;
+    if (moving) {
+      playback.stopAll();
+      setAssistantHint(false);
+      setIsLookingUp(false);
+      setLookupTool(null);
+    } else {
+      setConnectionStatus("connecting");
+      setError(null);
+      setCallDuration(0);
+    }
     try {
       // 1. Open the audio lane (sends INIT_SESSION on open) BEFORE the trigger,
       //    so the server can route audio the moment the Nova/Grok session is up.
-      await ws.connect();
+      if (!moving) await ws.connect();
+      callWorkflowRef.current = workflowId;
 
       // 2. START_CALL via REST — fire-and-forget; the workflow stays open for the call.
       const token = getAccessToken ? await getAccessToken() : null;
       const headers: Record<string, string> = { "Content-Type": "application/json" };
       if (token) headers["Authorization"] = `Bearer ${token}`;
       const chatId = session.chatId ?? `voice_${session.conversationId}`;
-      fetch(`${apiUrl}/api/workflows/${session.workflowId}/execute`, {
+      fetch(`${apiUrl}/api/workflows/${workflowId}/execute`, {
         method: "POST",
         headers,
         body: JSON.stringify({
           input: {
-            message: "Start call",
+            message: start?.message ?? "Start call",
             chatId,
             conversationId: session.conversationId,
             userId: session.userId,
             providerId: "gravity-voice",
             isAudio: true,
             metadata: {
-              targetTriggerNode: session.targetTriggerNode,
+              ...(start?.metadata ?? {}),
+              targetTriggerNode,
               action: "START_CALL",
               isAction: true,
-              workflowId: session.workflowId,
+              workflowId,
               continuousStream: true,
             },
           },
           conversationId: session.conversationId,
         }),
       }).catch((e) => console.error("[voice] START_CALL error:", e));
+      if (moving) return;
 
       // 3. Start streaming the mic.
       await capture.startCapture();
       timerRef.current = setInterval(() => setCallDuration((p) => p + 1), 1000);
       setConnectionStatus("connected");
     } catch (err: unknown) {
+      callWorkflowRef.current = null;
       setError(err instanceof Error ? err.message : "Failed to start call");
       setConnectionStatus("error");
       setIsLookingUp(false);
       setLookupTool(null);
     }
-  }, [ws, capture, apiUrl, session, getAccessToken]);
+  }, [ws, capture, playback, apiUrl, session, getAccessToken]);
+
+  // JOIN, NOT START. The workflow is already running and its voice node has opened the vendor
+  // session on this conversation; all that is missing is a browser on the audio lane. So open
+  // the lane and the microphone, and send no execute: a second one would start a second run.
+  const joinCall = useCallback(async (workflowId?: string) => {
+    if (callWorkflowRef.current !== null) return;
+    callWorkflowRef.current = workflowId ?? session.workflowId ?? "";
+    setConnectionStatus("connecting");
+    setError(null);
+    setCallDuration(0);
+    try {
+      await ws.connect();
+      await capture.startCapture();
+      timerRef.current = setInterval(() => setCallDuration((p) => p + 1), 1000);
+      setConnectionStatus("connected");
+    } catch (err: unknown) {
+      callWorkflowRef.current = null;
+      setError(err instanceof Error ? err.message : "Failed to join call");
+      setConnectionStatus("error");
+    }
+  }, [ws, capture, session.workflowId]);
 
   const endCall = useCallback(async () => {
     if (timerRef.current) {
@@ -226,7 +308,8 @@ export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
     await capture.stopCapture();
     playback.stopAll();
     // END via WS control — NOT a new REST execute (that would start a new workflow).
-    ws.sendControl("AUDIO_CONTROL", { command: "stop", workflowId: session.workflowId });
+    ws.sendControl("AUDIO_CONTROL", { command: "stop", workflowId: callWorkflowRef.current ?? session.workflowId });
+    callWorkflowRef.current = null;
     ws.disconnect();
     setConnectionStatus("ended");
     setIsMuted(false);
@@ -335,5 +418,5 @@ export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
     store?.mergeAppState(state as unknown as Record<string, unknown>);
   }, [store, state]);
 
-  return { state, startCall, endCall, toggleMute };
+  return { state, startCall, joinCall, endCall, toggleMute, unlock: playback.unlock };
 }

package/vendor/sdk/pageInterfaces.tsx

@@ -0,0 +1,383 @@
+/**
+ * THE PAGE'S OWN TEMPLATES (docs/unoverse/design/sdk/UNOVERSE_HOST_PAGE.md rule 3).
+ *
+ * A website that is the app marks where its unoverse templates go:
+ *
+ *   <div data-unoverse-interface="unoverse/presence-avatar"></div>
+ *
+ * This runtime is already loaded (the embed started the app with no chrome). It reads each
+ * marked template by URI over MCP, exactly as it reads the app, and draws it INTO the page's
+ * element, in a shadow DOM (UnoverseComponent's own IsolatedRoot). One runtime, many shadow
+ * roots: one client, one conversation, one sign-in for every part of the page.
+ *
+ * A template ARRIVES WITH ITS PAGE, as Studio previews it and as a delivery lands it: one
+ * instance per linked part (`static:`), at its face, with the part's own values
+ * (the served `sections` and their `seeds`), then the template itself. Drawn bare, its parts'
+ * slots hold nothing and only the frame shows.
+ *
+ * The frame shares the page's origin (EMBED_CLIENT.md §1), so the page's document is
+ * reachable from here; React portals listen for events on their own container, so a part
+ * drawn into the page is as live as one drawn in the frame.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { createPortal } from "react-dom";
+import { ComponentStore, UnoverseComponent, type ActionHandler, type ActionMeta, type UnoverseClient, type UnoverseDefinition, type VoiceService } from "./lib";
+
+const MARK = "data-unoverse-interface";
+const CHAT = "page";
+const TEMPLATE_NODE = "~template";
+
+/** The page this runtime serves, or null when there is none it may reach (an MCP host). */
+function pageDocument(): Document | null {
+  try {
+    return window.parent !== window ? window.parent.document : null;
+  } catch {
+    return null; // a cross-origin host: there is no page of ours to draw into
+  }
+}
+
+/**
+ * WHICH TEMPLATE THE ARROW KEYS BELONG TO: exactly one. The one the visitor last pressed in;
+ * before any press, the one taking the most of the screen. Every template's state is its
+ * own, so a key must never move two (the presentation's slides moved the avatar's steps).
+ */
+let engaged: HTMLElement | null = null;
+function keyOwner(doc: Document): HTMLElement | null {
+  const full = doc.fullscreenElement as HTMLElement | null;
+  if (full?.hasAttribute(MARK)) return full; // a fullscreen template is the only one on screen
+  if (engaged && doc.contains(engaged)) return engaged;
+  const vh = doc.defaultView?.innerHeight ?? 0;
+  let best: HTMLElement | null = null;
+  let area = 0;
+  for (const el of doc.querySelectorAll<HTMLElement>(`[${MARK}]`)) {
+    const r = el.getBoundingClientRect();
+    const seen = Math.max(0, Math.min(r.bottom, vh) - Math.max(r.top, 0)) * r.width;
+    if (seen > area) (area = seen), (best = el);
+  }
+  return best;
+}
+
+/** A page template's address, from the name its element is marked with. */
+const uriOf = (name: string) => (name.includes("://") ? name : `unoverse://templates/${name}`);
+
+/** THE AVATARS: page templates whose steps are the call's phases (`listening`, `speaking`).
+ *  They are how the page is spoken to, so they are never the task in view; they are the ones
+ *  that follow the call. */
+const avatars = new Set<HTMLElement>();
+const CALL_PHASES = ["listening", "speaking"];
+
+/** The workflow a template names in its manifest (UNOVERSE_HOST_PAGE.md rule 4). */
+export type Binding = { workflow?: string; trigger?: string };
+
+/** THE TASK IN VIEW: the marked template, not an avatar, spanning the middle of the screen. */
+function taskInView(doc: Document): HTMLElement | null {
+  const mid = (doc.defaultView?.innerHeight ?? 0) / 2;
+  for (const el of doc.querySelectorAll<HTMLElement>(`[${MARK}]`)) {
+    if (avatars.has(el)) continue;
+    const r = el.getBoundingClientRect();
+    if (r.top <= mid && r.bottom >= mid) return el;
+  }
+  return null;
+}
+
+/**
+ * THE AVATAR'S SPOT WHILE A TEMPLATE IS FULLSCREEN. The browser shows only the fullscreen
+ * element, so the avatar's own element (in the site's navigation) is hidden. A fullscreen
+ * state's layout carries a `Place`; it draws this element, and the page's avatar draws there
+ * until the place goes. It is the same avatar, so it keeps following the call.
+ */
+let dock: HTMLElement | null = null;
+const dockWatchers = new Set<() => void>();
+const setDock = (at: HTMLElement | null) => {
+  if (at === dock) return;
+  dock = at;
+  dockWatchers.forEach((f) => f());
+};
+const watchDock = (f: () => void) => {
+  dockWatchers.add(f);
+  return () => void dockWatchers.delete(f);
+};
+const drawDock = () => <div ref={setDock} />;
+
+type Section = { kind?: string; face?: string; ref?: string; preview?: string[]; seeds?: Record<string, Record<string, unknown>> };
+
+/** One marked template: read it, give it its parts, draw it. */
+function PageTemplate({ client, uri, el, voice, waiting, onBinding, onCall, appStore }: { client: UnoverseClient; uri: string; el: HTMLElement; voice: VoiceService; waiting: boolean; onBinding: (uri: string, binding: Binding) => void; onCall: ActionHandler; appStore: ComponentStore }) {
+  const store = useMemo(() => new ComponentStore(), [uri]);
+  const [ready, setReady] = useState(false);
+  const partsRef = useRef<string[]>([]);
+  const defRef = useRef<{ stateTree?: { name: string; on?: string; initial?: string; states?: { name: string }[]; fullscreen?: boolean }[] } | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    client
+      .readDefinition(uri)
+      .then((def) => {
+        if (!alive || !def) return;
+        const d = def as UnoverseDefinition & { defaultLayout?: string; layouts?: Record<string, unknown>; sections?: Record<string, Section[]>; binding?: Binding };
+        if (d.binding?.workflow) onBinding(uri, d.binding);
+        defRef.current = d as typeof defRef.current;
+        const base = d.defaultLayout ?? (d.layouts ? Object.keys(d.layouts)[0] : undefined);
+        partsRef.current = [];
+        for (const sec of (base && d.sections?.[base]) || []) {
+          const parts = sec.ref ? [sec.ref] : sec.kind === "director" ? sec.preview ?? [] : [];
+          parts.forEach((ref, i) => {
+            const nodeId = `${sec.face}~${ref}~${i}`;
+            partsRef.current.push(nodeId);
+            store.apply({ type: "COMPONENT_INIT", chatId: CHAT, nodeId, component: { type: ref, props: sec.seeds?.[ref] ?? {} } });
+            if (sec.face) store.mergeComponentState(CHAT, nodeId, { state: sec.face });
+          });
+        }
+        const ref = uri.replace(/^unoverse:\/\/templates\//, "");
+        store.apply({ type: "COMPONENT_INIT", chatId: CHAT, nodeId: TEMPLATE_NODE, component: { type: ref, componentUrl: uri, props: {} } });
+        if (base) store.mergeComponentState(CHAT, TEMPLATE_NODE, { state: base });
+        if ((d.stateTree ?? []).some((t) => CALL_PHASES.every((p) => t.states?.some((x) => x.name === p)))) avatars.add(el);
+        setReady(true);
+      })
+      .catch((e) => console.warn(`[unoverse] page template "${uri}" failed to load:`, e));
+    return () => {
+      alive = false;
+    };
+  }, [client, uri, store]);
+
+  // A TEMPLATE FOLLOWS ITS TASK. Whatever runs the task publishes where it is as
+  // `tasks.<its URI>` in the app state (SIGNAL.md 6c); this template moves to that step, the
+  // same write its own Next makes, whether the move came from a voice or a chat.
+  // Its `props` too, keyed by part: `{ <part>: values }` merges into that part (a template's
+  // content lives in its parts), once per change, so a template already on the page is
+  // hydrated in place.
+  //
+  // THE SAME TEMPLATE, STREAMED. When a run renders this template, it streams into the
+  // client's store like any interface. It is already on the page, so it is not drawn again:
+  // this copy hydrates from it, each part's values onto that part. A copy still on its first
+  // step (the wait, such as `finding`) moves to the next step as its values land; nothing
+  // outside the template moves it.
+  useEffect(() => {
+    if (!ready) return;
+    let lastProps = "";
+    let lastStreamed = "";
+    const fillParts = (parts: Record<string, unknown>) => {
+      for (const [part, values] of Object.entries(parts)) {
+        if (!values || typeof values !== "object" || Array.isArray(values)) continue;
+        for (const nodeId of partsRef.current.filter((id) => id.startsWith(`${part}~`))) store.mergeComponentState(CHAT, nodeId, values as Record<string, unknown>);
+      }
+    };
+    const moveTo = (at: unknown) => {
+      if (typeof at !== "string") return;
+      const tree = defRef.current?.stateTree?.find((t) => t.on && t.states?.some((x) => x.name === at));
+      if (!tree?.on) return;
+      const tpl = store.get(CHAT, TEMPLATE_NODE) as Record<string, unknown> | undefined;
+      if (tpl?.[tree.on] !== at) store.mergeComponentState(CHAT, TEMPLATE_NODE, { [tree.on]: at });
+    };
+    const follow = () => {
+      const task = ((appStore.getAppState().tasks ?? {}) as Record<string, { step?: string; props?: Record<string, unknown> }>)[uri];
+      if (task?.props && typeof task.props === "object") {
+        const next = JSON.stringify(task.props);
+        if (next !== lastProps) {
+          lastProps = next;
+          fillParts(task.props);
+        }
+      }
+      moveTo(task?.step);
+      for (const r of appStore.getResponses()) {
+        for (const pointer of r.components) {
+          const { chatId, nodeId } = appStore.split(pointer);
+          if ((appStore.getComponentUrl(chatId, nodeId) ?? "").split("#")[0] !== uri) continue;
+          const streamed = appStore.get(chatId, nodeId) ?? {};
+          const next = JSON.stringify(streamed);
+          if (next === lastStreamed) continue;
+          lastStreamed = next;
+          if (!streamed.state || typeof streamed.state !== "object") continue;
+          fillParts(streamed.state as Record<string, unknown>);
+          const tree = defRef.current?.stateTree?.find((t) => t.on && (t.states?.length ?? 0) > 1);
+          const tpl = store.get(CHAT, TEMPLATE_NODE) as Record<string, unknown> | undefined;
+          if (tree?.on && (tpl?.[tree.on] ?? tree.initial) === tree.initial) moveTo(tree.states![1].name);
+        }
+      }
+    };
+    follow();
+    return appStore.subscribe(follow);
+  }, [ready, appStore, store, uri]);
+
+  // THE ARROW KEYS STEP IT, on the PAGE. Left and Right move a template's steps (the served
+  // step tree: `on` + its substates), the same write its own Back and Next make. The keys are
+  // the page's, so they are heard on the page's document, not this frame's. Typing in a field
+  // never steps, and only the template that owns the keys moves (keyOwner).
+  useEffect(() => {
+    const doc = pageDocument();
+    if (!doc || !ready) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "ArrowRight" && e.key !== "ArrowLeft") return;
+      if (keyOwner(doc) !== el) return;
+      const t = e.target as HTMLElement | null;
+      if (t && (t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName))) return;
+      const tpl = store.get(CHAT, TEMPLATE_NODE) as Record<string, unknown> | undefined;
+      const def = defRef.current;
+      const face = String(tpl?.state ?? "");
+      const tree = def?.stateTree?.find((s) => s.name === face);
+      const steps = tree?.states?.map((s) => s.name) ?? [];
+      if (!tree?.on || steps.length < 2) return;
+      const cur = String(tpl?.[tree.on] ?? tree.initial ?? steps[0]);
+      const i = steps.indexOf(cur) + (e.key === "ArrowRight" ? 1 : -1);
+      if (i < 0 || i >= steps.length) return;
+      e.preventDefault();
+      store.mergeComponentState(CHAT, TEMPLATE_NODE, { [tree.on]: steps[i] });
+    };
+    doc.addEventListener("keydown", onKey);
+    return () => doc.removeEventListener("keydown", onKey);
+  }, [ready, store, el]);
+
+  // FULLSCREEN IS A STATE. Entering a state marked `fullscreen` takes this template's element
+  // fullscreen; leaving it hands the screen back. The request is made inside the store write
+  // the visitor's click made (setValue notifies synchronously), because a browser grants
+  // fullscreen only to a click. Refused, or left with Esc, the template goes back to the
+  // state it came from. The step is one value across states, so the slide stays put.
+  useEffect(() => {
+    const doc = pageDocument();
+    if (!doc || !ready) return;
+    const states = () => defRef.current?.stateTree ?? [];
+    const isFull = (name: string) => states().some((t) => t.name === name && t.fullscreen);
+    const face = () => String((store.get(CHAT, TEMPLATE_NODE) as Record<string, unknown> | undefined)?.state ?? "");
+    let from = isFull(face()) ? (states().find((t) => !t.fullscreen)?.name ?? "") : face();
+    let asking = false;
+    const back = () => store.mergeComponentState(CHAT, TEMPLATE_NODE, { state: from });
+    const sync = () => {
+      const now = face();
+      if (!isFull(now)) {
+        from = now;
+        if (doc.fullscreenElement === el) void doc.exitFullscreen();
+        return;
+      }
+      if (doc.fullscreenElement === el || asking) return;
+      asking = true;
+      el.requestFullscreen()
+        .catch(back)
+        .finally(() => (asking = false));
+    };
+    const onChange = () => {
+      if (doc.fullscreenElement !== el && !asking && isFull(face())) back();
+    };
+    const stop = store.subscribe(sync);
+    doc.addEventListener("fullscreenchange", onChange);
+    return () => {
+      stop();
+      doc.removeEventListener("fullscreenchange", onChange);
+    };
+  }, [ready, store, el]);
+
+  // WHILE A TEMPLATE IS FULLSCREEN, AN AVATAR DRAWS IN ITS PLACE (drawDock).
+  const docked = useSyncExternalStore(watchDock, () => dock);
+
+  // AN AVATAR FOLLOWS THE CALL: its steps are the call's phases, so its step is the call's
+  // state. `waiting` rides beside it, on any step: a task in view that the call is not working
+  // yet. The avatar draws it as a pulse, and a press on the pulse starts or moves the call.
+  const callState = voice.state.callState;
+  useEffect(() => {
+    if (!ready || !avatars.has(el)) return;
+    const tree = defRef.current?.stateTree?.find((t) => CALL_PHASES.every((p) => t.states?.some((x) => x.name === p)));
+    if (!tree?.on) return;
+    store.mergeComponentState(CHAT, TEMPLATE_NODE, { [tree.on]: callState, waiting });
+  }, [ready, store, el, callState, waiting]);
+
+  if (!ready) return null;
+  const drawn = <UnoverseComponent client={client} store={store} chatId={CHAT} nodeId={TEMPLATE_NODE} onAction={onCall} place={drawDock} appStore={appStore} />;
+  return docked && avatars.has(el) ? createPortal(drawn, docked) : drawn;
+}
+
+/**
+ * ONE APP STATE FOR THE WHOLE PAGE. Each template keeps its own slice in its own store, and
+ * all of them read and write the app's state in `appStore`, the store the call and the
+ * workflow write to. A name one template saves is a name every other template can show.
+ */
+export function PageInterfaces({ org, client, voice, appStore, toServer, startTask }: { org: string; client: UnoverseClient; voice: VoiceService; appStore: ComponentStore; toServer: (t: string, data: Record<string, unknown>, meta?: ActionMeta) => void; startTask: (binding: Binding, task: string) => void }) {
+  const [targets, setTargets] = useState<HTMLElement[]>([]);
+  // The task in view, by its URI, measured again as the page scrolls or resizes.
+  const [inView, setInView] = useState<string | null>(null);
+  // Each template's own workflow, as it loads; a template without one is never called.
+  const [bindings, setBindings] = useState<Record<string, Binding>>({});
+  const onBinding = useCallback((uri: string, b: Binding) => setBindings((prev) => (prev[uri] ? prev : { ...prev, [uri]: b })), []);
+  // The tasks this page has started. Each starts once: a second press starts nothing. The ref
+  // holds it at once, so two quick presses are still one; the state redraws the avatar.
+  const started = useRef(new Set<string>());
+  const [, setStarted] = useState(0);
+
+  // THE AVATAR STARTS THE TASK'S WORKFLOW (UNOVERSE_HOST_PAGE.md rule 4), like any button. The
+  // page connects to nothing until it is pressed. A task in view with a workflow, that is not
+  // already running, is WAITING: a press starts its workflow at the template's trigger. A voice
+  // in that workflow is the workflow's own. Nothing in view, or nothing bound: nothing.
+  const target = inView && bindings[inView]?.workflow ? inView : null;
+  const waiting = !!target && !started.current.has(target);
+  // A TEMPLATE'S OWN ACTIONS go where the app's go: its `submit` answers the task that is waiting
+  // on it, exactly as in the app (appEngine `toServer`). The call's three are the page's.
+  const onCall: ActionHandler = (spec, data, meta) => {
+    const action = typeof spec === "string" ? spec : spec?.type;
+    if (action === "submit" || action === "cancel") toServer(action, data, meta);
+    else if (action === "startCall") {
+      if (!target || started.current.has(target)) return;
+      started.current.add(target);
+      setStarted((n) => n + 1);
+      // The press is the click the browser needs before it plays a voice the workflow may have.
+      voice.unlock();
+      startTask(bindings[target], target);
+    } else if (action === "endCall") {
+      void voice.endCall();
+    } else if (action === "toggleMute") voice.toggleMute();
+    // Another app on the page, opened or closed by its `<org>/<app>` (its own tag, EMBED_CLIENT.md).
+    else if (action === "toggleApp") {
+      const app = (data as { app?: unknown } | undefined)?.app;
+      if (typeof app === "string") (pageDocument()?.defaultView as (Window & { unoverseApps?: Record<string, { toggle(): void }> }) | undefined)?.unoverseApps?.[app]?.toggle();
+    }
+  };
+
+  useEffect(() => {
+    const doc = pageDocument();
+    const win = doc?.defaultView;
+    if (!doc || !win) return;
+    const measure = () => {
+      const name = taskInView(doc)?.getAttribute(MARK);
+      setInView(name ? uriOf(name) : null);
+    };
+    measure();
+    win.addEventListener("scroll", measure, { passive: true });
+    win.addEventListener("resize", measure);
+    return () => {
+      win.removeEventListener("scroll", measure);
+      win.removeEventListener("resize", measure);
+    };
+  }, [targets]);
+
+  useEffect(() => {
+    const doc = pageDocument();
+    if (!doc) return;
+    const scan = () => {
+      // Only this app's own org's templates: another app on the page draws its own.
+      const found = [...doc.querySelectorAll<HTMLElement>(`[${MARK}]`)].filter((el) => el.getAttribute(MARK)?.startsWith(`${org}/`));
+      setTargets((prev) => (prev.length === found.length && prev.every((el, i) => el === found[i]) ? prev : found));
+    };
+    scan();
+    // The page may render its parts after this runtime starts (a client-rendered page),
+    // so it keeps looking; only a change in the marked set re-renders.
+    const watch = new MutationObserver(scan);
+    watch.observe(doc.body, { childList: true, subtree: true });
+    // A press anywhere inside a marked template makes it the one the keys move; a press
+    // outside every template hands the keys back to the one most in view.
+    const onPress = (e: Event) => {
+      engaged = (e.composedPath().find((n) => n instanceof HTMLElement && n.hasAttribute(MARK)) as HTMLElement | undefined) ?? null;
+    };
+    doc.addEventListener("pointerdown", onPress, true);
+    return () => {
+      watch.disconnect();
+      doc.removeEventListener("pointerdown", onPress, true);
+    };
+  }, []);
+
+  return (
+    <>
+      {targets.map((el) => {
+        const name = el.getAttribute(MARK) ?? "";
+        if (!name) return null;
+        return createPortal(<PageTemplate client={client} uri={uriOf(name)} el={el} voice={voice} waiting={waiting} onBinding={onBinding} onCall={onCall} appStore={appStore} />, el, name);
+      })}
+    </>
+  );
+}