vanilla-agent 0.2.0 → 1.0.0

package/src/types.ts

@@ -1,11 +1,11 @@
-import type { ChatWidgetPlugin } from "./plugins/types";
+import type { AgentWidgetPlugin } from "./plugins/types";
 
-export type ChatWidgetFeatureFlags = {
+export type AgentWidgetFeatureFlags = {
   showReasoning?: boolean;
   showToolCalls?: boolean;
 };
 
-export type ChatWidgetTheme = {
+export type AgentWidgetTheme = {
   primary?: string;
   secondary?: string;
   surface?: string;
@@ -24,6 +24,9 @@ export type ChatWidgetTheme = {
   closeButtonColor?: string;
   closeButtonBackgroundColor?: string;
   closeButtonBorderColor?: string;
+  clearChatIconColor?: string;
+  clearChatBackgroundColor?: string;
+  clearChatBorderColor?: string;
   micIconColor?: string;
   micBackgroundColor?: string;
   micBorderColor?: string;
@@ -39,7 +42,7 @@ export type ChatWidgetTheme = {
   buttonRadius?: string;
 };
 
-export type ChatWidgetLauncherConfig = {
+export type AgentWidgetLauncherConfig = {
   enabled?: boolean;
   title?: string;
   subtitle?: string;
@@ -68,10 +71,17 @@ export type ChatWidgetLauncherConfig = {
   closeButtonBorderWidth?: string;
   closeButtonBorderColor?: string;
   closeButtonBorderRadius?: string;
+  closeButtonPaddingX?: string;
+  closeButtonPaddingY?: string;
   closeButtonPlacement?: "inline" | "top-right";
+  closeButtonIconName?: string;
+  closeButtonIconText?: string;
+  closeButtonTooltipText?: string;
+  closeButtonShowTooltip?: boolean;
+  clearChat?: AgentWidgetClearChatConfig;
 };
 
-export type ChatWidgetSendButtonConfig = {
+export type AgentWidgetSendButtonConfig = {
   borderWidth?: string;
   borderColor?: string;
   paddingX?: string;
@@ -86,7 +96,22 @@ export type ChatWidgetSendButtonConfig = {
   size?: string;
 };
 
-export type ChatWidgetStatusIndicatorConfig = {
+export type AgentWidgetClearChatConfig = {
+  enabled?: boolean;
+  iconName?: string;
+  iconColor?: string;
+  backgroundColor?: string;
+  borderWidth?: string;
+  borderColor?: string;
+  borderRadius?: string;
+  size?: string;
+  paddingX?: string;
+  paddingY?: string;
+  tooltipText?: string;
+  showTooltip?: boolean;
+};
+
+export type AgentWidgetStatusIndicatorConfig = {
   visible?: boolean;
   idleText?: string;
   connectingText?: string;
@@ -94,7 +119,7 @@ export type ChatWidgetStatusIndicatorConfig = {
   errorText?: string;
 };
 
-export type ChatWidgetVoiceRecognitionConfig = {
+export type AgentWidgetVoiceRecognitionConfig = {
   enabled?: boolean;
   pauseDuration?: number;
   iconName?: string;
@@ -113,7 +138,7 @@ export type ChatWidgetVoiceRecognitionConfig = {
   showRecordingIndicator?: boolean;
 };
 
-export type ChatWidgetConfig = {
+export type AgentWidgetConfig = {
   apiUrl?: string;
   flowId?: string;
   headers?: Record<string, string>;
@@ -123,28 +148,28 @@ export type ChatWidgetConfig = {
     inputPlaceholder?: string;
     sendButtonLabel?: string;
   };
-  theme?: ChatWidgetTheme;
-  features?: ChatWidgetFeatureFlags;
-  launcher?: ChatWidgetLauncherConfig;
-  initialMessages?: ChatWidgetMessage[];
+  theme?: AgentWidgetTheme;
+  features?: AgentWidgetFeatureFlags;
+  launcher?: AgentWidgetLauncherConfig;
+  initialMessages?: AgentWidgetMessage[];
   suggestionChips?: string[];
   debug?: boolean;
   formEndpoint?: string;
   launcherWidth?: string;
-  sendButton?: ChatWidgetSendButtonConfig;
-  statusIndicator?: ChatWidgetStatusIndicatorConfig;
-  voiceRecognition?: ChatWidgetVoiceRecognitionConfig;
+  sendButton?: AgentWidgetSendButtonConfig;
+  statusIndicator?: AgentWidgetStatusIndicatorConfig;
+  voiceRecognition?: AgentWidgetVoiceRecognitionConfig;
   postprocessMessage?: (context: {
     text: string;
-    message: ChatWidgetMessage;
+    message: AgentWidgetMessage;
     streaming: boolean;
   }) => string;
-  plugins?: ChatWidgetPlugin[];
+  plugins?: AgentWidgetPlugin[];
 };
 
-export type ChatWidgetMessageRole = "user" | "assistant" | "system";
+export type AgentWidgetMessageRole = "user" | "assistant" | "system";
 
-export type ChatWidgetReasoning = {
+export type AgentWidgetReasoning = {
   id: string;
   status: "pending" | "streaming" | "complete";
   chunks: string[];
@@ -153,7 +178,7 @@ export type ChatWidgetReasoning = {
   durationMs?: number;
 };
 
-export type ChatWidgetToolCall = {
+export type AgentWidgetToolCall = {
   id: string;
   name?: string;
   status: "pending" | "running" | "complete";
@@ -166,29 +191,29 @@ export type ChatWidgetToolCall = {
   durationMs?: number;
 };
 
-export type ChatWidgetMessageVariant = "assistant" | "reasoning" | "tool";
+export type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool";
 
-export type ChatWidgetMessage = {
+export type AgentWidgetMessage = {
   id: string;
-  role: ChatWidgetMessageRole;
+  role: AgentWidgetMessageRole;
   content: string;
   createdAt: string;
   streaming?: boolean;
-  variant?: ChatWidgetMessageVariant;
+  variant?: AgentWidgetMessageVariant;
   sequence?: number;
-  reasoning?: ChatWidgetReasoning;
-  toolCall?: ChatWidgetToolCall;
-  tools?: ChatWidgetToolCall[];
+  reasoning?: AgentWidgetReasoning;
+  toolCall?: AgentWidgetToolCall;
+  tools?: AgentWidgetToolCall[];
 };
 
-export type ChatWidgetEvent =
-  | { type: "message"; message: ChatWidgetMessage }
+export type AgentWidgetEvent =
+  | { type: "message"; message: AgentWidgetMessage }
   | { type: "status"; status: "connecting" | "connected" | "error" | "idle" }
   | { type: "error"; error: Error };
 
-export type ChatWidgetInitOptions = {
+export type AgentWidgetInitOptions = {
   target: string | HTMLElement;
-  config?: ChatWidgetConfig;
+  config?: AgentWidgetConfig;
   useShadowDom?: boolean;
   onReady?: () => void;
 };

package/src/ui.ts

@@ -1,6 +1,6 @@
 import { escapeHtml } from "./postprocessors";
-import { ChatWidgetSession, ChatWidgetSessionStatus } from "./session";
-import { ChatWidgetConfig, ChatWidgetMessage } from "./types";
+import { AgentWidgetSession, AgentWidgetSessionStatus } from "./session";
+import { AgentWidgetConfig, AgentWidgetMessage } from "./types";
 import { applyThemeVariables } from "./utils/theme";
 import { renderLucideIcon } from "./utils/icons";
 import { createElement } from "./utils/dom";
@@ -14,16 +14,18 @@ import { createToolBubble } from "./components/tool-bubble";
 import { createSuggestions } from "./components/suggestions";
 import { enhanceWithForms } from "./components/forms";
 import { pluginRegistry } from "./plugins/registry";
+import { mergeWithDefaults } from "./defaults";
 
 type Controller = {
-  update: (config: ChatWidgetConfig) => void;
+  update: (config: AgentWidgetConfig) => void;
   destroy: () => void;
   open: () => void;
   close: () => void;
   toggle: () => void;
+  clearChat: () => void;
 };
 
-const buildPostprocessor = (cfg?: ChatWidgetConfig): MessageTransform => {
+const buildPostprocessor = (cfg?: AgentWidgetConfig): MessageTransform => {
   if (cfg?.postprocessMessage) {
     return (context) =>
       cfg.postprocessMessage!({
@@ -35,16 +37,16 @@ const buildPostprocessor = (cfg?: ChatWidgetConfig): MessageTransform => {
   return ({ text }) => escapeHtml(text);
 };
 
-export const createChatExperience = (
+export const createAgentExperience = (
   mount: HTMLElement,
-  initialConfig?: ChatWidgetConfig
+  initialConfig?: AgentWidgetConfig
 ): Controller => {
   // Tailwind config uses important: "#vanilla-agent-root", so ensure mount has this ID
   if (!mount.id || mount.id !== "vanilla-agent-root") {
     mount.id = "vanilla-agent-root";
   }
 
-  let config = { ...initialConfig };
+  let config = mergeWithDefaults(initialConfig) as AgentWidgetConfig;
   applyThemeVariables(mount, config);
 
   // Get plugins for this instance
@@ -61,7 +63,7 @@ export const createChatExperience = (
   
   // Get status indicator config
   const statusConfig = config.statusIndicator ?? {};
-  const getStatusText = (status: ChatWidgetSessionStatus): string => {
+  const getStatusText = (status: AgentWidgetSessionStatus): string => {
     if (status === "idle") return statusConfig.idleText ?? statusCopy.idle;
     if (status === "connecting") return statusConfig.connectingText ?? statusCopy.connecting;
     if (status === "connected") return statusConfig.connectedText ?? statusCopy.connected;
@@ -97,7 +99,7 @@ export const createChatExperience = (
   const destroyCallbacks: Array<() => void> = [];
   const suggestionsManager = createSuggestions(suggestions);
   let closeHandler: (() => void) | null = null;
-  let session: ChatWidgetSession;
+  let session: AgentWidgetSession;
   let isStreaming = false;
   let shouldAutoScroll = true;
   let lastScrollTop = 0;
@@ -178,7 +180,7 @@ export const createChatExperience = (
   // Message rendering with plugin support
   const renderMessagesWithPlugins = (
     container: HTMLElement,
-    messages: ChatWidgetMessage[],
+    messages: AgentWidgetMessage[],
     transform: MessageTransform
   ) => {
     container.innerHTML = "";
@@ -259,9 +261,28 @@ export const createChatExperience = (
     // Add typing indicator if streaming and there's at least one user message
     if (isStreaming && messages.some((msg) => msg.role === "user")) {
       const typingIndicator = createTypingIndicator();
+      
+      // Create a bubble wrapper for the typing indicator (similar to assistant messages)
+      const typingBubble = document.createElement("div");
+      typingBubble.className = [
+        "tvw-max-w-[85%]",
+        "tvw-rounded-2xl",
+        "tvw-text-sm",
+        "tvw-leading-relaxed",
+        "tvw-shadow-sm",
+        "tvw-bg-cw-surface",
+        "tvw-border",
+        "tvw-border-cw-message-border",
+        "tvw-text-cw-primary",
+        "tvw-px-5",
+        "tvw-py-3"
+      ].join(" ");
+      
+      typingBubble.appendChild(typingIndicator);
+      
       const typingWrapper = document.createElement("div");
-      typingWrapper.className = "tvw-flex tvw-justify-end";
-      typingWrapper.appendChild(typingIndicator);
+      typingWrapper.className = "tvw-flex";
+      typingWrapper.appendChild(typingBubble);
       fragment.appendChild(typingWrapper);
     }
 
@@ -317,9 +338,14 @@ export const createChatExperience = (
     introSubtitle.textContent =
       config.copy?.welcomeSubtitle ??
       "Ask anything about your account or products.";
-    textarea.placeholder = config.copy?.inputPlaceholder ?? "Type your message…";
-    sendButton.textContent = config.copy?.sendButtonLabel ?? "Send";
-    
+    textarea.placeholder = config.copy?.inputPlaceholder ?? "How can I help...";
+
+    // Only update send button text if NOT using icon mode
+    const useIcon = config.sendButton?.useIcon ?? false;
+    if (!useIcon) {
+      sendButton.textContent = config.copy?.sendButtonLabel ?? "Send";
+    }
+
     // Update textarea font family and weight
     const fontFamily = config.theme?.inputFontFamily ?? "sans-serif";
     const fontWeight = config.theme?.inputFontWeight ?? "400";
@@ -340,7 +366,7 @@ export const createChatExperience = (
     textarea.style.fontWeight = fontWeight;
   };
 
-  session = new ChatWidgetSession(config, {
+  session = new AgentWidgetSession(config, {
     onMessagesChanged(messages) {
       renderMessagesWithPlugins(messagesWrapper, messages, postprocess);
       // Re-render suggestions to hide them after first user message
@@ -359,7 +385,7 @@ export const createChatExperience = (
     },
     onStatusChanged(status) {
       const currentStatusConfig = config.statusIndicator ?? {};
-      const getCurrentStatusText = (status: ChatWidgetSessionStatus): string => {
+      const getCurrentStatusText = (status: AgentWidgetSessionStatus): string => {
         if (status === "idle") return currentStatusConfig.idleText ?? statusCopy.idle;
         if (status === "connecting") return currentStatusConfig.connectingText ?? statusCopy.connecting;
         if (status === "connected") return currentStatusConfig.connectedText ?? statusCopy.connected;
@@ -568,7 +594,7 @@ export const createChatExperience = (
   };
 
   // Function to create mic button dynamically
-  const createMicButton = (voiceConfig: ChatWidgetConfig['voiceRecognition'], sendButtonConfig: ChatWidgetConfig['sendButton']): { micButton: HTMLButtonElement; micButtonWrapper: HTMLElement } | null => {
+  const createMicButton = (voiceConfig: AgentWidgetConfig['voiceRecognition'], sendButtonConfig: AgentWidgetConfig['sendButton']): { micButton: HTMLButtonElement; micButtonWrapper: HTMLElement } | null => {
     const hasSpeechRecognition = 
       typeof window !== 'undefined' && 
       (typeof (window as any).webkitSpeechRecognition !== 'undefined' || 
@@ -711,7 +737,7 @@ export const createChatExperience = (
       return;
     }
     const launcherWidth = config?.launcher?.width ?? config?.launcherWidth;
-    const width = launcherWidth ?? "min(360px, calc(100vw - 24px))";
+    const width = launcherWidth ?? "min(400px, calc(100vw - 24px))";
     panel.style.width = width;
     panel.style.maxWidth = width;
     const viewportHeight = window.innerHeight;
@@ -777,6 +803,25 @@ export const createChatExperience = (
 
   refreshCloseButton();
 
+  // Setup clear chat button click handler
+  const setupClearChatButton = () => {
+    const { clearChatButton } = panelElements;
+    if (!clearChatButton) return;
+
+    clearChatButton.addEventListener("click", () => {
+      // Clear messages in session (this will trigger onMessagesChanged which re-renders)
+      session.clearMessages();
+
+      // Dispatch custom event for external handlers (e.g., localStorage clearing in examples)
+      const clearEvent = new CustomEvent("vanilla-agent:clear-chat", {
+        detail: { timestamp: new Date().toISOString() }
+      });
+      window.dispatchEvent(clearEvent);
+    });
+  };
+
+  setupClearChatButton();
+
   composerForm.addEventListener("submit", handleSubmit);
   textarea.addEventListener("keydown", handleInputEnter);
 
@@ -796,7 +841,7 @@ export const createChatExperience = (
   }
 
   return {
-    update(nextConfig: ChatWidgetConfig) {
+    update(nextConfig: AgentWidgetConfig) {
       config = { ...config, ...nextConfig };
       applyThemeVariables(mount, config);
 
@@ -995,6 +1040,259 @@ export const createChatExperience = (
           closeButton.style.borderRadius = "";
           closeButton.classList.add("tvw-rounded-full");
         }
+
+        // Update padding
+        if (launcher.closeButtonPaddingX) {
+          closeButton.style.paddingLeft = launcher.closeButtonPaddingX;
+          closeButton.style.paddingRight = launcher.closeButtonPaddingX;
+        } else {
+          closeButton.style.paddingLeft = "";
+          closeButton.style.paddingRight = "";
+        }
+        if (launcher.closeButtonPaddingY) {
+          closeButton.style.paddingTop = launcher.closeButtonPaddingY;
+          closeButton.style.paddingBottom = launcher.closeButtonPaddingY;
+        } else {
+          closeButton.style.paddingTop = "";
+          closeButton.style.paddingBottom = "";
+        }
+
+        // Update icon
+        const closeButtonIconName = launcher.closeButtonIconName ?? "x";
+        const closeButtonIconText = launcher.closeButtonIconText ?? "×";
+
+        // Clear existing content and render new icon
+        closeButton.innerHTML = "";
+        const iconSvg = renderLucideIcon(closeButtonIconName, "20px", launcher.closeButtonColor || "", 2);
+        if (iconSvg) {
+          closeButton.appendChild(iconSvg);
+        } else {
+          closeButton.textContent = closeButtonIconText;
+        }
+
+        // Update tooltip
+        const { closeButtonWrapper } = panelElements;
+        const closeButtonTooltipText = launcher.closeButtonTooltipText ?? "Close chat";
+        const closeButtonShowTooltip = launcher.closeButtonShowTooltip ?? true;
+
+        closeButton.setAttribute("aria-label", closeButtonTooltipText);
+
+        if (closeButtonWrapper) {
+          // Clean up old tooltip event listeners if they exist
+          if ((closeButtonWrapper as any)._cleanupTooltip) {
+            (closeButtonWrapper as any)._cleanupTooltip();
+            delete (closeButtonWrapper as any)._cleanupTooltip;
+          }
+
+          // Set up new portaled tooltip with event listeners
+          if (closeButtonShowTooltip && closeButtonTooltipText) {
+            let portaledTooltip: HTMLElement | null = null;
+
+            const showTooltip = () => {
+              if (portaledTooltip || !closeButton) return; // Already showing or button doesn't exist
+
+              // Create tooltip element
+              portaledTooltip = createElement("div", "tvw-clear-chat-tooltip");
+              portaledTooltip.textContent = closeButtonTooltipText;
+
+              // Add arrow
+              const arrow = createElement("div");
+              arrow.className = "tvw-clear-chat-tooltip-arrow";
+              portaledTooltip.appendChild(arrow);
+
+              // Get button position
+              const buttonRect = closeButton.getBoundingClientRect();
+
+              // Position tooltip above button
+              portaledTooltip.style.position = "fixed";
+              portaledTooltip.style.left = `${buttonRect.left + buttonRect.width / 2}px`;
+              portaledTooltip.style.top = `${buttonRect.top - 8}px`;
+              portaledTooltip.style.transform = "translate(-50%, -100%)";
+
+              // Append to body
+              document.body.appendChild(portaledTooltip);
+            };
+
+            const hideTooltip = () => {
+              if (portaledTooltip && portaledTooltip.parentNode) {
+                portaledTooltip.parentNode.removeChild(portaledTooltip);
+                portaledTooltip = null;
+              }
+            };
+
+            // Add event listeners
+            closeButtonWrapper.addEventListener("mouseenter", showTooltip);
+            closeButtonWrapper.addEventListener("mouseleave", hideTooltip);
+            closeButton.addEventListener("focus", showTooltip);
+            closeButton.addEventListener("blur", hideTooltip);
+
+            // Store cleanup function on the wrapper for later use
+            (closeButtonWrapper as any)._cleanupTooltip = () => {
+              hideTooltip();
+              if (closeButtonWrapper) {
+                closeButtonWrapper.removeEventListener("mouseenter", showTooltip);
+                closeButtonWrapper.removeEventListener("mouseleave", hideTooltip);
+              }
+              if (closeButton) {
+                closeButton.removeEventListener("focus", showTooltip);
+                closeButton.removeEventListener("blur", hideTooltip);
+              }
+            };
+          }
+        }
+      }
+
+      // Update clear chat button styling from config
+      const { clearChatButton, clearChatButtonWrapper } = panelElements;
+      if (clearChatButton) {
+        const clearChatConfig = launcher.clearChat ?? {};
+        const clearChatEnabled = clearChatConfig.enabled ?? true;
+
+        // Show/hide button based on enabled state
+        if (clearChatButtonWrapper) {
+          clearChatButtonWrapper.style.display = clearChatEnabled ? "" : "none";
+        }
+
+        if (clearChatEnabled) {
+          // Update size
+          const clearChatSize = clearChatConfig.size ?? "32px";
+          clearChatButton.style.height = clearChatSize;
+          clearChatButton.style.width = clearChatSize;
+
+          // Update icon
+          const clearChatIconName = clearChatConfig.iconName ?? "refresh-cw";
+          const clearChatIconColor = clearChatConfig.iconColor ?? "";
+
+          // Clear existing icon and render new one
+          clearChatButton.innerHTML = "";
+          const iconSvg = renderLucideIcon(clearChatIconName, "20px", clearChatIconColor || "", 2);
+          if (iconSvg) {
+            clearChatButton.appendChild(iconSvg);
+          }
+
+          // Update icon color
+          if (clearChatIconColor) {
+            clearChatButton.style.color = clearChatIconColor;
+            clearChatButton.classList.remove("tvw-text-cw-muted");
+          } else {
+            clearChatButton.style.color = "";
+            clearChatButton.classList.add("tvw-text-cw-muted");
+          }
+
+          // Update background color
+          if (clearChatConfig.backgroundColor) {
+            clearChatButton.style.backgroundColor = clearChatConfig.backgroundColor;
+            clearChatButton.classList.remove("hover:tvw-bg-gray-100");
+          } else {
+            clearChatButton.style.backgroundColor = "";
+            clearChatButton.classList.add("hover:tvw-bg-gray-100");
+          }
+
+          // Update border
+          if (clearChatConfig.borderWidth || clearChatConfig.borderColor) {
+            const borderWidth = clearChatConfig.borderWidth || "0px";
+            const borderColor = clearChatConfig.borderColor || "transparent";
+            clearChatButton.style.border = `${borderWidth} solid ${borderColor}`;
+            clearChatButton.classList.remove("tvw-border-none");
+          } else {
+            clearChatButton.style.border = "";
+            clearChatButton.classList.add("tvw-border-none");
+          }
+
+          // Update border radius
+          if (clearChatConfig.borderRadius) {
+            clearChatButton.style.borderRadius = clearChatConfig.borderRadius;
+            clearChatButton.classList.remove("tvw-rounded-full");
+          } else {
+            clearChatButton.style.borderRadius = "";
+            clearChatButton.classList.add("tvw-rounded-full");
+          }
+
+          // Update padding
+          if (clearChatConfig.paddingX) {
+            clearChatButton.style.paddingLeft = clearChatConfig.paddingX;
+            clearChatButton.style.paddingRight = clearChatConfig.paddingX;
+          } else {
+            clearChatButton.style.paddingLeft = "";
+            clearChatButton.style.paddingRight = "";
+          }
+          if (clearChatConfig.paddingY) {
+            clearChatButton.style.paddingTop = clearChatConfig.paddingY;
+            clearChatButton.style.paddingBottom = clearChatConfig.paddingY;
+          } else {
+            clearChatButton.style.paddingTop = "";
+            clearChatButton.style.paddingBottom = "";
+          }
+
+          const clearChatTooltipText = clearChatConfig.tooltipText ?? "Clear chat";
+          const clearChatShowTooltip = clearChatConfig.showTooltip ?? true;
+
+          clearChatButton.setAttribute("aria-label", clearChatTooltipText);
+
+          if (clearChatButtonWrapper) {
+            // Clean up old tooltip event listeners if they exist
+            if ((clearChatButtonWrapper as any)._cleanupTooltip) {
+              (clearChatButtonWrapper as any)._cleanupTooltip();
+              delete (clearChatButtonWrapper as any)._cleanupTooltip;
+            }
+
+            // Set up new portaled tooltip with event listeners
+            if (clearChatShowTooltip && clearChatTooltipText) {
+              let portaledTooltip: HTMLElement | null = null;
+
+              const showTooltip = () => {
+                if (portaledTooltip || !clearChatButton) return; // Already showing or button doesn't exist
+
+                // Create tooltip element
+                portaledTooltip = createElement("div", "tvw-clear-chat-tooltip");
+                portaledTooltip.textContent = clearChatTooltipText;
+
+                // Add arrow
+                const arrow = createElement("div");
+                arrow.className = "tvw-clear-chat-tooltip-arrow";
+                portaledTooltip.appendChild(arrow);
+
+                // Get button position
+                const buttonRect = clearChatButton.getBoundingClientRect();
+
+                // Position tooltip above button
+                portaledTooltip.style.position = "fixed";
+                portaledTooltip.style.left = `${buttonRect.left + buttonRect.width / 2}px`;
+                portaledTooltip.style.top = `${buttonRect.top - 8}px`;
+                portaledTooltip.style.transform = "translate(-50%, -100%)";
+
+                // Append to body
+                document.body.appendChild(portaledTooltip);
+              };
+
+              const hideTooltip = () => {
+                if (portaledTooltip && portaledTooltip.parentNode) {
+                  portaledTooltip.parentNode.removeChild(portaledTooltip);
+                  portaledTooltip = null;
+                }
+              };
+
+              // Add event listeners
+              clearChatButtonWrapper.addEventListener("mouseenter", showTooltip);
+              clearChatButtonWrapper.addEventListener("mouseleave", hideTooltip);
+              clearChatButton.addEventListener("focus", showTooltip);
+              clearChatButton.addEventListener("blur", hideTooltip);
+
+              // Store cleanup function on the button for later use
+              (clearChatButtonWrapper as any)._cleanupTooltip = () => {
+                hideTooltip();
+                if (clearChatButtonWrapper) {
+                  clearChatButtonWrapper.removeEventListener("mouseenter", showTooltip);
+                  clearChatButtonWrapper.removeEventListener("mouseleave", hideTooltip);
+                }
+                if (clearChatButton) {
+                  clearChatButton.removeEventListener("focus", showTooltip);
+                  clearChatButton.removeEventListener("blur", hideTooltip);
+                }
+              };
+            }
+          }
+        }
       }
 
       postprocess = buildPostprocessor(config);
@@ -1289,7 +1587,7 @@ export const createChatExperience = (
       // Update status text if status is currently set
       if (session) {
         const currentStatus = session.getStatus();
-        const getCurrentStatusText = (status: ChatWidgetSessionStatus): string => {
+        const getCurrentStatusText = (status: AgentWidgetSessionStatus): string => {
           if (status === "idle") return statusIndicatorConfig.idleText ?? statusCopy.idle;
           if (status === "connecting") return statusIndicatorConfig.connectingText ?? statusCopy.connecting;
           if (status === "connected") return statusIndicatorConfig.connectedText ?? statusCopy.connected;
@@ -1311,6 +1609,16 @@ export const createChatExperience = (
       if (!launcherEnabled) return;
       setOpenState(!open);
     },
+    clearChat() {
+      // Clear messages in session (this will trigger onMessagesChanged which re-renders)
+      session.clearMessages();
+
+      // Dispatch custom event for external handlers (e.g., localStorage clearing in examples)
+      const clearEvent = new CustomEvent("vanilla-agent:clear-chat", {
+        detail: { timestamp: new Date().toISOString() }
+      });
+      window.dispatchEvent(clearEvent);
+    },
     destroy() {
       destroyCallbacks.forEach((cb) => cb());
       wrapper.remove();
@@ -1322,4 +1630,4 @@ export const createChatExperience = (
   };
 };
 
-export type ChatWidgetController = Controller;
+export type AgentWidgetController = Controller;

package/src/utils/constants.ts

@@ -1,6 +1,6 @@
-import { ChatWidgetSessionStatus } from "../session";
+import { AgentWidgetSessionStatus } from "../session";
 
-export const statusCopy: Record<ChatWidgetSessionStatus, string> = {
+export const statusCopy: Record<AgentWidgetSessionStatus, string> = {
   idle: "Online",
   connecting: "Connecting…",
   connected: "Streaming…",
@@ -9,3 +9,5 @@ export const statusCopy: Record<ChatWidgetSessionStatus, string> = {
 
 
 
+
+

package/src/utils/dom.ts

@@ -18,3 +18,5 @@ export const createFragment = (): DocumentFragment => {
 
 
 
+
+