vanilla-agent 1.28.0 → 1.30.0

package/dist/widget.css

@@ -86,7 +86,8 @@
   gap: 1.5rem;
 }
 
-:root {
+/* Widget CSS Variables - scoped to widget root to avoid polluting global namespace */
+#vanilla-agent-root {
   --cw-radius-sm: 0.75rem;
   --cw-radius-md: 1rem;
   --cw-radius-lg: 1.5rem;
@@ -119,19 +120,19 @@
   --cw-md-h6-margin: 0.5rem 0 0.25rem;
   --cw-md-h6-line-height: 1.5;
 
-  /* Markdown Table Variables (defaults - theme-aware values set on #vanilla-agent-root) */
+  /* Markdown Table Variables */
   --cw-md-table-border-color: #e5e7eb;
   --cw-md-table-header-bg: #f8fafc;
   --cw-md-table-header-weight: 600;
   --cw-md-table-cell-padding: 0.5rem 0.75rem;
   --cw-md-table-border-radius: 0.375rem;
 
-  /* Markdown Horizontal Rule Variables (defaults - theme-aware values set on #vanilla-agent-root) */
+  /* Markdown Horizontal Rule Variables */
   --cw-md-hr-color: #e5e7eb;
   --cw-md-hr-height: 1px;
   --cw-md-hr-margin: 1rem 0;
 
-  /* Markdown Blockquote Variables (defaults - theme-aware values set on #vanilla-agent-root) */
+  /* Markdown Blockquote Variables */
   --cw-md-blockquote-border-color: #3b82f6;
   --cw-md-blockquote-border-width: 3px;
   --cw-md-blockquote-padding: 0.5rem 1rem;
@@ -140,7 +141,7 @@
   --cw-md-blockquote-text-color: #6b7280;
   --cw-md-blockquote-font-style: italic;
 
-  /* Markdown Code Block Variables (defaults - theme-aware values set on #vanilla-agent-root) */
+  /* Markdown Code Block Variables */
   --cw-md-code-block-bg: #f3f4f6;
   --cw-md-code-block-border-color: #e5e7eb;
   --cw-md-code-block-text-color: inherit;
@@ -148,7 +149,7 @@
   --cw-md-code-block-border-radius: 0.375rem;
   --cw-md-code-block-font-size: 0.875rem;
 
-  /* Markdown Inline Code Variables (defaults - theme-aware values set on #vanilla-agent-root) */
+  /* Markdown Inline Code Variables */
   --cw-md-inline-code-bg: #f3f4f6;
   --cw-md-inline-code-padding: 0.125rem 0.375rem;
   --cw-md-inline-code-border-radius: 0.25rem;
@@ -677,7 +678,7 @@
 }
 
 /* Ensure textarea in composer form has no border on focus */
-textarea:focus {
+.tvw-widget-composer textarea:focus {
   border: none !important;
   outline: none !important;
   border-width: 0 !important;
@@ -687,11 +688,11 @@ textarea:focus {
 }
 
 /* Prevent form container from showing focus styles */
-form:focus-within {
+.tvw-widget-composer:focus-within {
   outline: none !important;
 }
 
-form:focus-within textarea {
+.tvw-widget-composer:focus-within textarea {
   border: none !important;
   outline: none !important;
 }
@@ -804,7 +805,7 @@ form:focus-within textarea {
 }
 
 /* Typing indicator animation */
-@keyframes typing {
+@keyframes tvw-typing {
   0%, 100% {
     opacity: 0.5;
     transform: translateY(0);
@@ -816,7 +817,7 @@ form:focus-within textarea {
 }
 
 .tvw-animate-typing {
-  animation: typing 1s infinite;
+  animation: tvw-typing 1s infinite;
 }
 
 .tvw-space-x-1 > * + * {
@@ -848,7 +849,7 @@ form:focus-within textarea {
 }
 
 /* Voice recognition recording animation */
-@keyframes voice-recording-pulse {
+@keyframes tvw-voice-recording-pulse {
   0%, 100% {
     opacity: 1;
     transform: scale(1);
@@ -860,11 +861,11 @@ form:focus-within textarea {
 }
 
 .tvw-voice-recording {
-  animation: voice-recording-pulse 1.5s ease-in-out infinite;
+  animation: tvw-voice-recording-pulse 1.5s ease-in-out infinite;
 }
 
 .tvw-voice-recording svg {
-  animation: voice-recording-pulse 1.5s ease-in-out infinite;
+  animation: tvw-voice-recording-pulse 1.5s ease-in-out infinite;
 }
 
 /* Markdown content overflow handling */
@@ -1239,8 +1240,12 @@ form:focus-within textarea {
   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.28.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/tailwind.css

@@ -3,7 +3,8 @@
 @tailwind utilities;
 
 @layer base {
-  :root {
+  /* Widget CSS Variables - scoped to widget root to avoid polluting global namespace */
+  #vanilla-agent-root {
     --travrse-primary: #111827;
     --travrse-secondary: #4338ca;
     --travrse-surface: #ffffff;

package/src/styles/widget.css

@@ -86,7 +86,8 @@
   gap: 1.5rem;
 }
 
-:root {
+/* Widget CSS Variables - scoped to widget root to avoid polluting global namespace */
+#vanilla-agent-root {
   --cw-radius-sm: 0.75rem;
   --cw-radius-md: 1rem;
   --cw-radius-lg: 1.5rem;
@@ -119,19 +120,19 @@
   --cw-md-h6-margin: 0.5rem 0 0.25rem;
   --cw-md-h6-line-height: 1.5;
 
-  /* Markdown Table Variables (defaults - theme-aware values set on #vanilla-agent-root) */
+  /* Markdown Table Variables */
   --cw-md-table-border-color: #e5e7eb;
   --cw-md-table-header-bg: #f8fafc;
   --cw-md-table-header-weight: 600;
   --cw-md-table-cell-padding: 0.5rem 0.75rem;
   --cw-md-table-border-radius: 0.375rem;
 
-  /* Markdown Horizontal Rule Variables (defaults - theme-aware values set on #vanilla-agent-root) */
+  /* Markdown Horizontal Rule Variables */
   --cw-md-hr-color: #e5e7eb;
   --cw-md-hr-height: 1px;
   --cw-md-hr-margin: 1rem 0;
 
-  /* Markdown Blockquote Variables (defaults - theme-aware values set on #vanilla-agent-root) */
+  /* Markdown Blockquote Variables */
   --cw-md-blockquote-border-color: #3b82f6;
   --cw-md-blockquote-border-width: 3px;
   --cw-md-blockquote-padding: 0.5rem 1rem;
@@ -140,7 +141,7 @@
   --cw-md-blockquote-text-color: #6b7280;
   --cw-md-blockquote-font-style: italic;
 
-  /* Markdown Code Block Variables (defaults - theme-aware values set on #vanilla-agent-root) */
+  /* Markdown Code Block Variables */
   --cw-md-code-block-bg: #f3f4f6;
   --cw-md-code-block-border-color: #e5e7eb;
   --cw-md-code-block-text-color: inherit;
@@ -148,7 +149,7 @@
   --cw-md-code-block-border-radius: 0.375rem;
   --cw-md-code-block-font-size: 0.875rem;
 
-  /* Markdown Inline Code Variables (defaults - theme-aware values set on #vanilla-agent-root) */
+  /* Markdown Inline Code Variables */
   --cw-md-inline-code-bg: #f3f4f6;
   --cw-md-inline-code-padding: 0.125rem 0.375rem;
   --cw-md-inline-code-border-radius: 0.25rem;
@@ -677,7 +678,7 @@
 }
 
 /* Ensure textarea in composer form has no border on focus */
-textarea:focus {
+.tvw-widget-composer textarea:focus {
   border: none !important;
   outline: none !important;
   border-width: 0 !important;
@@ -687,11 +688,11 @@ textarea:focus {
 }
 
 /* Prevent form container from showing focus styles */
-form:focus-within {
+.tvw-widget-composer:focus-within {
   outline: none !important;
 }
 
-form:focus-within textarea {
+.tvw-widget-composer:focus-within textarea {
   border: none !important;
   outline: none !important;
 }
@@ -804,7 +805,7 @@ form:focus-within textarea {
 }
 
 /* Typing indicator animation */
-@keyframes typing {
+@keyframes tvw-typing {
   0%, 100% {
     opacity: 0.5;
     transform: translateY(0);
@@ -816,7 +817,7 @@ form:focus-within textarea {
 }
 
 .tvw-animate-typing {
-  animation: typing 1s infinite;
+  animation: tvw-typing 1s infinite;
 }
 
 .tvw-space-x-1 > * + * {
@@ -848,7 +849,7 @@ form:focus-within textarea {
 }
 
 /* Voice recognition recording animation */
-@keyframes voice-recording-pulse {
+@keyframes tvw-voice-recording-pulse {
   0%, 100% {
     opacity: 1;
     transform: scale(1);
@@ -860,11 +861,11 @@ form:focus-within textarea {
 }
 
 .tvw-voice-recording {
-  animation: voice-recording-pulse 1.5s ease-in-out infinite;
+  animation: tvw-voice-recording-pulse 1.5s ease-in-out infinite;
 }
 
 .tvw-voice-recording svg {
-  animation: voice-recording-pulse 1.5s ease-in-out infinite;
+  animation: tvw-voice-recording-pulse 1.5s ease-in-out infinite;
 }
 
 /* Markdown content overflow handling */
@@ -1239,8 +1240,12 @@ form:focus-within textarea {
   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;