@runtypelabs/persona 4.13.0 → 4.15.0

package/src/ui.ts

@@ -34,7 +34,9 @@ import {
   PersonaArtifactFileMeta,
   PersonaArtifactActionContext,
   AgentWidgetContentSegment,
-  AgentWidgetContextMentionRef
+  AgentWidgetContextMentionRef,
+  AgentWidgetSuggestion,
+  AgentWidgetSuggestionSource
 } from "./types";
 import { AttachmentManager } from "./utils/attachment-manager";
 import {
@@ -91,7 +93,7 @@ import { buildHeaderWithLayout } from "./components/header-layouts";
 import { positionMap } from "./utils/positioning";
 import type { HeaderElements as _HeaderElements, ComposerElements as _ComposerElements } from "./components/panel";
 import { MessageTransform, MessageActionCallbacks, LoadingIndicatorRenderer } from "./components/message-bubble";
-import { createStandardBubble, createTypingIndicator } from "./components/message-bubble";
+import { createStandardBubble, createTypingIndicator, getBubbleClasses } from "./components/message-bubble";
 import { createReasoningBubble, reasoningExpansionState, updateReasoningBubbleUI } from "./components/reasoning-bubble";
 import { createToolBubble, toolExpansionState, updateToolBubbleUI } from "./components/tool-bubble";
 import {
@@ -111,6 +113,7 @@ import {
 import {
   isSuggestRepliesMessage,
   latestAgentSuggestions,
+  resolveFollowUpsFeature,
 } from "./suggest-replies-tool";
 import { formatElapsedMs } from "./utils/formatting";
 import { approvalDetailsExpansionState, createApprovalBubble, updateApprovalDetailsUI } from "./components/approval-bubble";
@@ -133,6 +136,7 @@ import {
   shouldExpandLauncherForArtifacts
 } from "./utils/artifact-gate";
 import { resolveArtifactDisplayMode } from "./utils/artifact-display";
+import { resolveConfigPreferences } from "./utils/feature-preferences";
 import { readFlexGapPx, resolveArtifactPaneWidthPx } from "./utils/artifact-resize";
 import { enhanceWithForms } from "./components/forms";
 import { pluginRegistry } from "./plugins/registry";
@@ -358,6 +362,19 @@ type Controller = {
    * @deprecated Use injectMessage() instead.
    */
   injectTestMessage: (event: AgentWidgetEvent) => void;
+  /**
+   * Show follow-up suggestions from host code. An ephemeral UI overlay: the
+   * items never enter the transcript, the wire payload, or persisted state, so
+   * they do not survive a refresh. Cleared automatically when the next user
+   * message appends. Latest writer wins against the agent's `suggest_replies`
+   * payloads: this call overrides chips shown now, and a payload arriving
+   * afterwards overrides these. Renders through the `suggestions.followUps`
+   * presentation config and the full plugin and `persona:suggestReplies:*`
+   * event pipeline, with source `"host"`. An empty array clears.
+   */
+  setFollowUpSuggestions: (items: AgentWidgetSuggestion[]) => void;
+  /** Remove host-set follow-up suggestions. Agent-set chips are untouched. */
+  clearFollowUpSuggestions: () => void;
   getMessages: () => AgentWidgetMessage[];
   getStatus: () => AgentWidgetSessionStatus;
   getPersistentMetadata: () => Record<string, unknown>;
@@ -596,6 +613,11 @@ export const createAgentExperience = (
   }
 
   let config = mergeWithDefaults(initialConfig) as AgentWidgetConfig;
+  // `config.features` holds the preference-resolved view every read site uses;
+  // `baseFeatures` keeps the pre-preference base so update() re-resolves from
+  // it instead of stacking new preferences onto already-overlaid values.
+  let baseFeatures = config.features;
+  config = resolveConfigPreferences(config);
   // Note: applyThemeVariables is called after applyFullHeightStyles() below
   // because applyFullHeightStyles resets mount.style.cssText
 
@@ -866,6 +888,8 @@ export const createAgentExperience = (
     container,
     body,
     messagesWrapper,
+    starterSuggestions,
+    transcriptSuggestions,
     suggestions,
     textarea,
     sendButton,
@@ -1320,6 +1344,11 @@ export const createAgentExperience = (
     messagesWrapper.style.marginLeft = "auto";
     messagesWrapper.style.marginRight = "auto";
     messagesWrapper.style.width = "100%";
+    starterSuggestions.style.maxWidth = contentMaxWidth;
+    transcriptSuggestions.style.maxWidth = contentMaxWidth;
+    transcriptSuggestions.style.marginLeft = "auto";
+    transcriptSuggestions.style.marginRight = "auto";
+    transcriptSuggestions.style.width = "100%";
   }
   // The pill IS the composer in composer-bar mode and should match the
   // wrapper's responsive width (50vw / 70vw / 90vw), not be capped by
@@ -1800,7 +1829,7 @@ export const createAgentExperience = (
   let artifactPaneExpandedPinned = false;
   // Whether the user explicitly opened the pane (card click, inline Expand,
   // showArtifacts(), programmatic upsert). Auto-open is otherwise reserved for
-  // artifacts whose resolved display mode is "panel": "card" keeps the card as
+  // artifacts whose resolved display mode is "panel": "collapsed" keeps the card as
   // the only affordance and "inline" renders in the transcript. "inline" no
   // longer *auto*-opens the pane, but its Expand control is a deliberate,
   // user-driven open (setting artifactsPaneUserOpened, same as a card click);
@@ -1811,7 +1840,7 @@ export const createAgentExperience = (
     artifactsPaneUserOpened ||
     lastArtifactsState.artifacts.some(
       (a) =>
-        resolveArtifactDisplayMode(config.features?.artifacts, a.artifactType) === "panel"
+        resolveArtifactDisplayMode(config.features?.artifacts, a) === "panel"
     );
   const artifactPaneVisible = () =>
     lastArtifactsState.artifacts.length > 0 &&
@@ -2010,7 +2039,7 @@ export const createAgentExperience = (
     event.preventDefault();
     event.stopPropagation();
     artifactsPaneUserHidden = false;
-    // Card click is an explicit open: it overrides the "card"/"inline"
+    // Card click is an explicit open: it overrides the "collapsed"/"inline"
     // auto-open suppression for as long as artifacts exist.
     artifactsPaneUserOpened = true;
     session.selectArtifact(artifactId);
@@ -2518,7 +2547,7 @@ export const createAgentExperience = (
     } else if (lastArtifactsState.artifacts.length > 0 && artifactPaneCanShow()) {
       // User chose “show” again (e.g. programmatic showArtifacts): clear dismiss chrome
       // and force drawer open so narrow-host / mobile slide-out is not stuck off-screen.
-      // Artifacts whose display mode is "card" or "inline" don't auto-open the
+      // Artifacts whose display mode is "collapsed" or "inline" don't auto-open the
       // pane (artifactPaneCanShow); it stays hidden until an explicit open or
       // until a "panel"-mode artifact arrives.
       artifactPaneApi.element.classList.remove("persona-hidden");
@@ -3440,7 +3469,17 @@ export const createAgentExperience = (
     }
   }
 
-  const suggestionsManager = createSuggestions(suggestions);
+  const composerSuggestionsManager = createSuggestions(suggestions);
+  const starterSuggestionsManager = createSuggestions(starterSuggestions);
+  const transcriptSuggestionsManager = createSuggestions(transcriptSuggestions);
+  const suggestionManagers = [
+    composerSuggestionsManager,
+    starterSuggestionsManager,
+    transcriptSuggestionsManager,
+  ];
+  destroyCallbacks.push(() => {
+    suggestionManagers.forEach((manager) => manager.destroy());
+  });
   let closeHandler: (() => void) | null = null;
   let session: AgentWidgetSession;
 
@@ -3451,35 +3490,217 @@ export const createAgentExperience = (
   // keep their before-first-user-message behavior. Config updates MUST route
   // through here too: re-rendering with only `config.suggestionChips` would
   // drop a live agent chip row until the next message change.
+  // Warn once per widget instance: renderSuggestions runs on every change.
+  // Host-set follow-ups (`setFollowUpSuggestions`) are an ephemeral UI overlay:
+  // never appended to the session, never sent on the wire, never persisted.
+  let hostFollowUps: AgentWidgetSuggestion[] | null = null;
+  // Latches: a host that drives the surface itself is a legitimate no-tool
+  // integration, so the never-called hint must stay off even after the overlay
+  // expires.
+  let hostFollowUpsEverSet = false;
+  // Latest-writer-wins bookkeeping captured at set time: the overlay is dropped
+  // once another user message appends or a newer suggest_replies message lands.
+  let hostFollowUpsUserCount = 0;
+  let hostFollowUpsAgentId: string | null = null;
+
+  const countUserMessages = (messages: AgentWidgetMessage[]): number =>
+    messages.reduce(
+      (total, message) => (message.role === "user" ? total + 1 : total),
+      0
+    );
+
+  /** Identity of the newest suggest_replies message, regardless of position. */
+  const latestSuggestRepliesId = (
+    messages: AgentWidgetMessage[]
+  ): string | null => {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (isSuggestRepliesMessage(messages[i])) return messages[i].id ?? null;
+    }
+    return null;
+  };
+
+  let warnedPinnedStarterPlacement = false;
+  const warnPinnedStarterPlacement = () => {
+    if (warnedPinnedStarterPlacement || config.debug !== true) return;
+    warnedPinnedStarterPlacement = true;
+    console.warn(
+      '[persona] suggestions.starters.placement is pinned to "welcome" but copy.showWelcomeCard is false, so no starters render. Use "auto" or "composer".',
+    );
+  };
+  // Debug-only setup hint: a stream this session ended without the agent ever
+  // calling suggest_replies, so the model never got the tool. Gated on a
+  // COMPLETED stream, not on transcript shape: a restored transcript
+  // (initialMessages/onStateLoaded) proves nothing about this session's wiring.
+  let hintedFollowUpsNeverCalled = false;
+  let completedStreamThisSession = false;
+  const hintFollowUpsNeverCalled = (
+    messages: AgentWidgetMessage[],
+    feature: ReturnType<typeof resolveFollowUpsFeature>
+  ) => {
+    if (hintedFollowUpsNeverCalled || config.debug !== true) return;
+    if (!feature.enabled || feature.expose) return;
+    if (hostFollowUpsEverSet) return;
+    if (!completedStreamThisSession) return;
+    if (session.isStreaming()) return;
+    if (messages.some(isSuggestRepliesMessage)) return;
+    hintedFollowUpsNeverCalled = true;
+    console.info(
+      "[persona] Follow-up suggestions are enabled but the agent has not called suggest_replies. The model needs the tool declared (runtimeTools server-side, suggestions.followUps.expose: true from the widget, or your own backend's tool definition) and benefits from instructions telling it when to offer follow-ups. See the integration paths table in UI-COMPONENTS.md."
+    );
+  };
+
   const renderSuggestions = (messages?: AgentWidgetMessage[]) => {
     if (!session) return;
     const current = messages ?? session.getMessages();
-    const agentChips =
-      config.features?.suggestReplies?.enabled !== false
-        ? latestAgentSuggestions(current)
-        : null;
-    if (agentChips) {
-      suggestionsManager.render(
-        agentChips,
+    const clearManager = (manager: ReturnType<typeof createSuggestions>) => {
+      manager.render([], session, textarea, current);
+    };
+    const clearOthers = (active: ReturnType<typeof createSuggestions>) => {
+      suggestionManagers.forEach((manager) => {
+        if (manager !== active) clearManager(manager);
+      });
+    };
+    // Same lifecycle as agent follow-ups: the overlay expires on the next user
+    // message, and a suggest_replies message newer than the set call wins.
+    if (
+      hostFollowUps &&
+      (countUserMessages(current) > hostFollowUpsUserCount ||
+        latestSuggestRepliesId(current) !== hostFollowUpsAgentId)
+    ) {
+      hostFollowUps = null;
+    }
+
+    // `enabled: false` disables the tool, not the surface: host-set follow-ups
+    // still render.
+    const followUpsFeature = resolveFollowUpsFeature(config);
+    hintFollowUpsNeverCalled(current, followUpsFeature);
+    const agentSuggestions = followUpsFeature.enabled
+      ? latestAgentSuggestions(current)
+      : null;
+    const followUpSuggestions = hostFollowUps ?? agentSuggestions;
+    const followUpSource: AgentWidgetSuggestionSource = hostFollowUps
+      ? "host"
+      : "agent";
+
+    if (followUpSuggestions) {
+      const followUps = config.suggestions?.followUps;
+      const requestedPlacement =
+        followUps?.placement ?? (followUps ? "auto" : "composer");
+      const placement =
+        requestedPlacement === "auto"
+          ? isComposerBar()
+            ? "composer"
+            : "after-message"
+          : requestedPlacement;
+      const manager =
+        placement === "after-message"
+          ? transcriptSuggestionsManager
+          : composerSuggestionsManager;
+      clearOthers(manager);
+      manager.render(
+        followUpSuggestions,
         session,
         textarea,
         current,
         config.suggestionChipsConfig,
-        { agentPushed: true }
+        {
+          source: followUpSource,
+          surface: "followUp",
+          variant: followUps?.variant ?? "chip",
+          behavior: followUps?.behavior ?? "send",
+          overflow: followUps?.overflow ?? "scroll",
+          maxItems: followUps?.maxItems ?? 4,
+          config,
+          plugins,
+        }
       );
-    } else if (current.some((msg) => msg.role === "user")) {
-      // Hide suggestions once a user message exists.
-      suggestionsManager.render([], session, textarea, current);
-    } else {
-      suggestionsManager.render(
-        config.suggestionChips,
+      return;
+    }
+
+    if (current.some((message) => message.role === "user")) {
+      suggestionManagers.forEach(clearManager);
+      return;
+    }
+
+    const starters = config.suggestions?.starters;
+    if (starters) {
+      // The starter host lives inside the welcome card, so a pinned "welcome"
+      // placement has nowhere to render when that card is hidden.
+      const welcomeCardVisible = config.copy?.showWelcomeCard !== false;
+      const requestedPlacement = starters.placement ?? "auto";
+      const placement =
+        requestedPlacement === "auto"
+          ? welcomeCardVisible
+            ? "welcome"
+            : "composer"
+          : requestedPlacement;
+      if (placement === "welcome" && !welcomeCardVisible) {
+        warnPinnedStarterPlacement();
+        suggestionManagers.forEach(clearManager);
+        return;
+      }
+      const manager =
+        placement === "welcome"
+          ? starterSuggestionsManager
+          : composerSuggestionsManager;
+      clearOthers(manager);
+      manager.render(
+        starters.items ?? config.suggestionChips,
         session,
         textarea,
         current,
-        config.suggestionChipsConfig
+        config.suggestionChipsConfig,
+        {
+          surface: "starter",
+          variant: starters.variant ?? "card",
+          behavior: starters.behavior ?? "send",
+          overflow: starters.overflow ?? "wrap",
+          maxItems: starters.maxItems ?? 4,
+          config,
+          plugins,
+        }
       );
+      return;
     }
+
+    clearOthers(composerSuggestionsManager);
+    composerSuggestionsManager.render(
+      config.suggestionChips,
+      session,
+      textarea,
+      current,
+      config.suggestionChipsConfig,
+      {
+        surface: "starter",
+        variant: "chip",
+        behavior: "send",
+        overflow: "wrap",
+        config,
+        plugins,
+      }
+    );
   };
+
+  const clearHostFollowUps = () => {
+    if (!hostFollowUps) return;
+    hostFollowUps = null;
+    renderSuggestions();
+  };
+
+  const setHostFollowUps = (items: AgentWidgetSuggestion[]) => {
+    const list = Array.isArray(items) ? [...items] : [];
+    if (!list.length) {
+      clearHostFollowUps();
+      return;
+    }
+    const current = session ? session.getMessages() : [];
+    hostFollowUps = list;
+    hostFollowUpsEverSet = true;
+    hostFollowUpsUserCount = countUserMessages(current);
+    hostFollowUpsAgentId = latestSuggestRepliesId(current);
+    renderSuggestions(current);
+  };
+
   let isStreaming = false;
   const messageCache = createMessageCache();
   // Tracks the last fingerprint we rendered a plugin-rendered ask_user_question
@@ -4505,7 +4726,7 @@ export const createAgentExperience = (
       // visible instead of silently swallowed.
       if (
         isSuggestRepliesMessage(message) &&
-        config.features?.suggestReplies?.enabled !== false
+        resolveFollowUpsFeature(config).enabled
       ) {
         return;
       }
@@ -5045,28 +5266,30 @@ export const createAgentExperience = (
 
       // Only render if we have an indicator (allows hiding via returning null)
       if (typingIndicator) {
-        // Create a bubble wrapper for the typing indicator (similar to assistant messages)
+        // Bubble wrapper for the typing indicator. It borrows the assistant
+        // bubble's classes and background so the "thinking" bubble matches the
+        // message bubbles that replace it under every layout preset.
         const typingBubble = document.createElement("div");
         const showBubble = config.loadingIndicator?.showBubble !== false; // default true
+        const messageLayout = config.layout?.messages?.layout ?? "bubble";
         typingBubble.className = showBubble
-          ? [
-              "persona-rounded-2xl",
-              "persona-text-sm",
-              "persona-leading-relaxed",
-              "persona-shadow-sm",
-              "persona-bg-persona-surface",
-              "persona-border",
-              "persona-text-persona-primary",
-              "persona-px-5",
-              "persona-py-3"
-            ].join(" ")
+          ? getBubbleClasses("assistant", messageLayout).join(" ")
           : [
               "persona-text-sm",
               "persona-leading-relaxed",
-              "persona-text-persona-primary"
+              "persona-text-persona-text"
             ].join(" ");
         typingBubble.setAttribute("data-typing-indicator", "true");
-        typingBubble.style.borderColor = "var(--persona-message-assistant-border, var(--persona-border, #e5e7eb))";
+        if (showBubble) {
+          typingBubble.style.color =
+            "var(--persona-message-assistant-text, var(--persona-text))";
+          if (messageLayout !== "flat") {
+            typingBubble.style.backgroundColor =
+              "var(--persona-message-assistant-bg, var(--persona-container))";
+            typingBubble.style.borderColor =
+              "var(--persona-message-assistant-border, var(--persona-border, #e5e7eb))";
+          }
+        }
 
         typingBubble.appendChild(typingIndicator);
 
@@ -5876,8 +6099,16 @@ export const createAgentExperience = (
     if (micButton) {
       micButton.disabled = disabled;
     }
-    suggestionsManager.buttons.forEach((btn) => {
-      btn.disabled = disabled;
+    suggestionManagers.forEach((manager) => {
+      manager.elements.forEach((element) => {
+        element.toggleAttribute("data-disabled", disabled);
+        if (!(element instanceof HTMLButtonElement)) {
+          element.setAttribute("aria-disabled", disabled ? "true" : "false");
+        }
+      });
+      manager.buttons.forEach((button) => {
+        button.disabled = disabled;
+      });
     });
     footer.dataset.personaComposerStreaming = disabled ? "true" : "false";
     footer.querySelectorAll<HTMLElement>("[data-persona-composer-disable-when-streaming]").forEach((el) => {
@@ -6188,6 +6419,16 @@ export const createAgentExperience = (
       }
       if (!streaming) {
         scheduleAutoScroll(true);
+        // setStreaming only fires on a change, so this is always a real stream
+        // ending. Evaluate the never-called hint here: no later render is
+        // guaranteed on a settled transcript.
+        completedStreamThisSession = true;
+        if (session) {
+          hintFollowUpsNeverCalled(
+            session.getMessages(),
+            resolveFollowUpsFeature(config)
+          );
+        }
       }
       // Keep the "streaming below" hint and its announcement in sync with the
       // streaming lifecycle (Principles 8 + 15).
@@ -7846,8 +8087,11 @@ export const createAgentExperience = (
       const previousStreamAnimationType = config.features?.streamAnimation?.type;
       // One consistent recursive patch policy across the live controller and the
       // init handle. See utils/config-merge.ts for the replace-leaf list and
-      // explicit-undefined reset semantics.
-      config = mergeConfigUpdate(config, nextConfig);
+      // explicit-undefined reset semantics. The patch merges over the
+      // pre-preference base features, then preferences re-resolve on top.
+      config = mergeConfigUpdate({ ...config, features: baseFeatures }, nextConfig);
+      baseFeatures = config.features;
+      config = resolveConfigPreferences(config);
       // applyFullHeightStyles resets mount.style.cssText, so call it before applyThemeVariables
       applyFullHeightStyles();
       applyThemeVariables(mount, config);
@@ -9282,13 +9526,20 @@ export const createAgentExperience = (
       if (!artifactsSidebarEnabled(config)) return null;
       // Programmatic upserts match the streamed UX: only "panel"-mode
       // artifacts auto-open the pane (overriding a previous Close), while
-      // "card"/"inline" stay calm — the injected transcript block is the
+      // "collapsed"/"inline" stay calm — the injected transcript block is the
       // affordance. Independent of `transcript: false`: pane-only callers
-      // (e.g. the theme editor preview) rely on the panel-default surfacing;
-      // callers that want the pane in a non-panel mode call showArtifacts().
+      // (e.g. the theme editor preview) rely on the auto-open default
+      // surfacing; callers that want the pane in another mode call
+      // showArtifacts().
       const mode = resolveArtifactDisplayMode(
         config.features?.artifacts,
-        manual.artifactType
+        {
+          artifactType: manual.artifactType,
+          ...(manual.artifactType === "markdown" && manual.file
+            ? { file: manual.file }
+            : {}),
+          ...(manual.presentation ? { presentation: manual.presentation } : {}),
+        }
       );
       if (mode === "panel") {
         artifactsPaneUserHidden = false;
@@ -9340,6 +9591,21 @@ export const createAgentExperience = (
       }
       return session.resolveApproval(approvalMessage.approval, decision, options);
     },
+    /**
+     * Show follow-up suggestions from host code. Ephemeral UI state only: the
+     * items never enter the transcript, the wire payload, or persistence, so
+     * they do not survive a refresh. Cleared when the next user message
+     * appends. Latest writer wins against agent `suggest_replies` payloads.
+     * Renders through the `suggestions.followUps` presentation config and the
+     * full plugin and DOM-event pipeline with source `"host"`.
+     */
+    setFollowUpSuggestions(items: AgentWidgetSuggestion[]): void {
+      setHostFollowUps(items);
+    },
+    /** Remove host-set follow-ups. Agent-set chips are untouched. */
+    clearFollowUpSuggestions(): void {
+      clearHostFollowUps();
+    },
     getMessages() {
       return session.getMessages();
     },

package/src/ui.typing-indicator.test.ts

@@ -0,0 +1,135 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+/**
+ * Mount a widget with a never-resolving fetch, send a message, and return the
+ * standalone typing indicator bubble rendered during the silent gap.
+ */
+const renderTypingBubble = async (
+  config: Record<string, unknown>
+): Promise<{ bubble: HTMLElement; destroy: () => void }> => {
+  global.fetch = vi.fn().mockImplementation(
+    () => new Promise(() => {})
+  ) as unknown as typeof fetch;
+
+  const mount = createMount();
+  const controller = createAgentExperience(mount, {
+    apiUrl: "https://api.example.com/chat",
+    launcher: { enabled: false },
+    ...config,
+  } as unknown as Parameters<typeof createAgentExperience>[1]);
+
+  controller.submitMessage("hello");
+  await Promise.resolve();
+  await Promise.resolve();
+
+  const bubble = mount.querySelector<HTMLElement>('[data-typing-indicator="true"]')!;
+  return { bubble, destroy: () => controller.destroy() };
+};
+
+describe("standalone typing indicator bubble", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    if (typeof localStorage !== "undefined") localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("uses the assistant bubble classes under the default bubble layout", async () => {
+    const { bubble, destroy } = await renderTypingBubble({});
+
+    expect(bubble).not.toBeNull();
+    expect(bubble.classList.contains("persona-message-assistant-bubble")).toBe(true);
+    expect(bubble.classList.contains("persona-shadow-sm")).toBe(true);
+    expect(bubble.classList.contains("persona-border")).toBe(true);
+    expect(bubble.classList.contains("persona-px-5")).toBe(true);
+
+    destroy();
+  });
+
+  it("drops the shadow and border under the minimal layout", async () => {
+    const { bubble, destroy } = await renderTypingBubble({
+      layout: { messages: { layout: "minimal" } },
+    });
+
+    expect(bubble.classList.contains("persona-message-assistant-bubble")).toBe(true);
+    expect(bubble.classList.contains("persona-shadow-sm")).toBe(false);
+    expect(bubble.classList.contains("persona-border")).toBe(false);
+    expect(bubble.classList.contains("persona-px-3")).toBe(true);
+    // Minimal keeps the surface background, matching its message bubbles.
+    expect(bubble.style.backgroundColor).toContain("--persona-message-assistant-bg");
+
+    destroy();
+  });
+
+  it("drops the background entirely under the flat layout", async () => {
+    const { bubble, destroy } = await renderTypingBubble({
+      layout: { messages: { layout: "flat" } },
+    });
+
+    expect(bubble.classList.contains("persona-shadow-sm")).toBe(false);
+    expect(bubble.classList.contains("persona-border")).toBe(false);
+    expect(bubble.style.backgroundColor).toBe("");
+    expect(bubble.style.color).toBe(
+      "var(--persona-message-assistant-text, var(--persona-text))"
+    );
+
+    destroy();
+  });
+
+  it("renders bare text classes when loadingIndicator.showBubble is false", async () => {
+    const { bubble, destroy } = await renderTypingBubble({
+      loadingIndicator: { showBubble: false },
+    });
+
+    expect(bubble.classList.contains("persona-message-assistant-bubble")).toBe(false);
+    expect(bubble.classList.contains("persona-shadow-sm")).toBe(false);
+    expect(bubble.classList.contains("persona-border")).toBe(false);
+    expect(bubble.classList.contains("persona-text-persona-text")).toBe(true);
+    expect(bubble.classList.contains("persona-text-persona-primary")).toBe(false);
+    expect(bubble.style.backgroundColor).toBe("");
+
+    destroy();
+  });
+
+  it("honors the assistant bubble theme background token", async () => {
+    const { bubble, destroy } = await renderTypingBubble({
+      layout: { messages: { layout: "minimal" } },
+      theme: {
+        semantic: {
+          colors: {
+            container: "#112233",
+            text: "#ddeeff",
+            border: "#445566",
+          },
+        },
+      },
+    });
+
+    // The bubble reads the same variable the assistant message bubbles read,
+    // so `theme.components.message.assistant.background` covers both.
+    expect(bubble.style.backgroundColor).toBe(
+      "var(--persona-message-assistant-bg, var(--persona-container))"
+    );
+    const root = bubble.closest<HTMLElement>("[data-persona-root]");
+    expect(root?.style.getPropertyValue("--persona-message-assistant-bg")).toBe(
+      "#112233"
+    );
+    expect(root?.style.getPropertyValue("--persona-message-assistant-text")).toBe(
+      "#ddeeff"
+    );
+    expect(root?.style.getPropertyValue("--persona-message-assistant-border")).toBe(
+      "#445566"
+    );
+
+    destroy();
+  });
+});