@backbay/glia 0.2.0-alpha.1

package/dist/audio/hooks/useAudioPlayer.js

@@ -0,0 +1,96 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+// =============================================================================
+// Hook
+// =============================================================================
+export function useAudioPlayer(options = {}) {
+    const { volume = 1, onEnded, onError } = options;
+    const audioRef = useRef(null);
+    const objectUrlRef = useRef(null);
+    const [isPlaying, setIsPlaying] = useState(false);
+    const [error, setError] = useState(null);
+    // Ensure we have an audio element.
+    if (!audioRef.current && typeof Audio !== 'undefined') {
+        audioRef.current = new Audio();
+    }
+    const stop = useCallback(() => {
+        const audio = audioRef.current;
+        if (!audio)
+            return;
+        try {
+            audio.pause();
+            audio.currentTime = 0;
+        }
+        catch {
+            // Ignore.
+        }
+        finally {
+            setIsPlaying(false);
+        }
+    }, []);
+    const play = useCallback(async (source) => {
+        const audio = audioRef.current;
+        if (!audio) {
+            throw new Error('Audio playback not supported in this environment');
+        }
+        setError(null);
+        // Clean up previous object URL.
+        if (objectUrlRef.current) {
+            URL.revokeObjectURL(objectUrlRef.current);
+            objectUrlRef.current = null;
+        }
+        const src = typeof source === 'string' ? source : URL.createObjectURL(source);
+        if (typeof source !== 'string') {
+            objectUrlRef.current = src;
+        }
+        audio.volume = volume;
+        audio.src = src;
+        try {
+            await audio.play();
+            setIsPlaying(true);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Failed to play audio';
+            setIsPlaying(false);
+            setError(message);
+            onError?.(err instanceof Error ? err : new Error(message));
+            throw err instanceof Error ? err : new Error(message);
+        }
+    }, [volume, onError]);
+    useEffect(() => {
+        const audio = audioRef.current;
+        if (!audio)
+            return;
+        const handleEnded = () => {
+            setIsPlaying(false);
+            onEnded?.();
+        };
+        const handleError = () => {
+            setIsPlaying(false);
+            const message = 'Audio element error';
+            setError(message);
+            onError?.(new Error(message));
+        };
+        audio.addEventListener('ended', handleEnded);
+        audio.addEventListener('error', handleError);
+        return () => {
+            audio.removeEventListener('ended', handleEnded);
+            audio.removeEventListener('error', handleError);
+        };
+    }, [onEnded, onError]);
+    useEffect(() => {
+        return () => {
+            stop();
+            if (objectUrlRef.current) {
+                URL.revokeObjectURL(objectUrlRef.current);
+                objectUrlRef.current = null;
+            }
+        };
+    }, [stop]);
+    return {
+        isPlaying,
+        error,
+        play,
+        stop,
+        audioElement: audioRef.current,
+    };
+}

package/dist/audio/hooks/useBargeIn.d.ts

@@ -0,0 +1,27 @@
+export interface UseBargeInOptions {
+    /**
+     * Microphone or remote user stream.
+     * You must request user consent in the host app (getUserMedia) and pass it in.
+     */
+    stream: MediaStream | null;
+    enabled?: boolean;
+    /**
+     * RMS threshold in 0..1.
+     * Typical values are small; start around 0.02 and calibrate per environment.
+     */
+    threshold?: number;
+    /**
+     * Keep "speaking" true for this long after signal drops below threshold.
+     */
+    hangoverMs?: number;
+    /**
+     * Called on the rising edge (silence -> speaking).
+     */
+    onBargeIn?: () => void;
+}
+export interface UseBargeInReturn {
+    isUserSpeaking: boolean;
+    levelRms: number;
+}
+export declare function useBargeIn(options: UseBargeInOptions): UseBargeInReturn;
+//# sourceMappingURL=useBargeIn.d.ts.map

package/dist/audio/hooks/useBargeIn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBargeIn.d.ts","sourceRoot":"","sources":["../../../src/audio/hooks/useBargeIn.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAE3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAyEvE"}

package/dist/audio/hooks/useBargeIn.js

@@ -0,0 +1,65 @@
+import { useEffect, useRef, useState } from 'react';
+// =============================================================================
+// Hook
+// =============================================================================
+export function useBargeIn(options) {
+    const { stream, enabled = true, threshold = 0.02, hangoverMs = 250, onBargeIn } = options;
+    const [isUserSpeaking, setIsUserSpeaking] = useState(false);
+    const [levelRms, setLevelRms] = useState(0);
+    const rafRef = useRef(null);
+    const lastAboveRef = useRef(0);
+    const prevSpeakingRef = useRef(false);
+    useEffect(() => {
+        if (!enabled || !stream) {
+            setIsUserSpeaking(false);
+            setLevelRms(0);
+            return;
+        }
+        if (typeof AudioContext === 'undefined') {
+            // Cannot compute RMS without Web Audio; degrade gracefully.
+            return;
+        }
+        const audioContext = new AudioContext();
+        const source = audioContext.createMediaStreamSource(stream);
+        const analyser = audioContext.createAnalyser();
+        analyser.fftSize = 2048;
+        source.connect(analyser);
+        const buffer = new Float32Array(analyser.fftSize);
+        const tick = () => {
+            analyser.getFloatTimeDomainData(buffer);
+            let sum = 0;
+            for (let i = 0; i < buffer.length; i++) {
+                const x = buffer[i];
+                sum += x * x;
+            }
+            const rms = Math.sqrt(sum / buffer.length);
+            setLevelRms(rms);
+            const now = performance.now();
+            if (rms >= threshold) {
+                lastAboveRef.current = now;
+            }
+            const speaking = rms >= threshold || now - lastAboveRef.current <= hangoverMs;
+            setIsUserSpeaking(speaking);
+            if (!prevSpeakingRef.current && speaking) {
+                onBargeIn?.();
+            }
+            prevSpeakingRef.current = speaking;
+            rafRef.current = requestAnimationFrame(tick);
+        };
+        rafRef.current = requestAnimationFrame(tick);
+        return () => {
+            if (rafRef.current)
+                cancelAnimationFrame(rafRef.current);
+            rafRef.current = null;
+            try {
+                source.disconnect();
+                analyser.disconnect();
+            }
+            catch {
+                // Ignore.
+            }
+            audioContext.close().catch(() => { });
+        };
+    }, [stream, enabled, threshold, hangoverMs, onBargeIn]);
+    return { isUserSpeaking, levelRms };
+}

package/dist/audio/hooks/useCognitionSpeech.d.ts

@@ -0,0 +1,52 @@
+import type { AVO } from '../../emotion/types.js';
+import type { CognitionState, CognitionEvent } from '../../cognition/types.js';
+import type { EmotionTarget } from '../../cognition/controller.js';
+import type { AudioPolicy, AudioProof, AudioVerifier, SpeechSynthesisProvider, SpeechSynthesisRequest, SpeechSynthesisResult, VoiceCatalog } from '../types.js';
+export interface UseCognitionSpeechOptions {
+    provider: SpeechSynthesisProvider;
+    verifier?: AudioVerifier;
+    voices: VoiceCatalog;
+    policy: AudioPolicy;
+    volume?: number;
+    verificationMode?: 'before_playback' | 'after_playback' | 'never';
+    initialCognition?: Partial<CognitionState>;
+    autoTick?: boolean;
+    onCognitionChange?: (state: CognitionState) => void;
+    bargeIn?: {
+        stream: MediaStream | null;
+        threshold?: number;
+        hangoverMs?: number;
+    };
+    defaults?: {
+        voiceId?: string;
+        groundedVoiceTag?: string;
+        defaultVoiceTag?: string;
+        temperature?: number;
+    };
+    onProof?: (proof: AudioProof) => void;
+    onBargeIn?: () => void;
+    onError?: (error: Error) => void;
+}
+export interface SpeakWithCognitionOptions {
+    runId?: string;
+    language?: string;
+    targetAffect?: AVO;
+}
+export interface UseCognitionSpeechReturn {
+    cognition: CognitionState;
+    emotion: EmotionTarget;
+    handleCognition: (event: CognitionEvent) => void;
+    /** @deprecated Use handleCognition instead */
+    emitCognition: (event: CognitionEvent) => void;
+    tickCognition: (deltaMs: number) => void;
+    isSynthesizing: boolean;
+    isSpeaking: boolean;
+    error: string | null;
+    lastRequest: SpeechSynthesisRequest | null;
+    lastResult: SpeechSynthesisResult | null;
+    lastProof: AudioProof | null;
+    speak: (text: string, options?: SpeakWithCognitionOptions) => Promise<void>;
+    cancel: () => void;
+}
+export declare function useCognitionSpeech(options: UseCognitionSpeechOptions): UseCognitionSpeechReturn;
+//# sourceMappingURL=useCognitionSpeech.d.ts.map

package/dist/audio/hooks/useCognitionSpeech.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCognitionSpeech.d.ts","sourceRoot":"","sources":["../../../src/audio/hooks/useCognitionSpeech.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,aAAa,EACb,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,EACb,MAAM,aAAa,CAAC;AAOrB,MAAM,WAAW,yBAAyB;IAExC,QAAQ,EAAE,uBAAuB,CAAC;IAClC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,OAAO,CAAC;IAGlE,gBAAgB,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAGpD,OAAO,CAAC,EAAE;QACR,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;QAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IAGF,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IAGF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IAEvC,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,EAAE,aAAa,CAAC;IACvB,eAAe,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACjD,8CAA8C;IAC9C,aAAa,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAC/C,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAGzC,cAAc,EAAE,OAAO,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC3C,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACzC,SAAS,EAAE,UAAU,GAAG,IAAI,CAAC;IAE7B,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,yBAAyB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAMD,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,wBAAwB,CA6F1B"}

package/dist/audio/hooks/useCognitionSpeech.js

@@ -0,0 +1,77 @@
+'use client';
+import { useCallback } from 'react';
+import { useCognition } from '../../cognition/hooks/useCognition.js';
+import { planSpeechFromCognition } from '../planner.js';
+import { useSpeechSynthesis } from './useSpeechSynthesis.js';
+// =============================================================================
+// Hook
+// =============================================================================
+export function useCognitionSpeech(options) {
+    const { provider, verifier, voices, policy, volume, verificationMode, initialCognition, autoTick = true, onCognitionChange, bargeIn, defaults, onProof, onBargeIn, onError, } = options;
+    // Cognition state
+    const cognitionResult = useCognition({
+        initial: initialCognition,
+        autoTick,
+        onChange: onCognitionChange,
+    });
+    // Speech synthesis - uses signals derived from cognition
+    const speechResult = useSpeechSynthesis({
+        provider,
+        verifier,
+        voices,
+        policy,
+        volume,
+        verificationMode,
+        signals: {
+            mode: cognitionResult.state.mode,
+            personaDriftRisk: cognitionResult.state.personaDriftRisk,
+            confidence: cognitionResult.state.confidence,
+            risk: cognitionResult.state.risk,
+        },
+        defaults,
+        bargeIn,
+        onProof,
+        onBargeIn: () => {
+            // On barge-in, emit interrupt to cognition
+            cognitionResult.handleEvent({ type: 'ui.interrupt' });
+            onBargeIn?.();
+        },
+        onError,
+    });
+    // Speak using full cognition state
+    const speak = useCallback(async (text, speakOptions) => {
+        // Plan using full cognition state
+        const request = planSpeechFromCognition({
+            text,
+            language: speakOptions?.language,
+            runId: speakOptions?.runId,
+            targetAffect: speakOptions?.targetAffect,
+            cognition: cognitionResult.state,
+            policy,
+            voices,
+            defaults,
+        });
+        // Synthesize and play
+        await speechResult.speak(text, {
+            ...speakOptions,
+            targetAffect: request.targetAffect,
+        });
+    }, [cognitionResult.state, policy, voices, defaults, speechResult]);
+    return {
+        // Cognition
+        cognition: cognitionResult.state,
+        emotion: cognitionResult.emotion,
+        handleCognition: cognitionResult.handleEvent,
+        emitCognition: cognitionResult.handleEvent, // deprecated alias
+        tickCognition: cognitionResult.tick,
+        // Speech
+        isSynthesizing: speechResult.isSynthesizing,
+        isSpeaking: speechResult.isSpeaking,
+        error: speechResult.error,
+        lastRequest: speechResult.lastRequest,
+        lastResult: speechResult.lastResult,
+        lastProof: speechResult.lastProof,
+        speak,
+        cancel: speechResult.cancel,
+    };
+}

package/dist/audio/hooks/useHybridSpeech.d.ts

@@ -0,0 +1,24 @@
+import type { UseSpeechSynthesisOptions, UseSpeechSynthesisReturn, SpeakOptions } from './useSpeechSynthesis.js';
+import type { UseAudioOverlayOptions, UseAudioOverlayReturn } from './useAudioOverlay.js';
+export interface UseHybridSpeechOptions {
+    main: UseSpeechSynthesisOptions;
+    overlay: UseAudioOverlayOptions & {
+        enabled?: boolean;
+    };
+    /**
+     * If true, automatically stops overlay playback when main speech starts.
+     */
+    stopOverlayOnMainSpeak?: boolean;
+}
+export interface UseHybridSpeechReturn {
+    main: UseSpeechSynthesisReturn;
+    overlay: UseAudioOverlayReturn;
+    /**
+     * Convenience: play a quick acknowledgement (overlay) while synthesizing main speech.
+     * Overlay is best-effort and will not block main speech if it fails.
+     */
+    speakWithAck: (text: string, options?: SpeakOptions) => Promise<void>;
+    cancelAll: () => void;
+}
+export declare function useHybridSpeech(options: UseHybridSpeechOptions): UseHybridSpeechReturn;
+//# sourceMappingURL=useHybridSpeech.d.ts.map

package/dist/audio/hooks/useHybridSpeech.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHybridSpeech.d.ts","sourceRoot":"","sources":["../../../src/audio/hooks/useHybridSpeech.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEjH,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAO1F,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,yBAAyB,CAAC;IAChC,OAAO,EAAE,sBAAsB,GAAG;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAExD;;OAEG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,OAAO,EAAE,qBAAqB,CAAC;IAE/B;;;OAGG;IACH,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtE,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAMD,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAsCtF"}

package/dist/audio/hooks/useHybridSpeech.js

@@ -0,0 +1,40 @@
+import { useCallback, useEffect } from 'react';
+import { useSpeechSynthesis } from './useSpeechSynthesis.js';
+import { useAudioOverlay } from './useAudioOverlay.js';
+// =============================================================================
+// Hook
+// =============================================================================
+export function useHybridSpeech(options) {
+    const { main: mainOptions, overlay: overlayOptions, stopOverlayOnMainSpeak = true } = options;
+    const main = useSpeechSynthesis(mainOptions);
+    const overlayEnabled = overlayOptions.enabled !== false;
+    const overlay = useAudioOverlay(overlayOptions);
+    useEffect(() => {
+        if (!stopOverlayOnMainSpeak)
+            return;
+        if (!overlayEnabled)
+            return;
+        if (!main.isSpeaking)
+            return;
+        overlay.cancel();
+    }, [stopOverlayOnMainSpeak, overlayEnabled, main.isSpeaking, overlay]);
+    const speakWithAck = useCallback(async (text, speakOptions) => {
+        if (overlayEnabled) {
+            void overlay.speakToken('ack', speakOptions).catch(() => { });
+        }
+        try {
+            await main.speak(text, speakOptions);
+        }
+        catch (err) {
+            if (overlayEnabled)
+                overlay.cancel();
+            throw err;
+        }
+    }, [overlayEnabled, overlay, main]);
+    const cancelAll = useCallback(() => {
+        main.cancel();
+        if (overlayEnabled)
+            overlay.cancel();
+    }, [main, overlayEnabled, overlay]);
+    return { main, overlay, speakWithAck, cancelAll };
+}

package/dist/audio/hooks/useRunSpeechCues.d.ts

@@ -0,0 +1,28 @@
+import type { RunStatus } from '../../protocol/types.js';
+import type { OverlayToken } from '../overlay.js';
+export interface RunSpeechCueMap {
+    onStart?: OverlayToken;
+    onComplete?: OverlayToken;
+    onFail?: OverlayToken;
+    onCancel?: OverlayToken;
+}
+export interface UseRunSpeechCuesOptions {
+    runId: string | null;
+    enabled?: boolean;
+    /**
+     * Called with the selected overlay token. Typical implementation calls
+     * `overlay.speakToken(token, { runId })`.
+     */
+    emit: (token: OverlayToken, args: {
+        runId: string;
+        status: RunStatus;
+    }) => void | Promise<void>;
+    cues?: RunSpeechCueMap;
+    /**
+     * Minimum time between cue emissions (prevents spam on flappy status updates).
+     */
+    cooldownMs?: number;
+}
+export declare const DEFAULT_RUN_SPEECH_CUES: Required<RunSpeechCueMap>;
+export declare function useRunSpeechCues(options: UseRunSpeechCuesOptions): void;
+//# sourceMappingURL=useRunSpeechCues.d.ts.map

package/dist/audio/hooks/useRunSpeechCues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRunSpeechCues.d.ts","sourceRoot":"","sources":["../../../src/audio/hooks/useRunSpeechCues.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAMlD,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhG,IAAI,CAAC,EAAE,eAAe,CAAC;IAEvB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,eAAe,CAK7D,CAAC;AAMF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAiCvE"}

package/dist/audio/hooks/useRunSpeechCues.js

@@ -0,0 +1,47 @@
+import { useEffect, useRef } from 'react';
+import { useRunStream } from '../../hooks/useRunStream.js';
+// =============================================================================
+// Defaults
+// =============================================================================
+export const DEFAULT_RUN_SPEECH_CUES = {
+    onStart: 'hold',
+    onComplete: 'done',
+    onFail: 'error',
+    onCancel: 'warning',
+};
+// =============================================================================
+// Hook
+// =============================================================================
+export function useRunSpeechCues(options) {
+    const { runId, enabled = true, emit, cues, cooldownMs = 800 } = options;
+    const { status } = useRunStream(runId);
+    const prevStatusRef = useRef(null);
+    const lastEmitAtRef = useRef(0);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        if (!runId)
+            return;
+        const prev = prevStatusRef.current;
+        prevStatusRef.current = status;
+        if (prev === status)
+            return;
+        const now = Date.now();
+        if (now - lastEmitAtRef.current < cooldownMs)
+            return;
+        const cueMap = { ...DEFAULT_RUN_SPEECH_CUES, ...(cues ?? {}) };
+        let token = null;
+        if (status === 'running')
+            token = cueMap.onStart;
+        if (status === 'completed')
+            token = cueMap.onComplete;
+        if (status === 'failed')
+            token = cueMap.onFail;
+        if (status === 'cancelled')
+            token = cueMap.onCancel;
+        if (!token)
+            return;
+        lastEmitAtRef.current = now;
+        void emit(token, { runId, status });
+    }, [enabled, runId, status, emit, cues, cooldownMs]);
+}

package/dist/audio/hooks/useSpeechSynthesis.d.ts

@@ -0,0 +1,58 @@
+import type { AVO } from '../../emotion/types.js';
+import { type AudioPlannerSignals } from '../planner.js';
+import type { AudioPolicy, AudioProof, AudioVerifier, SpeechSynthesisProvider, SpeechSynthesisRequest, SpeechSynthesisResult, VoiceCatalog } from '../types.js';
+export interface UseSpeechSynthesisOptions {
+    provider: SpeechSynthesisProvider;
+    verifier?: AudioVerifier;
+    voices: VoiceCatalog;
+    policy: AudioPolicy;
+    signals?: AudioPlannerSignals;
+    defaults?: {
+        voiceId?: string;
+        groundedVoiceTag?: string;
+        defaultVoiceTag?: string;
+        temperature?: number;
+    };
+    /**
+     * If provided, enables barge-in (user speech cancels synthesis and playback).
+     */
+    bargeIn?: {
+        stream: MediaStream | null;
+        threshold?: number;
+        hangoverMs?: number;
+    };
+    /**
+     * Playback volume 0..1
+     */
+    volume?: number;
+    /**
+     * Controls when verification happens.
+     *
+     * - "before_playback": verify first; only play if verified (best for high-trust lanes)
+     * - "after_playback": play immediately; verify in background (best UX when trust allows)
+     * - "never": do not verify (not recommended)
+     *
+     * Default: derived from policy (`requireProofBeforePlayback`).
+     */
+    verificationMode?: 'before_playback' | 'after_playback' | 'never';
+    onProof?: (proof: AudioProof) => void;
+    onBargeIn?: () => void;
+    onError?: (error: Error) => void;
+}
+export interface SpeakOptions {
+    runId?: string;
+    language?: string;
+    targetAffect?: AVO;
+}
+export interface UseSpeechSynthesisReturn {
+    isSynthesizing: boolean;
+    isSpeaking: boolean;
+    error: string | null;
+    lastRequest: SpeechSynthesisRequest | null;
+    lastResult: SpeechSynthesisResult | null;
+    lastProof: AudioProof | null;
+    speak: (text: string, options?: SpeakOptions) => Promise<void>;
+    cancel: () => void;
+}
+export declare function useSpeechSynthesis(options: UseSpeechSynthesisOptions): UseSpeechSynthesisReturn;
+//# sourceMappingURL=useSpeechSynthesis.d.ts.map

package/dist/audio/hooks/useSpeechSynthesis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSpeechSynthesis.d.ts","sourceRoot":"","sources":["../../../src/audio/hooks/useSpeechSynthesis.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAc,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAErE,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,aAAa,EACb,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,EACb,MAAM,aAAa,CAAC;AAQrB,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,uBAAuB,CAAC;IAClC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAEzB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;IAEpB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,CAAC,EAAE;QACT,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IAEF;;OAEG;IACH,OAAO,CAAC,EAAE;QACR,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;QAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IAEF;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,OAAO,CAAC;IAElE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,OAAO,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAErB,WAAW,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC3C,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACzC,SAAS,EAAE,UAAU,GAAG,IAAI,CAAC;IAE7B,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAMD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,wBAAwB,CAiL/F"}