@burdenoff/fe-libs 2026.1013.9 → 2026.1013.10

package/dist/shared/assistant/index.d.ts

@@ -44,6 +44,7 @@ export * from './speech/browserSpeechEngine';
 export * from './speech/hostedTtsSpeechEngine';
 export * from './speech/routingSpeechEngine';
 export * from './speech/hostedVoiceCatalogue';
+export * from './speech/pieceSink';
 export * from './speech/speechFeed';
 export * from './voice/useVoiceInput';
 export * from './voice/voiceStageState';

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

@@ -1,23 +1,24 @@
 import { tapPlaybackElement as e } from "../voice/handsfree/playbackReference.js";
 import { HOSTED_TTS_TIER as t, HOSTED_VOICES as n, hostedLocaleFor as r } from "./hostedVoiceCatalogue.js";
 import { buildRequest as i, classifyHttpFailure as a, decodeAudioResponse as o, disableDurationMs as s, shouldDisableEngine as c, speakableChunks as l } from "./hostedTtsProtocol.js";
+import { createPieceSink as u } from "./pieceSink.js";
 //#region src/shared/assistant/speech/hostedTtsSpeechEngine.ts
-function u(e) {
+function d(e) {
 	let t = Object.entries(e).map(([e, t]) => `${e.toLowerCase()}:${t}`).sort().join("\n"), n = 5381;
 	for (let e = 0; e < t.length; e += 1) n = (n << 5) + n + t.charCodeAt(e) | 0;
 	return `${t.length}:${n >>> 0}`;
 }
-var d = new Set([
+var f = new Set([
 	429,
 	502,
 	503,
 	504
-]), f = 3, p = 400, m = 2e3;
-function h(e, t) {
+]), p = 3, m = 400, h = 2e3;
+function g(e, t) {
 	let n = e === null ? NaN : Number(e);
-	return Math.min(Number.isFinite(n) && n >= 0 ? n * 1e3 : p * 2 ** (t - 1), m);
+	return Math.min(Number.isFinite(n) && n >= 0 ? n * 1e3 : m * 2 ** (t - 1), h);
 }
-function g(e, t) {
+function _(e, t) {
 	return new Promise((n) => {
 		if (t.aborted) {
 			n();
@@ -32,44 +33,44 @@ function g(e, t) {
 		t.addEventListener("abort", i, { once: !0 });
 	});
 }
-function _(p) {
-	let m = p.fetchImpl ?? ((...e) => fetch(...e)), _ = p.now ?? (() => Date.now()), v = null, y = null, b = 0, x = null, S = 0, C = null, w = null, T = () => {
+function v(m) {
+	let h = m.fetchImpl ?? ((...e) => fetch(...e)), v = m.now ?? (() => Date.now()), y = null, b = null, x = 0, S = null, C = null, w = 0, T = null, E = null, D = () => {
 		try {
-			return p.getHeaders?.() ?? {};
+			return m.getHeaders?.() ?? {};
 		} catch {
 			return {};
 		}
-	}, E = () => _() >= S ? !1 : w === null ? !0 : u(T()) === w, D = /* @__PURE__ */ new Set(), O = () => {
-		for (let e of [...D]) e();
-	}, k = () => {
-		C !== null && clearTimeout(C), C = null;
-	}, A = (e) => {
-		k(), C = setTimeout(() => {
-			C = null;
-			let e = S - _();
+	}, O = () => v() >= w ? !1 : E === null ? !0 : d(D()) === E, k = /* @__PURE__ */ new Set(), A = () => {
+		for (let e of [...k]) e();
+	}, j = () => {
+		T !== null && clearTimeout(T), T = null;
+	}, M = (e) => {
+		j(), T = setTimeout(() => {
+			T = null;
+			let e = w - v();
 			if (e > 0) {
-				A(e);
+				M(e);
 				return;
 			}
-			O();
+			A();
 		}, e);
-	}, j = (e, t) => {
-		S = _() + e, w = t, A(e), O();
-	}, M = () => {
-		y &&= (URL.revokeObjectURL(y), null);
-	}, N = () => {
-		if (v) {
-			v.onended = null, v.onerror = null;
+	}, N = (e, t) => {
+		w = v() + e, E = t, M(e), A();
+	}, P = () => {
+		b &&= (URL.revokeObjectURL(b), null);
+	}, F = () => {
+		if (y) {
+			y.onended = null, y.onerror = null;
 			try {
-				v.pause();
+				y.pause();
 			} catch {}
-			v = null;
+			y = null;
 		}
-		M();
+		P();
 	};
-	async function P(e, n, s) {
-		let c = i(e, r(n.lang) ?? n.lang, t, n.voice?.name ?? null, n.rate), l = p.getHeaders?.() ?? {}, _;
-		for (let e = 1; _ = await m(p.endpoint, {
+	async function I(e, n, s) {
+		let c = i(e, r(n.lang) ?? n.lang, t, n.voice?.name ?? null, n.rate), l = m.getHeaders?.() ?? {}, u;
+		for (let e = 1; u = await h(m.endpoint, {
 			method: "POST",
 			signal: s,
 			headers: {
@@ -77,42 +78,42 @@ function _(p) {
 				...l
 			},
 			body: JSON.stringify(c)
-		}), !_.ok; e += 1) {
-			if (!(d.has(_.status) && e < f && !s.aborted)) {
-				let e = /* @__PURE__ */ Error(`hosted tts ${_.status}`);
-				throw e.reason = a(_.status), e.headers = u(l), e;
+		}), !u.ok; e += 1) {
+			if (!(f.has(u.status) && e < p && !s.aborted)) {
+				let e = /* @__PURE__ */ Error(`hosted tts ${u.status}`);
+				throw e.reason = a(u.status), e.headers = d(l), e;
 			}
-			await g(h(_.headers.get("retry-after"), e), s);
+			await _(g(u.headers.get("retry-after"), e), s);
 		}
-		let v = _.headers.get("content-type"), y = o(v, v?.includes("json") ? await _.json() : await _.arrayBuffer());
+		let v = u.headers.get("content-type"), y = o(v, v?.includes("json") ? await u.json() : await u.arrayBuffer());
 		if (!y) {
 			let e = /* @__PURE__ */ Error("hosted tts returned no audio");
 			throw e.reason = "unknown", e;
 		}
 		return y;
 	}
-	function F(t, n, r) {
+	function L(t, n, r) {
 		return new Promise((i, a) => {
-			if (n !== b) {
+			if (n !== x) {
 				i();
 				return;
 			}
 			let o = new Blob([t.slice().buffer], { type: "audio/mpeg" });
-			M(), y = URL.createObjectURL(o);
-			let s = new Audio(y);
-			e(s), v = s, s.onended = () => {
-				n === b && i();
+			P(), b = URL.createObjectURL(o);
+			let s = new Audio(b);
+			e(s), y = s, s.onended = () => {
+				n === x && i();
 			}, s.onerror = () => {
-				if (n !== b) {
+				if (n !== x) {
 					i();
 					return;
 				}
 				let e = /* @__PURE__ */ Error("audio playback failed");
 				e.reason = "unknown", a(e);
 			}, s.play().then(() => {
-				n === b && r?.();
+				n === x && r?.();
 			}, (e) => {
-				if (n !== b) {
+				if (n !== x) {
 					i();
 					return;
 				}
@@ -124,14 +125,14 @@ function _(p) {
 	return {
 		id: "hosted-tts",
 		isSupported() {
-			return E() ? !1 : typeof window < "u" && typeof window.Audio == "function" && typeof fetch == "function";
+			return O() ? !1 : typeof window < "u" && typeof window.Audio == "function" && typeof fetch == "function";
 		},
 		listVoices() {
-			return E() ? [] : [...n];
+			return O() ? [] : [...n];
 		},
 		subscribeVoices(e) {
-			return D.add(e), () => {
-				D.delete(e);
+			return k.add(e), () => {
+				k.delete(e);
 			};
 		},
 		speak(e, t, n = {}) {
@@ -140,43 +141,61 @@ function _(p) {
 				n.onEnd?.();
 				return;
 			}
-			b += 1;
-			let i = b;
-			N();
+			x += 1;
+			let i = x;
+			F(), C?.cancel();
 			let a = new AbortController();
-			x = a;
-			let o = !1, u = () => {
+			S = a;
+			let o = !1, d = () => {
 				o || (o = !0, n.onStart?.());
-			}, d = (e) => {
-				let n = P(e, t, a.signal);
+			}, f = (e) => {
+				let n = I(e, t, a.signal);
 				return n.catch(() => {}), n;
-			};
-			(async () => {
+			}, p = t.audioOutput ? u(t.audioOutput, {
+				play: (e) => L(e, i, d),
+				isCurrent: () => i === x,
+				onChunkStart: (e) => n.onChunkStart?.(e),
+				onStart: d
+			}) : null;
+			C = p, (async () => {
 				try {
-					let e = d(r[0]);
+					let e = f(r[0]);
 					for (let t = 0; t < r.length; t += 1) {
-						if (i !== b) return;
+						if (i !== x) return;
 						let a = await e;
-						if (i !== b) return;
+						if (i !== x) return;
 						let o = r[t + 1];
-						o !== void 0 && (e = d(o)), n.onChunkStart?.(t), await F(a, i, u);
+						if (o !== void 0 && (e = f(o)), p) {
+							await p.write(a);
+							continue;
+						}
+						n.onChunkStart?.(t), await L(a, i, d);
 					}
-					i === b && n.onEnd?.();
+					if (p) {
+						let e = await p.drain();
+						if (i !== x) return;
+						if (!e) throw Object.assign(/* @__PURE__ */ Error("audio output did not finish"), { reason: "unknown" });
+					}
+					i === x && n.onEnd?.();
 				} catch (e) {
-					if (a.abort(), i !== b) return;
-					b += 1, N();
+					if (a.abort(), i !== x) return;
+					if (p) {
+						if (await p.drain().catch(() => !1), i !== x) return;
+						p.cancel();
+					}
+					x += 1, F();
 					let t = e?.reason;
-					c(t, e?.transient === !0) && j(s(t), t === "not-allowed" ? e.headers ?? null : null), n.onError?.(t === "not-allowed" || t === "unsupported" || t === "cancelled" ? t : "unknown");
+					c(t, e?.transient === !0) && N(s(t), t === "not-allowed" ? e.headers ?? null : null), n.onError?.(t === "not-allowed" || t === "unsupported" || t === "cancelled" ? t : "unknown");
 				}
 			})();
 		},
 		headersChanged() {
-			_() >= S || w === null || E() || (S = 0, w = null, k(), O());
+			v() >= w || E === null || O() || (w = 0, E = null, j(), A());
 		},
 		cancel() {
-			b += 1, x?.abort(), x = null, N();
+			x += 1, S?.abort(), S = null, F(), C?.cancel(), C = null;
 		}
 	};
 }
 //#endregion
-export { _ as createHostedTtsEngine, h as retryDelayMs };
+export { v as createHostedTtsEngine, g as retryDelayMs };

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

@@ -0,0 +1,43 @@
+import { SpeechAudioOutput } from './types';
+/** @internal What the sink needs from the reply it belongs to. */
+export interface PieceSinkReply {
+    /** Plays one piece on the speakers and resolves when it has finished: the engine's own `play`. */
+    play(bytes: Uint8Array): Promise<void>;
+    /** False once the reply was cancelled or replaced: nothing more is played. */
+    isCurrent(): boolean;
+    /** Piece `index` begins: the live caption's sync signal. */
+    onChunkStart(index: number): void;
+    /** The reply's first sound (the engine announces it once per reply). */
+    onStart(): void;
+}
+/** @internal The engine's side of one reply's audio output. */
+export interface PieceSink {
+    /**
+     * Hand over the reply's next piece. Pieces are numbered 0, 1, 2… by ONE
+     * counter for the whole reply: a queue's count continues across appends and
+     * across drains, and a retracted number is never given again. Resolves when
+     * the next piece may follow; rejects as `drain` does once the speakers fail.
+     */
+    write(bytes: Uint8Array): Promise<void>;
+    /**
+     * Resolves once everything written so far has finished playing: `true`, or
+     * `false` when the output FAILED after every piece had begun, so the end was
+     * never confirmed (a leave is not a failure: `true`). Callable any number of
+     * times; writing may go on after it, even while it is pending (a piece written
+     * meanwhile is not part of it). Never rejects with the output's reason, only
+     * with the speakers' own failure, which the engine reports as it always has.
+     * Once the speakers have failed, every later or queued `write` and `drain`
+     * rejects with that same failure until `cancel()`: nothing more plays, and
+     * nothing is confirmed.
+     */
+    drain(): Promise<boolean>;
+    /**
+     * Withdraw every piece from `fromIndex` on that has not begun, on the output
+     * and in the record a failure replays from; the one playing finishes.
+     */
+    retract(fromIndex: number): void;
+    /** The hard stop: silence the output and drop everything. Nothing is replayed. */
+    cancel(): void;
+}
+/** @internal One reply's piece sink, playing on `output` until it fails or leaves. */
+export declare function createPieceSink(output: SpeechAudioOutput, reply: PieceSinkReply): PieceSink;

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

@@ -0,0 +1,84 @@
+import { SPEECH_OUTPUT_LEFT as e } from "./types.js";
+//#region src/shared/assistant/speech/pieceSink.ts
+var t = (t) => t?.reason === e;
+function n(e, n) {
+	let r = e, i = !1, a = 0, o = /* @__PURE__ */ new Map(), s = () => !i && n.isCurrent(), c = () => {
+		let e = r;
+		r = null;
+		try {
+			e?.cancel();
+		} catch {}
+	}, l = (e, t) => () => {
+		if (!(r !== e || !s() || !o.has(t))) {
+			for (let e of o.keys()) {
+				if (e > t) break;
+				o.delete(e);
+			}
+			n.onChunkStart(t), n.onStart();
+		}
+	}, u = !1, d = async () => {
+		for (let [e, t] of o) {
+			if (!s()) return;
+			o.delete(e), u = !0, n.onChunkStart(e);
+			try {
+				await n.play(t);
+			} catch (e) {
+				throw o.clear(), e;
+			}
+		}
+	}, f = Promise.resolve(), p = () => {
+		if (!s()) return Promise.resolve();
+		let e = f.then(d);
+		return f = e, e;
+	};
+	return {
+		async write(e) {
+			let t = a;
+			if (a += 1, !s()) return;
+			o.set(t, e);
+			let n = r;
+			if (n) try {
+				await n.write(e, t, l(n, t));
+			} catch {
+				if (!s()) return;
+				r === n && c();
+			}
+			r === null && await p();
+		},
+		async drain() {
+			let e = r;
+			if (e && s()) {
+				let n = a;
+				try {
+					if (await e.drain(), r === e) {
+						for (let e of o.keys()) {
+							if (e >= n) break;
+							o.delete(e);
+						}
+						return !0;
+					}
+				} catch (n) {
+					if (!s()) return !0;
+					let i = t(n) || o.size > 0;
+					return r === e && c(), await p(), i || u;
+				}
+			}
+			return await p(), !0;
+		},
+		retract(e) {
+			if (!s()) return;
+			let t = r;
+			if (t) try {
+				t.retract(e);
+			} catch {
+				r === t && c();
+			}
+			for (let t of o.keys()) t >= e && o.delete(t);
+		},
+		cancel() {
+			i = !0, o.clear(), c();
+		}
+	};
+}
+//#endregion
+export { n as createPieceSink };

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

@@ -17,7 +17,80 @@ 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()`.
+ *
+ * One object serves exactly one reply: attach a fresh one to each, so neither
+ * a leave 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.
+ */
+export declare const SPEECH_OUTPUT_LEFT = "left";
 /**
  * Why playback stopped. `cancelled` is not a failure: it is what every queued
  * utterance reports when we deliberately cancel (new playback, panel close,

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

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