@convai/web-sdk 1.7.0-beta.2 → 1.8.0-beta.0

package/dist/vanilla/ConvaiWidget.js

@@ -3,9 +3,104 @@
  * Ports the React ConvaiWidget to vanilla TypeScript with DOM manipulation
  */
 import { AudioRenderer } from "./AudioRenderer";
-import { aeroTheme, injectGlobalStyles } from "./styles";
+import { aeroTheme, injectGlobalStyles, injectKeyframes, } from "./styles";
 import { Icons } from "./icons";
 import { ConvaiClient } from "../core/ConvaiClient";
+/**
+ * Positioning declarations for the widget root, keyed by `placement`. The
+ * `bottom-right` entry must stay byte-identical to the literals it replaces --
+ * the inline-style parity suite snapshots the resolved `cssText` and compares
+ * it to a committed fixture.
+ */
+/** Gap between a fixed-placement widget and the viewport edge it anchors to. */
+const PLACEMENT_INSET_PX = 24;
+const PLACEMENT_CSS = {
+    "bottom-right": `position: fixed; bottom: ${PLACEMENT_INSET_PX}px; right: ${PLACEMENT_INSET_PX}px;`,
+    "bottom-left": `position: fixed; bottom: ${PLACEMENT_INSET_PX}px; left: ${PLACEMENT_INSET_PX}px;`,
+    "top-right": `position: fixed; top: ${PLACEMENT_INSET_PX}px; right: ${PLACEMENT_INSET_PX}px;`,
+    "top-left": `position: fixed; top: ${PLACEMENT_INSET_PX}px; left: ${PLACEMENT_INSET_PX}px;`,
+    inline: "position: relative;",
+};
+/** The open panel's preferred size. Capped by `PANEL_MAX_*` — see below. */
+const PANEL_W_PX = 400;
+const PANEL_H_PX = 600;
+/**
+ * A ceiling on the open panel, so it can never be clipped by the viewport.
+ *
+ * The panel used to be a flat 400x600. The widget is `position: fixed`
+ * anchored `PLACEMENT_INSET_PX` from one edge, so on any viewport narrower
+ * than 448px — or shorter than 648px — the panel ran past the opposite edge
+ * and was silently cut off, with no scrollbar to reveal it, because fixed
+ * elements do not contribute to scrollable overflow. That is most phones: at
+ * 393px (iPhone 15 Pro) 30px of the panel sat off-screen, at 360px 63px did,
+ * and in landscape 233px of it — the entire header, including the close
+ * button — sat above the viewport, leaving nothing on screen to dismiss it.
+ *
+ * Expressed as `max-width`/`max-height` rather than folding the cap into the
+ * width with `min()`. Both compute the same thing, but they fail differently:
+ * a parser that does not know `min()` drops the whole declaration and the
+ * panel is left with no width at all, which is worse than the bug. An unknown
+ * `max-width` drops only the ceiling and leaves the previous behaviour intact.
+ * (Not hypothetical — happy-dom, which this package's own tests run in, parses
+ * the `max-width` form and discards the `min()` one.)
+ *
+ * Dynamic viewport units so mobile browser chrome is accounted for as it shows
+ * and hides, rather than sizing against a viewport the user cannot fully see.
+ * Applied to the container permanently rather than per state: the collapsed
+ * bubble is far below the ceiling, so it is unaffected.
+ */
+const PANEL_MAX_W = `calc(100dvw - ${PLACEMENT_INSET_PX * 2}px)`;
+const PANEL_MAX_H = `calc(100dvh - ${PLACEMENT_INSET_PX * 2}px)`;
+/** `convai-error{code:'mic-permission'}` per the embed's error-handling contract. */
+const MIC_PERMISSION_ERROR_CODE = "mic-permission";
+/**
+ * Distinguishes a microphone-permission denial from any other audio failure.
+ *
+ * Traced (not assumed): `client.audioControls.unmuteAudio()` delegates to
+ * `AudioManager.enableAudio()`, which calls
+ * `room.localParticipant.setMicrophoneEnabled(true)`. That's LiveKit's
+ * `setTrackEnabled()`, which on failure does `throw e` unchanged, from a
+ * `catch` around `createLocalTracks()`, which itself does `throw e` unchanged
+ * around `navigator.mediaDevices.getUserMedia()`. `AudioManager.enableAudio()`
+ * also just does `throw error` in its own catch. Nothing on that path wraps or
+ * replaces the error, so a user's permission denial reaches here as the exact
+ * `DOMException` `getUserMedia()` produced, with `.name === 'NotAllowedError'`
+ * (`'PermissionDeniedError'` is the old pre-spec name some browsers used).
+ */
+function isMicPermissionDenial(error) {
+    const name = error?.name;
+    return name === "NotAllowedError" || name === "PermissionDeniedError";
+}
+/**
+ * Wraps a mic-permission denial so a consumer of the client's `error`
+ * channel can tell it apart from a generic failure without knowing anything
+ * about `DOMException` internals -- it only has to check `error.code`. The
+ * original error is preserved on `.cause` for anyone who wants the detail.
+ */
+function toMicPermissionError(cause) {
+    const err = new Error("Microphone access was denied. Continuing in text-only mode.");
+    err.name = "ConvaiMicPermissionError";
+    err.code = MIC_PERMISSION_ERROR_CODE;
+    err.cause = cause;
+    return err;
+}
+/**
+ * Routes a failed `enableAudio()`/`unmuteAudio()` call onto the client's
+ * *existing* `error` channel -- the same one `ConvaiClient` already uses --
+ * instead of letting it become an unhandled rejection (the click-handler
+ * site) or vanish into a bare `console.error` (the auto-voice-mode sites).
+ * `console.error` is kept alongside for local debugging; this just adds the
+ * event emission next to it. `client.emit` is called defensively since it
+ * isn't part of the public `IConvaiClient` surface -- see the `emit?` field
+ * on `VanillaWidgetOptions.convaiClient` in `./types.ts`.
+ */
+function reportMicFailure(client, logLabel, error) {
+    console.error(logLabel, error);
+    const payload = isMicPermissionDenial(error)
+        ? toMicPermissionError(error)
+        : error;
+    client.emit?.("error", payload);
+}
 /**
  * Create a Convai chat widget in the specified container
  *
@@ -42,6 +137,21 @@ import { ConvaiClient } from "../core/ConvaiClient";
  * ```
  */
 export function createConvaiWidget(container, options) {
+    /**
+     * Where global styles and `@keyframes` are injected.
+     *
+     * An explicit `options.styleTarget` wins and is used verbatim. Otherwise we
+     * fall back to deriving it from the container's current root — which is what
+     * every existing caller relies on, but only works when the container is
+     * already attached to its final root. A caller that builds a detached
+     * subtree and appends it to a shadow root afterwards must pass
+     * `styleTarget` explicitly, or the styles land in `document.head` and the
+     * shadow tree renders unstyled with no error.
+     */
+    const styleTarget = options.styleTarget ??
+        (container.getRootNode() instanceof ShadowRoot
+            ? container.getRootNode()
+            : document);
     // Create client if not provided - guarantee it's defined
     const client = options.convaiClient ||
         (() => {
@@ -61,8 +171,14 @@ export function createConvaiWidget(container, options) {
             });
         })();
     const { showVideo = true, showScreenShare = true, defaultVoiceMode = true, onConnect, onDisconnect, onMessage, } = options;
+    // Unknown/typo'd values fall back to the default rather than throwing --
+    // a bad `placement` attribute on a customer's page must not blank the
+    // widget.
+    const placement = options.placement && options.placement in PLACEMENT_CSS
+        ? options.placement
+        : "bottom-right";
     // Inject global styles
-    injectGlobalStyles();
+    injectGlobalStyles(styleTarget);
     // State
     let isOpen = false;
     let isSettingsOpen = false;
@@ -76,6 +192,22 @@ export function createConvaiWidget(container, options) {
     let hasEnteredDefaultVoiceMode = false;
     /** True after we have connected at least once; used to call reconnect() instead of connect() when opening after disconnect */
     let hasConnectedBefore = false;
+    /**
+     * True from the moment an open is requested on a *disconnected* client
+     * until that open either completes or is cancelled.
+     *
+     * `isOpen` alone cannot express this: the first open awaits a real
+     * `connect()` (0.5-3s in production) and only flips `isOpen` afterwards, so
+     * for that whole window the widget is neither open nor idle. Without this
+     * flag `close()` sees `isOpen === false` and no-ops -- and the connect then
+     * pops the panel open behind the user -- while `toggle()` sees the same
+     * `false`, starts a *second* open, and lands on the already-connecting
+     * branch that opens immediately. Every entry point below treats
+     * `pendingOpen` as "open" for the purpose of deciding what a close/toggle
+     * means, and `handleToggle` re-checks it before committing `setIsOpen(true)`
+     * so a cancellation during the await is honoured.
+     */
+    let pendingOpen = false;
     // DOM elements (will be created below)
     let rootElement;
     let morphingContainer;
@@ -89,6 +221,13 @@ export function createConvaiWidget(container, options) {
     let settingsTray;
     let floatingVideo;
     let voiceModeOverlay;
+    let connectingOverlay;
+    /**
+     * Elements captured at creation. IDs are scoped per DOM tree, so
+     * document.getElementById() returns null when the widget is mounted
+     * inside a shadow root. Every element here is created in this file.
+     */
+    const refs = {};
     // Audio Analysis State
     let audioContext = null;
     let analyzer = null;
@@ -97,14 +236,18 @@ export function createConvaiWidget(container, options) {
     let source = null;
     // Fetch character info - matches React useCharacterInfo hook
     const fetchCharacterInfo = async () => {
-        if (!client.apiKey || !client.characterId)
+        // Prefer authToken over apiKey, matching the precedence ConvaiClient
+        // uses when building /connect headers -- a client carrying both must
+        // behave identically in both places.
+        const credential = client.authToken ?? client.apiKey;
+        if (!credential || !client.characterId)
             return;
         try {
             const response = await fetch("https://api.convai.com/character/get", {
                 method: "POST",
                 headers: {
                     "Content-Type": "application/json",
-                    "API-AUTH-TOKEN": client.apiKey,
+                    "API-AUTH-TOKEN": credential,
                 },
                 body: JSON.stringify({ charID: client.characterId }),
             });
@@ -129,23 +272,34 @@ export function createConvaiWidget(container, options) {
         rootElement = document.createElement("div");
         rootElement.className = "convai-widget";
         rootElement.style.cssText = `
-      position: fixed;
-      bottom: 1.5rem;
-      right: 1.5rem;
-      z-index: ${aeroTheme.zIndex.modal};
-      font-family: ${aeroTheme.typography.fontFamily.primary};
+      ${PLACEMENT_CSS[placement]}
+      z-index: var(--convai-z-index, ${aeroTheme.zIndex.modal});
+      font-family: var(--convai-font, ${aeroTheme.typography.fontFamily.primary});
     `;
         // Morphing container
         morphingContainer = document.createElement("div");
+        // `part="launcher"` is precise only while collapsed: this same element
+        // morphs into the open panel (400x600, capped to the viewport — see PANEL_MAX_W)
+        // and carries that panel's background,
+        // radius and shadow. See the `part="panel"` call site below for the full
+        // semantics a host needs to know.
+        morphingContainer.setAttribute("part", "launcher");
+        // NOTE on border-radius: deliberately NOT themable. `--convai-radius`
+        // drives the open panel only. One token cannot serve both geometries --
+        // `--convai-radius: 8px` would squircle the circular launcher, and `50%`
+        // would turn the panel into an ellipse. A dedicated
+        // `--convai-launcher-radius` can be added additively later if wanted.
         morphingContainer.style.cssText = `
       position: relative;
-      width: 4rem;
-      height: 4rem;
-      background: ${aeroTheme.colors.glass.backdrop};
+      width: var(--convai-launcher-size, 64px);
+      height: var(--convai-launcher-size, 64px);
+      max-width: ${PANEL_MAX_W};
+      max-height: ${PANEL_MAX_H};
+      background: var(--convai-panel-bg, ${aeroTheme.colors.glass.backdrop});
       backdrop-filter: ${aeroTheme.glass.backdrop};
       border: ${aeroTheme.glass.border};
       border-radius: 50%;
-      box-shadow: ${aeroTheme.shadows.glass};
+      box-shadow: var(--convai-shadow, ${aeroTheme.shadows.glass});
       transition: all 0.3s ease-in-out;
       overflow: hidden;
       display: flex;
@@ -166,10 +320,39 @@ export function createConvaiWidget(container, options) {
       transform: scale(1);
     `;
         const convaiLogo = Icons.ConvaiLogo("xl", "idle");
-        convaiLogo.style.color = aeroTheme.colors.convai.light;
+        convaiLogo.style.color = `var(--convai-accent, ${aeroTheme.colors.convai.light})`;
         buttonContent.appendChild(convaiLogo);
         // Chat content
         chatContent = document.createElement("div");
+        // ----------------------------------------------------------------------
+        // `launcher` / `panel` part semantics. Read before writing theming docs.
+        //
+        // This widget morphs rather than swapping trees: `morphingContainer` IS
+        // the 64px circle AND the open panel, animating between them (see
+        // setIsOpen). It therefore owns every painted surface property of both
+        // states -- background, border, border-radius, box-shadow. `buttonContent`
+        // and `chatContent` are transparent `inset: 0` overlays that only
+        // cross-fade their contents.
+        //
+        // So, precisely:
+        //   ::part(launcher)  -> morphingContainer. Paints the collapsed circle
+        //                        AND the open panel; there is no rule that hits
+        //                        only one. This is the surface part.
+        //   ::part(panel)     -> chatContent. The open state's *content layer*:
+        //                        useful for padding, colour, font, opacity. It has
+        //                        no background, no border and no radius of its
+        //                        own, so `::part(panel){border-radius}` does
+        //                        nothing -- set radius via ::part(launcher) or
+        //                        `--convai-radius` (which is panel-scoped).
+        //
+        // Assessed and deliberately not "fixed": moving `launcher` onto
+        // buttonContent would make `::part(launcher){background}` state-specific
+        // but would silently break `border-radius` and `box-shadow` on it, since
+        // buttonContent is clipped by the container's own radius + overflow:
+        // hidden. Correcting this properly needs a separate launcher element
+        // instead of a morph -- a rendering change, out of scope here.
+        // ----------------------------------------------------------------------
+        chatContent.setAttribute("part", "panel");
         chatContent.style.cssText = `
       position: absolute;
       inset: 0;
@@ -190,11 +373,19 @@ export function createConvaiWidget(container, options) {
         contentElement.style.cssText = `
       flex: 1;
       overflow-y: auto;
-      padding: 1rem;
+      padding: 16px;
       background: transparent;
+      position: relative;
     `;
         messageListElement = createMessageList();
         contentElement.appendChild(messageListElement);
+        // Connecting overlay -- shown until the bot is ready. Appended last, not
+        // to match DOM order (position: absolute + z-index: 100, set inside
+        // createConnectingOverlay, is what keeps it on top regardless of source
+        // order) but so inserting it doesn't shift every existing sibling's
+        // index-based path in the inline-style-parity fixture.
+        connectingOverlay = createConnectingOverlay();
+        contentElement.appendChild(connectingOverlay);
         // Footer
         footerElement = createFooter();
         chatContent.appendChild(headerElement);
@@ -211,7 +402,7 @@ export function createConvaiWidget(container, options) {
         container.appendChild(floatingVideo);
         container.appendChild(rootElement);
         // Event listeners
-        morphingContainer.addEventListener("click", handleToggle);
+        morphingContainer.addEventListener("click", handleLauncherClick);
     };
     // Create Voice Mode Overlay
     const createVoiceModeOverlay = () => {
@@ -222,13 +413,13 @@ export function createConvaiWidget(container, options) {
       left: 50%;
       transform: translate(-50%, -50%);
       text-align: center;
-      padding: 1rem;
+      padding: 16px;
       z-index: 10;
       pointer-events: auto;
       display: none;
       flex-direction: column;
       align-items: center;
-      gap: 1.5rem;
+      gap: 24px;
     `;
         // Bars Container
         const barsContainer = document.createElement("div");
@@ -260,15 +451,17 @@ export function createConvaiWidget(container, options) {
         const statusContainer = document.createElement("div");
         const statusTitle = document.createElement("div");
         statusTitle.id = "voice-mode-title";
+        refs.voiceModeTitle = statusTitle;
         statusTitle.style.cssText = `
       font-size: 14px;
       font-weight: 500;
-      color: ${aeroTheme.colors.text.primary};
-      margin-bottom: 0.5rem;
+      color: var(--convai-panel-fg, ${aeroTheme.colors.text.primary});
+      margin-bottom: 8px;
     `;
         statusTitle.textContent = "Voice Only Mode";
         const statusSubtitle = document.createElement("div");
         statusSubtitle.id = "voice-mode-subtitle";
+        refs.voiceModeSubtitle = statusSubtitle;
         statusSubtitle.style.cssText = `
       font-size: 12px;
       color: ${aeroTheme.colors.text.secondary};
@@ -279,6 +472,79 @@ export function createConvaiWidget(container, options) {
         overlay.appendChild(statusContainer);
         return overlay;
     };
+    // Create Connecting Overlay -- matches React's inline AnimatePresence
+    // block exactly (ConvaiWidget.tsx:681-737): shown whenever
+    // `isConnected && !isBotReady`, covering just the content area (not the
+    // header/footer) so the chrome stays interactive while the character
+    // joins. Persistent in the DOM like voiceModeOverlay above -- toggled via
+    // opacity/pointer-events rather than mounted/unmounted, since this file has
+    // no AnimatePresence-style exit-animation machinery. Visibility is driven
+    // by updateConnectingOverlay().
+    const createConnectingOverlay = () => {
+        const overlay = document.createElement("div");
+        overlay.id = "convai-connecting-overlay";
+        overlay.style.cssText = `
+      position: absolute;
+      inset: 0;
+      z-index: 100;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      gap: 16px;
+      background: rgba(255, 255, 255, 0.95);
+      opacity: 0;
+      pointer-events: none;
+      transition: opacity 0.3s;
+    `;
+        // Keyframes live in the shadow-safe injector (styles.ts), not
+        // document.head -- @keyframes defined there do not resolve for shadow
+        // content. Idempotent; also called from createSettingsTray().
+        injectKeyframes(styleTarget);
+        // Spinning logo: a full turn every 2s, linear, infinite.
+        const spinWrapper = document.createElement("div");
+        spinWrapper.className = "convai-connecting-spin";
+        spinWrapper.style.cssText = `
+      display: inline-flex;
+      animation: convaiConnectingSpin 2s linear infinite;
+    `;
+        const logo = Icons.ConvaiLogo("xl", "connecting");
+        // Themable, like every other accent usage in this file (see
+        // theming.test.ts) -- var() with the exact literal React passes
+        // (`aeroTheme.colors.convai.light`) as the fallback, so an unset
+        // --convai-accent renders identically to the React value.
+        logo.style.color = `var(--convai-accent, ${aeroTheme.colors.convai.light})`;
+        spinWrapper.appendChild(logo);
+        overlay.appendChild(spinWrapper);
+        // Pulsing "Connecting to {characterName}..." label.
+        const label = document.createElement("div");
+        label.id = "convai-connecting-text";
+        label.className = "convai-connecting-pulse";
+        label.style.cssText = `
+      font-size: 14px;
+      font-weight: 500;
+      color: ${aeroTheme.colors.text.secondary};
+      animation: convaiConnectingPulse 2s ease-in-out infinite;
+    `;
+        refs.connectingLabel = label;
+        overlay.appendChild(label);
+        return overlay;
+    };
+    /** Shows/hides the connecting overlay and refreshes its label. Called
+     * from updateHeader() so every existing call site (stateChange, botReady,
+     * connect/disconnect via stateChange, character-info fetch, ...) stays in
+     * sync automatically. */
+    const updateConnectingOverlay = () => {
+        if (!connectingOverlay)
+            return;
+        const label = refs.connectingLabel;
+        if (label) {
+            label.textContent = `Connecting to ${characterName}...`;
+        }
+        const shouldShow = client.state.isConnected && !client.isBotReady;
+        connectingOverlay.style.opacity = shouldShow ? "1" : "0";
+        connectingOverlay.style.pointerEvents = shouldShow ? "auto" : "none";
+    };
     // Audio Analysis State for Voice Mode
     let audioLevels = Array(40).fill(0);
     let targetLevels = Array(40).fill(0.05);
@@ -295,14 +561,14 @@ export function createConvaiWidget(container, options) {
         // Update colors based on state
         bars.forEach((bar) => {
             bar.style.backgroundColor = isTalking
-                ? aeroTheme.colors.convai.light
+                ? `var(--convai-accent, ${aeroTheme.colors.convai.light})`
                 : isListening
                     ? aeroTheme.colors.text.primary
                     : aeroTheme.colors.neutral[400];
         });
         // Update Text
-        const title = document.getElementById("voice-mode-title");
-        const subtitle = document.getElementById("voice-mode-subtitle");
+        const title = refs.voiceModeTitle;
+        const subtitle = refs.voiceModeSubtitle;
         if (title) {
             title.textContent = isTalking
                 ? "Character Speaking..."
@@ -408,7 +674,15 @@ export function createConvaiWidget(container, options) {
             updateAudioBars();
         }
         catch (e) {
-            console.error("Audio analysis setup failed:", e);
+            // Fourth mic-acquiring call site: this getUserMedia() is independent
+            // of client.audioControls (it's a separate analyser-only stream, not
+            // routed through AudioManager), but a denial here is the identical
+            // failure mode -- most commonly a mid-session permission revocation,
+            // since by the time voice mode is entered the mic has usually already
+            // been granted via unmuteAudio(). Same helper, same channel, so a
+            // consumer sees one consistent signal regardless of which internal
+            // path acquired the mic.
+            reportMicFailure(client, "Audio analysis setup failed:", e);
         }
     };
     const stopAudioAnalysis = () => {
@@ -425,13 +699,14 @@ export function createConvaiWidget(container, options) {
     // Create header
     const createHeader = () => {
         const header = document.createElement("div");
+        header.setAttribute("part", "header");
         header.style.cssText = `
       display: flex;
       align-items: center;
       justify-content: space-between;
-      padding: 1rem;
+      padding: 16px;
       border-bottom: 1px solid ${aeroTheme.colors.neutral[200]};
-      background: white;
+      background: var(--convai-panel-bg, white);
       position: relative;
     `;
         // Close button on the left
@@ -439,10 +714,10 @@ export function createConvaiWidget(container, options) {
         const chevronIcon = Icons.ChevronDown("md");
         closeButton.appendChild(chevronIcon);
         closeButton.style.cssText = `
-      font-size: 1.25rem;
+      font-size: 20px;
       color: ${aeroTheme.colors.text.secondary};
       cursor: pointer;
-      padding: 0.25rem;
+      padding: 4px;
       transition: ${aeroTheme.transitions.fast};
       background: transparent;
       border: none;
@@ -459,21 +734,22 @@ export function createConvaiWidget(container, options) {
       transform: translateX(-50%);
       display: flex;
       align-items: center;
-      gap: 0.5rem;
+      gap: 8px;
       font-size: ${aeroTheme.typography.fontSize.base};
       font-weight: ${aeroTheme.typography.fontWeight.semibold};
-      color: ${aeroTheme.colors.text.primary};
+      color: var(--convai-panel-fg, ${aeroTheme.colors.text.primary});
     `;
         titleSection.id = "convai-widget-title";
+        refs.widgetTitle = titleSection;
         // Settings button on the right
         const settingsButton = document.createElement("button");
         const moreIcon = Icons.MoreVertical("md");
         settingsButton.appendChild(moreIcon);
         settingsButton.style.cssText = `
-      font-size: 1.5rem;
+      font-size: 24px;
       color: ${aeroTheme.colors.text.secondary};
       cursor: pointer;
-      padding: 0.25rem;
+      padding: 4px;
       transition: ${aeroTheme.transitions.fast};
       background: transparent;
       border: none;
@@ -490,7 +766,7 @@ export function createConvaiWidget(container, options) {
     };
     // Update header with character info
     const updateHeader = () => {
-        const titleSection = document.getElementById("convai-widget-title");
+        const titleSection = refs.widgetTitle;
         if (!titleSection)
             return;
         titleSection.innerHTML = "";
@@ -499,8 +775,8 @@ export function createConvaiWidget(container, options) {
             img.src = characterImage;
             img.alt = characterName;
             img.style.cssText = `
-        width: 1.5rem;
-        height: 1.5rem;
+        width: 24px;
+        height: 24px;
         border-radius: 50%;
         object-fit: cover;
         border: 1.5px solid ${getBotStatusColor().color};
@@ -530,7 +806,7 @@ export function createConvaiWidget(container, options) {
       padding: 0;
       display: inline-flex;
       align-items: center;
-      margin-left: 0.5rem;
+      margin-left: 8px;
       outline: none;
       transition: transform 0.1s ease-out;
     `;
@@ -551,7 +827,7 @@ export function createConvaiWidget(container, options) {
             voiceBadge.textContent = "VOICE";
             voiceBadge.style.cssText = `
         font-size: 10px;
-        color: ${aeroTheme.colors.convai.light};
+        color: var(--convai-accent, ${aeroTheme.colors.convai.light});
         font-weight: 500;
         margin-left: 8px;
         padding: 2px 6px;
@@ -616,15 +892,21 @@ export function createConvaiWidget(container, options) {
             listeningTag.insertBefore(dot, listeningTag.firstChild);
             titleSection.appendChild(listeningTag);
         }
+        // Every call site that refreshes the header (stateChange, botReady,
+        // connect/disconnect via stateChange, character-info fetch, ...) also
+        // needs the connecting overlay re-evaluated -- it depends on the same
+        // `isConnected`/`isBotReady`/`characterName` inputs.
+        updateConnectingOverlay();
     };
     // Create message list
     const createMessageList = () => {
         const list = document.createElement("div");
         list.id = "convai-message-list";
+        list.setAttribute("part", "messages");
         list.style.cssText = `
       display: flex;
       flex-direction: column;
-      gap: 0.75rem;
+      gap: 12px;
       min-height: 100%;
     `;
         return list;
@@ -633,22 +915,23 @@ export function createConvaiWidget(container, options) {
     const createFooter = () => {
         const footer = document.createElement("div");
         footer.style.cssText = `
-      padding: 1rem;
+      padding: 16px;
       border-top: 1px solid ${aeroTheme.colors.neutral[200]};
-      background: white;
+      background: var(--convai-panel-bg, white);
       display: flex;
-      gap: 0.5rem;
+      gap: 8px;
       align-items: center;
       position: relative;
     `;
         // Voice Mode Exit Button (Initially hidden)
         const voiceExitButton = document.createElement("button");
         voiceExitButton.id = "convai-voice-exit-btn";
+        refs.voiceExitBtn = voiceExitButton;
         const exitIcon = Icons.PhoneOff("md");
         voiceExitButton.appendChild(exitIcon);
         voiceExitButton.style.cssText = `
-      width: 2.25rem;
-      height: 2.25rem;
+      width: 36px;
+      height: 36px;
       border-radius: 50%;
       background: ${aeroTheme.colors.error[500]};
       color: white;
@@ -659,19 +942,31 @@ export function createConvaiWidget(container, options) {
       margin: 0 auto;
       border: none;
     `;
-        voiceExitButton.addEventListener("click", async () => {
+        voiceExitButton.addEventListener("click", () => {
+            // Deliberately a *sync* listener. It used to be `async` with a bare
+            // `await client.audioControls.muteAudio()` and no try/catch: on the
+            // LiveKit path that call rethrows when the room has dropped, so a
+            // network blip mid-call plus a tap on exit leaked an unhandled
+            // rejection onto the host page *and* skipped the two lines below,
+            // stranding the user in the voice overlay with no way out.
+            //
+            // The mute is not dropped -- `applyVoiceMode()` -> `updateVoiceMode()`
+            // performs it (conditionally, if the mic is live) inside the exit
+            // branch, where a failure is now reported rather than fatal. Exiting
+            // the UI is unconditional either way: the overlay must never outlive
+            // the user's decision to leave it.
             client.sendInterruptMessage();
-            await client.audioControls.muteAudio(); // Mute on exit
             isVoiceMode = false;
-            updateVoiceMode();
+            applyVoiceMode();
         });
         footer.appendChild(voiceExitButton);
         // Standard Footer Content (Mic + Input)
         const standardContent = document.createElement("div");
         standardContent.id = "convai-footer-standard";
+        refs.footerStandard = standardContent;
         standardContent.style.cssText = `
       display: flex;
-      gap: 0.5rem;
+      gap: 8px;
       align-items: center;
       width: 100%;
     `;
@@ -684,15 +979,16 @@ export function createConvaiWidget(container, options) {
       align-items: center;
     `;
         inputElement = document.createElement("input");
+        inputElement.setAttribute("part", "input");
         inputElement.type = "text";
         inputElement.placeholder = "Conversation";
         inputElement.style.cssText = `
       width: 100%;
-      padding: 0.75rem 2.75rem 0.75rem 1rem;
+      padding: 12px 44px 12px 16px;
       border-radius: ${aeroTheme.borderRadius.full};
       border: 1px solid ${aeroTheme.colors.neutral[300]};
       background: ${aeroTheme.colors.glass.medium};
-      color: ${aeroTheme.colors.text.primary};
+      color: var(--convai-panel-fg, ${aeroTheme.colors.text.primary});
       font-size: ${aeroTheme.typography.fontSize.sm};
       transition: ${aeroTheme.transitions.fast};
       outline: none;
@@ -708,16 +1004,22 @@ export function createConvaiWidget(container, options) {
         // Send button
         const sendButton = document.createElement("button");
         sendButton.id = "convai-send-button";
+        // This button is dual-role -- it sends text when the input has a draft,
+        // and toggles voice mode when empty -- but there is no separate mic
+        // element, so only the send-button part applies. `mic-button` is
+        // reserved for a future version that splits the two; see parts.test.ts.
+        sendButton.setAttribute("part", "send-button");
+        refs.sendButton = sendButton;
         const sendIcon = Icons.Send("md");
         sendButton.appendChild(sendIcon);
         sendButton.style.cssText = `
       position: absolute;
-      right: 0.375rem;
-      width: 2.25rem;
-      height: 2.25rem;
+      right: 6px;
+      width: 36px;
+      height: 36px;
       border-radius: 50%;
       background: transparent; /* Initial transparent for voice toggle */
-      color: ${aeroTheme.colors.text.primary};
+      color: var(--convai-panel-fg, ${aeroTheme.colors.text.primary});
       display: flex;
       align-items: center;
       justify-content: center;
@@ -732,9 +1034,19 @@ export function createConvaiWidget(container, options) {
             else {
                 // Toggle Voice Mode
                 client.sendInterruptMessage();
-                await client.audioControls.unmuteAudio(); // Unmute on enter
-                isVoiceMode = true;
-                updateVoiceMode();
+                try {
+                    await client.audioControls.unmuteAudio(); // Unmute on enter
+                    isVoiceMode = true;
+                    // Awaited so this try/catch actually covers it -- bare, the promise
+                    // escaped the block it looks like it belongs to.
+                    await updateVoiceMode();
+                }
+                catch (error) {
+                    // isVoiceMode is only flipped after a successful unmute, so a
+                    // denial here leaves the widget in text mode, not stranded
+                    // mid-transition into voice mode.
+                    reportMicFailure(client, "Failed to enable microphone:", error);
+                }
             }
         });
         inputContainer.appendChild(inputElement);
@@ -751,7 +1063,7 @@ export function createConvaiWidget(container, options) {
       position: absolute;
       top: 60px;
       right: 16px;
-      background: white;
+      background: var(--convai-panel-bg, white);
       border-radius: ${aeroTheme.borderRadius.xl};
       box-shadow: ${aeroTheme.shadows.xl};
       padding: 0;
@@ -766,17 +1078,7 @@ export function createConvaiWidget(container, options) {
       overflow: hidden;
     `;
         // Add animation keyframes if not present
-        if (!document.getElementById("convai-widget-keyframes")) {
-            const style = document.createElement("style");
-            style.id = "convai-widget-keyframes";
-            style.textContent = `
-        @keyframes popIn {
-          from { opacity: 0; transform: scale(0.95) translateY(-10px); }
-          to { opacity: 1; transform: scale(1) translateY(0); }
-        }
-      `;
-            document.head.appendChild(style);
-        }
+        injectKeyframes(styleTarget);
         // Horizontal Settings Row Container
         const settingsRow = document.createElement("div");
         settingsRow.style.cssText = `
@@ -805,7 +1107,7 @@ export function createConvaiWidget(container, options) {
                 ? "#10b981"
                 : isDestructive
                     ? "#ef4444"
-                    : aeroTheme.colors.text.primary};
+                    : `var(--convai-panel-fg, ${aeroTheme.colors.text.primary})`};
         transition: ${aeroTheme.transitions.fast};
         min-width: 50px;
       `;
@@ -855,6 +1157,7 @@ export function createConvaiWidget(container, options) {
             videoIcon.style.height = "18px";
             const videoBtn = createOption(videoIcon, "Video", handleToggleVideo, isVideoVisible);
             videoBtn.id = "convai-settings-video-btn";
+            refs.settingsVideoBtn = videoBtn;
             settingsRow.appendChild(videoBtn);
         }
         // Screen Share - only show if connection type is video
@@ -867,6 +1170,7 @@ export function createConvaiWidget(container, options) {
             shareIcon.style.height = "18px";
             const shareBtn = createOption(shareIcon, "Screen", handleToggleScreenShare, isSharing);
             shareBtn.id = "convai-settings-share-btn";
+            refs.settingsShareBtn = shareBtn;
             settingsRow.appendChild(shareBtn);
         }
         // Disconnect
@@ -903,7 +1207,7 @@ export function createConvaiWidget(container, options) {
                 ? "#10b981"
                 : isDestructive
                     ? "#ef4444"
-                    : aeroTheme.colors.text.primary};
+                    : `var(--convai-panel-fg, ${aeroTheme.colors.text.primary})`};
         transition: ${aeroTheme.transitions.fast};
         min-width: 50px;
       `;
@@ -953,6 +1257,7 @@ export function createConvaiWidget(container, options) {
             videoIcon.style.height = "18px";
             const videoBtn = createOption(videoIcon, "Video", handleToggleVideo, isVideoVisible);
             videoBtn.id = "convai-settings-video-btn";
+            refs.settingsVideoBtn = videoBtn;
             settingsRow.appendChild(videoBtn);
         }
         // Screen Share - Always show if showScreenShare is true and connection type is video
@@ -965,6 +1270,7 @@ export function createConvaiWidget(container, options) {
             shareIcon.style.height = "18px";
             const shareBtn = createOption(shareIcon, "Screen", handleToggleScreenShare, isSharing);
             shareBtn.id = "convai-settings-share-btn";
+            refs.settingsShareBtn = shareBtn;
             settingsRow.appendChild(shareBtn);
         }
         // Disconnect
@@ -977,6 +1283,12 @@ export function createConvaiWidget(container, options) {
     const createFloatingVideo = () => {
         const container = document.createElement("div");
         container.id = "floating-video-container";
+        // NOTE on z-index: deliberately NOT themable. `--convai-z-index` drives the
+        // widget root only. Both elements are `position: fixed` and this one is
+        // appended *before* the widget root, so on a tie the widget paints on top:
+        // a host raising the token to clear their nav bar would hide the user's own
+        // camera preview behind the panel. Video/screen share are also out of scope
+        // for the embed, which is chat-only.
         container.style.cssText = `
       position: fixed;
       left: 20px;
@@ -1158,12 +1470,16 @@ export function createConvaiWidget(container, options) {
     };
     // Event handlers
     const handleToggle = async () => {
-        if (isOpen) {
-            // Just close if already open
+        if (isOpen || pendingOpen) {
+            // Already open, or an open is already in flight: nothing to do. The
+            // `pendingOpen` half is what keeps a repeat call from falling through
+            // to the `isConnecting` branch below and opening the panel *before* the
+            // connect it is waiting on has finished.
             return;
         }
         // Connect on first click if not already connected/connecting
         if (!client.state.isConnected && !client.state.isConnecting) {
+            pendingOpen = true;
             try {
                 // Use reconnect when opening again after a disconnect (reuses stored config)
                 if (hasConnectedBefore && typeof client.reconnect === "function") {
@@ -1172,18 +1488,40 @@ export function createConvaiWidget(container, options) {
                 else {
                     await client.connect();
                 }
+                // Re-checked *after* the await: a close()/toggle()/launcher click
+                // during the connect clears the flag, and that cancellation has to
+                // win. The client stays connected either way -- only the panel is
+                // held back -- so a later open() takes the already-connected branch
+                // and opens instantly.
+                if (!pendingOpen)
+                    return;
                 setIsOpen(true);
             }
             catch (error) {
                 console.error("Failed to connect:", error);
             }
+            finally {
+                pendingOpen = false;
+            }
         }
         else {
             // Just toggle open/close if already connected
             setIsOpen(!isOpen);
         }
     };
+    /** A launcher click while an open is pending means "cancel", same as `toggle()`. */
+    const handleLauncherClick = () => {
+        if (pendingOpen) {
+            handleClose();
+            return;
+        }
+        void handleToggle();
+    };
     const handleClose = () => {
+        // Cancels an in-flight open as well as closing an open panel; see
+        // `pendingOpen`. `setIsOpen(false)` on an already-closed widget just
+        // re-applies the collapsed styles, so this is safe in both cases.
+        pendingOpen = false;
         setIsOpen(false);
     };
     const handleSend = () => {
@@ -1218,7 +1556,7 @@ export function createConvaiWidget(container, options) {
             isVoiceMode = false;
             hasEnteredDefaultVoiceMode = false;
             updateHeader();
-            updateVoiceMode();
+            await updateVoiceMode();
             updateSendButton();
         }
         catch (error) {
@@ -1232,7 +1570,11 @@ export function createConvaiWidget(container, options) {
         isVoiceMode = false;
         hasEnteredDefaultVoiceMode = false;
         updateHeader();
-        updateVoiceMode();
+        // Not awaited: this function has no try/catch of its own and is wired
+        // straight to a click, so awaiting would only move a rejection from one
+        // unguarded place to another. See the note on `handleDisconnect`'s own
+        // `await client.disconnect()` in the fix report.
+        applyVoiceMode();
         updateSendButton();
     };
     const handleToggleVideo = async () => {
@@ -1271,10 +1613,17 @@ export function createConvaiWidget(container, options) {
     const setIsOpen = async (open) => {
         isOpen = open;
         if (open) {
-            morphingContainer.style.width = "400px";
-            morphingContainer.style.height = "600px";
-            morphingContainer.style.borderRadius = aeroTheme.borderRadius.xl;
+            morphingContainer.style.width = `${PANEL_W_PX}px`;
+            morphingContainer.style.height = `${PANEL_H_PX}px`;
+            morphingContainer.style.borderRadius = `var(--convai-radius, ${aeroTheme.borderRadius.xl})`;
             morphingContainer.style.cursor = "default";
+            // The open panel is a *different* glass treatment from the launcher
+            // bubble, matching the React widget: near-opaque and saturated, so the
+            // host page does not bleed through. At the bubble's 0.8 alpha a dark
+            // host page shows through the panel and reads as grey.
+            morphingContainer.style.background =
+                "var(--convai-panel-bg, rgba(252, 252, 253, 0.95))";
+            morphingContainer.style.backdropFilter = "blur(20px) saturate(180%)";
             buttonContent.style.opacity = "0";
             buttonContent.style.transform = "scale(0.8)";
             buttonContent.style.pointerEvents = "none";
@@ -1290,19 +1639,24 @@ export function createConvaiWidget(container, options) {
                         await client.audioControls.unmuteAudio();
                         isVoiceMode = true;
                         hasEnteredDefaultVoiceMode = true;
-                        updateVoiceMode();
+                        await updateVoiceMode();
                     }
                     catch (error) {
-                        console.error("Failed to enter voice mode on open:", error);
+                        reportMicFailure(client, "Failed to enter voice mode on open:", error);
                     }
                 }, 100);
             }
         }
         else {
-            morphingContainer.style.width = "4rem";
-            morphingContainer.style.height = "4rem";
+            morphingContainer.style.width = "var(--convai-launcher-size, 64px)";
+            morphingContainer.style.height = "var(--convai-launcher-size, 64px)";
+            // Literal, not `--convai-radius` — see the creation site: that token is
+            // the *panel* radius, and reusing it here would squircle the launcher.
             morphingContainer.style.borderRadius = "50%";
             morphingContainer.style.cursor = "pointer";
+            // Back to the launcher bubble's lighter glass — see the open branch.
+            morphingContainer.style.background = `var(--convai-panel-bg, ${aeroTheme.colors.glass.backdrop})`;
+            morphingContainer.style.backdropFilter = aeroTheme.glass.backdrop;
             buttonContent.style.opacity = "1";
             buttonContent.style.transform = "scale(1)";
             buttonContent.style.pointerEvents = "auto";
@@ -1316,7 +1670,7 @@ export function createConvaiWidget(container, options) {
         settingsTray.style.display = open ? "flex" : "none";
     };
     const updateSendButton = () => {
-        const sendButton = document.getElementById("convai-send-button");
+        const sendButton = refs.sendButton;
         if (!sendButton)
             return;
         // Clear previous content
@@ -1324,8 +1678,15 @@ export function createConvaiWidget(container, options) {
         if (inputValue.length > 0) {
             // Show Send Button
             sendButton.appendChild(Icons.Send("md"));
-            sendButton.style.background = aeroTheme.colors.text.primary;
-            sendButton.style.color = "white";
+            sendButton.style.background = `var(--convai-accent, ${aeroTheme.colors.text.primary})`;
+            // The label sits *on* the accent fill, so it must follow the panel
+            // surface colour rather than stay a hardcoded "white" -- a host setting
+            // a pale --convai-accent would otherwise get white-on-white. `white` is
+            // byte-identical to the fallback --convai-panel-bg already carries at
+            // its three other sites, so the default rendering is unchanged.
+            // Pairing requirement for hosts: --convai-accent and --convai-panel-bg
+            // must contrast with each other, since this is the one place they meet.
+            sendButton.style.color = "var(--convai-panel-bg, white)";
             sendButton.style.border = "none";
             sendButton.title = "Send";
         }
@@ -1333,7 +1694,7 @@ export function createConvaiWidget(container, options) {
             // Show Voice Mode Toggle
             sendButton.appendChild(Icons.Waveform("md"));
             sendButton.style.background = "transparent";
-            sendButton.style.color = aeroTheme.colors.text.primary;
+            sendButton.style.color = `var(--convai-panel-fg, ${aeroTheme.colors.text.primary})`;
             sendButton.style.border = `1px solid ${aeroTheme.colors.neutral[300]}`;
             sendButton.title = "Voice Mode";
         }
@@ -1364,8 +1725,8 @@ export function createConvaiWidget(container, options) {
         }
     };
     const updateVoiceMode = async () => {
-        const standardFooter = document.getElementById("convai-footer-standard");
-        const voiceExitBtn = document.getElementById("convai-voice-exit-btn");
+        const standardFooter = refs.footerStandard;
+        const voiceExitBtn = refs.voiceExitBtn;
         if (isVoiceMode) {
             // Show Voice Overlay
             if (voiceModeOverlay)
@@ -1391,9 +1752,22 @@ export function createConvaiWidget(container, options) {
             startAudioAnalysis();
         }
         else {
-            // Ensure microphone is muted when not in voice mode
+            // Ensure microphone is muted when not in voice mode.
+            //
+            // This await is the only one in this function that can reject, and
+            // everything below it -- hiding the overlay, restoring the standard
+            // footer, updating the header, stopping the analyser -- is the only
+            // route out of the voice UI. So a failed mute must never short-circuit
+            // it: report it and carry on tearing the overlay down. (LiveKit's
+            // setMicrophoneEnabled(false) rethrows on a dropped room, which is
+            // exactly when the user is most likely to be hitting exit.)
             if (!client.audioControls.isAudioMuted) {
-                await client.audioControls.muteAudio();
+                try {
+                    await client.audioControls.muteAudio();
+                }
+                catch (error) {
+                    reportMicFailure(client, "Failed to mute microphone:", error);
+                }
             }
             // Hide Overlay
             if (voiceModeOverlay)
@@ -1425,6 +1799,24 @@ export function createConvaiWidget(container, options) {
             stopAudioAnalysis();
         }
     };
+    /**
+     * Fire-and-forget `updateVoiceMode()` for the call sites that are
+     * synchronous (DOM listeners, the constructor tail) and therefore have no
+     * caller to catch anything it rejects with.
+     *
+     * `updateVoiceMode()` is `async`, so a bare call there would put a floating
+     * promise on the host page. Its one rejecting await is now guarded
+     * internally, which makes this belt-and-braces -- but it is the guarantee
+     * that keeps a future await added inside `updateVoiceMode()` from silently
+     * reintroducing the unhandled rejection this replaces. Routed through
+     * `reportMicFailure` so a failure is observable on the client's `error`
+     * channel rather than console-only.
+     */
+    const applyVoiceMode = () => {
+        void updateVoiceMode().catch((error) => {
+            reportMicFailure(client, "Failed to apply voice mode:", error);
+        });
+    };
     // Microphone button removed - only controlled via voice mode now
     // Helper for Markdown - matches React MarkdownRenderer.tsx
     const renderMarkdown = (text, container) => {
@@ -1459,7 +1851,7 @@ export function createConvaiWidget(container, options) {
                         strong.textContent = match[2];
                         strong.style.cssText = `
               font-weight: 600;
-              color: ${aeroTheme.colors.text.primary};
+              color: var(--convai-panel-fg, ${aeroTheme.colors.text.primary});
             `;
                         parts.push(strong);
                     }
@@ -1526,7 +1918,7 @@ export function createConvaiWidget(container, options) {
             height: 100%;
             color: ${aeroTheme.colors.text.secondary};
             text-align: center;
-            padding: 2rem;
+            padding: 32px;
         `;
             emptyState.innerHTML = `
             <p style="font-weight: 500; margin-bottom: 8px;">Start a conversation</p>
@@ -1548,6 +1940,7 @@ export function createConvaiWidget(container, options) {
         contain: layout style paint;
       `;
             const bubble = document.createElement("div");
+            bubble.setAttribute("part", msg.isUser ? "message message-user" : "message message-bot");
             // Add data attribute to identify user messages for debugging/styling
             if (msg.isUser) {
                 bubble.setAttribute("data-message-type", "user");
@@ -1555,6 +1948,10 @@ export function createConvaiWidget(container, options) {
             // Set base styles first - explicitly set background to match React UserBubble exactly
             // CRITICAL: Use the exact same background for both user and bot messages
             const backgroundColor = "rgba(252, 252, 253, 0.95)";
+            // NOTE on border-radius: deliberately NOT themable. `--convai-radius` is
+            // the open panel's radius; a bubble's asymmetric tail corner is a
+            // different geometry (`50%` would make ellipses of these). A dedicated
+            // `--convai-bubble-radius` can be added additively later if wanted.
             bubble.style.cssText = `
         padding: 12px;
         border-radius: ${msg.isUser ? "12px 12px 4px 12px" : "12px 12px 12px 4px"};
@@ -1563,8 +1960,8 @@ export function createConvaiWidget(container, options) {
         backdrop-filter: blur(20px) saturate(180%);
         border: 1px solid rgba(0, 0, 0, 0.06);
         box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.8) inset, 0 2px 8px rgba(0, 0, 0, 0.08);
-        color: ${aeroTheme.colors.text.primary};
-        font-family: ${aeroTheme.typography.fontFamily.body};
+        color: var(--convai-panel-fg, ${aeroTheme.colors.text.primary});
+        font-family: var(--convai-font, ${aeroTheme.typography.fontFamily.body});
         font-size: 14px;
         line-height: 1.5;
         word-wrap: break-word;
@@ -1596,8 +1993,8 @@ export function createConvaiWidget(container, options) {
                 // Logo/Icon - matches React LogoWrapper
                 const logoContainer = document.createElement("div");
                 logoContainer.style.cssText = `
-          width: 1rem;
-          height: 1rem;
+          width: 16px;
+          height: 16px;
           display: flex;
           align-items: center;
           justify-content: center;
@@ -1624,10 +2021,10 @@ export function createConvaiWidget(container, options) {
                 const nameLabel = document.createElement("span");
                 nameLabel.textContent = msg.sender === "User" ? "You" : msg.sender;
                 nameLabel.style.cssText = `
-          font-size: 0.75rem;
+          font-size: 12px;
           color: ${msg.isUser ? aeroTheme.colors.convai.dark : "#10b981"};
           font-weight: 500;
-          font-family: ${aeroTheme.typography.fontFamily.body};
+          font-family: var(--convai-font, ${aeroTheme.typography.fontFamily.body});
           isolation: isolate;
           contain: layout style paint;
         `;
@@ -1649,11 +2046,11 @@ export function createConvaiWidget(container, options) {
                 const timestamp = document.createElement("span");
                 timestamp.textContent = msg.timestamp;
                 timestamp.style.cssText = `
-          font-size: 0.75rem;
+          font-size: 12px;
           color: ${aeroTheme.colors.text.secondary};
           margin-top: 4px;
           align-self: ${msg.isUser ? "flex-end" : "flex-start"};
-          font-family: ${aeroTheme.typography.fontFamily.body};
+          font-family: var(--convai-font, ${aeroTheme.typography.fontFamily.body});
         `;
                 messageWrapper.appendChild(timestamp);
             }
@@ -1730,7 +2127,10 @@ export function createConvaiWidget(container, options) {
                 isVideoVisible = false;
                 hasEnteredDefaultVoiceMode = false;
                 updateHeader();
-                updateVoiceMode();
+                // Synchronous listener: nothing here can catch a rejection, and the
+                // mute inside is the one most likely to fail (the room has just
+                // dropped -- that is why we are collapsing).
+                applyVoiceMode();
             }
             // Auto-enter voice mode on first connection if defaultVoiceMode is true
             if (client.state.isConnected &&
@@ -1743,10 +2143,10 @@ export function createConvaiWidget(container, options) {
                         await client.audioControls.unmuteAudio();
                         isVoiceMode = true;
                         hasEnteredDefaultVoiceMode = true;
-                        updateVoiceMode();
+                        await updateVoiceMode();
                     }
                     catch (error) {
-                        console.error("Failed to enter voice mode:", error);
+                        reportMicFailure(client, "Failed to enter voice mode:", error);
                     }
                 }, 100);
             }
@@ -1756,9 +2156,9 @@ export function createConvaiWidget(container, options) {
         client.videoControls.on("videoStateChange", (videoState) => {
             if (videoState.isVideoEnabled !== undefined) {
                 isVideoVisible = videoState.isVideoEnabled;
-                updateVoiceMode();
+                applyVoiceMode(); // synchronous listener; see applyVoiceMode()
                 // Update tray button state
-                const videoBtn = document.getElementById("convai-settings-video-btn");
+                const videoBtn = refs.settingsVideoBtn;
                 if (videoBtn) {
                     const isActive = isVideoVisible;
                     videoBtn.style.backgroundColor = isActive
@@ -1766,7 +2166,7 @@ export function createConvaiWidget(container, options) {
                         : "transparent";
                     videoBtn.style.color = isActive
                         ? "#10b981"
-                        : aeroTheme.colors.text.primary;
+                        : `var(--convai-panel-fg, ${aeroTheme.colors.text.primary})`;
                     // Update Icon - first child is icon container
                     const iconContainer = videoBtn.querySelector("div");
                     if (iconContainer) {
@@ -1783,7 +2183,7 @@ export function createConvaiWidget(container, options) {
         client.screenShareControls.on("screenShareStateChange", (screenShareState) => {
             if (screenShareState.isScreenShareActive !== undefined) {
                 const isSharing = screenShareState.isScreenShareActive;
-                const shareBtn = document.getElementById("convai-settings-share-btn");
+                const shareBtn = refs.settingsShareBtn;
                 if (shareBtn) {
                     const isActive = isSharing;
                     shareBtn.style.backgroundColor = isActive
@@ -1791,7 +2191,7 @@ export function createConvaiWidget(container, options) {
                         : "transparent";
                     shareBtn.style.color = isActive
                         ? "#10b981"
-                        : aeroTheme.colors.text.primary;
+                        : `var(--convai-panel-fg, ${aeroTheme.colors.text.primary})`;
                     // Update Icon - first child is icon container
                     const iconContainer = shareBtn.querySelector("div");
                     if (iconContainer) {
@@ -1821,8 +2221,13 @@ export function createConvaiWidget(container, options) {
         client.on("connect", () => {
             hasConnectedBefore = true;
             // Initialize audio renderer on connection
+            // NOTE: the audio elements live under rootElement, so playback ends if
+            // the host *removes or re-parents* its mount container mid-call. Merely
+            // hiding it (display: none / visibility: hidden) does NOT stop
+            // HTMLMediaElement playback in any browser — an earlier version of this
+            // comment claimed otherwise and was wrong.
             if (client.room && !audioRenderer) {
-                audioRenderer = new AudioRenderer(client.room);
+                audioRenderer = new AudioRenderer(client.room, { container: rootElement });
             }
             // Fetch character info
             fetchCharacterInfo();
@@ -1847,21 +2252,80 @@ export function createConvaiWidget(container, options) {
     // Initialize
     createDOM();
     setupClientListeners();
+    // Paint the connecting overlay's initial state. updateHeader() (which also
+    // calls updateConnectingOverlay()) is otherwise only reached via a client
+    // event or a successful character-info fetch, so a widget constructed
+    // already connected-but-not-ready would show nothing until one of those
+    // fires without this.
+    updateConnectingOverlay();
     // Set initial button state
     updateSendButton(); // Show voice mode button initially since input is empty
     // Set initial voice mode UI if defaultVoiceMode is true
     if (defaultVoiceMode) {
-        updateVoiceMode();
+        applyVoiceMode(); // synchronous constructor tail; see applyVoiceMode()
     }
     // If already connected, initialize audio renderer and fetch character info
+    // NOTE: same lifetime caveat as the "connect" handler above — the audio
+    // elements are torn down with rootElement if the host detaches it.
     if (client.state.isConnected && client.room) {
-        audioRenderer = new AudioRenderer(client.room);
+        audioRenderer = new AudioRenderer(client.room, { container: rootElement });
         fetchCharacterInfo();
     }
     // Return widget instance
     const widget = {
         element: rootElement,
         client: client,
+        // `isOpen` reports *requested* state, which on a warm client is the same
+        // thing as rendered state: `setIsOpen()` runs synchronously. The one case
+        // where they differ is the first open on a disconnected client, where the
+        // panel is committed only after `connect()` resolves; reporting `false`
+        // for those seconds would tell an embed reconciling its own
+        // convai-open/convai-close events that a widget it just opened is closed.
+        // `pendingOpen` is cleared by every cancellation path, so this never
+        // reports open for a request that was called off.
+        get isOpen() {
+            return isOpen || pendingOpen;
+        },
+        // Drives the exact same path the launcher click does: `handleToggle`
+        // (connect-on-first-open, then `setIsOpen(true)`). Idempotent against an
+        // in-flight open as well as an open panel, so repeat calls never start a
+        // second connect.
+        open: () => {
+            if (isOpen || pendingOpen)
+                return;
+            void handleToggle();
+        },
+        // Drives the same path the header's close button does: `handleClose` ->
+        // `setIsOpen(false)`. Also cancels an open that is still waiting on
+        // `connect()`; a redundant `close()` is a no-op.
+        close: () => {
+            if (!isOpen && !pendingOpen)
+                return;
+            handleClose();
+        },
+        toggle: () => {
+            if (isOpen || pendingOpen) {
+                handleClose();
+            }
+            else {
+                void handleToggle();
+            }
+        },
+        // Pushes a synthetic ChatMessage straight onto `client.chatMessages` and
+        // re-renders via the widget's existing `updateMessageList()`. It never
+        // calls a client send method (e.g. `sendUserTextMessage`), so the
+        // message never reaches the character and is never billed as an LLM
+        // turn. The `local-` id keeps it from colliding with a server-issued id.
+        appendMessage: (message) => {
+            const chatMessage = {
+                id: `local-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
+                type: message.sender === "user" ? "user-llm-text" : "bot-llm-text",
+                content: message.content,
+                timestamp: new Date().toISOString(),
+            };
+            client.chatMessages.push(chatMessage);
+            updateMessageList();
+        },
         destroy: () => {
             // Cleanup audio renderer
             if (audioRenderer) {
@@ -1869,7 +2333,7 @@ export function createConvaiWidget(container, options) {
                 audioRenderer = null;
             }
             // Remove event listeners
-            morphingContainer.removeEventListener("click", handleToggle);
+            morphingContainer.removeEventListener("click", handleLauncherClick);
             // Remove DOM elements
             if (rootElement.parentElement) {
                 rootElement.remove();