@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/dist/voice/useDictation.js

@@ -1,60 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { webSpeechVoice } from "./webSpeech.js";
-/**
- * Dictating into a message box: the words settle into `onFinal` sentence by sentence while
- * `interim` shows what is still being heard, until `stop`, or until the browser ends the session
- * or refuses the microphone. It is the voice window's transport (`webSpeechVoice`) without the
- * conversation, and without reading the microphone's level, which a box to write in does not
- * show and some browsers do not like having a second reader of.
- */
-export function useDictation({ lang, onFinal }) {
-    const voice = useMemo(() => webSpeechVoice({ lang, meter: false }), [lang]);
-    const [listening, setListening] = useState(false);
-    const [interim, setInterim] = useState("");
-    // The session the buttons and the words on screen belong to; none once it was stopped.
-    const mine = useRef(undefined);
-    const sessions = useRef(0);
-    // The latest `onFinal`, for a session started earlier.
-    const final = useRef(onFinal);
-    useEffect(() => {
-        final.current = onFinal;
-    }, [onFinal]);
-    const stop = useCallback(() => {
-        mine.current = undefined;
-        voice.stopListening();
-        setListening(false);
-        setInterim("");
-    }, [voice]);
-    const start = useCallback(() => {
-        if (!voice.supported || mine.current !== undefined)
-            return;
-        sessions.current += 1;
-        const session = sessions.current;
-        mine.current = session;
-        setListening(true);
-        void (async () => {
-            try {
-                for await (const heard of voice.listen()) {
-                    // Words said just before `stop` still arrive; only the screen is no longer theirs.
-                    if (heard.final)
-                        final.current(heard.text);
-                    if (mine.current !== session)
-                        continue;
-                    setInterim(heard.final ? "" : heard.text);
-                }
-            }
-            catch {
-                // A refusal or a failure ends the dictation, as the end of the session does.
-            }
-            finally {
-                if (mine.current === session) {
-                    mine.current = undefined;
-                    setListening(false);
-                    setInterim("");
-                }
-            }
-        })();
-    }, [voice]);
-    useEffect(() => stop, [stop]);
-    return { supported: voice.supported, listening, interim, start, stop };
-}

package/dist/voice/useReducedMotion.d.ts

@@ -1,5 +0,0 @@
-/**
- * Whether the person asked their system for less motion. It follows the setting while the page
- * is open. Without `matchMedia` (a server, an old browser) there is no such request.
- */
-export declare function useReducedMotion(): boolean;

package/dist/voice/useVoice.d.ts

@@ -1,70 +0,0 @@
-import type { SurfaceData } from "../surface/types.js";
-import { type Voice, type VoiceState } from "./voice.js";
-/** What was said and answered in one turn of the conversation. */
-export interface VoiceTurn {
-    /** What the person said. */
-    said: string;
-    /** What the agent answered, in words; empty when it only showed something. */
-    answer: string;
-    /** What the agent showed with its answer. The host decides where it goes. */
-    surfaces: SurfaceData[];
-}
-export interface VoiceOptions {
-    /** The agent the person talks to. */
-    agentId: string;
-    /** The conversation to speak in; the agent remembers it across turns. */
-    thread?: string | undefined;
-    /**
-     * The way of talking and listening. Default: the browser's own, in `lang`. Make it once (at
-     * module level, or memoized): a new one on every render starts the listening over each time.
-     */
-    voice?: Voice | undefined;
-    /** The language to listen and speak in, as a BCP 47 tag. Default: the provider's locale's. */
-    lang?: string | undefined;
-    /**
-     * Go back to listening after each answer (default), so the conversation goes on until it is
-     * stopped. Without it, one turn is held and the conversation ends once the answer is said.
-     */
-    continuous?: boolean | undefined;
-    /** A turn was answered: what was said and what came back, for the host's own records. */
-    onTurn?: ((turn: VoiceTurn) => void) | undefined;
-    /** The agent showed something with its answer. The voice does not draw it; the host places it. */
-    onSurfaces?: ((surfaces: SurfaceData[]) => void) | undefined;
-}
-export interface VoiceConversation {
-    /** Whether this browser can hold a voice conversation. Nothing starts where it cannot. */
-    supported: boolean;
-    /**
-     * Where the conversation stands: `listening` while the microphone is open, `thinking` from
-     * when the person pauses until the answer arrives, `speaking` while it is said.
-     */
-    state: VoiceState;
-    /** How loud the microphone or the voice is, from 0 to 1, for the orb. */
-    level: number;
-    /** What was heard, as it comes and once it is whole. */
-    transcript: string;
-    /** What the agent said last. */
-    captions: string;
-    /** A conversation is open: the microphone is wanted when it is the person's turn. */
-    active: boolean;
-    /** The microphone is off, though the conversation is open. */
-    muted: boolean;
-    /** Something went wrong; the text is for the person. */
-    problem: string | undefined;
-    /** Opens the conversation. Call it from a click: browsers let nothing speak before that. */
-    start: () => void;
-    /** Ends it, cutting short whatever is being said or heard. */
-    stop: () => void;
-    /** Turns the microphone off or on (the agent's answer to what was already said still comes). */
-    mute: (muted?: boolean) => void;
-}
-/**
- * A spoken conversation with an agent: it listens, sends what the person said as their message
- * (with `modality: "voice"`, so the agent knows they are listening and keeps its answer short),
- * waits while the answer comes, and says it. Then, if `continuous`, it listens again.
- *
- * The loop only decides *when*: the turn is sent the way the chat sends its own (`useTurns`),
- * and how to hear and speak is the `Voice`'s. The microphone is open only on the person's turn,
- * never while an answer is coming or being said, so the agent does not hear itself.
- */
-export declare function useVoice(options: VoiceOptions): VoiceConversation;

package/dist/voice/useVoice.js

@@ -1,197 +0,0 @@
-import { useCallback, useEffect, useMemo, useReducer, useRef, useState, useSyncExternalStore, } from "react";
-import { useTurns } from "../chat/useTurns.js";
-import { useLanguage, useMessages, useSignalcore } from "../SignalcoreProvider.js";
-import { VoiceError } from "./voice.js";
-import { webSpeechVoice } from "./webSpeech.js";
-/** The language each locale speaks and listens in, unless the host says another. */
-const LANGUAGE_TAGS = { es: "es-ES", en: "en-US" };
-/** How long to wait before listening again when the browser ended a session by itself. */
-const RELISTEN_MS = 300;
-const FIRST = { open: false, muted: false, asked: false, queue: [], taken: undefined };
-function step(loop, event) {
-    switch (event.type) {
-        case "start":
-            return { ...loop, open: true, asked: false, queue: [] };
-        case "stop":
-            return { ...loop, open: false, queue: [] };
-        case "mute":
-            return { ...loop, muted: event.muted ?? !loop.muted };
-        case "asked":
-            return { ...loop, asked: true };
-        case "answered":
-            // Said only while the conversation is open: an answer that comes after it was ended is
-            // still shown, but it is not read out to someone who left.
-            return {
-                ...loop,
-                taken: event.reply.id,
-                queue: loop.open && event.reply.text !== "" ? [...loop.queue, event.reply] : loop.queue,
-            };
-        case "said":
-            return { ...loop, queue: loop.queue.filter((each) => each !== event.reply) };
-    }
-}
-/** The agent's latest message. */
-const latestReply = (said) => said.findLast((message) => message.role === "agent");
-/** What the person said that this message answers. */
-function questionOf(said, reply) {
-    const before = said.slice(0, said.indexOf(reply));
-    return before.findLast((message) => message.role === "person")?.text ?? "";
-}
-/** The words for a voice that failed: the person's to fix when they said no, ours otherwise. */
-function troubleWith(error, copy) {
-    if (error instanceof VoiceError) {
-        if (error.reason === "denied")
-            return copy.voiceDenied;
-        if (error.reason === "unsupported")
-            return copy.voiceUnsupported;
-    }
-    return copy.voiceFailed;
-}
-/**
- * A spoken conversation with an agent: it listens, sends what the person said as their message
- * (with `modality: "voice"`, so the agent knows they are listening and keeps its answer short),
- * waits while the answer comes, and says it. Then, if `continuous`, it listens again.
- *
- * The loop only decides *when*: the turn is sent the way the chat sends its own (`useTurns`),
- * and how to hear and speak is the `Voice`'s. The microphone is open only on the person's turn,
- * never while an answer is coming or being said, so the agent does not hear itself.
- */
-export function useVoice(options) {
-    const { agentId, thread, continuous = true } = options;
-    const { client } = useSignalcore();
-    const { locale } = useLanguage();
-    const copy = useMessages();
-    const lang = options.lang ?? LANGUAGE_TAGS[locale];
-    const browser = useMemo(() => webSpeechVoice({ lang }), [lang]);
-    const voice = options.voice ?? browser;
-    const turns = useTurns({ agentId, thread, modality: "voice" });
-    const [loop, dispatch] = useReducer(step, FIRST);
-    const [transcript, setTranscript] = useState("");
-    const [trouble, setTrouble] = useState();
-    // Counts the times listening has to begin again while the person's turn goes on: the browser
-    // ended a session by itself, or what was heard could not be sent.
-    const [relistened, setRelistened] = useState(0);
-    // The agent's words are taken once each, as they arrive: said aloud if the person is there.
-    const reply = useMemo(() => latestReply(turns.said), [turns.said]);
-    if (reply && reply.id !== loop.taken)
-        dispatch({ type: "answered", reply });
-    const busy = turns.answering || turns.waiting;
-    // One turn was asked for and nothing more is coming: the conversation is over.
-    const finished = !continuous && loop.asked && !busy && loop.queue.length === 0;
-    const open = loop.open && !finished;
-    const speaking = loop.queue[0];
-    const listening = open && !loop.muted && !busy && speaking === undefined;
-    const latest = useRef({ turns, options, copy });
-    useEffect(() => {
-        latest.current = { turns, options, copy };
-    });
-    // The microphone is open exactly while it is the person's turn.
-    useEffect(() => {
-        if (!listening)
-            return undefined;
-        let current = true;
-        let again;
-        const hear = async () => {
-            try {
-                for await (const heard of voice.listen()) {
-                    if (!current)
-                        return;
-                    setTranscript(heard.text);
-                    if (heard.final && heard.text !== "") {
-                        // The person paused: what they said is the turn, and the microphone closes.
-                        current = false;
-                        voice.stopListening();
-                        if (latest.current.turns.ask({ input: heard.text }, heard.text)) {
-                            dispatch({ type: "asked" });
-                        }
-                        else {
-                            // Nothing could be sent: listen again rather than leave the person unheard.
-                            setRelistened((count) => count + 1);
-                        }
-                        return;
-                    }
-                }
-                // The browser ended the session (a long silence): the person is still there.
-                if (current) {
-                    again = setTimeout(() => {
-                        setRelistened((count) => count + 1);
-                    }, RELISTEN_MS);
-                }
-            }
-            catch (error) {
-                if (!current)
-                    return;
-                setTrouble(troubleWith(error, latest.current.copy));
-                dispatch({ type: "stop" });
-            }
-        };
-        void hear();
-        return () => {
-            current = false;
-            clearTimeout(again);
-            voice.stopListening();
-        };
-    }, [listening, voice, relistened]);
-    // The agent's answer is said, one at a time.
-    useEffect(() => {
-        if (!speaking)
-            return undefined;
-        let current = true;
-        const said = () => {
-            if (current)
-                dispatch({ type: "said", reply: speaking });
-        };
-        voice.speak(speaking.text).then(said, (error) => {
-            if (current)
-                setTrouble(troubleWith(error, latest.current.copy));
-            said();
-        });
-        return () => {
-            current = false;
-            voice.stopSpeaking();
-        };
-    }, [speaking, voice]);
-    // The host hears of each answer once, and of what it showed.
-    const question = reply ? questionOf(turns.said, reply) : "";
-    useEffect(() => {
-        if (!reply)
-            return;
-        const { onTurn, onSurfaces } = latest.current.options;
-        onTurn?.({ said: question, answer: reply.text, surfaces: reply.surfaces });
-        if (reply.surfaces.length > 0)
-            onSurfaces?.(reply.surfaces);
-    }, [reply, question]);
-    const available = client?.agents?.invoke !== undefined;
-    const start = useCallback(() => {
-        if (!voice.supported)
-            return;
-        setTrouble(available ? undefined : copy.chatUnavailable);
-        if (!available)
-            return;
-        setTranscript("");
-        dispatch({ type: "start" });
-    }, [voice, available, copy.chatUnavailable]);
-    const stop = useCallback(() => {
-        dispatch({ type: "stop" });
-    }, []);
-    const mute = useCallback((muted) => {
-        dispatch({ type: "mute", muted });
-    }, []);
-    const heardState = useSyncExternalStore(voice.subscribe, () => voice.state, () => "idle");
-    const heardLevel = useSyncExternalStore(voice.subscribe, () => voice.level, () => 0);
-    // The loop knows when the person is waiting on the agent; the voice knows what it hears and says.
-    const state = !open ? "idle" : speaking ? "speaking" : busy ? "thinking" : heardState;
-    return {
-        supported: voice.supported,
-        state,
-        level: open ? heardLevel : 0,
-        transcript,
-        captions: reply?.text ?? "",
-        active: open,
-        muted: loop.muted,
-        problem: turns.problem ?? trouble,
-        start,
-        stop,
-        mute,
-    };
-}

package/dist/voice/useVoicePrimitives.d.ts

@@ -1,7 +0,0 @@
-import type { Primitives } from "../host.js";
-/**
- * What the voice window is built from, as `usePrimitives` is for surfaces: the host's `Orb` where
- * the provider has one (`components={{ Orb }}`), ours otherwise. It is kept apart from
- * `usePrimitives` because the default orb is in this entry, and the core does not load it.
- */
-export declare function useVoicePrimitives(): Pick<Primitives, "Orb">;

package/dist/voice/useVoicePrimitives.js

@@ -1,11 +0,0 @@
-import { useSignalcore } from "../SignalcoreProvider.js";
-import { Orb } from "./Orb.js";
-/**
- * What the voice window is built from, as `usePrimitives` is for surfaces: the host's `Orb` where
- * the provider has one (`components={{ Orb }}`), ours otherwise. It is kept apart from
- * `usePrimitives` because the default orb is in this entry, and the core does not load it.
- */
-export function useVoicePrimitives() {
-    const { components } = useSignalcore();
-    return { Orb: Object.hasOwn(components, "Orb") ? (components.Orb ?? Orb) : Orb };
-}

package/dist/voice/voice.d.ts

@@ -1,55 +0,0 @@
-/**
- * Where a voice conversation stands: `idle` (nobody is talking), `listening` (the microphone is
- * open), `thinking` (the person finished and the agent is working on the answer), `speaking`
- * (the agent's answer is being said). The orb is drawn from it.
- */
-export type VoiceState = "idle" | "listening" | "thinking" | "speaking";
-/**
- * What the person is saying. `final` is false while they speak (the words so far, which may
- * still change) and true once they pause: that text is a whole utterance and will not change.
- */
-export interface Heard {
-    text: string;
-    final: boolean;
-}
-/** Why a voice could not do what was asked: it cannot here, it was refused, or it broke. */
-export type VoiceFailure = "unsupported" | "denied" | "failed";
-/** What a transport throws from `listen()` when it cannot go on; `reason` says why. */
-export declare class VoiceError extends Error {
-    readonly reason: VoiceFailure;
-    constructor(reason: VoiceFailure, message?: string);
-}
-/**
- * What a way of talking and listening does, and nothing about the agent: the browser's own speech
- * APIs are the first one (`webSpeechVoice`), and a provider's (a hosted assistant over WebRTC)
- * can come behind the same shape. `useVoice` runs the conversation on top of one.
- *
- * `state` and `level` can be read at any time and change over time; `subscribe` tells when (it
- * has the shape React's `useSyncExternalStore` takes).
- */
-export interface Voice {
-    /** Whether this browser can hold a voice conversation at all (listen and speak). */
-    readonly supported: boolean;
-    readonly state: VoiceState;
-    /**
-     * How loud it is right now, from 0 to 1: the microphone while listening, the voice while
-     * speaking, 0 otherwise. Already smoothed, so it can drive an animation as it is.
-     */
-    readonly level: number;
-    /** Calls `listener` whenever `state` or `level` change; the result stops it. */
-    subscribe: (listener: () => void) => () => void;
-    /**
-     * Opens the microphone and says what the person says: the words so far while they speak, then
-     * the whole utterance when they pause. The iteration ends when listening stops, by
-     * `stopListening`, by leaving the loop, or because the transport ended it (a long silence);
-     * it throws a `VoiceError` when listening cannot go on. Words still in flight when listening
-     * is stopped may arrive before it ends.
-     */
-    listen: () => AsyncIterable<Heard>;
-    /** Closes the microphone. */
-    stopListening: () => void;
-    /** Says the words aloud; resolves when they have been said, or were cut by `stopSpeaking`. */
-    speak: (text: string) => Promise<void>;
-    /** Cuts the voice short. */
-    stopSpeaking: () => void;
-}

package/dist/voice/voice.js

@@ -1,9 +0,0 @@
-/** What a transport throws from `listen()` when it cannot go on; `reason` says why. */
-export class VoiceError extends Error {
-    reason;
-    constructor(reason, message = reason) {
-        super(message);
-        this.name = "VoiceError";
-        this.reason = reason;
-    }
-}

package/dist/voice/webSpeech.d.ts

@@ -1,33 +0,0 @@
-import { type Voice } from "./voice.js";
-/**
- * The voice to speak a language with: one of the exact region (`es-ES`), else one of the same
- * language, the browser's default for it first. Nothing when the browser has none yet (the list
- * loads late); the utterance's `lang` then lets the browser choose.
- */
-export declare function voiceFor(voices: readonly SpeechSynthesisVoice[], lang: string): SpeechSynthesisVoice | undefined;
-export interface WebSpeechOptions {
-    /** The language spoken and heard, as a BCP 47 tag (`"es-ES"`, `"en-US"`). */
-    lang: string;
-    /**
-     * Read the microphone's loudness while listening, with a second stream beside the recognizer's
-     * (default). Turn it off where only the words matter, such as dictating into a message box:
-     * some browsers do not like two readers of the microphone, and the level is not shown there.
-     */
-    meter?: boolean;
-}
-/**
- * The first way to talk and listen: the browser's own speech recognition and speech synthesis,
- * with nothing to install and nothing sent to us. Quality is the browser's (the voice, how well
- * it hears accents), which is why a provider's transport can come behind the same `Voice`.
- *
- * - **Listening.** One recognizer session at a time, continuous with interim results. While it
- *   runs, the microphone's real loudness comes from an `AnalyserNode` (see `meter`).
- * - **Speaking.** `speechSynthesis` with a voice picked for the language. Speaking closes the
- *   microphone first, so the agent does not hear itself.
- * - **The level while speaking is an estimate.** `speechSynthesis` exposes no audio stream to
- *   measure, so the loudness is made up from what it does say: every `boundary` event (a word
- *   starts) pushes it up in proportion to the word, and it falls back between words, over a
- *   floor so a voice whose engine sends no boundaries still moves. It follows the rhythm of the
- *   speech, not its volume.
- */
-export declare function webSpeechVoice({ lang, meter }: WebSpeechOptions): Voice;