vanilla-agent 1.7.2 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanilla-agent",
-  "version": "1.7.2",
+  "version": "1.9.0",
   "description": "Themeable, plugable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/components/panel.ts

@@ -67,6 +67,8 @@ export interface PanelElements {
   clearChatButton: HTMLButtonElement | null;
   clearChatButtonWrapper: HTMLElement | null;
   iconHolder: HTMLElement;
+  headerTitle: HTMLElement;
+  headerSubtitle: HTMLElement;
 }
 
 export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelElements => {
@@ -789,7 +791,9 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     closeButtonWrapper,
     clearChatButton,
     clearChatButtonWrapper,
-    iconHolder
+    iconHolder,
+    headerTitle: title,
+    headerSubtitle: subtitle
   };
 };
 

package/src/components/suggestions.ts

@@ -1,16 +1,28 @@
 import { createElement } from "../utils/dom";
 import { AgentWidgetSession } from "../session";
-import { AgentWidgetMessage } from "../types";
+import { AgentWidgetMessage, AgentWidgetSuggestionChipsConfig } from "../types";
 
 export interface SuggestionButtons {
   buttons: HTMLButtonElement[];
-  render: (chips: string[] | undefined, session: AgentWidgetSession, textarea: HTMLTextAreaElement, messages?: AgentWidgetMessage[]) => void;
+  render: (
+    chips: string[] | undefined,
+    session: AgentWidgetSession,
+    textarea: HTMLTextAreaElement,
+    messages?: AgentWidgetMessage[],
+    config?: AgentWidgetSuggestionChipsConfig
+  ) => void;
 }
 
 export const createSuggestions = (container: HTMLElement): SuggestionButtons => {
   const suggestionButtons: HTMLButtonElement[] = [];
 
-  const render = (chips: string[] | undefined, session: AgentWidgetSession, textarea: HTMLTextAreaElement, messages?: AgentWidgetMessage[]) => {
+  const render = (
+    chips: string[] | undefined,
+    session: AgentWidgetSession,
+    textarea: HTMLTextAreaElement,
+    messages?: AgentWidgetMessage[],
+    chipsConfig?: AgentWidgetSuggestionChipsConfig
+  ) => {
     container.innerHTML = "";
     suggestionButtons.length = 0;
     if (!chips || !chips.length) return;
@@ -23,6 +35,20 @@ export const createSuggestions = (container: HTMLElement): SuggestionButtons =>
 
     const fragment = document.createDocumentFragment();
     const streaming = session ? session.isStreaming() : false;
+
+    // Get font family mapping function
+    const getFontFamilyValue = (family: "sans-serif" | "serif" | "mono"): string => {
+      switch (family) {
+        case "serif":
+          return 'Georgia, "Times New Roman", Times, serif';
+        case "mono":
+          return '"Courier New", Courier, "Lucida Console", Monaco, monospace';
+        case "sans-serif":
+        default:
+          return '-apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif';
+      }
+    };
+
     chips.forEach((chip) => {
       const btn = createElement(
         "button",
@@ -31,6 +57,25 @@ export const createSuggestions = (container: HTMLElement): SuggestionButtons =>
       btn.type = "button";
       btn.textContent = chip;
       btn.disabled = streaming;
+
+      // Apply typography settings
+      if (chipsConfig?.fontFamily) {
+        btn.style.fontFamily = getFontFamilyValue(chipsConfig.fontFamily);
+      }
+      if (chipsConfig?.fontWeight) {
+        btn.style.fontWeight = chipsConfig.fontWeight;
+      }
+
+      // Apply padding settings
+      if (chipsConfig?.paddingX) {
+        btn.style.paddingLeft = chipsConfig.paddingX;
+        btn.style.paddingRight = chipsConfig.paddingX;
+      }
+      if (chipsConfig?.paddingY) {
+        btn.style.paddingTop = chipsConfig.paddingY;
+        btn.style.paddingBottom = chipsConfig.paddingY;
+      }
+
       btn.addEventListener("click", () => {
         if (!session || session.isStreaming()) return;
         textarea.value = "";

package/src/defaults.ts

@@ -128,6 +128,12 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
     "Tell me about your features",
     "How does this work?",
   ],
+  suggestionChipsConfig: {
+    fontFamily: "sans-serif",
+    fontWeight: "500",
+    paddingX: "12px",
+    paddingY: "6px",
+  },
   debug: false,
 };
 
@@ -176,5 +182,9 @@ export function mergeWithDefaults(
       ...config.features,
     },
     suggestionChips: config.suggestionChips ?? DEFAULT_WIDGET_CONFIG.suggestionChips,
+    suggestionChipsConfig: {
+      ...DEFAULT_WIDGET_CONFIG.suggestionChipsConfig,
+      ...config.suggestionChipsConfig,
+    },
   };
 }

package/src/types.ts

@@ -51,6 +51,7 @@ export type AgentWidgetActionParser = (
 export type AgentWidgetActionHandlerResult = {
   handled?: boolean;
   displayText?: string;
+  persistMessage?: boolean; // If false, prevents message from being saved to history
 };
 
 export type AgentWidgetActionContext = {
@@ -92,11 +93,27 @@ export type AgentWidgetActionEventPayload = {
   message: AgentWidgetMessage;
 };
 
+export type AgentWidgetStateEvent = {
+  open: boolean;
+  source: "user" | "auto" | "api" | "system";
+  timestamp: number;
+};
+
+export type AgentWidgetStateSnapshot = {
+  open: boolean;
+  launcherEnabled: boolean;
+  voiceActive: boolean;
+  streaming: boolean;
+};
+
 export type AgentWidgetControllerEventMap = {
   "assistant:message": AgentWidgetMessage;
   "assistant:complete": AgentWidgetMessage;
   "voice:state": AgentWidgetVoiceStateEvent;
   "action:detected": AgentWidgetActionEventPayload;
+  "widget:opened": AgentWidgetStateEvent;
+  "widget:closed": AgentWidgetStateEvent;
+  "widget:state": AgentWidgetStateSnapshot;
 };
 
 export type AgentWidgetFeatureFlags = {
@@ -258,6 +275,13 @@ export type AgentWidgetToolCallConfig = {
   labelTextColor?: string;
 };
 
+export type AgentWidgetSuggestionChipsConfig = {
+  fontFamily?: "sans-serif" | "serif" | "mono";
+  fontWeight?: string;
+  paddingX?: string;
+  paddingY?: string;
+};
+
 /**
  * Interface for pluggable stream parsers that extract text from streaming responses.
  * Parsers handle incremental parsing to extract text values from structured formats (JSON, XML, etc.).
@@ -330,6 +354,7 @@ export type AgentWidgetConfig = {
   launcher?: AgentWidgetLauncherConfig;
   initialMessages?: AgentWidgetMessage[];
   suggestionChips?: string[];
+  suggestionChipsConfig?: AgentWidgetSuggestionChipsConfig;
   debug?: boolean;
   formEndpoint?: string;
   launcherWidth?: string;

package/src/ui.ts

@@ -7,7 +7,9 @@ import {
   AgentWidgetStorageAdapter,
   AgentWidgetStoredState,
   AgentWidgetControllerEventMap,
-  AgentWidgetVoiceStateEvent
+  AgentWidgetVoiceStateEvent,
+  AgentWidgetStateEvent,
+  AgentWidgetStateSnapshot
 } from "./types";
 import { applyThemeVariables } from "./utils/theme";
 import { renderLucideIcon } from "./utils/icons";
@@ -73,6 +75,10 @@ type Controller = {
     event: K,
     handler: (payload: AgentWidgetControllerEventMap[K]) => void
   ) => void;
+  // State query methods
+  isOpen: () => boolean;
+  isVoiceActive: () => boolean;
+  getState: () => AgentWidgetStateSnapshot;
 };
 
 const buildPostprocessor = (
@@ -84,14 +90,18 @@ const buildPostprocessor = (
     const rawPayload = context.message.rawContent ?? null;
 
     if (actionManager) {
-      const actionOverride = actionManager.process({
+      const actionResult = actionManager.process({
         text: nextText,
         raw: rawPayload ?? nextText,
         message: context.message,
         streaming: context.streaming
       });
-      if (actionOverride !== null) {
-        nextText = actionOverride;
+      if (actionResult !== null) {
+        nextText = actionResult.text;
+        // Mark message as non-persistable if persist is false
+        if (!actionResult.persist) {
+          (context.message as any).__skipPersist = true;
+        }
       }
     }
 
@@ -214,7 +224,9 @@ export const createAgentExperience = (
     introTitle,
     introSubtitle,
     closeButton,
-    iconHolder
+    iconHolder,
+    headerTitle,
+    headerSubtitle
   } = panelElements;
   
   // Use mutable references for mic button so we can update them dynamically
@@ -285,7 +297,9 @@ export const createAgentExperience = (
   };
 
   const getMessagesForPersistence = () =>
-    session ? stripStreamingFromMessages(session.getMessages()) : [];
+    session 
+      ? stripStreamingFromMessages(session.getMessages()).filter(msg => !(msg as any).__skipPersist)
+      : [];
 
   function persistState(messagesOverride?: AgentWidgetMessage[]) {
     if (!storageAdapter?.save || !session) return;
@@ -597,15 +611,39 @@ export const createAgentExperience = (
     }
   };
 
-  const setOpenState = (nextOpen: boolean) => {
+  const setOpenState = (nextOpen: boolean, source: "user" | "auto" | "api" | "system" = "user") => {
     if (!launcherEnabled) return;
     if (open === nextOpen) return;
+    
+    const prevOpen = open;
     open = nextOpen;
     updateOpenState();
+    
     if (open) {
       recalcPanelHeight();
       scheduleAutoScroll(true);
     }
+    
+    // Emit widget state events
+    const stateEvent: AgentWidgetStateEvent = {
+      open,
+      source,
+      timestamp: Date.now()
+    };
+    
+    if (open && !prevOpen) {
+      eventBus.emit("widget:opened", stateEvent);
+    } else if (!open && prevOpen) {
+      eventBus.emit("widget:closed", stateEvent);
+    }
+    
+    // Emit general state snapshot
+    eventBus.emit("widget:state", {
+      open,
+      launcherEnabled,
+      voiceActive: voiceState.active,
+      streaming: session.isStreaming()
+    });
   };
 
   const setComposerDisabled = (disabled: boolean) => {
@@ -664,7 +702,7 @@ export const createAgentExperience = (
           suggestionsManager.render([], session, textarea, messages);
         } else {
           // Show suggestions if no user message yet
-          suggestionsManager.render(config.suggestionChips, session, textarea, messages);
+          suggestionsManager.render(config.suggestionChips, session, textarea, messages, config.suggestionChipsConfig);
         }
       }
       scheduleAutoScroll(!isStreaming);
@@ -1059,7 +1097,7 @@ export const createAgentExperience = (
   destroyCallbacks.push(autoResumeUnsub);
 
   const toggleOpen = () => {
-    setOpenState(!open);
+    setOpenState(!open, "user");
   };
 
   let launcherButtonInstance = launcherEnabled
@@ -1070,7 +1108,7 @@ export const createAgentExperience = (
     mount.appendChild(launcherButtonInstance.element);
   }
   updateOpenState();
-  suggestionsManager.render(config.suggestionChips, session, textarea);
+  suggestionsManager.render(config.suggestionChips, session, textarea, undefined, config.suggestionChipsConfig);
   updateCopy();
   setComposerDisabled(session.isStreaming());
   scheduleAutoScroll(true);
@@ -1259,6 +1297,14 @@ export const createAgentExperience = (
         launcherButtonInstance.update(config);
       }
 
+      // Update panel header title and subtitle
+      if (headerTitle && config.launcher?.title !== undefined) {
+        headerTitle.textContent = config.launcher.title;
+      }
+      if (headerSubtitle && config.launcher?.subtitle !== undefined) {
+        headerSubtitle.textContent = config.launcher.subtitle;
+      }
+
       // Only update open state if launcher enabled state changed or autoExpand value changed
       const launcherEnabledChanged = launcherEnabled !== prevLauncherEnabled;
       const autoExpandChanged = autoExpand !== prevAutoExpand;
@@ -1271,11 +1317,11 @@ export const createAgentExperience = (
           updateOpenState();
         } else {
           // Launcher was just enabled - respect autoExpand setting
-          setOpenState(autoExpand);
+          setOpenState(autoExpand, "auto");
         }
       } else if (autoExpandChanged) {
         // autoExpand value changed - update state to match
-        setOpenState(autoExpand);
+        setOpenState(autoExpand, "auto");
       }
       // Otherwise, preserve current open state (user may have manually opened/closed)
 
@@ -1716,7 +1762,7 @@ export const createAgentExperience = (
         session.getMessages(),
         postprocess
       );
-      suggestionsManager.render(config.suggestionChips, session, textarea);
+      suggestionsManager.render(config.suggestionChips, session, textarea, undefined, config.suggestionChipsConfig);
       updateCopy();
       setComposerDisabled(session.isStreaming());
       
@@ -2013,15 +2059,15 @@ export const createAgentExperience = (
     },
     open() {
       if (!launcherEnabled) return;
-      setOpenState(true);
+      setOpenState(true, "api");
     },
     close() {
       if (!launcherEnabled) return;
-      setOpenState(false);
+      setOpenState(false, "api");
     },
     toggle() {
       if (!launcherEnabled) return;
-      setOpenState(!open);
+      setOpenState(!open, "api");
     },
     clearChat() {
       // Clear messages in session (this will trigger onMessagesChanged which re-renders)
@@ -2082,7 +2128,7 @@ export const createAgentExperience = (
       
       // Auto-open widget if closed and launcher is enabled
       if (!open && launcherEnabled) {
-        setOpenState(true);
+        setOpenState(true, "system");
       }
       
       textarea.value = message;
@@ -2098,7 +2144,7 @@ export const createAgentExperience = (
       
       // Auto-open widget if closed and launcher is enabled
       if (!open && launcherEnabled) {
-        setOpenState(true);
+        setOpenState(true, "system");
       }
       
       textarea.value = "";
@@ -2113,7 +2159,7 @@ export const createAgentExperience = (
       
       // Auto-open widget if closed and launcher is enabled
       if (!open && launcherEnabled) {
-        setOpenState(true);
+        setOpenState(true, "system");
       }
       
       voiceState.manuallyDeactivated = false;
@@ -2132,7 +2178,7 @@ export const createAgentExperience = (
     injectTestMessage(event: AgentWidgetEvent) {
       // Auto-open widget if closed and launcher is enabled
       if (!open && launcherEnabled) {
-        setOpenState(true);
+        setOpenState(true, "system");
       }
       session.injectTestEvent(event);
     },
@@ -2156,6 +2202,21 @@ export const createAgentExperience = (
     off(event, handler) {
       eventBus.off(event, handler);
     },
+    // State query methods
+    isOpen(): boolean {
+      return launcherEnabled && open;
+    },
+    isVoiceActive(): boolean {
+      return voiceState.active;
+    },
+    getState(): AgentWidgetStateSnapshot {
+      return {
+        open: launcherEnabled && open,
+        launcherEnabled,
+        voiceActive: voiceState.active,
+        streaming: session.isStreaming()
+      };
+    },
     destroy() {
       destroyCallbacks.forEach((cb) => cb());
       wrapper.remove();

package/src/utils/actions.ts

@@ -140,7 +140,7 @@ export const createActionManager = (options: ActionManagerOptions) => {
     }));
   };
 
-  const process = (context: ActionManagerProcessContext): string | null => {
+  const process = (context: ActionManagerProcessContext): { text: string; persist: boolean } | null => {
     if (
       context.streaming ||
       context.message.role !== "assistant" ||
@@ -202,12 +202,11 @@ export const createActionManager = (options: ActionManagerOptions) => {
 
         if (!handlerResult) continue;
 
-        if (handlerResult.displayText !== undefined && handlerResult.handled) {
-          return handlerResult.displayText;
-        }
-
         if (handlerResult.handled) {
-          return "";
+          // persistMessage defaults to true if not specified
+          const persist = handlerResult.persistMessage !== false;
+          const displayText = handlerResult.displayText !== undefined ? handlerResult.displayText : "";
+          return { text: displayText, persist };
         }
       } catch (error) {
         if (typeof console !== "undefined") {
@@ -217,7 +216,7 @@ export const createActionManager = (options: ActionManagerOptions) => {
       }
     }
 
-    return "";
+    return { text: "", persist: true };
   };
 
   return {