@burdenoff/website-sdk 2026.1101.2 → 2026.1101.4

package/README.md

@@ -372,9 +372,16 @@ publishes audio, video or data, and it sends the avatar nothing to say.
   production nothing else is added, so no preflight has to complete while the
   page unloads. The server ends sessions on its own deadlines as well.
 - **Consent copy is versioned.** The panel shows a consent card only when it
-  holds reviewed copy for exactly the version the server names (the current
-  English copy is `web-consent-2026-10-31`, and `web-consent-2026-11` stays for
-  servers that still name it); otherwise the view stays as it was.
+  holds reviewed copy for exactly the version the server names; otherwise the
+  view stays as it was. `web-consent-2026-11-02` is product-neutral: its card
+  reads "a suggested question" on every site, whatever `productName` is, so
+  every product's site shows the same words and the server can bind one notice
+  digest for all of them (the card's title, intro, processing, storage and
+  privacy-link lines, each ending with a line feed: 760 bytes, SHA-256
+  `2e02b051ceb1163c14bc58fa63a954a12c0d1f2695029a6d4805922d74c793f7`).
+  `web-consent-2026-10-31` (which names the product, "a suggested Healthy Bowl
+  question") and `web-consent-2026-11` stay, unchanged, for servers that still
+  name them.
 - **How a session ended.** When the worker leaves, the server closes the room,
   or the session's time runs out with the room still open, the view says only
   "The live avatar has ended." (key `finished`). The browser
@@ -439,10 +446,191 @@ Testing hooks (`data-boff-explore`): `avatar-live` (with `data-phase`),
 `avatar-live-captions`, `avatar-live-countdown`, `avatar-live-sound`,
 `avatar-live-continue`, `avatar-live-back`, `avatar-live-bot-check`.
 
+#### Site assistant dock (`SiteAssistantDock`, every product site)
+
+`SiteAssistantDock` is the site-wide assistant in one component: the floating
+"Ask AI" button, which opens the assistant panel (`ExplorePanel`) over the
+current page, and that panel, with the site's product scope and its avatar. It
+replaces `<ExploreCta variant="floating" />` in a site's layout. The behaviour
+is HealthyBowl's, as approved there (BOFF-9697, BOFF-9796):
+
+- The button is still a real link to `/explore`: a modified click (new tab) and
+  a visitor without JavaScript reach the page; a plain click opens the compact
+  panel without leaving the page.
+- Expand and Restore keep the same conversation, and so do closing, reopening
+  and going to `/explore` and back: the panel and `/explore` share the
+  provider's one conversation. Nothing is asked of a server until the first
+  opening; the dock starts the provider's conversation then.
+- Escape and the phone's Back go expanded, then compact, then closed, through
+  history entries of the panel's own (the same URL, so the router stays put).
+  Closing stops the microphone and reading aloud, and focus goes back to the
+  button, which carries `aria-controls` and `aria-expanded`.
+- On `/explore` (`explorePath`, matched as the router matches it: ignoring case
+  and a trailing slash) there is no button and the panel hides; an open panel
+  shows again on the way out.
+- The panel keeps `bottomOffset` clear at the bottom of the window, so it never
+  covers the cookie banner's controls, and the floating button sits that much
+  higher (`calc(1.25rem + bottomOffset)`), so the banner does not cover the
+  button before the visitor answers it. Unset, the button is where it always was.
+- One dock, one panel, one conversation: render it once, in the layout every
+  route shares. A second dock mounted while one is there renders nothing, in
+  every build (a development build also logs an error); if the first one
+  unmounts, the second takes over.
+
+It **needs an `ExploreChatProvider` above it**. Without one a development build
+throws `SiteAssistantDock must be rendered under an ExploreChatProvider`, and a
+production build logs that error and renders the plain floating link to
+`/explore` that sites had before the dock.
+
+A site adds these lines.
+
+1. **The provider, at the app root**, inside the router and around the routes.
+   The dock starts it on the first opening, so `enabled` is for `/explore` only:
+
+   ```tsx
+   import { ExploreChatProvider, normalizeRoutePath } from '@burdenoff/website-sdk'
+
+   function SiteShell() {
+     const { pathname, search } = useLocation()
+     const onExplore = normalizeRoutePath(pathname) === '/explore'
+     // A shared conversation is /explore?c=<token> and nothing else.
+     const shareToken = onExplore ? new URLSearchParams(search).get('c') : null
+     const pageUrl =
+       typeof window === 'undefined' ? undefined : new URL(`${pathname}${search}`, window.location.origin).href
+     return (
+       <ExploreChatProvider
+         key={shareToken ?? ''}
+         enabled={onExplore}
+         productSlug={PRODUCT_SLUG}
+         locale={ASSISTANT.locale}
+         pageUrl={pageUrl}
+         shareToken={shareToken}
+       >
+         <AppRoutes />
+       </ExploreChatProvider>
+     )
+   }
+   ```
+
+2. **The config objects** (`src/config/assistant.ts`), built once at module
+   scope so the panel's memoised prompt list is not rebuilt on every render:
+
+   ```ts
+   import { websiteAvatarLive } from '@burdenoff/website-sdk'
+   import manifest from '@/data/avatar-manifest.<site>.en.json'
+
+   export const ASSISTANT = {
+     productSlug: PRODUCT_SLUG,
+     scope: 'product',
+     productName: 'Healthy Bowl', // the brand as a reader sees it
+     examplePrompts: PROBLEMS.map(({ problem }) => problem), // the questions the manifest lists
+     locale: import.meta.env.VITE_DEPLOY_ENV === 'alpha' ? 'en' : undefined,
+   } as const
+
+   export const AVATAR = {
+     src: '/avatar-faces/av_stock_001.webp',
+     live: websiteAvatarLive({
+       deployEnv: import.meta.env.VITE_DEPLOY_ENV,
+       siteKey: import.meta.env.VITE_AVATAR_TURNSTILE_SITE_KEY,
+       site: '<site>', // as the live avatar service knows it: `healthybowl`
+       manifestVersion: manifest.version,
+       load: () => import('@burdenoff/website-sdk/avatar-live'),
+     }),
+   }
+   ```
+
+3. **The dock in the layout**, in place of `<ExploreCta variant="floating" />`:
+
+   ```tsx
+   import { SiteAssistantDock } from '@burdenoff/website-sdk'
+
+   const { pathname } = useLocation()
+   const navigate = useNavigate()
+
+   <SiteAssistantDock
+     {...ASSISTANT}
+     avatar={AVATAR}
+     currentPath={pathname}
+     onNavigate={(path) => navigate(path)}
+     bottomOffset="var(--hb-cookie-banner-height, 0px)" // YOUR banner's variable, see below
+   />
+   ```
+
+   `bottomOffset` must name **the site's own cookie banner's height
+   variable**. The SDK sets no such variable and there is no shared name:
+   HealthyBowl's banner publishes `--hb-cookie-banner-height`, and another
+   site passes whatever its banner publishes. A banner that publishes none
+   leaves the panel and the button under it. We recommend every site's banner
+   publish its height as a CSS variable on `<html>` while it shows, and remove
+   it when it goes:
+
+   ```tsx
+   // In the site's cookie banner component.
+   const bannerRef = useRef<HTMLDivElement>(null)
+   useLayoutEffect(() => {
+     const banner = bannerRef.current
+     if (!banner) return
+     const root = document.documentElement
+     const publish = () =>
+       root.style.setProperty('--<site>-cookie-banner-height', `${banner.offsetHeight}px`)
+     publish()
+     const observer = new ResizeObserver(publish) // wrapping text, a resized window
+     observer.observe(banner)
+     return () => {
+       observer.disconnect()
+       root.style.removeProperty('--<site>-cookie-banner-height') // answered: nothing to keep clear
+     }
+   }, [])
+   ```
+
+   and keep the `, 0px` fallback in `bottomOffset`, so the dock sits at its
+   usual place whenever the banner is not on screen.
+
+4. **The build env var** `VITE_AVATAR_TURNSTILE_SITE_KEY`: the site's
+   Cloudflare Turnstile site key. `websiteAvatarLive` returns `undefined` (the
+   still picture and "Live avatar coming soon", no live avatar) when it is
+   unset or empty; on alpha (`VITE_DEPLOY_ENV=alpha`) it accepts Cloudflare's
+   always-pass test key `1x00000000000000000000AA` (the alpha gateway runs
+   Turnstile in dummy mode) or a real key; everywhere else, production
+   included, only a real-looking key (`0x…`, letters, digits, `_` and `-`, 18
+   to 64 characters) that is not one of Cloudflare's test keys (`1x…AA`,
+   `2x…AB`, `1x…BB`, `2x…BB`, `3x…FF`, or anything of their shape). Install
+   `livekit-client` on the site (see [Live avatar](#live-avatar-opt-in-receive-only)),
+   and declare the variable in `vite-env.d.ts`.
+   `websiteAvatarLive` trusts `VITE_DEPLOY_ENV`, so a production build must
+   never be labelled `alpha` (that would let a test key through the check);
+   the production gateway's real Turnstile secret would still reject a test
+   token, so the live avatar would fail to start rather than run unchecked.
+
+5. **The privacy anchor** `/privacy#live-avatar`: the live avatar's consent
+   card links there, so the site's privacy page needs an element with
+   `id="live-avatar"` describing the live avatar.
+
+6. **The still picture** `public/avatar-faces/av_stock_001.webp`: the approved
+   avatar picture the Avatar view shows (and shows instead of the live avatar
+   when it is off), copied from HealthyBowl's website.
+
+**`SiteAssistantDock` props**
+
+| Prop | Default | What it does |
+|---|---|---|
+| `productSlug`, `scope`, `productName`, `examplePrompts`, `locale` | – | Passed to the panel's chat unchanged. See [One product's own assistant](#one-products-own-assistant). |
+| `avatar` | – | `{ src, name?, live? }`: the Avatar view's still picture, and `live` (from `websiteAvatarLive`) to opt in to the live avatar. Absent: no Avatar view. |
+| `onNavigate` | – | The router's navigate, for links in the conversation. |
+| `bottomOffset` | `0px` | A CSS length kept clear at the bottom: the site's own cookie banner's height variable (HealthyBowl: `var(--hb-cookie-banner-height, 0px)`). The panel keeps it clear and the floating button sits that much higher. |
+| `className` | – | Extra classes for the floating button. |
+| `panelClassName` | – | Extra classes for the panel. |
+| `currentPath` | `window.location.pathname` | The router's path. Pass it: the fallback cannot see `pushState` navigations. |
+| `explorePath` | `/explore` | The button's link, the route the dock hides on, and the panel's share links. |
+| `label` | `Ask AI` | The button's label and accessible name. |
+| `id` | `boff-explore-panel` | The panel's id, for the button's `aria-controls`. |
+| `zIndex` | `50` | The panel's `z-index`. |
+
 **`ExploreCta` props**: `variant` (`'header' \| 'mobile' \| 'floating'`, required),
 `href` (default `/explore`), `label` (default `Ask AI`), `className`,
-`onNavigate`, `onClick`, `currentPath`. The `floating` variant hides itself on
-`/explore`. Pass `currentPath` from your router — the fallback
+`onNavigate`, `onClick`, `currentPath`, and, for `floating` only,
+`bottomOffset` (a CSS length to lift the bubble by, as on the dock). The
+`floating` variant hides itself on `/explore`. Pass `currentPath` from your router — the fallback
 (`window.location.pathname` + `popstate`) cannot observe SPA `pushState`
 navigations.
 

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

@@ -474,6 +474,21 @@ var CONSENT = /* @__PURE__ */ new Map([
         privacyLink: "How we handle this"
       }
     }
+  ],
+  [
+    // The words of web-consent-2026-10-31 with no product name in them: one notice, byte for byte, on every product's
+    // site, because the server binds one consent version and one notice digest for all of them.
+    "web-consent-2026-11-02",
+    {
+      en: {
+        title: "Live AI avatar (beta)",
+        introProduct: null,
+        intro: "This is an AI avatar, not a real person. It reads the assistant's first eligible answer to a suggested question aloud for up to a minute. The answer is AI-generated and can be wrong.",
+        processing: "When you start, Cloudflare checks for bots. The answer text goes to Google to create the voice. Our server sends that voice through LiveKit to Protoface, which makes the avatar video streamed through LiveKit. Your browser connects to LiveKit, which sees your IP address.",
+        storage: "Your microphone and camera are not used. We do not record the live session or store the generated voice. We keep a record of this consent. The privacy notice explains our safeguards, storage periods and the providers' processing. For people aged eighteen and over.",
+        privacyLink: "How we handle this"
+      }
+    }
   ]
 ]);
 function avatarConsentCopy(version, locale) {
@@ -1229,7 +1244,7 @@ function AvatarLiveView({
           className: "w-full max-w-sm rounded-lg border border-border p-4 text-start",
           children: [
             /* @__PURE__ */ jsxRuntime.jsx("h2", { id: consentTitleId, className: "text-base font-semibold", children: copy.title }),
-            /* @__PURE__ */ jsxRuntime.jsx("p", { className: "mt-2 text-sm", children: productName === null ? copy.intro : chunkO4GS3XPZ_js.fill(copy.introProduct, { product: productName }) }),
+            /* @__PURE__ */ jsxRuntime.jsx("p", { className: "mt-2 text-sm", children: productName === null || copy.introProduct === null ? copy.intro : chunkO4GS3XPZ_js.fill(copy.introProduct, { product: productName }) }),
             /* @__PURE__ */ jsxRuntime.jsx("p", { className: "mt-2 text-sm text-muted-foreground", children: copy.processing }),
             /* @__PURE__ */ jsxRuntime.jsx("p", { className: "mt-2 text-sm text-muted-foreground", children: copy.storage }),
             /* @__PURE__ */ jsxRuntime.jsxs(