@burdenoff/fe-libs 2026.1013.9 → 2026.1013.11

package/dist/shared/assistant/speech/types.d.ts

@@ -17,13 +17,117 @@ export interface SpeechSpeakOptions {
      * heard (BOFF-7283). Omitted means fallback is allowed.
      */
     fallback?: boolean;
+    /**
+     * Play this reply's hosted audio HERE instead of on the speakers: the
+     * optional live avatar (BOFF-8822). Attached per reply by the panel that
+     * shows the avatar, so no other caller of the shared engine can reach it.
+     * An engine with no audio data to hand over (the device voice) ignores it.
+     *
+     * It belongs to the whole reply: one output, one piece count and one hard
+     * stop, whether the reply is one `speak()` or a queue that grows by appends.
+     */
+    audioOutput?: SpeechAudioOutput;
+}
+/**
+ * Somewhere other than the speakers to play a reply's hosted audio
+ * (BOFF-8822).
+ *
+ * ★★ The hosted engine keeps everything else: the request (voice, language,
+ * rate), the retries, the one-piece prefetch, the refusal latch, `cancel()`.
+ * Each piece is synthesised ONCE. If the output fails, the pieces it never
+ * began play on the speakers from the bytes already fetched, so falling back
+ * never synthesises anything twice, and an output's failure never latches the
+ * engine off.
+ *
+ * ★ Leaving is not stopping. When the output stops being the reply's
+ * destination while the reply goes on (the user switched the avatar off), it
+ * rejects the pending `write` or `drain` (or the next one, if none is pending)
+ * and every later one with an error whose `reason` is `SPEECH_OUTPUT_LEFT`. The
+ * rest of the reply then plays on the speakers, exactly as after a failure, and
+ * still ends with `onEnd`. Switching it off never goes through the engine's
+ * `cancel()`, which silences the reply, nor through `retract()`.
+ *
+ * ★★ Refusing is neither leaving nor failing (operator decision D7 b). When the
+ * output cannot show that what it played BEFORE this reply has stopped (its
+ * drain bound ran out while that audio may still be heard), it must not start
+ * this reply anywhere: it writes nothing, unmutes nothing, and rejects the
+ * pending `write` or `drain` (or the next one, if none is pending) and every
+ * later one with a `SpeechOutputRefusal`. The engine then silences it, plays
+ * NOTHING on the speakers, and ends the reply with
+ * `onError('output-not-cleared')`, which no fallback re-speaks. A `drain()`
+ * with nothing written yet is no exception: the engine drains before it
+ * reports a failure of its own, and a drain that resolves lets the device
+ * voice speak the reply.
+ *
+ * One object serves exactly one reply: attach a fresh one to each, so neither
+ * a leave, a refusal nor the hard stop carries over to the next reply.
+ */
+export interface SpeechAudioOutput {
+    /**
+     * Take piece `index` (the bytes the proxy returned). `index` counts the
+     * reply's pieces from 0 with ONE counter for the whole reply: for a queue it
+     * continues across appends, and a retracted number is never given again.
+     *
+     * Resolve when the next piece may follow: once this one is queued, pieces
+     * play back to back; resolving when it BEGINS keeps synthesis one piece
+     * ahead, as on the speakers. Call `began()` when its sound begins, and,
+     * before rejecting, for any piece that MAY have been heard: the speakers
+     * resume after the last piece that began, so nothing is heard twice. A piece
+     * retracted before it began resolves its `write` without `began()`. Writing
+     * may go on after a `drain()`, until `cancel()` or the reply's end.
+     */
+    write(bytes: Uint8Array, index: number, began: () => void): Promise<void>;
+    /**
+     * Resolve once everything written SO FAR has finished playing; reject as
+     * `write` does. Callable more than once: a queue may drain when its speech
+     * pauses and write again afterwards, even before that drain settles (a piece
+     * written meanwhile is not part of it). The reply's last drain follows its
+     * end and its last write.
+     */
+    drain(): Promise<void>;
+    /**
+     * Drop every piece with `index >= fromIndex` that has not begun; the piece
+     * playing, if any, finishes. Call `began()` first for any of them that MAY
+     * have been heard: it is then the one playing, and stays. Queued speech is
+     * withdrawn this way; `cancel()` remains the hard stop.
+     */
+    retract(fromIndex: number): void;
+    /**
+     * The hard stop (a stop, a new reply, a failure): silence at once and drop
+     * everything queued. Pending `write`/`drain` calls still settle, either way.
+     */
+    cancel(): void;
+}
+/**
+ * The `reason` a `SpeechAudioOutput` rejects with once it has LEFT the reply
+ * (switched off while the reply goes on). Any other rejection is a failure,
+ * except a refusal (`SPEECH_OUTPUT_REFUSE_AUDIBLE`).
+ */
+export declare const SPEECH_OUTPUT_LEFT = "left";
+/**
+ * The `reason` a `SpeechAudioOutput` rejects with to REFUSE the reply
+ * (operator decision D7 b): what it played before could not be shown to have
+ * stopped, so nothing of this reply may be heard, on the output, on the
+ * speakers or on any other voice. Exported so that an output cannot misspell it
+ * and silently turn a refusal into a failure the speakers take over.
+ */
+export declare const SPEECH_OUTPUT_REFUSE_AUDIBLE = "refuse-audible";
+/** What a `SpeechAudioOutput` rejects with to refuse the reply (`SPEECH_OUTPUT_REFUSE_AUDIBLE`). */
+export interface SpeechOutputRefusal {
+    readonly reason: typeof SPEECH_OUTPUT_REFUSE_AUDIBLE;
 }
 /**
  * Why playback stopped. `cancelled` is not a failure: it is what every queued
  * utterance reports when we deliberately cancel (new playback, panel close,
  * conversation switch), and the UI must stay silent about it.
+ *
+ * `output-not-cleared` is a failure that must NEVER be heard (BOFF-8822,
+ * operator decision D7 b): the reply's audio output refused it because what it
+ * played before could not be shown to have stopped. Nothing re-speaks it, the
+ * device voice included, and its text stays where it is. Only a reply with an
+ * `audioOutput` can end this way.
  */
-export type SpeechErrorReason = 'cancelled' | 'not-allowed' | 'unsupported' | 'unknown';
+export type SpeechErrorReason = 'cancelled' | 'not-allowed' | 'unsupported' | 'unknown' | 'output-not-cleared';
 export interface SpeechSpeakHandlers {
     /**
      * Audio has actually begun playing — not merely been requested.

package/dist/shared/assistant/speech/types.js

@@ -0,0 +1,4 @@
+//#region src/shared/assistant/speech/types.ts
+var e = "left", t = "refuse-audible";
+//#endregion
+export { e as SPEECH_OUTPUT_LEFT, t as SPEECH_OUTPUT_REFUSE_AUDIBLE };

package/dist/shared/assistant/ui/AssistantSpeechProvider.d.ts

@@ -54,6 +54,17 @@ export interface AssistantSpeechContextValue {
     setVoice: (voiceName: string | null) => void;
     /** The message currently being spoken, if any. */
     speakingMessageId: string | null;
+    /**
+     * ★★ The reply an audio output REFUSED (BOFF-8822, operator decision D7 b;
+     * reason `output-not-cleared`): what it played before could not be shown to
+     * have stopped, so the reply was never heard, on any voice. It ended as a
+     * failure like any other (playback is idle and its text is untouched); this
+     * says WHICH reply, so the voice session can explain the silence. A new
+     * object per refusal; null until one happens, which needs an audio output.
+     */
+    outputNotCleared: {
+        readonly messageId: string;
+    } | null;
     isSpeaking: (messageId: string) => boolean;
     /**
      * Speak this message, or stop if it is already the one speaking.