@burdenoff/fe-libs 2026.1014.5 → 2026.1015.2

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

@@ -1,4 +1,4 @@
-import { ComponentType, FC, ReactNode } from 'react';
+import { ComponentType, FC, ReactNode, RefObject } from 'react';
 import { SpeechEngine } from '../speech/types';
 import { VoiceView } from './voice/AssistantVoiceSession';
 export interface LiveAvatarStageProps {
@@ -15,10 +15,115 @@ export interface AssistantLiveAvatarSeam {
     /**
      * The avatar's ON switch. Optional. It is SHOWN only when `Stage` is given,
      * since without a stage there is nothing to show; told when a voice
-     * conversation is live, and switched OFF at the end of every one, either way.
+     * conversation is live, and switched OFF at the end of every one, either way
+     * (except while the Avatar tab is open, which owns its avatar).
      */
     enabled?: LiveAvatarEnabledStore;
+    /**
+     * The Avatar tab (BOFF-9341). Optional; without it there is no tab, and the
+     * panel is exactly what it was.
+     *
+     * ★★ HOST CONTRACT: hand the seam over only once the server's availability
+     * has said the avatar is offered to this person here (as VibeControls does),
+     * and keep it stable. The tab asks the same free availability question when
+     * it opens, and starts a paid session only on the person's Turn on.
+     */
+    tab?: LiveAvatarTabSeam;
+}
+/** Whether the Avatar tab may be offered, as a store read with `useSyncExternalStore`. STABLE. */
+export interface LiveAvatarTabOfferedStore {
+    subscribe: (onChange: () => void) => () => void;
+    /** This browser can show the avatar (desktop Chrome first), and it was not refused on this page. */
+    getSnapshot: () => boolean;
+}
+/** The Avatar tab's part of the seam (`createLiveAvatarSeam` builds it). STABLE, like the rest of the seam. */
+export interface LiveAvatarTabSeam {
+    readonly offered: LiveAvatarTabOfferedStore;
+    /**
+     * Told when the Avatar tab opens and closes; idempotent. Opening starts
+     * nothing paid. Closing is the person's OFF for the tab's avatar, except one
+     * `heldByVoice`, which stays ON for the voice stage.
+     */
+    readonly setOpen: (open: boolean) => void;
+    /**
+     * Whether the avatar now ON was turned on outside the tab, during the voice
+     * conversation that is still live: closing the tab hands it back to Voice
+     * instead of ending it (critic #9). Read when the tab closes.
+     */
+    readonly heldByVoice: () => boolean;
+    /**
+     * The tab's avatar area, drawn inside the panel's Avatar tab (`AssistantAvatarTab`): the frame, the chooser, the avatar's voice, the
+     * disclosure with Turn on / Turn off, its status line, and the way into the voice conversation. Mounted only while the tab is open.
+     */
+    readonly View: ComponentType<LiveAvatarTabProps>;
+}
+/** The voice conversation, as the Avatar tab shows it and starts it (the composer's own conversation, `useVoiceSession`). */
+export interface LiveAvatarTabVoice {
+    /** A voice conversation is live: its compact strip sits under the tab. */
+    readonly live: boolean;
+    /** Why one cannot start now, in the person's words (the composer's full check, `voiceStartBlocker`); null when it can. */
+    readonly blocked: string | null;
+    /** The reason lasts (no voice here, in this mode, or in this conversation): asking the avatar is impossible for now. */
+    readonly impossible: boolean;
+    /** Start it: the composer's own start (`startVoiceWithPrewarm`). Opens the microphone; never called by anything but its button. */
+    readonly start: () => void;
+}
+/** What the panel hands the tab's `View`. */
+export interface LiveAvatarTabProps {
+    /**
+     * The tab is on screen and nothing covers it (History, the preview, the voice session enlarged, a transcript drawer): replies may
+     * go to the avatar only while this is true (D4, critic #4). Per reply: each reply is routed once, when it starts, so a reply already
+     * on the avatar when this turns false finishes there; the next goes to the speakers.
+     */
+    readonly shown: boolean;
+    readonly voice: LiveAvatarTabVoice;
+    /** Hands-free interrupt was switched off for this avatar (`useLiveAvatarHandsFreeGuard`): said in the tab while no voice is live. */
+    readonly handsFreeOff: boolean;
+    /** The id the leave hint ("Leaving the Avatar tab turns the avatar off.") must carry: the Chat tab is described by it. */
+    readonly leaveHintId: string;
+    /** The "Start a voice conversation" button: focus returns to it when a voice conversation started in the tab ends. */
+    readonly startVoiceRef: RefObject<HTMLButtonElement | null>;
 }
+/** The ids the tab row and the two tab panels share (`AIAssistantPanel` makes them). */
+export interface LiveAvatarTabIds {
+    readonly chatTab: string;
+    readonly avatarTab: string;
+    readonly chatPanel: string;
+    readonly avatarPanel: string;
+    readonly leaveHint: string;
+}
+/**
+ * The Avatar tab's state as the panel provides it to the views below it: the
+ * chat area, the voice session and the seam's own hooks. Closed by default, so
+ * a panel that provides nothing (every host without the tab) is today's.
+ */
+export interface LiveAvatarTabState {
+    /** The Avatar tab is the view on screen. */
+    readonly open: boolean;
+    /** Select Chat again: what something in the tab calls to hand the person back to the chat. */
+    readonly close: () => void;
+    /**
+     * The tab row's ids while it is shown, else null (or absent): only then is the chat region a tab panel, so a panel without the
+     * tab is today's markup, attribute for attribute.
+     */
+    readonly ids?: LiveAvatarTabIds | null;
+    /** A full-surface overlay (History, the preview) covers the panel: the tab under it is not shown (D4). */
+    readonly covered?: boolean;
+}
+/**
+ * @internal Provided by `AIAssistantPanel` and read by the assistant's own
+ * views; not part of the module's public surface.
+ */
+export declare const LiveAvatarTabContext: import('react').Context<LiveAvatarTabState>;
+/** @internal The Avatar tab's state (`LiveAvatarTabContext`): closed without a panel that offers it. */
+export declare function useLiveAvatarTab(): LiveAvatarTabState;
+/** @internal The seam's tab part, or null: what the chat area draws the open tab with. */
+export declare function useLiveAvatarTabSeam(): LiveAvatarTabSeam | null;
+/**
+ * @internal For `AIAssistantPanel`: whether the seam offers the Avatar tab now. False without a tab part, and then nothing is
+ * subscribed to.
+ */
+export declare function useLiveAvatarTabOffered(tab: LiveAvatarTabSeam | undefined): boolean;
 /**
  * The avatar's ON flag as a store, read with `useSyncExternalStore`: the voice
  * session subscribes and nothing above it re-renders. It must be STABLE, and
@@ -28,7 +133,9 @@ export interface AssistantLiveAvatarSeam {
  * ★★ ON is only ever the person's own click, on a control the host offers
  * only while `voiceLive` says a voice conversation is live, and a paid session
  * starts only then: no avatar after its conversation has ended. The panel
- * switches the avatar OFF, never ON.
+ * switches the avatar OFF, never ON. The one other place is the Avatar tab
+ * (BOFF-9341), whose own Turn on starts the avatar with or without a voice
+ * conversation, and whose avatar ends when the tab closes.
  */
 export interface LiveAvatarEnabledStore {
     subscribe: (onChange: () => void) => () => void;
@@ -39,7 +146,9 @@ export interface LiveAvatarEnabledStore {
      * Called at the end of EVERY voice conversation, even when the avatar is
      * already OFF; again for any ON while a failed one is still on screen; and
      * by the compact view's stop. So it must be idempotent and cheap. It touches
-     * no audio: a reply already playing is the speech engine's to finish.
+     * no audio: a reply already playing is the speech engine's to finish. None
+     * of the three end calls is made while the Avatar tab is open: the tab owns
+     * its avatar then.
      */
     switchOff: () => void;
     /**
@@ -53,7 +162,12 @@ export declare const LiveAvatarSeamProvider: FC<{
     value?: AssistantLiveAvatarSeam;
     children: ReactNode;
 }>;
-/** The stage component, or null — which is what every host without an avatar gets. */
+/**
+ * The stage component, or null — which is what every host without an avatar
+ * gets, and what the voice stage gets while the Avatar tab is open: the tab is
+ * then the one place the avatar is shown, and the voice stage draws its
+ * waveform (BOFF-9341).
+ */
 export declare function useLiveAvatarStage(): ComponentType<LiveAvatarStageProps> | null;
 /**
  * The engine the speech provider should be handed, or `undefined` for "use your
@@ -88,6 +202,14 @@ export declare function useLiveAvatarOn(): boolean;
  *  - Switched OFF: hands-free stays OFF. Nothing turns it back on behind the person's back, and the
  *    copy (`avatar.handsFreeOff`) says so and where to turn it back on (More options).
  *
+ * ★ ONE notice per avatar, shared by every view that mounts this guard (BOFF-9341: the voice session
+ * and the Avatar tab). Whichever of them sees the ON first switches hands-free off; every one of them
+ * then says so, so a voice conversation started after the tab's Turn on still explains it. Which view
+ * SHOWS the notice is the views' call: the tab while no voice conversation is live, the session's
+ * strip otherwise, so it is said in exactly one place. It is kept while any of them is mounted and
+ * the avatar stays ON, and goes with the last of them (a microtask late, so React's development
+ * double mount keeps it, as component state was kept before).
+ *
  * Without a seam nothing here subscribes to, reads or writes anything.
  */
 export declare function useLiveAvatarHandsFreeGuard(): boolean;
@@ -113,6 +235,13 @@ export declare function useLiveAvatarHandsFreeGuard(): boolean;
  * ★ Adjusted DURING RENDER, as `AIAssistantPanel` adjusts its preview flag: no
  * frame shows the stale view, and the update is conditional on the state it
  * replaces, so it cannot loop.
+ *
+ * ★★ The Avatar tab (BOFF-9341). While it is open it shows the avatar, so this
+ * holds nothing: the user's choice, and whatever changes meanwhile lets go.
+ * When it closes on an avatar Voice turned on, in this conversation
+ * (`heldByVoice`, critic #9), the avatar stays ON, and over the compact view
+ * the hold shows it again here. Any other avatar of the tab ends as the tab
+ * closes, so nothing is held for it: no frame shows a stage going away.
  */
 export declare function useLiveAvatarVoiceView(chosen: VoiceView, ended: boolean): VoiceView;
 /**
@@ -144,6 +273,9 @@ export declare function useLiveAvatarMiniIndicatorShown(): boolean;
  * comes after the microphone control, so Tab meets the strip's own control
  * first.
  *
+ * ★ Hidden while the Avatar tab is open (BOFF-9341): the tab shows the avatar,
+ * and its own Turn off, right above the strip.
+ *
  * ★ "Avatar on" is a state, not a label. The control is an icon named by
  * `avatar.stop`, so no button is named for the opposite of what it does, and
  * its name is all of its words (WCAG 2.5.3, as the session's End).

package/dist/shared/assistant/ui/assistantLiveAvatarSeam.js

@@ -5,104 +5,163 @@ import { ASSISTANT_VOICE_SESSION_ATTR as i } from "./panelOverlays.js";
 import { createContext as a, useContext as o, useEffect as s, useLayoutEffect as c, useMemo as l, useRef as u, useState as d, useSyncExternalStore as f } from "react";
 import { VideoOff as p } from "lucide-react";
 import { jsx as m, jsxs as h } from "react/jsx-runtime";
-//#region src/shared/assistant/ui/assistantLiveAvatarSeam.tsx
-var g = a(null), _ = ({ value: e, children: t }) => /* @__PURE__ */ m(g.Provider, {
+var g = a({
+	open: !1,
+	close: () => {},
+	ids: null,
+	covered: !1
+});
+function _() {
+	return o(g);
+}
+function v() {
+	return o(x)?.tab ?? null;
+}
+var y = {
+	subscribe: () => () => {},
+	getSnapshot: () => !1
+};
+function b(e) {
+	let t = e?.offered ?? y;
+	return f(t.subscribe, t.getSnapshot, t.getSnapshot);
+}
+var x = a(null), S = ({ value: e, children: t }) => /* @__PURE__ */ m(x.Provider, {
 	value: e ?? null,
 	children: t
 });
-function v() {
-	return o(g)?.Stage ?? null;
+function C() {
+	let e = o(x)?.Stage ?? null;
+	return _().open ? null : e;
 }
-function y(e) {
+function w(e) {
 	let r = f(n, t, t), i = e?.decorateSpeechEngine;
 	return l(() => i ? i(r) : void 0, [i, r]);
 }
-var b = {
+var T = {
 	subscribe: () => () => {},
 	getSnapshot: () => !1,
 	switchOff: () => {},
 	voiceLive: () => {}
 };
-function x(e) {
+function E(e) {
 	return e?.Stage ? e.enabled : void 0;
 }
-function S(e) {
-	let t = e ?? b;
+function D(e) {
+	let t = e ?? T;
 	return f(t.subscribe, t.getSnapshot, t.getSnapshot);
 }
-function C() {
-	return S(o(g)?.enabled);
+function O() {
+	return D(o(x)?.enabled);
 }
-function w() {
-	let t = o(g)?.enabled, [n, r] = d(null);
+function k() {
+	let t = o(x)?.enabled, n = t ? M(t) : A, r = f(n.subscribe, n.isShown, n.isShown);
 	return s(() => {
 		if (!t) return;
-		let n = () => {
+		let r = () => {
 			if (!t.getSnapshot()) {
-				r(null);
+				n.set(!1);
 				return;
 			}
-			let n = e.getState();
-			n.handsFreeInterrupt && (n.setHandsFreeInterrupt(!1), r(() => t));
-		};
-		n();
-		let i = t.subscribe(n), a = e.subscribe(n);
+			let r = e.getState();
+			r.handsFreeInterrupt && (r.setHandsFreeInterrupt(!1), n.set(!0));
+		}, i = n.hold();
+		r();
+		let a = t.subscribe(r), o = e.subscribe(r);
 		return () => {
-			i(), a();
+			a(), o(), i();
 		};
-	}, [t]), n !== null && n === t;
+	}, [t, n]), r;
+}
+var A = {
+	subscribe: () => () => {},
+	isShown: () => !1,
+	set: () => {},
+	hold: () => () => {}
+}, j = /* @__PURE__ */ new WeakMap();
+function M(e) {
+	let t = j.get(e);
+	if (t) return t;
+	let n = !1, r = 0, i = /* @__PURE__ */ new Set(), a = (e) => {
+		if (n !== e) {
+			n = e;
+			for (let e of [...i]) e();
+		}
+	}, o = {
+		subscribe: (e) => (i.add(e), () => {
+			i.delete(e);
+		}),
+		isShown: () => n,
+		set: a,
+		hold: () => {
+			r += 1;
+			let e = !1;
+			return () => {
+				e || (e = !0, --r, queueMicrotask(() => {
+					r === 0 && a(!1);
+				}));
+			};
+		}
+	};
+	return j.set(e, o), o;
 }
-function T(e, t) {
-	let n = o(g);
-	E(n?.enabled, t);
-	let r = x(n), i = S(r), [a, s] = d(() => ({
-		on: i,
+function N(e, t) {
+	let n = o(x), r = _().open;
+	P(n?.enabled, t, r);
+	let i = E(n), a = D(i), [s, c] = d(() => ({
+		on: a,
 		chosen: e,
-		open: i && e === "mini"
+		tabOpen: r,
+		open: a && e === "mini" && !r
 	}));
-	if (!r) return e;
-	let c = a.open;
-	return (a.on !== i || a.chosen !== e) && (c = a.on !== i && i && e === "mini", s({
-		on: i,
+	if (!i) return e;
+	let l = s.open;
+	return (s.on !== a || s.chosen !== e || s.tabOpen !== r) && (l = r ? !1 : s.tabOpen ? a && e === "mini" && n?.tab?.heldByVoice() === !0 : s.on !== a && a && e === "mini", c({
+		on: a,
 		chosen: e,
-		open: c
-	})), c && !t ? "panel" : e;
+		tabOpen: r,
+		open: l
+	})), l && !t && !r ? "panel" : e;
 }
-function E(e, t) {
-	let n = u(0);
-	s(() => {
+function P(e, t, n) {
+	let r = u(0), i = u(n);
+	c(() => {
+		i.current = n;
+	}, [n]), s(() => {
 		if (!e) return;
-		let r = ++n.current, i = (e) => queueMicrotask(() => {
-			n.current === r && e();
-		}), a = () => i(() => {
-			e.voiceLive(!1), e.switchOff();
+		let n = ++r.current, a = (e) => queueMicrotask(() => {
+			r.current === n && e();
+		}), o = () => {
+			i.current || e.switchOff();
+		}, s = () => a(() => {
+			e.voiceLive(!1), o();
 		});
-		if (!t) return i(() => e.voiceLive(!0)), a;
-		a();
-		let o = e.getSnapshot();
+		if (!t) return a(() => e.voiceLive(!0)), s;
+		s();
+		let c = e.getSnapshot();
 		return e.subscribe(() => {
-			let t = o;
-			o = e.getSnapshot(), o && !t && i(() => e.switchOff());
+			let t = c;
+			c = e.getSnapshot(), c && !t && a(o);
 		});
 	}, [e, t]);
 }
-function D() {
-	return S(x(o(g)));
+function F() {
+	let e = D(E(o(x))), t = _().open;
+	return e && !t;
 }
-var O = () => {
-	let e = x(o(g)), t = S(e);
-	return e && t ? /* @__PURE__ */ m(j, {
+var I = () => {
+	let e = E(o(x)), t = D(e), n = _().open;
+	return e && t && !n ? /* @__PURE__ */ m(z, {
 		onStop: e.switchOff,
 		isOn: e.getSnapshot
 	}) : null;
-}, k = "[data-testid=\"assistant-voice-orb\"]", A = "[data-testid=\"assistant-voice-end\"]", j = ({ onStop: e, isOn: t }) => {
+}, L = "[data-testid=\"assistant-voice-orb\"]", R = "[data-testid=\"assistant-voice-end\"]", z = ({ onStop: e, isOn: t }) => {
 	let n = r(), a = u(null), o = u(t);
 	return c(() => {
 		let e = a.current, t = o.current;
 		return () => {
 			if (!e?.contains(e.ownerDocument.activeElement)) return;
-			let n = e.closest(`[${i}]`), r = t() ? null : n?.querySelector(k);
-			(r && !r.hasAttribute("disabled") ? r : n?.querySelector(A))?.focus();
+			let n = e.closest(`[${i}]`), r = t() ? null : n?.querySelector(L);
+			(r && !r.hasAttribute("disabled") ? r : n?.querySelector(R))?.focus();
 		};
 	}, []), /* @__PURE__ */ h("div", {
 		ref: a,
@@ -125,4 +184,4 @@ var O = () => {
 	});
 };
 //#endregion
-export { O as LiveAvatarMiniIndicator, _ as LiveAvatarSeamProvider, w as useLiveAvatarHandsFreeGuard, D as useLiveAvatarMiniIndicatorShown, C as useLiveAvatarOn, y as useLiveAvatarSpeechEngine, v as useLiveAvatarStage, T as useLiveAvatarVoiceView };
+export { I as LiveAvatarMiniIndicator, S as LiveAvatarSeamProvider, g as LiveAvatarTabContext, k as useLiveAvatarHandsFreeGuard, F as useLiveAvatarMiniIndicatorShown, O as useLiveAvatarOn, w as useLiveAvatarSpeechEngine, C as useLiveAvatarStage, _ as useLiveAvatarTab, b as useLiveAvatarTabOffered, v as useLiveAvatarTabSeam, N as useLiveAvatarVoiceView };

package/dist/shared/assistant/ui/avatar/AssistantAvatarTab.d.ts

@@ -0,0 +1,13 @@
+import { FC } from 'react';
+import { LiveAvatarTabSeam, LiveAvatarTabVoice } from '../assistantLiveAvatarSeam';
+export interface AssistantAvatarTabProps {
+    readonly tab: LiveAvatarTabSeam;
+    /** This panel's id, and the Avatar tab that labels it. */
+    readonly id: string;
+    readonly labelledBy: string;
+    readonly leaveHintId: string;
+    /** Nothing covers the tab (D4): see `LiveAvatarTabProps.shown`. */
+    readonly shown: boolean;
+    readonly voice: LiveAvatarTabVoice;
+}
+export declare const AssistantAvatarTab: FC<AssistantAvatarTabProps>;

package/dist/shared/assistant/ui/avatar/AssistantAvatarTab.js

@@ -0,0 +1,70 @@
+import { ASSISTANT_VOICE_SESSION_ATTR as e } from "../panelOverlays.js";
+import { useLiveAvatarHandsFreeGuard as t } from "../assistantLiveAvatarSeam.js";
+import { useEffect as n, useLayoutEffect as r, useRef as i, useState as a } from "react";
+import { jsx as o } from "react/jsx-runtime";
+//#region src/shared/assistant/ui/avatar/AssistantAvatarTab.tsx
+var s = 180;
+function c(t, n) {
+	let [i, o] = a(0);
+	return r(() => {
+		if (!n) return;
+		let r = t.current?.parentElement?.querySelector(`[${e}]`);
+		if (!r) return;
+		let i = () => {
+			let e = typeof r.getBoundingClientRect == "function" ? r.getBoundingClientRect().height : 0;
+			o(Math.round(e));
+		};
+		if (i(), typeof ResizeObserver > "u") return;
+		let a = new ResizeObserver(i);
+		return a.observe(r), () => a.disconnect();
+	}, [t, n]), n ? i > 0 ? i : s : 0;
+}
+function l() {
+	if (typeof document > "u") return !1;
+	let e = document.activeElement;
+	return e === null || e === document.body || !e.isConnected || e.hasAttribute("data-assistant-panel");
+}
+var u = ({ tab: e, id: a, labelledBy: s, leaveHintId: u, shown: d, voice: f }) => {
+	let p = i(null), m = i(null), h = t(), g = c(p, f.live), _ = i(null);
+	r(() => {
+		let t = (_.current?.setup ?? 0) + 1;
+		return _.current = {
+			tab: e,
+			setup: t
+		}, e.setOpen(!0), () => {
+			queueMicrotask(() => {
+				let n = _.current;
+				n !== null && n.tab === e && n.setup !== t || e.setOpen(!1);
+			});
+		};
+	}, [e]);
+	let v = i(f.live);
+	return n(() => {
+		let e = v.current;
+		v.current = f.live, !(!e || f.live) && l() && m.current?.focus();
+	}, [f.live]), /* @__PURE__ */ o("div", {
+		ref: p,
+		role: "tabpanel",
+		id: a,
+		"aria-labelledby": s,
+		className: "absolute inset-0 z-[5] flex flex-col bg-bg-surface",
+		"data-testid": "assistant-avatar-tab",
+		children: /* @__PURE__ */ o("div", {
+			className: "flex min-h-0 flex-1 flex-col overflow-y-auto px-4 pt-4",
+			style: {
+				paddingBottom: g + 16,
+				scrollPaddingBottom: g + 16
+			},
+			"data-testid": "assistant-avatar-tab-column",
+			children: /* @__PURE__ */ o(e.View, {
+				shown: d,
+				voice: f,
+				handsFreeOff: h,
+				leaveHintId: u,
+				startVoiceRef: m
+			})
+		})
+	});
+};
+//#endregion
+export { u as AssistantAvatarTab };

package/dist/shared/assistant/ui/composer/AssistantComposer.d.ts

@@ -55,6 +55,24 @@ interface Props {
      * sandbox while the person is still typing (BOFF-7801).
      */
     onDraftStart?: () => void;
+    /**
+     * ★ BOFF-9341: something covers the composer (the Avatar tab). Dictation
+     * stops, keeping every word it heard in the draft, and stays stopped: a
+     * microphone recording behind a surface the person cannot see is a privacy
+     * problem, and the tab's own voice conversation needs the microphone.
+     */
+    suspendDictation?: boolean;
+    /**
+     * Told what holds the voice conversation back here (BOFF-9341): a Send
+     * saving its attachments, and dictation holding the microphone. The rest of
+     * the composer's check comes from the props it is given.
+     */
+    onVoiceStateChange?: (state: AssistantComposerVoiceState) => void;
+}
+/** What in the composer holds a voice conversation back (`onVoiceStateChange`). */
+export interface AssistantComposerVoiceState {
+    readonly committing: boolean;
+    readonly dictating: boolean;
 }
 /**
  * AssistantComposer — the v2 input surface (per the ai-assistant-v2 mockups).