@burdenoff/website-sdk 2026.1104.3 → 2026.1105.1

package/dist/avatar-mic/index.d.mts

@@ -0,0 +1,193 @@
+/** What the worklet posts for each frame. */
+interface CaptureFrameMessage {
+    /** s16le mono 16 kHz, `CAPTURE_FRAME_SAMPLES` samples. */
+    pcm: ArrayBuffer;
+    /** Microphone level over the frame, dBFS. */
+    rmsDb: number;
+    /** Reference-bus level over the same samples, dBFS (about -90 when silent, as it always is here). */
+    refDb: number;
+    /** Zero crossings per sample. */
+    zcr: number;
+    /** AudioContext time at the end of the frame, seconds. */
+    ctxTime: number;
+    seq: number;
+}
+
+/**
+ * BOFF-9797 (Stage C). The Avatar tab's own microphone capture: `getUserMedia`, through the capture worklet
+ * (`capture-worklet.ts`), into 16 kHz PCM frames.
+ *
+ * **Ported, not shared.** From `src/shared/assistant/voice/handsfree/micCapture.ts` in Algoshred/fe-libs at the
+ * commit `capture-worklet.ts` names (`CAPTURE_WORKLET_PORTED_FROM`; blob `8486c630`), with one difference: fe-libs
+ * routes everything its assistant plays into the worklet's second input (its playback reference, for barge-in), and the
+ * website plays nothing through this context (the avatar's voice is the room's own audio element, and the mic is
+ * offered only while no session plays), so no reference bus is made and the worklet has the microphone as its only
+ * input. `looksLikeHeadset`, which only fe-libs' barge-in reads, is not ported. `capture-worklet.test.ts` holds the
+ * parity tests.
+ *
+ * It opens `getUserMedia` with echo cancellation, noise suppression and auto gain on. Constraints are plain `true`,
+ * never `{ exact }`: `exact` throws OverconstrainedError on handsets that cannot honour one. The settings the browser
+ * actually applied are read back (`track.getSettings()`), because some Android handsets report `true` and apply nothing.
+ *
+ * `stop()` stops the track (the browser's recording indicator goes), disconnects the graph and closes the context. The
+ * caller does that the moment a press ends, whichever way it ends; `pagehide` does it too, whatever the caller does.
+ */
+
+interface MicCaptureHandle {
+    context: AudioContext;
+    micSource: MediaStreamAudioSourceNode;
+    track: MediaStreamTrack;
+    /** What the browser reports it applied. */
+    settings: MediaTrackSettings;
+    /** Stop everything and release the microphone. Safe to call more than once. */
+    stop(): void;
+}
+
+/** What the mic needs of a WebSocket; {@link openBrowserSocket} adapts the browser's. (fe-libs' seam.) */
+interface SocketLike {
+    readonly readyState: number;
+    send(data: string | ArrayBufferLike | ArrayBufferView): void;
+    close(code?: number): void;
+    listen(handlers: SocketHandlers): void;
+}
+interface SocketHandlers {
+    open(): void;
+    message(data: unknown): void;
+    close(code: number): void;
+    error(): void;
+}
+
+/**
+ * BOFF-9797 (Stage C). The shapes the Avatar tab's mic shares with the live avatar's view.
+ *
+ * Types only, on purpose: the view (`explore-avatar-mic.tsx`, in the view's chunk) imports this file for its types and
+ * nothing else, so the view never carries the mic's code. It reaches the mic's chunk (`dist/avatar-mic/`) only through
+ * a dynamic `import()`, the first time a visitor uses the mic.
+ */
+/**
+ * What an availability answer offered the mic (`stt`, while the gateway's website speech-to-text is on): the token for
+ * one stream, when the gateway says it expires, and when this browser received it, on its own clock.
+ */
+interface AvatarMicOffer {
+    token: string;
+    /** Epoch milliseconds, on the gateway's clock. */
+    expiresAt: number;
+    /** Epoch milliseconds, on this browser's clock. */
+    receivedAt: number;
+}
+/**
+ * Why a press did not give text:
+ *
+ * - `denied`: the microphone was refused (the visitor, the browser or the page's permissions);
+ * - `unsupported`: this browser cannot capture here, or has no microphone to use;
+ * - `unavailable`: the server will not take a stream from this page now: no offer, an offer it refuses twice, its mic
+ *   notice is another version than this SDK's, or the website avatar is paused;
+ * - `limit`: a limit on voice questions is reached (the visitor's, the network's, or every visitor's together);
+ * - `busy`: the stream is busy, or the server's counters cannot be read: try again in a moment;
+ * - `failed`: anything else (the connection lost, availability or the speech service not answering, no answer in
+ *   time).
+ */
+type AvatarMicFailure = "denied" | "unsupported" | "unavailable" | "limit" | "busy" | "failed";
+/**
+ * One press of the mic, as the view shows it. `epoch` names the press: a new press has a new one, and what an older one
+ * reports is never shown for a newer one.
+ *
+ * - `starting`: the microphone opening (the browser's permission prompt included) and the stream connecting;
+ * - `listening`: recording, since `startedAt` (this browser's clock), with what has been heard so far (the final text
+ *   and, after it, the words still being recognised);
+ * - `finishing`: the recording has stopped (a tap, or the limit: `limit`), and the last of the text is on its way;
+ * - `done`: the text, final (empty when no words were heard);
+ * - `failed`: no text, and why (with any final text heard before it failed, which the view does not use).
+ */
+type AvatarMicState = {
+    name: "idle";
+} | {
+    name: "starting";
+    epoch: number;
+} | {
+    name: "listening";
+    epoch: number;
+    startedAt: number;
+    text: string;
+} | {
+    name: "finishing";
+    epoch: number;
+    text: string;
+    limit: boolean;
+} | {
+    name: "done";
+    epoch: number;
+    text: string;
+    limit: boolean;
+} | {
+    name: "failed";
+    epoch: number;
+    reason: AvatarMicFailure;
+    text: string;
+};
+interface AvatarMicOptions {
+    /** `avatarApiBase` of the SDK's gateway: the stream is `<base>/stt/stream`. */
+    base: string;
+    /** The mic notice version the visitor saw: every press names it, and the server takes only its own. */
+    notice: string;
+    /** The latest offer the view holds, or null. */
+    offer: () => AvatarMicOffer | null;
+    /**
+     * Ask availability again for a new offer: null when the answer carries none (the press is `unavailable`); rejects when
+     * there is no answer at all (the press is `failed`, and the mic is still offered).
+     */
+    refreshOffer: () => Promise<AvatarMicOffer | null>;
+    /** Every change of the press's state. */
+    onState: (state: AvatarMicState) => void;
+}
+/** One view's mic: one press at a time. */
+interface AvatarMic {
+    /** A new press. One still finishing is cancelled first (superseded); one starting or listening is left alone. */
+    start(): void;
+    /** Stop recording and wait for the final text (the visitor's tap). A press still starting is cancelled instead. */
+    stop(): void;
+    /** Call off whatever is under way, release the microphone, and report nothing more of it: back to `idle`. */
+    cancel(): void;
+    /** The press as it stands. */
+    state(): AvatarMicState;
+}
+/** What the mic's chunk (`dist/avatar-mic/`) exports. */
+interface AvatarMicModule {
+    createAvatarMic: (options: AvatarMicOptions) => AvatarMic;
+}
+
+/**
+ * BOFF-9797 (Stage C). The Avatar tab's mic, one press at a time: tap to start, tap to stop, thirty seconds at most.
+ *
+ * A press, in order:
+ *
+ * 1. **The microphone opens** (`startMicCapture`: the browser's permission prompt the first time). Meanwhile the offer
+ *    is made ready: the token the last availability answer carried while it is fresh, else a new one, asked for now.
+ * 2. **The stream connects**, once the microphone is live (never while a permission prompt is up, so no stream is held
+ *    open for a visitor who has not decided): `boff.web-stt.v1` and `offer.<token>`. A refused upgrade (4401) asks
+ *    availability again and tries once more, never twice.
+ * 3. **The server says it is ready**: the press's `config` (its utterance id, its epoch, `en-IN`, and the mic notice the
+ *    visitor saw), then up to {@link PRE_ROLL_MS} of what the microphone heard while the stream connected, then every
+ *    frame as it comes. Listening, from here: what has been heard so far is reported as it is recognised.
+ * 4. **The recording stops**: the visitor's tap, or {@link MAX_PRESS_MS} (counted both on the clock and in audio sent),
+ *    or the speech service's own limit. The microphone is released at once; `end`, and the last of the text.
+ * 5. **The text is final** (`done`): reported once, for the view to put in the box. Nothing is ever sent for the
+ *    visitor: the text goes nowhere else.
+ *
+ * **Released on every way out.** The microphone's track is stopped the moment the recording stops, and also when the
+ * press fails, is cancelled (`cancel()`: the view going, the page hidden, the Chat tab) or superseded (a new press while
+ * one is still finishing: `cancel` for the old one, so it stops being paid for, and its text is never reported). A
+ * microphone that opens after its press has gone is closed as it opens. The stream is closed whenever no press needs
+ * it: one connection serves a press and the press that supersedes it, and no other.
+ */
+
+/** What a press needs from the browser. The browser's own by default; a test hands in fakes. */
+interface AvatarMicSeams {
+    createSocket: (url: string, protocols: string[]) => SocketLike;
+    startCapture: (onFrame: (frame: CaptureFrameMessage) => void) => Promise<Pick<MicCaptureHandle, "stop">>;
+    newUtteranceId: () => string | null;
+}
+/** The mic of one Avatar tab. See the file's comment for what a press does. */
+declare function createAvatarMic(options: AvatarMicOptions, seams?: Partial<AvatarMicSeams>): AvatarMic;
+
+export { type AvatarMic, type AvatarMicFailure, type AvatarMicModule, type AvatarMicOffer, type AvatarMicOptions, type AvatarMicState, createAvatarMic };

package/dist/avatar-mic/index.d.ts

@@ -0,0 +1,193 @@
+/** What the worklet posts for each frame. */
+interface CaptureFrameMessage {
+    /** s16le mono 16 kHz, `CAPTURE_FRAME_SAMPLES` samples. */
+    pcm: ArrayBuffer;
+    /** Microphone level over the frame, dBFS. */
+    rmsDb: number;
+    /** Reference-bus level over the same samples, dBFS (about -90 when silent, as it always is here). */
+    refDb: number;
+    /** Zero crossings per sample. */
+    zcr: number;
+    /** AudioContext time at the end of the frame, seconds. */
+    ctxTime: number;
+    seq: number;
+}
+
+/**
+ * BOFF-9797 (Stage C). The Avatar tab's own microphone capture: `getUserMedia`, through the capture worklet
+ * (`capture-worklet.ts`), into 16 kHz PCM frames.
+ *
+ * **Ported, not shared.** From `src/shared/assistant/voice/handsfree/micCapture.ts` in Algoshred/fe-libs at the
+ * commit `capture-worklet.ts` names (`CAPTURE_WORKLET_PORTED_FROM`; blob `8486c630`), with one difference: fe-libs
+ * routes everything its assistant plays into the worklet's second input (its playback reference, for barge-in), and the
+ * website plays nothing through this context (the avatar's voice is the room's own audio element, and the mic is
+ * offered only while no session plays), so no reference bus is made and the worklet has the microphone as its only
+ * input. `looksLikeHeadset`, which only fe-libs' barge-in reads, is not ported. `capture-worklet.test.ts` holds the
+ * parity tests.
+ *
+ * It opens `getUserMedia` with echo cancellation, noise suppression and auto gain on. Constraints are plain `true`,
+ * never `{ exact }`: `exact` throws OverconstrainedError on handsets that cannot honour one. The settings the browser
+ * actually applied are read back (`track.getSettings()`), because some Android handsets report `true` and apply nothing.
+ *
+ * `stop()` stops the track (the browser's recording indicator goes), disconnects the graph and closes the context. The
+ * caller does that the moment a press ends, whichever way it ends; `pagehide` does it too, whatever the caller does.
+ */
+
+interface MicCaptureHandle {
+    context: AudioContext;
+    micSource: MediaStreamAudioSourceNode;
+    track: MediaStreamTrack;
+    /** What the browser reports it applied. */
+    settings: MediaTrackSettings;
+    /** Stop everything and release the microphone. Safe to call more than once. */
+    stop(): void;
+}
+
+/** What the mic needs of a WebSocket; {@link openBrowserSocket} adapts the browser's. (fe-libs' seam.) */
+interface SocketLike {
+    readonly readyState: number;
+    send(data: string | ArrayBufferLike | ArrayBufferView): void;
+    close(code?: number): void;
+    listen(handlers: SocketHandlers): void;
+}
+interface SocketHandlers {
+    open(): void;
+    message(data: unknown): void;
+    close(code: number): void;
+    error(): void;
+}
+
+/**
+ * BOFF-9797 (Stage C). The shapes the Avatar tab's mic shares with the live avatar's view.
+ *
+ * Types only, on purpose: the view (`explore-avatar-mic.tsx`, in the view's chunk) imports this file for its types and
+ * nothing else, so the view never carries the mic's code. It reaches the mic's chunk (`dist/avatar-mic/`) only through
+ * a dynamic `import()`, the first time a visitor uses the mic.
+ */
+/**
+ * What an availability answer offered the mic (`stt`, while the gateway's website speech-to-text is on): the token for
+ * one stream, when the gateway says it expires, and when this browser received it, on its own clock.
+ */
+interface AvatarMicOffer {
+    token: string;
+    /** Epoch milliseconds, on the gateway's clock. */
+    expiresAt: number;
+    /** Epoch milliseconds, on this browser's clock. */
+    receivedAt: number;
+}
+/**
+ * Why a press did not give text:
+ *
+ * - `denied`: the microphone was refused (the visitor, the browser or the page's permissions);
+ * - `unsupported`: this browser cannot capture here, or has no microphone to use;
+ * - `unavailable`: the server will not take a stream from this page now: no offer, an offer it refuses twice, its mic
+ *   notice is another version than this SDK's, or the website avatar is paused;
+ * - `limit`: a limit on voice questions is reached (the visitor's, the network's, or every visitor's together);
+ * - `busy`: the stream is busy, or the server's counters cannot be read: try again in a moment;
+ * - `failed`: anything else (the connection lost, availability or the speech service not answering, no answer in
+ *   time).
+ */
+type AvatarMicFailure = "denied" | "unsupported" | "unavailable" | "limit" | "busy" | "failed";
+/**
+ * One press of the mic, as the view shows it. `epoch` names the press: a new press has a new one, and what an older one
+ * reports is never shown for a newer one.
+ *
+ * - `starting`: the microphone opening (the browser's permission prompt included) and the stream connecting;
+ * - `listening`: recording, since `startedAt` (this browser's clock), with what has been heard so far (the final text
+ *   and, after it, the words still being recognised);
+ * - `finishing`: the recording has stopped (a tap, or the limit: `limit`), and the last of the text is on its way;
+ * - `done`: the text, final (empty when no words were heard);
+ * - `failed`: no text, and why (with any final text heard before it failed, which the view does not use).
+ */
+type AvatarMicState = {
+    name: "idle";
+} | {
+    name: "starting";
+    epoch: number;
+} | {
+    name: "listening";
+    epoch: number;
+    startedAt: number;
+    text: string;
+} | {
+    name: "finishing";
+    epoch: number;
+    text: string;
+    limit: boolean;
+} | {
+    name: "done";
+    epoch: number;
+    text: string;
+    limit: boolean;
+} | {
+    name: "failed";
+    epoch: number;
+    reason: AvatarMicFailure;
+    text: string;
+};
+interface AvatarMicOptions {
+    /** `avatarApiBase` of the SDK's gateway: the stream is `<base>/stt/stream`. */
+    base: string;
+    /** The mic notice version the visitor saw: every press names it, and the server takes only its own. */
+    notice: string;
+    /** The latest offer the view holds, or null. */
+    offer: () => AvatarMicOffer | null;
+    /**
+     * Ask availability again for a new offer: null when the answer carries none (the press is `unavailable`); rejects when
+     * there is no answer at all (the press is `failed`, and the mic is still offered).
+     */
+    refreshOffer: () => Promise<AvatarMicOffer | null>;
+    /** Every change of the press's state. */
+    onState: (state: AvatarMicState) => void;
+}
+/** One view's mic: one press at a time. */
+interface AvatarMic {
+    /** A new press. One still finishing is cancelled first (superseded); one starting or listening is left alone. */
+    start(): void;
+    /** Stop recording and wait for the final text (the visitor's tap). A press still starting is cancelled instead. */
+    stop(): void;
+    /** Call off whatever is under way, release the microphone, and report nothing more of it: back to `idle`. */
+    cancel(): void;
+    /** The press as it stands. */
+    state(): AvatarMicState;
+}
+/** What the mic's chunk (`dist/avatar-mic/`) exports. */
+interface AvatarMicModule {
+    createAvatarMic: (options: AvatarMicOptions) => AvatarMic;
+}
+
+/**
+ * BOFF-9797 (Stage C). The Avatar tab's mic, one press at a time: tap to start, tap to stop, thirty seconds at most.
+ *
+ * A press, in order:
+ *
+ * 1. **The microphone opens** (`startMicCapture`: the browser's permission prompt the first time). Meanwhile the offer
+ *    is made ready: the token the last availability answer carried while it is fresh, else a new one, asked for now.
+ * 2. **The stream connects**, once the microphone is live (never while a permission prompt is up, so no stream is held
+ *    open for a visitor who has not decided): `boff.web-stt.v1` and `offer.<token>`. A refused upgrade (4401) asks
+ *    availability again and tries once more, never twice.
+ * 3. **The server says it is ready**: the press's `config` (its utterance id, its epoch, `en-IN`, and the mic notice the
+ *    visitor saw), then up to {@link PRE_ROLL_MS} of what the microphone heard while the stream connected, then every
+ *    frame as it comes. Listening, from here: what has been heard so far is reported as it is recognised.
+ * 4. **The recording stops**: the visitor's tap, or {@link MAX_PRESS_MS} (counted both on the clock and in audio sent),
+ *    or the speech service's own limit. The microphone is released at once; `end`, and the last of the text.
+ * 5. **The text is final** (`done`): reported once, for the view to put in the box. Nothing is ever sent for the
+ *    visitor: the text goes nowhere else.
+ *
+ * **Released on every way out.** The microphone's track is stopped the moment the recording stops, and also when the
+ * press fails, is cancelled (`cancel()`: the view going, the page hidden, the Chat tab) or superseded (a new press while
+ * one is still finishing: `cancel` for the old one, so it stops being paid for, and its text is never reported). A
+ * microphone that opens after its press has gone is closed as it opens. The stream is closed whenever no press needs
+ * it: one connection serves a press and the press that supersedes it, and no other.
+ */
+
+/** What a press needs from the browser. The browser's own by default; a test hands in fakes. */
+interface AvatarMicSeams {
+    createSocket: (url: string, protocols: string[]) => SocketLike;
+    startCapture: (onFrame: (frame: CaptureFrameMessage) => void) => Promise<Pick<MicCaptureHandle, "stop">>;
+    newUtteranceId: () => string | null;
+}
+/** The mic of one Avatar tab. See the file's comment for what a press does. */
+declare function createAvatarMic(options: AvatarMicOptions, seams?: Partial<AvatarMicSeams>): AvatarMic;
+
+export { type AvatarMic, type AvatarMicFailure, type AvatarMicModule, type AvatarMicOffer, type AvatarMicOptions, type AvatarMicState, createAvatarMic };