use-voice-control 0.1.37 → 0.1.39

package/dist/react/useReadAloud.d.ts

@@ -0,0 +1,22 @@
+import { ReadAloudChunk, ReadAloudOptions, ReadAloudState } from '../client/read-aloud';
+export interface UseReadAloudOptions extends Omit<ReadAloudOptions, "onStateChange" | "onChunk"> {
+    /** Called as each chunk starts playing (e.g. to highlight it in the document). */
+    onChunk?: (chunk: ReadAloudChunk) => void;
+}
+export interface UseReadAloudReturn {
+    state: ReadAloudState;
+    /** True while loading, speaking, or paused. */
+    isActive: boolean;
+    isSpeaking: boolean;
+    isPaused: boolean;
+    /** The chunk currently being spoken, or `null` between utterances. */
+    currentChunk: ReadAloudChunk | null;
+    error: Error | null;
+    speak: (text: string) => Promise<void>;
+    pause: () => void;
+    resume: () => void;
+    stop: () => void;
+    /** Speak `text`, or stop if something is already playing. */
+    toggle: (text: string) => void;
+}
+export declare function useReadAloud(options?: UseReadAloudOptions): UseReadAloudReturn;

package/dist/react.js

@@ -0,0 +1,212 @@
+import { useState as u, useRef as b, useMemo as T, useEffect as E, useCallback as C } from "react";
+import { ReadAloudController as x, isTranscriptionSupported as L, LiveTranscriber as A } from "./client.js";
+import { jsx as R } from "react/jsx-runtime";
+import { createPortal as I } from "react-dom";
+function F(s = {}) {
+  const [g, h] = u("idle"), [S, y] = u(null), [v, l] = u(null), d = b(s);
+  d.current = s;
+  const o = T(
+    () => new x({
+      onStateChange: h,
+      onChunk: (t) => {
+        var a, c;
+        y(t), (c = (a = d.current).onChunk) == null || c.call(a, t);
+      },
+      onEnd: (t) => {
+        var a, c;
+        y(null), (c = (a = d.current).onEnd) == null || c.call(a, t);
+      },
+      onError: (t) => {
+        var a, c;
+        l(t), (c = (a = d.current).onError) == null || c.call(a, t);
+      }
+    }),
+    []
+  );
+  E(() => {
+    const { onChunk: t, onEnd: a, onError: c, ...P } = s;
+    o.setOptions({
+      ...P,
+      onStateChange: h,
+      onChunk: (e) => {
+        var n, r;
+        y(e), (r = (n = d.current).onChunk) == null || r.call(n, e);
+      },
+      onEnd: (e) => {
+        var n, r;
+        y(null), (r = (n = d.current).onEnd) == null || r.call(n, e);
+      },
+      onError: (e) => {
+        var n, r;
+        l(e), (r = (n = d.current).onError) == null || r.call(n, e);
+      }
+    });
+  }, [
+    o,
+    s.provider,
+    s.voice,
+    s.endpoint,
+    s.maxChunkLength,
+    s.synthesize
+  ]), E(() => () => o.stop(), [o]);
+  const f = C(
+    async (t) => {
+      l(null), await o.speak(t);
+    },
+    [o]
+  ), p = C(() => o.stop(), [o]), w = C(() => o.pause(), [o]), i = C(() => o.resume(), [o]), m = C(
+    (t) => {
+      o.isActive() ? o.stop() : f(t);
+    },
+    [o, f]
+  );
+  return {
+    state: g,
+    isActive: g !== "idle",
+    isSpeaking: g === "speaking",
+    isPaused: g === "paused",
+    currentChunk: S,
+    error: v,
+    speak: f,
+    pause: w,
+    resume: i,
+    stop: p,
+    toggle: m
+  };
+}
+function H(s = {}) {
+  const [g, h] = u(!1), [S, y] = u(!1), [v, l] = u(""), [d, o] = u(""), [f, p] = u(0), [w, i] = u(null), m = b(s);
+  m.current = s, E(() => y(L()), []);
+  const t = T(
+    () => new A({
+      onStateChange: h,
+      onPartial: (e) => {
+        var n, r;
+        l(e), e && (o(e), p((k) => k + 1)), (r = (n = m.current).onPartial) == null || r.call(n, e);
+      },
+      onCommit: (e) => {
+        var n, r;
+        l(""), o(e), p((k) => k + 1), (r = (n = m.current).onCommit) == null || r.call(n, e);
+      },
+      onError: (e) => {
+        var n, r;
+        i(e), (r = (n = m.current).onError) == null || r.call(n, e);
+      }
+    }),
+    []
+  );
+  E(() => {
+    t.setOptions({
+      engine: s.engine,
+      language: s.language,
+      model: s.model,
+      onStateChange: h,
+      onPartial: (e) => {
+        var n, r;
+        l(e), e && (o(e), p((k) => k + 1)), (r = (n = m.current).onPartial) == null || r.call(n, e);
+      },
+      onCommit: (e) => {
+        var n, r;
+        l(""), o(e), p((k) => k + 1), (r = (n = m.current).onCommit) == null || r.call(n, e);
+      },
+      onError: (e) => {
+        var n, r;
+        i(e), (r = (n = m.current).onError) == null || r.call(n, e);
+      }
+    });
+  }, [t, s.engine, s.language, s.model]), E(() => () => {
+    t.stop();
+  }, [t]);
+  const a = C(async () => {
+    i(null), await t.start();
+  }, [t]), c = C(async () => {
+    await t.stop(), l("");
+  }, [t]), P = C(async () => {
+    t.isListening() ? await c() : await a();
+  }, [t, a, c]);
+  return {
+    isListening: g,
+    isSupported: S,
+    partial: v,
+    lastPhrase: d,
+    phraseId: f,
+    error: w,
+    start: a,
+    stop: c,
+    toggle: P
+  };
+}
+const O = 2e3;
+function M({
+  phrase: s,
+  phraseId: g,
+  durationMs: h = O,
+  visible: S = !0,
+  zIndex: y = 2147483e3,
+  className: v
+}) {
+  const [l, d] = u(!1), [o, f] = u(!1), [p, w] = u(""), i = b(null);
+  return E(() => d(!0), []), E(() => {
+    const a = s.trim();
+    if (!S || !a) {
+      S || f(!1);
+      return;
+    }
+    return w(a), f(!0), i.current && clearTimeout(i.current), i.current = setTimeout(() => f(!1), h), () => {
+      i.current && clearTimeout(i.current);
+    };
+  }, [s, g, S, h]), E(() => () => {
+    i.current && clearTimeout(i.current);
+  }, []), !l || !p ? null : I(
+    /* @__PURE__ */ R(
+      "div",
+      {
+        "aria-hidden": "true",
+        className: v,
+        "data-spoken-phrase-overlay": "",
+        style: {
+          position: "fixed",
+          inset: 0,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          pointerEvents: "none",
+          padding: "6vw",
+          zIndex: y,
+          opacity: o ? 1 : 0,
+          transition: "opacity 320ms ease-out"
+        },
+        children: /* @__PURE__ */ R("div", { style: {
+          maxWidth: "min(1100px, 90vw)",
+          textAlign: "center",
+          // Scales with the viewport so a short phrase fills the screen on a laptop
+          // and still fits on a phone.
+          fontSize: "clamp(2rem, 7vw, 6rem)",
+          fontWeight: 700,
+          lineHeight: 1.1,
+          letterSpacing: "-0.02em",
+          color: "#ffffff",
+          // A dark pill keeps the words readable over light and dark pages alike.
+          background: "rgba(15, 23, 42, 0.82)",
+          borderRadius: "1.5rem",
+          padding: "0.6em 0.8em",
+          boxShadow: "0 25px 80px rgba(0, 0, 0, 0.45)",
+          backdropFilter: "blur(8px)",
+          transform: o ? "scale(1)" : "scale(0.96)",
+          transition: "transform 320ms ease-out",
+          overflowWrap: "anywhere"
+        }, children: p })
+      }
+    ),
+    document.body
+  );
+}
+export {
+  A as LiveTranscriber,
+  x as ReadAloudController,
+  M as SpokenPhraseOverlay,
+  L as isTranscriptionSupported,
+  H as useLiveTranscription,
+  F as useReadAloud
+};
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sources":["../speech/react/useReadAloud.ts","../speech/react/useLiveTranscription.ts","../speech/react/SpokenPhraseOverlay.tsx"],"sourcesContent":["/**\n * @fileoverview React binding for `ReadAloudController`.\n *\n * Keeps one controller alive for the lifetime of the component, mirrors its state\n * into React state, and stops playback on unmount so navigating away never leaves\n * audio running.\n */\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport {\n  ReadAloudController,\n  type ReadAloudChunk,\n  type ReadAloudOptions,\n  type ReadAloudState,\n} from \"../client/read-aloud\";\n\nexport interface UseReadAloudOptions\n  extends Omit<ReadAloudOptions, \"onStateChange\" | \"onChunk\"> {\n  /** Called as each chunk starts playing (e.g. to highlight it in the document). */\n  onChunk?: (chunk: ReadAloudChunk) => void;\n}\n\nexport interface UseReadAloudReturn {\n  state: ReadAloudState;\n  /** True while loading, speaking, or paused. */\n  isActive: boolean;\n  isSpeaking: boolean;\n  isPaused: boolean;\n  /** The chunk currently being spoken, or `null` between utterances. */\n  currentChunk: ReadAloudChunk | null;\n  error: Error | null;\n  speak: (text: string) => Promise<void>;\n  pause: () => void;\n  resume: () => void;\n  stop: () => void;\n  /** Speak `text`, or stop if something is already playing. */\n  toggle: (text: string) => void;\n}\n\nexport function useReadAloud(options: UseReadAloudOptions = {}): UseReadAloudReturn {\n  const [state, setState] = useState<ReadAloudState>(\"idle\");\n  const [currentChunk, setCurrentChunk] = useState<ReadAloudChunk | null>(null);\n  const [error, setError] = useState<Error | null>(null);\n\n  // Callers routinely pass inline callbacks; hold them in a ref so the controller\n  // is never rebuilt mid-playback.\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n\n  const controller = useMemo(\n    () =>\n      new ReadAloudController({\n        onStateChange: setState,\n        onChunk: (chunk) => {\n          setCurrentChunk(chunk);\n          optionsRef.current.onChunk?.(chunk);\n        },\n        onEnd: (reason) => {\n          setCurrentChunk(null);\n          optionsRef.current.onEnd?.(reason);\n        },\n        onError: (err) => {\n          setError(err);\n          optionsRef.current.onError?.(err);\n        },\n      }),\n    []\n  );\n\n  // Re-apply the caller's settings (voice, endpoint, …) whenever they change,\n  // preserving the callback wiring above.\n  useEffect(() => {\n    const { onChunk, onEnd, onError, ...rest } = options;\n    controller.setOptions({\n      ...rest,\n      onStateChange: setState,\n      onChunk: (chunk) => {\n        setCurrentChunk(chunk);\n        optionsRef.current.onChunk?.(chunk);\n      },\n      onEnd: (reason) => {\n        setCurrentChunk(null);\n        optionsRef.current.onEnd?.(reason);\n      },\n      onError: (err) => {\n        setError(err);\n        optionsRef.current.onError?.(err);\n      },\n    });\n  }, [\n    controller,\n    options.provider,\n    options.voice,\n    options.endpoint,\n    options.maxChunkLength,\n    options.synthesize,\n  ]);\n\n  useEffect(() => () => controller.stop(), [controller]);\n\n  const speak = useCallback(\n    async (text: string) => {\n      setError(null);\n      await controller.speak(text);\n    },\n    [controller]\n  );\n\n  const stop = useCallback(() => controller.stop(), [controller]);\n  const pause = useCallback(() => controller.pause(), [controller]);\n  const resume = useCallback(() => controller.resume(), [controller]);\n\n  const toggle = useCallback(\n    (text: string) => {\n      if (controller.isActive()) {\n        controller.stop();\n      } else {\n        void speak(text);\n      }\n    },\n    [controller, speak]\n  );\n\n  return {\n    state,\n    isActive: state !== \"idle\",\n    isSpeaking: state === \"speaking\",\n    isPaused: state === \"paused\",\n    currentChunk,\n    error,\n    speak,\n    pause,\n    resume,\n    stop,\n    toggle,\n  };\n}\n","/**\n * @fileoverview React binding for `LiveTranscriber`.\n *\n * Exposes the two streams a dictation UI needs: `partial`, which changes on every\n * word while a phrase is in progress, and the committed phrases delivered through\n * `onCommit`. `lastPhrase` carries whatever was most recently heard — partial or\n * committed — along with a monotonically increasing `phraseId` so a display can\n * re-trigger its own timeout even when the same words are said twice in a row.\n */\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport {\n  LiveTranscriber,\n  isTranscriptionSupported,\n  type LiveTranscriberOptions,\n} from \"../client/live-transcriber\";\n\nexport interface UseLiveTranscriptionOptions\n  extends Omit<LiveTranscriberOptions, \"onStateChange\"> {}\n\nexport interface UseLiveTranscriptionReturn {\n  isListening: boolean;\n  /** True when this browser can dictate at all. */\n  isSupported: boolean;\n  /** The in-progress phrase, updating as it is spoken. Empty between phrases. */\n  partial: string;\n  /** The most recent thing heard, partial or committed. */\n  lastPhrase: string;\n  /** Increments on every `lastPhrase` update, including repeats of the same words. */\n  phraseId: number;\n  error: Error | null;\n  start: () => Promise<void>;\n  stop: () => Promise<void>;\n  toggle: () => Promise<void>;\n}\n\nexport function useLiveTranscription(\n  options: UseLiveTranscriptionOptions = {}\n): UseLiveTranscriptionReturn {\n  const [isListening, setIsListening] = useState(false);\n  const [isSupported, setIsSupported] = useState(false);\n  const [partial, setPartial] = useState(\"\");\n  const [lastPhrase, setLastPhrase] = useState(\"\");\n  const [phraseId, setPhraseId] = useState(0);\n  const [error, setError] = useState<Error | null>(null);\n\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n\n  // Support depends on `window`, so it can only be settled after hydration.\n  useEffect(() => setIsSupported(isTranscriptionSupported()), []);\n\n  const transcriber = useMemo(\n    () =>\n      new LiveTranscriber({\n        onStateChange: setIsListening,\n        onPartial: (text) => {\n          setPartial(text);\n          if (text) {\n            setLastPhrase(text);\n            setPhraseId((id) => id + 1);\n          }\n          optionsRef.current.onPartial?.(text);\n        },\n        onCommit: (text) => {\n          setPartial(\"\");\n          setLastPhrase(text);\n          setPhraseId((id) => id + 1);\n          optionsRef.current.onCommit?.(text);\n        },\n        onError: (err) => {\n          setError(err);\n          optionsRef.current.onError?.(err);\n        },\n      }),\n    []\n  );\n\n  // Engine/language changes take effect on the next `start()`.\n  useEffect(() => {\n    transcriber.setOptions({\n      engine: options.engine,\n      language: options.language,\n      model: options.model,\n      onStateChange: setIsListening,\n      onPartial: (text) => {\n        setPartial(text);\n        if (text) {\n          setLastPhrase(text);\n          setPhraseId((id) => id + 1);\n        }\n        optionsRef.current.onPartial?.(text);\n      },\n      onCommit: (text) => {\n        setPartial(\"\");\n        setLastPhrase(text);\n        setPhraseId((id) => id + 1);\n        optionsRef.current.onCommit?.(text);\n      },\n      onError: (err) => {\n        setError(err);\n        optionsRef.current.onError?.(err);\n      },\n    });\n  }, [transcriber, options.engine, options.language, options.model]);\n\n  useEffect(() => {\n    return () => {\n      void transcriber.stop();\n    };\n  }, [transcriber]);\n\n  const start = useCallback(async () => {\n    setError(null);\n    await transcriber.start();\n  }, [transcriber]);\n\n  const stop = useCallback(async () => {\n    await transcriber.stop();\n    setPartial(\"\");\n  }, [transcriber]);\n\n  const toggle = useCallback(async () => {\n    if (transcriber.isListening()) {\n      await stop();\n    } else {\n      await start();\n    }\n  }, [transcriber, start, stop]);\n\n  return {\n    isListening,\n    isSupported,\n    partial,\n    lastPhrase,\n    phraseId,\n    error,\n    start,\n    stop,\n    toggle,\n  };\n}\n","/**\n * @fileoverview Full-screen display of the phrase that was just spoken.\n *\n * While dictating, the words land in whatever input has focus — which is easy to\n * lose track of when you are looking away from the screen. This overlay echoes the\n * latest phrase in large type at the centre of the viewport and fades out two\n * seconds after the last update, so a glance confirms you were heard correctly.\n *\n * It renders into `document.body` through a portal with pointer events disabled, so\n * it never intercepts clicks or gets clipped by the host app's layout, and it is\n * styled inline so it looks the same in every app that mounts it regardless of the\n * CSS framework in play.\n */\nimport { useEffect, useRef, useState, type CSSProperties } from \"react\";\nimport { createPortal } from \"react-dom\";\n\nexport interface SpokenPhraseOverlayProps {\n  /** The words to display. An empty string hides the overlay. */\n  phrase: string;\n  /**\n   * Bump this whenever `phrase` is refreshed to restart the hide timer, including\n   * when the same words are repeated. `useLiveTranscription` supplies it.\n   */\n  phraseId?: number;\n  /** How long the phrase stays up after the last update. Default 2000ms. */\n  durationMs?: number;\n  /** Set false to suppress the overlay entirely (e.g. once dictation stops). */\n  visible?: boolean;\n  /** Stacking order. Default 2147483000, above typical app chrome and modals. */\n  zIndex?: number;\n  className?: string;\n}\n\nconst HIDE_AFTER_MS = 2000;\n\nexport function SpokenPhraseOverlay({\n  phrase,\n  phraseId,\n  durationMs = HIDE_AFTER_MS,\n  visible = true,\n  zIndex = 2147483000,\n  className,\n}: SpokenPhraseOverlayProps) {\n  const [mounted, setMounted] = useState(false);\n  const [shown, setShown] = useState(false);\n  // Held separately from `phrase` so the text stays put while fading out rather\n  // than blanking the moment the transcript clears.\n  const [displayed, setDisplayed] = useState(\"\");\n  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n  useEffect(() => setMounted(true), []);\n\n  useEffect(() => {\n    const text = phrase.trim();\n    if (!visible || !text) {\n      if (!visible) setShown(false);\n      return;\n    }\n\n    setDisplayed(text);\n    setShown(true);\n\n    if (timerRef.current) clearTimeout(timerRef.current);\n    timerRef.current = setTimeout(() => setShown(false), durationMs);\n\n    return () => {\n      if (timerRef.current) clearTimeout(timerRef.current);\n    };\n  }, [phrase, phraseId, visible, durationMs]);\n\n  useEffect(() => {\n    return () => {\n      if (timerRef.current) clearTimeout(timerRef.current);\n    };\n  }, []);\n\n  if (!mounted || !displayed) return null;\n\n  const containerStyle: CSSProperties = {\n    position: \"fixed\",\n    inset: 0,\n    display: \"flex\",\n    alignItems: \"center\",\n    justifyContent: \"center\",\n    pointerEvents: \"none\",\n    padding: \"6vw\",\n    zIndex,\n    opacity: shown ? 1 : 0,\n    transition: \"opacity 320ms ease-out\",\n  };\n\n  const textStyle: CSSProperties = {\n    maxWidth: \"min(1100px, 90vw)\",\n    textAlign: \"center\",\n    // Scales with the viewport so a short phrase fills the screen on a laptop\n    // and still fits on a phone.\n    fontSize: \"clamp(2rem, 7vw, 6rem)\",\n    fontWeight: 700,\n    lineHeight: 1.1,\n    letterSpacing: \"-0.02em\",\n    color: \"#ffffff\",\n    // A dark pill keeps the words readable over light and dark pages alike.\n    background: \"rgba(15, 23, 42, 0.82)\",\n    borderRadius: \"1.5rem\",\n    padding: \"0.6em 0.8em\",\n    boxShadow: \"0 25px 80px rgba(0, 0, 0, 0.45)\",\n    backdropFilter: \"blur(8px)\",\n    transform: shown ? \"scale(1)\" : \"scale(0.96)\",\n    transition: \"transform 320ms ease-out\",\n    overflowWrap: \"anywhere\",\n  };\n\n  return createPortal(\n    <div\n      aria-hidden=\"true\"\n      className={className}\n      data-spoken-phrase-overlay=\"\"\n      style={containerStyle}\n    >\n      <div style={textStyle}>{displayed}</div>\n    </div>,\n    document.body\n  );\n}\n\nexport default SpokenPhraseOverlay;\n"],"names":["useReadAloud","options","state","setState","useState","currentChunk","setCurrentChunk","error","setError","optionsRef","useRef","controller","useMemo","ReadAloudController","chunk","_b","_a","reason","err","useEffect","onChunk","onEnd","onError","rest","speak","useCallback","text","stop","pause","resume","toggle","useLiveTranscription","isListening","setIsListening","isSupported","setIsSupported","partial","setPartial","lastPhrase","setLastPhrase","phraseId","setPhraseId","isTranscriptionSupported","transcriber","LiveTranscriber","id","start","HIDE_AFTER_MS","SpokenPhraseOverlay","phrase","durationMs","visible","zIndex","className","mounted","setMounted","shown","setShown","displayed","setDisplayed","timerRef","createPortal","jsx"],"mappings":";;;;AAuCO,SAASA,EAAaC,IAA+B,IAAwB;AAClF,QAAM,CAACC,GAAOC,CAAQ,IAAIC,EAAyB,MAAM,GACnD,CAACC,GAAcC,CAAe,IAAIF,EAAgC,IAAI,GACtE,CAACG,GAAOC,CAAQ,IAAIJ,EAAuB,IAAI,GAI/CK,IAAaC,EAAOT,CAAO;AACjC,EAAAQ,EAAW,UAAUR;AAErB,QAAMU,IAAaC;AAAA,IACjB,MACE,IAAIC,EAAoB;AAAA,MACtB,eAAeV;AAAA,MACf,SAAS,CAACW,MAAU;;AAClB,QAAAR,EAAgBQ,CAAK,IACrBC,KAAAC,IAAAP,EAAW,SAAQ,YAAnB,QAAAM,EAAA,KAAAC,GAA6BF;AAAA,MAC/B;AAAA,MACA,OAAO,CAACG,MAAW;;AACjB,QAAAX,EAAgB,IAAI,IACpBS,KAAAC,IAAAP,EAAW,SAAQ,UAAnB,QAAAM,EAAA,KAAAC,GAA2BC;AAAA,MAC7B;AAAA,MACA,SAAS,CAACC,MAAQ;;AAChB,QAAAV,EAASU,CAAG,IACZH,KAAAC,IAAAP,EAAW,SAAQ,YAAnB,QAAAM,EAAA,KAAAC,GAA6BE;AAAA,MAC/B;AAAA,IAAA,CACD;AAAA,IACH,CAAA;AAAA,EAAC;AAKH,EAAAC,EAAU,MAAM;AACd,UAAM,EAAE,SAAAC,GAAS,OAAAC,GAAO,SAAAC,GAAS,GAAGC,MAAStB;AAC7C,IAAAU,EAAW,WAAW;AAAA,MACpB,GAAGY;AAAA,MACH,eAAepB;AAAA,MACf,SAAS,CAACW,MAAU;;AAClB,QAAAR,EAAgBQ,CAAK,IACrBC,KAAAC,IAAAP,EAAW,SAAQ,YAAnB,QAAAM,EAAA,KAAAC,GAA6BF;AAAA,MAC/B;AAAA,MACA,OAAO,CAACG,MAAW;;AACjB,QAAAX,EAAgB,IAAI,IACpBS,KAAAC,IAAAP,EAAW,SAAQ,UAAnB,QAAAM,EAAA,KAAAC,GAA2BC;AAAA,MAC7B;AAAA,MACA,SAAS,CAACC,MAAQ;;AAChB,QAAAV,EAASU,CAAG,IACZH,KAAAC,IAAAP,EAAW,SAAQ,YAAnB,QAAAM,EAAA,KAAAC,GAA6BE;AAAA,MAC/B;AAAA,IAAA,CACD;AAAA,EACH,GAAG;AAAA,IACDP;AAAA,IACAV,EAAQ;AAAA,IACRA,EAAQ;AAAA,IACRA,EAAQ;AAAA,IACRA,EAAQ;AAAA,IACRA,EAAQ;AAAA,EAAA,CACT,GAEDkB,EAAU,MAAM,MAAMR,EAAW,QAAQ,CAACA,CAAU,CAAC;AAErD,QAAMa,IAAQC;AAAA,IACZ,OAAOC,MAAiB;AACtB,MAAAlB,EAAS,IAAI,GACb,MAAMG,EAAW,MAAMe,CAAI;AAAA,IAC7B;AAAA,IACA,CAACf,CAAU;AAAA,EAAA,GAGPgB,IAAOF,EAAY,MAAMd,EAAW,QAAQ,CAACA,CAAU,CAAC,GACxDiB,IAAQH,EAAY,MAAMd,EAAW,SAAS,CAACA,CAAU,CAAC,GAC1DkB,IAASJ,EAAY,MAAMd,EAAW,UAAU,CAACA,CAAU,CAAC,GAE5DmB,IAASL;AAAA,IACb,CAACC,MAAiB;AAChB,MAAIf,EAAW,aACbA,EAAW,KAAA,IAENa,EAAME,CAAI;AAAA,IAEnB;AAAA,IACA,CAACf,GAAYa,CAAK;AAAA,EAAA;AAGpB,SAAO;AAAA,IACL,OAAAtB;AAAA,IACA,UAAUA,MAAU;AAAA,IACpB,YAAYA,MAAU;AAAA,IACtB,UAAUA,MAAU;AAAA,IACpB,cAAAG;AAAA,IACA,OAAAE;AAAA,IACA,OAAAiB;AAAA,IACA,OAAAI;AAAA,IACA,QAAAC;AAAA,IACA,MAAAF;AAAA,IACA,QAAAG;AAAA,EAAA;AAEJ;ACpGO,SAASC,EACd9B,IAAuC,IACX;AAC5B,QAAM,CAAC+B,GAAaC,CAAc,IAAI7B,EAAS,EAAK,GAC9C,CAAC8B,GAAaC,CAAc,IAAI/B,EAAS,EAAK,GAC9C,CAACgC,GAASC,CAAU,IAAIjC,EAAS,EAAE,GACnC,CAACkC,GAAYC,CAAa,IAAInC,EAAS,EAAE,GACzC,CAACoC,GAAUC,CAAW,IAAIrC,EAAS,CAAC,GACpC,CAACG,GAAOC,CAAQ,IAAIJ,EAAuB,IAAI,GAE/CK,IAAaC,EAAOT,CAAO;AACjC,EAAAQ,EAAW,UAAUR,GAGrBkB,EAAU,MAAMgB,EAAeO,EAAA,CAA0B,GAAG,CAAA,CAAE;AAE9D,QAAMC,IAAc/B;AAAA,IAClB,MACE,IAAIgC,EAAgB;AAAA,MAClB,eAAeX;AAAA,MACf,WAAW,CAACP,MAAS;;AACnB,QAAAW,EAAWX,CAAI,GACXA,MACFa,EAAcb,CAAI,GAClBe,EAAY,CAACI,MAAOA,IAAK,CAAC,KAE5B9B,KAAAC,IAAAP,EAAW,SAAQ,cAAnB,QAAAM,EAAA,KAAAC,GAA+BU;AAAA,MACjC;AAAA,MACA,UAAU,CAACA,MAAS;;AAClB,QAAAW,EAAW,EAAE,GACbE,EAAcb,CAAI,GAClBe,EAAY,CAACI,MAAOA,IAAK,CAAC,IAC1B9B,KAAAC,IAAAP,EAAW,SAAQ,aAAnB,QAAAM,EAAA,KAAAC,GAA8BU;AAAA,MAChC;AAAA,MACA,SAAS,CAACR,MAAQ;;AAChB,QAAAV,EAASU,CAAG,IACZH,KAAAC,IAAAP,EAAW,SAAQ,YAAnB,QAAAM,EAAA,KAAAC,GAA6BE;AAAA,MAC/B;AAAA,IAAA,CACD;AAAA,IACH,CAAA;AAAA,EAAC;AAIH,EAAAC,EAAU,MAAM;AACd,IAAAwB,EAAY,WAAW;AAAA,MACrB,QAAQ1C,EAAQ;AAAA,MAChB,UAAUA,EAAQ;AAAA,MAClB,OAAOA,EAAQ;AAAA,MACf,eAAegC;AAAA,MACf,WAAW,CAACP,MAAS;;AACnB,QAAAW,EAAWX,CAAI,GACXA,MACFa,EAAcb,CAAI,GAClBe,EAAY,CAACI,MAAOA,IAAK,CAAC,KAE5B9B,KAAAC,IAAAP,EAAW,SAAQ,cAAnB,QAAAM,EAAA,KAAAC,GAA+BU;AAAA,MACjC;AAAA,MACA,UAAU,CAACA,MAAS;;AAClB,QAAAW,EAAW,EAAE,GACbE,EAAcb,CAAI,GAClBe,EAAY,CAACI,MAAOA,IAAK,CAAC,IAC1B9B,KAAAC,IAAAP,EAAW,SAAQ,aAAnB,QAAAM,EAAA,KAAAC,GAA8BU;AAAA,MAChC;AAAA,MACA,SAAS,CAACR,MAAQ;;AAChB,QAAAV,EAASU,CAAG,IACZH,KAAAC,IAAAP,EAAW,SAAQ,YAAnB,QAAAM,EAAA,KAAAC,GAA6BE;AAAA,MAC/B;AAAA,IAAA,CACD;AAAA,EACH,GAAG,CAACyB,GAAa1C,EAAQ,QAAQA,EAAQ,UAAUA,EAAQ,KAAK,CAAC,GAEjEkB,EAAU,MACD,MAAM;AACX,IAAKwB,EAAY,KAAA;AAAA,EACnB,GACC,CAACA,CAAW,CAAC;AAEhB,QAAMG,IAAQrB,EAAY,YAAY;AACpC,IAAAjB,EAAS,IAAI,GACb,MAAMmC,EAAY,MAAA;AAAA,EACpB,GAAG,CAACA,CAAW,CAAC,GAEVhB,IAAOF,EAAY,YAAY;AACnC,UAAMkB,EAAY,KAAA,GAClBN,EAAW,EAAE;AAAA,EACf,GAAG,CAACM,CAAW,CAAC,GAEVb,IAASL,EAAY,YAAY;AACrC,IAAIkB,EAAY,gBACd,MAAMhB,EAAA,IAEN,MAAMmB,EAAA;AAAA,EAEV,GAAG,CAACH,GAAaG,GAAOnB,CAAI,CAAC;AAE7B,SAAO;AAAA,IACL,aAAAK;AAAA,IACA,aAAAE;AAAA,IACA,SAAAE;AAAA,IACA,YAAAE;AAAA,IACA,UAAAE;AAAA,IACA,OAAAjC;AAAA,IACA,OAAAuC;AAAA,IACA,MAAAnB;AAAA,IACA,QAAAG;AAAA,EAAA;AAEJ;AC5GA,MAAMiB,IAAgB;AAEf,SAASC,EAAoB;AAAA,EAClC,QAAAC;AAAA,EACA,UAAAT;AAAA,EACA,YAAAU,IAAaH;AAAA,EACb,SAAAI,IAAU;AAAA,EACV,QAAAC,IAAS;AAAA,EACT,WAAAC;AACF,GAA6B;AAC3B,QAAM,CAACC,GAASC,CAAU,IAAInD,EAAS,EAAK,GACtC,CAACoD,GAAOC,CAAQ,IAAIrD,EAAS,EAAK,GAGlC,CAACsD,GAAWC,CAAY,IAAIvD,EAAS,EAAE,GACvCwD,IAAWlD,EAA6C,IAAI;AA4BlE,SA1BAS,EAAU,MAAMoC,EAAW,EAAI,GAAG,CAAA,CAAE,GAEpCpC,EAAU,MAAM;AACd,UAAMO,IAAOuB,EAAO,KAAA;AACpB,QAAI,CAACE,KAAW,CAACzB,GAAM;AACrB,MAAKyB,KAASM,EAAS,EAAK;AAC5B;AAAA,IACF;AAEA,WAAAE,EAAajC,CAAI,GACjB+B,EAAS,EAAI,GAETG,EAAS,WAAS,aAAaA,EAAS,OAAO,GACnDA,EAAS,UAAU,WAAW,MAAMH,EAAS,EAAK,GAAGP,CAAU,GAExD,MAAM;AACX,MAAIU,EAAS,WAAS,aAAaA,EAAS,OAAO;AAAA,IACrD;AAAA,EACF,GAAG,CAACX,GAAQT,GAAUW,GAASD,CAAU,CAAC,GAE1C/B,EAAU,MACD,MAAM;AACX,IAAIyC,EAAS,WAAS,aAAaA,EAAS,OAAO;AAAA,EACrD,GACC,CAAA,CAAE,GAED,CAACN,KAAW,CAACI,IAAkB,OAoC5BG;AAAA,IACL,gBAAAC;AAAA,MAAC;AAAA,MAAA;AAAA,QACC,eAAY;AAAA,QACZ,WAAAT;AAAA,QACA,8BAA2B;AAAA,QAC3B,OAvCkC;AAAA,UACpC,UAAU;AAAA,UACV,OAAO;AAAA,UACP,SAAS;AAAA,UACT,YAAY;AAAA,UACZ,gBAAgB;AAAA,UAChB,eAAe;AAAA,UACf,SAAS;AAAA,UACT,QAAAD;AAAA,UACA,SAASI,IAAQ,IAAI;AAAA,UACrB,YAAY;AAAA,QAAA;AAAA,QA+BV,UAAA,gBAAAM,EAAC,OAAA,EAAI,OA5BwB;AAAA,UAC/B,UAAU;AAAA,UACV,WAAW;AAAA;AAAA;AAAA,UAGX,UAAU;AAAA,UACV,YAAY;AAAA,UACZ,YAAY;AAAA,UACZ,eAAe;AAAA,UACf,OAAO;AAAA;AAAA,UAEP,YAAY;AAAA,UACZ,cAAc;AAAA,UACd,SAAS;AAAA,UACT,WAAW;AAAA,UACX,gBAAgB;AAAA,UAChB,WAAWN,IAAQ,aAAa;AAAA,UAChC,YAAY;AAAA,UACZ,cAAc;AAAA,QAAA,GAUY,UAAAE,EAAA,CAAU;AAAA,MAAA;AAAA,IAAA;AAAA,IAEpC,SAAS;AAAA,EAAA;AAEb;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-voice-control",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "description": "React voice control with speech transcription, vocalization, and interruption (STT/TTS/VAD) support.",
   "repository": {
     "type": "git",
@@ -15,6 +15,14 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react.js"
+    },
     "./api-client": {
       "types": "./speech/api-client.ts",
       "import": "./speech/api-client.ts"
@@ -27,26 +35,32 @@
   ],
   "scripts": {
     "build": "tsc && vite build",
+    "prepare": "tsc && vite build",
     "dev": "vite build --watch",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",
     "lucide-react": "^0.344.0",
-    "@moonshine-ai/moonshine-js": "^0.1.29",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "@moonshine-ai/moonshine-js": "^0.1.29"
   },
   "devDependencies": {
-    "@types/react": "^18.0.0",
-    "@types/react-dom": "^18.0.0",
+    "@types/react": "^19.2.17",
+    "@vitejs/plugin-react": "^4.3.4",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "@vitest/coverage-v8": "^4.0.18",
     "typescript": "^5.3.3",
     "vite": "^5.0.0",
-    "vite-plugin-dts": "^5.0.0"
+    "vite-plugin-dts": "^5.0.0",
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "optionalDependencies": {
     "@huggingface/transformers": "^3.0.0"

package/speech/api-client.ts

@@ -1,3 +1,10 @@
+/**
+ * @fileoverview Browser-side helper functions for calling the package's TTS/STT HTTP API routes.
+ *
+ * Provides `generateSpeechFromText`/`createAudioURL`/`speakText` for turning text into
+ * playable audio via `POST /api/speech/tts`, and `checkSTTAPI` to probe availability of
+ * `/api/speech/stt`.
+ */
 import type { TTSOptions } from "./types/types";
 
 export async function generateSpeechFromText(

package/speech/client/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Public entry point for the framework-agnostic browser engines:
+ * read-aloud playback and live dictation. React callers should prefer the hooks in
+ * `use-voice-control/react`, which wrap these.
+ */
+export {
+  ReadAloudController,
+  type ReadAloudChunk,
+  type ReadAloudOptions,
+  type ReadAloudState,
+  type SynthesizeFn,
+} from "./read-aloud";
+
+export {
+  LiveTranscriber,
+  isTranscriptionSupported,
+  type LiveTranscriberOptions,
+  type TranscriberEngine,
+} from "./live-transcriber";
+
+export type { TTSProvider, KokoroVoice, DeepgramSpeaker } from "../types/types";

package/speech/client/live-transcriber.ts

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview Browser-side live dictation engine.
+ *
+ * `LiveTranscriber` streams microphone audio to a recognizer and reports two kinds
+ * of text: `onPartial`, the in-progress guess that keeps changing while a phrase is
+ * being spoken, and `onCommit`, a phrase the recognizer has settled on. Callers use
+ * the first to type text into an input as it is being said, and the second to
+ * finalize it.
+ *
+ * Two engines are supported. The browser's own `SpeechRecognition` is preferred when
+ * present because it needs no model download; otherwise the package's bundled
+ * Moonshine model runs the recognition entirely on-device. Chromium's recognizer
+ * stops itself after a pause, so a session that is still meant to be listening is
+ * restarted automatically.
+ */
+
+export type TranscriberEngine = "auto" | "webspeech" | "moonshine";
+
+export interface LiveTranscriberOptions {
+  /** Which recognizer to use. Default `auto` (browser first, Moonshine as fallback). */
+  engine?: TranscriberEngine;
+  /** BCP-47 language tag for the browser recognizer. Default `en-US`. */
+  language?: string;
+  /** Moonshine model name. Default `model/small`. */
+  model?: string;
+  /** Fires continuously with the current in-progress phrase. */
+  onPartial?: (text: string) => void;
+  /** Fires once per phrase the recognizer has settled on. */
+  onCommit?: (text: string) => void;
+  /** Fires whenever the microphone starts or stops. */
+  onStateChange?: (listening: boolean) => void;
+  onError?: (error: Error) => void;
+}
+
+type SpeechRecognitionCtor = new () => any;
+
+function getSpeechRecognition(): SpeechRecognitionCtor | null {
+  if (typeof window === "undefined") return null;
+  return (
+    (window as any).SpeechRecognition ||
+    (window as any).webkitSpeechRecognition ||
+    null
+  );
+}
+
+/** True when this browser can dictate at all (either engine). */
+export function isTranscriptionSupported(): boolean {
+  if (typeof window === "undefined") return false;
+  if (getSpeechRecognition()) return true;
+  return !!navigator.mediaDevices?.getUserMedia;
+}
+
+export class LiveTranscriber {
+  private options: LiveTranscriberOptions;
+  private listening = false;
+  /** Distinguishes a deliberate `stop()` from Chromium's idle auto-stop. */
+  private stopRequested = false;
+  private recognition: any = null;
+  private moonshine: any = null;
+
+  constructor(options: LiveTranscriberOptions = {}) {
+    this.options = options;
+  }
+
+  setOptions(options: LiveTranscriberOptions): void {
+    this.options = options;
+  }
+
+  isListening(): boolean {
+    return this.listening;
+  }
+
+  async start(): Promise<void> {
+    if (this.listening) return;
+    this.stopRequested = false;
+
+    const engine = this.options.engine ?? "auto";
+    const Recognition = getSpeechRecognition();
+
+    try {
+      if (engine !== "moonshine" && Recognition) {
+        this.startWebSpeech(Recognition);
+        return;
+      }
+      if (engine === "webspeech") {
+        throw new Error("Speech recognition is not available in this browser");
+      }
+      await this.startMoonshine();
+    } catch (error) {
+      this.setListening(false);
+      this.options.onError?.(
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.stopRequested = true;
+
+    if (this.recognition) {
+      try {
+        this.recognition.stop();
+      } catch {
+        /* already stopped */
+      }
+      this.recognition = null;
+    }
+
+    if (this.moonshine) {
+      try {
+        await this.moonshine.stop?.();
+      } catch {
+        /* already stopped */
+      }
+      this.moonshine = null;
+    }
+
+    this.setListening(false);
+  }
+
+  async toggle(): Promise<void> {
+    if (this.listening) {
+      await this.stop();
+    } else {
+      await this.start();
+    }
+  }
+
+  private setListening(listening: boolean): void {
+    if (this.listening === listening) return;
+    this.listening = listening;
+    this.options.onStateChange?.(listening);
+  }
+
+  private startWebSpeech(Recognition: SpeechRecognitionCtor): void {
+    const recognition = new Recognition();
+    recognition.continuous = true;
+    recognition.interimResults = true;
+    recognition.lang = this.options.language ?? "en-US";
+
+    recognition.onstart = () => this.setListening(true);
+
+    recognition.onresult = (event: any) => {
+      let interim = "";
+      for (let i = event.resultIndex; i < event.results.length; i += 1) {
+        const result = event.results[i];
+        const text = String(result[0]?.transcript ?? "").trim();
+        if (!text) continue;
+        if (result.isFinal) {
+          // No `onPartial("")` first: a commit supersedes the interim phrase, and
+          // clearing it separately would make consumers that write the interim
+          // into a document erase and re-insert the same words.
+          this.options.onCommit?.(text);
+        } else {
+          interim += `${interim ? " " : ""}${text}`;
+        }
+      }
+      if (interim) this.options.onPartial?.(interim);
+    };
+
+    recognition.onerror = (event: any) => {
+      const code = event?.error;
+      // `no-speech` and `aborted` are routine during a long dictation session;
+      // `onend` restarts the recognizer for us.
+      if (code === "no-speech" || code === "aborted") return;
+      this.stopRequested = true;
+      this.options.onError?.(new Error(`Speech recognition error: ${code}`));
+    };
+
+    recognition.onend = () => {
+      if (this.stopRequested || this.recognition !== recognition) {
+        this.recognition = null;
+        this.setListening(false);
+        return;
+      }
+      // Chromium ends the session after a pause — start a fresh one so the user
+      // can keep dictating without touching the button again.
+      try {
+        recognition.start();
+      } catch {
+        this.recognition = null;
+        this.setListening(false);
+      }
+    };
+
+    this.recognition = recognition;
+    recognition.start();
+  }
+
+  private async startMoonshine(): Promise<void> {
+    const Moonshine = await import("@moonshine-ai/moonshine-js");
+
+    const transcriber = new Moonshine.MicrophoneTranscriber(
+      this.options.model ?? "model/small",
+      {
+        onTranscriptionUpdated: (text: string) => {
+          this.options.onPartial?.(String(text ?? "").trim());
+        },
+        onTranscriptionCommitted: (text: string) => {
+          const committed = String(text ?? "").trim();
+          if (committed) this.options.onCommit?.(committed);
+          else this.options.onPartial?.("");
+        },
+      },
+      false // streaming mode
+    );
+
+    this.moonshine = transcriber;
+    await transcriber.start();
+    if (this.stopRequested) {
+      await this.stop();
+      return;
+    }
+    this.setListening(true);
+  }
+}