@iloveagents/foundry-web-voice 0.1.0

package/dist/react/voice-module.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `createVoiceModule` — the voice tier as a `bootstrapShell` module.
+ *
+ * The returned object is structurally a `ChatModule`. It is typed locally
+ * rather than imported from `@iloveagents/foundry-web-shell` on purpose: the
+ * shell composes modules, so a module importing the shell would invert the
+ * dependency and make every voice consumer install the shell — including the
+ * ones that build their own runtime. Only the three fields this module
+ * actually populates are declared.
+ */
+import type { ReactNode } from "react";
+import { type VoiceInstallOptions } from "./install.tsx";
+/** The slice of `foundry-web-shell`'s `ChatModule` contract this module fills. */
+export interface VoiceChatModule {
+    name: string;
+    layoutExtras?: ReactNode;
+}
+/**
+ * ```ts
+ * bootstrapShell({
+ *   modules: [
+ *     createVoiceModule({
+ *       connection: { proxyUrl: import.meta.env.VITE_VOICE_PROXY_URL },
+ *       session: sessionConfig().voice("en-US-AvaMultilingualNeural").build(),
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * Call it once, at module scope, next to the other modules — the voice
+ * adapter is registered as a side effect of the call, before the runtime
+ * first mounts.
+ */
+export declare function createVoiceModule(options: VoiceInstallOptions): VoiceChatModule;

package/dist/react/voice-module.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { installVoice } from "./install.js";
+/**
+ * ```ts
+ * bootstrapShell({
+ *   modules: [
+ *     createVoiceModule({
+ *       connection: { proxyUrl: import.meta.env.VITE_VOICE_PROXY_URL },
+ *       session: sessionConfig().voice("en-US-AvaMultilingualNeural").build(),
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * Call it once, at module scope, next to the other modules — the voice
+ * adapter is registered as a side effect of the call, before the runtime
+ * first mounts.
+ */
+export function createVoiceModule(options) {
+    const { Host } = installVoice(options);
+    return {
+        name: "foundry-voice",
+        layoutExtras: _jsx(Host, {}),
+    };
+}

package/dist/react/voice-stage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What you look at while you are talking.
+ *
+ * A live call replaces the conversation rather than adding to it: the
+ * transcript scrolling past is not the thing you are attending to, and the
+ * empty-state "How can I help you today?" is actively wrong once the answer
+ * to that question is "say it out loud". The thread is not lost — it is
+ * behind this, and comes straight back when the call ends. In `relay` the
+ * turns are already in it; in `realtime` assistant-ui keeps them there for
+ * the life of the session.
+ *
+ * Everything here is theme tokens and the session's own state, so it
+ * inherits an app's palette without being told about it.
+ */
+export interface VoiceStageProps {
+    /** Overrides the live session's avatar streams (rarely needed). */
+    videoStream?: MediaStream | null;
+    audioStream?: MediaStream | null;
+}
+export declare function VoiceStage(props?: VoiceStageProps): import("react/jsx-runtime").JSX.Element;

package/dist/react/voice-stage.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * What you look at while you are talking.
+ *
+ * A live call replaces the conversation rather than adding to it: the
+ * transcript scrolling past is not the thing you are attending to, and the
+ * empty-state "How can I help you today?" is actively wrong once the answer
+ * to that question is "say it out loud". The thread is not lost — it is
+ * behind this, and comes straight back when the call ends. In `relay` the
+ * turns are already in it; in `realtime` assistant-ui keeps them there for
+ * the life of the session.
+ *
+ * Everything here is theme tokens and the session's own state, so it
+ * inherits an app's palette without being told about it.
+ */
+import { useVoiceState } from "@assistant-ui/react";
+import { VoiceVisualizer } from "./voice-visualizer.js";
+import { VoiceAvatarPanel } from "./voice-avatar.js";
+import { useVoiceUiStore } from "./voice-ui-store.js";
+export function VoiceStage(props = {}) {
+    // Read from the store by default, so the stage can be registered as a
+    // bare component reference rather than a closure that has to be
+    // re-registered every time a stream arrives.
+    const liveVideo = useVoiceUiStore((s) => s.videoStream);
+    const liveAudio = useVoiceUiStore((s) => s.audioStream);
+    // `undefined` means "not specified, use the live session". An explicit
+    // `null` is a host saying "show no avatar / play no audio here", which the
+    // props contract allows and `??` silently ignored — it treats both the same
+    // and handed the live streams back either way.
+    const videoStream = props.videoStream === undefined ? liveVideo : props.videoStream;
+    const audioStream = props.audioStream === undefined ? liveAudio : props.audioStream;
+    const voice = useVoiceState();
+    const analyser = useVoiceUiStore((s) => s.analyser);
+    const sessionState = useVoiceUiStore((s) => s.sessionState);
+    const connectionState = useVoiceUiStore((s) => s.connectionState);
+    const userText = useVoiceUiStore((s) => s.userText);
+    const assistantText = useVoiceUiStore((s) => s.assistantText);
+    const chromaKey = useVoiceUiStore((s) => s.chromaKey);
+    const connecting = !voice || voice.status.type === "starting";
+    const muted = voice?.isMuted ?? false;
+    const status = connecting
+        ? "Connecting…"
+        : connectionState === "reconnecting"
+            ? "Reconnecting…"
+            : muted
+                ? "Microphone muted"
+                : sessionState === "thinking"
+                    ? "Thinking…"
+                    : sessionState === "speaking"
+                        ? "Speaking"
+                        : "Listening";
+    // While the assistant talks the visualiser is showing its voice, so the
+    // caption should be its words; otherwise show what was just heard.
+    const caption = sessionState === "speaking" ? assistantText : userText;
+    return (_jsxs("div", { className: "relative flex h-full min-h-full flex-col", children: [_jsx("div", { className: "relative min-h-0 flex-1 overflow-hidden", children: videoStream ? (
+                // Full-bleed and anchored to the top, so the avatar is framed head
+                // and torso with the legs running off the lower edge — the framing
+                // a person on a call has, rather than a full-length figure floating
+                // in the middle of the page. The `!` overrides the SDK canvas's
+                // inline `height:auto; object-fit:contain`.
+                _jsx(VoiceAvatarPanel, { videoStream: videoStream, audioStream: audioStream, chromaKeyConfig: chromaKey ?? undefined, className: "absolute inset-0", canvasClassName: "h-full! w-full! max-h-none! max-w-none! object-cover! object-top!" })) : (_jsx("div", { className: "absolute inset-0 flex items-center justify-center", children: _jsx(VoiceVisualizer, { analyser: connecting || muted ? null : analyser, label: `Voice conversation — ${status}`, className: "h-full max-h-80 w-full max-w-md" }) })) }), _jsxs("div", { className: "relative shrink-0 px-6 pb-8 pt-4 text-center", children: [_jsx("p", { className: "text-sm text-muted-foreground", role: "status", "aria-live": "polite", children: status }), _jsx("p", { className: "mx-auto mt-2 flex h-14 max-w-xl items-start justify-center overflow-hidden " +
+                            "text-lg leading-7 " +
+                            (caption ? "text-foreground/90" : "text-sm leading-7 text-muted-foreground/70"), children: _jsx("span", { className: "line-clamp-2", children: caption || "Say something to get started." }) })] })] }));
+}

package/dist/react/voice-status-strip.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A one-line "what is the session doing right now" strip, rendered in the
+ * composer banner slot while a voice session is live.
+ *
+ * Listening / speaking come from the runtime's own voice state; `thinking`
+ * and `reconnecting` have no runtime equivalent and come from the SDK.
+ * Without this, the gap between the user finishing a sentence and the
+ * assistant starting to speak is indistinguishable from a dead session.
+ */
+export declare function VoiceStatusStrip(): import("react/jsx-runtime").JSX.Element | null;

package/dist/react/voice-status-strip.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A one-line "what is the session doing right now" strip, rendered in the
+ * composer banner slot while a voice session is live.
+ *
+ * Listening / speaking come from the runtime's own voice state; `thinking`
+ * and `reconnecting` have no runtime equivalent and come from the SDK.
+ * Without this, the gap between the user finishing a sentence and the
+ * assistant starting to speak is indistinguishable from a dead session.
+ */
+import { useVoiceState } from "@assistant-ui/react";
+import { useVoiceUiStore } from "./voice-ui-store.js";
+export function VoiceStatusStrip() {
+    const voice = useVoiceState();
+    const sessionState = useVoiceUiStore((s) => s.sessionState);
+    const connectionState = useVoiceUiStore((s) => s.connectionState);
+    if (!voice || voice.status.type === "ended")
+        return null;
+    const label = voice.status.type === "starting"
+        ? "Connecting…"
+        : connectionState === "reconnecting"
+            ? "Reconnecting…"
+            : voice.isMuted
+                ? "Microphone muted"
+                : sessionState === "thinking"
+                    ? "Thinking…"
+                    : voice.mode === "speaking"
+                        ? "Speaking…"
+                        : "Listening…";
+    return (_jsxs("div", { className: "flex items-center gap-2 px-4 py-1.5 text-xs text-muted-foreground", role: "status", "aria-live": "polite", children: [_jsx("span", { "aria-hidden": "true", className: `size-1.5 rounded-full bg-primary ${voice.isMuted ? "" : "animate-pulse"}` }), label] }));
+}

package/dist/react/voice-surface.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `VoiceSurface` — the render-less host that owns the Voice Live session.
+ *
+ * `useVoiceLive` is a hook, so the session can only exist inside a mounted
+ * component; assistant-ui's `RealtimeVoiceAdapter.connect()` is imperative
+ * and may be called at any moment after that. This component is the join:
+ * it mounts the hook once (inert — `autoConnect` is off, nothing touches the
+ * microphone until the user asks) and publishes its controls to the bridge,
+ * which is what the adapter awaits.
+ *
+ * Every callback handed to the hook is stable and closes over nothing but
+ * the bridge, so none of them can go stale for the life of a session.
+ */
+import type { VoiceBridge } from "../adapter/voice-bridge.ts";
+import type { VoiceConfig } from "../adapter/types.ts";
+export interface VoiceSurfaceProps {
+    bridge: VoiceBridge;
+    config: VoiceConfig;
+    /** Render the avatar panel when the session config asks for an avatar. @default true */
+    avatar?: boolean;
+    /**
+     * Replace the chat thread with the voice stage while a call is live.
+     * @default true
+     */
+    stage?: boolean;
+}
+export declare function VoiceSurface({ bridge, config, avatar, stage }: VoiceSurfaceProps): import("react/jsx-runtime").JSX.Element;

package/dist/react/voice-surface.js

@@ -0,0 +1,289 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * `VoiceSurface` — the render-less host that owns the Voice Live session.
+ *
+ * `useVoiceLive` is a hook, so the session can only exist inside a mounted
+ * component; assistant-ui's `RealtimeVoiceAdapter.connect()` is imperative
+ * and may be called at any moment after that. This component is the join:
+ * it mounts the hook once (inert — `autoConnect` is off, nothing touches the
+ * microphone until the user asks) and publishes its controls to the bridge,
+ * which is what the adapter awaits.
+ *
+ * Every callback handed to the hook is stable and closes over nothing but
+ * the bridge, so none of them can go stale for the life of a session.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useVoiceLive } from "@iloveagents/foundry-voice-live-react";
+import { clientToolRegistry } from "@iloveagents/foundry-agent";
+import { registerChatSlots, submitComposerText, useChatSlotsStore, } from "@iloveagents/foundry-web-ui";
+import { buildVoiceSession } from "../adapter/session-config.js";
+import { createRegistryToolExecutor } from "../adapter/tool-bridge.js";
+import { ToolSync } from "../adapter/tool-sync.js";
+import { HalfDuplexGate } from "../adapter/half-duplex.js";
+import { RelayAnswerWatcher } from "./relay-answer-watcher.js";
+import { VoiceAvatarPanel } from "./voice-avatar.js";
+import { VoiceStage } from "./voice-stage.js";
+import { needsAudioOnlySink } from "./audio-ownership.js";
+import { VoiceAudioSink } from "./voice-audio-sink.js";
+import { useDirectAudioOutput } from "./use-direct-audio-output.js";
+import { resetVoiceSessionState, useVoiceUiStore } from "./voice-ui-store.js";
+export function VoiceSurface({ bridge, config, avatar = true, stage = true }) {
+    const mode = config.mode ?? "relay";
+    const wantsTools = mode === "realtime" && (config.exposeClientTools ?? true);
+    const session = useMemo(() => buildVoiceSession({
+        mode,
+        overrides: config.session,
+        registry: wantsTools ? clientToolRegistry.getState() : undefined,
+    }), [mode, config.session, wantsTools]);
+    const onEvent = useCallback((event) => bridge.handleServerEvent(event), [bridge]);
+    const onTranscript = useCallback((role, text, isFinal) => {
+        bridge.handleTranscript(role, text, isFinal);
+        // The stage shows what is being said right now; a final empty string
+        // is a VAD misfire and would blank the line for no reason.
+        if (text.trim() || !isFinal) {
+            useVoiceUiStore.setState(role === "user" ? { userText: text } : { assistantText: text });
+        }
+    }, [bridge]);
+    const toolExecutor = useMemo(() => (wantsTools ? createRegistryToolExecutor(clientToolRegistry.getState()) : undefined), [wantsTools]);
+    const live = useVoiceLive({
+        connection: config.connection,
+        session,
+        autoConnect: false,
+        logLevel: config.logLevel,
+        reconnect: config.reconnect,
+        onEvent,
+        onTranscript,
+        toolExecutor,
+    });
+    // The hook returns a fresh object every render; the controls handed to the
+    // bridge must not. Route them through a ref so `attach` happens once and
+    // still reaches the current session.
+    const liveRef = useRef(live);
+    liveRef.current = live;
+    const controls = useMemo(() => ({
+        connect: () => liveRef.current.connect(),
+        disconnect: () => liveRef.current.disconnect(),
+        mute: () => {
+            if (!liveRef.current.isMuted)
+                liveRef.current.toggleMute();
+        },
+        unmute: () => {
+            if (liveRef.current.isMuted)
+                liveRef.current.toggleMute();
+        },
+        sendEvent: (event) => liveRef.current.sendEvent(event),
+        cancelResponse: () => liveRef.current.cancelResponse(),
+        getAnalyser: () => liveRef.current.audioAnalyser,
+    }), []);
+    useEffect(() => {
+        const detach = bridge.attach(controls);
+        return () => {
+            detach();
+            // Losing the host ends the call. Nothing else can do it from here: the
+            // disconnected-state effect below cannot run after unmount, so without
+            // this a conditionally-rendered <FoundryVoice/> (or any host removed
+            // mid-call) leaves assistant-ui holding a running voice session and the
+            // speech queue wedged for whatever mounts next.
+            bridge.handleClosed();
+        };
+    }, [bridge, controls]);
+    useEffect(() => {
+        bridge.setSubmitText(mode === "relay" ? submitComposerText : null);
+        return () => bridge.setSubmitText(null);
+    }, [bridge, mode]);
+    // Keep the voice model's tool catalogue in step with the page's. Page
+    // tools are registered and cleared on navigation, so a catalogue frozen
+    // at connect time leaves the model either unable to act on the page the
+    // user is looking at, or calling a tool that no longer exists.
+    //
+    // Keyed on `isReady`, not just mounted: a registry change that happens
+    // while the session is still connecting used to be dropped by an
+    // is-ready guard and never replayed. Re-running on the ready edge and
+    // syncing immediately closes that window, and `ToolSync`'s dedupe makes
+    // the extra call free when nothing actually changed.
+    const hostToolsKey = JSON.stringify(config.session?.tools ?? null);
+    const toolSync = useRef(null);
+    toolSync.current ?? (toolSync.current = new ToolSync((tools) => liveRef.current.updateSession({ tools })));
+    useEffect(() => {
+        const sync = toolSync.current;
+        if (!sync)
+            return;
+        if (!wantsTools || !live.isReady) {
+            // The next session sends its own catalogue; forget what this one did.
+            sync.reset();
+            return;
+        }
+        const hostTools = config.session?.tools;
+        sync.sync(clientToolRegistry.getState(), hostTools);
+        return clientToolRegistry.subscribe(() => sync.sync(clientToolRegistry.getState(), hostTools));
+        // Keyed on the host tools' CONTENT, not the array's identity: a host that
+        // rebuilds its config object every render would otherwise resubscribe on
+        // every render for a catalogue that never changed.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [wantsTools, live.isReady, hostToolsKey]);
+    // Half-duplex: hold the microphone closed while the assistant speaks, so
+    // its own voice cannot trip the service's VAD and start a conversation
+    // with itself. The when-to-open/close decision lives in `HalfDuplexGate`
+    // (pure, tested) — the two rules that matter, releasing only what the gate
+    // took and never overriding the user's own mute, are exactly the ones an
+    // inline pair of booleans got wrong.
+    const halfDuplexGate = useRef(new HalfDuplexGate());
+    useEffect(() => {
+        const action = halfDuplexGate.current.next({
+            enabled: !!config.halfDuplex,
+            speaking: live.sessionState === "speaking",
+            sdkMuted: live.isMuted,
+            userMuted: bridge.isUserMuted,
+        });
+        if (action === "mute" && !liveRef.current.isMuted)
+            liveRef.current.toggleMute();
+        else if (action === "unmute" && liveRef.current.isMuted)
+            liveRef.current.toggleMute();
+    }, [bridge, config.halfDuplex, live.sessionState, live.isMuted]);
+    // Publish session facts the UI reads (mic button, status strip). The
+    // bridge is the adapter's channel; this store is the components'.
+    const sessionState = live.sessionState;
+    useEffect(() => {
+        bridge.handleSessionState(sessionState);
+        useVoiceUiStore.setState({ sessionState });
+    }, [bridge, sessionState]);
+    useEffect(() => {
+        useVoiceUiStore.setState({
+            connectionState: live.connectionState,
+            isMuted: live.isMuted,
+            isReady: live.isReady,
+            analyser: live.audioAnalyser,
+            videoStream: live.videoStream,
+            audioStream: live.audioStream,
+        });
+    }, [
+        live.connectionState,
+        live.isMuted,
+        live.isReady,
+        live.audioAnalyser,
+        live.videoStream,
+        live.audioStream,
+    ]);
+    // A finished session must not leak into the next one: stale captions, a
+    // dead analyser, and an outstanding auto-mute are all last-call state.
+    useEffect(() => {
+        if (live.connectionState === "disconnected") {
+            // A fatal error and the disconnect can be published together, and this
+            // effect is declared first, so it would end the session as "finished"
+            // before the error effect below ever ran — and assistant-ui's `end()` is
+            // once-only, so the reason could never be corrected. A consumer would
+            // see a clean hang-up where the call had actually failed. Report the
+            // error here, on the way past, so whichever arrives wins honestly.
+            if (live.error && live.error !== reportedError.current) {
+                reportedError.current = live.error;
+                bridge.handleError(live.error);
+            }
+            // End the adapter session too, not just our own UI state. Without this
+            // a clean remote close (or exhausted reconnects) left `bridge.connected`
+            // true and assistant-ui's voice session `running`: the controls kept
+            // showing a live call and relay answers were queued to a dead transport.
+            bridge.handleClosed();
+            halfDuplexGate.current.reset();
+            resetVoiceSessionState();
+        }
+    }, [bridge, live.connectionState, live.error]);
+    // Host chroma-key tuning travels through the store because the stage is
+    // registered as a bare component reference, not a closure over config.
+    useEffect(() => {
+        useVoiceUiStore.setState({ chromaKey: config.chromaKey ?? null });
+    }, [config.chromaKey]);
+    // Hand the thread over to the stage for the duration of the call, and hand
+    // it straight back afterwards. Registering the component IS the takeover,
+    // so there is no second "is it active" flag to keep in step.
+    const callLive = live.connectionState === "connected" || live.connectionState === "reconnecting";
+    useEffect(() => {
+        if (!stage)
+            return;
+        // Last-registration-wins: another module may take the slot while a call is
+        // running, so every path that CLEARS has to check we still own it. Guarding
+        // only the cleanup was not enough — ending a call re-runs this effect with
+        // `callLive` false, and the body cleared the slot on the way past.
+        const releaseIfOurs = () => {
+            if (useChatSlotsStore.getState().threadSurface === VoiceStage) {
+                registerChatSlots({ threadSurface: null });
+            }
+        };
+        if (callLive)
+            registerChatSlots({ threadSurface: VoiceStage });
+        else
+            releaseIfOurs();
+        return releaseIfOurs;
+    }, [stage, callLive]);
+    // Surface a session-fatal error once. `error` stays set until the next
+    // connect, so re-reporting it on every render would end the session
+    // repeatedly and spam the host's callback.
+    const reportedError = useRef(null);
+    useEffect(() => {
+        if (live.error && live.error !== reportedError.current) {
+            reportedError.current = live.error;
+            bridge.handleError(live.error);
+        }
+        else if (!live.error) {
+            reportedError.current = null;
+        }
+    }, [bridge, live.error]);
+    // Who plays the audio, and how.
+    //
+    // Avatar: `VoiceLiveAvatar` owns an element and the audio arrives with the
+    // video. WebRTC: the stream is a remote track, which only an element can
+    // play. Otherwise the audio is PCM this browser decoded itself, and it
+    // goes straight out through Web Audio — see `useDirectAudioOutput` for why
+    // that is worth doing rather than attaching the MediaStream.
+    // Whether an element is needed follows from what the SESSION negotiated, not
+    // from whether we chose to show a face. A host that configures an avatar but
+    // hides the panel (`avatar: false`) still receives the assistant's voice as a
+    // remote track, and routing that through Web Audio as if it were locally
+    // decoded PCM plays nothing at all — the assistant simply goes silent.
+    const hasAvatar = !!session.avatar;
+    const showAvatar = avatar && hasAvatar;
+    const isWebRtc = config.connection.transport === "webrtc";
+    const needsElement = hasAvatar || isWebRtc;
+    useDirectAudioOutput(!needsElement, live.audioContext, live.audioAnalyser);
+    // Whether a sink is needed depends on whether an avatar element is ACTUALLY
+    // mounted, not on whether we intended one. With `stage: true` the avatar is
+    // drawn by the registered stage, and the chat surface can take that stage
+    // down — closing the floating panel does exactly that — while the call
+    // deliberately continues. Keyed off intent, the sink stayed absent and the
+    // assistant went silent until the panel was reopened.
+    const avatarPanels = useVoiceUiStore((s) => s.avatarPanels);
+    // Who plays the remote stream while an avatar is appearing or disappearing.
+    //
+    // A panel registers itself in an effect, so the count cannot answer this on
+    // the commit where an avatar mounts — it is still zero while
+    // `VoiceLiveAvatar` is mounting its own audio element, and a sink mounted
+    // alongside gives the stream two owners and starts it twice. What IS known
+    // synchronously is that a panel renders exactly when there is a video
+    // stream to draw, so an element can be predicted rather than observed.
+    //
+    // The prediction can still be wrong in one direction: with `stage: true` the
+    // panel is drawn by a registered chat slot, and the surrounding surface may
+    // not be on screen at all (a closed bubble). So if nothing has registered by
+    // the next tick, the prediction is abandoned and the sink takes the audio
+    // back — which is the case that made an ongoing call go silent.
+    const avatarElementExpected = showAvatar && !!live.videoStream;
+    const [predictionFailed, setPredictionFailed] = useState(false);
+    useEffect(() => {
+        if (!avatarElementExpected || avatarPanels > 0) {
+            setPredictionFailed(false);
+            return;
+        }
+        const settle = setTimeout(() => setPredictionFailed(true), 0);
+        return () => clearTimeout(settle);
+    }, [avatarElementExpected, avatarPanels]);
+    const sinkNeeded = needsAudioOnlySink({
+        needsElement,
+        avatarPanels,
+        avatarElementExpected,
+        predictionFailed,
+    });
+    return (_jsxs(_Fragment, { children: [mode === "relay" ? _jsx(RelayAnswerWatcher, { bridge: bridge }) : null, showAvatar && !stage ? (
+            // With the stage on, the avatar is drawn there instead of floating.
+            _jsx(VoiceAvatarPanel, { videoStream: live.videoStream, audioStream: live.audioStream, 
+                // Tuning must not depend on where the avatar happens to be drawn.
+                chromaKeyConfig: config.chromaKey ?? undefined })) : sinkNeeded ? (_jsx(VoiceAudioSink, { stream: live.audioStream })) : null] }));
+}

package/dist/react/voice-ui-store.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Session facts the voice UI reads.
+ *
+ * Distinct from the bridge, deliberately: the bridge is the channel to
+ * assistant-ui's runtime (transcripts, mode, volume, status), while this is
+ * the channel to *our* components (the mic button's tooltip, the status
+ * strip's wording). Mixing them would make the mic button re-render on every
+ * transcript delta and put UI copy inside the protocol layer.
+ *
+ * Status the runtime already owns — connected, muted, listening vs speaking —
+ * is read from ``useVoiceState()`` / ``useVoiceVolume()``. What lives here is
+ * only what the runtime has no concept of: the SDK's finer-grained session
+ * state (``thinking``) and its connection lifecycle (``reconnecting``).
+ */
+import type { ChromaKeyConfig, ConnectionState, SessionState } from "@iloveagents/foundry-voice-live-react";
+interface VoiceUiState {
+    connectionState: ConnectionState;
+    sessionState: SessionState;
+    isMuted: boolean;
+    isReady: boolean;
+    /** Live output analyser, for the visualiser. Null between sessions. */
+    analyser: AnalyserNode | null;
+    /**
+     * The last thing each side said, for the voice stage.
+     *
+     * Only the latest line: the stage is something you glance at while
+     * talking, not a transcript to read. The thread is where history lives —
+     * in `relay` these turns are already there, and in `realtime` assistant-ui
+     * puts them there for the life of the session.
+     */
+    userText: string;
+    assistantText: string;
+    /** Avatar streams, when the session was configured with one. */
+    videoStream: MediaStream | null;
+    audioStream: MediaStream | null;
+    /** Host chroma-key tuning, forwarded to the avatar wherever it renders. */
+    chromaKey: ChromaKeyConfig | null;
+    /**
+     * How many `VoiceAvatarPanel`s are mounted right now.
+     *
+     * Who plays the audio cannot be decided from configuration alone. The stage
+     * is registered as a chat slot, so the surrounding chat surface decides
+     * whether it is rendered — and a floating panel closing while the call
+     * deliberately continues takes the avatar's element down with it. A count
+     * kept by the panels themselves is the only thing that knows.
+     */
+    avatarPanels: number;
+}
+export declare const useVoiceUiStore: import("zustand").UseBoundStore<import("zustand").StoreApi<VoiceUiState>>;
+/**
+ * Everything a finished session leaves behind. Without this, the next call
+ * opens on the previous call's caption and a dead analyser — stale by
+ * definition, and visibly so on the stage.
+ */
+export declare function resetVoiceSessionState(): void;
+/** Called by `VoiceAvatarPanel` as it mounts and unmounts. */
+export declare function trackAvatarPanel(delta: 1 | -1): void;
+export {};

package/dist/react/voice-ui-store.js

@@ -0,0 +1,46 @@
+/**
+ * Session facts the voice UI reads.
+ *
+ * Distinct from the bridge, deliberately: the bridge is the channel to
+ * assistant-ui's runtime (transcripts, mode, volume, status), while this is
+ * the channel to *our* components (the mic button's tooltip, the status
+ * strip's wording). Mixing them would make the mic button re-render on every
+ * transcript delta and put UI copy inside the protocol layer.
+ *
+ * Status the runtime already owns — connected, muted, listening vs speaking —
+ * is read from ``useVoiceState()`` / ``useVoiceVolume()``. What lives here is
+ * only what the runtime has no concept of: the SDK's finer-grained session
+ * state (``thinking``) and its connection lifecycle (``reconnecting``).
+ */
+import { create } from "zustand";
+export const useVoiceUiStore = create(() => ({
+    connectionState: "disconnected",
+    sessionState: "idle",
+    isMuted: false,
+    isReady: false,
+    analyser: null,
+    userText: "",
+    assistantText: "",
+    videoStream: null,
+    audioStream: null,
+    chromaKey: null,
+    avatarPanels: 0,
+}));
+/**
+ * Everything a finished session leaves behind. Without this, the next call
+ * opens on the previous call's caption and a dead analyser — stale by
+ * definition, and visibly so on the stage.
+ */
+export function resetVoiceSessionState() {
+    useVoiceUiStore.setState({
+        userText: "",
+        assistantText: "",
+        analyser: null,
+        videoStream: null,
+        audioStream: null,
+    });
+}
+/** Called by `VoiceAvatarPanel` as it mounts and unmounts. */
+export function trackAvatarPanel(delta) {
+    useVoiceUiStore.setState((s) => ({ avatarPanels: Math.max(0, s.avatarPanels + delta) }));
+}

package/dist/react/voice-visualizer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The listening/speaking indicator: concentric rings breathing with the
+ * audio level.
+ *
+ * Three things it does that a canvas visualiser usually gets wrong:
+ *
+ * - **It wears the theme, and notices when the theme changes.** Colours are
+ *   read from the app's CSS custom properties (`--primary`,
+ *   `--muted-foreground`) rather than baked in. A canvas cannot inherit a CSS
+ *   variable the way a DOM node does, so it re-reads them: periodically while
+ *   animating (a theme-layer swap lands as inline style on an ancestor, which
+ *   no root-element observer can see), and on a root class / `data-theme` /
+ *   OS-scheme change for the static case, where no loop is running to notice.
+ *   Opacity comes from `globalAlpha`, not from building `rgba()` strings, so
+ *   any colour format the design system uses — `oklch`, `hsl`, hex — works
+ *   untouched.
+ * - **It matches the device.** The backing store is sized in device pixels
+ *   and scaled, so the rings are not soft on a retina display; a
+ *   `ResizeObserver` keeps that true when the pane is resized.
+ * - **It stops.** No analyser, a hidden tab, or `prefers-reduced-motion` and
+ *   the animation loop is not running at all — a decorative
+ *   `requestAnimationFrame` that never yields is a battery drain on a page
+ *   people leave open.
+ */
+export interface VoiceVisualizerProps {
+    /** Analyser from the live session; `null` renders the idle state. */
+    analyser: AnalyserNode | null;
+    /**
+     * Extra re-read trigger for theme systems the built-in observation cannot
+     * see (root attributes and the OS scheme are watched automatically).
+     */
+    themeKey?: string;
+    className?: string;
+    /** Accessible description of what the animation represents. */
+    label?: string;
+}
+export declare function VoiceVisualizer({ analyser, themeKey, className, label, }: VoiceVisualizerProps): import("react/jsx-runtime").JSX.Element;