@runtypelabs/persona 4.8.0 → 4.10.0

package/src/ui.ts

@@ -5,6 +5,7 @@ import { onMarkdownParsersReady, getMarkdownParsersSync } from "./markdown-parse
 import { AgentWidgetSession, AgentWidgetSessionStatus } from "./session";
 import {
   AgentWidgetConfig,
+  AgentWidgetConfigPatch,
   AgentWidgetApprovalDecisionOptions,
   AgentWidgetMessage,
   AgentWidgetEvent,
@@ -30,9 +31,16 @@ import {
   PersonaArtifactRecord,
   PersonaArtifactManualUpsert,
   PersonaArtifactFileMeta,
-  PersonaArtifactActionContext
+  PersonaArtifactActionContext,
+  AgentWidgetContentSegment,
+  AgentWidgetContextMentionRef
 } from "./types";
 import { AttachmentManager } from "./utils/attachment-manager";
+import {
+  createContextMentionOrchestrator,
+  type ContextMentionOrchestrator,
+} from "./utils/context-mention-orchestrator";
+import type { MentionSubmitBundle } from "./utils/context-mention-manager";
 import { createTextPart, ALL_SUPPORTED_MIME_TYPES } from "./utils/content";
 import { applyThemeVariables, createThemeObserver, getActiveTheme } from "./utils/theme";
 import { resolveTokenValue } from "./utils/tokens";
@@ -126,6 +134,7 @@ import { readFlexGapPx, resolveArtifactPaneWidthPx } from "./utils/artifact-resi
 import { enhanceWithForms } from "./components/forms";
 import { pluginRegistry } from "./plugins/registry";
 import { mergeWithDefaults, DEFAULT_FLOATING_LAUNCHER_WIDTH } from "./defaults";
+import { mergeConfigUpdate } from "./utils/config-merge";
 import { createEventBus } from "./utils/events";
 import {
   createActionManager,
@@ -298,7 +307,7 @@ const stripStreamingFromMessages = (messages: AgentWidgetMessage[]) =>
   }));
 
 type Controller = {
-  update: (config: AgentWidgetConfig) => void;
+  update: (config: AgentWidgetConfigPatch) => void;
   destroy: () => void;
   open: () => void;
   close: () => void;
@@ -535,6 +544,35 @@ function buildDropOverlay(
   return overlay;
 }
 
+// Deep-merge two mention context maps (`{ [sourceId]: { [itemId]: unknown } }`).
+// A source contributing to both bundles keeps BOTH per-item maps; a shallow
+// spread would let one sourceId's inner map wholesale replace the other's.
+export const mergeMentionContext = (
+  a: MentionSubmitBundle["context"],
+  b: MentionSubmitBundle["context"]
+): MentionSubmitBundle["context"] => {
+  const out: MentionSubmitBundle["context"] = { ...a };
+  for (const [sourceId, items] of Object.entries(b)) {
+    const existing = out[sourceId];
+    out[sourceId] = existing ? { ...existing, ...items } : items;
+  }
+  return out;
+};
+
+// Concatenate the fulfilled halves of two finalize() results (either may be
+// absent when its side rejected), deep-merging their per-source context.
+export const mergeFinalizedMentions = (
+  bundles: MentionSubmitBundle[]
+): MentionSubmitBundle =>
+  bundles.reduce<MentionSubmitBundle>(
+    (acc, b) => ({
+      blocks: [...acc.blocks, ...b.blocks],
+      contentParts: [...acc.contentParts, ...b.contentParts],
+      context: mergeMentionContext(acc.context, b.context),
+    }),
+    { blocks: [], contentParts: [], context: {} }
+  );
+
 export const createAgentExperience = (
   mount: HTMLElement,
   initialConfig?: AgentWidgetConfig,
@@ -840,9 +878,13 @@ export const createAgentExperience = (
     header,
     footer,
     actionsRow: _actionsRow,
-    leftActions,
     rightActions
   } = panelElements;
+  // Nullable + reassignable: a plugin `replaceComposer` swaps the footer, and
+  // `bindComposerRefsFromFooter` must repoint this at the NEW left-action
+  // cluster (or null it so the composerForm fallback fires) — a stale ref would
+  // insert the mention/attachment buttons into the detached old subtree.
+  let leftActions: HTMLElement | null = panelElements.leftActions;
   let setSendButtonMode = panelElements.setSendButtonMode;
 
   // Use mutable references for mic button so we can update them dynamically
@@ -981,6 +1023,9 @@ export const createAgentExperience = (
 
   // Initialized after composer plugins rebind footer DOM (see `bindComposerRefsFromFooter`)
   let attachmentManager: AttachmentManager | null = null;
+  // Context mentions orchestrator (core, tiny); lazy-loads the heavy runtime on
+  // first use. Null when `contextMentions` is disabled / has no sources.
+  let mentionOrchestrator: ContextMentionOrchestrator | null = null;
 
   /** Wired after `handleMicButtonClick` is defined; used by `renderComposer` `onVoiceToggle`. */
   let composerVoiceBridge: (() => void) | null = null;
@@ -1251,6 +1296,10 @@ export const createAgentExperience = (
       ".persona-widget-composer .persona-flex.persona-items-center.persona-justify-between"
     );
     if (ar) _actionsRow = ar;
+    // Rebind the left-action cluster to the NEW footer (both composer builders
+    // ship this class). Assign unconditionally: when a custom plugin composer
+    // has no left cluster, null lets the button-insert fall back to the form.
+    leftActions = pick<HTMLElement>(".persona-widget-composer__left-actions");
   };
   ensureComposerAttachmentSurface(footer);
   bindComposerRefsFromFooter(footer);
@@ -1303,6 +1352,49 @@ export const createAgentExperience = (
     container.appendChild(overlay);
   }
 
+  // Context mentions: render the affordance button + chip row eagerly (so the
+  // feature is discoverable) and lazy-load the heavy runtime on first use. The
+  // orchestrator returns null when disabled or sourceless.
+  const mentionPrefetch = () => mentionOrchestrator?.prefetch();
+  if (config.contextMentions?.enabled && textarea) {
+    // Slash-command dispatch (prompt macros write text / submit; client actions
+    // read/replace the value) and submission are owned by the composer input
+    // surface itself — the mention runtime builds a textarea (chip) or
+    // contenteditable (inline) adapter from this textarea. Broader host actions
+    // (clear transcript, theme) are still wired via closures over the controller.
+    mentionOrchestrator = createContextMentionOrchestrator({
+      config,
+      textarea,
+      anchor: composerForm ?? textarea,
+      getMessages: () => session.getMessages(),
+      // The engine chunk creates the mention live regions in this container on
+      // mount, keeping the live-region helper out of the core bundle.
+      liveRegionHost: container,
+    });
+
+    if (mentionOrchestrator) {
+      // Chip row sits directly above the textarea.
+      const ta = textarea;
+      ta.parentElement?.insertBefore(mentionOrchestrator.contextRow, ta);
+      // Each channel's "add context" affordance is a secondary control that
+      // augments the outgoing message, so it joins the LEFT action cluster
+      // (beside the attachment button) — never the right cluster with mic +
+      // send. Buttons are inserted leftmost in channel order so they read as
+      // "add to my message" and stay clear of the primary send action. Both
+      // composer builders (full + pill) always ship `leftActions`; the form
+      // fallback is purely defensive.
+      const buttons = mentionOrchestrator.affordanceButtons;
+      for (let i = buttons.length - 1; i >= 0; i--) {
+        const btn = buttons[i];
+        if (leftActions) leftActions.insertBefore(btn, leftActions.firstChild);
+        else composerForm?.appendChild(btn);
+      }
+      // The focus-prefetch listener (warm the chunk on first focus so the first
+      // `@` is instant) is registered through the shared `composerListeners`
+      // registry below, so it survives the inline contenteditable swap too.
+    }
+  }
+
   // Slot system: allow custom content injection into specific regions
   const renderSlots = () => {
     const slots = config.layout?.slots ?? {};
@@ -6174,26 +6266,93 @@ export const createAgentExperience = (
     setOpenState(true, "auto");
   };
 
-  const handleSubmit = (event: Event) => {
-    event.preventDefault();
+  // Combine `@`-chip mentions with an inline server-command's context bundle so
+  // both reach the message in one `mentions` payload. Either side may be null.
+  type SubmitMentions = NonNullable<
+    ReturnType<NonNullable<typeof mentionOrchestrator>["collectForSubmit"]>
+  >;
+  const mergeSubmitMentions = (
+    a: SubmitMentions | null,
+    b: SubmitMentions | null
+  ): SubmitMentions | null => {
+    if (!a) return b;
+    if (!b) return a;
+    return {
+      refs: [...a.refs, ...b.refs],
+      // allSettled, not all: one side rejecting must not discard the other
+      // side's already-resolved context (the bubble already echoed its chips).
+      finalize: async () => {
+        const [ra, rb] = await Promise.allSettled([a.finalize(), b.finalize()]);
+        const fulfilled: MentionSubmitBundle[] = [];
+        if (ra.status === "fulfilled") fulfilled.push(ra.value);
+        else console.warn("[Persona] a mention bundle failed to finalize; sending without it", ra.reason);
+        if (rb.status === "fulfilled") fulfilled.push(rb.value);
+        else console.warn("[Persona] a mention bundle failed to finalize; sending without it", rb.reason);
+        return mergeFinalizedMentions(fulfilled);
+      },
+    };
+  };
 
-    // While a response is streaming, the submit button acts as a stop button.
-    // Abort the in-flight stream and leave textarea contents / attachments
-    // intact so the user can edit and resend without retyping.
-    if (session.isStreaming()) {
-      session.cancel();
-      // Cancelling emits no terminal/error SSE frame, so reset the throughput
-      // tracker (as clear-chat does) to avoid a stale `running` row lingering.
-      throughputTracker?.reset();
-      eventStreamView?.update();
-      return;
-    }
+  // Inline-mode composer element: after the contenteditable swap, `textarea`
+  // additionally exposes `getInlineMessageFields()` (built in the inline chunk,
+  // which owns the document model — the core never imports it). Structural shape
+  // only, so no runtime import crosses the bundle boundary.
+  type InlineComposerFieldsHost = {
+    getInlineMessageFields?: () => {
+      content: string;
+      contextMentions: AgentWidgetContextMentionRef[];
+      contentSegments: AgentWidgetContentSegment[];
+    };
+  };
+  // Read the ordered display segments from the live inline composer, but only
+  // when at least one mention is present: a plain-text inline message must keep
+  // the normal markdown-rendered bubble (segments bypass that path), so we return
+  // undefined for pure prose and let the bubble render `content` as usual.
+  const readInlineContentSegments = (): AgentWidgetContentSegment[] | undefined => {
+    const host = textarea as unknown as InlineComposerFieldsHost;
+    const fields = host.getInlineMessageFields?.();
+    if (!fields) return undefined;
+    const hasMention = fields.contentSegments.some((s) => s.kind === "mention");
+    return hasMention ? fields.contentSegments : undefined;
+  };
+
+  // Re-entrancy guard for the async submit path: `takeInlineCommand` awaits (a
+  // lazy chunk load + host resolve) before the composer clears, and
+  // `isStreaming()` is still false in that window, so a second Enter would
+  // otherwise dispatch the same text/command twice.
+  let submitInFlight = false;
 
+  const performSubmit = async (submitOptions?: { viaVoice?: boolean }) => {
     const value = textarea.value.trim();
     const hasAttachments = attachmentManager?.hasAttachments() ?? false;
 
-    // Must have text or attachments to send
-    if (!value && !hasAttachments) return;
+    // Inline slash command (Slack-style): every `command:"server"` plus any
+    // arg-bearing prompt/action. Resolve FIRST — a prompt command changes the
+    // text to send, and an action sends nothing at all.
+    const inline = value
+      ? await (mentionOrchestrator?.takeInlineCommand(value) ?? Promise.resolve(null))
+      : null;
+
+    if (inline?.kind === "action") {
+      // Ran in the browser; nothing to send. Clear the composer + any chips.
+      textarea.value = "";
+      textarea.style.height = "auto";
+      resetHistoryNavigation();
+      mentionOrchestrator?.clear();
+      return;
+    }
+
+    // Gather `@`-chip mentions synchronously (detaches chips + captures composer
+    // text before clearing); `finalize()` resolves them inside `sendMessage`.
+    const chipMentions = mentionOrchestrator?.collectForSubmit() ?? null;
+    const serverMentions = inline?.kind === "server" ? inline.mentions : null;
+    const mentions = mergeSubmitMentions(chipMentions, serverMentions);
+    // A prompt command replaces the outgoing text with its resolved macro.
+    const sendText = inline?.kind === "prompt" ? inline.sendText : value;
+
+    const hasChips = !!chipMentions && chipMentions.refs.length > 0;
+    // Must have text, attachments, chips, or an inline server command's context.
+    if (!sendText && !hasAttachments && !hasChips && !serverMentions) return;
 
     maybeExpandComposerBar();
 
@@ -6204,22 +6363,65 @@ export const createAgentExperience = (
       // Add image parts first
       contentParts.push(...attachmentManager!.getContentParts());
       // Add text part if there's text
-      if (value) {
-        contentParts.push(createTextPart(value));
+      if (sendText) {
+        contentParts.push(createTextPart(sendText));
       }
     }
 
+    // Capture the inline display segments BEFORE clearing the composer (clearing
+    // rebuilds the document as empty text). Only set when a `prompt` macro didn't
+    // replace the outgoing text — a macro's segments no longer match `sendText`.
+    const contentSegments =
+      inline?.kind === "prompt" ? undefined : readInlineContentSegments();
+
     textarea.value = "";
     textarea.style.height = "auto"; // Reset height after clearing
     resetHistoryNavigation();
 
-    // Send message with optional content parts
-    session.sendMessage(value, { contentParts });
+    // Send message with optional content parts + mentions
+    session.sendMessage(sendText, {
+      contentParts,
+      mentions: mentions ?? undefined,
+      contentSegments,
+      viaVoice: submitOptions?.viaVoice,
+    });
 
-    // Clear attachments after sending
+    // Clear attachments + mention chips after sending
     if (hasAttachments) {
       attachmentManager!.clearAttachments();
     }
+    if (chipMentions) {
+      mentionOrchestrator?.clear();
+    }
+  };
+
+  const doSubmit = async (submitOptions?: { viaVoice?: boolean }) => {
+    if (submitInFlight) return;
+    submitInFlight = true;
+    try {
+      await performSubmit(submitOptions);
+    } finally {
+      submitInFlight = false;
+    }
+  };
+
+  const handleSubmit = (event: Event) => {
+    event.preventDefault();
+
+    // While a response is streaming, the submit button acts as a stop button.
+    // Abort the in-flight stream and leave textarea contents / attachments
+    // intact so the user can edit and resend without retyping.
+    if (session.isStreaming()) {
+      session.cancel();
+      // Cancelling emits no terminal/error SSE frame, so reset the throughput
+      // tracker (as clear-chat does) to avoid a stale `running` row lingering.
+      throughputTracker?.reset();
+      eventStreamView?.update();
+      return;
+    }
+
+    if (submitInFlight) return;
+    void doSubmit();
   };
 
   // --- Composer message-history navigation (Up/Down arrows) ---
@@ -6258,15 +6460,30 @@ export const createAgentExperience = (
     textarea.setSelectionRange(end, end);
   };
 
-  const handleComposerInput = () => {
-    // A real edit leaves history-navigation mode.
+  const handleComposerInput = (event: Event) => {
+    // The synthetic input from history recall (guarded by `suppressHistoryReset`)
+    // is not user typing: it must neither open the mention menu (an undefined
+    // inputType reads as menu-opening) nor exit history-navigation mode.
     if (suppressHistoryReset) return;
+    // Drive the mention menu (open/update/close) + lazy-load on first trigger.
+    // Skip while an IME composition is active: the intermediate value isn't the
+    // user's committed text, so it must not open or filter the menu.
+    if (!(event as InputEvent).isComposing) {
+      mentionOrchestrator?.handleInput((event as InputEvent).inputType ?? undefined);
+    }
+    // A real edit leaves history-navigation mode.
     resetHistoryNavigation();
   };
 
   const handleComposerKeydown = (event: KeyboardEvent) => {
     if (!textarea) return;
 
+    // Mention menu takes precedence when open (↑/↓ nav, Enter/Tab select, Esc
+    // close) and handles Backspace-removes-last-chip on an empty composer. One
+    // handler, no competing capture-phase listener. Skip during IME composition
+    // so Enter-to-confirm-composition isn't swallowed as a menu selection.
+    if (!event.isComposing && mentionOrchestrator?.handleKeydown(event)) return;
+
     // Up/Down: walk through previously sent user messages.
     if (
       historyNavigationEnabled() &&
@@ -6304,6 +6521,12 @@ export const createAgentExperience = (
         event.preventDefault();
         return;
       }
+      // A submit is already awaiting its async pre-send work; a second Enter in
+      // that window would dispatch the same text twice.
+      if (submitInFlight) {
+        event.preventDefault();
+        return;
+      }
       resetHistoryNavigation();
       event.preventDefault();
       sendButton.click();
@@ -6409,9 +6632,11 @@ export const createAgentExperience = (
           const finalValue = textarea.value.trim();
           if (finalValue && speechRecognition && isRecording) {
             stopVoiceRecognition();
-            textarea.value = "";
-            textarea.style.height = "auto"; // Reset height after clearing
-            session.sendMessage(finalValue, { viaVoice: true });
+            // Route through the normal submit path so mentions are collected +
+            // cleared like a manual send (the transcript already lives in the
+            // composer). Sending directly would leave stale tracked mention
+            // context to attach to the next unrelated message.
+            void doSubmit({ viaVoice: true });
           }
         }, pauseDuration);
       }
@@ -6429,9 +6654,9 @@ export const createAgentExperience = (
       if (isRecording) {
         const finalValue = textarea.value.trim();
         if (finalValue && finalValue !== initialText.trim()) {
-          textarea.value = "";
-          textarea.style.height = "auto"; // Reset height after clearing
-          session.sendMessage(finalValue, { viaVoice: true });
+          // Route through the normal submit path (mentions collect + clear), same
+          // as the pause-timer branch above.
+          void doSubmit({ viaVoice: true });
         }
         stopVoiceRecognition();
       }
@@ -7313,9 +7538,43 @@ export const createAgentExperience = (
   if (composerForm) {
     composerForm.addEventListener("submit", handleSubmit);
   }
-  textarea?.addEventListener("keydown", handleComposerKeydown);
-  textarea?.addEventListener("input", handleComposerInput);
-  textarea?.addEventListener("paste", handleInputPaste);
+
+  // Single registry of composer listeners. The initial attach and the inline
+  // contenteditable swap-reattach both consume this array, so a listener added
+  // here is mechanically included in both — no hand-maintained enumeration to
+  // drift. Add new composer listeners here, not as ad-hoc addEventListener calls.
+  type ComposerListener = [event: string, handler: (event: Event) => void];
+  const composerListeners: ComposerListener[] = [
+    ["keydown", handleComposerKeydown as unknown as (event: Event) => void],
+    ["input", handleComposerInput as (event: Event) => void],
+    ["paste", handleInputPaste as unknown as (event: Event) => void],
+    // Warm the mention chunk on first focus so the first `@` is instant.
+    ["focus", mentionPrefetch as (event: Event) => void],
+  ];
+  const attachComposerListeners = (el: HTMLElement | null): void => {
+    if (!el) return;
+    for (const [event, handler] of composerListeners) {
+      el.addEventListener(event, handler);
+    }
+  };
+  const detachComposerListeners = (el: HTMLElement | null): void => {
+    if (!el) return;
+    for (const [event, handler] of composerListeners) {
+      el.removeEventListener(event, handler);
+    }
+  };
+
+  attachComposerListeners(textarea);
+
+  // Inline mention mode swaps the textarea for a contenteditable surface (loaded
+  // lazily). When that happens, move the composer listeners onto the new element
+  // and repoint `textarea` (the swapped element shims the textarea API the rest of
+  // the composer code relies on). Fires immediately if the swap already occurred.
+  mentionOrchestrator?.onComposerSwap((next, prev) => {
+    detachComposerListeners(prev);
+    textarea = next as unknown as HTMLTextAreaElement;
+    attachComposerListeners(next);
+  });
 
   const escStopDoc = mount.ownerDocument ?? document;
   escStopDoc.addEventListener("keydown", handleEscStop, true);
@@ -7396,10 +7655,9 @@ export const createAgentExperience = (
     if (composerForm) {
       composerForm.removeEventListener("submit", handleSubmit);
     }
-    textarea?.removeEventListener("keydown", handleComposerKeydown);
-    textarea?.removeEventListener("input", handleComposerInput);
-    textarea?.removeEventListener("paste", handleInputPaste);
+    detachComposerListeners(textarea);
     escStopDoc.removeEventListener("keydown", handleEscStop, true);
+    mentionOrchestrator?.destroy();
   });
 
   destroyCallbacks.push(() => {
@@ -7427,7 +7685,7 @@ export const createAgentExperience = (
   }
 
   const controller: Controller = {
-    update(nextConfig: AgentWidgetConfig) {
+    update(nextConfig: AgentWidgetConfigPatch) {
       const previousToolCallConfig = config.toolCall;
       const previousMessageActions = config.messageActions;
       const previousLayoutMessages = config.layout?.messages;
@@ -7439,7 +7697,10 @@ export const createAgentExperience = (
       const previousToolCallDisplay = config.features?.toolCallDisplay;
       const previousReasoningDisplay = config.features?.reasoningDisplay;
       const previousStreamAnimationType = config.features?.streamAnimation?.type;
-      config = { ...config, ...nextConfig };
+      // One consistent recursive patch policy across the live controller and the
+      // init handle. See utils/config-merge.ts for the replace-leaf list and
+      // explicit-undefined reset semantics.
+      config = mergeConfigUpdate(config, nextConfig);
       // applyFullHeightStyles resets mount.style.cssText, so call it before applyThemeVariables
       applyFullHeightStyles();
       applyThemeVariables(mount, config);
@@ -7609,7 +7870,10 @@ export const createAgentExperience = (
           headerSubtitle.style.display = headerLayoutConfig.showSubtitle === false ? "none" : "";
         }
         if (closeButton) {
-          closeButton.style.display = headerLayoutConfig.showCloseButton === false ? "none" : "";
+          // showCloseButton (defaulted true) filters on top of toggleability;
+          // it must not reveal the close button on non-closeable panels.
+          const showClose = isPanelToggleable() && headerLayoutConfig.showCloseButton !== false;
+          closeButton.style.display = showClose ? "" : "none";
         }
         if (panelElements.clearChatButtonWrapper) {
           // showClearChat explicitly controls visibility when set
@@ -7670,7 +7934,7 @@ export const createAgentExperience = (
       refreshCloseButton();
 
       // Re-render messages if config affecting message rendering changed
-      const toolCallConfigChanged = JSON.stringify(nextConfig.toolCall) !== JSON.stringify(previousToolCallConfig);
+      const toolCallConfigChanged = JSON.stringify(config.toolCall) !== JSON.stringify(previousToolCallConfig);
       const messageActionsChanged = JSON.stringify(config.messageActions) !== JSON.stringify(previousMessageActions);
       const layoutMessagesChanged = JSON.stringify(config.layout?.messages) !== JSON.stringify(previousLayoutMessages);
       const loadingIndicatorChanged = config.loadingIndicator?.render !== previousLoadingIndicator?.render
@@ -7811,13 +8075,11 @@ export const createAgentExperience = (
       }
 
       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 = "";
-        }
+        // showCloseButton (defaulted true) filters on top of toggleability;
+        // it must not reveal the close button on non-closeable panels.
+        const layoutShowCloseButton =
+          isPanelToggleable() && config.layout?.header?.showCloseButton !== false;
+        closeButton.style.display = layoutShowCloseButton ? "" : "none";
 
         const closeButtonSize = launcher.closeButtonSize ?? "32px";
         const closeButtonPlacement = launcher.closeButtonPlacement ?? "inline";
@@ -7908,6 +8170,9 @@ export const createAgentExperience = (
         closeButton.innerHTML = "";
         const iconSvg = renderLucideIcon(closeButtonIconName, "28px", "currentColor", 1);
         if (iconSvg) {
+          // display:block matches the builder; inline SVG baseline spacing
+          // shifts the icon off-center.
+          iconSvg.style.display = "block";
           closeButton.appendChild(iconSvg);
         } else {
           closeButton.textContent = closeButtonIconText;
@@ -8094,8 +8359,13 @@ export const createAgentExperience = (
           // the icon to match its 16px button.
           clearChatButton.innerHTML = "";
           const clearChatIconSize = isComposerBar() ? "14px" : "20px";
-          const iconSvg = renderLucideIcon(clearChatIconName, clearChatIconSize, "currentColor", 2);
+          // Stroke 1 matches the mount-time builder (header-parts.ts); a
+          // different weight here makes the icon visibly bolden on update.
+          const iconSvg = renderLucideIcon(clearChatIconName, clearChatIconSize, "currentColor", 1);
           if (iconSvg) {
+            // display:block matches the builder; inline SVG baseline spacing
+            // shifts the icon off-center.
+            iconSvg.style.display = "block";
             clearChatButton.appendChild(iconSvg);
           }
 
@@ -8298,10 +8568,16 @@ export const createAgentExperience = (
           micButton.style.minWidth = micIconSize;
           micButton.style.minHeight = micIconSize;
           
-          // Update icon
-          const iconColor = voiceConfig.iconColor ?? sendButtonConfig.textColor ?? "currentColor";
+          // Update icon; color chain and stroke 1.5 match the mount-time
+          // builder (composer-parts.ts) so an unrelated update cannot restyle.
+          const iconColor = voiceConfig.iconColor ?? sendButtonConfig.textColor;
           micButton.innerHTML = "";
-          const micIconSvg = renderLucideIcon(micIconName, micIconSizeNum, iconColor, 2);
+          const micIconSvg = renderLucideIcon(
+            micIconName,
+            micIconSizeNum,
+            iconColor || "currentColor",
+            1.5
+          );
           if (micIconSvg) {
             micButton.appendChild(micIconSvg);
           } else {
@@ -8441,19 +8717,11 @@ export const createAgentExperience = (
           attachmentButton.style.minHeight = attachIconSize;
           attachmentButton.style.fontSize = "18px";
           attachmentButton.style.lineHeight = "1";
-          attachmentButton.style.backgroundColor = "transparent";
-          attachmentButton.style.color = "var(--persona-primary, #111827)";
-          attachmentButton.style.border = "none";
-          attachmentButton.style.borderRadius = "6px";
-          attachmentButton.style.transition = "background-color 0.15s ease";
-
-          // Add hover effect via mouseenter/mouseleave
-          attachmentButton.addEventListener("mouseenter", () => {
-            attachmentButton!.style.backgroundColor = "var(--persona-palette-colors-black-alpha-50, rgba(0, 0, 0, 0.05))";
-          });
-          attachmentButton.addEventListener("mouseleave", () => {
-            attachmentButton!.style.backgroundColor = "transparent";
-          });
+          // Appearance (bg / fg / border / radius / hover) is themed from the
+          // shared `.persona-attachment-button` CSS rule via the
+          // `--persona-button-ghost-*` tokens — matching the static
+          // createAttachmentControls path. Only sizing stays inline here so
+          // this runtime-created button restyles identically to the built-in one.
 
           const attachIconSvg = renderLucideIcon(attachIconName, attachIconSizeNum, "currentColor", 1.5);
           if (attachIconSvg) {
@@ -8475,8 +8743,10 @@ export const createAgentExperience = (
           tooltip.textContent = attachTooltipText;
           attachmentButtonWrapper.appendChild(tooltip);
 
-          // Insert into left actions container
-          leftActions.append(attachmentButtonWrapper);
+          // Insert into left actions container (fall back to the form when a
+          // custom composer has no left cluster).
+          if (leftActions) leftActions.append(attachmentButtonWrapper);
+          else composerForm.appendChild(attachmentButtonWrapper);
 
           // Initialize attachment manager
           if (!attachmentManager && attachmentInput && attachmentPreviewsContainer) {
@@ -8491,10 +8761,6 @@ export const createAgentExperience = (
             });
           }
 
-          // Create drop overlay if missing
-          if (!container.querySelector(".persona-attachment-drop-overlay")) {
-            container.appendChild(buildDropOverlay(attachmentsConfig.dropOverlay));
-          }
         } else {
           // Show existing attachment button and update config
           attachmentButtonWrapper.style.display = "";
@@ -8515,6 +8781,33 @@ export const createAgentExperience = (
             });
           }
         }
+
+        // Rebuild the overlay so live dropOverlay updates restyle it; visibility
+        // is owned by the container's drop-active class, so this is drag-safe.
+        container.querySelector(".persona-attachment-drop-overlay")?.remove();
+        container.appendChild(buildDropOverlay(config.attachments?.dropOverlay));
+
+        // Re-render icon/tooltip so live buttonIconName/buttonTooltipText
+        // updates apply; the button element itself is created once and kept.
+        if (attachmentButton) {
+          const attCfg = config.attachments ?? {};
+          const tooltipText = attCfg.buttonTooltipText ?? "Attach file";
+          attachmentButton.setAttribute("aria-label", tooltipText);
+          attachmentButton.textContent = "";
+          const btnSize = parseFloat(config.sendButton?.size ?? "40px") || 40;
+          const iconSvg = renderLucideIcon(
+            attCfg.buttonIconName ?? "paperclip",
+            Math.round(btnSize * 0.6),
+            "currentColor",
+            1.5
+          );
+          if (iconSvg) attachmentButton.appendChild(iconSvg);
+          else attachmentButton.textContent = "📎";
+          const attachTooltip = attachmentButtonWrapper?.querySelector(
+            ".persona-send-button-tooltip"
+          );
+          if (attachTooltip) attachTooltip.textContent = tooltipText;
+        }
       } else {
         // Hide attachment button if disabled
         if (attachmentButtonWrapper) {
@@ -8549,9 +8842,6 @@ export const createAgentExperience = (
         sendButton.style.fontSize = "18px";
         sendButton.style.lineHeight = "1";
         
-        // Clear existing content
-        sendButton.innerHTML = "";
-        
         // Set foreground color from config or theme token
         if (textColor) {
           sendButton.style.color = textColor;
@@ -8559,20 +8849,25 @@ export const createAgentExperience = (
           sendButton.style.color = "var(--persona-button-primary-fg, #ffffff)";
         }
 
-        // Use Lucide icon if iconName is provided, otherwise fall back to iconText
-        if (iconName) {
-          const iconSize = parseFloat(buttonSize) || 24;
-          const iconColor = textColor?.trim() || "currentColor";
-          const iconSvg = renderLucideIcon(iconName, iconSize, iconColor, 2);
-          if (iconSvg) {
-            sendButton.appendChild(iconSvg);
+        // Skip the icon-content re-render while streaming: the button holds the
+        // stop icon (owned by setSendButtonMode), and clobbering it here would
+        // show the send arrow mid-stream while the aria-label still says stop.
+        if (!session.isStreaming()) {
+          sendButton.innerHTML = "";
+          if (iconName) {
+            const iconSize = parseFloat(buttonSize) || 24;
+            const iconColor = textColor?.trim() || "currentColor";
+            const iconSvg = renderLucideIcon(iconName, iconSize, iconColor, 2);
+            if (iconSvg) {
+              sendButton.appendChild(iconSvg);
+            } else {
+              sendButton.textContent = iconText;
+            }
           } else {
             sendButton.textContent = iconText;
           }
-        } else {
-          sendButton.textContent = iconText;
         }
-        
+
         // Update classes
         sendButton.className = "persona-rounded-button persona-flex persona-items-center persona-justify-center disabled:persona-opacity-50 persona-cursor-pointer";