@theoremjs/react 0.0.0-stage → 0.3.1

package/components/live/use-live-runner-model.js

@@ -0,0 +1,190 @@
+import { liveIngressEnabledFromSpec } from '@theoremjs/agents';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { stashLiveCaptionCall, } from "../../client/live/live-captions.js";
+import { liveState } from "../../client/live/live-state.js";
+import { createTraceFeed } from "../../client/trace-feed.js";
+import { usePageToolWarnings } from "../../hooks/use-page-tool-warnings.js";
+import { useLiveRunnerControls } from "./use-live-runner-controls.js";
+import { useLiveRunnerGate, useLiveRunnerUiState } from "./use-live-runner-ui.js";
+import { useLiveSessionClient } from "./use-live-session-client.js";
+/**
+ * Calls start from the landing (voice, or video + voice), not on mount. Once
+ * started, the call view stays until a reload; ending leaves Start call. Each
+ * restart is a new conversation; earlier calls' captions stay, above a divider.
+ */
+function useLiveCallLifecycle(controls, captionsRef, sessionActive, videoAvailable) {
+    const [callStarted, setCallStarted] = useState(false);
+    const [ended, setEnded] = useState(false);
+    const videoOnConnectRef = useRef(false);
+    const startCall = useCallback((options) => {
+        videoOnConnectRef.current = options.video && videoAvailable;
+        setCallStarted(true);
+        setEnded(false);
+        void controls.startSession();
+    }, [controls, videoAvailable]);
+    // why: Camera capture needs a live session, so a video call turns it on once connected.
+    useEffect(() => {
+        if (!sessionActive || !videoOnConnectRef.current)
+            return;
+        videoOnConnectRef.current = false;
+        void controls.handleToggleVideo();
+    }, [controls, sessionActive]);
+    const handleEnd = useCallback(() => {
+        videoOnConnectRef.current = false;
+        controls.teardownSession();
+        setEnded(true);
+    }, [controls]);
+    const [pastCalls, setPastCalls] = useState([]);
+    const handleRestart = useCallback(async () => {
+        const previous = captionsRef.current.turns;
+        setPastCalls((calls) => stashLiveCaptionCall(calls, previous));
+        setEnded(false);
+        await controls.handleRestart();
+    }, [controls, captionsRef]);
+    const teardownSessionRef = useRef(controls.teardownSession);
+    teardownSessionRef.current = controls.teardownSession;
+    useEffect(() => {
+        return () => {
+            teardownSessionRef.current();
+        };
+    }, []);
+    return { callStarted, ended, pastCalls, startCall, handleEnd, handleRestart };
+}
+/**
+ * Owns LiveRunner state, session client, and stage callbacks.
+ * `connection` resolves what the call opens: a host with a fixed profile returns
+ * its id; the studio returns its draft as the relay's open message. `options`
+ * are the host's part in the call: its slots, the page's context, and its page tools.
+ */
+export function useLiveRunnerModel(iface, connection, options = {}) {
+    const ui = useLiveRunnerUiState(iface.labels);
+    const gate = useLiveRunnerGate({
+        setCaptions: ui.setCaptions,
+        setActiveTool: ui.setActiveTool,
+        reportFailure: ui.reportFailure,
+    });
+    const connectionRef = useRef(connection);
+    connectionRef.current = connection;
+    const voiceAvailable = liveIngressEnabledFromSpec(iface.live.ingress, 'audio');
+    const videoAvailable = liveIngressEnabledFromSpec(iface.live.ingress, 'video');
+    const textAvailable = liveIngressEnabledFromSpec(iface.live.ingress, 'text');
+    const state = useMemo(() => liveState({
+        status: ui.status,
+        connectPhase: ui.connectPhase,
+        toolName: ui.activeTool,
+        isMuted: ui.isMuted,
+        voiceEnabled: voiceAvailable,
+    }), [ui.activeTool, ui.connectPhase, ui.isMuted, ui.status, voiceAvailable]);
+    // why: One feed per runner: every session it opens adds its records.
+    const traces = useMemo(createTraceFeed, []);
+    const { clientRef, ensureClient, clearClient } = useLiveSessionClient({
+        slots: options.slots,
+        context: options.context,
+        pageTools: options.pageTools,
+        voiceAvailable,
+        traces,
+        handleLiveTurnEvent: gate.handleLiveTurnEvent,
+        waitForGateDecision: gate.waitForGateDecision,
+        gatePromptRef: gate.gatePromptRef,
+        isMutedRef: ui.isMutedRef,
+        sessionPermissionsRef: ui.sessionPermissionsRef,
+        videoCaptureRef: ui.videoCaptureRef,
+        setConnectPhase: ui.setConnectPhase,
+        setStatus: ui.setStatus,
+        setSessionActive: ui.setSessionActive,
+        reportFailure: ui.reportFailure,
+        clearFailure: ui.clearFailure,
+        reportSessionEnded: ui.reportSessionEnded,
+        clearSessionEnded: ui.clearSessionEnded,
+        setCaptions: ui.setCaptions,
+        setInputLevel: ui.setInputLevel,
+        setOutputLevel: ui.setOutputLevel,
+        setActiveTool: ui.setActiveTool,
+        setSessionPermissions: ui.setSessionPermissions,
+        setVideoPreview: ui.setVideoPreview,
+        setVideoFacingMode: ui.setVideoFacingMode,
+        setIsVideoOn: ui.setIsVideoOn,
+    });
+    const controls = useLiveRunnerControls({
+        clientRef,
+        videoCaptureRef: ui.videoCaptureRef,
+        connectionRef,
+        statusRef: ui.statusRef,
+        isMutedRef: ui.isMutedRef,
+        sessionPermissionsRef: ui.sessionPermissionsRef,
+        ensureClient,
+        clearClient,
+        cancelGateDecision: gate.cancelGateDecision,
+        stopVideo: ui.stopVideo,
+        resetCaptions: ui.resetCaptions,
+        sessionActive: ui.sessionActive,
+        textAvailable,
+        videoAvailable,
+        voiceAvailable,
+        isVideoOn: ui.isVideoOn,
+        textDraft: ui.textDraft,
+        setTextDraft: ui.setTextDraft,
+        setCaptions: ui.setCaptions,
+        reportFailure: ui.reportFailure,
+        clearFailure: ui.clearFailure,
+        setIsMuted: ui.setIsMuted,
+        setSessionActive: ui.setSessionActive,
+        setSessionPermissions: ui.setSessionPermissions,
+        setStatus: ui.setStatus,
+        setConnectPhase: ui.setConnectPhase,
+        setInputLevel: ui.setInputLevel,
+        setOutputLevel: ui.setOutputLevel,
+        setVideoPreview: ui.setVideoPreview,
+        setVideoFacingMode: ui.setVideoFacingMode,
+        setIsVideoOn: ui.setIsVideoOn,
+    });
+    const { callStarted, ended, pastCalls, startCall, handleEnd, handleRestart } = useLiveCallLifecycle(controls, ui.captionsRef, ui.sessionActive, videoAvailable);
+    // why: The page's context is compared by value, so a host may build it inline on each render.
+    const contextJson = JSON.stringify(options.context);
+    useEffect(() => {
+        clientRef.current?.setContext(contextJson === undefined ? undefined : JSON.parse(contextJson));
+    }, [clientRef, contextJson]);
+    // why: Slots are compared by value too; a changed value takes an open call up again with it.
+    const slotsJson = JSON.stringify(options.slots);
+    useEffect(() => {
+        clientRef.current?.setSlots(slotsJson === undefined ? undefined : JSON.parse(slotsJson));
+    }, [clientRef, slotsJson]);
+    usePageToolWarnings(iface.tools.page, options.pageTools);
+    return {
+        handle: iface.identity.handle,
+        traces,
+        callStarted,
+        pastCalls,
+        captions: ui.captions,
+        failure: ui.failure,
+        sessionEnded: ui.sessionEnded,
+        levelsRef: ui.levelsRef,
+        isMuted: ui.isMuted,
+        isVideoOn: ui.isVideoOn,
+        sessionActive: ui.sessionActive,
+        liveState: state,
+        activeTool: ui.activeTool,
+        status: ui.status,
+        textAvailable,
+        textDraft: ui.textDraft,
+        toolActive: ui.activeTool !== null || gate.gatePrompt !== null,
+        videoAvailable,
+        videoFacingMode: ui.videoFacingMode,
+        videoPreview: ui.videoPreview,
+        voiceAvailable,
+        // why: Also after ending (or failing) before the first connect, so the call can't get stuck.
+        canRestart: !ui.sessionActive &&
+            ui.status !== 'connecting' &&
+            (ui.everConnected || ended || ui.failure !== null),
+        gatePrompt: gate.gatePrompt,
+        setTextDraft: ui.setTextDraft,
+        handleEnd,
+        startCall,
+        handleRestart,
+        handleSendText: controls.handleSendText,
+        handleToggleMic: controls.handleToggleMic,
+        handleFlipCamera: controls.handleFlipCamera,
+        handleToggleVideo: controls.handleToggleVideo,
+        resolveGateDecision: gate.resolveGateDecision,
+    };
+}

package/components/live/use-live-runner-ui.d.ts

@@ -0,0 +1,67 @@
+import { type LabelOverrides, type SessionEventOf } from '@theoremjs/agents';
+import { type Dispatch, type SetStateAction } from 'react';
+import { type ClientFailure } from '../../client/failure.ts';
+import { applyLiveTurnToolEvent } from '../../client/live/apply-live-turn-tool-event.ts';
+import { type LiveCaptionState } from '../../client/live/live-captions.ts';
+import type { LiveConnectPhase, LiveSessionStatus } from '../../client/live/live-state.ts';
+import type { LiveGateAnswer, LiveToolGatePrompt } from '../../client/live/live-tool.ts';
+import type { LiveFacingMode, LiveVideoCapture } from '../../client/live/live-video.ts';
+import type { ToolGateResolution } from '../../client/tool-resume.ts';
+/** UI + media state bag for the live runner. `labels` is the interface's: the profile's wording. */
+export declare function useLiveRunnerUiState(labels: LabelOverrides): {
+    status: LiveSessionStatus;
+    setStatus: Dispatch<SetStateAction<LiveSessionStatus>>;
+    connectPhase: LiveConnectPhase | null;
+    setConnectPhase: Dispatch<SetStateAction<LiveConnectPhase | null>>;
+    levelsRef: import("react").RefObject<{
+        input: number;
+        output: number;
+    }>;
+    setInputLevel: (value: SetStateAction<number>) => void;
+    setOutputLevel: (value: SetStateAction<number>) => void;
+    isMuted: boolean;
+    setIsMuted: Dispatch<SetStateAction<boolean>>;
+    isVideoOn: boolean;
+    setIsVideoOn: Dispatch<SetStateAction<boolean>>;
+    activeTool: string | null;
+    setActiveTool: Dispatch<SetStateAction<string | null>>;
+    captions: LiveCaptionState;
+    setCaptions: Dispatch<SetStateAction<LiveCaptionState>>;
+    failure: ClientFailure | null;
+    reportFailure: (err: unknown) => void;
+    clearFailure: () => void;
+    sessionEnded: string | null;
+    reportSessionEnded: (session: SessionEventOf<"ended">) => void;
+    clearSessionEnded: () => void;
+    textDraft: string;
+    setTextDraft: Dispatch<SetStateAction<string>>;
+    sessionActive: boolean;
+    setSessionActive: Dispatch<SetStateAction<boolean>>;
+    sessionPermissions: string[];
+    setSessionPermissions: Dispatch<SetStateAction<string[]>>;
+    everConnected: boolean;
+    videoPreview: HTMLVideoElement | null;
+    setVideoPreview: Dispatch<SetStateAction<HTMLVideoElement | null>>;
+    videoFacingMode: LiveFacingMode;
+    setVideoFacingMode: Dispatch<SetStateAction<LiveFacingMode>>;
+    videoCaptureRef: import("react").RefObject<LiveVideoCapture | null>;
+    captionsRef: import("react").RefObject<LiveCaptionState>;
+    isMutedRef: import("react").RefObject<boolean>;
+    sessionPermissionsRef: import("react").RefObject<string[]>;
+    statusRef: import("react").RefObject<LiveSessionStatus>;
+    resetCaptions: () => void;
+    stopVideo: () => void;
+};
+/** Gate prompt + live turn-tool event wiring. */
+export declare function useLiveRunnerGate(args: {
+    setCaptions: Dispatch<SetStateAction<LiveCaptionState>>;
+    setActiveTool: Dispatch<SetStateAction<string | null>>;
+    reportFailure: (err: unknown) => void;
+}): {
+    gatePrompt: LiveToolGatePrompt | null;
+    gatePromptRef: import("react").RefObject<LiveToolGatePrompt | null>;
+    handleLiveTurnEvent: (event: Parameters<typeof applyLiveTurnToolEvent>[0]) => void;
+    waitForGateDecision: (prompt: LiveToolGatePrompt) => Promise<LiveGateAnswer>;
+    resolveGateDecision: (resolution: ToolGateResolution) => void;
+    cancelGateDecision: () => void;
+};

package/components/live/use-live-runner-ui.js

@@ -0,0 +1,167 @@
+import { TheoremError } from '@theoremjs/agents';
+import { useCallback, useEffect, useRef, useState, } from 'react';
+import { clientFailure } from "../../client/failure.js";
+import { applyLiveTurnToolEvent } from "../../client/live/apply-live-turn-tool-event.js";
+import { applyLiveTurnEvent, clearLiveCaptionInterim, emptyLiveCaptionState, } from "../../client/live/live-captions.js";
+/** UI + media state bag for the live runner. `labels` is the interface's: the profile's wording. */
+export function useLiveRunnerUiState(labels) {
+    const [status, setStatus] = useState('disconnected');
+    const [connectPhase, setConnectPhase] = useState(null);
+    // why: Levels move the waveform only. Writing them here keeps a sample off the React tree.
+    const levelsRef = useRef({ input: 0, output: 0 });
+    const setInputLevel = useCallback((value) => {
+        const levels = levelsRef.current;
+        levels.input = typeof value === 'function' ? value(levels.input) : value;
+    }, []);
+    const setOutputLevel = useCallback((value) => {
+        const levels = levelsRef.current;
+        levels.output = typeof value === 'function' ? value(levels.output) : value;
+    }, []);
+    const [isMuted, setIsMuted] = useState(false);
+    const [isVideoOn, setIsVideoOn] = useState(false);
+    const [activeTool, setActiveTool] = useState(null);
+    const [captions, setCaptions] = useState(emptyLiveCaptionState);
+    const [failure, setFailure] = useState(null);
+    /** The user's line for a session the provider ended after warning it would. */
+    const [sessionEnded, setSessionEnded] = useState(null);
+    const [textDraft, setTextDraft] = useState('');
+    const [sessionActive, setSessionActive] = useState(false);
+    const [sessionPermissions, setSessionPermissions] = useState([]);
+    const [everConnected, setEverConnected] = useState(false);
+    const [videoPreview, setVideoPreview] = useState(null);
+    const [videoFacingMode, setVideoFacingMode] = useState('user');
+    const videoCaptureRef = useRef(null);
+    const captionsRef = useRef(captions);
+    const isMutedRef = useRef(isMuted);
+    const sessionPermissionsRef = useRef(sessionPermissions);
+    const statusRef = useRef(status);
+    captionsRef.current = captions;
+    isMutedRef.current = isMuted;
+    sessionPermissionsRef.current = sessionPermissions;
+    statusRef.current = status;
+    useEffect(() => {
+        if (sessionActive)
+            setEverConnected(true);
+    }, [sessionActive]);
+    const reportFailure = useCallback((err) => {
+        setFailure(clientFailure(err, labels));
+    }, [labels]);
+    const clearFailure = useCallback(() => {
+        setFailure(null);
+    }, []);
+    const reportSessionEnded = useCallback((session) => {
+        setSessionEnded(session.message);
+    }, []);
+    const clearSessionEnded = useCallback(() => {
+        setSessionEnded(null);
+    }, []);
+    const resetCaptions = useCallback(() => {
+        setCaptions(emptyLiveCaptionState());
+    }, []);
+    const stopVideo = useCallback(() => {
+        if (videoCaptureRef.current) {
+            videoCaptureRef.current.stop();
+            videoCaptureRef.current = null;
+        }
+        setVideoPreview(null);
+        setVideoFacingMode('user');
+        setIsVideoOn(false);
+    }, []);
+    return {
+        status,
+        setStatus,
+        connectPhase,
+        setConnectPhase,
+        levelsRef,
+        setInputLevel,
+        setOutputLevel,
+        isMuted,
+        setIsMuted,
+        isVideoOn,
+        setIsVideoOn,
+        activeTool,
+        setActiveTool,
+        captions,
+        setCaptions,
+        failure,
+        reportFailure,
+        clearFailure,
+        sessionEnded,
+        reportSessionEnded,
+        clearSessionEnded,
+        textDraft,
+        setTextDraft,
+        sessionActive,
+        setSessionActive,
+        sessionPermissions,
+        setSessionPermissions,
+        everConnected,
+        videoPreview,
+        setVideoPreview,
+        videoFacingMode,
+        setVideoFacingMode,
+        videoCaptureRef,
+        captionsRef,
+        isMutedRef,
+        sessionPermissionsRef,
+        statusRef,
+        resetCaptions,
+        stopVideo,
+    };
+}
+/** Gate prompt + live turn-tool event wiring. */
+export function useLiveRunnerGate(args) {
+    const [gatePrompt, setGatePrompt] = useState(null);
+    const gatePromptRef = useRef(gatePrompt);
+    gatePromptRef.current = gatePrompt;
+    const gateResolverRef = useRef(null);
+    const gateRejectRef = useRef(null);
+    const answerGate = useCallback((answer) => {
+        gateResolverRef.current?.(answer);
+        gateResolverRef.current = null;
+        gateRejectRef.current = null;
+        setGatePrompt(null);
+    }, []);
+    const handleLiveTurnEvent = useCallback((event) => {
+        args.setCaptions((prev) => applyLiveTurnEvent(prev, event));
+        applyLiveTurnToolEvent(event, {
+            gateCallId: gatePromptRef.current?.callId,
+            withdrawGate: () => {
+                answerGate('withdrawn');
+            },
+            clearInterim: () => {
+                args.setCaptions((prev) => clearLiveCaptionInterim(prev));
+            },
+            clearActiveTool: () => {
+                args.setActiveTool(null);
+            },
+            reportFailure: args.reportFailure,
+            setActiveTool: args.setActiveTool,
+        });
+    }, [args, answerGate]);
+    const waitForGateDecision = useCallback((prompt) => {
+        return new Promise((resolve, reject) => {
+            setGatePrompt(prompt);
+            gateResolverRef.current = resolve;
+            gateRejectRef.current = reject;
+        });
+    }, []);
+    const resolveGateDecision = useCallback((resolution) => {
+        answerGate(resolution);
+    }, [answerGate]);
+    const cancelGateDecision = useCallback(() => {
+        // labels-exempt: internal diagnostic; the user reads error.cancelled
+        gateRejectRef.current?.(new TheoremError('cancelled', 'live session ended with a gate open'));
+        gateResolverRef.current = null;
+        gateRejectRef.current = null;
+        setGatePrompt(null);
+    }, []);
+    return {
+        gatePrompt,
+        gatePromptRef,
+        handleLiveTurnEvent,
+        waitForGateDecision,
+        resolveGateDecision,
+        cancelGateDecision,
+    };
+}

package/components/live/use-live-session-client.d.ts

@@ -0,0 +1,41 @@
+import { type SessionEventOf, type TurnEvent } from '@theoremjs/agents';
+import { type Dispatch, type MutableRefObject, type SetStateAction } from 'react';
+import { type LiveCaptionState } from '../../client/live/live-captions.ts';
+import type { LiveCallOptions } from '../../client/live/live-page-tool.ts';
+import type { LiveConnectPhase, LiveSessionStatus } from '../../client/live/live-state.ts';
+import type { LiveGateAnswer, LiveToolGatePrompt } from '../../client/live/live-tool.ts';
+import type { LiveFacingMode, LiveVideoCapture } from '../../client/live/live-video.ts';
+import { type LiveConnection, LiveSessionClient } from '../../client/live-client.ts';
+import type { TraceFeed } from '../../client/trace-feed.ts';
+export type LiveClientBindings = LiveCallOptions & {
+    voiceAvailable: boolean;
+    /** Where the session's trace records go, when the relay delivers them. */
+    traces: TraceFeed;
+    handleLiveTurnEvent: (event: TurnEvent) => void;
+    waitForGateDecision: (prompt: LiveToolGatePrompt) => Promise<LiveGateAnswer>;
+    gatePromptRef: MutableRefObject<LiveToolGatePrompt | null>;
+    isMutedRef: MutableRefObject<boolean>;
+    sessionPermissionsRef: MutableRefObject<string[]>;
+    videoCaptureRef: MutableRefObject<LiveVideoCapture | null>;
+    setConnectPhase: Dispatch<SetStateAction<LiveConnectPhase | null>>;
+    setStatus: Dispatch<SetStateAction<LiveSessionStatus>>;
+    setSessionActive: Dispatch<SetStateAction<boolean>>;
+    reportFailure: (err: unknown) => void;
+    clearFailure: () => void;
+    reportSessionEnded: (session: SessionEventOf<'ended'>) => void;
+    clearSessionEnded: () => void;
+    setCaptions: Dispatch<SetStateAction<LiveCaptionState>>;
+    setInputLevel: Dispatch<SetStateAction<number>>;
+    setOutputLevel: Dispatch<SetStateAction<number>>;
+    setActiveTool: Dispatch<SetStateAction<string | null>>;
+    setSessionPermissions: Dispatch<SetStateAction<string[]>>;
+    setVideoPreview: Dispatch<SetStateAction<HTMLVideoElement | null>>;
+    setVideoFacingMode: Dispatch<SetStateAction<LiveFacingMode>>;
+    setIsVideoOn: Dispatch<SetStateAction<boolean>>;
+};
+/** Owns LiveSessionClient construction + reconnect identity. */
+export declare function useLiveSessionClient(bindings: LiveClientBindings): {
+    clientRef: import("react").RefObject<LiveSessionClient | null>;
+    ensureClient: (connection: LiveConnection) => LiveSessionClient;
+    clearClient: () => void;
+};

package/components/live/use-live-session-client.js

@@ -0,0 +1,126 @@
+import { TheoremError } from '@theoremjs/agents';
+import { useCallback, useRef, } from 'react';
+import { applyLiveTranscript } from "../../client/live/live-captions.js";
+import { runLiveToolCall } from "../../client/live/run-live-tool-call.js";
+import { LiveSessionClient } from "../../client/live-client.js";
+function onLiveStatusChange(next, bindings) {
+    bindings.setStatus(next);
+    if (next === 'listening' || next === 'ready') {
+        bindings.setSessionActive(true);
+        bindings.clearFailure();
+        bindings.clearSessionEnded();
+        return;
+    }
+    if (next !== 'disconnected' && next !== 'error')
+        return;
+    bindings.setSessionActive(false);
+    if (bindings.videoCaptureRef.current) {
+        bindings.videoCaptureRef.current.stop();
+        bindings.videoCaptureRef.current = null;
+    }
+    bindings.setVideoPreview(null);
+    bindings.setVideoFacingMode('user');
+    bindings.setIsVideoOn(false);
+}
+function onLiveTranscript(text, isUser, meta, bindings) {
+    // why: A thought or a tool call in the same batch is already queued; each folds onto the last.
+    bindings.setCaptions((prev) => applyLiveTranscript(prev, text, isUser, meta?.interim));
+}
+async function onLiveToolCall(name, toolArgs, meta, bindings, clientRef) {
+    bindings.setActiveTool(name);
+    bindings.clearFailure();
+    const client = clientRef.current;
+    if (!client) {
+        // labels-exempt: internal diagnostic; the user reads error.request
+        bindings.reportFailure(new TheoremError('request', 'live tool call with no session client'));
+        return;
+    }
+    try {
+        await runLiveToolCall({
+            pageTools: bindings.pageTools,
+            executeToolOnRelay: (call) => client.executeToolOnRelay(call),
+            name,
+            toolArgs,
+            callId: meta.callId,
+            operationId: meta.operationId,
+            sessionPermissions: bindings.sessionPermissionsRef.current,
+            setSessionPermissions: (next) => {
+                bindings.sessionPermissionsRef.current = next;
+                bindings.setSessionPermissions(next);
+            },
+            waitForGateDecision: bindings.waitForGateDecision,
+        });
+    }
+    catch (err) {
+        bindings.reportFailure(err);
+    }
+    finally {
+        if (!bindings.gatePromptRef.current)
+            bindings.setActiveTool(null);
+    }
+}
+/** Owns LiveSessionClient construction + reconnect identity. */
+export function useLiveSessionClient(bindings) {
+    const clientRef = useRef(null);
+    const bindingsRef = useRef(bindings);
+    bindingsRef.current = bindings;
+    const ensureClient = useCallback((connection) => {
+        if (clientRef.current)
+            return clientRef.current;
+        const b = bindingsRef.current;
+        const client = new LiveSessionClient({
+            ...connection,
+            slots: b.slots,
+            context: b.context,
+            voiceIngress: b.voiceAvailable,
+            onConnectPhase: (phase) => {
+                b.setConnectPhase(phase);
+            },
+            onStatusChange: (next) => {
+                onLiveStatusChange(next, bindingsRef.current);
+            },
+            onTranscript: (text, isUser, meta) => {
+                onLiveTranscript(text, isUser, meta, bindingsRef.current);
+            },
+            onTurnEvent: (event) => {
+                // why: An `unsupported` event is the host's to read; Theorem's UI shows nothing for it.
+                if (event.type === 'unsupported')
+                    return;
+                // why: A `malformed` one was left out and the call goes on; the user reads that part was skipped.
+                if (event.type === 'malformed') {
+                    bindingsRef.current.reportFailure(event.error);
+                    return;
+                }
+                bindingsRef.current.handleLiveTurnEvent(event);
+            },
+            onTrace: (record) => {
+                bindingsRef.current.traces.push(record);
+            },
+            onVolumeLevel: (level, isUser) => {
+                const current = bindingsRef.current;
+                if (isUser) {
+                    current.setInputLevel(current.isMutedRef.current ? 0 : level);
+                }
+                else {
+                    current.setOutputLevel(level);
+                }
+            },
+            onError: (err) => {
+                bindingsRef.current.reportFailure(err);
+            },
+            onSessionEnded: (session) => {
+                bindingsRef.current.reportSessionEnded(session);
+            },
+            onToolCall: (name, args, meta) => onLiveToolCall(name, args, meta, bindingsRef.current, clientRef),
+        });
+        clientRef.current = client;
+        return client;
+    }, []);
+    const clearClient = useCallback(() => {
+        if (clientRef.current) {
+            clientRef.current.disconnect();
+            clientRef.current = null;
+        }
+    }, []);
+    return { clientRef, ensureClient, clearClient };
+}

package/components/use-composer-voice.d.ts

@@ -0,0 +1,28 @@
+import { type LabelOverrides } from '@theoremjs/agents';
+import type { ProfileInputsInterface } from '@theoremjs/agents/interface';
+import { type VoiceRecorderFailureCode } from '../client/voice-recorder.ts';
+/** A voice note that could not be recorded or staged. */
+export type VoiceFailure = {
+    /** A recorder failure, or `too_many_files` when the message is already full. */
+    code: VoiceRecorderFailureCode | 'too_many_files';
+    /** What the user reads: the profile labels' `voice.<code>` (or the file-limit line). */
+    error: string;
+    /** Raw detail for the builder; never shown to the user. */
+    errorInternal?: string;
+};
+export declare function useComposerVoice(args: {
+    inputs: ProfileInputsInterface;
+    /** The interface's `labels`: the profile's wording for voice failures. */
+    labels: LabelOverrides;
+    pendingFiles: readonly File[];
+    onVoiceStaged?: (file: File) => void;
+    onVoiceClear?: () => void;
+}): {
+    recording: boolean;
+    inputLevel: number;
+    failure: VoiceFailure | null;
+    setFailure: import("react").Dispatch<import("react").SetStateAction<VoiceFailure | null>>;
+    toggleRecording: () => Promise<void>;
+    discardRecordingOrVoice: () => void;
+    disposeRecorder: () => void;
+};