@burdenoff/website-sdk 2026.1028.1 → 2026.1031.1

package/dist/types-CndbmBK-.d.mts

@@ -0,0 +1,68 @@
+/**
+ * BOFF-9797. The shapes shared by the site-wide assistant panel (the package root) and the live avatar's sub-path
+ * (`@burdenoff/website-sdk/avatar-live`).
+ *
+ * Types only, on purpose: the root imports this file for its types and nothing else, so the root bundle never carries
+ * any of the sub-path's code or its media library. The panel reaches the sub-path only through the loader its host
+ * passes in (`live.load`), and only after the visitor has agreed to start.
+ */
+/** What the receive-only room tells the panel. */
+type ReceiveOnlyEvent = 
+/** One of the speaker's tracks (the avatar worker's video or audio) is subscribed and attached. */
+{
+    type: "speaker-track";
+    kind: "video" | "audio";
+}
+/** The avatar worker left the room: the session is over on the server's side. */
+ | {
+    type: "speaker-left";
+}
+/**
+ * Whether the browser is holding back sound or video until the visitor taps (Safari and iOS, mostly). While `true`,
+ * the panel offers "Tap to turn on sound", which calls `enablePlayback` from that tap.
+ */
+ | {
+    type: "playback-blocked";
+    blocked: boolean;
+}
+/**
+ * The room connection closed without the panel asking. `byServer` when the server closed it (the room was deleted
+ * or closed, or this viewer removed); otherwise the connection was lost.
+ */
+ | {
+    type: "disconnected";
+    byServer: boolean;
+};
+interface ReceiveOnlyJoinOptions {
+    /** The room server: `join.livekitUrl` from the create answer. Only a `wss:` URL is accepted. */
+    url: string;
+    /** `join.participantToken` from the create answer: subscribe-only and short-lived. Never logged. */
+    token: string;
+    /** `join.workerIdentity` from the create answer: the one participant whose video and audio are subscribed. */
+    workerIdentity: string;
+    /** Where the speaker's video plays. */
+    video: HTMLVideoElement;
+    /** Where the speaker's voice plays. */
+    audio: HTMLAudioElement;
+    /** Called for every {@link ReceiveOnlyEvent}. */
+    onEvent: (event: ReceiveOnlyEvent) => void;
+}
+/** A joined room. */
+interface ReceiveOnlySession {
+    /**
+     * Resume what the browser held back (`playback-blocked`). Call it from the visitor's tap or click: browsers allow
+     * sound only from a gesture.
+     */
+    enablePlayback: () => Promise<void>;
+    /** Leave the room and detach the speaker's tracks. Safe to call more than once. */
+    leave: () => Promise<void>;
+}
+/**
+ * What `live.load` resolves to: the `@burdenoff/website-sdk/avatar-live` module, whose `joinReceiveOnly` joins a room
+ * that can only watch and listen.
+ */
+interface AvatarLiveModule {
+    joinReceiveOnly: (options: ReceiveOnlyJoinOptions) => Promise<ReceiveOnlySession>;
+}
+
+export type { AvatarLiveModule as A, ReceiveOnlyJoinOptions as R, ReceiveOnlySession as a, ReceiveOnlyEvent as b };

package/dist/types-CndbmBK-.d.ts

@@ -0,0 +1,68 @@
+/**
+ * BOFF-9797. The shapes shared by the site-wide assistant panel (the package root) and the live avatar's sub-path
+ * (`@burdenoff/website-sdk/avatar-live`).
+ *
+ * Types only, on purpose: the root imports this file for its types and nothing else, so the root bundle never carries
+ * any of the sub-path's code or its media library. The panel reaches the sub-path only through the loader its host
+ * passes in (`live.load`), and only after the visitor has agreed to start.
+ */
+/** What the receive-only room tells the panel. */
+type ReceiveOnlyEvent = 
+/** One of the speaker's tracks (the avatar worker's video or audio) is subscribed and attached. */
+{
+    type: "speaker-track";
+    kind: "video" | "audio";
+}
+/** The avatar worker left the room: the session is over on the server's side. */
+ | {
+    type: "speaker-left";
+}
+/**
+ * Whether the browser is holding back sound or video until the visitor taps (Safari and iOS, mostly). While `true`,
+ * the panel offers "Tap to turn on sound", which calls `enablePlayback` from that tap.
+ */
+ | {
+    type: "playback-blocked";
+    blocked: boolean;
+}
+/**
+ * The room connection closed without the panel asking. `byServer` when the server closed it (the room was deleted
+ * or closed, or this viewer removed); otherwise the connection was lost.
+ */
+ | {
+    type: "disconnected";
+    byServer: boolean;
+};
+interface ReceiveOnlyJoinOptions {
+    /** The room server: `join.livekitUrl` from the create answer. Only a `wss:` URL is accepted. */
+    url: string;
+    /** `join.participantToken` from the create answer: subscribe-only and short-lived. Never logged. */
+    token: string;
+    /** `join.workerIdentity` from the create answer: the one participant whose video and audio are subscribed. */
+    workerIdentity: string;
+    /** Where the speaker's video plays. */
+    video: HTMLVideoElement;
+    /** Where the speaker's voice plays. */
+    audio: HTMLAudioElement;
+    /** Called for every {@link ReceiveOnlyEvent}. */
+    onEvent: (event: ReceiveOnlyEvent) => void;
+}
+/** A joined room. */
+interface ReceiveOnlySession {
+    /**
+     * Resume what the browser held back (`playback-blocked`). Call it from the visitor's tap or click: browsers allow
+     * sound only from a gesture.
+     */
+    enablePlayback: () => Promise<void>;
+    /** Leave the room and detach the speaker's tracks. Safe to call more than once. */
+    leave: () => Promise<void>;
+}
+/**
+ * What `live.load` resolves to: the `@burdenoff/website-sdk/avatar-live` module, whose `joinReceiveOnly` joins a room
+ * that can only watch and listen.
+ */
+interface AvatarLiveModule {
+    joinReceiveOnly: (options: ReceiveOnlyJoinOptions) => Promise<ReceiveOnlySession>;
+}
+
+export type { AvatarLiveModule as A, ReceiveOnlyJoinOptions as R, ReceiveOnlySession as a, ReceiveOnlyEvent as b };

package/dist/{use-progressive-reveal-C0hkdu_i.d.ts → use-explore-chat-DunjG-3p.d.ts}

@@ -1,4 +1,4 @@
-import { b as ExploreCatalog, c as ExploreMessage, d as ExploreFeedbackRating, e as ExploreFeedbackReason, f as ExploreLimits } from './explore-types-_9UJu6EA.js';
+import { E as ExploreCatalog, a as ExploreMessage, b as ExploreFeedbackRating, c as ExploreFeedbackReason, d as ExploreLimits } from './explore-types-Bb2Ih3d8.js';
 
 /** What travels on the wire — mirrors `ExploreAttachmentInput`. */
 interface ExploreAttachmentPayload {
@@ -207,6 +207,14 @@ interface UseExploreChatResult {
      */
     isSharedView: boolean;
     canSend: boolean;
+    /**
+     * BOFF-9797. This visitor's conversation token as it stands at the call, or null (no conversation yet, or a
+     * read-only shared view, whose `?c=` secret is not a conversation token).
+     *
+     * A function rather than a field on purpose: nothing renders, serialises or logs it with the rest of this object.
+     * The live avatar reads it once, into the body of its create request, which is the only place it goes.
+     */
+    getConversationToken: () => string | null;
 }
 /** Fallback limits, mirroring the server defaults in CONTRACT.md §3. */
 declare const FALLBACK_EXPLORE_LIMITS: ExploreLimits;
@@ -235,38 +243,4 @@ interface ArchivedExploreConversation {
 }
 declare function useExploreChat(options?: UseExploreChatOptions): UseExploreChatResult;
 
-/**
- * Stop whatever this SDK is reading aloud, from outside a component.
- *
- * A no-op when nothing of ours is speaking — deliberately, rather than calling
- * `speechSynthesis.cancel()` unconditionally, which would also silence a host page that is
- * using the same queue for its own reasons.
- */
-declare function stopSpeaking(): void;
-interface UseSpeechOutputOptions {
-    /** BCP-47 tag to read in. Omit to let the platform pick its default voice. */
-    lang?: string;
-}
-interface UseSpeechOutputResult {
-    /**
-     * False when this browser has no synthesiser, or has one that was asked to speak and did
-     * not. Render no control at all when it is false — see the note at the top of the file.
-     */
-    supported: boolean;
-    speaking: boolean;
-    speak: (text: string) => void;
-    stop: () => void;
-    toggle: (text: string) => void;
-}
-declare function useSpeechOutput({ lang, }?: UseSpeechOutputOptions): UseSpeechOutputResult;
-
-/**
- * The part of `text` that is currently on screen.
- *
- * @param text    everything that has arrived so far — `content` once the turn completes,
- *                `partialContent` while it runs.
- * @param settled true once the turn is COMPLETED or FAILED and `text` will not grow again.
- */
-declare function useProgressiveReveal(text: string, settled: boolean): string;
-
-export { DEFAULT_EXPLORE_EXAMPLE_PROMPTS as D, type ExploreChatError as E, FALLBACK_EXPLORE_LIMITS as F, type StagedAttachment as S, type UseExploreChatOptions as U, type ExploreChatErrorKind as a, type ExploreChatPhase as b, type ExploreEscalateOutcome as c, type ExploreEscalateResult as d, type UseExploreChatResult as e, type UseSpeechOutputOptions as f, type UseSpeechOutputResult as g, classifyExploreError as h, useProgressiveReveal as i, useSpeechOutput as j, stopSpeaking as s, useExploreChat as u };
+export { DEFAULT_EXPLORE_EXAMPLE_PROMPTS as D, type ExploreChatError as E, FALLBACK_EXPLORE_LIMITS as F, type StagedAttachment as S, type UseExploreChatOptions as U, type ExploreChatErrorKind as a, type ExploreChatPhase as b, type ExploreEscalateOutcome as c, type ExploreEscalateResult as d, type UseExploreChatResult as e, classifyExploreError as f, useExploreChat as u };

package/dist/{use-progressive-reveal-BFPWbEXy.d.mts → use-explore-chat-zRuoAin6.d.mts}

@@ -1,4 +1,4 @@
-import { b as ExploreCatalog, c as ExploreMessage, d as ExploreFeedbackRating, e as ExploreFeedbackReason, f as ExploreLimits } from './explore-types-_9UJu6EA.mjs';
+import { E as ExploreCatalog, a as ExploreMessage, b as ExploreFeedbackRating, c as ExploreFeedbackReason, d as ExploreLimits } from './explore-types-Bb2Ih3d8.mjs';
 
 /** What travels on the wire — mirrors `ExploreAttachmentInput`. */
 interface ExploreAttachmentPayload {
@@ -207,6 +207,14 @@ interface UseExploreChatResult {
      */
     isSharedView: boolean;
     canSend: boolean;
+    /**
+     * BOFF-9797. This visitor's conversation token as it stands at the call, or null (no conversation yet, or a
+     * read-only shared view, whose `?c=` secret is not a conversation token).
+     *
+     * A function rather than a field on purpose: nothing renders, serialises or logs it with the rest of this object.
+     * The live avatar reads it once, into the body of its create request, which is the only place it goes.
+     */
+    getConversationToken: () => string | null;
 }
 /** Fallback limits, mirroring the server defaults in CONTRACT.md §3. */
 declare const FALLBACK_EXPLORE_LIMITS: ExploreLimits;
@@ -235,38 +243,4 @@ interface ArchivedExploreConversation {
 }
 declare function useExploreChat(options?: UseExploreChatOptions): UseExploreChatResult;
 
-/**
- * Stop whatever this SDK is reading aloud, from outside a component.
- *
- * A no-op when nothing of ours is speaking — deliberately, rather than calling
- * `speechSynthesis.cancel()` unconditionally, which would also silence a host page that is
- * using the same queue for its own reasons.
- */
-declare function stopSpeaking(): void;
-interface UseSpeechOutputOptions {
-    /** BCP-47 tag to read in. Omit to let the platform pick its default voice. */
-    lang?: string;
-}
-interface UseSpeechOutputResult {
-    /**
-     * False when this browser has no synthesiser, or has one that was asked to speak and did
-     * not. Render no control at all when it is false — see the note at the top of the file.
-     */
-    supported: boolean;
-    speaking: boolean;
-    speak: (text: string) => void;
-    stop: () => void;
-    toggle: (text: string) => void;
-}
-declare function useSpeechOutput({ lang, }?: UseSpeechOutputOptions): UseSpeechOutputResult;
-
-/**
- * The part of `text` that is currently on screen.
- *
- * @param text    everything that has arrived so far — `content` once the turn completes,
- *                `partialContent` while it runs.
- * @param settled true once the turn is COMPLETED or FAILED and `text` will not grow again.
- */
-declare function useProgressiveReveal(text: string, settled: boolean): string;
-
-export { DEFAULT_EXPLORE_EXAMPLE_PROMPTS as D, type ExploreChatError as E, FALLBACK_EXPLORE_LIMITS as F, type StagedAttachment as S, type UseExploreChatOptions as U, type ExploreChatErrorKind as a, type ExploreChatPhase as b, type ExploreEscalateOutcome as c, type ExploreEscalateResult as d, type UseExploreChatResult as e, type UseSpeechOutputOptions as f, type UseSpeechOutputResult as g, classifyExploreError as h, useProgressiveReveal as i, useSpeechOutput as j, stopSpeaking as s, useExploreChat as u };
+export { DEFAULT_EXPLORE_EXAMPLE_PROMPTS as D, type ExploreChatError as E, FALLBACK_EXPLORE_LIMITS as F, type StagedAttachment as S, type UseExploreChatOptions as U, type ExploreChatErrorKind as a, type ExploreChatPhase as b, type ExploreEscalateOutcome as c, type ExploreEscalateResult as d, type UseExploreChatResult as e, classifyExploreError as f, useExploreChat as u };

package/dist/use-progressive-reveal-ppicEgzZ.d.mts

@@ -0,0 +1,35 @@
+/**
+ * Stop whatever this SDK is reading aloud, from outside a component.
+ *
+ * A no-op when nothing of ours is speaking — deliberately, rather than calling
+ * `speechSynthesis.cancel()` unconditionally, which would also silence a host page that is
+ * using the same queue for its own reasons.
+ */
+declare function stopSpeaking(): void;
+interface UseSpeechOutputOptions {
+    /** BCP-47 tag to read in. Omit to let the platform pick its default voice. */
+    lang?: string;
+}
+interface UseSpeechOutputResult {
+    /**
+     * False when this browser has no synthesiser, or has one that was asked to speak and did
+     * not. Render no control at all when it is false — see the note at the top of the file.
+     */
+    supported: boolean;
+    speaking: boolean;
+    speak: (text: string) => void;
+    stop: () => void;
+    toggle: (text: string) => void;
+}
+declare function useSpeechOutput({ lang, }?: UseSpeechOutputOptions): UseSpeechOutputResult;
+
+/**
+ * The part of `text` that is currently on screen.
+ *
+ * @param text    everything that has arrived so far — `content` once the turn completes,
+ *                `partialContent` while it runs.
+ * @param settled true once the turn is COMPLETED or FAILED and `text` will not grow again.
+ */
+declare function useProgressiveReveal(text: string, settled: boolean): string;
+
+export { type UseSpeechOutputOptions as U, type UseSpeechOutputResult as a, useSpeechOutput as b, stopSpeaking as s, useProgressiveReveal as u };

package/dist/use-progressive-reveal-ppicEgzZ.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Stop whatever this SDK is reading aloud, from outside a component.
+ *
+ * A no-op when nothing of ours is speaking — deliberately, rather than calling
+ * `speechSynthesis.cancel()` unconditionally, which would also silence a host page that is
+ * using the same queue for its own reasons.
+ */
+declare function stopSpeaking(): void;
+interface UseSpeechOutputOptions {
+    /** BCP-47 tag to read in. Omit to let the platform pick its default voice. */
+    lang?: string;
+}
+interface UseSpeechOutputResult {
+    /**
+     * False when this browser has no synthesiser, or has one that was asked to speak and did
+     * not. Render no control at all when it is false — see the note at the top of the file.
+     */
+    supported: boolean;
+    speaking: boolean;
+    speak: (text: string) => void;
+    stop: () => void;
+    toggle: (text: string) => void;
+}
+declare function useSpeechOutput({ lang, }?: UseSpeechOutputOptions): UseSpeechOutputResult;
+
+/**
+ * The part of `text` that is currently on screen.
+ *
+ * @param text    everything that has arrived so far — `content` once the turn completes,
+ *                `partialContent` while it runs.
+ * @param settled true once the turn is COMPLETED or FAILED and `text` will not grow again.
+ */
+declare function useProgressiveReveal(text: string, settled: boolean): string;
+
+export { type UseSpeechOutputOptions as U, type UseSpeechOutputResult as a, useSpeechOutput as b, stopSpeaking as s, useProgressiveReveal as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burdenoff/website-sdk",
-  "version": "2026.1028.1",
+  "version": "2026.1031.1",
   "description": "Shared SDK for Burdenoff product websites - reusable React components, utilities, and configurations",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -56,6 +56,11 @@
       "import": "./dist/store/index.mjs",
       "require": "./dist/store/index.js"
     },
+    "./avatar-live": {
+      "types": "./dist/avatar-live/index.d.ts",
+      "import": "./dist/avatar-live/index.mjs",
+      "require": "./dist/avatar-live/index.js"
+    },
     "./comparison": {
       "types": "./dist/comparison/index.d.ts",
       "import": "./dist/comparison/index.mjs",
@@ -68,7 +73,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node scripts/validate-avatar-live.mjs",
     "dev": "tsup --watch",
     "lint": "eslint . --ext .ts,.tsx",
     "lint:ci": "eslint src --max-warnings 0",
@@ -120,7 +125,13 @@
     "react-hook-form": ">=7.0.0",
     "sonner": ">=1.0.0",
     "tailwind-merge": ">=2.0.0",
-    "zod": ">=3.0.0"
+    "zod": ">=3.0.0",
+    "livekit-client": "^2.22.3"
+  },
+  "peerDependenciesMeta": {
+    "livekit-client": {
+      "optional": true
+    }
   },
   "dependencies": {
     "isomorphic-dompurify": "^2.36.0",
@@ -152,6 +163,7 @@
     "eslint-plugin-react-hooks": "^5.2.0",
     "globals": "^16.5.0",
     "jsdom": "^24.1.3",
+    "livekit-client": "2.22.3",
     "lucide-react": "^0.462.0",
     "prettier": "^3.9.6",
     "react": "^18.3.1",