@theoremjs/react 0.3.0 → 0.3.1

package/client/voice-recorder.d.ts

@@ -1,4 +1,4 @@
-/** Why recording failed; the user reads lexicon `voice.<code>`. */
+/** Why recording failed; the user reads labels `voice.<code>`. */
 export type VoiceRecorderFailureCode = 'unsupported' | 'permission' | 'unavailable' | 'failed' | 'empty';
 /** Headless MediaRecorder session for turn-composer voice notes. */
 export declare class ComposerVoiceRecorder {

package/client/voice-recorder.js

@@ -41,7 +41,6 @@ export class ComposerVoiceRecorder {
         this.accept = accept;
         this.onLevel = onLevel;
     }
-    // fallow-ignore-next-line unused-class-member -- called from useComposerVoice via recorder refs
     async start() {
         this.disposeTracks();
         const mime = pickMediaRecorderMime(this.accept);
@@ -72,10 +71,9 @@ export class ComposerVoiceRecorder {
         this.recording = true;
         this.startMeter();
     }
-    // fallow-ignore-next-line unused-class-member -- called from useComposerVoice via recorder refs
     async stop() {
         if (!this.recorder || !this.recording) {
-            // lexicon-exempt: internal diagnostic; the user reads voice.empty
+            // labels-exempt: internal diagnostic; the user reads voice.empty
             throw new VoiceRecorderFailure('empty', 'stop without a recording');
         }
         const recorder = this.recorder;
@@ -110,14 +108,13 @@ export class ComposerVoiceRecorder {
                 this.recorder.stop();
             }
             catch {
-                // ignore
+                // why: stop() throws when the recorder stopped between the check and the call; it is stopped either way.
             }
         }
         this.disposeTracks();
         this.chunks = [];
         this.recorder = null;
     }
-    // fallow-ignore-next-line unused-class-member -- called from useComposerVoice cleanup
     dispose() {
         this.cancel();
     }

package/client/wire-line.js

@@ -32,7 +32,7 @@ export function issueSummary(error) {
     return issuesSummary(error.issues, []);
 }
 function badResponse(what, error) {
-    // lexicon-exempt: internal diagnostic; the user reads error.bad_response
+    // labels-exempt: internal diagnostic; the user reads error.bad_response
     return new TheoremError('bad_response', `${what} failed its wire check: ${issueSummary(error)}`);
 }
 /** `raw` as `schema` reads it; one that fails is `bad_response`, naming `what`. */
@@ -51,7 +51,7 @@ function malformed(message) {
 /** One wire value: a known kind that passed its schema, `unsupported`, or `malformed`. */
 export function readWireValue(lines, raw) {
     const kind = wireKind.safeParse(raw);
-    // lexicon-exempt: internal diagnostic; the user reads session.part_skipped
+    // labels-exempt: internal diagnostic; the user reads session.part_skipped
     if (!kind.success)
         return malformed(`a line without a kind failed its wire check: ${issueSummary(kind.error)}`);
     const { type } = kind.data;
@@ -60,7 +60,7 @@ export function readWireValue(lines, raw) {
     const line = lines[type].safeParse(raw);
     if (line.success)
         return line.data;
-    // lexicon-exempt: internal diagnostic; the user reads session.part_skipped
+    // labels-exempt: internal diagnostic; the user reads session.part_skipped
     return malformed(`a '${type}' line failed its wire check: ${issueSummary(line.error)}`);
 }
 /** JSON text as a value, or undefined when it is not JSON. The parser's own error quotes the text, so it is not kept. */
@@ -77,13 +77,13 @@ function jsonValue(text) {
 /** One wire line's text: {@link readWireValue} of its JSON, or `malformed` when it is not JSON. */
 export function readWireLine(lines, text) {
     const json = jsonValue(text);
-    // lexicon-exempt: internal diagnostic; the user reads session.part_skipped
+    // labels-exempt: internal diagnostic; the user reads session.part_skipped
     return json ? readWireValue(lines, json.value) : malformed('a line is not JSON');
 }
 /** A whole reply's JSON text as a value; text that is not JSON is `bad_response`. */
 export function parseWireJson(text) {
     const json = jsonValue(text);
-    // lexicon-exempt: internal diagnostic; the user reads error.bad_response
+    // labels-exempt: internal diagnostic; the user reads error.bad_response
     if (!json)
         throw new TheoremError('bad_response', 'a line is not JSON');
     return json.value;

package/client/worklets/mic-capture.js

@@ -4,13 +4,13 @@
  * by URL (see `../mic-capture.ts`), so it imports nothing and ships as is.
  */
 registerProcessor(
-	'mic-capture-processor',
-	class MicCaptureProcessor extends AudioWorkletProcessor {
-		process(inputs) {
-			const channel = inputs[0][0];
-			const copy = new Float32Array(channel);
-			this.port.postMessage(copy, [copy.buffer]);
-			return true;
-		}
-	},
+  'mic-capture-processor',
+  class MicCaptureProcessor extends AudioWorkletProcessor {
+    process(inputs) {
+      const channel = inputs[0][0];
+      const copy = new Float32Array(channel);
+      this.port.postMessage(copy, [copy.buffer]);
+      return true;
+    }
+  },
 );

package/components/InkWaveform.d.ts

@@ -1,10 +1,21 @@
+import { type RefObject } from 'react';
 import { type InkWaveStatus } from '../client/ink-waveform.ts';
+/** Mic and speaker levels. A host on the audio clock writes this; the bars read it each frame. */
+export type InkWaveLevels = {
+    input: number;
+    output: number;
+};
 export type InkWaveformProps = {
     status?: InkWaveStatus;
     inputLevel?: number;
     outputLevel?: number;
+    /**
+     * Latest levels, read each frame. When set, it wins over `inputLevel` and
+     * `outputLevel`, so a host can move the bars without rendering.
+     */
+    levelsRef?: RefObject<InkWaveLevels>;
     toolActive?: boolean;
     frozen?: boolean;
     variant?: 'default' | 'hero' | 'pill' | 'strip';
 };
-export declare function InkWaveform({ status, inputLevel, outputLevel, toolActive, frozen, variant, }: InkWaveformProps): import("react").JSX.Element;
+export declare function InkWaveform({ status, inputLevel, outputLevel, levelsRef, toolActive, frozen, variant, }: InkWaveformProps): import("react").JSX.Element;

package/components/InkWaveform.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useMemo, useRef, useState } from 'react';
-import { computeInkBarTargets, INK_WAVE_BAR_COUNT, INK_WAVE_HERO_BAR_COUNT, inkWaveDriver, inkWavePhases, stepInkBarHeights, } from "../client/ink-waveform.js";
+import { useEffect, useMemo, useRef } from 'react';
+import { computeInkBarTargets, INK_WAVE_BAR_COUNT, INK_WAVE_HERO_BAR_COUNT, inkWaveDriver, inkWavePhases, } from "../client/ink-waveform.js";
+const REST_HEIGHT = 0.06;
 const WAVE_CONFIG = {
     hero: {
         viewWidth: 960,
@@ -16,7 +17,6 @@ const WAVE_CONFIG = {
         strokeWidth: 3,
         barCount: INK_WAVE_BAR_COUNT,
     },
-    // A long, low band (a call bar along the foot of a page): many fine bars.
     strip: {
         viewWidth: 1600,
         viewHeight: 48,
@@ -37,62 +37,84 @@ function resolveWaveDimensions(variant) {
     const gap = (cfg.viewWidth - cfg.strokeWidth * cfg.barCount) / (cfg.barCount + 1);
     return { ...cfg, gap };
 }
-function useAnimatedWaveHeights(args) {
-    const { barCount, phases, status, inputLevel, outputLevel, toolActive, frozen } = args;
-    const [heights, setHeights] = useState(() => Array.from({ length: barCount }, () => 0.06));
-    const snapRef = useRef({
-        status,
-        inputLevel,
-        outputLevel,
-        toolActive,
-        frozen,
+/** One frame's bar targets. The live ref's levels win over the last render's; a frozen wave moves to none. */
+function frameTargets(snap, phases, timeMs) {
+    const { input, output } = snap.levelsRef?.current ?? {
+        input: snap.inputLevel,
+        output: snap.outputLevel,
+    };
+    const heard = snap.frozen ? { input: 0, output: 0 } : { input, output };
+    return computeInkBarTargets({
+        phases,
+        timeMs,
+        driver: inkWaveDriver(snap.status, snap.toolActive, input, output, snap.frozen),
+        inputLevel: heard.input,
+        outputLevel: heard.output,
+        frozen: snap.frozen,
     });
+}
+/**
+ * Paints bar heights onto the mounted lines. The motion is the same as
+ * `computeInkBarTargets` plus the per-frame ease; React never sees a frame,
+ * so a strip of bars does not reconcile on the audio clock.
+ */
+function usePaintedWave(svgRef, snapRef, phases, barCount, viewHeight) {
     useEffect(() => {
-        snapRef.current = { status, inputLevel, outputLevel, toolActive, frozen };
-    }, [status, inputLevel, outputLevel, toolActive, frozen]);
-    useEffect(() => {
+        const svg = svgRef.current;
+        if (!svg)
+            return;
+        const lines = svg.children;
+        const count = Math.min(barCount, lines.length);
+        const heights = new Float64Array(count);
+        heights.fill(REST_HEIGHT);
+        const restY = viewHeight - REST_HEIGHT * (viewHeight - 4);
+        for (let index = 0; index < count; index++) {
+            lines[index].y2.baseVal.value = restY;
+        }
         let frame = 0;
-        setHeights(Array.from({ length: barCount }, () => 0.06));
         const tick = (time) => {
             const snap = snapRef.current;
-            setHeights((prev) => {
-                const current = prev.length === barCount ? prev : Array.from({ length: barCount }, () => 0.06);
-                const targets = computeInkBarTargets({
-                    phases,
-                    timeMs: time,
-                    driver: inkWaveDriver(snap.status, snap.toolActive, snap.inputLevel, snap.outputLevel, snap.frozen),
-                    inputLevel: snap.frozen ? 0 : snap.inputLevel,
-                    outputLevel: snap.frozen ? 0 : snap.outputLevel,
-                    frozen: snap.frozen,
-                });
-                return stepInkBarHeights(current, targets, snap.frozen ? 0.2 : 0.14);
-            });
+            const targets = frameTargets(snap, phases, time);
+            const alpha = snap.frozen ? 0.2 : 0.14;
+            for (let index = 0; index < count; index++) {
+                const height = heights[index] + (targets[index] - heights[index]) * alpha;
+                heights[index] = height;
+                lines[index].y2.baseVal.value = viewHeight - height * (viewHeight - 4);
+            }
             frame = requestAnimationFrame(tick);
         };
         frame = requestAnimationFrame(tick);
         return () => {
             cancelAnimationFrame(frame);
         };
-    }, [barCount, phases]);
-    return heights;
+    }, [svgRef, snapRef, phases, barCount, viewHeight]);
 }
-export function InkWaveform({ status = 'disconnected', inputLevel = 0, outputLevel = 0, toolActive = false, frozen = false, variant = 'default', }) {
+export function InkWaveform({ status = 'disconnected', inputLevel = 0, outputLevel = 0, levelsRef, toolActive = false, frozen = false, variant = 'default', }) {
     const { viewWidth, viewHeight, preserveAspect, strokeWidth, barCount, gap } = resolveWaveDimensions(variant);
     const phases = useMemo(() => inkWavePhases(barCount), [barCount]);
-    const heights = useAnimatedWaveHeights({
-        barCount,
-        phases,
+    const xs = useMemo(() => {
+        const next = new Array(barCount);
+        for (let index = 0; index < barCount; index++) {
+            next[index] = gap + index * (strokeWidth + gap) + strokeWidth / 2;
+        }
+        return next;
+    }, [barCount, gap, strokeWidth]);
+    const svgRef = useRef(null);
+    const snapRef = useRef({
         status,
         inputLevel,
         outputLevel,
+        levelsRef,
         toolActive,
         frozen,
     });
-    const bars = heights.map((height, index) => {
-        const x = gap + index * (strokeWidth + gap) + strokeWidth / 2;
-        const barHeight = height * (viewHeight - 4);
-        return { x, y2: viewHeight - barHeight };
-    });
+    snapRef.current.status = status;
+    snapRef.current.inputLevel = inputLevel;
+    snapRef.current.outputLevel = outputLevel;
+    snapRef.current.levelsRef = levelsRef;
+    snapRef.current.toolActive = toolActive;
+    snapRef.current.frozen = frozen;
+    usePaintedWave(svgRef, snapRef, phases, barCount, viewHeight);
     const className = [
         'ink-wave',
         variant === 'hero' ? 'ink-wave--hero' : '',
@@ -101,8 +123,9 @@ export function InkWaveform({ status = 'disconnected', inputLevel = 0, outputLev
     ]
         .filter(Boolean)
         .join(' ');
-    return (_jsx("svg", { className: className, "aria-hidden": "true", viewBox: `0 0 ${String(viewWidth)} ${String(viewHeight)}`, preserveAspectRatio: preserveAspect, 
-        // Attribute defaults for hosts without ink-controls.css (the Astryx UI);
+    const restY = viewHeight - REST_HEIGHT * (viewHeight - 4);
+    return (_jsx("svg", { ref: svgRef, className: className, "aria-hidden": "true", viewBox: `0 0 ${String(viewWidth)} ${String(viewHeight)}`, preserveAspectRatio: preserveAspect, 
+        // why: Attribute defaults for hosts without ink-controls.css (the Astryx UI);
         // the live stylesheet overrides them where it loads.
-        width: "100%", height: "100%", children: bars.map((bar) => (_jsx("line", { className: "ink-wave__bar", x1: bar.x, x2: bar.x, y1: viewHeight, y2: bar.y2, strokeWidth: strokeWidth, stroke: "currentColor", strokeLinecap: "square" }, `${String(bar.x)}:${String(bar.y2)}`))) }));
+        width: "100%", height: "100%", children: xs.map((x) => (_jsx("line", { className: "ink-wave__bar", x1: x, x2: x, y1: viewHeight, y2: restY, strokeWidth: strokeWidth, stroke: "currentColor", strokeLinecap: "square" }, x))) }));
 }

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

@@ -1,13 +1,12 @@
-import { type MutableRefObject, type Dispatch, type SetStateAction } from 'react';
+import { type Dispatch, type MutableRefObject, type SetStateAction } from 'react';
 import { type LiveCaptionState } from '../../client/live/live-captions.ts';
-import { type LiveFacingMode, type LiveVideoCapture } from '../../client/live/live-video.ts';
 import type { LiveConnectPhase, LiveSessionStatus } from '../../client/live/live-state.ts';
+import { type LiveFacingMode, type LiveVideoCapture } from '../../client/live/live-video.ts';
 import type { LiveConnection, LiveSessionClient } from '../../client/live-client.ts';
 /** Media + session lifecycle handlers for LiveRunner. */
 export declare function useLiveRunnerControls(args: {
     clientRef: MutableRefObject<LiveSessionClient | null>;
     videoCaptureRef: MutableRefObject<LiveVideoCapture | null>;
-    captionsRef: MutableRefObject<LiveCaptionState>;
     connectionRef: MutableRefObject<() => LiveConnection | Promise<LiveConnection>>;
     statusRef: MutableRefObject<LiveSessionStatus>;
     isMutedRef: MutableRefObject<boolean>;
@@ -40,7 +39,7 @@ export declare function useLiveRunnerControls(args: {
 }): {
     teardownSession: () => void;
     startSession: () => Promise<void>;
-    handleSendText: () => void;
+    handleSendText: (text?: string) => void;
     handleToggleVideo: () => Promise<void>;
     handleFlipCamera: () => Promise<void>;
     handleToggleMic: () => void;

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

@@ -1,5 +1,5 @@
 import { useCallback } from 'react';
-import { applyLiveTranscript, } from "../../client/live/live-captions.js";
+import { applyLiveTranscript } from "../../client/live/live-captions.js";
 import { startLiveVideoCapture, } from "../../client/live/live-video.js";
 /** Media + session lifecycle handlers for LiveRunner. */
 export function useLiveRunnerControls(args) {
@@ -31,17 +31,13 @@ export function useLiveRunnerControls(args) {
             args.reportFailure(err);
         }
     }, [args]);
-    const handleSendText = useCallback(() => {
-        const text = args.textDraft.trim();
-        if (!text || !args.clientRef.current || !args.sessionActive || !args.textAvailable)
+    const handleSendText = useCallback((text) => {
+        const message = (typeof text === 'string' ? text : args.textDraft).trim();
+        if (!message || !args.clientRef.current || !args.sessionActive || !args.textAvailable)
             return;
-        args.clientRef.current.sendText(text);
+        args.clientRef.current.sendText(message);
         args.setTextDraft('');
-        const next = applyLiveTranscript(args.captionsRef.current, text, true, false, {
-            forceNew: true,
-        });
-        args.captionsRef.current = next;
-        args.setCaptions(next);
+        args.setCaptions((prev) => applyLiveTranscript(prev, message, true, false, { forceNew: true }));
     }, [args]);
     const handleToggleVideo = useCallback(async () => {
         if (!args.clientRef.current || !args.sessionActive || !args.videoAvailable)

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

@@ -1,12 +1,14 @@
 import type { LiveProfileInterface } from '@theoremjs/agents/interface';
-import type { LiveCaptionState, LiveCaptionTurn } from '../../client/live/live-captions.ts';
+import { type LiveCaptionState, type LiveCaptionTurn } from '../../client/live/live-captions.ts';
+import type { LiveCallOptions } from '../../client/live/live-page-tool.ts';
 import type { LiveConnection } from '../../client/live-client.ts';
 /**
  * Owns LiveRunner state, session client, and stage callbacks.
  * `connection` resolves what the call opens: a host with a fixed profile returns
- * its id; the playground returns its draft as the relay's open message.
+ * 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 declare function useLiveRunnerModel(iface: LiveProfileInterface, connection: () => LiveConnection | Promise<LiveConnection>): {
+export declare function useLiveRunnerModel(iface: LiveProfileInterface, connection: () => LiveConnection | Promise<LiveConnection>, options?: LiveCallOptions): {
     handle: string;
     traces: import("../../index.ts").TraceFeed;
     callStarted: boolean;
@@ -14,10 +16,12 @@ export declare function useLiveRunnerModel(iface: LiveProfileInterface, connecti
     captions: LiveCaptionState;
     failure: import("../../index.ts").ClientFailure | null;
     sessionEnded: string | null;
-    inputLevel: number;
+    levelsRef: import("react").RefObject<{
+        input: number;
+        output: number;
+    }>;
     isMuted: boolean;
     isVideoOn: boolean;
-    outputLevel: number;
     sessionActive: boolean;
     liveState: import("../../index.ts").LiveState;
     activeTool: string | null;
@@ -37,7 +41,7 @@ export declare function useLiveRunnerModel(iface: LiveProfileInterface, connecti
         video: boolean;
     }) => void;
     handleRestart: () => Promise<void>;
-    handleSendText: () => void;
+    handleSendText: (text?: string) => void;
     handleToggleMic: () => void;
     handleFlipCamera: () => Promise<void>;
     handleToggleVideo: () => Promise<void>;

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

@@ -1,7 +1,9 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 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";
@@ -20,7 +22,7 @@ function useLiveCallLifecycle(controls, captionsRef, sessionActive, videoAvailab
         setEnded(false);
         void controls.startSession();
     }, [controls, videoAvailable]);
-    // Camera capture needs a live session, so a video call turns it on once connected.
+    // why: Camera capture needs a live session, so a video call turns it on once connected.
     useEffect(() => {
         if (!sessionActive || !videoOnConnectRef.current)
             return;
@@ -35,8 +37,7 @@ function useLiveCallLifecycle(controls, captionsRef, sessionActive, videoAvailab
     const [pastCalls, setPastCalls] = useState([]);
     const handleRestart = useCallback(async () => {
         const previous = captionsRef.current.turns;
-        if (previous.length > 0)
-            setPastCalls((calls) => [...calls, previous]);
+        setPastCalls((calls) => stashLiveCaptionCall(calls, previous));
         setEnded(false);
         await controls.handleRestart();
     }, [controls, captionsRef]);
@@ -52,10 +53,11 @@ function useLiveCallLifecycle(controls, captionsRef, sessionActive, videoAvailab
 /**
  * Owns LiveRunner state, session client, and stage callbacks.
  * `connection` resolves what the call opens: a host with a fixed profile returns
- * its id; the playground returns its draft as the relay's open message.
+ * 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) {
-    const ui = useLiveRunnerUiState(iface.lexicon);
+export function useLiveRunnerModel(iface, connection, options = {}) {
+    const ui = useLiveRunnerUiState(iface.labels);
     const gate = useLiveRunnerGate({
         setCaptions: ui.setCaptions,
         setActiveTool: ui.setActiveTool,
@@ -73,14 +75,16 @@ export function useLiveRunnerModel(iface, connection) {
         isMuted: ui.isMuted,
         voiceEnabled: voiceAvailable,
     }), [ui.activeTool, ui.connectPhase, ui.isMuted, ui.status, voiceAvailable]);
-    // One feed per runner: every session it opens adds its records.
+    // 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,
-        captionsRef: ui.captionsRef,
         gatePromptRef: gate.gatePromptRef,
         isMutedRef: ui.isMutedRef,
         sessionPermissionsRef: ui.sessionPermissionsRef,
@@ -104,7 +108,6 @@ export function useLiveRunnerModel(iface, connection) {
     const controls = useLiveRunnerControls({
         clientRef,
         videoCaptureRef: ui.videoCaptureRef,
-        captionsRef: ui.captionsRef,
         connectionRef,
         statusRef: ui.statusRef,
         isMutedRef: ui.isMutedRef,
@@ -136,6 +139,17 @@ export function useLiveRunnerModel(iface, connection) {
         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,
@@ -144,10 +158,9 @@ export function useLiveRunnerModel(iface, connection) {
         captions: ui.captions,
         failure: ui.failure,
         sessionEnded: ui.sessionEnded,
-        inputLevel: ui.inputLevel,
+        levelsRef: ui.levelsRef,
         isMuted: ui.isMuted,
         isVideoOn: ui.isVideoOn,
-        outputLevel: ui.outputLevel,
         sessionActive: ui.sessionActive,
         liveState: state,
         activeTool: ui.activeTool,
@@ -159,8 +172,10 @@ export function useLiveRunnerModel(iface, connection) {
         videoFacingMode: ui.videoFacingMode,
         videoPreview: ui.videoPreview,
         voiceAvailable,
-        // 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),
+        // 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,

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

@@ -1,22 +1,24 @@
+import { type LabelOverrides, type SessionEventOf } from '@theoremjs/agents';
 import { type Dispatch, type SetStateAction } from 'react';
-import { type LexiconOverrides, type SessionEventOf } from '@theoremjs/agents';
 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 { LiveConnectPhase, LiveSessionStatus } from '../../client/live/live-state.ts';
 import type { ToolGateResolution } from '../../client/tool-resume.ts';
-/** UI + media state bag for the live runner. `lexicon` is the interface's: the profile's wording. */
-export declare function useLiveRunnerUiState(lexicon: LexiconOverrides): {
+/** 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>>;
-    inputLevel: number;
-    setInputLevel: Dispatch<SetStateAction<number>>;
-    outputLevel: number;
-    setOutputLevel: Dispatch<SetStateAction<number>>;
+    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;

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

@@ -1,14 +1,22 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
 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 { clearLiveCaptionInterim, emptyLiveCaptionState, } from "../../client/live/live-captions.js";
-/** UI + media state bag for the live runner. `lexicon` is the interface's: the profile's wording. */
-export function useLiveRunnerUiState(lexicon) {
+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);
-    const [inputLevel, setInputLevel] = useState(0);
-    const [outputLevel, setOutputLevel] = useState(0);
+    // 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);
@@ -36,8 +44,8 @@ export function useLiveRunnerUiState(lexicon) {
             setEverConnected(true);
     }, [sessionActive]);
     const reportFailure = useCallback((err) => {
-        setFailure(clientFailure(err, lexicon));
-    }, [lexicon]);
+        setFailure(clientFailure(err, labels));
+    }, [labels]);
     const clearFailure = useCallback(() => {
         setFailure(null);
     }, []);
@@ -64,9 +72,8 @@ export function useLiveRunnerUiState(lexicon) {
         setStatus,
         connectPhase,
         setConnectPhase,
-        inputLevel,
+        levelsRef,
         setInputLevel,
-        outputLevel,
         setOutputLevel,
         isMuted,
         setIsMuted,
@@ -116,6 +123,7 @@ export function useLiveRunnerGate(args) {
         setGatePrompt(null);
     }, []);
     const handleLiveTurnEvent = useCallback((event) => {
+        args.setCaptions((prev) => applyLiveTurnEvent(prev, event));
         applyLiveTurnToolEvent(event, {
             gateCallId: gatePromptRef.current?.callId,
             withdrawGate: () => {
@@ -142,7 +150,7 @@ export function useLiveRunnerGate(args) {
         answerGate(resolution);
     }, [answerGate]);
     const cancelGateDecision = useCallback(() => {
-        // lexicon-exempt: internal diagnostic; the user reads error.cancelled
+        // 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;

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

@@ -1,18 +1,18 @@
-import { type Dispatch, type MutableRefObject, type SetStateAction } from 'react';
 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 { LiveConnectPhase, LiveSessionStatus } from '../../client/live/live-state.ts';
 import { type LiveConnection, LiveSessionClient } from '../../client/live-client.ts';
 import type { TraceFeed } from '../../client/trace-feed.ts';
-export type LiveClientBindings = {
+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>;
-    captionsRef: MutableRefObject<LiveCaptionState>;
     gatePromptRef: MutableRefObject<LiveToolGatePrompt | null>;
     isMutedRef: MutableRefObject<boolean>;
     sessionPermissionsRef: MutableRefObject<string[]>;