solid-drift 0.25.0 → 0.27.0

package/dist/voice.js

@@ -0,0 +1,577 @@
+import { createSignal, onCleanup } from "solid-js";
+import { schedule } from "./engine.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/* ------------------------------------------------------------------ */
+/* Shared browser globals (stub-friendly for tests)                     */
+/* ------------------------------------------------------------------ */
+const g = globalThis;
+function getSpeechRecognitionCtor() {
+    const ctor = g["SpeechRecognition"] ?? g["webkitSpeechRecognition"];
+    return ctor ?? null;
+}
+function getAudioContextCtor() {
+    const ctor = g["AudioContext"] ?? g["webkitAudioContext"];
+    return ctor ?? null;
+}
+/**
+ * The state machine behind a voice assistant turn: the user speaks
+ * (`listening`), the app works (`thinking`), the app replies
+ * (`speaking`), then back to `idle`. Wire the phases to
+ * `createSpeech` (listening), your model call (thinking), and
+ * `createTTS` (speaking).
+ *
+ * ```ts
+ * const voice = createVoiceState();
+ * voice.toListening();          // mic open
+ * // ... transcript arrives
+ * voice.toThinking();           // calling the model
+ * // ... reply ready
+ * voice.toSpeaking();           // TTS playing
+ * voice.toIdle();
+ * ```
+ */
+export function createVoiceState() {
+    const [state, setState] = createSignal("idle");
+    return {
+        state,
+        toIdle: () => setState("idle"),
+        toListening: () => setState("listening"),
+        toThinking: () => setState("thinking"),
+        toSpeaking: () => setState("speaking"),
+    };
+}
+/**
+ * A live microphone volume meter: `getUserMedia` plus an
+ * `AnalyserNode`, smoothed to a 0..1 level signal.
+ *
+ * ```ts
+ * const mic = createMicLevel();
+ * // in a click handler:
+ * await mic.start();
+ * <div style={{ width: `${mic.level() * 100}%` }} />
+ * ```
+ *
+ * SSR-safe: `supported` is false without WebAudio/getUserMedia and
+ * `start()` rejects there.
+ */
+export function createMicLevel(options = {}) {
+    const { fftSize = 512, smoothing = 0.7, gain = 3, onLevel } = options;
+    const [level, setLevel] = createSignal(0);
+    const [active, setActive] = createSignal(false);
+    const [analyser, setAnalyser] = createSignal(null);
+    const [error, setError] = createSignal(null);
+    const supported = getAudioContextCtor() !== null &&
+        typeof g["navigator"]?.mediaDevices
+            ?.getUserMedia === "function";
+    let context = null;
+    let stream = null;
+    let ownsStream = false;
+    let cancelLoop = null;
+    let current = 0;
+    const stop = () => {
+        cancelLoop?.();
+        cancelLoop = null;
+        if (ownsStream) {
+            stream?.getTracks().forEach((t) => t.stop());
+        }
+        stream = null;
+        ownsStream = false;
+        if (context) {
+            void context.close().catch(() => { });
+            context = null;
+        }
+        setAnalyser(null);
+        current = 0;
+        setLevel(0);
+        setActive(false);
+    };
+    const start = async () => {
+        if (active())
+            return;
+        setError(null);
+        try {
+            const Ctor = getAudioContextCtor();
+            const gum = g["navigator"]?.mediaDevices
+                ?.getUserMedia;
+            if (!Ctor || !gum) {
+                throw new Error("createMicLevel: WebAudio or getUserMedia is not available");
+            }
+            if (options.stream) {
+                stream = options.stream;
+                ownsStream = false;
+            }
+            else {
+                stream = await gum.call(g["navigator"].mediaDevices, { audio: true });
+                ownsStream = true;
+            }
+            context = new Ctor();
+            if (context.state === "suspended") {
+                await context.resume().catch(() => { });
+            }
+            const node = context.createAnalyser();
+            node.fftSize = fftSize;
+            context.createMediaStreamSource(stream).connect(node);
+            setAnalyser(node);
+            const data = new Uint8Array(node.frequencyBinCount);
+            setActive(true);
+            cancelLoop = schedule(() => {
+                if (!active())
+                    return false;
+                node.getByteTimeDomainData(data);
+                let sum = 0;
+                for (let i = 0; i < data.length; i++) {
+                    const v = (data[i] - 128) / 128;
+                    sum += v * v;
+                }
+                const rms = Math.sqrt(sum / data.length);
+                const target = Math.min(1, rms * gain);
+                current = smoothing * current + (1 - smoothing) * target;
+                setLevel(current);
+                onLevel?.(current);
+                return true;
+            });
+        }
+        catch (e) {
+            stop();
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            throw err;
+        }
+    };
+    onCleanup(stop);
+    return { level, active, supported, analyser, error, start, stop };
+}
+/**
+ * Speech-to-text via the Web Speech API (`SpeechRecognition` with
+ * `webkitSpeechRecognition` fallback).
+ *
+ * ```ts
+ * const speech = createSpeech({ lang: "en-US" });
+ * // in a click handler:
+ * speech.start();
+ * <p>{speech.transcript()}<span class="dim">{speech.interim()}</span></p>
+ * ```
+ *
+ * SSR-safe: `supported` is false without the API and `start()` is a
+ * no-op there. Note the API itself is a browser/cloud service with
+ * per-browser availability and limits.
+ */
+export function createSpeech(options = {}) {
+    const { continuous = false, interimResults = true, onResult, onError, } = options;
+    const [listening, setListening] = createSignal(false);
+    const [transcript, setTranscript] = createSignal("");
+    const [interim, setInterim] = createSignal("");
+    const [error, setError] = createSignal(null);
+    const Ctor = getSpeechRecognitionCtor();
+    const supported = Ctor !== null;
+    let recognition = null;
+    let wantListening = false;
+    const ensure = () => {
+        if (!Ctor)
+            return null;
+        if (!recognition) {
+            recognition = new Ctor();
+            recognition.lang =
+                options.lang ??
+                    g["navigator"]?.language ??
+                    "en-US";
+            recognition.continuous = continuous;
+            recognition.interimResults = interimResults;
+            recognition.onstart = () => setListening(true);
+            recognition.onresult = (event) => {
+                let interimText = "";
+                for (let i = event.resultIndex; i < event.results.length; i++) {
+                    const result = event.results[i];
+                    const text = result[0]?.transcript ?? "";
+                    if (result.isFinal) {
+                        setTranscript((prev) => prev + text);
+                        onResult?.(text, true);
+                    }
+                    else {
+                        interimText += text;
+                        onResult?.(text, false);
+                    }
+                }
+                setInterim(interimText);
+            };
+            recognition.onerror = (event) => {
+                const err = new Error(`Speech recognition error: ${event.error}${event.message ? ` - ${event.message}` : ""}`);
+                setError(err);
+                onError?.(err);
+            };
+            recognition.onend = () => {
+                setListening(false);
+                // Chrome ends the session on silence even when continuous;
+                // restart while the user still wants to listen.
+                if (wantListening && continuous && recognition) {
+                    try {
+                        recognition.start();
+                    }
+                    catch {
+                        wantListening = false;
+                    }
+                }
+            };
+        }
+        return recognition;
+    };
+    const start = () => {
+        const rec = ensure();
+        if (!rec)
+            return;
+        setError(null);
+        wantListening = true;
+        try {
+            rec.start();
+        }
+        catch {
+            // Already started; the running session stands.
+        }
+    };
+    const stop = () => {
+        wantListening = false;
+        try {
+            recognition?.stop();
+        }
+        catch {
+            // Already stopped.
+        }
+        setListening(false);
+    };
+    const reset = () => {
+        setTranscript("");
+        setInterim("");
+    };
+    onCleanup(stop);
+    return { supported, listening, transcript, interim, error, start, stop, reset };
+}
+/**
+ * A canvas waveform renderer driven by an `AnalyserNode`.
+ *
+ * ```tsx
+ * const mic = createMicLevel();
+ * createWaveform(() => canvas, { analyser: mic.analyser, mode: "bars" });
+ * <canvas ref={canvas} style={{ width: "100%", height: "64px" }} />
+ * ```
+ *
+ * The canvas is sized to its CSS box times the device pixel ratio.
+ * Under reduced motion it redraws at most every 250ms. SSR-safe:
+ * nothing renders without a canvas.
+ */
+export function createWaveform(canvas, options) {
+    const { analyser, color = "#3e6c99", lineWidth = 2, mode = "line", background = null, enabled = true, } = options;
+    const [active, setActive] = createSignal(false);
+    const isEnabled = () => typeof enabled === "function" ? enabled() : enabled;
+    if (typeof window === "undefined")
+        return { active };
+    let cancel = null;
+    let lastDraw = 0;
+    const reduced = prefersReducedMotion();
+    const draw = (t) => {
+        if (!isEnabled()) {
+            setActive(false);
+            return false;
+        }
+        setActive(true);
+        if (reduced && t - lastDraw < 250)
+            return true;
+        lastDraw = t;
+        const el = canvas();
+        const node = analyser();
+        if (!el || typeof el.getContext !== "function")
+            return true;
+        const dpr = Math.min(2, g["devicePixelRatio"] ?? 1);
+        const w = el.clientWidth * dpr;
+        const h = el.clientHeight * dpr;
+        if (w <= 0 || h <= 0)
+            return true;
+        if (el.width !== Math.round(w) || el.height !== Math.round(h)) {
+            el.width = Math.round(w);
+            el.height = Math.round(h);
+        }
+        const ctx = el.getContext("2d");
+        if (!ctx)
+            return true;
+        ctx.clearRect(0, 0, el.width, el.height);
+        if (background) {
+            ctx.fillStyle = background;
+            ctx.fillRect(0, 0, el.width, el.height);
+        }
+        ctx.strokeStyle = color;
+        ctx.fillStyle = color;
+        ctx.lineWidth = lineWidth * dpr;
+        if (!node) {
+            // Idle baseline.
+            ctx.beginPath();
+            ctx.moveTo(0, el.height / 2);
+            ctx.lineTo(el.width, el.height / 2);
+            ctx.stroke();
+            return true;
+        }
+        if (mode === "bars") {
+            const data = new Uint8Array(node.frequencyBinCount);
+            node.getByteFrequencyData(data);
+            const bars = Math.min(64, data.length);
+            const bw = el.width / bars;
+            for (let i = 0; i < bars; i++) {
+                const v = data[Math.floor((i / bars) * data.length)] / 255;
+                const bh = Math.max(2 * dpr, v * el.height);
+                ctx.fillRect(i * bw + bw * 0.15, el.height - bh, bw * 0.7, bh);
+            }
+        }
+        else {
+            const data = new Uint8Array(node.frequencyBinCount);
+            node.getByteTimeDomainData(data);
+            ctx.beginPath();
+            const mid = el.height / 2;
+            for (let i = 0; i < data.length; i++) {
+                const x = (i / (data.length - 1)) * el.width;
+                const y = mid + ((data[i] - 128) / 128) * mid;
+                if (i === 0)
+                    ctx.moveTo(x, y);
+                else
+                    ctx.lineTo(x, y);
+            }
+            ctx.stroke();
+        }
+        return true;
+    };
+    cancel = schedule(draw);
+    onCleanup(() => {
+        cancel?.();
+        setActive(false);
+    });
+    return { active };
+}
+/**
+ * Text-to-speech with `speechSynthesis` by default and a clean
+ * upgrade path to cloud voices.
+ *
+ * ```ts
+ * const tts = createTTS({ rate: 1.05 });
+ * tts.speak("Your report is ready.");
+ *
+ * // Cloud upgrade:
+ * const tts = createTTS({
+ *   provider: {
+ *     speak: async (text, { signal }) => {
+ *       const res = await fetch("/api/tts", {
+ *         method: "POST",
+ *         body: JSON.stringify({ text }),
+ *         signal,
+ *       });
+ *       await playAudioBlob(await res.blob(), signal);
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * SSR-safe: `supported` is false without `speechSynthesis` and
+ * `speak()` is a no-op there.
+ */
+export function createTTS(options = {}) {
+    const { provider = "browser", rate = 1, pitch = 1, volume = 1, voice, onStart, onEnd, onError, } = options;
+    const [speaking, setSpeaking] = createSignal(false);
+    const [voices, setVoices] = createSignal([]);
+    const synth = g["speechSynthesis"] ?? null;
+    const Utterance = g["SpeechSynthesisUtterance"] ?? null;
+    const supported = provider !== "browser" || (synth !== null && Utterance !== null);
+    let cloudController = null;
+    const refreshVoices = () => {
+        if (synth)
+            setVoices([...synth.getVoices()]);
+    };
+    if (synth) {
+        refreshVoices();
+        const handler = () => refreshVoices();
+        synth.addEventListener("voiceschanged", handler);
+        onCleanup(() => synth.removeEventListener("voiceschanged", handler));
+    }
+    const pickVoice = () => {
+        const list = voices();
+        if (!voice || list.length === 0)
+            return undefined;
+        if (typeof voice === "function")
+            return voice(list);
+        return list.find((v) => v.name === voice) ?? undefined;
+    };
+    const cancel = () => {
+        cloudController?.abort();
+        cloudController = null;
+        try {
+            synth?.cancel();
+        }
+        catch {
+            // Already idle.
+        }
+        setSpeaking(false);
+    };
+    const speak = (text) => {
+        if (!text)
+            return;
+        cancel();
+        if (typeof provider === "object") {
+            cloudController = new AbortController();
+            const signal = cloudController.signal;
+            setSpeaking(true);
+            onStart?.();
+            void provider
+                .speak(text, { signal })
+                .then(() => {
+                if (signal.aborted)
+                    return;
+                setSpeaking(false);
+                onEnd?.();
+            })
+                .catch((e) => {
+                if (signal.aborted)
+                    return;
+                setSpeaking(false);
+                const err = e instanceof Error ? e : new Error(String(e));
+                onError?.(err);
+            });
+            return;
+        }
+        if (!synth || !Utterance)
+            return;
+        const utterance = new Utterance(text);
+        utterance.lang =
+            options.lang ??
+                g["navigator"]?.language ??
+                "en-US";
+        utterance.rate = rate;
+        utterance.pitch = pitch;
+        utterance.volume = volume;
+        const chosen = pickVoice();
+        if (chosen)
+            utterance.voice = chosen;
+        utterance.onstart = () => {
+            setSpeaking(true);
+            onStart?.();
+        };
+        utterance.onend = () => {
+            setSpeaking(false);
+            onEnd?.();
+        };
+        utterance.onerror = () => {
+            setSpeaking(false);
+            const err = new Error("Speech synthesis failed");
+            onError?.(err);
+        };
+        synth.speak(utterance);
+    };
+    onCleanup(cancel);
+    return { supported, speaking, voices, speak, cancel };
+}
+/**
+ * An animated "thinking" indicator for voice reply latency: cycles
+ * trailing dots, then moves through phrases.
+ *
+ * ```ts
+ * const thinking = createThinking({ phrases: ["Thinking", "Searching"] });
+ * thinking.start();
+ * <p>{thinking.text()}</p> // "Thinking", "Thinking.", "Thinking..", ...
+ * ```
+ */
+export function createThinking(options = {}) {
+    const { phrases = ["Thinking"], interval = 400 } = options;
+    const safePhrases = phrases.length > 0 ? phrases : ["Thinking"];
+    const [text, setText] = createSignal("");
+    const [running, setRunning] = createSignal(false);
+    let timer = null;
+    let phrase = 0;
+    let dots = 0;
+    const stopTimer = () => {
+        if (timer !== null) {
+            clearInterval(timer);
+            timer = null;
+        }
+    };
+    const start = () => {
+        stopTimer();
+        phrase = 0;
+        dots = 0;
+        setRunning(true);
+        setText(safePhrases[0]);
+        timer = setInterval(() => {
+            dots = (dots + 1) % 4;
+            if (dots === 0)
+                phrase = (phrase + 1) % safePhrases.length;
+            setText(safePhrases[phrase] + ".".repeat(dots));
+        }, interval);
+    };
+    const stop = () => {
+        stopTimer();
+        setRunning(false);
+        setText("");
+    };
+    onCleanup(stopTimer);
+    return { text, running, start, stop };
+}
+/**
+ * A voice-enabled prompt input: a text value plus mic dictation,
+ * built for chat boxes and voice assistants. Dictated finals are
+ * appended to the value as they arrive; pairs with `createChatModel`
+ * for a full voice loop.
+ *
+ * ```tsx
+ * const prompt = createPrompt({ onSubmit: (t) => chat.send(t) });
+ * <input
+ *   value={prompt.value()}
+ *   onInput={(e) => prompt.setValue(e.currentTarget.value)}
+ *   onKeyDown={(e) => e.key === "Enter" && prompt.submit()}
+ *   placeholder={prompt.listening() ? prompt.interim() || "Listening..." : "Ask anything"}
+ * />
+ * <button onClick={() => prompt.toggleMic()}>Mic</button>
+ * ```
+ */
+export function createPrompt(options = {}) {
+    const { onSubmit, clearOnSubmit = true, lang } = options;
+    const [value, setValue] = createSignal("");
+    const speech = createSpeech({
+        lang,
+        continuous: true,
+        onResult: (transcript, isFinal) => {
+            if (!isFinal)
+                return;
+            setValue((prev) => {
+                const needsSpace = prev.length > 0 && !/\s$/.test(prev);
+                return prev + (needsSpace ? " " : "") + transcript.trim();
+            });
+        },
+    });
+    const toggleMic = () => {
+        if (speech.listening()) {
+            speech.stop();
+        }
+        else {
+            speech.reset();
+            speech.start();
+        }
+    };
+    const clear = () => {
+        setValue("");
+        speech.reset();
+    };
+    const submit = () => {
+        const text = value().trim();
+        if (speech.listening())
+            speech.stop();
+        if (!text)
+            return;
+        onSubmit?.(text);
+        if (clearOnSubmit)
+            clear();
+    };
+    onCleanup(() => speech.stop());
+    return {
+        value,
+        setValue,
+        listening: speech.listening,
+        interim: speech.interim,
+        supported: speech.supported,
+        toggleMic,
+        submit,
+        clear,
+    };
+}

package/package.json

@@ -43,5 +43,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.25.0"
+  "version": "0.27.0"
 }