@athenaintel/react 0.23.3 → 0.24.0

package/dist/dictation/recorded-dictation-engine.js

@@ -0,0 +1,153 @@
+import { DICTATION_ENGINE_ERROR_KINDS } from "./dictation-engine.js";
+const DEFAULT_MIME_TYPES = ["audio/webm;codecs=opus", "audio/webm", "audio/mp4", "audio/ogg;codecs=opus"];
+const DEFAULT_FLUSH_TIMEOUT_MS = 9e4;
+const DEFAULT_MAX_RECORDING_MS = 5 * 6e4;
+function resolveMediaRecorderCtor() {
+  if (typeof window === "undefined") return null;
+  return window.MediaRecorder ?? null;
+}
+function pickRecorderMimeType(Ctor, candidates) {
+  if (!Ctor.isTypeSupported) return void 0;
+  return candidates.find((type) => {
+    var _a;
+    return (_a = Ctor.isTypeSupported) == null ? void 0 : _a.call(Ctor, type);
+  });
+}
+function transcriptionError(error) {
+  return {
+    kind: DICTATION_ENGINE_ERROR_KINDS.connection,
+    message: error instanceof Error && error.message ? error.message : "Transcription failed. Try again."
+  };
+}
+function createRecordedDictationEngine(options) {
+  const {
+    transcribe,
+    mimeTypes = DEFAULT_MIME_TYPES,
+    flushTimeoutMs = DEFAULT_FLUSH_TIMEOUT_MS,
+    maxDurationMs = DEFAULT_MAX_RECORDING_MS
+  } = options;
+  return {
+    id: "recorded-upload",
+    flushTimeoutMs,
+    stoppingLabel: "Transcribing…",
+    isSupported: () => {
+      var _a;
+      return resolveMediaRecorderCtor() !== null && typeof navigator !== "undefined" && typeof ((_a = navigator.mediaDevices) == null ? void 0 : _a.getUserMedia) === "function";
+    },
+    start: ({ stream, lang, callbacks }) => {
+      const Ctor = resolveMediaRecorderCtor();
+      const noop = { stop: () => void 0, abort: () => void 0 };
+      if (!Ctor || !stream) {
+        callbacks.onError({
+          kind: !Ctor ? DICTATION_ENGINE_ERROR_KINDS.unsupported : DICTATION_ENGINE_ERROR_KINDS.permission,
+          message: !Ctor ? "This browser cannot record audio." : "No microphone stream was available."
+        });
+        callbacks.onEnd();
+        return noop;
+      }
+      const mimeType = pickRecorderMimeType(Ctor, mimeTypes);
+      let recorder;
+      try {
+        recorder = new Ctor(stream, mimeType ? { mimeType } : void 0);
+      } catch (error) {
+        callbacks.onError({
+          kind: DICTATION_ENGINE_ERROR_KINDS.unknown,
+          message: error instanceof Error ? error.message : "Recording could not start."
+        });
+        callbacks.onEnd();
+        return noop;
+      }
+      const chunks = [];
+      const upload = new AbortController();
+      let ended = false;
+      let aborted = false;
+      let limitTimer;
+      const clearLimit = () => {
+        if (limitTimer === void 0) return;
+        clearTimeout(limitTimer);
+        limitTimer = void 0;
+      };
+      const end = () => {
+        if (ended) return;
+        ended = true;
+        clearLimit();
+        recorder.ondataavailable = null;
+        recorder.onstop = null;
+        recorder.onerror = null;
+        callbacks.onEnd();
+      };
+      const stopRecorder = () => {
+        if (recorder.state === "inactive") return false;
+        try {
+          recorder.stop();
+          return true;
+        } catch {
+          return false;
+        }
+      };
+      recorder.ondataavailable = (event) => {
+        if (event.data && event.data.size > 0) chunks.push(event.data);
+      };
+      recorder.onerror = () => {
+        callbacks.onError({
+          kind: DICTATION_ENGINE_ERROR_KINDS.unknown,
+          message: "Recording stopped unexpectedly."
+        });
+        end();
+      };
+      recorder.onstop = () => {
+        if (aborted || ended) {
+          end();
+          return;
+        }
+        const clip = new Blob(chunks, { type: recorder.mimeType || mimeType || "audio/webm" });
+        if (clip.size === 0) {
+          end();
+          return;
+        }
+        void transcribe(clip, { lang, signal: upload.signal }).then((text) => {
+          if (ended) return;
+          const trimmed = text.trim();
+          if (trimmed) callbacks.onTranscript({ final: trimmed, interim: "" });
+        }).catch((error) => {
+          if (ended) return;
+          callbacks.onError(transcriptionError(error));
+        }).finally(end);
+      };
+      try {
+        recorder.start();
+      } catch (error) {
+        callbacks.onError({
+          kind: DICTATION_ENGINE_ERROR_KINDS.unknown,
+          message: error instanceof Error ? error.message : "Recording could not start."
+        });
+        end();
+        return noop;
+      }
+      if (Number.isFinite(maxDurationMs) && maxDurationMs > 0) {
+        limitTimer = setTimeout(() => {
+          limitTimer = void 0;
+          if (!ended) stopRecorder();
+        }, maxDurationMs);
+      }
+      return {
+        stop: () => {
+          clearLimit();
+          if (!stopRecorder()) end();
+        },
+        abort: () => {
+          aborted = true;
+          upload.abort();
+          stopRecorder();
+          end();
+        }
+      };
+    }
+  };
+}
+export {
+  DEFAULT_MAX_RECORDING_MS,
+  createRecordedDictationEngine,
+  pickRecorderMimeType
+};
+//# sourceMappingURL=recorded-dictation-engine.js.map

package/dist/dictation/recorded-dictation-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorded-dictation-engine.js","sources":["../../src/dictation/recorded-dictation-engine.ts"],"sourcesContent":["import {\n  DICTATION_ENGINE_ERROR_KINDS,\n  type DictationEngine,\n  type DictationEngineError,\n} from './dictation-engine';\n\nexport interface DictationTranscribeContext {\n  /** BCP-47 tag the session was started with (host `lang` or the document's). */\n  lang: string;\n  /** Fires when the user cancels or the composer gives up waiting. */\n  signal: AbortSignal;\n}\n\n/**\n * Turn a finished recording into text. Receives the whole clip once the user\n * stops; resolves with the transcript (empty when nothing was said). Should\n * honour `signal` so a cancelled dictation does not keep uploading.\n */\nexport type DictationTranscriber = (clip: Blob, context: DictationTranscribeContext) => Promise<string>;\n\nexport interface RecordedDictationEngineOptions {\n  transcribe: DictationTranscriber;\n  /**\n   * Preferred `MediaRecorder` container, tried in order until the browser\n   * accepts one. Defaults to Opus in WebM (Chrome, Firefox, Edge) then MP4\n   * (Safari); the browser's own default is the last resort.\n   */\n  mimeTypes?: readonly string[];\n  /**\n   * Upper bound on the transcription round trip; the in-flight request is\n   * aborted when it elapses. Defaults to 90s, above agora's 60s Deepgram\n   * budget plus upload time.\n   */\n  flushTimeoutMs?: number;\n  /**\n   * Longest recording the engine accepts before it stops on its own and\n   * transcribes what it has, exactly as if Stop had been pressed. Bounds a\n   * mic left open by mistake: every recorded minute is a minute billed by the\n   * recognizer, and agora refuses clips over its size cap. Defaults to\n   * 5 minutes; pass `Infinity` to disable.\n   */\n  maxDurationMs?: number;\n}\n\nconst DEFAULT_MIME_TYPES = ['audio/webm;codecs=opus', 'audio/webm', 'audio/mp4', 'audio/ogg;codecs=opus'];\nconst DEFAULT_FLUSH_TIMEOUT_MS = 90_000;\nexport const DEFAULT_MAX_RECORDING_MS = 5 * 60_000;\n\n// lib.dom typings for MediaRecorder vary across the TypeScript versions the\n// SDK supports; describe only what the engine touches.\ninterface MediaRecorderLike extends EventTarget {\n  readonly state: 'inactive' | 'recording' | 'paused';\n  readonly mimeType: string;\n  start: (timeslice?: number) => void;\n  stop: () => void;\n  ondataavailable: ((event: { data: Blob }) => void) | null;\n  onstop: (() => void) | null;\n  onerror: ((event: Event) => void) | null;\n}\ninterface MediaRecorderCtor {\n  new (stream: MediaStream, options?: { mimeType?: string }): MediaRecorderLike;\n  isTypeSupported?: (type: string) => boolean;\n}\n\nfunction resolveMediaRecorderCtor(): MediaRecorderCtor | null {\n  if (typeof window === 'undefined') return null;\n  return (window as unknown as { MediaRecorder?: MediaRecorderCtor }).MediaRecorder ?? null;\n}\n\n/** First container the recorder accepts, or undefined for the browser default. */\nexport function pickRecorderMimeType(\n  Ctor: Pick<MediaRecorderCtor, 'isTypeSupported'>,\n  candidates: readonly string[],\n): string | undefined {\n  if (!Ctor.isTypeSupported) return undefined;\n  return candidates.find((type) => Ctor.isTypeSupported?.(type));\n}\n\nfunction transcriptionError(error: unknown): DictationEngineError {\n  return {\n    kind: DICTATION_ENGINE_ERROR_KINDS.connection,\n    message: error instanceof Error && error.message ? error.message : 'Transcription failed. Try again.',\n  };\n}\n\n/**\n * Record-then-transcribe: capture the microphone with `MediaRecorder` while\n * the user talks, then hand the finished clip to `transcribe` on stop. No\n * interim words are shown; the composer shows a \"transcribing\" state until\n * the text lands. Works in every browser with `MediaRecorder`, so the mic is\n * available where Web Speech is not (Firefox) and the quality is whatever the\n * server-side recognizer provides.\n */\nexport function createRecordedDictationEngine(options: RecordedDictationEngineOptions): DictationEngine {\n  const {\n    transcribe,\n    mimeTypes = DEFAULT_MIME_TYPES,\n    flushTimeoutMs = DEFAULT_FLUSH_TIMEOUT_MS,\n    maxDurationMs = DEFAULT_MAX_RECORDING_MS,\n  } = options;\n  return {\n    id: 'recorded-upload',\n    flushTimeoutMs,\n    stoppingLabel: 'Transcribing…',\n    isSupported: () =>\n      resolveMediaRecorderCtor() !== null &&\n      typeof navigator !== 'undefined' &&\n      typeof navigator.mediaDevices?.getUserMedia === 'function',\n    start: ({ stream, lang, callbacks }) => {\n      const Ctor = resolveMediaRecorderCtor();\n      const noop = { stop: () => undefined, abort: () => undefined };\n      if (!Ctor || !stream) {\n        callbacks.onError({\n          kind: !Ctor ? DICTATION_ENGINE_ERROR_KINDS.unsupported : DICTATION_ENGINE_ERROR_KINDS.permission,\n          message: !Ctor ? 'This browser cannot record audio.' : 'No microphone stream was available.',\n        });\n        callbacks.onEnd();\n        return noop;\n      }\n\n      const mimeType = pickRecorderMimeType(Ctor, mimeTypes);\n      let recorder: MediaRecorderLike;\n      try {\n        recorder = new Ctor(stream, mimeType ? { mimeType } : undefined);\n      } catch (error) {\n        callbacks.onError({\n          kind: DICTATION_ENGINE_ERROR_KINDS.unknown,\n          message: error instanceof Error ? error.message : 'Recording could not start.',\n        });\n        callbacks.onEnd();\n        return noop;\n      }\n\n      const chunks: Blob[] = [];\n      const upload = new AbortController();\n      let ended = false;\n      let aborted = false;\n      let limitTimer: ReturnType<typeof setTimeout> | undefined;\n      const clearLimit = () => {\n        if (limitTimer === undefined) return;\n        clearTimeout(limitTimer);\n        limitTimer = undefined;\n      };\n      const end = () => {\n        if (ended) return;\n        ended = true;\n        clearLimit();\n        recorder.ondataavailable = null;\n        recorder.onstop = null;\n        recorder.onerror = null;\n        callbacks.onEnd();\n      };\n      const stopRecorder = () => {\n        if (recorder.state === 'inactive') return false;\n        try {\n          recorder.stop();\n          return true;\n        } catch {\n          return false;\n        }\n      };\n\n      recorder.ondataavailable = (event) => {\n        if (event.data && event.data.size > 0) chunks.push(event.data);\n      };\n      recorder.onerror = () => {\n        callbacks.onError({\n          kind: DICTATION_ENGINE_ERROR_KINDS.unknown,\n          message: 'Recording stopped unexpectedly.',\n        });\n        end();\n      };\n      recorder.onstop = () => {\n        if (aborted || ended) {\n          end();\n          return;\n        }\n        const clip = new Blob(chunks, { type: recorder.mimeType || mimeType || 'audio/webm' });\n        if (clip.size === 0) {\n          end();\n          return;\n        }\n        void transcribe(clip, { lang, signal: upload.signal })\n          .then((text) => {\n            if (ended) return;\n            const trimmed = text.trim();\n            if (trimmed) callbacks.onTranscript({ final: trimmed, interim: '' });\n          })\n          .catch((error: unknown) => {\n            if (ended) return;\n            callbacks.onError(transcriptionError(error));\n          })\n          .finally(end);\n      };\n\n      try {\n        recorder.start();\n      } catch (error) {\n        callbacks.onError({\n          kind: DICTATION_ENGINE_ERROR_KINDS.unknown,\n          message: error instanceof Error ? error.message : 'Recording could not start.',\n        });\n        end();\n        return noop;\n      }\n\n      if (Number.isFinite(maxDurationMs) && maxDurationMs > 0) {\n        limitTimer = setTimeout(() => {\n          limitTimer = undefined;\n          // Same path as the user's Stop: onstop transcribes the clip and the\n          // words land in the draft. A recorder that is already inactive is a\n          // stop in flight, which must run to completion untouched.\n          if (!ended) stopRecorder();\n        }, maxDurationMs);\n      }\n\n      return {\n        stop: () => {\n          clearLimit();\n          if (!stopRecorder()) end();\n        },\n        abort: () => {\n          aborted = true;\n          upload.abort();\n          stopRecorder();\n          end();\n        },\n      };\n    },\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/dictation/use-athena-dictation-engine.cjs

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const AthenaContext = require("../provider/AthenaContext.cjs");
+const statewireAuthHeaders = require("../runtime/statewire-auth-headers.cjs");
+const dictationEngine = require("./dictation-engine.cjs");
+const recordedDictationEngine = require("./recorded-dictation-engine.cjs");
+function transcriptionUploadUrl(backendUrl) {
+  return `${backendUrl.replace(/\/api\/assistant-ui\/?$/, "").replace(/\/$/, "")}/api/transcription/upload`;
+}
+function transcriptionUploadErrorMessage(status) {
+  switch (status) {
+    case 401:
+    case 403:
+      return "Dictation is not available for this sign-in. Reload and try again.";
+    case 413:
+      return "That recording is too long to transcribe.";
+    case 422:
+      return "The dictation language was rejected. Use a BCP-47 tag such as en-US.";
+    case 429:
+      return "Too many dictations in a row. Wait a moment and try again.";
+    case 503:
+      return "Dictation is not set up on this server.";
+    default:
+      return `Transcription failed (${status}).`;
+  }
+}
+function createAthenaUploadTranscriber(getConfig) {
+  return async (clip, { lang, signal }) => {
+    const config = getConfig();
+    const headers = await statewireAuthHeaders.resolveStatewireAuthHeaders(config, { staleAuth: false });
+    const form = new FormData();
+    const extension = clip.type.includes("mp4") ? "mp4" : clip.type.includes("ogg") ? "ogg" : "webm";
+    form.append("file", clip, `dictation.${extension}`);
+    if (lang) form.append("language", lang);
+    const response = await fetch(transcriptionUploadUrl(config.backendUrl), {
+      method: "POST",
+      headers,
+      body: form,
+      credentials: "include",
+      signal
+    });
+    if (!response.ok) throw new Error(transcriptionUploadErrorMessage(response.status));
+    const payload = await response.json();
+    return typeof payload.transcript === "string" ? payload.transcript : "";
+  };
+}
+function useAthenaDictationEngine(override) {
+  const config = AthenaContext.useAthenaConfig();
+  const configRef = react.useRef(config);
+  configRef.current = config;
+  return react.useMemo(() => {
+    if (override) return override;
+    const recorded = recordedDictationEngine.createRecordedDictationEngine({
+      transcribe: createAthenaUploadTranscriber(() => configRef.current)
+    });
+    return recorded.isSupported() ? recorded : dictationEngine.createWebSpeechDictationEngine();
+  }, [override]);
+}
+exports.createAthenaUploadTranscriber = createAthenaUploadTranscriber;
+exports.transcriptionUploadErrorMessage = transcriptionUploadErrorMessage;
+exports.transcriptionUploadUrl = transcriptionUploadUrl;
+exports.useAthenaDictationEngine = useAthenaDictationEngine;
+//# sourceMappingURL=use-athena-dictation-engine.cjs.map

package/dist/dictation/use-athena-dictation-engine.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-athena-dictation-engine.cjs","sources":["../../src/dictation/use-athena-dictation-engine.ts"],"sourcesContent":["import { useMemo, useRef } from 'react';\nimport { type AthenaConfig, useAthenaConfig } from '../provider/AthenaContext';\nimport { resolveStatewireAuthHeaders } from '../runtime/statewire-auth-headers';\nimport { createWebSpeechDictationEngine, type DictationEngine } from './dictation-engine';\nimport { createRecordedDictationEngine, type DictationTranscriber } from './recorded-dictation-engine';\n\ninterface UploadTranscriptionResponse {\n  transcript: string;\n}\n\n/** Agora's REST base from the configured backend URL (which may point at a nested endpoint). */\nexport function transcriptionUploadUrl(backendUrl: string): string {\n  return `${backendUrl.replace(/\\/api\\/assistant-ui\\/?$/, '').replace(/\\/$/, '')}/api/transcription/upload`;\n}\n\n/**\n * One line for the composer per way `/transcription/upload` refuses a clip.\n * The copy lives here, apart from the fetch, so it can be pinned by a test.\n */\nexport function transcriptionUploadErrorMessage(status: number): string {\n  switch (status) {\n    case 401:\n    case 403:\n      return 'Dictation is not available for this sign-in. Reload and try again.';\n    case 413:\n      return 'That recording is too long to transcribe.';\n    case 422:\n      return 'The dictation language was rejected. Use a BCP-47 tag such as en-US.';\n    case 429:\n      return 'Too many dictations in a row. Wait a moment and try again.';\n    case 503:\n      return 'Dictation is not set up on this server.';\n    default:\n      return `Transcription failed (${status}).`;\n  }\n}\n\n/**\n * Post a finished clip to agora's `/transcription/upload` route, which runs\n * it through Deepgram and returns the text. Credentials are read at call\n * time so a rotated token is picked up. The session language (host `lang`\n * or the document's) is forwarded so non-English speech is recognised as\n * such; the request is dropped when the engine aborts.\n */\nexport function createAthenaUploadTranscriber(\n  getConfig: () => Pick<AthenaConfig, 'backendUrl' | 'apiKey' | 'token' | 'getToken'>,\n): DictationTranscriber {\n  return async (clip, { lang, signal }) => {\n    const config = getConfig();\n    const headers = await resolveStatewireAuthHeaders(config, { staleAuth: false });\n    const form = new FormData();\n    const extension = clip.type.includes('mp4') ? 'mp4' : clip.type.includes('ogg') ? 'ogg' : 'webm';\n    form.append('file', clip, `dictation.${extension}`);\n    if (lang) form.append('language', lang);\n    const response = await fetch(transcriptionUploadUrl(config.backendUrl), {\n      method: 'POST',\n      headers,\n      body: form,\n      credentials: 'include',\n      signal,\n    });\n    if (!response.ok) throw new Error(transcriptionUploadErrorMessage(response.status));\n    const payload = (await response.json()) as UploadTranscriptionResponse;\n    return typeof payload.transcript === 'string' ? payload.transcript : '';\n  };\n}\n\n/**\n * The composer's default speech engine: record with `MediaRecorder`, then\n * transcribe the clip through agora (Deepgram). Falls back to the browser's\n * Web Speech API only where `MediaRecorder` is missing. A host-provided\n * `engine` always wins.\n */\nexport function useAthenaDictationEngine(override?: DictationEngine): DictationEngine {\n  const config = useAthenaConfig();\n  const configRef = useRef(config);\n  configRef.current = config;\n  return useMemo(() => {\n    if (override) return override;\n    const recorded = createRecordedDictationEngine({\n      transcribe: createAthenaUploadTranscriber(() => configRef.current),\n    });\n    return recorded.isSupported() ? recorded : createWebSpeechDictationEngine();\n  }, [override]);\n}\n"],"names":["resolveStatewireAuthHeaders","useAthenaConfig","useRef","useMemo","createRecordedDictationEngine","createWebSpeechDictationEngine"],"mappings":";;;;;;;AAWO,SAAS,uBAAuB,YAA4B;AACjE,SAAO,GAAG,WAAW,QAAQ,2BAA2B,EAAE,EAAE,QAAQ,OAAO,EAAE,CAAC;AAChF;AAMO,SAAS,gCAAgC,QAAwB;AACtE,UAAQ,QAAA;AAAA,IACN,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO,yBAAyB,MAAM;AAAA,EAAA;AAE5C;AASO,SAAS,8BACd,WACsB;AACtB,SAAO,OAAO,MAAM,EAAE,MAAM,aAAa;AACvC,UAAM,SAAS,UAAA;AACf,UAAM,UAAU,MAAMA,qBAAAA,4BAA4B,QAAQ,EAAE,WAAW,OAAO;AAC9E,UAAM,OAAO,IAAI,SAAA;AACjB,UAAM,YAAY,KAAK,KAAK,SAAS,KAAK,IAAI,QAAQ,KAAK,KAAK,SAAS,KAAK,IAAI,QAAQ;AAC1F,SAAK,OAAO,QAAQ,MAAM,aAAa,SAAS,EAAE;AAClD,QAAI,KAAM,MAAK,OAAO,YAAY,IAAI;AACtC,UAAM,WAAW,MAAM,MAAM,uBAAuB,OAAO,UAAU,GAAG;AAAA,MACtE,QAAQ;AAAA,MACR;AAAA,MACA,MAAM;AAAA,MACN,aAAa;AAAA,MACb;AAAA,IAAA,CACD;AACD,QAAI,CAAC,SAAS,GAAI,OAAM,IAAI,MAAM,gCAAgC,SAAS,MAAM,CAAC;AAClF,UAAM,UAAW,MAAM,SAAS,KAAA;AAChC,WAAO,OAAO,QAAQ,eAAe,WAAW,QAAQ,aAAa;AAAA,EACvE;AACF;AAQO,SAAS,yBAAyB,UAA6C;AACpF,QAAM,SAASC,cAAAA,gBAAA;AACf,QAAM,YAAYC,MAAAA,OAAO,MAAM;AAC/B,YAAU,UAAU;AACpB,SAAOC,MAAAA,QAAQ,MAAM;AACnB,QAAI,SAAU,QAAO;AACrB,UAAM,WAAWC,wBAAAA,8BAA8B;AAAA,MAC7C,YAAY,8BAA8B,MAAM,UAAU,OAAO;AAAA,IAAA,CAClE;AACD,WAAO,SAAS,gBAAgB,WAAWC,gBAAAA,+BAAA;AAAA,EAC7C,GAAG,CAAC,QAAQ,CAAC;AACf;;;;;"}

package/dist/dictation/use-athena-dictation-engine.d.ts

@@ -0,0 +1,25 @@
+import { type AthenaConfig } from '../provider/AthenaContext';
+import { type DictationEngine } from './dictation-engine';
+import { type DictationTranscriber } from './recorded-dictation-engine';
+/** Agora's REST base from the configured backend URL (which may point at a nested endpoint). */
+export declare function transcriptionUploadUrl(backendUrl: string): string;
+/**
+ * One line for the composer per way `/transcription/upload` refuses a clip.
+ * The copy lives here, apart from the fetch, so it can be pinned by a test.
+ */
+export declare function transcriptionUploadErrorMessage(status: number): string;
+/**
+ * Post a finished clip to agora's `/transcription/upload` route, which runs
+ * it through Deepgram and returns the text. Credentials are read at call
+ * time so a rotated token is picked up. The session language (host `lang`
+ * or the document's) is forwarded so non-English speech is recognised as
+ * such; the request is dropped when the engine aborts.
+ */
+export declare function createAthenaUploadTranscriber(getConfig: () => Pick<AthenaConfig, 'backendUrl' | 'apiKey' | 'token' | 'getToken'>): DictationTranscriber;
+/**
+ * The composer's default speech engine: record with `MediaRecorder`, then
+ * transcribe the clip through agora (Deepgram). Falls back to the browser's
+ * Web Speech API only where `MediaRecorder` is missing. A host-provided
+ * `engine` always wins.
+ */
+export declare function useAthenaDictationEngine(override?: DictationEngine): DictationEngine;

package/dist/dictation/use-athena-dictation-engine.js

@@ -0,0 +1,64 @@
+import { useRef, useMemo } from "react";
+import { useAthenaConfig } from "../provider/AthenaContext.js";
+import { resolveStatewireAuthHeaders } from "../runtime/statewire-auth-headers.js";
+import { createWebSpeechDictationEngine } from "./dictation-engine.js";
+import { createRecordedDictationEngine } from "./recorded-dictation-engine.js";
+function transcriptionUploadUrl(backendUrl) {
+  return `${backendUrl.replace(/\/api\/assistant-ui\/?$/, "").replace(/\/$/, "")}/api/transcription/upload`;
+}
+function transcriptionUploadErrorMessage(status) {
+  switch (status) {
+    case 401:
+    case 403:
+      return "Dictation is not available for this sign-in. Reload and try again.";
+    case 413:
+      return "That recording is too long to transcribe.";
+    case 422:
+      return "The dictation language was rejected. Use a BCP-47 tag such as en-US.";
+    case 429:
+      return "Too many dictations in a row. Wait a moment and try again.";
+    case 503:
+      return "Dictation is not set up on this server.";
+    default:
+      return `Transcription failed (${status}).`;
+  }
+}
+function createAthenaUploadTranscriber(getConfig) {
+  return async (clip, { lang, signal }) => {
+    const config = getConfig();
+    const headers = await resolveStatewireAuthHeaders(config, { staleAuth: false });
+    const form = new FormData();
+    const extension = clip.type.includes("mp4") ? "mp4" : clip.type.includes("ogg") ? "ogg" : "webm";
+    form.append("file", clip, `dictation.${extension}`);
+    if (lang) form.append("language", lang);
+    const response = await fetch(transcriptionUploadUrl(config.backendUrl), {
+      method: "POST",
+      headers,
+      body: form,
+      credentials: "include",
+      signal
+    });
+    if (!response.ok) throw new Error(transcriptionUploadErrorMessage(response.status));
+    const payload = await response.json();
+    return typeof payload.transcript === "string" ? payload.transcript : "";
+  };
+}
+function useAthenaDictationEngine(override) {
+  const config = useAthenaConfig();
+  const configRef = useRef(config);
+  configRef.current = config;
+  return useMemo(() => {
+    if (override) return override;
+    const recorded = createRecordedDictationEngine({
+      transcribe: createAthenaUploadTranscriber(() => configRef.current)
+    });
+    return recorded.isSupported() ? recorded : createWebSpeechDictationEngine();
+  }, [override]);
+}
+export {
+  createAthenaUploadTranscriber,
+  transcriptionUploadErrorMessage,
+  transcriptionUploadUrl,
+  useAthenaDictationEngine
+};
+//# sourceMappingURL=use-athena-dictation-engine.js.map

package/dist/dictation/use-athena-dictation-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-athena-dictation-engine.js","sources":["../../src/dictation/use-athena-dictation-engine.ts"],"sourcesContent":["import { useMemo, useRef } from 'react';\nimport { type AthenaConfig, useAthenaConfig } from '../provider/AthenaContext';\nimport { resolveStatewireAuthHeaders } from '../runtime/statewire-auth-headers';\nimport { createWebSpeechDictationEngine, type DictationEngine } from './dictation-engine';\nimport { createRecordedDictationEngine, type DictationTranscriber } from './recorded-dictation-engine';\n\ninterface UploadTranscriptionResponse {\n  transcript: string;\n}\n\n/** Agora's REST base from the configured backend URL (which may point at a nested endpoint). */\nexport function transcriptionUploadUrl(backendUrl: string): string {\n  return `${backendUrl.replace(/\\/api\\/assistant-ui\\/?$/, '').replace(/\\/$/, '')}/api/transcription/upload`;\n}\n\n/**\n * One line for the composer per way `/transcription/upload` refuses a clip.\n * The copy lives here, apart from the fetch, so it can be pinned by a test.\n */\nexport function transcriptionUploadErrorMessage(status: number): string {\n  switch (status) {\n    case 401:\n    case 403:\n      return 'Dictation is not available for this sign-in. Reload and try again.';\n    case 413:\n      return 'That recording is too long to transcribe.';\n    case 422:\n      return 'The dictation language was rejected. Use a BCP-47 tag such as en-US.';\n    case 429:\n      return 'Too many dictations in a row. Wait a moment and try again.';\n    case 503:\n      return 'Dictation is not set up on this server.';\n    default:\n      return `Transcription failed (${status}).`;\n  }\n}\n\n/**\n * Post a finished clip to agora's `/transcription/upload` route, which runs\n * it through Deepgram and returns the text. Credentials are read at call\n * time so a rotated token is picked up. The session language (host `lang`\n * or the document's) is forwarded so non-English speech is recognised as\n * such; the request is dropped when the engine aborts.\n */\nexport function createAthenaUploadTranscriber(\n  getConfig: () => Pick<AthenaConfig, 'backendUrl' | 'apiKey' | 'token' | 'getToken'>,\n): DictationTranscriber {\n  return async (clip, { lang, signal }) => {\n    const config = getConfig();\n    const headers = await resolveStatewireAuthHeaders(config, { staleAuth: false });\n    const form = new FormData();\n    const extension = clip.type.includes('mp4') ? 'mp4' : clip.type.includes('ogg') ? 'ogg' : 'webm';\n    form.append('file', clip, `dictation.${extension}`);\n    if (lang) form.append('language', lang);\n    const response = await fetch(transcriptionUploadUrl(config.backendUrl), {\n      method: 'POST',\n      headers,\n      body: form,\n      credentials: 'include',\n      signal,\n    });\n    if (!response.ok) throw new Error(transcriptionUploadErrorMessage(response.status));\n    const payload = (await response.json()) as UploadTranscriptionResponse;\n    return typeof payload.transcript === 'string' ? payload.transcript : '';\n  };\n}\n\n/**\n * The composer's default speech engine: record with `MediaRecorder`, then\n * transcribe the clip through agora (Deepgram). Falls back to the browser's\n * Web Speech API only where `MediaRecorder` is missing. A host-provided\n * `engine` always wins.\n */\nexport function useAthenaDictationEngine(override?: DictationEngine): DictationEngine {\n  const config = useAthenaConfig();\n  const configRef = useRef(config);\n  configRef.current = config;\n  return useMemo(() => {\n    if (override) return override;\n    const recorded = createRecordedDictationEngine({\n      transcribe: createAthenaUploadTranscriber(() => configRef.current),\n    });\n    return recorded.isSupported() ? recorded : createWebSpeechDictationEngine();\n  }, [override]);\n}\n"],"names":[],"mappings":";;;;;AAWO,SAAS,uBAAuB,YAA4B;AACjE,SAAO,GAAG,WAAW,QAAQ,2BAA2B,EAAE,EAAE,QAAQ,OAAO,EAAE,CAAC;AAChF;AAMO,SAAS,gCAAgC,QAAwB;AACtE,UAAQ,QAAA;AAAA,IACN,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO,yBAAyB,MAAM;AAAA,EAAA;AAE5C;AASO,SAAS,8BACd,WACsB;AACtB,SAAO,OAAO,MAAM,EAAE,MAAM,aAAa;AACvC,UAAM,SAAS,UAAA;AACf,UAAM,UAAU,MAAM,4BAA4B,QAAQ,EAAE,WAAW,OAAO;AAC9E,UAAM,OAAO,IAAI,SAAA;AACjB,UAAM,YAAY,KAAK,KAAK,SAAS,KAAK,IAAI,QAAQ,KAAK,KAAK,SAAS,KAAK,IAAI,QAAQ;AAC1F,SAAK,OAAO,QAAQ,MAAM,aAAa,SAAS,EAAE;AAClD,QAAI,KAAM,MAAK,OAAO,YAAY,IAAI;AACtC,UAAM,WAAW,MAAM,MAAM,uBAAuB,OAAO,UAAU,GAAG;AAAA,MACtE,QAAQ;AAAA,MACR;AAAA,MACA,MAAM;AAAA,MACN,aAAa;AAAA,MACb;AAAA,IAAA,CACD;AACD,QAAI,CAAC,SAAS,GAAI,OAAM,IAAI,MAAM,gCAAgC,SAAS,MAAM,CAAC;AAClF,UAAM,UAAW,MAAM,SAAS,KAAA;AAChC,WAAO,OAAO,QAAQ,eAAe,WAAW,QAAQ,aAAa;AAAA,EACvE;AACF;AAQO,SAAS,yBAAyB,UAA6C;AACpF,QAAM,SAAS,gBAAA;AACf,QAAM,YAAY,OAAO,MAAM;AAC/B,YAAU,UAAU;AACpB,SAAO,QAAQ,MAAM;AACnB,QAAI,SAAU,QAAO;AACrB,UAAM,WAAW,8BAA8B;AAAA,MAC7C,YAAY,8BAA8B,MAAM,UAAU,OAAO;AAAA,IAAA,CAClE;AACD,WAAO,SAAS,gBAAgB,WAAW,+BAAA;AAAA,EAC7C,GAAG,CAAC,QAAQ,CAAC;AACf;"}

package/dist/dictation/use-dictation.cjs

@@ -4,7 +4,7 @@ const react = require("react");
 const athenaDiagnostics = require("../diagnostics/athena-diagnostics.cjs");
 const dictationEngine = require("./dictation-engine.cjs");
 const dictationState = require("./dictation-state.cjs");
-const STOP_FLUSH_TIMEOUT_MS = 1500;
+const DEFAULT_STOP_FLUSH_TIMEOUT_MS = 1500;
 const EMPTY_TRANSCRIPT = { final: "", interim: "" };
 function documentLanguage() {
   if (typeof document !== "undefined" && document.documentElement.lang) {
@@ -36,6 +36,7 @@ function useDictation(options = {}) {
   const onAutoEndRef = react.useRef(onAutoEnd);
   onAutoEndRef.current = onAutoEnd;
   const stopWaitersRef = react.useRef([]);
+  const sessionErrorRef = react.useRef(null);
   const generationRef = react.useRef(0);
   react.useEffect(() => {
     setIsSupported(engine.isSupported());
@@ -43,7 +44,8 @@ function useDictation(options = {}) {
   const settleWaiters = react.useCallback((spoken) => {
     const waiters = stopWaitersRef.current;
     stopWaitersRef.current = [];
-    for (const resolve of waiters) resolve(spoken);
+    const result = { text: spoken, error: sessionErrorRef.current };
+    for (const resolve of waiters) resolve(result);
   }, []);
   const releaseSession = react.useCallback(() => {
     sessionRef.current = null;
@@ -65,6 +67,7 @@ function useDictation(options = {}) {
         level: "warn",
         data: { phase: "error", engine: engine.id, kind: engineError.kind }
       });
+      sessionErrorRef.current = engineError;
       dispatch({ type: "error", error: engineError });
     },
     [engine.id]
@@ -74,6 +77,7 @@ function useDictation(options = {}) {
     const generation = generationRef.current + 1;
     generationRef.current = generation;
     transcriptRef.current = EMPTY_TRANSCRIPT;
+    sessionErrorRef.current = null;
     dispatch({ type: "start" });
     athenaDiagnostics.athenaDiagnostics.emit("composer.dictation", {
       level: "debug",
@@ -162,25 +166,31 @@ function useDictation(options = {}) {
       if (stateRef.current.status === dictationState.DICTATION_STATUSES.starting) {
         teardown();
         dispatch({ type: "cancel" });
-        return Promise.resolve("");
+        return Promise.resolve({ text: "", error: null });
       }
-      return Promise.resolve(dictationState.spokenText(transcriptRef.current));
+      return Promise.resolve({ text: dictationState.spokenText(transcriptRef.current), error: sessionErrorRef.current });
     }
     dispatch({ type: "stop" });
     const flushed = new Promise((resolve) => {
       stopWaitersRef.current.push(resolve);
       window.setTimeout(() => {
         if (sessionRef.current === session) {
+          if (!dictationState.spokenText(transcriptRef.current)) {
+            reportEngineError({
+              kind: dictationEngine.DICTATION_ENGINE_ERROR_KINDS.connection,
+              message: "Transcription timed out. Try again."
+            });
+          }
           session.abort();
           dispatch({ type: "ended" });
           releaseSession();
           settleWaiters(dictationState.spokenText(transcriptRef.current));
         }
-      }, STOP_FLUSH_TIMEOUT_MS);
+      }, engine.flushTimeoutMs ?? DEFAULT_STOP_FLUSH_TIMEOUT_MS);
     });
     session.stop();
     return flushed;
-  }, [releaseSession, settleWaiters, teardown]);
+  }, [engine.flushTimeoutMs, releaseSession, reportEngineError, settleWaiters, teardown]);
   const cancel = react.useCallback(() => {
     teardown();
     dispatch({ type: "cancel" });
@@ -195,6 +205,7 @@ function useDictation(options = {}) {
     error: state.error,
     stream,
     isSupported,
+    engine,
     start,
     stop,
     cancel

package/dist/dictation/use-dictation.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-dictation.cjs","sources":["../../src/dictation/use-dictation.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react';\nimport { athenaDiagnostics } from '../diagnostics/athena-diagnostics';\nimport {\n  createWebSpeechDictationEngine,\n  DICTATION_ENGINE_ERROR_KINDS,\n  type DictationEngine,\n  type DictationEngineError,\n  type DictationEngineSession,\n} from './dictation-engine';\nimport {\n  DICTATION_STATUSES,\n  dictationReducer,\n  INITIAL_DICTATION_STATE,\n  joinSpeech,\n  spokenText,\n  type DictationStatus,\n  type DictationTranscript,\n} from './dictation-state';\n\nexport interface UseDictationOptions {\n  /** Speech engine. Defaults to the browser's Web Speech API. */\n  engine?: DictationEngine;\n  /** BCP-47 language tag. Defaults to the document language, else `en-US`. */\n  lang?: string;\n  /**\n   * Open the microphone through `getUserMedia` so callers get a `stream` for\n   * a waveform. Web Speech opens its own capture; this second capture is\n   * what the level meter reads. Defaults to true.\n   */\n  captureStream?: boolean;\n  /**\n   * The engine ended on its own (silence window, recognizer timeout) while\n   * listening, without `stop()` or `cancel()`. Receives the spoken text so\n   * the words are not lost; the composer puts them into the draft.\n   */\n  onAutoEnd?: (spoken: string) => void;\n}\n\nexport interface DictationController {\n  status: DictationStatus;\n  /** True while starting, listening or stopping. */\n  isActive: boolean;\n  transcript: DictationTranscript;\n  /** `final` plus the interim tail, ready to hand to the composer. */\n  text: string;\n  error: DictationEngineError | null;\n  /** The microphone stream while active (for a waveform), else null. */\n  stream: MediaStream | null;\n  /** Whether the engine can run here. Hide the control when false. */\n  isSupported: boolean;\n  start: () => void;\n  /**\n   * Finish recording. Resolves with the spoken text once the engine has\n   * flushed (bounded wait), so trailing words are not lost.\n   */\n  stop: () => Promise<string>;\n  /** Discard the session and its transcript. */\n  cancel: () => void;\n}\n\n/** How long `stop()` waits for the engine's final flush before giving up. */\nconst STOP_FLUSH_TIMEOUT_MS = 1500;\n\ntype StopResolver = (spoken: string) => void;\n\nconst EMPTY_TRANSCRIPT: DictationTranscript = { final: '', interim: '' };\n\nfunction documentLanguage(): string {\n  if (typeof document !== 'undefined' && document.documentElement.lang) {\n    return document.documentElement.lang;\n  }\n  if (typeof navigator !== 'undefined' && navigator.language) return navigator.language;\n  return 'en-US';\n}\n\nasync function openMicrophone(): Promise<MediaStream | null> {\n  if (typeof navigator === 'undefined' || !navigator.mediaDevices?.getUserMedia) return null;\n  return navigator.mediaDevices.getUserMedia({ audio: true });\n}\n\nfunction releaseStream(stream: MediaStream | null): void {\n  if (!stream) return;\n  for (const track of stream.getTracks()) track.stop();\n}\n\n/**\n * Drive a dictation session: microphone, speech engine, and the transcript\n * state machine. The composer renders the waveform from `stream` and the\n * live caption from `transcript`; on `stop()` it appends `text` to the draft.\n */\nexport function useDictation(options: UseDictationOptions = {}): DictationController {\n  const engine = useMemo(() => options.engine ?? createWebSpeechDictationEngine(), [options.engine]);\n  const { lang, captureStream = true, onAutoEnd } = options;\n  const [state, dispatch] = useReducer(dictationReducer, INITIAL_DICTATION_STATE);\n  const [stream, setStream] = useState<MediaStream | null>(null);\n  const [isSupported, setIsSupported] = useState(false);\n\n  const sessionRef = useRef<DictationEngineSession | null>(null);\n  const streamRef = useRef<MediaStream | null>(null);\n  const stateRef = useRef(state);\n  stateRef.current = state;\n  // The authoritative transcript, updated synchronously as the engine reports\n  // it. The reducer's copy renders the caption; this one is what `stop()` and\n  // `onAutoEnd` hand over, so an engine that flushes its last words and ends\n  // in the same tick — before React has rendered — loses nothing.\n  const transcriptRef = useRef<DictationTranscript>(EMPTY_TRANSCRIPT);\n  const onAutoEndRef = useRef(onAutoEnd);\n  onAutoEndRef.current = onAutoEnd;\n  // stop() callers waiting for the engine's final flush.\n  const stopWaitersRef = useRef<StopResolver[]>([]);\n  // Distinguishes a fresh session from the callbacks of a torn-down one.\n  const generationRef = useRef(0);\n\n  useEffect(() => {\n    setIsSupported(engine.isSupported());\n  }, [engine]);\n\n  const settleWaiters = useCallback((spoken: string) => {\n    const waiters = stopWaitersRef.current;\n    stopWaitersRef.current = [];\n    for (const resolve of waiters) resolve(spoken);\n  }, []);\n\n  const releaseSession = useCallback(() => {\n    sessionRef.current = null;\n    releaseStream(streamRef.current);\n    streamRef.current = null;\n    setStream(null);\n  }, []);\n\n  const teardown = useCallback(() => {\n    generationRef.current += 1;\n    sessionRef.current?.abort();\n    releaseSession();\n    transcriptRef.current = EMPTY_TRANSCRIPT;\n    settleWaiters('');\n  }, [releaseSession, settleWaiters]);\n\n  const reportEngineError = useCallback(\n    (engineError: DictationEngineError) => {\n      athenaDiagnostics.emit('composer.dictation', {\n        level: 'warn',\n        data: { phase: 'error', engine: engine.id, kind: engineError.kind },\n      });\n      dispatch({ type: 'error', error: engineError });\n    },\n    [engine.id],\n  );\n\n  const start = useCallback(() => {\n    if (sessionRef.current) return;\n    const generation = generationRef.current + 1;\n    generationRef.current = generation;\n    transcriptRef.current = EMPTY_TRANSCRIPT;\n    dispatch({ type: 'start' });\n    athenaDiagnostics.emit('composer.dictation', {\n      level: 'debug',\n      data: { phase: 'start', engine: engine.id },\n    });\n\n    const run = async () => {\n      let microphone: MediaStream | null = null;\n      if (captureStream) {\n        try {\n          microphone = await openMicrophone();\n        } catch (error) {\n          if (generationRef.current !== generation) {\n            releaseStream(microphone);\n            return;\n          }\n          dispatch({\n            type: 'error',\n            error: {\n              kind: DICTATION_ENGINE_ERROR_KINDS.permission,\n              message:\n                error instanceof DOMException && error.name === 'NotFoundError'\n                  ? 'No microphone was found.'\n                  : 'Microphone access was denied. Allow the microphone for this site and try again.',\n            },\n          });\n          return;\n        }\n      }\n      if (generationRef.current !== generation) {\n        releaseStream(microphone);\n        return;\n      }\n      streamRef.current = microphone;\n      setStream(microphone);\n\n      // An engine may fail synchronously inside start() (Web Speech throws\n      // when recognition.start() is refused) and run onError/onEnd before we\n      // hold the session. Those callbacks flip this flag so a dead session is\n      // never stored, which would make every later mic click return early.\n      let terminated = false;\n      const endSession = () => {\n        terminated = true;\n        const current = stateRef.current;\n        const spoken = spokenText(transcriptRef.current);\n        // No stop() is waiting: the engine gave up on its own. Hand the\n        // words over so they land in the draft instead of vanishing.\n        const endedOnItsOwn =\n          stopWaitersRef.current.length === 0 && current.status === DICTATION_STATUSES.listening;\n        // The reducer keeps an error status through 'ended', so an error\n        // reported just before the engine closed stays on screen.\n        dispatch({ type: 'ended' });\n        releaseSession();\n        settleWaiters(spoken);\n        if (endedOnItsOwn) onAutoEndRef.current?.(spoken);\n      };\n      let session: DictationEngineSession;\n      try {\n        session = engine.start({\n          stream: microphone,\n          lang: lang ?? documentLanguage(),\n          callbacks: {\n            onTranscript: (update) => {\n              if (generationRef.current !== generation) return;\n              transcriptRef.current = {\n                final: joinSpeech(transcriptRef.current.final, update.final),\n                interim: update.interim,\n              };\n              dispatch({ type: 'transcript', update });\n            },\n            onError: (engineError) => {\n              if (generationRef.current !== generation) return;\n              // A silence timeout is the engine giving up politely; keep the\n              // words we have instead of showing an error.\n              if (engineError.kind === DICTATION_ENGINE_ERROR_KINDS.noSpeech) return;\n              reportEngineError(engineError);\n            },\n            onEnd: () => {\n              if (generationRef.current !== generation) return;\n              endSession();\n            },\n          },\n        });\n      } catch (error) {\n        // A relay engine that cannot build its session must not strand the\n        // microphone or leave the composer in `starting`.\n        releaseSession();\n        reportEngineError({\n          kind: DICTATION_ENGINE_ERROR_KINDS.connection,\n          message: error instanceof Error ? error.message : 'Dictation could not start.',\n        });\n        return;\n      }\n      if (terminated) return;\n      sessionRef.current = session;\n      dispatch({ type: 'listening' });\n    };\n    void run();\n  }, [captureStream, engine, lang, releaseSession, reportEngineError, settleWaiters]);\n\n  const stop = useCallback((): Promise<string> => {\n    const session = sessionRef.current;\n    if (!session) {\n      // Stopped while the microphone prompt was still open: nothing was heard\n      // yet, and the pending start must not bring the engine up afterwards.\n      if (stateRef.current.status === DICTATION_STATUSES.starting) {\n        teardown();\n        dispatch({ type: 'cancel' });\n        return Promise.resolve('');\n      }\n      return Promise.resolve(spokenText(transcriptRef.current));\n    }\n    dispatch({ type: 'stop' });\n    const flushed = new Promise<string>((resolve) => {\n      stopWaitersRef.current.push(resolve);\n      window.setTimeout(() => {\n        // Bounded wait: a recognizer that never fires onend must not hold the\n        // composer hostage. Force the session closed and hand over what was\n        // heard so far.\n        if (sessionRef.current === session) {\n          session.abort();\n          dispatch({ type: 'ended' });\n          releaseSession();\n          settleWaiters(spokenText(transcriptRef.current));\n        }\n      }, STOP_FLUSH_TIMEOUT_MS);\n    });\n    session.stop();\n    return flushed;\n  }, [releaseSession, settleWaiters, teardown]);\n\n  const cancel = useCallback(() => {\n    teardown();\n    dispatch({ type: 'cancel' });\n  }, [teardown]);\n\n  // Release the microphone with the component.\n  useEffect(() => () => teardown(), [teardown]);\n\n  const isActive =\n    state.status === DICTATION_STATUSES.starting ||\n    state.status === DICTATION_STATUSES.listening ||\n    state.status === DICTATION_STATUSES.stopping;\n\n  return {\n    status: state.status,\n    isActive,\n    transcript: state.transcript,\n    text: spokenText(state.transcript),\n    error: state.error,\n    stream,\n    isSupported,\n    start,\n    stop,\n    cancel,\n  };\n}\n"],"names":["useMemo","createWebSpeechDictationEngine","useReducer","dictationReducer","INITIAL_DICTATION_STATE","useState","useRef","useEffect","useCallback","athenaDiagnostics","DICTATION_ENGINE_ERROR_KINDS","spokenText","DICTATION_STATUSES","joinSpeech"],"mappings":"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"}
+{"version":3,"file":"use-dictation.cjs","sources":["../../src/dictation/use-dictation.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react';\nimport { athenaDiagnostics } from '../diagnostics/athena-diagnostics';\nimport {\n  createWebSpeechDictationEngine,\n  DICTATION_ENGINE_ERROR_KINDS,\n  type DictationEngine,\n  type DictationEngineError,\n  type DictationEngineSession,\n} from './dictation-engine';\nimport {\n  DICTATION_STATUSES,\n  dictationReducer,\n  INITIAL_DICTATION_STATE,\n  joinSpeech,\n  spokenText,\n  type DictationStatus,\n  type DictationTranscript,\n} from './dictation-state';\n\nexport interface UseDictationOptions {\n  /**\n   * Speech engine. Defaults to the browser's Web Speech API; `AthenaChat`\n   * passes the record-then-transcribe engine from `useAthenaDictationEngine`.\n   */\n  engine?: DictationEngine;\n  /** BCP-47 language tag. Defaults to the document language, else `en-US`. */\n  lang?: string;\n  /**\n   * Open the microphone through `getUserMedia` so callers get a `stream` for\n   * a waveform. Web Speech opens its own capture; this second capture is\n   * what the level meter reads. Defaults to true.\n   */\n  captureStream?: boolean;\n  /**\n   * The engine ended on its own (silence window, recognizer timeout) while\n   * listening, without `stop()` or `cancel()`. Receives the spoken text so\n   * the words are not lost; the composer puts them into the draft.\n   */\n  onAutoEnd?: (spoken: string) => void;\n}\n\nexport interface DictationStopResult {\n  /** Spoken text (final plus interim tail) gathered before the engine closed. */\n  text: string;\n  /**\n   * The engine error reported during this session, if any. When set the\n   * transcript may be incomplete: a recorded engine whose upload failed has no\n   * words to hand over, so callers should not send the draft as if it were.\n   */\n  error: DictationEngineError | null;\n}\n\nexport interface DictationController {\n  status: DictationStatus;\n  /** True while starting, listening or stopping. */\n  isActive: boolean;\n  transcript: DictationTranscript;\n  /** `final` plus the interim tail, ready to hand to the composer. */\n  text: string;\n  error: DictationEngineError | null;\n  /** The microphone stream while active (for a waveform), else null. */\n  stream: MediaStream | null;\n  /** Whether the engine can run here. Hide the control when false. */\n  isSupported: boolean;\n  /** The engine in use (for its `stoppingLabel` and diagnostics). */\n  engine: DictationEngine;\n  start: () => void;\n  /**\n   * Finish recording. Resolves once the engine has flushed (bounded wait), so\n   * trailing words are not lost, with the spoken text and any error raised\n   * along the way.\n   */\n  stop: () => Promise<DictationStopResult>;\n  /** Discard the session and its transcript. */\n  cancel: () => void;\n}\n\n/** How long `stop()` waits for a live engine's final flush before giving up. */\nconst DEFAULT_STOP_FLUSH_TIMEOUT_MS = 1500;\n\ntype StopResolver = (result: DictationStopResult) => void;\n\nconst EMPTY_TRANSCRIPT: DictationTranscript = { final: '', interim: '' };\n\nfunction documentLanguage(): string {\n  if (typeof document !== 'undefined' && document.documentElement.lang) {\n    return document.documentElement.lang;\n  }\n  if (typeof navigator !== 'undefined' && navigator.language) return navigator.language;\n  return 'en-US';\n}\n\nasync function openMicrophone(): Promise<MediaStream | null> {\n  if (typeof navigator === 'undefined' || !navigator.mediaDevices?.getUserMedia) return null;\n  return navigator.mediaDevices.getUserMedia({ audio: true });\n}\n\nfunction releaseStream(stream: MediaStream | null): void {\n  if (!stream) return;\n  for (const track of stream.getTracks()) track.stop();\n}\n\n/**\n * Drive a dictation session: microphone, speech engine, and the transcript\n * state machine. The composer renders the waveform from `stream` and the\n * live caption from `transcript`; on `stop()` it appends `text` to the draft.\n */\nexport function useDictation(options: UseDictationOptions = {}): DictationController {\n  const engine = useMemo(() => options.engine ?? createWebSpeechDictationEngine(), [options.engine]);\n  const { lang, captureStream = true, onAutoEnd } = options;\n  const [state, dispatch] = useReducer(dictationReducer, INITIAL_DICTATION_STATE);\n  const [stream, setStream] = useState<MediaStream | null>(null);\n  const [isSupported, setIsSupported] = useState(false);\n\n  const sessionRef = useRef<DictationEngineSession | null>(null);\n  const streamRef = useRef<MediaStream | null>(null);\n  const stateRef = useRef(state);\n  stateRef.current = state;\n  // The authoritative transcript, updated synchronously as the engine reports\n  // it. The reducer's copy renders the caption; this one is what `stop()` and\n  // `onAutoEnd` hand over, so an engine that flushes its last words and ends\n  // in the same tick — before React has rendered — loses nothing.\n  const transcriptRef = useRef<DictationTranscript>(EMPTY_TRANSCRIPT);\n  const onAutoEndRef = useRef(onAutoEnd);\n  onAutoEndRef.current = onAutoEnd;\n  // stop() callers waiting for the engine's final flush.\n  const stopWaitersRef = useRef<StopResolver[]>([]);\n  // Last engine error of the current session, handed to stop() callers\n  // synchronously (the reducer's copy may not have rendered yet).\n  const sessionErrorRef = useRef<DictationEngineError | null>(null);\n  // Distinguishes a fresh session from the callbacks of a torn-down one.\n  const generationRef = useRef(0);\n\n  useEffect(() => {\n    setIsSupported(engine.isSupported());\n  }, [engine]);\n\n  const settleWaiters = useCallback((spoken: string) => {\n    const waiters = stopWaitersRef.current;\n    stopWaitersRef.current = [];\n    const result: DictationStopResult = { text: spoken, error: sessionErrorRef.current };\n    for (const resolve of waiters) resolve(result);\n  }, []);\n\n  const releaseSession = useCallback(() => {\n    sessionRef.current = null;\n    releaseStream(streamRef.current);\n    streamRef.current = null;\n    setStream(null);\n  }, []);\n\n  const teardown = useCallback(() => {\n    generationRef.current += 1;\n    sessionRef.current?.abort();\n    releaseSession();\n    transcriptRef.current = EMPTY_TRANSCRIPT;\n    settleWaiters('');\n  }, [releaseSession, settleWaiters]);\n\n  const reportEngineError = useCallback(\n    (engineError: DictationEngineError) => {\n      athenaDiagnostics.emit('composer.dictation', {\n        level: 'warn',\n        data: { phase: 'error', engine: engine.id, kind: engineError.kind },\n      });\n      sessionErrorRef.current = engineError;\n      dispatch({ type: 'error', error: engineError });\n    },\n    [engine.id],\n  );\n\n  const start = useCallback(() => {\n    if (sessionRef.current) return;\n    const generation = generationRef.current + 1;\n    generationRef.current = generation;\n    transcriptRef.current = EMPTY_TRANSCRIPT;\n    sessionErrorRef.current = null;\n    dispatch({ type: 'start' });\n    athenaDiagnostics.emit('composer.dictation', {\n      level: 'debug',\n      data: { phase: 'start', engine: engine.id },\n    });\n\n    const run = async () => {\n      let microphone: MediaStream | null = null;\n      if (captureStream) {\n        try {\n          microphone = await openMicrophone();\n        } catch (error) {\n          if (generationRef.current !== generation) {\n            releaseStream(microphone);\n            return;\n          }\n          dispatch({\n            type: 'error',\n            error: {\n              kind: DICTATION_ENGINE_ERROR_KINDS.permission,\n              message:\n                error instanceof DOMException && error.name === 'NotFoundError'\n                  ? 'No microphone was found.'\n                  : 'Microphone access was denied. Allow the microphone for this site and try again.',\n            },\n          });\n          return;\n        }\n      }\n      if (generationRef.current !== generation) {\n        releaseStream(microphone);\n        return;\n      }\n      streamRef.current = microphone;\n      setStream(microphone);\n\n      // An engine may fail synchronously inside start() (Web Speech throws\n      // when recognition.start() is refused) and run onError/onEnd before we\n      // hold the session. Those callbacks flip this flag so a dead session is\n      // never stored, which would make every later mic click return early.\n      let terminated = false;\n      const endSession = () => {\n        terminated = true;\n        const current = stateRef.current;\n        const spoken = spokenText(transcriptRef.current);\n        // No stop() is waiting: the engine gave up on its own. Hand the\n        // words over so they land in the draft instead of vanishing.\n        const endedOnItsOwn =\n          stopWaitersRef.current.length === 0 && current.status === DICTATION_STATUSES.listening;\n        // The reducer keeps an error status through 'ended', so an error\n        // reported just before the engine closed stays on screen.\n        dispatch({ type: 'ended' });\n        releaseSession();\n        settleWaiters(spoken);\n        if (endedOnItsOwn) onAutoEndRef.current?.(spoken);\n      };\n      let session: DictationEngineSession;\n      try {\n        session = engine.start({\n          stream: microphone,\n          lang: lang ?? documentLanguage(),\n          callbacks: {\n            onTranscript: (update) => {\n              if (generationRef.current !== generation) return;\n              transcriptRef.current = {\n                final: joinSpeech(transcriptRef.current.final, update.final),\n                interim: update.interim,\n              };\n              dispatch({ type: 'transcript', update });\n            },\n            onError: (engineError) => {\n              if (generationRef.current !== generation) return;\n              // A silence timeout is the engine giving up politely; keep the\n              // words we have instead of showing an error.\n              if (engineError.kind === DICTATION_ENGINE_ERROR_KINDS.noSpeech) return;\n              reportEngineError(engineError);\n            },\n            onEnd: () => {\n              if (generationRef.current !== generation) return;\n              endSession();\n            },\n          },\n        });\n      } catch (error) {\n        // A relay engine that cannot build its session must not strand the\n        // microphone or leave the composer in `starting`.\n        releaseSession();\n        reportEngineError({\n          kind: DICTATION_ENGINE_ERROR_KINDS.connection,\n          message: error instanceof Error ? error.message : 'Dictation could not start.',\n        });\n        return;\n      }\n      if (terminated) return;\n      sessionRef.current = session;\n      dispatch({ type: 'listening' });\n    };\n    void run();\n  }, [captureStream, engine, lang, releaseSession, reportEngineError, settleWaiters]);\n\n  const stop = useCallback((): Promise<DictationStopResult> => {\n    const session = sessionRef.current;\n    if (!session) {\n      // Stopped while the microphone prompt was still open: nothing was heard\n      // yet, and the pending start must not bring the engine up afterwards.\n      if (stateRef.current.status === DICTATION_STATUSES.starting) {\n        teardown();\n        dispatch({ type: 'cancel' });\n        return Promise.resolve({ text: '', error: null });\n      }\n      return Promise.resolve({ text: spokenText(transcriptRef.current), error: sessionErrorRef.current });\n    }\n    dispatch({ type: 'stop' });\n    const flushed = new Promise<DictationStopResult>((resolve) => {\n      stopWaitersRef.current.push(resolve);\n      window.setTimeout(() => {\n        // Bounded wait: a recognizer that never fires onend must not hold the\n        // composer hostage. Force the session closed and hand over what was\n        // heard so far. An engine that had nothing to show yet (a recorded\n        // clip still transcribing) surfaces that as an error rather than\n        // passing off silence as the result.\n        if (sessionRef.current === session) {\n          // Report before abort(): an engine that ends synchronously on\n          // abort settles the waiters, and they must see this error.\n          if (!spokenText(transcriptRef.current)) {\n            reportEngineError({\n              kind: DICTATION_ENGINE_ERROR_KINDS.connection,\n              message: 'Transcription timed out. Try again.',\n            });\n          }\n          session.abort();\n          dispatch({ type: 'ended' });\n          releaseSession();\n          settleWaiters(spokenText(transcriptRef.current));\n        }\n      }, engine.flushTimeoutMs ?? DEFAULT_STOP_FLUSH_TIMEOUT_MS);\n    });\n    session.stop();\n    return flushed;\n  }, [engine.flushTimeoutMs, releaseSession, reportEngineError, settleWaiters, teardown]);\n\n  const cancel = useCallback(() => {\n    teardown();\n    dispatch({ type: 'cancel' });\n  }, [teardown]);\n\n  // Release the microphone with the component.\n  useEffect(() => () => teardown(), [teardown]);\n\n  const isActive =\n    state.status === DICTATION_STATUSES.starting ||\n    state.status === DICTATION_STATUSES.listening ||\n    state.status === DICTATION_STATUSES.stopping;\n\n  return {\n    status: state.status,\n    isActive,\n    transcript: state.transcript,\n    text: spokenText(state.transcript),\n    error: state.error,\n    stream,\n    isSupported,\n    engine,\n    start,\n    stop,\n    cancel,\n  };\n}\n"],"names":["useMemo","createWebSpeechDictationEngine","useReducer","dictationReducer","INITIAL_DICTATION_STATE","useState","useRef","useEffect","useCallback","athenaDiagnostics","DICTATION_ENGINE_ERROR_KINDS","spokenText","DICTATION_STATUSES","joinSpeech"],"mappings":"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"}

package/dist/dictation/use-dictation.d.ts

@@ -1,7 +1,10 @@
 import { type DictationEngine, type DictationEngineError } from './dictation-engine';
 import { type DictationStatus, type DictationTranscript } from './dictation-state';
 export interface UseDictationOptions {
-    /** Speech engine. Defaults to the browser's Web Speech API. */
+    /**
+     * Speech engine. Defaults to the browser's Web Speech API; `AthenaChat`
+     * passes the record-then-transcribe engine from `useAthenaDictationEngine`.
+     */
     engine?: DictationEngine;
     /** BCP-47 language tag. Defaults to the document language, else `en-US`. */
     lang?: string;
@@ -18,6 +21,16 @@ export interface UseDictationOptions {
      */
     onAutoEnd?: (spoken: string) => void;
 }
+export interface DictationStopResult {
+    /** Spoken text (final plus interim tail) gathered before the engine closed. */
+    text: string;
+    /**
+     * The engine error reported during this session, if any. When set the
+     * transcript may be incomplete: a recorded engine whose upload failed has no
+     * words to hand over, so callers should not send the draft as if it were.
+     */
+    error: DictationEngineError | null;
+}
 export interface DictationController {
     status: DictationStatus;
     /** True while starting, listening or stopping. */
@@ -30,12 +43,15 @@ export interface DictationController {
     stream: MediaStream | null;
     /** Whether the engine can run here. Hide the control when false. */
     isSupported: boolean;
+    /** The engine in use (for its `stoppingLabel` and diagnostics). */
+    engine: DictationEngine;
     start: () => void;
     /**
-     * Finish recording. Resolves with the spoken text once the engine has
-     * flushed (bounded wait), so trailing words are not lost.
+     * Finish recording. Resolves once the engine has flushed (bounded wait), so
+     * trailing words are not lost, with the spoken text and any error raised
+     * along the way.
      */
-    stop: () => Promise<string>;
+    stop: () => Promise<DictationStopResult>;
     /** Discard the session and its transcript. */
     cancel: () => void;
 }