@unoverse-platform/studio 0.1.96 → 0.1.98

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

@@ -25,6 +25,8 @@
  */
 
 /** A pointer into the data plane — the `${chatId}:${nodeId}` key. */
+import { stateOfUri } from "./apps";
+
 export type Pointer = string;
 
 /** Structural equality for wire values: identity first, JSON compare for the rest.
@@ -79,6 +81,7 @@ export type LifecycleState = "idle" | "thinking" | "streaming" | "complete" | "e
 
 /** Stable empty slice for missing keys — never mutate. */
 const EMPTY_SLICE: Record<string, unknown> = Object.freeze({});
+const EMPTY_POINTERS: readonly Pointer[] = Object.freeze([]);
 
 export class ComponentStore {
   // --- data plane ---
@@ -122,6 +125,13 @@ export class ComponentStore {
   private appState: Record<string, unknown> = {};
   // --- history cap (UNOVERSE_STATE_MODEL §6a): hold at most N turns, oldest-out-first. ---
   private maxTurns: number;
+  // --- places (docs/unoverse/design/screen/UNOVERSE_SCREEN.md): what the server's screen document puts
+  //     in each place, in order. An app that declares places draws from here and nothing else. ---
+  private places = new Map<string, Pointer[]>();
+  /** Interfaces that have been placed outside the conversation at some point (see setPlace). */
+  private everOff = new Set<Pointer>();
+  /** The state the screen placed each interface in: a place draws it in this face. */
+  private placed = new Map<Pointer, string>();
 
   /** @param opts.maxTurns history cap (default 100; §6a). Channels may raise/lower it. */
   constructor(opts?: { maxTurns?: number }) {
@@ -179,7 +189,11 @@ export class ComponentStore {
    * marked isApp). Templates are SERVED apps, never streamed components (protocol
    * §0.1); this records WHICH app the channel should load, never a timeline component.
    */
-  setActiveApp(name: string, props: Record<string, unknown> = {}): void {
+  setActiveApp(address: string, given: Record<string, unknown> = {}): void {
+    // THE HASH NAMES THE STATE (stateOfUri): `unoverse://apps/acme/workspace#review` is the
+    // app, opened on review; the hash seeds `state` when the props carry none.
+    const { uri: name, state } = stateOfUri(address);
+    const props = state && given.state == null ? { state, ...given } : given;
     if (this.activeAppName === name && JSON.stringify(this.activeAppProps) === JSON.stringify(props)) return;
     // TEMPLATE SWAP = the hard refresh boundary: a NEW shell starts with every surface
     // retired — every instance (durable ones included) returns to inline; the new
@@ -294,13 +308,16 @@ export class ComponentStore {
    * declared initial, and a card whose initial IS the lower state would re-claim it on
    * the next walk and never settle.
    */
-  cancelBelow(active: string, order: string[]): void {
+  cancelBelow(active: string, order: string[], aliasOf?: Map<string, string>): void {
     const below = new Set(order.slice(order.indexOf(active) + 1));
     if (order.indexOf(active) < 0 || !below.size) return;
     let changed = false;
     for (const [key, slice] of this.data) {
       if (slice.lifetime === "conversation") continue;
-      if (!below.has((slice.state ?? slice.view ?? slice.defaultState) as string)) continue;
+      // A face is read THROUGH the mount claims (`mountAliases`), exactly as the ladder
+      // reads it: a card wearing `grid` under a `page` mount sits in `page`.
+      const face = (slice.state ?? slice.view ?? slice.defaultState) as string;
+      if (!below.has(aliasOf?.get(face) ?? face)) continue;
       this.data.set(key, { ...slice, [this.faceKey(slice)]: "inline", ...("defaultState" in slice ? { defaultState: "inline" } : {}) });
       this.touches.set(key, ++this.touchSeq);
       changed = true;
@@ -308,11 +325,24 @@ export class ComponentStore {
     if (changed) this.bump();
   }
 
+  /**
+   * GUEST CLOSE from template chrome: every surfaced slice retracts to `inline`, the
+   * universal fallback face — never to its declared initial (ruled 2026-09-07: a card's
+   * declared initial is a claimed state such as `grid`, so retracting there resurrected
+   * the rail the guest had just closed; rule 6 forbids it). Durable slices opt out as ever.
+   */
   closeSurfaces(): void {
     let changed = false;
     for (const [key, slice] of this.data) {
       if (slice.lifetime === "conversation") continue;
-      if (this.retractSlice(key, slice)) changed = true;
+      const current = (slice.state ?? slice.view ?? slice.defaultState) as unknown;
+      if (typeof current !== "string" || current === "inline") continue;
+      const next: Record<string, unknown> = { ...slice };
+      next[this.faceKey(next)] = "inline";
+      if ("defaultState" in next) next.defaultState = "inline";
+      this.data.set(key, next);
+      this.touches.set(key, ++this.touchSeq);
+      changed = true;
     }
     if (changed) this.bump();
   }
@@ -327,6 +357,49 @@ export class ComponentStore {
     this.bump();
   }
 
+  /** Replace one place's contents, and the state each interface is placed in, as the server's
+   *  SCREEN_PLACE says. */
+  setPlace(place: string, pointers: Pointer[], states: Record<Pointer, string> = {}): void {
+    const current = this.places.get(place) ?? [];
+    const sameList = current.length === pointers.length && current.every((p, i) => p === pointers[i]);
+    const sameStates = Object.entries(states).every(([p, s]) => this.placed.get(p) === s);
+    if (sameList && sameStates) return;
+    // STEPPING ASIDE IS AN ARRIVAL IN THE CONVERSATION (owner, 2026-09-16). An interface that
+    // opened in another place (focus, main, rail) was placed in its turn when it opened, off
+    // the conversation, after the reply bubble that had already been created. When the
+    // screen moves it into `chat` it appears in the conversation for the first time, so that
+    // is where its turn places it: at the front, above the reply. Placed once, here, and no
+    // later data moves it (the 2026-09-08 ruling below, "where it arrived is where it lives",
+    // holds: this is an arrival, not an update). A card shown straight into `chat` was never
+    // elsewhere and keeps its arrival order.
+    // Remembered, not read at the moment: the screen empties the old place and fills `chat`
+    // as two messages, in either order, so "is it elsewhere now" can already be false.
+    if (place !== "chat") for (const p of pointers) this.everOff.add(p);
+    if (place === "chat") {
+      const wasInChat = new Set(current);
+      for (const p of pointers) {
+        if (wasInChat.has(p) || !this.everOff.has(p)) continue;
+        // A TURN WITH COMPONENTS IS THE ASSISTANT'S: said in the predicate, because a check
+        // inside a callback does not narrow the union outside it, and only the assistant's turn
+        // has `components` at all.
+        const turn = this.timeline.find((t): t is AssistantTurn => t.role === "assistant" && t.components.includes(p));
+        if (!turn) continue;
+        turn.components = [p, ...turn.components.filter((c) => c !== p)];
+      }
+    }
+    this.places.set(place, pointers);
+    for (const [p, s] of Object.entries(states)) this.placed.set(p, s);
+    this.bump();
+  }
+  /** The state the screen placed an interface in, or undefined when the screen named none. */
+  placedState(pointer: Pointer): string | undefined {
+    return this.placed.get(pointer);
+  }
+  /** What one place holds, in the order the screen document gives. */
+  placeItems(place: string): readonly Pointer[] {
+    return this.places.get(place) ?? EMPTY_POINTERS;
+  }
+
   // ════════════════════════════════════════════════════════════════════════════
   //  STATE HAS TWO HOMES, BY SCOPE (UNOVERSE_STATE_MODEL §2) — and the SDK hardcodes
   //  NO UI concept (no panel / focus / faq / voice). The dev picks the key and the home:
@@ -404,17 +477,19 @@ export class ComponentStore {
       const seeded = event.component.props as Record<string, unknown> | undefined;
       this.supersede(event.chatId, seeded?.state ?? seeded?.view ?? seeded?.defaultState);
     } else {
-      // NEW ACTIVITY reads newest-at-the-bottom: if this component is no longer the
-      // LAST pointer in its turn (something was placed after it), fresh server data
-      // moves it back to the end — e.g. answer text resuming AFTER an interactive
-      // component the workflow placed mid-turn. At most ONE structure bump per
-      // overtake; the streaming hot path (already last) stays data-only.
-      const resp = this.responseFor(event.chatId);
-      if (resp && resp.components.length > 1 && resp.components[resp.components.length - 1] !== key && resp.components.includes(key)) {
-        resp.components.splice(resp.components.indexOf(key), 1);
-        resp.components.push(key);
-        this.bump();
-      }
+      // WHERE IT ARRIVED IS WHERE IT LIVES (owner ruling 2026-09-08). A pointer's place in
+      // its turn is fixed by `placeInTimeline` when it first appears, and no later data
+      // moves it. Updates change what a component SAYS, never where it sits.
+      //
+      // This replaces "new activity reads newest-at-the-bottom", which moved a component to
+      // the end of its turn whenever fresh data arrived for it. That was written for one
+      // case — answer text resuming after an interactive component placed mid-turn — and it
+      // recomputed order on EVERY update, which is stable only while one thing is updating.
+      // A held Agent task has two: the task's face ticking through its steps, and the
+      // reply resuming once the result lands. They alternate, so the bottom slot alternated
+      // with them and the pair visibly swapped places on screen (SAB Account Agent,
+      // 2026-09-08). The case it was written for is served by arrival order too: text
+      // placed before a form stays above it.
       this.merge(key, this.shieldGuestFace(key, event.data));
       // Rule 5 — a server data-write that PLACES a component into a public state
       // (the host's arrival placement rides COMPONENT_DATA) refreshes that state.

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

@@ -72,6 +72,9 @@ export interface UnoverseNode {
    *  EXISTS only while a component is in its state (§5b: derived, not stored) — e.g. a
    *  focus overlay that appears because something is focused and vanishes when it isn't. */
   frame?: UnoverseNode;
+  /** Place: how the place holds what the screen shows into it. `one` shows the newest;
+   *  `many` shows the set the last show named (docs/unoverse/design/screen/UNOVERSE_SCREEN.md §2.2). */
+  holds?: "one" | "many";
   /** Skeleton: placeholder variant. */
   variant?: "text" | "card" | "image";
   /** Timeline: data sub-tree rendered for a user turn (binds `text`). ALL bubble UX lives here, not the SDK. */
@@ -154,6 +157,9 @@ export interface UnoverseNode {
   /** Markdown: render links in the surrounding text colour rather than the link colour,
    *  for a block that is already inside a coloured surface. */
   inheritLinkColor?: boolean;
+  /** Markdown: the action a citation's Open button fires (a `cite:` link, drawn as a marker with
+   *  a pop-up), with the citation in scope. Undeclared, the pop-up shows without the button. */
+  citeAction?: string;
   /** Input: cap the number of characters accepted. */
   maxLength?: number;
   /** Input: render a multi-line field rather than a single line. */
@@ -206,19 +212,14 @@ export interface UnoverseDefinition {
    *  state entry that mounts a template (`template:`); the loader stamps the mounted
    *  template's own state names as `claims` — the mount state's reaction claim. */
   templates?: Record<string, { template?: string; claims?: string[]; preview?: string[]; director?: Record<string, unknown> } & Record<string, unknown>>;
+  /** The places this app declares. An app with places is drawn by the screen document:
+   *  each interface sits where the server placed it (UNOVERSE_SCREEN.md). */
+  places?: { name: string; holds: "one" | "many" }[];
   defaultLayout?: string;
   /** THE DECLARED STATE ORDER (STATE_MODEL v2 §5 rules 3+5) — the template's priority
    *  ladder and arrival-scan order, served from the manifest. First entry outranks
    *  all below it; no name is special. Absent → legacy v1 recency semantics. */
   stateOrder?: string[];
-  /** THE LATCH, PER STATE (docs/MCP_COMPLETE_GUIDE.md §The Component Latch, moved off the
-   *  manifest 2026-08-31): the states whose wearer the conversation may be ADDRESSED AT,
-   *  keyed by state name, compiled from each state's own `latch:` block.
-   *
-   *  A state absent from this map can never hold the latch, so the SAME instance retracted
-   *  from its page state to an inline one drops the pill by construction. `resolveLatch`
-   *  reads this; nothing about the latch travels on the wire with a render. */
-  latches?: Record<string, { title: string; icon?: string }>;
 }
 
 // ---- The interaction vocabulary (UNOVERSE_SPEC.md §2e-3) ----

package/vendor/sdk/lib/primitives.tsx

@@ -19,7 +19,7 @@
  *     Text/Image (see FRAMEWORK.md), never a composite.
  * ════════════════════════════════════════════════════════════════════════════
  */
-import { createElement, useEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import { createContext, createElement, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from "react";
 import Markdown from "markdown-to-jsx";
 import type { ResolvedTheme, UnoverseNode } from "./core";
 import { styleToCss, cssDecls } from "./style";
@@ -699,6 +699,58 @@ export function InputView({ node, data, theme, onAction }: { node: UnoverseNode;
   );
 }
 
+/**
+ * WHAT A CITATION'S OPEN BUTTON FIRES (docs/unoverse/data/objects/citations-in-answers.md): the
+ * action the Markdown node declares in `citeAction`, with the render data. Carried by context,
+ * not baked into the overrides, so the overrides stay built once per theme and a marker's open
+ * pop-up survives the answer streaming on around it.
+ */
+const CiteContext = createContext<{ action?: string; onAction?: ActionHandler; data: Record<string, unknown> }>({ data: {} });
+
+/**
+ * A CITATION STILL ARRIVING is held back (citations-in-answers.md): while an answer streams, the
+ * tail from an open `[1](cite:` to its closing `)` would draw as a long line of raw link and then
+ * collapse into its marker, jolting the text once per citation. Only the tail is touched, and only
+ * a numbered label (a citation's), so finished text and web links draw exactly as written.
+ */
+const OPEN_CITATION = /\[\d{0,3}(?:\](?:\((?:c(?:i(?:t(?:e(?::[^)\n]*)?)?)?)?)?)?)?$/;
+export function holdOpenCitation(text: string): string {
+  return text.replace(OPEN_CITATION, "");
+}
+
+/**
+ * A CITATION'S QUOTE STAYS ONE CELL (citations-in-answers.md, 2026-09-15): a quote of a table row
+ * carried its pipes ("Total | 10") into the link's title, and inside an answer's own table the
+ * pipe split the row and left the marker raw. Before the markdown is parsed, a pipe inside a
+ * `cite:` link's title becomes a broken bar and a line break a space; the words still read.
+ */
+const CITATION_TITLE = /(\]\(cite:[^)\s]*\s+")([^"]*)("\))/g;
+export function keepCitationsWhole(text: string): string {
+  return text.replace(CITATION_TITLE, (_, open: string, quote: string, close: string) => `${open}${quote.replace(/\|/g, "\u00a6").replace(/\s*\n\s*/g, " ")}${close}`);
+}
+
+/**
+ * WHERE A POP-UP FITS (citations-in-answers.md): the horizontal shift that keeps a box of this
+ * width inside the window from an anchor at `left`, and whether it opens above the anchor
+ * because below there is no room and above there is. A margin keeps it off the very edge.
+ */
+export function fitPopover(anchor: { left: number; top: number; bottom: number }, box: { width: number; height: number }, view: { width: number; height: number }, margin = 8) {
+  const over = anchor.left + box.width - (view.width - margin);
+  const shift = Math.max(over > 0 ? -over : 0, margin - anchor.left);
+  const above = anchor.bottom + box.height + margin > view.height && anchor.top - box.height - margin >= 0;
+  return { shift, above };
+}
+
+/** A `cite:` link's parts: `cite:<document>?part=&page=&doc=`, its title the quoted words. */
+function citationOf(href: string, title?: string) {
+  try {
+    const u = new URL(href);
+    return { document: decodeURIComponent(u.pathname), part: u.searchParams.get("part") ?? "", page: u.searchParams.get("page") ?? "", doc: u.searchParams.get("doc") ?? "", quote: title ?? "" };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * markdown-to-jsx overrides for the `Markdown` primitive.
  *
@@ -734,6 +786,60 @@ function buildMarkdownOverrides(theme: ResolvedTheme, inheritLinkColor = false)
       {linkArrow}
     </a>
   );
+  // A CITATION (citations-in-answers.md): a `cite:` link is a marker after the fact it supports.
+  // Tapped, a pop-up shows the quoted words, the document and the page, and an Open button that
+  // fires the node's `citeAction` with the citation. Behaviour only: every look is a served
+  // prose key (citeAnchor, citeMark, citePopover, citeQuote, citeSource, citeOpen).
+  const CiteMark = ({ href, title, children }: { href: string; title?: string; children?: ReactNode }) => {
+    const [open, setOpen] = useState(false);
+    const box = useRef<HTMLSpanElement>(null);
+    const pop = useRef<HTMLSpanElement>(null);
+    const [place, setPlace] = useState({ shift: 0, above: false });
+    // ALWAYS ON SCREEN: measured as it opens, and again when the window changes size.
+    useLayoutEffect(() => {
+      if (!open) return;
+      const fit = () => {
+        if (!box.current || !pop.current) return;
+        const a = box.current.getBoundingClientRect();
+        setPlace(fitPopover(a, { width: pop.current.offsetWidth, height: pop.current.offsetHeight }, { width: window.innerWidth, height: window.innerHeight }));
+      };
+      fit();
+      window.addEventListener("resize", fit);
+      return () => window.removeEventListener("resize", fit);
+    }, [open]);
+    const { action, onAction, data } = useContext(CiteContext);
+    const c = citationOf(href, title);
+    useEffect(() => {
+      if (!open) return;
+      const away = (e: Event) => { if (box.current && !e.composedPath().includes(box.current)) setOpen(false); };
+      const esc = (e: KeyboardEvent) => { if (e.key === "Escape") setOpen(false); };
+      document.addEventListener("pointerdown", away);
+      document.addEventListener("keydown", esc);
+      return () => { document.removeEventListener("pointerdown", away); document.removeEventListener("keydown", esc); };
+    }, [open]);
+    if (!c) return <>{children}</>;
+    const source = [c.doc, c.page ? `p. ${c.page}` : ""].filter(Boolean).join(" · ");
+    return (
+      <span ref={box} style={s("citeAnchor")}>
+        <button type="button" aria-expanded={open} aria-label={source ? `Source: ${source}` : "Source"} style={s("citeMark")} onClick={() => setOpen((o) => !o)}>
+          {children}
+        </button>
+        {open && (
+          <span ref={pop} role="dialog" style={{ ...s("citePopover"), transform: `translateX(${place.shift}px)`, ...(place.above ? { top: "auto", bottom: "100%" } : {}) }}>
+            {c.quote && <span style={{ display: "block", ...s("citeQuote") }}>“{c.quote}”</span>}
+            {source && <span style={{ display: "block", ...s("citeSource") }}>{source}</span>}
+            {action && onAction && (
+              <button type="button" style={s("citeOpen")} onClick={() => { setOpen(false); onAction(action, { ...data, citation: c }); }}>
+                Open
+              </button>
+            )}
+          </span>
+        )}
+      </span>
+    );
+  };
+  const Link = (a: React.AnchorHTMLAttributes<HTMLAnchorElement>) =>
+    typeof a.href === "string" && a.href.startsWith("cite:") ? <CiteMark href={a.href} title={a.title}>{a.children}</CiteMark> : <ExternalLink {...a} />;
   // Wide tables scroll instead of crushing columns (legacy ScrollableTable).
   const ScrollableTable = (a: React.TableHTMLAttributes<HTMLTableElement>) => (
     <div style={s("tableWrap")}>
@@ -751,7 +857,7 @@ function buildMarkdownOverrides(theme: ResolvedTheme, inheritLinkColor = false)
 
   return {
     p: { props: { style: s("paragraph") } },
-    a: { component: ExternalLink },
+    a: { component: Link },
     table: { component: ScrollableTable },
     img: { component: MarkdownImage },
     // INLINE MARKS and BLOCKS. Authored copy uses all of these (a bolded access code, a
@@ -785,16 +891,19 @@ function buildMarkdownOverrides(theme: ResolvedTheme, inheritLinkColor = false)
  * Container takes node.style (tokens); elements map to served theme tokens via
  * buildMarkdownOverrides. The SDK authors ZERO style values.
  */
-export function MarkdownView({ node, data, theme }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme }): ReactNode {
+export function MarkdownView({ node, data, theme, onAction }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme; onAction?: ActionHandler }): ReactNode {
   const value = (node.bind?.value ? (data[node.bind.value] as string) : "") ?? "";
   // Explicit opt-in ONLY (a CTA pill whose label must match its declared color):
   // `inheritLinkColor: true` on the node. Declaring a body color alone never
   // hijacks anchors — chat prose keeps the served link recipe.
   const inheritLink = (node as { inheritLinkColor?: boolean }).inheritLinkColor === true;
   const overrides = useMemo(() => buildMarkdownOverrides(theme, inheritLink), [theme, inheritLink]);
+  const cite = (node as { citeAction?: string }).citeAction;
   return (
     <div style={styleToCss(node.style, theme, data)}>
-      <Markdown options={{ overrides, forceBlock: true }}>{value}</Markdown>
+      <CiteContext.Provider value={{ action: cite, onAction, data }}>
+        <Markdown options={{ overrides, forceBlock: true }}>{holdOpenCitation(keepCitationsWhole(value))}</Markdown>
+      </CiteContext.Provider>
     </div>
   );
 }

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

@@ -10,6 +10,9 @@
 
 import { useRef, useCallback, useEffect, useState } from "react";
 
+/** How far ahead the first frame is scheduled when nothing is queued. */
+const START_LEAD_SECONDS = 0.2;
+
 /** Decode LPCM (Int16, 24 kHz, mono) → AudioBuffer. */
 function decodeLPCM(audioContext: AudioContext, data: ArrayBuffer): AudioBuffer {
   const sampleRate = 24000;
@@ -69,7 +72,11 @@ export function useAudioPlayback(): UseAudioPlaybackReturn {
       try {
         const audioBuffer = decodeLPCM(audioContext, item.audioData);
         const now = audioContext.currentTime;
-        const startTime = Math.max(now, nextTimeRef.current);
+        // A CUSHION WHEN THE QUEUE IS EMPTY. A vendor that streams at speaking pace (GPT-Live)
+        // sends each frame just as the last one ends, so a frame that is a moment late leaves a
+        // gap, and a gap is heard as a click. Starting a little ahead absorbs that lateness; once
+        // playing, frames join end to end as before.
+        const startTime = nextTimeRef.current > now ? nextTimeRef.current : now + START_LEAD_SECONDS;
 
         const source = audioContext.createBufferSource();
         source.buffer = audioBuffer;

package/vendor/sdk/lib/render.tsx

@@ -132,7 +132,7 @@ export function renderNode(
   // ComponentSlot AND Template keep their appWidth: both are slot-dispatched places
   // whose width applies to their FRAME (app.tsx), not to a box of their own —
   // consuming it here left the mount frame width-less (measured live 2026-08-28).
-  if (panelW && node.type !== "ComponentSlot" && node.type !== "Template") {
+  if (panelW && node.type !== "ComponentSlot" && node.type !== "Template" && node.type !== "Place") {
     const w = cssWidth(theme.appSize?.[panelW] ?? panelW);
     if (w) node = { ...node, appWidth: undefined, style: { ...(node.style ?? {}), width: w, flex: "0 0 auto" } } as UnoverseNode;
   }
@@ -148,8 +148,8 @@ export function renderNode(
   // Orb: procedural thinking/working animation — state is a literal or bound (`bind.state`).
   if (node.type === "Orb") return <OrbView key={key} node={node} data={data} 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" || node.type === "Template") return slot ? slot(node, key) : null;
+  if (node.type === "Markdown") return <MarkdownView key={key} node={node} data={data} theme={theme} onAction={onAction} />;
+  if (node.type === "ComponentSlot" || node.type === "Timeline" || node.type === "Template" || node.type === "Place") return slot ? slot(node, key) : null;
 
   // `Ref` — REFERENCE, NOT COPY. The design system's shared pieces travel once and are
   // cached; a definition names one and specialises it here (core/refs.ts: `props` remap,

package/vendor/sdk/lib/voice.tsx

@@ -23,6 +23,7 @@ import { useAudioCapture } from "./realtime/useAudioCapture";
 import { useAudioPlayback } from "./realtime/useAudioPlayback";
 import type { AudioStateEvent } from "./realtime/types";
 import type { ComponentStore } from "./core";
+import { sessionUserId } from "./connection";
 
 export type VoiceConnectionStatus = "idle" | "connecting" | "connected" | "ended" | "error";
 
@@ -93,8 +94,14 @@ function formatDuration(totalSeconds: number): string {
 }
 
 export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
-  const { apiUrl, session, getAccessToken } = config;
+  const { apiUrl, getAccessToken } = config;
   const wsUrl = config.wsUrl ?? apiUrl.replace(/^http/, "ws");
+  // Same identity as the data plane (connection.tsx): without a token the audio socket is a
+  // guest socket, and the server refuses INIT_SESSION unless the id is guest-prefixed.
+  const session = useMemo(
+    () => ({ ...config.session, userId: sessionUserId(config.session.userId, getAccessToken) }),
+    [config.session, getAccessToken],
+  );
 
   const [connectionStatus, setConnectionStatus] = useState<VoiceConnectionStatus>("idle");
   const [isMuted, setIsMuted] = useState(false);
@@ -130,6 +137,8 @@ export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
         setConnectionStatus("ended");
         setAssistantHint(false);
         setUserSpeaking(false);
+        setIsLookingUp(false);
+        setLookupTool(null);
         playback.markAsLastChunk();
       } else if (state === "TOOL_USE") {
         setIsLookingUp(true);
@@ -204,6 +213,8 @@ export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
     } catch (err: unknown) {
       setError(err instanceof Error ? err.message : "Failed to start call");
       setConnectionStatus("error");
+      setIsLookingUp(false);
+      setLookupTool(null);
     }
   }, [ws, capture, apiUrl, session, getAccessToken]);
 
@@ -219,6 +230,8 @@ export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
     ws.disconnect();
     setConnectionStatus("ended");
     setIsMuted(false);
+    setIsLookingUp(false);
+    setLookupTool(null);
   }, [capture, playback, ws, session.workflowId]);
 
   const toggleMute = useCallback(() => {
@@ -259,14 +272,15 @@ export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
     () => ({
       connectionStatus,
       // The one phase the template branches on — derived from the neutral facts. Order matters:
-      // agent speaking wins over user (barge-in), both win over a lookup, and all three win
-      // over plain "active".
+      // a lookup wins, then agent speaking over user (barge-in), and all three win over plain
+      // "active".
       //
-      // `thinking` sits BELOW both speaking checks because someone actually talking is the more
-      // important fact: a lookup can still be running while the assistant narrates it ("let me
-      // check that for you"), and the surface should show the speech.
+      // `thinking` sits ABOVE speaking because a lookup has a true start and a true end (the
+      // hand-off and its answer), while speaking may have no end at all: GPT-Live sends no
+      // end-of-speech event and streams silence, so speaking can read true for the whole call
+      // and would hide the lookup. Thinking clears on the answer, a hang-up or a dropped call.
       //
-      // It sits ABOVE "active" because that is the bug it fixes. A lookup takes 8 to 9 seconds,
+      // It also sits ABOVE "active" because that is the bug it fixed. A lookup takes 8 to 9 seconds,
       // and for all of it callState read "active" — which every voice template draws as a calm
       // halo meaning "the floor is yours". The orb is the only progress indicator a call has,
       // and it was saying the opposite of what was happening. `isLookingUp` was already right
@@ -274,12 +288,12 @@ export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
       // field the templates branch on.
       callState: (!isCallActive
         ? "idle"
-        : isAssistantSpeaking
-          ? "speaking"
-          : isUserSpeaking
-            ? "listening"
-            : isLookingUp
-              ? "thinking"
+        : isLookingUp
+          ? "thinking"
+          : isAssistantSpeaking
+            ? "speaking"
+            : isUserSpeaking
+              ? "listening"
               : "active") as VoiceCallState,
       isIdle: !isCallActive,
       isCallActive,

package/vite.config.ts

@@ -1,5 +1,5 @@
 /**
- * Local Studio — the standalone developer tool (docs/architecture/LOCAL_STUDIO.md).
+ * Local Studio — the standalone developer tool (docs/architecture/authoring/LOCAL_STUDIO.md).
  *
  * Runs entirely offline against the developer's own project folder. No Postgres, no
  * Redis, no engine, no Docker: the catalog routes are served straight off disk by the