@burdenoff/website-sdk 2026.1102.3 → 2026.1104.1

package/README.md

@@ -420,10 +420,24 @@ publishes audio, video or data, and it sends the avatar nothing to say.
   limits, region, language, paused, a question the avatar cannot read) is one
   short sentence and "Continue in Chat". A network or CORS failure, or a route
   that is not there, shows the view as it was before.
-- **Ending.** Stop, switching to Chat, closing the panel, hiding the page, and
-  the live avatar going off under a session (the panel's locale changing to one
+- **Ending.** Stop, closing the panel, leaving the page (`pagehide`), and the
+  live avatar going off under a session (the panel's locale changing to one
   whose strings have not been reviewed) all end the session with a `keepalive`
-  request and leave the room. The end is a simple CORS request: its body is a
+  request and leave the room. Once the create has been sent (connecting,
+  joining, speaking), switching to the Chat tab (or pressing Continue in Chat)
+  and hiding the page (another browser tab, another app) do **not** end it: the
+  Avatar pane is only hidden, the room's video and audio stay attached, and the
+  avatar speaks to the end the server planned for it, which a hidden page
+  cannot extend. Coming back to the Avatar tab shows the session as it is, with
+  the countdown to the server's end, and asks nothing again. Before the create,
+  nothing paid exists, so the Chat tab still calls off an availability check, a
+  "Start when ready" and a bot check, and a hidden page still calls off a
+  "Start when ready" and returns a bot check to the consent card, all with
+  nothing created. While a session is created, joined or played, Chat's own
+  read-aloud and dictation are held (`ExplorePage`'s `voiceHold`): a reading
+  under way stops, and both controls stay where they are, `aria-disabled`, with
+  the avatar's status line as their title, until the session ends; nothing in
+  Chat ends the session. The end is a simple CORS request: its body is a
   string and the SDK sets no `content-type`, so the browser sends it as
   `text/plain;charset=UTF-8` (which the gateway accepts for this route), and on
   production nothing else is added, so no preflight has to complete while the
@@ -510,9 +524,11 @@ publishes audio, video or data, and it sends the avatar nothing to say.
     of the same host for the validation check.
 - **Not verified in this package.** Every test here uses fakes: nothing reaches
   Turnstile, the gateway, the avatar service or the media room. Left to the
-  alpha test: real playback on iPhone Safari and Android Chrome; that
-  `page_hide` ends actually arrive from those browsers; and that the receive-only
-  token has `canPublish=false` and `canPublishData=false`, and a worker RPC
+  alpha test: real playback on iPhone Safari and Android Chrome; that the voice
+  keeps playing behind the Chat tab and in a background browser tab there (a
+  browser may suspend it; the server still ends the session at its planned
+  end); that `page_hide` ends actually arrive from those browsers; and that the
+  receive-only token has `canPublish=false` and `canPublishData=false`, and a worker RPC
   addressed to the viewer is dropped without disconnecting it (the media client
   answers incoming RPC requests on its own, so "never publishes" holds only as
   far as the token's permissions do).

package/dist/avatar-live-view/index.d.mts

@@ -9,6 +9,11 @@ interface AvatarLiveViewProps {
     live: ExplorePanelAvatarLive;
     /** The Avatar view is showing: the panel is open and its Avatar tab is selected. */
     active: boolean;
+    /**
+     * The panel is open, whichever tab it shows. With `active` it tells the Chat tab (open, not active: the pane is only
+     * hidden, and a session under way keeps playing) from the panel closing (not open: what is under way ends).
+     */
+    open: boolean;
     locale: ExploreLocale;
     /** The product the panel speaks for, when it is one product's own; null on the portfolio's. */
     productName: string | null;
@@ -19,8 +24,18 @@ interface AvatarLiveViewProps {
     };
     /** The Avatar tab as it was before the live avatar: shown whenever the live avatar is not offered or not reachable. */
     fallback: ReactNode;
-    /** Back to the Chat tab. Leaving the Avatar tab ends a session, like any other way out of it. */
+    /**
+     * Back to the Chat tab. Like the Chat tab itself, it calls off a start that has not been sent yet, and leaves a
+     * session under way speaking.
+     */
     onContinueInChat: () => void;
+    /**
+     * Told whenever the avatar's voice starts or stops being the page's: its status line while a session is being
+     * created, joined or played ("Connecting to the live avatar…", "The avatar is speaking."), and null otherwise (and
+     * when the view goes). The panel holds Chat's own read-aloud and dictation meanwhile, so the page never speaks in two
+     * voices and the microphone never takes down the avatar's.
+     */
+    onVoiceHold?: (line: string | null) => void;
     /** "Continue in Chat" in the panel's language: the panel's own word for it, so this chunk carries none of the panel's. */
     continueInChat: string;
     /**
@@ -51,6 +66,6 @@ interface AvatarLiveViewProps {
     /** The panel's conversation, null when there is no provider. */
     conversation: AvatarConversation | null;
 }
-declare function AvatarLiveView({ live, active, locale, productName, still, fallback, onContinueInChat, continueInChat, newChat, send, tryAsking, prompts, touchFirst, currentPath, off, base, headers, conversation, }: AvatarLiveViewProps): react.JSX.Element;
+declare function AvatarLiveView({ live, active, open, locale, productName, still, fallback, onContinueInChat, onVoiceHold, continueInChat, newChat, send, tryAsking, prompts, touchFirst, currentPath, off, base, headers, conversation, }: AvatarLiveViewProps): react.JSX.Element;
 
 export { AvatarLiveView, type AvatarLiveViewProps };

package/dist/avatar-live-view/index.d.ts

@@ -9,6 +9,11 @@ interface AvatarLiveViewProps {
     live: ExplorePanelAvatarLive;
     /** The Avatar view is showing: the panel is open and its Avatar tab is selected. */
     active: boolean;
+    /**
+     * The panel is open, whichever tab it shows. With `active` it tells the Chat tab (open, not active: the pane is only
+     * hidden, and a session under way keeps playing) from the panel closing (not open: what is under way ends).
+     */
+    open: boolean;
     locale: ExploreLocale;
     /** The product the panel speaks for, when it is one product's own; null on the portfolio's. */
     productName: string | null;
@@ -19,8 +24,18 @@ interface AvatarLiveViewProps {
     };
     /** The Avatar tab as it was before the live avatar: shown whenever the live avatar is not offered or not reachable. */
     fallback: ReactNode;
-    /** Back to the Chat tab. Leaving the Avatar tab ends a session, like any other way out of it. */
+    /**
+     * Back to the Chat tab. Like the Chat tab itself, it calls off a start that has not been sent yet, and leaves a
+     * session under way speaking.
+     */
     onContinueInChat: () => void;
+    /**
+     * Told whenever the avatar's voice starts or stops being the page's: its status line while a session is being
+     * created, joined or played ("Connecting to the live avatar…", "The avatar is speaking."), and null otherwise (and
+     * when the view goes). The panel holds Chat's own read-aloud and dictation meanwhile, so the page never speaks in two
+     * voices and the microphone never takes down the avatar's.
+     */
+    onVoiceHold?: (line: string | null) => void;
     /** "Continue in Chat" in the panel's language: the panel's own word for it, so this chunk carries none of the panel's. */
     continueInChat: string;
     /**
@@ -51,6 +66,6 @@ interface AvatarLiveViewProps {
     /** The panel's conversation, null when there is no provider. */
     conversation: AvatarConversation | null;
 }
-declare function AvatarLiveView({ live, active, locale, productName, still, fallback, onContinueInChat, continueInChat, newChat, send, tryAsking, prompts, touchFirst, currentPath, off, base, headers, conversation, }: AvatarLiveViewProps): react.JSX.Element;
+declare function AvatarLiveView({ live, active, open, locale, productName, still, fallback, onContinueInChat, onVoiceHold, continueInChat, newChat, send, tryAsking, prompts, touchFirst, currentPath, off, base, headers, conversation, }: AvatarLiveViewProps): react.JSX.Element;
 
 export { AvatarLiveView, type AvatarLiveViewProps };

package/dist/avatar-live-view/index.js

@@ -1026,11 +1026,13 @@ function clock(seconds) {
 function AvatarLiveView({
   live,
   active,
+  open,
   locale,
   productName,
   still,
   fallback,
   onContinueInChat,
+  onVoiceHold,
   continueInChat,
   newChat,
   send,
@@ -1078,9 +1080,19 @@ function AvatarLiveView({
   const askMaxLength = chatMaxLength !== void 0 && Number.isFinite(chatMaxLength) && chatMaxLength >= 1 ? Math.min(ASK_MAX_LENGTH, Math.floor(chatMaxLength)) : ASK_MAX_LENGTH;
   const [note, setNote] = react.useState(null);
   const [usedToday, setUsedToday] = react.useState(false);
+  const showing = active && !off;
+  const behindChat = open && !active && !off;
   const phaseRef = react.useRef(IDLE);
-  const latest = react.useRef({ live, locale, base, headers, off, currentPath });
-  latest.current = { live, locale, base, headers, off, currentPath };
+  const latest = react.useRef({
+    live,
+    locale,
+    base,
+    headers,
+    off,
+    currentPath,
+    showing
+  });
+  latest.current = { live, locale, base, headers, off, currentPath, showing };
   const conversationRef = react.useRef(conversation);
   conversationRef.current = conversation;
   const waitRef = react.useRef(null);
@@ -1099,6 +1111,10 @@ function AvatarLiveView({
     phaseRef.current = next;
     setPhase(next);
   }, []);
+  const inSight = react.useCallback(
+    () => latest.current.showing && (typeof document === "undefined" || document.visibilityState !== "hidden"),
+    []
+  );
   const setMode = react.useCallback((next) => {
     questionsRef.current = next;
     setQuestions(next);
@@ -1153,6 +1169,17 @@ function AvatarLiveView({
     },
     [go]
   );
+  const goLive = react.useCallback(() => {
+    const current = phaseRef.current;
+    const handle = sessionRef.current;
+    if (current.name !== "pending" || !handle) return;
+    handle.speakerArrived = true;
+    if (questionsRef.current === "any") {
+      noteUsedToday();
+      setUsedToday(true);
+    }
+    go({ name: "live", session: current.session });
+  }, [go]);
   const cancelStart = react.useCallback((reason) => {
     const run = startRef.current;
     if (!run) return;
@@ -1489,9 +1516,11 @@ function AvatarLiveView({
     }
   }, [cancelStart, cancelWaiting, finish, go, reoffer]);
   const leave = react.useCallback(
-    (reason) => {
+    (event) => {
       const current = phaseRef.current;
+      const reason = event === "user" || event === "chat" ? "user" : "page_hide";
       const how = reason === "user" ? "stopped" : "interrupted";
+      const keepsSession = event === "chat" || event === "hidden";
       switch (current.name) {
         case "checking": {
           if (reason !== "user") return;
@@ -1509,26 +1538,36 @@ function AvatarLiveView({
           go(reason === "user" ? IDLE : reoffer(current.offer));
           return;
         case "creating":
+          if (keepsSession) return;
           cancelStart(reason);
           go({ name: "ended", how });
           return;
         case "pending":
         case "live":
+          if (keepsSession) {
+            if (current.name === "pending" && sessionRef.current?.speakerArrived) {
+              goLive();
+            }
+            return;
+          }
           finish(how, reason);
           return;
         default:
           return;
       }
     },
-    [cancelStart, cancelWaiting, finish, go, reoffer]
+    [cancelStart, cancelWaiting, finish, go, goLive, reoffer]
   );
-  const showing = active && !off;
   react.useEffect(() => {
     if (!showing) {
-      leave("user");
+      leave(behindChat ? "chat" : "user");
       return;
     }
     const current = phaseRef.current;
+    if (current.name === "creating" || current.name === "pending" || current.name === "live") {
+      setNow(Date.now());
+      return;
+    }
     const offered = offeredNow();
     const used = offered !== null && claimedRef.current.has(offered);
     if (current.name === "ended" && used) return;
@@ -1541,7 +1580,7 @@ function AvatarLiveView({
     current.name === "checking" && checkRef.current === null) {
       check();
     }
-  }, [showing, check, leave, offeredNow]);
+  }, [showing, behindChat, check, leave, offeredNow]);
   react.useEffect(() => {
     if (askedLocale.current === locale) return;
     askedLocale.current = locale;
@@ -1628,7 +1667,9 @@ function AvatarLiveView({
       const wasLive = phaseRef.current.name === "live";
       switch (event.type) {
         case "speaker-track":
-          if (event.kind === "video") handle.speakerArrived = true;
+          if (event.kind !== "video") return;
+          handle.speakerArrived = true;
+          if (!inSight()) goLive();
           return;
         case "playback-blocked":
           setBlocked(event.blocked);
@@ -1645,7 +1686,7 @@ function AvatarLiveView({
           return;
       }
     },
-    [finish]
+    [finish, goLive, inSight]
   );
   react.useEffect(() => {
     if (phase.name !== "pending") return;
@@ -1719,11 +1760,23 @@ function AvatarLiveView({
     const timer = setInterval(() => setNow(Date.now()), 1e3);
     return () => clearInterval(timer);
   }, [ticking]);
+  const voiceLine = phase.name === "live" ? S.speaking : phase.name === "creating" || phase.name === "pending" ? S.connecting : null;
+  const onVoiceHoldRef = react.useRef(onVoiceHold);
+  onVoiceHoldRef.current = onVoiceHold;
+  react.useEffect(() => {
+    onVoiceHoldRef.current?.(voiceLine);
+  }, [voiceLine]);
+  react.useEffect(() => () => onVoiceHoldRef.current?.(null), []);
   react.useEffect(() => {
     if (typeof window === "undefined") return;
     const onPageHide = () => leave("page_hide");
     const onVisibility = () => {
-      if (document.visibilityState === "hidden") leave("page_hide");
+      if (document.visibilityState === "hidden") {
+        leave("hidden");
+        return;
+      }
+      const current = phaseRef.current.name;
+      if (current === "pending" || current === "live") setNow(Date.now());
     };
     window.addEventListener("pagehide", onPageHide);
     document.addEventListener("visibilitychange", onVisibility);
@@ -1829,17 +1882,7 @@ function AvatarLiveView({
     if (focused && focused !== document.body && focused.isConnected) return;
     rootRef.current?.querySelector(PRIMARY)?.focus();
   }, [active, phase.name, askState, shown.pendingAnswerId, blocked]);
-  const onPlaying = react.useCallback(() => {
-    const current = phaseRef.current;
-    const handle = sessionRef.current;
-    if (current.name !== "pending" || !handle) return;
-    handle.speakerArrived = true;
-    if (questionsRef.current === "any") {
-      noteUsedToday();
-      setUsedToday(true);
-    }
-    go({ name: "live", session: current.session });
-  }, [go]);
+  const onPlaying = goLive;
   const enablePlayback = react.useCallback(() => {
     void sessionRef.current?.joined?.enablePlayback().catch(() => void 0);
   }, []);