@burdenoff/website-sdk 2026.1105.3 → 2026.1106.1

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

@@ -30,6 +30,19 @@ interface AvatarMicOffer {
  *   time).
  */
 type AvatarMicFailure = "denied" | "unsupported" | "unavailable" | "limit" | "busy" | "failed";
+/**
+ * Why a press of the voice conversation ended with text, or with none (Stage C2, a press with an
+ * {@link AvatarMicEndpoint} only):
+ *
+ * - `pause`: the visitor stopped speaking for the pause, after a question: the one way a question is sent by itself;
+ * - `tap`: the visitor stopped it;
+ * - `limit`: the question reached the longest one, counted from its first word;
+ * - `silence`: nothing that counts as speech was heard in the longest wait, or before the recognizer ended;
+ * - `failed`: the recognizer failed, or could no longer go on, after or before words.
+ *
+ * Only `pause` may be sent; every other one's words go into the box for the visitor, never sent.
+ */
+type AvatarMicDoneBy = "tap" | "pause" | "limit" | "silence" | "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.
@@ -40,6 +53,11 @@ type AvatarMicFailure = "denied" | "unsupported" | "unavailable" | "limit" | "bu
  * - `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).
+ *
+ * A press with an {@link AvatarMicEndpoint} (the voice conversation, Stage C2) says more, and only it: `listening`
+ * says whether what is heard counts as speech (`genuine`) and whether the visitor has paused (`pausing`); `done` says
+ * why it ended (`by`) and whether its words are the avatar's own voice (`echo`). A press without one reports exactly
+ * the shapes it did before.
  */
 type AvatarMicState = {
     name: "idle";
@@ -51,6 +69,10 @@ type AvatarMicState = {
     epoch: number;
     startedAt: number;
     text: string;
+    /** With an endpoint: the words heard are speech, not silence, sounds or a stall (`isGenuineSpeech`). */
+    genuine?: boolean;
+    /** With an endpoint: no new word for a moment, after speech ("Still listening — take your time"). */
+    pausing?: boolean;
 } | {
     name: "finishing";
     epoch: number;
@@ -61,6 +83,10 @@ type AvatarMicState = {
     epoch: number;
     text: string;
     limit: boolean;
+    /** With an endpoint: why the press ended. */
+    by?: AvatarMicDoneBy;
+    /** With an endpoint: the words are the avatar's own answer, heard back through the microphone. */
+    echo?: boolean;
 } | {
     name: "failed";
     epoch: number;
@@ -103,10 +129,36 @@ interface BrowserAvatarMicOptions {
     lang: string;
     /** Tried once, in the same press, when the browser does not recognise `lang` (`en-US`). */
     fallbackLang: string;
-    /** The longest press, from the moment the browser starts listening: thirty seconds. */
+    /**
+     * The longest press, from the moment the browser starts listening: thirty seconds. With an `endpoint`, the longest
+     * wait for a question to start, and the longest question, from its first word.
+     */
     maxPressMs: number;
     /** Every change of the press's state. */
     onState: (state: AvatarMicState) => void;
+    /**
+     * The voice conversation (Stage C2): every press ends itself once the visitor has paused after a question (see
+     * {@link AvatarMicEndpoint}). Without it, a press is exactly the editable one: tap to start, tap to stop.
+     */
+    endpoint?: AvatarMicEndpoint;
+}
+/**
+ * How a press of the voice conversation ends itself (Stage C2): `done` with `by: "pause"` once what is heard is speech
+ * and no word of it has changed for `pauseMs` (twice that for a sentence left open), never sooner than
+ * `BROWSER_PAUSE_AFTER_START_MS` after its recognizer (re)started, and never between two recognizers.
+ */
+interface AvatarMicEndpoint {
+    /**
+     * The pause that ends a question, in milliseconds: the server's `mic.pauseMs` (2000 to 2500, read strictly by the
+     * view's API). Read within those bounds whatever is passed.
+     */
+    pauseMs: number;
+    /**
+     * The words of the answer the avatar has just read (its captions), for the echo check, read as the press ends; null
+     * when there is none, or when the check is not for this press (the view's hook checks only the presses the
+     * conversation starts by itself).
+     */
+    echoOf: () => string | null;
 }
 /** What the mic's chunk (`dist/avatar-mic/`) exports. */
 interface AvatarMicModule {
@@ -114,64 +166,6 @@ interface AvatarMicModule {
     createBrowserAvatarMic: (options: BrowserAvatarMicOptions) => AvatarMic;
 }
 
-/**
- * BOFF-9797 (Stage C, the browser's own recognizer). The Avatar tab's mic through the browser's speech recognition
- * (`SpeechRecognition`, `webkitSpeechRecognition`), as the product assistant listens: tap to start, tap to stop,
- * thirty seconds at most. The browser turns the voice into text (its own speech service: Google's for Chrome, Apple's
- * for Safari, Microsoft's for Edge); this module never sends anything anywhere, and the text goes only to the view,
- * which puts it in the box for the visitor to check and Send.
- *
- * The phones' quirks are the ones the SDK's Chat dictation (`src/hooks/use-speech-input.ts`, live on the sites) met
- * there, handled the same way: the permission prompt raised by opening the microphone first, a pause before the
- * recognizer opens its own, one quiet retry after a fresh grant, and one utterance per recognizer on a touch device.
- *
- * A press, in order:
- *
- * 1. **The tap** (`start`, called inside the tap where the view can). Where the browser reports the microphone granted
- *    (or reports nothing, and a press on this page has had it), the recognizer starts inside the tap. Otherwise the
- *    microphone is opened and released at once, inside the tap (`getUserMedia`): that is what raises the browser's
- *    permission prompt on phones, where a recognizer's own `start()` is refused (`not-allowed`) without asking anyone.
- *    Nothing of that capture is kept, played or sent. Once it is granted, the recognizer starts
- *    {@link BROWSER_PRIME_SETTLE_MS} later, so it does not race the released capture for the microphone. The
- *    recognizer: interim results, one alternative, the press's language, and `continuous`, except on a touch device,
- *    whose recognizer hears one utterance whatever it is asked (and, asked for more, fails sooner). A press still
- *    finishing is superseded (aborted, its text never reported; the view lets no tap through meanwhile).
- * 2. **The browser starts listening** (`onstart`, the honest signal: never while a prompt is up): `listening`, and the
- *    press's limit counts from here ({@link BrowserAvatarMicOptions.maxPressMs}).
- * 3. **Words as they are recognised**: rebuilt from the whole result list each time (finals, then the words still
- *    being recognised), so a result sent again never doubles up, and a final that repeats the one before it with more
- *    words replaces it (Android's cumulative finals).
- * 4. **The engine ending by itself** (a pause, a phone's one utterance, a quiet spell's `no-speech`) does NOT end the
- *    press: tap to stop holds on every platform. A new recognizer takes over in the same press, its words after the
- *    ones before: at once on a computer, after {@link BROWSER_TOUCH_RESTART_MS} on a touch device, and after
- *    {@link BROWSER_RESTART_COOLDOWN_MS} when one has just thrown on `start()` or, on a computer, ended as it began.
- *    Bounded against a recognizer that never listens: after {@link BROWSER_MAX_QUICK_ENDS} ends in a row as they
- *    began, or {@link BROWSER_MAX_RESTARTS} recognizers in all, the press gives what it has. Events of a recognizer that
- *    has been replaced are dropped.
- * 5. **The stop** (the visitor's tap, or the limit): `stop()`, not `abort()`, as browsers deliver the last words after
- *    it; up to {@link BROWSER_FINAL_WAIT_MS} for its end. A tap while it is still starting (the prompt included) calls
- *    the press off.
- * 6. **The text** (`done`): what was heard, final or not (an engine that never marks a result final, iOS Safari, still
- *    gives its words: the visitor checks them in the box anyway). Empty when nothing was heard.
- *
- * **Released on every way out.** `cancel()` (the view going, the page hidden, the Chat tab), a failure, a supersede and
- * the end of a press all detach the recognizer's handlers first and then `abort()` it, so the browser's recording
- * indicator goes and nothing it says later is reported. A microphone opened for the prompt is released as soon as it
- * opens, whether or not the press is still there.
- *
- * Errors. Opening the microphone for the prompt: refused (`NotAllowedError`, `SecurityError`) is `denied`; no
- * microphone (`NotFoundError`) is `unsupported`; anything else is `failed`. The recognizer's
- * (`SpeechRecognitionErrorEvent.error`): `not-allowed` or `service-not-allowed` while the microphone is confirmed for
- * the press (the browser reports it granted, or opening it just worked) is tried once more after
- * {@link BROWSER_GRANT_RETRY_MS}, quietly (Android refuses the first start after a fresh grant and takes the next), and
- * after that it is `unsupported`: the speech service refusing, not a permission the visitor can give. Unconfirmed,
- * `not-allowed` is `denied` (and the next tap asks the browser again) and `service-not-allowed` (iOS with Siri and
- * Dictation off, Edge's policy) is `unsupported`; `audio-capture` (no microphone) is `unsupported`;
- * `language-not-supported` tries the fallback language once, then `unsupported`; `network` is `failed`, and
- * `unsupported` the second time running on the page; `no-speech` is a quiet spell (a new recognizer); anything else is
- * `failed`. A failure once words were heard, whatever it is, gives those words instead (`done`).
- */
-
 /** One alternative of a recognition result: what the browser heard. */
 interface RecognitionAlternativeLike {
     readonly transcript: string;
@@ -315,4 +309,4 @@ interface AvatarMicSeams {
 /** 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, type BrowserAvatarMicOptions, createAvatarMic, createBrowserAvatarMic };
+export { type AvatarMic, type AvatarMicDoneBy, type AvatarMicEndpoint, type AvatarMicFailure, type AvatarMicModule, type AvatarMicOffer, type AvatarMicOptions, type AvatarMicState, type BrowserAvatarMicOptions, createAvatarMic, createBrowserAvatarMic };

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

@@ -30,6 +30,19 @@ interface AvatarMicOffer {
  *   time).
  */
 type AvatarMicFailure = "denied" | "unsupported" | "unavailable" | "limit" | "busy" | "failed";
+/**
+ * Why a press of the voice conversation ended with text, or with none (Stage C2, a press with an
+ * {@link AvatarMicEndpoint} only):
+ *
+ * - `pause`: the visitor stopped speaking for the pause, after a question: the one way a question is sent by itself;
+ * - `tap`: the visitor stopped it;
+ * - `limit`: the question reached the longest one, counted from its first word;
+ * - `silence`: nothing that counts as speech was heard in the longest wait, or before the recognizer ended;
+ * - `failed`: the recognizer failed, or could no longer go on, after or before words.
+ *
+ * Only `pause` may be sent; every other one's words go into the box for the visitor, never sent.
+ */
+type AvatarMicDoneBy = "tap" | "pause" | "limit" | "silence" | "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.
@@ -40,6 +53,11 @@ type AvatarMicFailure = "denied" | "unsupported" | "unavailable" | "limit" | "bu
  * - `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).
+ *
+ * A press with an {@link AvatarMicEndpoint} (the voice conversation, Stage C2) says more, and only it: `listening`
+ * says whether what is heard counts as speech (`genuine`) and whether the visitor has paused (`pausing`); `done` says
+ * why it ended (`by`) and whether its words are the avatar's own voice (`echo`). A press without one reports exactly
+ * the shapes it did before.
  */
 type AvatarMicState = {
     name: "idle";
@@ -51,6 +69,10 @@ type AvatarMicState = {
     epoch: number;
     startedAt: number;
     text: string;
+    /** With an endpoint: the words heard are speech, not silence, sounds or a stall (`isGenuineSpeech`). */
+    genuine?: boolean;
+    /** With an endpoint: no new word for a moment, after speech ("Still listening — take your time"). */
+    pausing?: boolean;
 } | {
     name: "finishing";
     epoch: number;
@@ -61,6 +83,10 @@ type AvatarMicState = {
     epoch: number;
     text: string;
     limit: boolean;
+    /** With an endpoint: why the press ended. */
+    by?: AvatarMicDoneBy;
+    /** With an endpoint: the words are the avatar's own answer, heard back through the microphone. */
+    echo?: boolean;
 } | {
     name: "failed";
     epoch: number;
@@ -103,10 +129,36 @@ interface BrowserAvatarMicOptions {
     lang: string;
     /** Tried once, in the same press, when the browser does not recognise `lang` (`en-US`). */
     fallbackLang: string;
-    /** The longest press, from the moment the browser starts listening: thirty seconds. */
+    /**
+     * The longest press, from the moment the browser starts listening: thirty seconds. With an `endpoint`, the longest
+     * wait for a question to start, and the longest question, from its first word.
+     */
     maxPressMs: number;
     /** Every change of the press's state. */
     onState: (state: AvatarMicState) => void;
+    /**
+     * The voice conversation (Stage C2): every press ends itself once the visitor has paused after a question (see
+     * {@link AvatarMicEndpoint}). Without it, a press is exactly the editable one: tap to start, tap to stop.
+     */
+    endpoint?: AvatarMicEndpoint;
+}
+/**
+ * How a press of the voice conversation ends itself (Stage C2): `done` with `by: "pause"` once what is heard is speech
+ * and no word of it has changed for `pauseMs` (twice that for a sentence left open), never sooner than
+ * `BROWSER_PAUSE_AFTER_START_MS` after its recognizer (re)started, and never between two recognizers.
+ */
+interface AvatarMicEndpoint {
+    /**
+     * The pause that ends a question, in milliseconds: the server's `mic.pauseMs` (2000 to 2500, read strictly by the
+     * view's API). Read within those bounds whatever is passed.
+     */
+    pauseMs: number;
+    /**
+     * The words of the answer the avatar has just read (its captions), for the echo check, read as the press ends; null
+     * when there is none, or when the check is not for this press (the view's hook checks only the presses the
+     * conversation starts by itself).
+     */
+    echoOf: () => string | null;
 }
 /** What the mic's chunk (`dist/avatar-mic/`) exports. */
 interface AvatarMicModule {
@@ -114,64 +166,6 @@ interface AvatarMicModule {
     createBrowserAvatarMic: (options: BrowserAvatarMicOptions) => AvatarMic;
 }
 
-/**
- * BOFF-9797 (Stage C, the browser's own recognizer). The Avatar tab's mic through the browser's speech recognition
- * (`SpeechRecognition`, `webkitSpeechRecognition`), as the product assistant listens: tap to start, tap to stop,
- * thirty seconds at most. The browser turns the voice into text (its own speech service: Google's for Chrome, Apple's
- * for Safari, Microsoft's for Edge); this module never sends anything anywhere, and the text goes only to the view,
- * which puts it in the box for the visitor to check and Send.
- *
- * The phones' quirks are the ones the SDK's Chat dictation (`src/hooks/use-speech-input.ts`, live on the sites) met
- * there, handled the same way: the permission prompt raised by opening the microphone first, a pause before the
- * recognizer opens its own, one quiet retry after a fresh grant, and one utterance per recognizer on a touch device.
- *
- * A press, in order:
- *
- * 1. **The tap** (`start`, called inside the tap where the view can). Where the browser reports the microphone granted
- *    (or reports nothing, and a press on this page has had it), the recognizer starts inside the tap. Otherwise the
- *    microphone is opened and released at once, inside the tap (`getUserMedia`): that is what raises the browser's
- *    permission prompt on phones, where a recognizer's own `start()` is refused (`not-allowed`) without asking anyone.
- *    Nothing of that capture is kept, played or sent. Once it is granted, the recognizer starts
- *    {@link BROWSER_PRIME_SETTLE_MS} later, so it does not race the released capture for the microphone. The
- *    recognizer: interim results, one alternative, the press's language, and `continuous`, except on a touch device,
- *    whose recognizer hears one utterance whatever it is asked (and, asked for more, fails sooner). A press still
- *    finishing is superseded (aborted, its text never reported; the view lets no tap through meanwhile).
- * 2. **The browser starts listening** (`onstart`, the honest signal: never while a prompt is up): `listening`, and the
- *    press's limit counts from here ({@link BrowserAvatarMicOptions.maxPressMs}).
- * 3. **Words as they are recognised**: rebuilt from the whole result list each time (finals, then the words still
- *    being recognised), so a result sent again never doubles up, and a final that repeats the one before it with more
- *    words replaces it (Android's cumulative finals).
- * 4. **The engine ending by itself** (a pause, a phone's one utterance, a quiet spell's `no-speech`) does NOT end the
- *    press: tap to stop holds on every platform. A new recognizer takes over in the same press, its words after the
- *    ones before: at once on a computer, after {@link BROWSER_TOUCH_RESTART_MS} on a touch device, and after
- *    {@link BROWSER_RESTART_COOLDOWN_MS} when one has just thrown on `start()` or, on a computer, ended as it began.
- *    Bounded against a recognizer that never listens: after {@link BROWSER_MAX_QUICK_ENDS} ends in a row as they
- *    began, or {@link BROWSER_MAX_RESTARTS} recognizers in all, the press gives what it has. Events of a recognizer that
- *    has been replaced are dropped.
- * 5. **The stop** (the visitor's tap, or the limit): `stop()`, not `abort()`, as browsers deliver the last words after
- *    it; up to {@link BROWSER_FINAL_WAIT_MS} for its end. A tap while it is still starting (the prompt included) calls
- *    the press off.
- * 6. **The text** (`done`): what was heard, final or not (an engine that never marks a result final, iOS Safari, still
- *    gives its words: the visitor checks them in the box anyway). Empty when nothing was heard.
- *
- * **Released on every way out.** `cancel()` (the view going, the page hidden, the Chat tab), a failure, a supersede and
- * the end of a press all detach the recognizer's handlers first and then `abort()` it, so the browser's recording
- * indicator goes and nothing it says later is reported. A microphone opened for the prompt is released as soon as it
- * opens, whether or not the press is still there.
- *
- * Errors. Opening the microphone for the prompt: refused (`NotAllowedError`, `SecurityError`) is `denied`; no
- * microphone (`NotFoundError`) is `unsupported`; anything else is `failed`. The recognizer's
- * (`SpeechRecognitionErrorEvent.error`): `not-allowed` or `service-not-allowed` while the microphone is confirmed for
- * the press (the browser reports it granted, or opening it just worked) is tried once more after
- * {@link BROWSER_GRANT_RETRY_MS}, quietly (Android refuses the first start after a fresh grant and takes the next), and
- * after that it is `unsupported`: the speech service refusing, not a permission the visitor can give. Unconfirmed,
- * `not-allowed` is `denied` (and the next tap asks the browser again) and `service-not-allowed` (iOS with Siri and
- * Dictation off, Edge's policy) is `unsupported`; `audio-capture` (no microphone) is `unsupported`;
- * `language-not-supported` tries the fallback language once, then `unsupported`; `network` is `failed`, and
- * `unsupported` the second time running on the page; `no-speech` is a quiet spell (a new recognizer); anything else is
- * `failed`. A failure once words were heard, whatever it is, gives those words instead (`done`).
- */
-
 /** One alternative of a recognition result: what the browser heard. */
 interface RecognitionAlternativeLike {
     readonly transcript: string;
@@ -315,4 +309,4 @@ interface AvatarMicSeams {
 /** 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, type BrowserAvatarMicOptions, createAvatarMic, createBrowserAvatarMic };
+export { type AvatarMic, type AvatarMicDoneBy, type AvatarMicEndpoint, type AvatarMicFailure, type AvatarMicModule, type AvatarMicOffer, type AvatarMicOptions, type AvatarMicState, type BrowserAvatarMicOptions, createAvatarMic, createBrowserAvatarMic };