@runtypelabs/persona 3.18.0 → 3.19.0

package/src/runtime/persist-state.test.ts

@@ -0,0 +1,152 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "../ui";
+import { createLocalStorageAdapter } from "../utils/storage";
+import type { AgentWidgetStorageAdapter } from "../types";
+
+const DEFAULT_KEY = "persona-state";
+
+const baseConfig = () => ({
+  apiUrl: "https://api.example.com/chat",
+  launcher: { enabled: false } as const,
+});
+
+const inject = (controller: ReturnType<typeof createAgentExperience>) =>
+  controller.injectAssistantMessage({ content: "hello world" });
+
+describe("persistState gates storage adapter", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    try {
+      window.localStorage.clear();
+    } catch {
+      /* jsdom edge cases */
+    }
+  });
+
+  it("persistState: false skips the default localStorage adapter", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      persistState: false,
+    });
+
+    inject(controller);
+
+    expect(window.localStorage.getItem(DEFAULT_KEY)).toBeNull();
+    controller.destroy();
+  });
+
+  it("persistState: false ignores any user-supplied storageAdapter (strict semantic)", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const customAdapter: AgentWidgetStorageAdapter = {
+      load: vi.fn(() => null),
+      save: vi.fn(),
+      clear: vi.fn(),
+    };
+
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      persistState: false,
+      storageAdapter: customAdapter,
+    });
+
+    inject(controller);
+
+    expect(customAdapter.load).not.toHaveBeenCalled();
+    expect(customAdapter.save).not.toHaveBeenCalled();
+    controller.destroy();
+  });
+
+  it("default config (persistState undefined) writes to the default localStorage key", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const controller = createAgentExperience(mount, baseConfig());
+
+    inject(controller);
+
+    const stored = window.localStorage.getItem(DEFAULT_KEY);
+    expect(stored).not.toBeNull();
+    const parsed = JSON.parse(stored!);
+    expect(parsed.messages).toBeInstanceOf(Array);
+    expect(parsed.messages.length).toBeGreaterThan(0);
+    controller.destroy();
+  });
+
+  it("persistState: true keeps using the default localStorage adapter", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      persistState: true,
+    });
+
+    inject(controller);
+
+    expect(window.localStorage.getItem(DEFAULT_KEY)).not.toBeNull();
+    controller.destroy();
+  });
+
+  it("two widgets with different storageAdapter keys keep their messages isolated", () => {
+    const mountA = document.createElement("div");
+    const mountB = document.createElement("div");
+    document.body.appendChild(mountA);
+    document.body.appendChild(mountB);
+
+    const controllerA = createAgentExperience(mountA, {
+      ...baseConfig(),
+      storageAdapter: createLocalStorageAdapter("persona-state-test-a"),
+    });
+    const controllerB = createAgentExperience(mountB, {
+      ...baseConfig(),
+      storageAdapter: createLocalStorageAdapter("persona-state-test-b"),
+    });
+
+    controllerA.injectAssistantMessage({ content: "message in A" });
+    controllerB.injectAssistantMessage({ content: "message in B" });
+
+    const storedA = JSON.parse(window.localStorage.getItem("persona-state-test-a")!);
+    const storedB = JSON.parse(window.localStorage.getItem("persona-state-test-b")!);
+
+    const aHasA = storedA.messages.some((m: { content?: string }) => m.content === "message in A");
+    const aHasB = storedA.messages.some((m: { content?: string }) => m.content === "message in B");
+    const bHasA = storedB.messages.some((m: { content?: string }) => m.content === "message in A");
+    const bHasB = storedB.messages.some((m: { content?: string }) => m.content === "message in B");
+
+    expect(aHasA).toBe(true);
+    expect(aHasB).toBe(false);
+    expect(bHasB).toBe(true);
+    expect(bHasA).toBe(false);
+    expect(window.localStorage.getItem(DEFAULT_KEY)).toBeNull();
+
+    controllerA.destroy();
+    controllerB.destroy();
+  });
+
+  it("persistState: false does not read from localStorage on init", () => {
+    // Pre-seed the default key with a stored message.
+    window.localStorage.setItem(
+      DEFAULT_KEY,
+      JSON.stringify({ messages: [{ id: "stale", role: "assistant", content: "stale" }] })
+    );
+
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      persistState: false,
+    });
+
+    expect(controller.getMessages()).toEqual([]);
+    controller.destroy();
+  });
+});

package/src/styles/widget.css

@@ -3389,3 +3389,351 @@
     animation: none !important;
   }
 }
+
+/* ===========================================================================
+ * Composer-bar mode (`launcher.mountMode: "composer-bar"`)
+ *
+ * Geometry (position, width, height) is set per-state inline by
+ * `applyComposerBarGeometry()` in ui.ts. The pill composer
+ * (`pill-composer-builder.ts`) ships with its own clean className
+ * (`persona-pill-composer`, no `persona-flex-col` / `persona-rounded-2xl`
+ * baggage), so layout CSS does not need to fight utility classes — no
+ * !important. The pill is the visible element in both collapsed and
+ * expanded states; only the panel above it appears/disappears.
+ *
+ * Avoid `transform: scale(...)` on the wrapper — it breaks the textarea
+ * caret/IME.
+ * ======================================================================= */
+.persona-widget-wrapper[data-persona-composer-bar] {
+  /* Flex column so the inner panel (which has `flex-1`) fills the wrapper.
+   * Without this, the panel would shrink-wrap its children (chat container
+   * + pill) and a gap would appear between the pill and the wrapper's
+   * `bottom: 16px` edge. */
+  display: flex;
+  flex-direction: column;
+  transition:
+    max-width 220ms ease,
+    bottom 220ms ease,
+    top 220ms ease,
+    left 220ms ease,
+    right 220ms ease,
+    transform 220ms ease,
+    border-radius 220ms ease,
+    height 220ms ease,
+    width 220ms ease;
+}
+
+/* Modal and anchored: the wrapper goes from collapsed (no inline geometry,
+ * so `top/left/transform` resolve to their auto/none defaults) to its
+ * expanded position. The default `transform 220ms ease` transition would
+ * interpolate `none → translate(...)` and visibly slide the wrapper from
+ * its static-default origin toward its target — diagonally for modal,
+ * horizontally from the right for anchored. Neither mode is morphing
+ * something the user can see (the wrapper is invisible when collapsed
+ * because the pill lives in pillRoot, not the wrapper), so the slide
+ * is pure motion noise. Disable geometry transitions for both; the
+ * container's opacity fade-in keyframe is the reveal.
+ *
+ * Fullscreen intentionally keeps its geometry transition — that's the
+ * one mode where the wrapper genuinely morphs (empty → full viewport),
+ * and the staggered fade-in cascade below is built to mask the
+ * outer-edge/inner-content desync during that morph. */
+.persona-widget-wrapper[data-persona-composer-bar][data-expanded-size="modal"],
+.persona-widget-wrapper[data-persona-composer-bar][data-expanded-size="anchored"] {
+  transition: none;
+}
+
+/* --- Pill composer chrome (always visible in composer-bar mode) -------- */
+
+/* Pill is a single-row grid: paperclip · textarea · mic + send. */
+.persona-pill-composer {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 14px;
+  border-radius: 9999px;
+  background: var(--persona-surface, #ffffff);
+  border: 1px solid var(--persona-border, #e5e7eb);
+  box-shadow:
+    0 6px 24px rgba(15, 23, 42, 0.10),
+    0 1px 2px rgba(15, 23, 42, 0.04);
+}
+
+.persona-pill-composer .persona-composer-textarea {
+  /* Single line by default; the autoresize closure expands up to the
+   * max-height set inline by pill-composer-builder (100px). Width 100%
+   * fills the `1fr` middle grid cell so wrapping only happens once the
+   * pill itself can't grow any wider. */
+  min-height: 24px;
+  width: 100%;
+  padding: 4px 0;
+}
+
+/* Responsive default width for the collapsed pill — applied only when
+ * `applyComposerBarGeometry()` leaves the wrapper's inline width empty
+ * (i.e., the user did NOT set `composerBar.collapsedMaxWidth`). Inline
+ * width from a user config still wins via specificity (inline > class). */
+/* Pill responsive widths now live on the viewport-fixed pillRoot below;
+ * the wrapper no longer doubles as the pill container. */
+
+/* The action cells host inline-flex buttons; without explicit flex layout
+ * on the cell, the buttons sit on the inline baseline and the cell extends
+ * below them with descender space, making the buttons look top-aligned. */
+.persona-pill-composer__left,
+.persona-pill-composer__right {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+/* Footer wrapping the pill: transparent surface, vertical stack with
+ * room above the pill for the previews row. */
+.persona-widget-footer--pill {
+  background: transparent;
+  border-top: none;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+/* Attachment previews row (above the pill). AttachmentManager toggles
+ * display:flex when items are added; default is display:none. */
+.persona-pill-composer__previews {
+  padding: 0 8px;
+}
+
+/* --- Container chrome ---------------------------------------------------
+ *
+ * Container chrome (background, border, border-radius, box-shadow) is
+ * applied inline by `applyFullHeightStyles()` in ui.ts so it can flow through
+ * the same `theme.components.panel.{shadow,border,borderRadius}` contract
+ * used by every other mount mode. Collapsed hides the container entirely
+ * (only the pill is visible); expanded re-applies the chrome. The
+ * `fullscreen` expanded variant intentionally stays chrome-less. */
+
+/* Composer overlay (interactive sheets like ask_user_question) hidden in
+ * collapsed; the pill has no room and the panel above is gone anyway. */
+[data-persona-composer-bar][data-state="collapsed"] .persona-composer-overlay {
+  display: none;
+}
+
+/* --- Pill root: viewport-fixed sibling of the wrapper ------------------
+ *
+ * In composer-bar mode the pill (`footer`) and peek banner live in a
+ * viewport-fixed sibling of the wrapper, NOT inside the wrapper. Reason:
+ * modal mode applies `transform: translate(-50%, -50%)` to the wrapper,
+ * which establishes a containing block for `position: fixed` descendants —
+ * a fixed pill inside a transformed wrapper would be positioned relative
+ * to the wrapper, not the viewport.
+ *
+ * Bottom offset and (optionally) width are written inline by ui.ts based
+ * on `launcher.composerBar.{bottomOffset, collapsedMaxWidth}`; otherwise
+ * the responsive defaults below apply. The pillRoot mirrors the wrapper's
+ * `[data-state]` and `[data-expanded-size]` attributes so peek/pill rules
+ * keyed off those attributes still cascade. */
+.persona-widget-pill-root {
+  position: fixed;
+  bottom: 16px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 90vw;
+  max-width: calc(100vw - 32px);
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+@media (min-width: 640px) {
+  .persona-widget-pill-root {
+    width: 70vw;
+  }
+}
+@media (min-width: 1024px) {
+  .persona-widget-pill-root {
+    width: 50vw;
+  }
+}
+
+/* Container hidden when the chat is collapsed — only the pill is visible. */
+[data-persona-composer-bar][data-state="collapsed"] .persona-widget-container {
+  display: none;
+}
+
+/* --- Peek banner ------------------------------------------------------- */
+/* The peek is the chrome-less row above the pill (composer-bar mode only)
+ * that previews the trailing 100 chars of the most recent assistant
+ * message. ui.ts toggles `--visible` based on streaming/hover/open state;
+ * pointer-events are gated so the faded-out peek never swallows clicks
+ * targeted at the pill below. */
+.persona-pill-peek {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 14px;
+  /* Frosted-glass chrome so the text stays readable over arbitrary host
+   * backgrounds (busy hero images, dark sections, brand colors). The
+   * translucent fill + backdrop blur turns the underlying area into a
+   * neutral surface; the hairline border + soft shadow define the edge
+   * without competing with the pill below. */
+  background: rgba(255, 255, 255, 0.78);
+  -webkit-backdrop-filter: blur(10px) saturate(1.5);
+  backdrop-filter: blur(10px) saturate(1.5);
+  border: 1px solid rgba(0, 0, 0, 0.06);
+  border-radius: 9999px;
+  box-shadow: 0 2px 8px rgba(15, 23, 42, 0.06);
+  color: var(--persona-primary, #111827);
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.4;
+  cursor: pointer;
+  opacity: 0;
+  pointer-events: none;
+  transform: translateY(2px);
+  transition:
+    opacity 150ms ease,
+    transform 150ms ease,
+    background-color 150ms ease;
+  text-align: left;
+  /* Full-width row that matches the pill below — text takes the middle
+   * (flex: 1 1 auto) and the chevron pins to the right edge. */
+  width: 100%;
+  align-self: stretch;
+}
+
+/* Browsers without backdrop-filter support (older Firefox, some webviews)
+ * fall through to a slightly more opaque solid surface so the underlying
+ * page can't bleed through. The non-supports rule above already gives a
+ * usable look (78% opacity); this just hardens it for non-blur fallback. */
+@supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+  .persona-pill-peek {
+    background: rgba(255, 255, 255, 0.95);
+  }
+}
+
+.persona-pill-peek--visible {
+  opacity: 1;
+  pointer-events: auto;
+  transform: translateY(0);
+}
+
+.persona-pill-peek:hover {
+  background: rgba(255, 255, 255, 0.92);
+}
+
+.persona-pill-peek__icon,
+.persona-pill-peek__caret {
+  display: inline-flex;
+  flex-shrink: 0;
+  color: currentColor;
+}
+
+.persona-pill-peek__text {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+/* Per-char/per-word animated spans render as inline-block, which interacts
+ * with the peek's nowrap+ellipsis chrome. Setting `vertical-align: baseline`
+ * keeps the spans on the same baseline as surrounding text so reveal
+ * transforms (translateY, scale) don't bump the line height. */
+[data-persona-root] .persona-pill-peek__text .persona-stream-char,
+[data-persona-root] .persona-pill-peek__text .persona-stream-word {
+  vertical-align: baseline;
+}
+
+/* Peek-scaled skeleton: the bubble-sized 260×10 bar would dwarf a 14px-line
+ * pill. Inside the peek we shrink to a single, full-flex bar that hints at
+ * "more is coming" without dominating the chrome. Used when
+ * `streamAnimation.placeholder === "skeleton"` AND content trims to empty
+ * (e.g. `buffer: "line"` between line completions). */
+[data-persona-root] .persona-pill-peek__text .persona-pill-peek__skeleton {
+  display: inline-flex;
+  vertical-align: middle;
+  width: 100%;
+  max-width: 200px;
+  padding: 0;
+}
+[data-persona-root] .persona-pill-peek__text .persona-pill-peek__skeleton .persona-stream-skeleton-line {
+  height: 8px;
+}
+
+/* --- Expanded states: geometry safety nets ----------------------------- */
+
+/* `fullscreen`: ui.ts clears all inline geometry so this rule lights up. */
+.persona-widget-wrapper[data-persona-composer-bar][data-state="expanded"][data-expanded-size="fullscreen"] {
+  inset: 0;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  transform: none;
+  max-width: none;
+  width: 100%;
+  height: 100%;
+  border-radius: 0;
+}
+
+/* Fullscreen "panel behind pill": the chat body fills the full viewport
+ * (including the area behind the fixed pill) so messages scroll under the
+ * pill. The body itself drops its bottom padding so its background extends
+ * to the viewport edge; reachability for the last bubble comes from
+ * padding-bottom on the messages wrapper (body's last child) — that
+ * pushes the final message above the pill area rather than hiding it
+ * behind. */
+.persona-widget-wrapper[data-persona-composer-bar][data-expanded-size="fullscreen"] .persona-widget-body {
+  padding-bottom: 0;
+}
+.persona-widget-wrapper[data-persona-composer-bar][data-expanded-size="fullscreen"] .persona-widget-body > :last-child {
+  padding-bottom: calc(var(--persona-pill-bottom, 16px) + var(--persona-pill-area-height, 80px) + 16px);
+}
+
+/* `modal` and `anchored` get their geometry inline from ui.ts; nothing
+ * needed in CSS for those. */
+
+/* --- Expand fade-in cascade -------------------------------------------- */
+/*
+ * Two staggered fades that mask the visual desync between the wrapper's
+ * fast-traveling outer edges and the inner content (which is constrained
+ * by `contentMaxWidth` + `margin: auto` and therefore moves at a fraction
+ * of the wrapper's growth rate). Without this, the user perceives an
+ * empty "gap" inside the wrapper as it morphs to fullscreen.
+ *
+ * - Chrome (container background, border, shadow, and the absolute close +
+ *   clear buttons) fades in across the same 220ms as the geometry transition,
+ *   so the box appears to materialize as it grows rather than snap into
+ *   existence at frame 0.
+ * - Body content (intro card, messages, composer overlay) fades in AFTER
+ *   the geometry has settled — `animation-delay: 220ms` plus
+ *   `animation-fill-mode: both` keeps it at opacity 0 during the morph.
+ *
+ * Because `[data-state="collapsed"] .persona-widget-container { display:
+ * none }`, the container leaves and re-enters the rendering tree on each
+ * expand, which retriggers the keyframe animation cleanly without
+ * needing a JS class toggle.
+ */
+@keyframes persona-composer-bar-fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.persona-widget-wrapper[data-persona-composer-bar][data-state="expanded"] .persona-widget-container {
+  animation: persona-composer-bar-fade-in 220ms ease both;
+}
+
+.persona-widget-wrapper[data-persona-composer-bar][data-state="expanded"] .persona-widget-body {
+  animation: persona-composer-bar-fade-in 200ms ease 220ms both;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .persona-widget-wrapper[data-persona-composer-bar] {
+    transition: none !important;
+  }
+  .persona-widget-wrapper[data-persona-composer-bar][data-state="expanded"] .persona-widget-container,
+  .persona-widget-wrapper[data-persona-composer-bar][data-state="expanded"] .persona-widget-body {
+    animation: none !important;
+  }
+}

package/src/types.ts

@@ -1150,6 +1150,103 @@ export type AgentWidgetDockConfig = {
   reveal?: "resize" | "overlay" | "push" | "emerge";
 };
 
+/**
+ * Layout configuration for `mountMode: "composer-bar"`. Controls how the
+ * collapsed pill is positioned and sized, and how the panel expands when
+ * the user opens it.
+ */
+export type AgentWidgetComposerBarConfig = {
+  /**
+   * Max-width of the collapsed pill composer at the bottom of the viewport.
+   * @default "720px"
+   */
+  collapsedMaxWidth?: string;
+  /**
+   * Bottom offset (CSS length) from the viewport edge in the collapsed state.
+   * @default "16px"
+   */
+  bottomOffset?: string;
+  /**
+   * Auto-expand the panel when the user submits a message while the composer
+   * is collapsed. When false, the message still sends but the panel remains
+   * collapsed (the host can drive expansion programmatically).
+   * @default true
+   */
+  expandOnSubmit?: boolean;
+  /**
+   * Size of the expanded chat panel.
+   * - `"anchored"` (default): the pill stays at the bottom of the viewport
+   *   and the chat history grows upward into a centered column above it.
+   *   Width is driven by `expandedMaxWidth`; the panel's top edge sits at
+   *   `expandedTopOffset` from the viewport top.
+   * - `"fullscreen"`: covers the entire viewport (mobile-app style). Inner
+   *   content is centered horizontally via `contentMaxWidth`.
+   * - `"modal"`: centered sheet with margins; size driven by
+   *   `modalMaxWidth` / `modalMaxHeight`.
+   * @default "anchored"
+   */
+  expandedSize?: "anchored" | "fullscreen" | "modal";
+  /**
+   * When `expandedSize === "anchored"`, max-width of the expanded panel
+   * column. Capped at `calc(100vw - 32px)` on narrow viewports.
+   * @default "880px"
+   */
+  expandedMaxWidth?: string;
+  /**
+   * When `expandedSize === "anchored"`, distance from the viewport top to
+   * the panel's top edge. Accepts any CSS length.
+   * @default "5vh"
+   */
+  expandedTopOffset?: string;
+  /**
+   * Max-width applied to messages, composer form, suggestions, and
+   * attachment previews so they center horizontally inside the expanded
+   * panel. Falls back to `layout.contentMaxWidth` when set; otherwise
+   * defaults to this value.
+   * @default "720px"
+   */
+  contentMaxWidth?: string;
+  /**
+   * When `expandedSize === "modal"`, max-width of the expanded sheet.
+   * @default "880px"
+   */
+  modalMaxWidth?: string;
+  /**
+   * When `expandedSize === "modal"`, max-height of the expanded sheet.
+   * @default "min(90vh, 800px)"
+   */
+  modalMaxHeight?: string;
+  /**
+   * Configuration for the "peek" banner — the chrome-less row above the
+   * collapsed pill that previews the most recent assistant message.
+   */
+  peek?: AgentWidgetComposerBarPeekConfig;
+};
+
+/**
+ * Configuration for the composer-bar peek banner. Reuses the same
+ * `streamAnimation` shape developers already configure for the main message
+ * stream, so the surface for animations is identical across both contexts.
+ *
+ * Resolution order:
+ * - If `peek.streamAnimation` is set, those values apply to the peek.
+ * - Otherwise the peek inherits from `features.streamAnimation`.
+ *
+ * Per-surface carve-outs:
+ * - `bubbleClass` from a plugin (used by `pop-bubble`) is ignored — the peek
+ *   has no bubble analog.
+ * - `containerClass`, `wrap` ("char" | "word"), `useCaret`, `placeholder`
+ *   ("skeleton"), `buffer` ("word" | "line"), `speed`, `duration`, and
+ *   custom plugins all apply unchanged.
+ */
+export type AgentWidgetComposerBarPeekConfig = {
+  /**
+   * Reveal animation for the peek's trailing-message preview. Same shape as
+   * `features.streamAnimation`. Omit to inherit from the main stream config.
+   */
+  streamAnimation?: AgentWidgetStreamAnimationFeature;
+};
+
 export type AgentWidgetLauncherConfig = {
   enabled?: boolean;
   title?: string;
@@ -1164,14 +1261,22 @@ export type AgentWidgetLauncherConfig = {
    * Controls how the launcher panel is mounted relative to the host page.
    * - "floating": default floating launcher / panel behavior
    * - "docked": wraps the target container and renders as a sibling dock
+   * - "composer-bar": persistent rounded-pill composer fixed to the bottom of
+   *   the viewport that morphs into a fullscreen (or modal) chat panel on
+   *   submit and minimizes back to the pill on close.
    *
    * @default "floating"
    */
-  mountMode?: "floating" | "docked";
+  mountMode?: "floating" | "docked" | "composer-bar";
   /**
    * Layout configuration for docked mode.
    */
   dock?: AgentWidgetDockConfig;
+  /**
+   * Layout configuration for composer-bar mode.
+   * Only applies when `mountMode === "composer-bar"`.
+   */
+  composerBar?: AgentWidgetComposerBarConfig;
   autoExpand?: boolean;
   width?: string;
   /**
@@ -3357,6 +3462,13 @@ export type AgentWidgetConfig = {
    * When `true`, uses default settings with sessionStorage.
    * When an object, allows customizing storage type, key prefix, and what to persist.
    *
+   * Setting this to `false` is the explicit kill-switch: it disables UI-state
+   * persistence **and** message-history persistence. When `false`, any
+   * `storageAdapter` you configure is ignored and the default localStorage
+   * adapter is not created — no chat history is read or written. Pass `true`
+   * (or omit) to keep the default behavior of persisting messages via the
+   * configured `storageAdapter` (or the built-in localStorage adapter).
+   *
    * @example
    * ```typescript
    * // Simple usage - persist open state in sessionStorage
@@ -3379,6 +3491,14 @@ export type AgentWidgetConfig = {
    *   }
    * }
    * ```
+   *
+   * @example
+   * ```typescript
+   * // Ephemeral widget — no message history written anywhere
+   * config: {
+   *   persistState: false
+   * }
+   * ```
    */
   persistState?: boolean | AgentWidgetPersistStateConfig;