@runtypelabs/persona 3.15.1 → 3.17.0

package/src/components/message-bubble.test.ts

@@ -1,7 +1,12 @@
 // @vitest-environment jsdom
 import { describe, it, expect } from "vitest";
-import { createStandardBubble, isSafeImageSrc } from "./message-bubble";
-import type { AgentWidgetMessage } from "../types";
+import {
+  createStandardBubble,
+  isSafeImageSrc,
+  resolveStopReasonNoticeText,
+  getDefaultStopReasonNoticeCopy,
+} from "./message-bubble";
+import type { AgentWidgetConfig, AgentWidgetMessage } from "../types";
 
 const makeMessage = (overrides: Partial<AgentWidgetMessage> = {}): AgentWidgetMessage => ({
   id: "msg-1",
@@ -95,3 +100,177 @@ describe("createStandardBubble", () => {
     expect(previewImages[0]?.getAttribute("alt")).toBe("Safe image");
   });
 });
+
+describe("resolveStopReasonNoticeText", () => {
+  it("returns null for natural completions", () => {
+    expect(resolveStopReasonNoticeText("end_turn")).toBeNull();
+  });
+
+  it("returns null for unknown reasons", () => {
+    expect(resolveStopReasonNoticeText("unknown")).toBeNull();
+  });
+
+  it("returns null when stopReason is undefined", () => {
+    expect(resolveStopReasonNoticeText(undefined)).toBeNull();
+  });
+
+  it("returns the default copy for actionable reasons", () => {
+    expect(resolveStopReasonNoticeText("max_tool_calls")).toBe(
+      getDefaultStopReasonNoticeCopy("max_tool_calls")
+    );
+    expect(resolveStopReasonNoticeText("length")).toBe(
+      getDefaultStopReasonNoticeCopy("length")
+    );
+    expect(resolveStopReasonNoticeText("content_filter")).toBe(
+      getDefaultStopReasonNoticeCopy("content_filter")
+    );
+    expect(resolveStopReasonNoticeText("error")).toBe(
+      getDefaultStopReasonNoticeCopy("error")
+    );
+  });
+
+  it("applies overrides on a per-key basis", () => {
+    expect(
+      resolveStopReasonNoticeText("max_tool_calls", {
+        ["max_tool_calls" as const]: "Custom override.",
+      })
+    ).toBe("Custom override.");
+  });
+
+  it("falls back to defaults for keys not overridden", () => {
+    expect(
+      resolveStopReasonNoticeText("length", {
+        ["max_tool_calls" as const]: "Custom.",
+      })
+    ).toBe(getDefaultStopReasonNoticeCopy("length"));
+  });
+
+  it("suppresses the notice when override is an empty string", () => {
+    expect(
+      resolveStopReasonNoticeText("max_tool_calls", {
+        ["max_tool_calls" as const]: "",
+      })
+    ).toBeNull();
+  });
+});
+
+describe("createStandardBubble — stopReason notice", () => {
+  const renderWithStopReason = (
+    overrides: Partial<AgentWidgetMessage>,
+    widgetConfig?: Partial<AgentWidgetConfig>
+  ) =>
+    createStandardBubble(
+      makeMessage(overrides),
+      ({ text }) => text,
+      undefined,
+      undefined,
+      undefined,
+      { widgetConfig: widgetConfig as AgentWidgetConfig | undefined }
+    );
+
+  it("renders no notice for end_turn (natural completion)", () => {
+    const bubble = renderWithStopReason({
+      content: "All done.",
+      stopReason: "end_turn",
+    });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+
+  it("renders no notice when stopReason is absent (backcompat)", () => {
+    const bubble = renderWithStopReason({ content: "Hello." });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+
+  it("renders no notice for unknown reasons", () => {
+    const bubble = renderWithStopReason({
+      content: "Hello.",
+      stopReason: "unknown",
+    });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+
+  it("renders the default notice for max_tool_calls", () => {
+    const bubble = renderWithStopReason({
+      content: "Used a tool.",
+      stopReason: "max_tool_calls",
+    });
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice).not.toBeNull();
+    expect(notice?.getAttribute("data-stop-reason")).toBe("max_tool_calls");
+    expect(notice?.textContent).toBe(getDefaultStopReasonNoticeCopy("max_tool_calls"));
+  });
+
+  it("renders the default notice for length", () => {
+    const bubble = renderWithStopReason({
+      content: "Long answer cut off.",
+      stopReason: "length",
+    });
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice?.getAttribute("data-stop-reason")).toBe("length");
+    expect(notice?.textContent).toBe(getDefaultStopReasonNoticeCopy("length"));
+  });
+
+  it("renders the default notice for content_filter", () => {
+    const bubble = renderWithStopReason({
+      content: "Filtered.",
+      stopReason: "content_filter",
+    });
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice?.getAttribute("data-stop-reason")).toBe("content_filter");
+  });
+
+  it("renders the default notice for error", () => {
+    const bubble = renderWithStopReason({
+      content: "Provider blew up.",
+      stopReason: "error",
+    });
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice?.getAttribute("data-stop-reason")).toBe("error");
+  });
+
+  it("applies copy overrides from widgetConfig.copy.stopReasonNotice", () => {
+    const bubble = renderWithStopReason(
+      { content: "x", stopReason: "max_tool_calls" },
+      { copy: { stopReasonNotice: { ["max_tool_calls" as const]: "Custom copy." } } }
+    );
+    expect(bubble.querySelector(".persona-message-stop-reason")?.textContent).toBe(
+      "Custom copy."
+    );
+  });
+
+  it("hides the empty content div when content is empty + max_tool_calls", () => {
+    // Regression: the empty-bubble symptom the upstream Runtype fix targets.
+    // With no content and max_tool_calls, the notice carries the bubble alone;
+    // the empty content div must be hidden so we don't render whitespace
+    // above the notice.
+    const bubble = renderWithStopReason({
+      content: "",
+      stopReason: "max_tool_calls",
+    });
+    const contentDiv = bubble.querySelector(".persona-message-content") as HTMLElement | null;
+    expect(contentDiv).not.toBeNull();
+    expect(contentDiv!.style.display).toBe("none");
+    const notice = bubble.querySelector(".persona-message-stop-reason");
+    expect(notice).not.toBeNull();
+    expect(notice?.getAttribute("data-stop-reason")).toBe("max_tool_calls");
+  });
+
+  it("does not render notice while message is still streaming", () => {
+    const bubble = renderWithStopReason({
+      content: "partial",
+      stopReason: "max_tool_calls",
+      streaming: true,
+    });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+
+  it("does not render notice on user messages", () => {
+    const bubble = renderWithStopReason({
+      role: "user",
+      content: "user msg",
+      // stopReason on a user message is nonsense, but guard against it
+      stopReason: "max_tool_calls",
+    });
+    expect(bubble.querySelector(".persona-message-stop-reason")).toBeNull();
+  });
+});

package/src/components/message-bubble.ts

@@ -7,10 +7,85 @@ import {
   AgentWidgetMessageActionsConfig,
   AgentWidgetMessageFeedback,
   LoadingIndicatorRenderContext,
-  ImageContentPart
+  ImageContentPart,
+  StopReasonKind
 } from "../types";
 import { createIconButton } from "../utils/buttons";
 import { IMAGE_ONLY_MESSAGE_FALLBACK_TEXT } from "../utils/content";
+import {
+  applyStreamBuffer,
+  createSkeletonPlaceholder,
+  createStreamCaret,
+  resolveStreamAnimation,
+  resolveStreamAnimationPlugin,
+  wrapStreamAnimation,
+} from "../utils/stream-animation";
+
+/**
+ * Default copy for the inline notice rendered when a turn ends with a
+ * non-natural stop reason. Deployers override per-reason via
+ * `config.copy.stopReasonNotice`. Returns `null` for natural completions
+ * (`end_turn`) and uninformative reasons (`unknown`) — those never render
+ * an affordance.
+ */
+export const getDefaultStopReasonNoticeCopy = (
+  stopReason: StopReasonKind
+): string | null => {
+  switch (stopReason) {
+    case "max_tool_calls":
+      return "Stopped after calling a tool. Send a follow-up to continue.";
+    case "length":
+      return "Response cut off as max tokens reached. Ask for more to continue.";
+    case "content_filter":
+      return "The provider filtered this response.";
+    case "error":
+      return "Something went wrong generating this response.";
+    case "end_turn":
+    case "unknown":
+    default:
+      return null;
+  }
+};
+
+/**
+ * Resolve the notice text for a stop reason, applying user overrides on
+ * top of the built-in defaults. Returns `null` when the reason does not
+ * warrant a notice or when the resolved string is empty (deployers can
+ * suppress per-reason by setting an empty override).
+ */
+export const resolveStopReasonNoticeText = (
+  stopReason: StopReasonKind | undefined,
+  overrides?: Partial<Record<StopReasonKind, string>>
+): string | null => {
+  if (!stopReason) return null;
+  const fallback = getDefaultStopReasonNoticeCopy(stopReason);
+  // Reasons without a default (end_turn, unknown) never render — overrides
+  // for those keys are intentionally ignored.
+  if (fallback === null) return null;
+  const override = overrides?.[stopReason];
+  const text = override !== undefined ? override : fallback;
+  if (!text) return null;
+  return text;
+};
+
+/**
+ * Build the inline notice element rendered on assistant bubbles whose
+ * turn ended with `max_tool_calls`, `length`, `content_filter`, or `error`.
+ */
+const createStopReasonNotice = (
+  stopReason: StopReasonKind,
+  text: string
+): HTMLElement => {
+  const notice = createElement(
+    "div",
+    "persona-message-stop-reason persona-text-xs persona-mt-2 persona-italic"
+  );
+  notice.setAttribute("data-stop-reason", stopReason);
+  notice.setAttribute("role", "note");
+  notice.style.opacity = "0.75";
+  notice.textContent = text;
+  return notice;
+};
 
 /** Validate that an image src URL uses a safe scheme (blocks javascript: and SVG data URIs). */
 export const isSafeImageSrc = (src: string): boolean => {
@@ -507,24 +582,107 @@ export const createStandardBubble = (
     imageParts.length > 0 && messageContentText === IMAGE_ONLY_MESSAGE_FALLBACK_TEXT;
   const shouldHideTextUntilPreviewFails = isImageOnlyFallbackMessage;
 
+  const streamAnimation = resolveStreamAnimation(
+    options?.widgetConfig?.features?.streamAnimation
+  );
+  const streamPluginOverrides =
+    options?.widgetConfig?.features?.streamAnimation?.plugins;
+  const streamPlugin =
+    message.role === "assistant" && streamAnimation.type !== "none"
+      ? resolveStreamAnimationPlugin(streamAnimation.type, streamPluginOverrides)
+      : null;
+  // Stay in "streaming-animated" mode while the plugin reports in-flight
+  // work for this message — e.g. glyph-cycle's tick loops still walking
+  // through the tail after the last token arrived. Without this, the final
+  // non-animated render rips out the cycling spans mid-animation.
+  const pluginStillAnimating =
+    message.role === "assistant" &&
+    streamPlugin?.isAnimating?.(message) === true;
+  const streamAnimationActive =
+    message.role === "assistant" &&
+    streamPlugin !== null &&
+    (Boolean(message.streaming) || pluginStillAnimating);
+
+  if (streamAnimationActive && streamPlugin?.bubbleClass) {
+    bubble.classList.add(streamPlugin.bubbleClass);
+  }
+
   // Add message content
   const contentDiv = document.createElement("div");
   contentDiv.classList.add("persona-message-content");
+
+  if (streamAnimationActive && streamPlugin) {
+    if (streamPlugin.containerClass) {
+      contentDiv.classList.add(streamPlugin.containerClass);
+    }
+    contentDiv.style.setProperty("--persona-stream-step", `${streamAnimation.speed}ms`);
+    contentDiv.style.setProperty("--persona-stream-duration", `${streamAnimation.duration}ms`);
+  }
+
+  const bufferedContent = streamAnimationActive
+    ? applyStreamBuffer(
+        message.content ?? "",
+        streamAnimation.buffer,
+        streamPlugin,
+        message,
+        Boolean(message.streaming)
+      )
+    : (message.content ?? "");
+
   const transformedContent = transform({
-    text: message.content,
+    text: bufferedContent,
     message,
     streaming: Boolean(message.streaming),
     raw: message.rawContent
   });
+
+  let animatedContent = transformedContent;
+  if (streamAnimationActive && streamPlugin?.wrap === "char") {
+    animatedContent = wrapStreamAnimation(transformedContent, "char", message.id, {
+      skipTags: streamPlugin.skipTags,
+    });
+  } else if (streamAnimationActive && streamPlugin?.wrap === "word") {
+    animatedContent = wrapStreamAnimation(transformedContent, "word", message.id, {
+      skipTags: streamPlugin.skipTags,
+    });
+  }
+
   let textContentDiv: HTMLElement | null = null;
 
   if (shouldHideTextUntilPreviewFails) {
     textContentDiv = document.createElement("div");
-    textContentDiv.innerHTML = transformedContent;
+    textContentDiv.innerHTML = animatedContent;
     textContentDiv.style.display = "none";
     contentDiv.appendChild(textContentDiv);
   } else {
-    contentDiv.innerHTML = transformedContent;
+    contentDiv.innerHTML = animatedContent;
+  }
+
+  if (
+    streamAnimationActive &&
+    streamPlugin?.useCaret &&
+    !shouldHideTextUntilPreviewFails &&
+    messageContentText
+  ) {
+    const caret = createStreamCaret();
+    // Caret must sit on the same line as the final char. Markdown wraps text
+    // in block elements (<p>, <li>, <pre>), so appending to contentDiv would
+    // drop the caret onto a fresh line. Tuck it after the last char/word span,
+    // or fall back to the last block when no spans exist yet.
+    const spans = contentDiv.querySelectorAll(
+      ".persona-stream-char, .persona-stream-word"
+    );
+    const lastSpan = spans[spans.length - 1];
+    if (lastSpan?.parentNode) {
+      lastSpan.parentNode.insertBefore(caret, lastSpan.nextSibling);
+    } else {
+      const lastChild = contentDiv.lastElementChild;
+      if (lastChild) {
+        lastChild.appendChild(caret);
+      } else {
+        contentDiv.appendChild(caret);
+      }
+    }
   }
 
   // Add inline timestamp if configured
@@ -561,19 +719,56 @@ export const createStandardBubble = (
     bubble.appendChild(timestamp);
   }
 
-  // Add typing indicator if this is a streaming assistant message
+  // Resolve the stop-reason notice (if any). Only assistant messages can
+  // carry a stop reason worth surfacing.
+  const stopReasonNoticeText =
+    message.role === "assistant"
+      ? resolveStopReasonNoticeText(
+          message.stopReason,
+          options?.widgetConfig?.copy?.stopReasonNotice
+        )
+      : null;
+
+  // Add typing indicator (or skeleton placeholder) for streaming assistant
+  // messages. Check the buffered content — a plugin's `bufferContent` may
+  // hold back the first N chars (e.g. glyph-cycle waits for 50 chars), during
+  // which the bubble would otherwise appear empty.
+  //
+  // When the `"line"` buffer strategy is paired with the skeleton placeholder,
+  // the skeleton trails below any already-revealed content to hint that more
+  // lines are on the way. It disappears on stream completion.
   if (message.streaming && message.role === "assistant") {
-    if (!message.content || !message.content.trim()) {
-      // Use custom renderer if provided, otherwise default
-      const indicator = renderLoadingIndicatorWithFallback(
-        'inline',
-        options?.loadingIndicatorRenderer,
-        options?.widgetConfig
-      );
-      if (indicator) {
-        bubble.appendChild(indicator);
+    const hasVisibleContent = Boolean(bufferedContent && bufferedContent.trim());
+    const skeletonEnabled = streamAnimation.placeholder === "skeleton";
+    const trailSkeleton =
+      skeletonEnabled && streamAnimation.buffer === "line" && hasVisibleContent;
+    if (!hasVisibleContent) {
+      if (skeletonEnabled) {
+        bubble.appendChild(createSkeletonPlaceholder());
+      } else {
+        const indicator = renderLoadingIndicatorWithFallback(
+          'inline',
+          options?.loadingIndicatorRenderer,
+          options?.widgetConfig
+        );
+        if (indicator) {
+          bubble.appendChild(indicator);
+        }
       }
+    } else if (trailSkeleton) {
+      bubble.appendChild(createSkeletonPlaceholder());
+    }
+  }
+
+  // Append the stop-reason notice for non-natural completions. When the
+  // assistant produced no text (the `max_tool_calls` empty-bubble symptom),
+  // hide the empty content div so the notice carries the entire bubble
+  // instead of trailing under a blank space.
+  if (stopReasonNoticeText && message.stopReason && !message.streaming) {
+    if (!messageContentText) {
+      contentDiv.style.display = "none";
     }
+    bubble.appendChild(createStopReasonNotice(message.stopReason, stopReasonNoticeText));
   }
 
   // Add message actions for assistant messages (only when not streaming and has content)

package/src/components/panel.ts

@@ -110,6 +110,8 @@ export interface PanelElements {
   actionsRow: HTMLElement;
   leftActions: HTMLElement;
   rightActions: HTMLElement;
+  /** Swap the send button between its send and stop appearances. */
+  setSendButtonMode: (mode: "send" | "stop") => void;
 }
 
 export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelElements => {
@@ -230,7 +232,8 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     // Actions row layout elements
     actionsRow: composerElements.actionsRow,
     leftActions: composerElements.leftActions,
-    rightActions: composerElements.rightActions
+    rightActions: composerElements.rightActions,
+    setSendButtonMode: composerElements.setSendButtonMode
   };
 };
 

package/src/defaults.ts

@@ -43,6 +43,12 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
     agentIconSize: "40px",
     headerIconSize: "40px",
     closeButtonSize: "32px",
+    // Zero out browser-default <button> padding so the icon gets the full
+    // 32x32 content box, matching clearChat.paddingX/Y below. Without this,
+    // UA stylesheets add ~1-2px vertical and ~6px horizontal padding that
+    // eats into the border-box width and shrinks the rendered icon.
+    closeButtonPaddingX: "0px",
+    closeButtonPaddingY: "0px",
     callToActionIconName: "arrow-up-right",
     callToActionIconText: "",
     callToActionIconSize: "32px",
@@ -131,6 +137,12 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
       expandable: true,
       loadingAnimation: "none",
     },
+    streamAnimation: {
+      type: "none",
+      placeholder: "none",
+      speed: 120,
+      duration: 1800,
+    },
   },
   suggestionChips: [
     "What can you help me with?",
@@ -245,6 +257,8 @@ export function mergeWithDefaults(
       const ca = config.features?.artifacts;
       const dsb = DEFAULT_WIDGET_CONFIG.features?.scrollToBottom;
       const csb = config.features?.scrollToBottom;
+      const dsa = DEFAULT_WIDGET_CONFIG.features?.streamAnimation;
+      const csa = config.features?.streamAnimation;
       const mergedArtifacts =
         da === undefined && ca === undefined
           ? undefined
@@ -263,11 +277,19 @@ export function mergeWithDefaults(
               ...dsb,
               ...csb,
             };
+      const mergedStreamAnimation =
+        dsa === undefined && csa === undefined
+          ? undefined
+          : {
+              ...dsa,
+              ...csa,
+            };
       return {
         ...DEFAULT_WIDGET_CONFIG.features,
         ...config.features,
         ...(mergedScrollToBottom !== undefined ? { scrollToBottom: mergedScrollToBottom } : {}),
         ...(mergedArtifacts !== undefined ? { artifacts: mergedArtifacts } : {}),
+        ...(mergedStreamAnimation !== undefined ? { streamAnimation: mergedStreamAnimation } : {}),
       };
     })(),
     suggestionChips: config.suggestionChips ?? DEFAULT_WIDGET_CONFIG.suggestionChips,

package/src/index-global.ts

@@ -0,0 +1,31 @@
+/**
+ * IIFE entry point — bundled for `<script>` tag consumers.
+ *
+ * This file re-exports everything from the main entry AND side-imports all
+ * built-in subpath animations so they register automatically. Script-tag
+ * users who include the global build don't need extra script tags or
+ * registration calls — setting `features.streamAnimation.type` to any
+ * built-in name just works.
+ *
+ * npm consumers continue to import from the main entry (`import ... from
+ * "@runtypelabs/persona"`) — those animations stay in their subpath
+ * modules so bundlers can tree-shake them.
+ */
+
+// Re-export the full public API.
+export * from "./index";
+
+// Side-import the remaining subpath animations so they're available to
+// script-tag consumers without an explicit import. (`letter-rise` and
+// `word-fade` are core built-ins and register automatically.)
+import "./animations/wipe";
+import "./animations/glyph-cycle";
+
+// Expose plugin-registration helpers on the global so custom animations
+// can be registered from inline `<script>` blocks or third-party CDN scripts.
+export {
+  registerStreamAnimationPlugin,
+  unregisterStreamAnimationPlugin,
+  listRegisteredStreamAnimations,
+} from "./utils/stream-animation";
+export type { StreamAnimationPlugin, StreamAnimationContext } from "./types";

package/src/index.ts

@@ -178,6 +178,24 @@ export type { AgentWidgetInitHandle };
 export type { AgentWidgetPlugin } from "./plugins/types";
 export { pluginRegistry } from "./plugins/registry";
 
+// Stream animation plugin API — lets consumers register custom animations
+// that match the built-in surface (typewriter, pop-bubble) and subpath
+// modules (letter-rise, word-fade, wipe, glyph-cycle).
+export {
+  registerStreamAnimationPlugin,
+  unregisterStreamAnimationPlugin,
+  listRegisteredStreamAnimations,
+} from "./utils/stream-animation";
+export type {
+  StreamAnimationPlugin,
+  StreamAnimationContext,
+  AgentWidgetStreamAnimationBuffer,
+  AgentWidgetStreamAnimationBuiltinType,
+  AgentWidgetStreamAnimationType,
+  AgentWidgetStreamAnimationFeature,
+  AgentWidgetStreamAnimationPlaceholder,
+} from "./types";
+
 // Dropdown utility exports
 export { createDropdownMenu } from "./utils/dropdown";
 export type { DropdownMenuItem, CreateDropdownOptions, DropdownMenuHandle } from "./utils/dropdown";

package/src/session.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
 import { AgentWidgetSession, AgentWidgetSessionStatus } from './session';
 import { AgentWidgetMessage } from './types';
 
@@ -245,3 +245,95 @@ describe('AgentWidgetSession - Message Injection', () => {
     });
   });
 });
+
+describe('AgentWidgetSession - cancel()', () => {
+  const originalFetch = global.fetch;
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  it('aborts the in-flight dispatch and flips streaming/status back to idle', async () => {
+    let capturedSignal: AbortSignal | null = null;
+    // Fetch returns a promise that only settles when the AbortSignal fires —
+    // modeling a dispatch that's still receiving SSE tokens.
+    global.fetch = vi.fn().mockImplementation((_url: string, options: any) => {
+      capturedSignal = options.signal as AbortSignal;
+      return new Promise((_resolve, reject) => {
+        options.signal?.addEventListener('abort', () => {
+          const err = new Error('aborted');
+          err.name = 'AbortError';
+          reject(err);
+        });
+      });
+    });
+
+    let streaming = false;
+    let status: AgentWidgetSessionStatus = 'idle';
+    const session = new AgentWidgetSession(
+      { apiUrl: 'http://example.invalid/chat' },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: (s) => { status = s; },
+        onStreamingChanged: (s) => { streaming = s; }
+      }
+    );
+
+    // Kick off the dispatch but don't await — we want it in-flight when we cancel.
+    const dispatchPromise = session.sendMessage('Hello');
+    // Let the session set up the AbortController and call fetch.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(streaming).toBe(true);
+    expect(session.isStreaming()).toBe(true);
+    expect(capturedSignal).not.toBeNull();
+    expect(capturedSignal!.aborted).toBe(false);
+
+    session.cancel();
+
+    expect(session.isStreaming()).toBe(false);
+    expect(streaming).toBe(false);
+    expect(status).toBe('idle');
+    expect(capturedSignal!.aborted).toBe(true);
+
+    // Drain the dispatch promise so the test doesn't leak a rejection.
+    await dispatchPromise;
+  });
+
+  it('is a no-op when not streaming', () => {
+    const session = new AgentWidgetSession(
+      { apiUrl: 'http://example.invalid/chat' },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {}
+      }
+    );
+
+    expect(session.isStreaming()).toBe(false);
+    expect(() => session.cancel()).not.toThrow();
+    expect(session.isStreaming()).toBe(false);
+    expect(session.getStatus()).toBe('idle');
+  });
+
+  it('stops in-progress audio playback (TTS + voice provider) on cancel', () => {
+    const session = new AgentWidgetSession(
+      { apiUrl: 'http://example.invalid/chat' },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {}
+      }
+    );
+
+    const stopSpeakingSpy = vi.spyOn(session, 'stopSpeaking');
+    const stopVoicePlaybackSpy = vi.spyOn(session, 'stopVoicePlayback');
+
+    session.cancel();
+
+    expect(stopSpeakingSpy).toHaveBeenCalledTimes(1);
+    expect(stopVoicePlaybackSpy).toHaveBeenCalledTimes(1);
+  });
+});