@burdenoff/fe-libs 2026.1016.2 → 2026.1017.1

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

@@ -1,39 +1,39 @@
-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, isOutputRefusal as d } from "./pieceSink.js";
+import { isPlaybackReferenceAttached as e, tapPlaybackElement as t } from "../voice/handsfree/playbackReference.js";
+import { HOSTED_TTS_TIER as n, HOSTED_VOICES as r, hostedLocaleFor as i } from "./hostedVoiceCatalogue.js";
+import { buildRequest as a, classifyHttpFailure as o, decodeAudioResponse as s, disableDurationMs as c, shouldDisableEngine as l, speakableChunks as u } from "./hostedTtsProtocol.js";
+import { createPieceSink as d, isOutputRefusal as f } from "./pieceSink.js";
 //#region src/shared/assistant/speech/hostedTtsSpeechEngine.ts
-function f(e) {
+function p(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 p = new Set([
+var m = new Set([
 	429,
 	502,
 	503,
 	504
-]), m = 3, h = 400, g = 2e3;
-function _(e, t) {
+]), h = 3, g = 400, _ = 2e3;
+function v(e, t) {
 	let n = e === null ? NaN : Number(e);
-	return Math.min(Number.isFinite(n) && n >= 0 ? n * 1e3 : h * 2 ** (t - 1), g);
+	return Math.min(Number.isFinite(n) && n >= 0 ? n * 1e3 : g * 2 ** (t - 1), _);
 }
-var v = 6e4, y = 2, b = 1e3;
-function x(e) {
-	return v + e / b * 2 * 1e3;
+var y = 6e4, b = 2, x = 1e3;
+function S(e) {
+	return y + e / x * 2 * 1e3;
 }
-var S = class extends Error {
+var C = class extends Error {
 	reason = "unknown";
 	constructor() {
 		super("audio output made no progress"), this.name = "OutputStalledError";
 	}
 };
-function C(e) {
+function w(e) {
 	let t = 0, n = !1, r = null, i = () => {
 		let n = r;
 		n !== null && (n.cancel(), n.cancel = e(() => {
-			r === n && (r = null, n.fail(new S()));
-		}, x(t)));
+			r === n && (r = null, n.fail(new C()));
+		}, S(t)));
 	};
 	return {
 		handed(e) {
@@ -64,7 +64,14 @@ function C(e) {
 		}
 	};
 }
-function w(e, t) {
+var T = "data:audio/wav;base64,UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=", E = [], D = 4;
+function O() {
+	for (let e of [...E]) e();
+}
+function k() {
+	E.length = 0;
+}
+function A(e, t) {
 	return new Promise((n) => {
 		if (t.aborted) {
 			n();
@@ -79,183 +86,193 @@ function w(e, t) {
 		t.addEventListener("abort", i, { once: !0 });
 	});
 }
-function T(h) {
-	let g = h.fetchImpl ?? ((...e) => fetch(...e)), v = h.now ?? (() => Date.now()), y = h.setTimer ?? ((e, t) => {
+function j(g) {
+	let _ = g.fetchImpl ?? ((...e) => fetch(...e)), y = g.now ?? (() => Date.now()), b = g.setTimer ?? ((e, t) => {
 		let n = setTimeout(e, t);
 		return () => clearTimeout(n);
-	}), b = null, x = null, T = 0, E = null, D = null, O = null, k = 0, A = null, j = null, M = () => {
+	}), x = null, S = null, O = null, k = !1, j = () => {
+		if (!(k || typeof Audio != "function")) try {
+			let e = O ?? new Audio();
+			if (O = e, x === e) return;
+			e.muted = !0, e.src = T, Promise.resolve(e.play()).then(() => {
+				O === e && x !== e && e.pause();
+			}, () => {});
+		} catch {}
+	};
+	E.push(j), E.length > D && E.shift();
+	let M = 0, N = null, P = null, F = null, I = 0, L = null, R = null, z = () => {
 		try {
-			return h.getHeaders?.() ?? {};
+			return g.getHeaders?.() ?? {};
 		} catch {
 			return {};
 		}
-	}, N = () => v() >= k ? !1 : j === null ? !0 : f(M()) === j, P = /* @__PURE__ */ new Set(), F = () => {
-		for (let e of [...P]) e();
-	}, I = () => {
-		A !== null && clearTimeout(A), A = null;
-	}, L = (e) => {
-		I(), A = setTimeout(() => {
-			A = null;
-			let e = k - v();
+	}, B = () => y() >= I ? !1 : R === null ? !0 : p(z()) === R, V = /* @__PURE__ */ new Set(), H = () => {
+		for (let e of [...V]) e();
+	}, U = () => {
+		L !== null && clearTimeout(L), L = null;
+	}, W = (e) => {
+		U(), L = setTimeout(() => {
+			L = null;
+			let e = I - y();
 			if (e > 0) {
-				L(e);
+				W(e);
 				return;
 			}
-			F();
+			H();
 		}, e);
-	}, R = (e, t) => {
-		k = v() + e, j = t, L(e), F();
-	}, z = () => {
-		x &&= (URL.revokeObjectURL(x), null);
-	}, B = () => {
-		if (b) {
-			b.onended = null, b.onerror = null;
+	}, G = (e, t) => {
+		I = y() + e, R = t, W(e), H();
+	}, K = () => {
+		S &&= (URL.revokeObjectURL(S), null);
+	}, q = () => {
+		if (x) {
+			x.onended = null, x.onerror = null;
 			try {
-				b.pause();
+				x.pause();
 			} catch {}
-			b = null;
+			x = null;
 		}
-		z();
+		K();
 	};
-	async function V(e, n, s) {
-		let c = i(e, r(n.lang) ?? n.lang, t, n.voice?.name ?? null, n.rate), l = h.getHeaders?.() ?? {}, u;
-		for (let e = 1; u = await g(h.endpoint, {
+	async function J(e, t, r) {
+		let c = a(e, i(t.lang) ?? t.lang, n, t.voice?.name ?? null, t.rate), l = g.getHeaders?.() ?? {}, u;
+		for (let e = 1; u = await _(g.endpoint, {
 			method: "POST",
-			signal: s,
+			signal: r,
 			headers: {
 				"content-type": "application/json",
 				...l
 			},
 			body: JSON.stringify(c)
 		}), !u.ok; e += 1) {
-			if (!(p.has(u.status) && e < m && !s.aborted)) {
+			if (!(m.has(u.status) && e < h && !r.aborted)) {
 				let e = /* @__PURE__ */ Error(`hosted tts ${u.status}`);
-				throw e.reason = a(u.status), e.headers = f(l), e;
+				throw e.reason = o(u.status), e.headers = p(l), e;
 			}
-			await w(_(u.headers.get("retry-after"), e), s);
+			await A(v(u.headers.get("retry-after"), e), r);
 		}
-		let d = u.headers.get("content-type"), v = o(d, d?.includes("json") ? await u.json() : await u.arrayBuffer());
-		if (!v) {
+		let d = u.headers.get("content-type"), f = s(d, d?.includes("json") ? await u.json() : await u.arrayBuffer());
+		if (!f) {
 			let e = /* @__PURE__ */ Error("hosted tts returned no audio");
 			throw e.reason = "unknown", e;
 		}
-		return v;
+		return f;
 	}
-	function H(t, n, r) {
-		return new Promise((i, a) => {
-			if (n !== T) {
-				i();
+	function Y(n, r, i) {
+		return new Promise((a, o) => {
+			if (r !== M) {
+				a();
 				return;
 			}
-			let o = new Blob([t.slice().buffer], { type: "audio/mpeg" });
-			z(), x = URL.createObjectURL(o);
-			let s = new Audio(x);
-			e(s), b = s, s.onended = () => {
-				n === T && i();
-			}, s.onerror = () => {
-				if (n !== T) {
-					i();
+			let s = new Blob([n.slice().buffer], { type: "audio/mpeg" });
+			K(), S = URL.createObjectURL(s);
+			let c;
+			e() ? (c = new Audio(S), t(c)) : (c = O ?? new Audio(), O = c, c.muted = !1, c.src = S), x = c, c.onended = () => {
+				r === M && a();
+			}, c.onerror = () => {
+				if (r !== M) {
+					a();
 					return;
 				}
 				let e = /* @__PURE__ */ Error("audio playback failed");
-				e.reason = "unknown", a(e);
-			}, s.play().then(() => {
-				n === T && r?.();
+				e.reason = "unknown", o(e);
+			}, c.play().then(() => {
+				c === O && !c.muted && (k = !0), r === M && i?.();
 			}, (e) => {
-				if (n !== T) {
-					i();
+				if (r !== M) {
+					a();
 					return;
 				}
-				let t = /* @__PURE__ */ Error("audio play rejected"), r = e?.name === "NotAllowedError";
-				t.reason = r ? "not-allowed" : "unknown", t.transient = r, a(t);
+				let t = /* @__PURE__ */ Error("audio play rejected"), n = e?.name === "NotAllowedError";
+				t.reason = n ? "not-allowed" : "unknown", t.transient = n, o(t);
 			});
 		});
 	}
 	return {
 		id: "hosted-tts",
 		isSupported() {
-			return N() ? !1 : typeof window < "u" && typeof window.Audio == "function" && typeof fetch == "function";
+			return B() ? !1 : typeof window < "u" && typeof window.Audio == "function" && typeof fetch == "function";
 		},
 		listVoices() {
-			return N() ? [] : [...n];
+			return B() ? [] : [...r];
 		},
 		subscribeVoices(e) {
-			return P.add(e), () => {
-				P.delete(e);
+			return V.add(e), () => {
+				V.delete(e);
 			};
 		},
 		speak(e, t, n = {}) {
-			let r = l(e);
+			let r = u(e);
 			if (r.length === 0) {
 				n.onEnd?.();
 				return;
 			}
-			T += 1;
-			let i = T;
-			B(), D?.cancel(), O?.stop();
+			M += 1;
+			let i = M;
+			q(), P?.cancel(), F?.stop(), j();
 			let a = new AbortController();
-			E = a;
-			let o = !1, f = () => {
+			N = a;
+			let o = !1, s = () => {
 				o || (o = !0, n.onStart?.());
 			}, p = (e) => {
-				let n = V(e, t, a.signal);
+				let n = J(e, t, a.signal);
 				return n.catch(() => {}), n;
-			}, m = t.audioOutput ? C(y) : null, h = t.audioOutput ? u(t.audioOutput, {
-				play: (e) => H(e, i, f),
-				isCurrent: () => i === T,
+			}, m = t.audioOutput ? w(b) : null, h = t.audioOutput ? d(t.audioOutput, {
+				play: (e) => Y(e, i, s),
+				isCurrent: () => i === M,
 				onChunkStart: (e) => {
 					m?.progress(), n.onChunkStart?.(e);
 				},
-				onStart: f
+				onStart: s
 			}) : null;
-			D = h, O = m;
+			P = h, F = m;
 			let g = (e) => m ? m.guard(e) : e, _ = () => {
-				h && (m?.stop(), O === m && (O = null), D === h && (D = null));
+				h && (m?.stop(), F === m && (F = null), P === h && (P = null));
 			};
 			(async () => {
 				try {
 					let e = p(r[0]);
 					for (let t = 0; t < r.length; t += 1) {
-						if (i !== T) return;
+						if (i !== M) return;
 						let a = await e;
-						if (i !== T) return;
+						if (i !== M) return;
 						let o = r[t + 1];
 						if (o !== void 0 && (e = p(o)), h) {
 							m?.handed(a.byteLength), await g(h.write(a));
 							continue;
 						}
-						n.onChunkStart?.(t), await H(a, i, f);
+						n.onChunkStart?.(t), await Y(a, i, s);
 					}
 					if (h) {
 						let e = await g(h.drain());
-						if (i !== T) return;
+						if (i !== M) return;
 						if (!e) throw Object.assign(/* @__PURE__ */ Error("audio output did not finish"), { reason: "unknown" });
 					}
-					i === T && (_(), n.onEnd?.());
+					i === M && (_(), n.onEnd?.());
 				} catch (e) {
-					if (a.abort(), i !== T) return;
+					if (a.abort(), i !== M) return;
 					let t = null;
 					if (h) {
-						let n = e instanceof S ? null : await g(h.drain()).then(() => null, (e) => e);
-						if (i !== T) return;
-						h.cancel(), d(e) ? t = e : d(n) && (t = n);
+						let n = e instanceof C ? null : await g(h.drain()).then(() => null, (e) => e);
+						if (i !== M) return;
+						h.cancel(), f(e) ? t = e : f(n) && (t = n);
 					}
-					if (T += 1, B(), _(), t) {
+					if (M += 1, q(), _(), t) {
 						n.onError?.("output-not-cleared");
 						return;
 					}
 					let r = e?.reason;
-					c(r, e?.transient === !0) && R(s(r), r === "not-allowed" ? e.headers ?? null : null), n.onError?.(r === "not-allowed" || r === "unsupported" || r === "cancelled" ? r : "unknown");
+					l(r, e?.transient === !0) && G(c(r), r === "not-allowed" ? e.headers ?? null : null), n.onError?.(r === "not-allowed" || r === "unsupported" || r === "cancelled" ? r : "unknown");
 				}
 			})();
 		},
 		headersChanged() {
-			v() >= k || j === null || N() || (k = 0, j = null, I(), F());
+			y() >= I || R === null || B() || (I = 0, R = null, U(), H());
 		},
 		cancel() {
-			T += 1, E?.abort(), E = null, B(), D?.cancel(), D = null, O?.stop(), O = null;
+			M += 1, N?.abort(), N = null, q(), P?.cancel(), P = null, F?.stop(), F = null;
 		}
 	};
 }
 //#endregion
-export { b as HOSTED_OUTPUT_MIN_AUDIO_BYTES_PER_SECOND, y as HOSTED_OUTPUT_STALL_AUDIO_RATIO, v as HOSTED_OUTPUT_STALL_BASE_MS, T as createHostedTtsEngine, x as hostedOutputStallMs, _ as retryDelayMs };
+export { x as HOSTED_OUTPUT_MIN_AUDIO_BYTES_PER_SECOND, b as HOSTED_OUTPUT_STALL_AUDIO_RATIO, y as HOSTED_OUTPUT_STALL_BASE_MS, T as SILENT_WAV_DATA_URI, j as createHostedTtsEngine, S as hostedOutputStallMs, O as primeHostedPlayback, k as resetHostedPlaybackForTest, v as retryDelayMs };

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

@@ -25,6 +25,9 @@ function e(e) {
 					onChunkStart: (e) => {
 						t === o && a.onChunkStart?.(e);
 					},
+					onDeviceFallback: () => {
+						t === o && a.onDeviceFallback?.();
+					},
 					onEnd: () => s(),
 					onError: (e) => s(e)
 				});

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

@@ -0,0 +1,84 @@
+/**
+ * The replies the Avatar tab asked to hear on the avatar (BOFF-9360): typed
+ * questions whose answers the avatar speaks, whatever Chat's auto-read is.
+ *
+ * ★★ Only the tab writes here. A reply is registered where the chat area
+ * creates it for a question sent from the tab, with the conversation and the
+ * question it belongs to (critic M2): a reply this module has never seen is
+ * spoken by today's rules, so a host without the live avatar, and every reply
+ * that was not asked from the tab, behaves exactly as before.
+ *
+ * ★★ Fail-safe by construction. A reply missing from here (evicted, never
+ * registered, released) stays text: the worst a gap can do is leave an answer
+ * silent, never speak one that should not be heard.
+ *
+ * ★ Each entry carries what happened to its speech (`outcome`), so the tab can
+ * say it without claiming anything was heard: it records what the audio path
+ * did, never what the person heard.
+ *
+ * ★ Module scope on purpose, like `speechFeed` and `supersededTurns`: the chat
+ * area (which registers), the speech provider (which speaks and settles) and
+ * the tab (which reads) are components that do not know each other.
+ *
+ * ★ Bounded: the tab asks one question at a time, so 16 entries is far more
+ * than one opening of the tab needs; the oldest is dropped first.
+ */
+/** What became of one registered reply's speech. */
+export type ReplySpeechOutcome = 
+/** Registered; the reply has not been spoken or refused yet. */
+'pending'
+/** Being spoken. */
+ | 'speaking'
+/** Spoken to its end. */
+ | 'spoken'
+/** The avatar would not take it (off, covered, ending, sound blocked, no hosted voice), so it was not read aloud. */
+ | 'declined'
+/** It left the avatar part way (an end, a failure), and the rest was stopped, never moved to the speakers (critic M1). */
+ | 'cut'
+/** The avatar's audio output refused it (D7 b): what it played before could not be shown to have stopped. */
+ | 'not-cleared'
+/** A Stop, a newer reply, a conversation switch or a hidden panel stopped it. */
+ | 'stopped'
+/** The voice failed. */
+ | 'failed'
+/** Released unspoken: its conversation is no longer the open one, or the tab closed. */
+ | 'dropped';
+/** One reply the tab asked to hear on the avatar. */
+export interface ReplySpeechRequest {
+    /** The conversation the question landed in (it may have been created by the send). */
+    readonly conversationId: string;
+    readonly questionId: string;
+    readonly replyId: string;
+    readonly outcome: ReplySpeechOutcome;
+}
+/** Record that the reply `replyId`, the answer to `questionId` in `conversationId`, should be spoken on the avatar. */
+export declare function requestReplyOnAvatar(request: {
+    readonly conversationId: string;
+    readonly questionId: string;
+    readonly replyId: string;
+}): void;
+/** Is `replyId` registered and not yet spoken or refused? Null and undefined never are. */
+export declare function replyWantsAvatar(replyId: string | null | undefined): boolean;
+/** The registered request for `replyId`, or null. */
+export declare function replySpeechRequest(replyId: string | null | undefined): ReplySpeechRequest | null;
+/**
+ * What became of `replyId`'s speech. Only a reply still pending or speaking moves, and `speaking` only from
+ * `pending`: the first outcome that ends it is the one kept. Unknown ids are ignored.
+ */
+export declare function settleReplyRequest(replyId: string | null | undefined, outcome: Exclude<ReplySpeechOutcome, 'pending'>): void;
+/**
+ * ★★ Critic M2: release every pending request whose conversation is not `activeConversationId`, read from the live
+ * store by the caller. Never on a timer, and never the open conversation's: a send that creates its conversation
+ * registers the reply in it before any switch handler runs, so its own reply survives the switch it caused.
+ */
+export declare function releaseReplyRequestsOutside(activeConversationId: string | null): void;
+/** Forget every request: the Avatar tab closed. A reply arriving later follows Chat's own auto-read. */
+export declare function clearReplyRequests(): void;
+/** Is any request still waiting for its reply? */
+export declare function hasPendingReplyRequests(): boolean;
+/** Subscribe to every change; returns an unsubscribe function. For `useSyncExternalStore`. */
+export declare function subscribeReplyRequests(listener: () => void): () => void;
+/** A number that changes on every change: a `useSyncExternalStore` snapshot. */
+export declare function replyRequestsVersion(): number;
+/** Tests only. */
+export declare function resetReplyRequestsForTest(): void;

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

@@ -0,0 +1,70 @@
+//#region src/shared/assistant/speech/replySpeechRequests.ts
+var e = 16, t = /* @__PURE__ */ new Map(), n = /* @__PURE__ */ new Set(), r = 0;
+function i() {
+	r += 1;
+	for (let e of [...n]) e();
+}
+var a = new Set([
+	"spoken",
+	"declined",
+	"cut",
+	"not-cleared",
+	"stopped",
+	"failed",
+	"dropped"
+]);
+function o(n) {
+	for (t.delete(n.replyId), t.set(n.replyId, {
+		conversationId: n.conversationId,
+		questionId: n.questionId,
+		replyId: n.replyId,
+		outcome: "pending"
+	}); t.size > e;) {
+		let e = t.keys().next();
+		if (e.done) break;
+		t.delete(e.value);
+	}
+	i();
+}
+function s(e) {
+	return typeof e == "string" && t.get(e)?.outcome === "pending";
+}
+function c(e) {
+	return typeof e == "string" ? t.get(e) ?? null : null;
+}
+function l(e, n) {
+	if (typeof e != "string") return;
+	let r = t.get(e);
+	!r || a.has(r.outcome) || n === "speaking" && r.outcome !== "pending" || (t.set(e, {
+		...r,
+		outcome: n
+	}), i());
+}
+function u(e) {
+	let n = !1;
+	for (let [r, i] of t) i.outcome !== "pending" || i.conversationId === e || (t.set(r, {
+		...i,
+		outcome: "dropped"
+	}), n = !0);
+	n && i();
+}
+function d() {
+	t.size !== 0 && (t.clear(), i());
+}
+function f() {
+	for (let e of t.values()) if (e.outcome === "pending") return !0;
+	return !1;
+}
+function p(e) {
+	return n.add(e), () => {
+		n.delete(e);
+	};
+}
+function m() {
+	return r;
+}
+function h() {
+	t.clear(), n.clear(), r = 0;
+}
+//#endregion
+export { d as clearReplyRequests, f as hasPendingReplyRequests, u as releaseReplyRequestsOutside, m as replyRequestsVersion, c as replySpeechRequest, s as replyWantsAvatar, o as requestReplyOnAvatar, h as resetReplyRequestsForTest, l as settleReplyRequest, p as subscribeReplyRequests };

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

@@ -5,7 +5,8 @@ import { selectVoiceForLocale as n } from "../voice/speechVoices.js";
 function r(e) {
 	switch (e) {
 		case "cancelled":
-		case "output-not-cleared": return !1;
+		case "output-not-cleared":
+		case "output-left": return !1;
 		case "not-allowed":
 		case "unsupported":
 		case "unknown": return !0;
@@ -14,23 +15,26 @@ function r(e) {
 }
 function i({ device: i, hosted: a }) {
 	if (!a) return i;
-	let o = new Set(a.listVoices().map((e) => e.name)), s = (e) => e.source === "hosted" || o.has(e.name), c = (e, t, r) => {
+	let o = new Set(a.listVoices().map((e) => e.name)), s = (e) => e.source === "hosted" || o.has(e.name), c = (e, t, r, a = !1) => {
+		let o = () => {
+			a && r?.onDeviceFallback?.();
+		};
 		if (!t.voice || !s(t.voice)) {
-			i.speak(e, t, r);
+			o(), i.speak(e, t, r);
 			return;
 		}
 		if (t.fallback === !1) {
 			r?.onError?.("unsupported");
 			return;
 		}
-		let a = n(i.listVoices(), t.lang);
-		if (!a) {
+		let c = n(i.listVoices(), t.lang);
+		if (!c) {
 			r?.onError?.("unsupported");
 			return;
 		}
-		i.speak(e, {
+		o(), i.speak(e, {
 			...t,
-			voice: a
+			voice: c
 		}, r);
 	}, l = (t) => a.isSupported() ? t.voice ? o.has(t.voice.name) ? a : i : e(t.lang) ? a : i : i;
 	return {
@@ -67,7 +71,7 @@ function i({ device: i, hosted: a }) {
 						return;
 					}
 					if (!s) {
-						c(e, n, o);
+						c(e, n, o, !0);
 						return;
 					}
 					let a = u >= 0 ? t(e).slice(u + 1) : [];
@@ -80,7 +84,7 @@ function i({ device: i, hosted: a }) {
 						...o,
 						onStart: void 0,
 						onChunkStart: (e) => o?.onChunkStart?.(l + e)
-					});
+					}, !0);
 				}
 			});
 		},

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

@@ -27,6 +27,19 @@ export interface SpeechSpeakOptions {
      * stop, whether the reply is one `speak()` or a queue that grows by appends.
      */
     audioOutput?: SpeechAudioOutput;
+    /**
+     * ★★ BOFF-9360 (critic M1): heard on the avatar, or nowhere. Set by the
+     * speech provider for a reply asked from the Avatar tab while Chat's
+     * auto-read is off, and read only by the live avatar's engine decorator
+     * (`wouldSpeakOnAvatar`); every other engine ignores it.
+     *
+     * Such a reply is never moved to the speakers: when its avatar output
+     * leaves it (the avatar is switched off, the tab closes, the session ends)
+     * or fails, part way or before its first piece, the rest is STOPPED and the
+     * reply ends with `onError('output-left')`. A device-voice fallback is off
+     * for it too. A refusal (`output-not-cleared`) is reported as it always is.
+     */
+    avatarOnly?: boolean;
 }
 /**
  * Somewhere other than the speakers to play a reply's hosted audio
@@ -138,8 +151,13 @@ export interface SpeechOutputRefusal {
  * 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.
+ *
+ * `output-left` ends an `avatarOnly` reply (BOFF-9360) that stopped going to
+ * the avatar, or was never given to it: the rest of it was stopped, never
+ * played on the speakers. Only the live avatar's engine decorator reports it,
+ * and nothing re-speaks it.
  */
-export type SpeechErrorReason = 'cancelled' | 'not-allowed' | 'unsupported' | 'unknown' | 'output-not-cleared';
+export type SpeechErrorReason = 'cancelled' | 'not-allowed' | 'unsupported' | 'unknown' | 'output-not-cleared' | 'output-left';
 export interface SpeechSpeakHandlers {
     /**
      * Audio has actually begun playing — not merely been requested.
@@ -173,6 +191,17 @@ export interface SpeechSpeakHandlers {
     /** The whole queue finished on its own. */
     onEnd?: () => void;
     onError?: (reason: SpeechErrorReason) => void;
+    /**
+     * ★ BOFF-9408: the hosted voice could not play this reply, so the rest of it
+     * (or all of it) is about to be spoken on the DEVICE voice.
+     *
+     * The routing engine calls it once, just before the device voice starts, so
+     * the caller can say so on screen instead of the user hearing a different
+     * voice with no explanation. The fallback changes nothing the user chose:
+     * their saved voice is untouched and the next reply tries the hosted voice
+     * again. Optional; an engine with no fallback never calls it.
+     */
+    onDeviceFallback?: () => void;
 }
 export interface SpeechEngine {
     /** Stable id, for logging and for telling engines apart in a future swap. */
@@ -187,4 +216,13 @@ export interface SpeechEngine {
     speak(chunks: readonly string[], options: SpeechSpeakOptions, handlers?: SpeechSpeakHandlers): void;
     /** Stop immediately and drop anything queued. Safe to call when idle. */
     cancel(): void;
+    /**
+     * ★ BOFF-9360: would `speak` with these options play the reply on the live
+     * avatar right now? The decorated live-avatar engine only (it asks the same
+     * per-reply route its `speak` asks, with the same avatar voice, so the two
+     * cannot disagree); every other engine omits it, which callers read as
+     * "no". Asked by the speech provider before an `avatarOnly` reply starts,
+     * and only then.
+     */
+    wouldSpeakOnAvatar?(options: SpeechSpeakOptions): boolean;
 }