vanilla-agent 1.29.0 → 1.30.0

package/dist/widget.css

@@ -1240,8 +1240,12 @@
   margin-top: 0.5rem;
   padding-top: 0.5rem;
   border-top: 1px solid var(--cw-divider, #f1f5f9);
-  /* Fade in when first shown (for "always" visibility) */
-  animation: tvw-message-actions-fade-in 0.3s ease-out;
+}
+
+/* Fade in animation only for "always" visibility mode (not hover) */
+/* forwards ensures final state is kept, idiomorph preserves element so animation only plays once */
+.tvw-message-actions:not(.tvw-message-actions-hover) {
+  animation: tvw-message-actions-fade-in 0.3s ease-out forwards;
 }
 
 /* Action bar alignment */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanilla-agent",
-  "version": "1.29.0",
+  "version": "1.30.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",
@@ -23,6 +23,7 @@
     "src"
   ],
   "dependencies": {
+    "idiomorph": "^0.7.4",
     "lucide": "^0.552.0",
     "marked": "^12.0.2",
     "partial-json": "^0.1.7",

package/src/@types/idiomorph.d.ts

@@ -0,0 +1,37 @@
+declare module "idiomorph" {
+  export interface IdiomorphCallbacks {
+    beforeNodeAdded?: (node: Node) => boolean | void;
+    afterNodeAdded?: (node: Node) => void;
+    beforeNodeMorphed?: (oldNode: Node, newNode: Node) => boolean | void;
+    afterNodeMorphed?: (oldNode: Node, newNode: Node) => void;
+    beforeNodeRemoved?: (node: Node) => boolean | void;
+    afterNodeRemoved?: (node: Node) => void;
+    beforeAttributeUpdated?: (
+      attributeName: string,
+      node: Node,
+      mutationType: "update" | "remove"
+    ) => boolean | void;
+  }
+
+  export interface IdiomorphOptions {
+    morphStyle?: "outerHTML" | "innerHTML";
+    ignoreActive?: boolean;
+    ignoreActiveValue?: boolean;
+    restoreFocus?: boolean;
+    callbacks?: IdiomorphCallbacks;
+    head?: {
+      style?: "merge" | "append" | "morph" | "none";
+    };
+  }
+
+  export interface IdiomorphStatic {
+    morph(
+      oldNode: Element | Document,
+      newContent: Element | Node | string,
+      options?: IdiomorphOptions
+    ): void;
+    defaults: IdiomorphOptions;
+  }
+
+  export const Idiomorph: IdiomorphStatic;
+}

package/src/components/message-bubble.ts

@@ -246,6 +246,9 @@ export const createMessageActions = (
       visibility === "hover" ? "tvw-message-actions-hover" : ""
     }`
   );
+  // Set id for idiomorph matching (prevents recreation on morph)
+  container.id = `actions-${message.id}`;
+  container.setAttribute("data-actions-for", message.id);
 
   // Track vote state for this message
   let currentVote: "upvote" | "downvote" | null = null;
@@ -414,6 +417,9 @@ export const createStandardBubble = (
   // Create the bubble element
   const classes = getBubbleClasses(message.role, layout);
   const bubble = createElement("div", classes.join(" "));
+  // Set id for idiomorph matching
+  bubble.id = `bubble-${message.id}`;
+  bubble.setAttribute("data-message-id", message.id);
 
   // Add message content
   const contentDiv = document.createElement("div");

package/src/components/reasoning-bubble.ts

@@ -26,6 +26,9 @@ export const createReasoningBubble = (message: AgentWidgetMessage): HTMLElement
       "tvw-py-0"
     ].join(" ")
   );
+  // Set id for idiomorph matching
+  bubble.id = `bubble-${message.id}`;
+  bubble.setAttribute("data-message-id", message.id);
 
   if (!reasoning) {
     return bubble;

package/src/components/tool-bubble.ts

@@ -28,6 +28,9 @@ export const createToolBubble = (message: AgentWidgetMessage, config?: AgentWidg
       "tvw-py-0"
     ].join(" ")
   );
+  // Set id for idiomorph matching
+  bubble.id = `bubble-${message.id}`;
+  bubble.setAttribute("data-message-id", message.id);
 
   // Apply bubble-level styles
   if (toolCallConfig.backgroundColor) {

package/src/styles/widget.css

@@ -1240,8 +1240,12 @@
   margin-top: 0.5rem;
   padding-top: 0.5rem;
   border-top: 1px solid var(--cw-divider, #f1f5f9);
-  /* Fade in when first shown (for "always" visibility) */
-  animation: tvw-message-actions-fade-in 0.3s ease-out;
+}
+
+/* Fade in animation only for "always" visibility mode (not hover) */
+/* forwards ensures final state is kept, idiomorph preserves element so animation only plays once */
+.tvw-message-actions:not(.tvw-message-actions-hover) {
+  animation: tvw-message-actions-fade-in 0.3s ease-out forwards;
 }
 
 /* Action bar alignment */

package/src/ui.ts

@@ -17,9 +17,11 @@ import {
 import { applyThemeVariables, createThemeObserver } from "./utils/theme";
 import { renderLucideIcon } from "./utils/icons";
 import { createElement } from "./utils/dom";
+import { morphMessages } from "./utils/morph";
 import { statusCopy } from "./utils/constants";
 import { createLauncherButton } from "./components/launcher";
 import { createWrapper, buildPanel, buildHeader, buildComposer, attachHeaderToContainer } from "./components/panel";
+import { buildHeaderWithLayout } from "./components/header-layouts";
 import { positionMap } from "./utils/positioning";
 import type { HeaderElements, ComposerElements } from "./components/panel";
 import { MessageTransform, MessageActionCallbacks } from "./components/message-bubble";
@@ -235,6 +237,7 @@ export const createAgentExperience = (
   let autoExpand = config.launcher?.autoExpand ?? false;
   let prevAutoExpand = autoExpand;
   let prevLauncherEnabled = launcherEnabled;
+  let prevHeaderLayout = config.layout?.header?.layout;
   let open = launcherEnabled ? autoExpand : true;
   let postprocess = buildPostprocessor(config, actionManager);
   let showReasoning = config.features?.showReasoning ?? true;
@@ -904,8 +907,8 @@ export const createAgentExperience = (
     messages: AgentWidgetMessage[],
     transform: MessageTransform
   ) => {
-    container.innerHTML = "";
-    const fragment = document.createDocumentFragment();
+    // Build new content in a temporary container for morphing
+    const tempContainer = document.createElement("div");
 
     messages.forEach((message) => {
       let bubble: HTMLElement | null = null;
@@ -976,8 +979,8 @@ export const createAgentExperience = (
             });
             if (componentBubble) {
               // Wrap component in standard bubble styling
-              const wrapper = document.createElement("div");
-              wrapper.className = [
+              const componentWrapper = document.createElement("div");
+              componentWrapper.className = [
                 "vanilla-message-bubble",
                 "tvw-max-w-[85%]",
                 "tvw-rounded-2xl",
@@ -986,7 +989,9 @@ export const createAgentExperience = (
                 "tvw-border-cw-message-border",
                 "tvw-p-4"
               ].join(" ");
-              wrapper.setAttribute("data-message-id", message.id);
+              // Set id for idiomorph matching
+              componentWrapper.id = `bubble-${message.id}`;
+              componentWrapper.setAttribute("data-message-id", message.id);
 
               // Add text content above component if present (combined text+component response)
               if (message.content && message.content.trim()) {
@@ -998,11 +1003,11 @@ export const createAgentExperience = (
                   streaming: Boolean(message.streaming),
                   raw: message.rawContent
                 });
-                wrapper.appendChild(textDiv);
+                componentWrapper.appendChild(textDiv);
               }
 
-              wrapper.appendChild(componentBubble);
-              bubble = wrapper;
+              componentWrapper.appendChild(componentBubble);
+              bubble = componentWrapper;
             }
           }
         }
@@ -1048,11 +1053,14 @@ export const createAgentExperience = (
 
       const wrapper = document.createElement("div");
       wrapper.className = "tvw-flex";
+      // Set id for idiomorph matching
+      wrapper.id = `wrapper-${message.id}`;
+      wrapper.setAttribute("data-wrapper-id", message.id);
       if (message.role === "user") {
         wrapper.classList.add("tvw-justify-end");
       }
       wrapper.appendChild(bubble);
-      fragment.appendChild(wrapper);
+      tempContainer.appendChild(wrapper);
     });
 
     // Add standalone typing indicator only if streaming but no assistant message is streaming yet
@@ -1085,16 +1093,21 @@ export const createAgentExperience = (
         "tvw-px-5",
         "tvw-py-3"
       ].join(" ");
+      typingBubble.setAttribute("data-typing-indicator", "true");
 
       typingBubble.appendChild(typingIndicator);
 
       const typingWrapper = document.createElement("div");
       typingWrapper.className = "tvw-flex";
+      // Set id for idiomorph matching
+      typingWrapper.id = "wrapper-typing-indicator";
+      typingWrapper.setAttribute("data-wrapper-id", "typing-indicator");
       typingWrapper.appendChild(typingBubble);
-      fragment.appendChild(typingWrapper);
+      tempContainer.appendChild(typingWrapper);
     }
 
-    container.appendChild(fragment);
+    // Use idiomorph to morph the container contents
+    morphMessages(container, tempContainer);
     // Defer scroll to next frame for smoother animation and to prevent jolt
     // This allows the browser to update layout (e.g., typing indicator removal) before scrolling
     // Use double RAF to ensure layout has fully settled before starting scroll animation
@@ -1902,6 +1915,66 @@ export const createAgentExperience = (
         headerSubtitle.textContent = config.launcher.subtitle;
       }
 
+      // Update header layout if it changed
+      const headerLayoutConfig = config.layout?.header;
+      const headerLayoutChanged = headerLayoutConfig?.layout !== prevHeaderLayout;
+
+      if (headerLayoutChanged && header) {
+        // Rebuild header with new layout
+        const newHeaderElements = headerLayoutConfig
+          ? buildHeaderWithLayout(config, headerLayoutConfig, {
+              showClose: launcherEnabled,
+              onClose: () => setOpenState(false, "user")
+            })
+          : buildHeader({
+              config,
+              showClose: launcherEnabled,
+              onClose: () => setOpenState(false, "user")
+            });
+
+        // Replace the old header with the new one
+        header.replaceWith(newHeaderElements.header);
+
+        // Update references
+        header = newHeaderElements.header;
+        iconHolder = newHeaderElements.iconHolder;
+        headerTitle = newHeaderElements.headerTitle;
+        headerSubtitle = newHeaderElements.headerSubtitle;
+        closeButton = newHeaderElements.closeButton;
+
+        prevHeaderLayout = headerLayoutConfig?.layout;
+      } else if (headerLayoutConfig) {
+        // Apply visibility settings without rebuilding
+        if (iconHolder) {
+          iconHolder.style.display = headerLayoutConfig.showIcon === false ? "none" : "";
+        }
+        if (headerTitle) {
+          headerTitle.style.display = headerLayoutConfig.showTitle === false ? "none" : "";
+        }
+        if (headerSubtitle) {
+          headerSubtitle.style.display = headerLayoutConfig.showSubtitle === false ? "none" : "";
+        }
+        if (closeButton) {
+          closeButton.style.display = headerLayoutConfig.showCloseButton === false ? "none" : "";
+        }
+        if (panelElements.clearChatButtonWrapper) {
+          // showClearChat explicitly controls visibility when set
+          const showClearChat = headerLayoutConfig.showClearChat;
+          if (showClearChat !== undefined) {
+            panelElements.clearChatButtonWrapper.style.display = showClearChat ? "" : "none";
+            // When clear chat is hidden, close button needs ml-auto to stay right-aligned
+            const { closeButtonWrapper } = panelElements;
+            if (closeButtonWrapper && !closeButtonWrapper.classList.contains("tvw-absolute")) {
+              if (showClearChat) {
+                closeButtonWrapper.classList.remove("tvw-ml-auto");
+              } else {
+                closeButtonWrapper.classList.add("tvw-ml-auto");
+              }
+            }
+          }
+        }
+      }
+
       // Only update open state if launcher enabled state changed or autoExpand value changed
       const launcherEnabledChanged = launcherEnabled !== prevLauncherEnabled;
       const autoExpandChanged = autoExpand !== prevAutoExpand;
@@ -1937,20 +2010,23 @@ export const createAgentExperience = (
       // Update panel icon sizes
       const launcher = config.launcher ?? {};
       const headerIconHidden = launcher.headerIconHidden ?? false;
+      const layoutShowIcon = config.layout?.header?.showIcon;
+      // Hide icon if either headerIconHidden is true OR layout.header.showIcon is false
+      const shouldHideIcon = headerIconHidden || layoutShowIcon === false;
       const headerIconName = launcher.headerIconName;
       const headerIconSize = launcher.headerIconSize ?? "48px";
-      
+
       if (iconHolder) {
-        const header = container.querySelector(".tvw-border-b-cw-divider");
-        const headerCopy = header?.querySelector(".tvw-flex-col");
-        
+        const headerEl = container.querySelector(".tvw-border-b-cw-divider");
+        const headerCopy = headerEl?.querySelector(".tvw-flex-col");
+
         // Handle hide/show
-        if (headerIconHidden) {
+        if (shouldHideIcon) {
           // Hide iconHolder
           iconHolder.style.display = "none";
           // Ensure headerCopy is still in header
-          if (header && headerCopy && !header.contains(headerCopy)) {
-            header.insertBefore(headerCopy, header.firstChild);
+          if (headerEl && headerCopy && !headerEl.contains(headerCopy)) {
+            headerEl.insertBefore(headerCopy, headerEl.firstChild);
           }
         } else {
           // Show iconHolder
@@ -1959,13 +2035,13 @@ export const createAgentExperience = (
           iconHolder.style.width = headerIconSize;
           
           // Ensure iconHolder is before headerCopy in header
-          if (header && headerCopy) {
-            if (!header.contains(iconHolder)) {
-              header.insertBefore(iconHolder, headerCopy);
+          if (headerEl && headerCopy) {
+            if (!headerEl.contains(iconHolder)) {
+              headerEl.insertBefore(iconHolder, headerCopy);
             } else if (iconHolder.nextSibling !== headerCopy) {
               // Reorder if needed
               iconHolder.remove();
-              header.insertBefore(iconHolder, headerCopy);
+              headerEl.insertBefore(iconHolder, headerCopy);
             }
           }
           
@@ -2015,7 +2091,26 @@ export const createAgentExperience = (
           }
         }
       }
+
+      // Handle title/subtitle visibility from layout config
+      const layoutShowTitle = config.layout?.header?.showTitle;
+      const layoutShowSubtitle = config.layout?.header?.showSubtitle;
+      if (headerTitle) {
+        headerTitle.style.display = layoutShowTitle === false ? "none" : "";
+      }
+      if (headerSubtitle) {
+        headerSubtitle.style.display = layoutShowSubtitle === false ? "none" : "";
+      }
+
       if (closeButton) {
+        // Handle close button visibility from layout config
+        const layoutShowCloseButton = config.layout?.header?.showCloseButton;
+        if (layoutShowCloseButton === false) {
+          closeButton.style.display = "none";
+        } else {
+          closeButton.style.display = "";
+        }
+
         const closeButtonSize = launcher.closeButtonSize ?? "32px";
         const closeButtonPlacement = launcher.closeButtonPlacement ?? "inline";
         closeButton.style.height = closeButtonSize;
@@ -2189,17 +2284,33 @@ export const createAgentExperience = (
       if (clearChatButton) {
         const clearChatConfig = launcher.clearChat ?? {};
         const clearChatEnabled = clearChatConfig.enabled ?? true;
+        const layoutShowClearChat = config.layout?.header?.showClearChat;
+        // layout.header.showClearChat takes precedence if explicitly set
+        // Otherwise fall back to launcher.clearChat.enabled
+        const shouldShowClearChat = layoutShowClearChat !== undefined
+          ? layoutShowClearChat
+          : clearChatEnabled;
         const clearChatPlacement = clearChatConfig.placement ?? "inline";
 
-        // Show/hide button based on enabled state
+        // Show/hide button based on layout config (primary) or launcher config (fallback)
         if (clearChatButtonWrapper) {
-          clearChatButtonWrapper.style.display = clearChatEnabled ? "" : "none";
+          clearChatButtonWrapper.style.display = shouldShowClearChat ? "" : "none";
+
+          // When clear chat is hidden, close button needs ml-auto to stay right-aligned
+          const { closeButtonWrapper } = panelElements;
+          if (closeButtonWrapper && !closeButtonWrapper.classList.contains("tvw-absolute")) {
+            if (shouldShowClearChat) {
+              closeButtonWrapper.classList.remove("tvw-ml-auto");
+            } else {
+              closeButtonWrapper.classList.add("tvw-ml-auto");
+            }
+          }
 
           // Update placement if changed
           const isTopRight = clearChatPlacement === "top-right";
           const currentlyTopRight = clearChatButtonWrapper.classList.contains("tvw-absolute");
 
-          if (isTopRight !== currentlyTopRight && clearChatEnabled) {
+          if (isTopRight !== currentlyTopRight && shouldShowClearChat) {
             clearChatButtonWrapper.remove();
 
             if (isTopRight) {
@@ -2239,7 +2350,7 @@ export const createAgentExperience = (
           }
         }
 
-        if (clearChatEnabled) {
+        if (shouldShowClearChat) {
           // Update size
           const clearChatSize = clearChatConfig.size ?? "32px";
           clearChatButton.style.height = clearChatSize;

package/src/utils/morph.ts

@@ -0,0 +1,36 @@
+import { Idiomorph } from "idiomorph";
+
+export type MorphOptions = {
+  preserveTypingAnimation?: boolean;
+};
+
+/**
+ * Morph a container's contents using idiomorph with chat-widget-specific
+ * preservation rules for typing indicators.
+ *
+ * Action buttons are matched by their `id` attribute (set to `actions-{messageId}`)
+ * so idiomorph updates them in place rather than recreating them.
+ */
+export const morphMessages = (
+  container: HTMLElement,
+  newContent: HTMLElement,
+  options: MorphOptions = {}
+): void => {
+  const { preserveTypingAnimation = true } = options;
+
+  Idiomorph.morph(container, newContent.innerHTML, {
+    morphStyle: "innerHTML",
+    callbacks: {
+      beforeNodeMorphed(oldNode: Node, newNode: Node): boolean | void {
+        if (!(oldNode instanceof HTMLElement)) return;
+
+        // Preserve typing indicator dots to maintain animation continuity
+        if (preserveTypingAnimation) {
+          if (oldNode.classList.contains("tvw-animate-typing")) {
+            return false;
+          }
+        }
+      },
+    },
+  });
+};