@runtypelabs/persona 3.15.1 → 3.17.0

package/src/client.test.ts

@@ -2576,3 +2576,144 @@ describe('AgentWidgetClient - Out-of-Order Sequence Reordering', () => {
   });
 });
 
+// ============================================================================
+// stopReason wiring (agent_turn_complete / step_complete)
+// ============================================================================
+
+describe('AgentWidgetClient - stopReason propagation', () => {
+  const dispatchModeStream = (stopReason?: string) => {
+    const data: Record<string, unknown> = {
+      type: 'step_complete',
+      id: 'step_1',
+      stepType: 'prompt',
+      result: { response: 'Hello there.' },
+    };
+    if (stopReason) data.stopReason = stopReason;
+    return [
+      `data: ${JSON.stringify(data)}\n\n`,
+      `data: ${JSON.stringify({ type: 'flow_complete', success: true })}\n\n`,
+    ];
+  };
+
+  const collectFinalAssistant = (events: AgentWidgetEvent[]): AgentWidgetMessage | null => {
+    const messageEvents = events.filter(e => e.type === 'message');
+    for (let i = messageEvents.length - 1; i >= 0; i--) {
+      const ev = messageEvents[i];
+      if (ev.type === 'message' && ev.message.role === 'assistant' && !ev.message.streaming) {
+        return ev.message;
+      }
+    }
+    return null;
+  };
+
+  const runDispatch = async (chunks: string[]): Promise<AgentWidgetEvent[]> => {
+    global.fetch = vi.fn().mockImplementation(async (_url: string, _options: any) => {
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(controller) {
+          for (const chunk of chunks) controller.enqueue(encoder.encode(chunk));
+          controller.close();
+        }
+      });
+      return { ok: true, body: stream };
+    });
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'usr_1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+    return events;
+  };
+
+  it.each(['end_turn', 'max_tool_calls', 'length', 'content_filter', 'error', 'unknown'] as const)(
+    'attaches stopReason=%s from step_complete (dispatch / flow path)',
+    async (stopReason) => {
+      const events = await runDispatch(dispatchModeStream(stopReason));
+      const final = collectFinalAssistant(events);
+      expect(final).not.toBeNull();
+      expect(final!.stopReason).toBe(stopReason);
+    }
+  );
+
+  it('leaves stopReason undefined when step_complete omits it (backcompat)', async () => {
+    const events = await runDispatch(dispatchModeStream(undefined));
+    const final = collectFinalAssistant(events);
+    expect(final).not.toBeNull();
+    expect(final!.stopReason).toBeUndefined();
+  });
+
+  it('captures the empty-content + max_tool_calls regression case', async () => {
+    // Symptom the upstream fix targets: model emits a tool call then gets cut
+    // off before producing follow-up text. Persona must record stopReason so
+    // the UI can render an affordance instead of an empty bubble.
+    const events = await runDispatch([
+      `data: ${JSON.stringify({
+        type: 'step_complete',
+        id: 'step_1',
+        stepType: 'prompt',
+        result: { response: '' },
+        stopReason: 'max_tool_calls',
+      })}\n\n`,
+      `data: ${JSON.stringify({ type: 'flow_complete', success: true })}\n\n`,
+    ]);
+    const final = collectFinalAssistant(events);
+    expect(final).not.toBeNull();
+    expect(final!.content).toBe('');
+    expect(final!.stopReason).toBe('max_tool_calls');
+  });
+
+  it('agent_turn_complete.stopReason overrides any earlier step_complete value (agent-loop path)', async () => {
+    // Build an agent-mode stream that emits both events. agent_turn_complete
+    // arrives last; its stopReason should win.
+    const execId = 'exec_stopreason';
+    global.fetch = createAgentStreamFetch([
+      sseEvent('agent_start', {
+        executionId: execId, agentId: 'virtual', agentName: 'Test',
+        maxTurns: 1, startedAt: new Date().toISOString(), seq: 1,
+      }),
+      sseEvent('agent_iteration_start', {
+        executionId: execId, iteration: 1, maxTurns: 1,
+        startedAt: new Date().toISOString(), seq: 2,
+      }),
+      sseEvent('agent_turn_start', {
+        executionId: execId, iteration: 1, turnIndex: 0,
+        role: 'assistant', turnId: 'turn_1', seq: 3,
+      }),
+      sseEvent('agent_turn_delta', {
+        executionId: execId, iteration: 1, delta: 'partial answer',
+        contentType: 'text', turnId: 'turn_1', seq: 4,
+      }),
+      sseEvent('agent_turn_complete', {
+        executionId: execId, iteration: 1, role: 'assistant',
+        turnId: 'turn_1', completedAt: new Date().toISOString(),
+        stopReason: 'max_tool_calls', seq: 5,
+      }),
+      sseEvent('agent_iteration_complete', {
+        executionId: execId, iteration: 1, toolCallsMade: 0,
+        stopConditionMet: true, completedAt: new Date().toISOString(), seq: 6,
+      }),
+      sseEvent('agent_complete', {
+        executionId: execId, agentId: 'virtual', success: true,
+        iterations: 1, stopReason: 'max_iterations',
+        completedAt: new Date().toISOString(), seq: 7,
+      }),
+    ]);
+
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      agent: { name: 'Test', model: 'openai:gpt-4o-mini', systemPrompt: 'test' },
+    });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'usr_1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    const final = collectFinalAssistant(events);
+    expect(final).not.toBeNull();
+    expect(final!.stopReason).toBe('max_tool_calls');
+    expect(final!.agentMetadata?.turnId).toBe('turn_1');
+  });
+});
+

package/src/client.ts

@@ -13,6 +13,7 @@ import {
   AgentWidgetHeadersFunction,
   AgentWidgetSSEEventResult as _AgentWidgetSSEEventResult,
   AgentExecutionState,
+  StopReasonKind,
   ClientSession,
   ClientInitResponse,
   ClientChatRequest,
@@ -1057,6 +1058,16 @@ export class AgentWidgetClient {
     let didSplitByPartId = false;
     const reasoningMessages = new Map<string, AgentWidgetMessage>();
     const toolMessages = new Map<string, AgentWidgetMessage>();
+    // Messages produced by steps inside a nested flow executed as a tool.
+    // Keyed by `${parentToolId}::${nestedStepId}::${partId}` so each nested
+    // step (send-stream, prompt) gets its own assistant message, and prompts
+    // with inner tool calls split into one message per text segment — still
+    // attributable to the parent tool call.
+    const nestedStepMessages = new Map<string, AgentWidgetMessage>();
+    // Most-recent partId seen for a given `${toolId}::${stepId}` scope, used
+    // to seal the previous segment when a new partId arrives within the
+    // same nested prompt step.
+    const nestedPartIdByStep = new Map<string, string>();
     const reasoningContext = {
       lastId: null as string | null,
       byStep: new Map<string, string>()
@@ -1066,6 +1077,49 @@ export class AgentWidgetClient {
       byCall: new Map<string, string>()
     };
 
+    // Nested message key. partId defaults to "" so steps without segmentation
+    // (e.g. send-stream) still have a deterministic single key.
+    const getNestedStepKey = (
+      toolId: string,
+      stepId: string,
+      partId: string = ""
+    ) => `${toolId}::${stepId}::${partId}`;
+
+    // Prefix used to sweep every nested message belonging to a single
+    // (toolId, stepId) scope — needed on step_complete to seal any segments
+    // that are still streaming.
+    const getNestedStepPrefix = (toolId: string, stepId: string) =>
+      `${toolId}::${stepId}::`;
+
+    const ensureNestedStepMessage = (
+      toolId: string,
+      stepId: string,
+      partId: string,
+      executionId?: string
+    ): AgentWidgetMessage => {
+      const key = getNestedStepKey(toolId, stepId, partId);
+      const existing = nestedStepMessages.get(key);
+      if (existing) return existing;
+      const idSuffix = partId ? `-${partId}` : "";
+      const message: AgentWidgetMessage = {
+        id: `nested-${toolId}-${stepId}${idSuffix}`,
+        role: "assistant",
+        content: "",
+        createdAt: new Date().toISOString(),
+        streaming: true,
+        sequence: nextSequence(),
+        ...(partId ? { partId } : {}),
+        agentMetadata: {
+          executionId,
+          parentToolId: toolId,
+          parentStepId: stepId,
+        },
+      };
+      nestedStepMessages.set(key, message);
+      emitMessage(message);
+      return message;
+    };
+
     const normalizeKey = (value: unknown): string | null => {
       if (value === null || value === undefined) return null;
       try {
@@ -1669,7 +1723,13 @@ export class AgentWidgetClient {
             toolContext.byCall.delete(callKey);
           }
         } else if (payloadType === "text_start") {
-          // Lifecycle event: a new text segment is beginning (emitted at tool boundaries)
+          // Lifecycle event: a new text segment is beginning (emitted at tool boundaries).
+          // When toolContext is present this fired inside a nested flow — it must not
+          // seal or rotate the outer assistant message. Nested prompt segmentation is
+          // handled via nestedStepMessages keyed by (toolId, stepId).
+          if ((payload as any).toolContext?.toolId) {
+            continue;
+          }
           const incomingPartId = payload.partId;
           if (incomingPartId !== undefined && partIdState.current !== null && incomingPartId !== partIdState.current) {
             const prev = assistantMessage as AgentWidgetMessage | null;
@@ -1685,7 +1745,13 @@ export class AgentWidgetClient {
             partIdState.current = incomingPartId;
           }
         } else if (payloadType === "text_end") {
-          // Lifecycle event: current text segment ended (tool call about to start)
+          // Lifecycle event: current text segment ended (tool call about to start).
+          // When toolContext is present the boundary belongs to a nested flow — leave
+          // outer assistant state alone so the outer stream is never interrupted by
+          // nested activity.
+          if ((payload as any).toolContext?.toolId) {
+            continue;
+          }
           // Seal the current assistant message so the next segment gets a new one
           const prev = assistantMessage as AgentWidgetMessage | null;
           if (prev) {
@@ -1704,6 +1770,77 @@ export class AgentWidgetClient {
             continue;
           }
 
+          // Nested flow routing: when toolContext is present, this step_delta
+          // originated inside a nested flow executed as a tool. Surface it as
+          // its own assistant message keyed by the nested step id, so authors
+          // who add send-stream / prompt steps inside their flow see them as
+          // real messages in the timeline, in order — rather than merging
+          // into the outer assistant bubble or getting buried in the tool
+          // card. Each nested step id gets its own message; the parent tool
+          // bubble continues to represent the invocation via tool_* events.
+          const nestedToolCtx = (payload as any).toolContext as
+            | { toolId?: string; stepId?: string; executionId?: string }
+            | undefined;
+          if (nestedToolCtx?.toolId) {
+            const nestedStepId = String(
+              payload.id ?? nestedToolCtx.stepId ?? `step-${nextSequence()}`
+            );
+            const incomingPartId =
+              payload.partId !== undefined && payload.partId !== null
+                ? String(payload.partId)
+                : "";
+            const stepScopeKey = `${nestedToolCtx.toolId}::${nestedStepId}`;
+            const prevPartId = nestedPartIdByStep.get(stepScopeKey);
+
+            // If partId changed within this nested step (prompt with inner
+            // tool call emitting a new text segment), seal the previous
+            // segment's message so each segment renders as its own bubble.
+            if (
+              incomingPartId !== "" &&
+              prevPartId !== undefined &&
+              prevPartId !== "" &&
+              prevPartId !== incomingPartId
+            ) {
+              const prev = nestedStepMessages.get(
+                getNestedStepKey(
+                  nestedToolCtx.toolId,
+                  nestedStepId,
+                  prevPartId
+                )
+              );
+              if (prev && prev.streaming !== false) {
+                prev.streaming = false;
+                emitMessage(prev);
+              }
+            }
+            if (incomingPartId !== "") {
+              nestedPartIdByStep.set(stepScopeKey, incomingPartId);
+            }
+
+            const nestedMsg = ensureNestedStepMessage(
+              nestedToolCtx.toolId,
+              nestedStepId,
+              incomingPartId,
+              nestedToolCtx.executionId
+            );
+            const nestedChunk =
+              payload.text ??
+              payload.delta ??
+              payload.content ??
+              payload.chunk ??
+              "";
+            if (nestedChunk) {
+              nestedMsg.content += String(nestedChunk);
+              nestedMsg.streaming = true;
+              emitMessage(nestedMsg);
+            }
+            if (payload.isComplete) {
+              nestedMsg.streaming = false;
+              emitMessage(nestedMsg);
+            }
+            continue;
+          }
+
           // partId-based segmentation: when partId changes, seal current message
           // and start a new one so text and tools render in chronological order
           const incomingPartId = payload.partId;
@@ -1927,11 +2064,51 @@ export class AgentWidgetClient {
             // Skip tool-related completions - they're handled by tool_complete
             continue;
           }
+
+          // Nested flow: seal every segment message produced by this nested
+          // step (a single nested prompt step may have produced multiple
+          // messages, one per partId, when inner tool calls split it). The
+          // outer assistantMessage state is untouched so reconciliation for
+          // the outer flow still works.
+          const nestedCompleteCtx = (payload as any).toolContext as
+            | { toolId?: string; stepId?: string; executionId?: string }
+            | undefined;
+          if (nestedCompleteCtx?.toolId) {
+            const nestedStepId = String(
+              payload.id ?? nestedCompleteCtx.stepId ?? ""
+            );
+            if (nestedStepId) {
+              const prefix = getNestedStepPrefix(
+                nestedCompleteCtx.toolId,
+                nestedStepId
+              );
+              for (const [key, msg] of nestedStepMessages) {
+                if (key.startsWith(prefix) && msg.streaming !== false) {
+                  msg.streaming = false;
+                  emitMessage(msg);
+                }
+              }
+              nestedPartIdByStep.delete(
+                `${nestedCompleteCtx.toolId}::${nestedStepId}`
+              );
+            }
+            continue;
+          }
+
+          // Capture optional per-step stopReason emitted by the runtime
+          // (e.g. `'max_tool_calls'`, `'length'`). This is the dispatch-mode
+          // fallback — `agent_turn_complete` will overwrite it later in
+          // agent-loop streams.
+          const stepStopReason = (payload as any).stopReason as
+            | StopReasonKind
+            | undefined;
+
           if (didSplitByPartId) {
             // Sealed segment(s) — do not create a second bubble from step_complete.
             // Merge authoritative final response into the last sealed segment (fixes async lag).
             if (assistantMessage !== null) {
               const msg: AgentWidgetMessage = assistantMessage;
+              if (stepStopReason) msg.stopReason = stepStopReason;
               streamParsers.delete(msg.id);
               rawContentBuffers.delete(msg.id);
               if (msg.streaming !== false) {
@@ -1942,6 +2119,7 @@ export class AgentWidgetClient {
             const splitFinalContent = payload.result?.response;
             const sealedForReconcile = lastSealedTextSegment;
             if (sealedForReconcile) {
+              if (stepStopReason) sealedForReconcile.stopReason = stepStopReason;
               if (splitFinalContent !== undefined && splitFinalContent !== null) {
                 reconcileSealedAssistantWithFinalResponse(sealedForReconcile, splitFinalContent);
               } else {
@@ -1954,6 +2132,7 @@ export class AgentWidgetClient {
           }
           const finalContent = payload.result?.response;
           const assistant = ensureAssistantMessage();
+          if (stepStopReason) assistant.stopReason = stepStopReason;
           if (finalContent !== undefined && finalContent !== null) {
             // Check if we already have extracted text from streaming
             const parser = streamParsers.get(assistant.id);
@@ -2241,6 +2420,22 @@ export class AgentWidgetClient {
               emitMessage(reasoningMessage);
             }
           }
+
+          // Attach the turn-level stopReason to the assistant message
+          // produced by this turn. Only overwrite the current message —
+          // prior turns already sealed their own stopReason via step_complete.
+          const turnStopReason = (payload as any).stopReason as
+            | StopReasonKind
+            | undefined;
+          if (turnStopReason && assistantMessage !== null) {
+            const turnId = payload.turnId;
+            const matchesTurn =
+              !turnId || assistantMessage.agentMetadata?.turnId === turnId;
+            if (matchesTurn) {
+              assistantMessage.stopReason = turnStopReason;
+              emitMessage(assistantMessage);
+            }
+          }
         } else if (payloadType === "agent_tool_start") {
           const toolId = payload.toolCallId ?? `agent-tool-${nextSequence()}`;
           trackToolId(getToolCallKey(payload), toolId);

package/src/components/composer-builder.ts

@@ -22,6 +22,13 @@ export interface ComposerElements {
   actionsRow: HTMLElement;
   leftActions: HTMLElement;
   rightActions: HTMLElement;
+  /**
+   * Swap the send button between its idle ("send") appearance and its
+   * streaming ("stop") appearance. In icon mode this swaps the SVG; in text
+   * mode it swaps the button label. Tooltip text is updated when a tooltip
+   * element is present.
+   */
+  setSendButtonMode: (mode: "send" | "stop") => void;
 }
 
 /**
@@ -122,7 +129,11 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
   const useIcon = sendButtonConfig.useIcon ?? false;
   const iconText = sendButtonConfig.iconText ?? "↑";
   const iconName = sendButtonConfig.iconName;
+  const stopIconName = sendButtonConfig.stopIconName ?? "square";
   const tooltipText = sendButtonConfig.tooltipText ?? "Send message";
+  const stopTooltipText = sendButtonConfig.stopTooltipText ?? "Stop generating";
+  const sendLabel = config?.copy?.sendButtonLabel ?? "Send";
+  const stopLabel = config?.copy?.stopButtonLabel ?? "Stop";
   const showTooltip = sendButtonConfig.showTooltip ?? false;
   const buttonSize = sendButtonConfig.size ?? "40px";
   const backgroundColor = sendButtonConfig.backgroundColor;
@@ -141,6 +152,11 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
   sendButton.type = "submit";
   sendButton.setAttribute("data-persona-composer-submit", "");
 
+  // Icons for both modes are pre-rendered so setSendButtonMode can swap them
+  // without having to re-render on every streaming state change.
+  let sendIcon: SVGElement | null = null;
+  let stopIcon: SVGElement | null = null;
+
   if (useIcon) {
     // Icon mode: circular button
     sendButton.style.width = buttonSize;
@@ -160,13 +176,14 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
       sendButton.style.color = "var(--persona-button-primary-fg, #ffffff)";
     }
 
+    const iconSize = parseFloat(buttonSize) || 24;
+    const iconColor = textColor?.trim() || "currentColor";
+
     // 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);
+      sendIcon = renderLucideIcon(iconName, iconSize, iconColor, 2);
+      if (sendIcon) {
+        sendButton.appendChild(sendIcon);
       } else {
         sendButton.textContent = iconText;
       }
@@ -174,6 +191,9 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
       sendButton.textContent = iconText;
     }
 
+    // Pre-render the stop icon so mode swaps are cheap; it starts detached.
+    stopIcon = renderLucideIcon(stopIconName, iconSize, iconColor, 2);
+
     if (backgroundColor) {
       sendButton.style.backgroundColor = backgroundColor;
     } else {
@@ -181,7 +201,7 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
     }
   } else {
     // Text mode: existing behavior
-    sendButton.textContent = config?.copy?.sendButtonLabel ?? "Send";
+    sendButton.textContent = sendLabel;
     if (textColor) {
       sendButton.style.color = textColor;
     } else {
@@ -215,14 +235,44 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
   }
 
   // Add tooltip if enabled
+  let sendTooltip: HTMLElement | null = null;
   if (showTooltip && tooltipText) {
-    const tooltip = createElement("div", "persona-send-button-tooltip");
-    tooltip.textContent = tooltipText;
-    sendButtonWrapper.appendChild(tooltip);
+    sendTooltip = createElement("div", "persona-send-button-tooltip");
+    sendTooltip.textContent = tooltipText;
+    sendButtonWrapper.appendChild(sendTooltip);
   }
 
+  sendButton.setAttribute("aria-label", tooltipText);
+
   sendButtonWrapper.appendChild(sendButton);
 
+  let currentMode: "send" | "stop" = "send";
+  const setSendButtonMode = (mode: "send" | "stop") => {
+    if (mode === currentMode) return;
+    currentMode = mode;
+    const label = mode === "stop" ? stopTooltipText : tooltipText;
+    sendButton.setAttribute("aria-label", label);
+    if (sendTooltip) {
+      sendTooltip.textContent = label;
+    }
+
+    if (useIcon) {
+      // Only swap icons if both were rendered successfully; otherwise the
+      // button is using textContent fallback and there's nothing to swap.
+      if (sendIcon && stopIcon) {
+        const next = mode === "stop" ? stopIcon : sendIcon;
+        const prev = mode === "stop" ? sendIcon : stopIcon;
+        if (prev.parentNode === sendButton) {
+          sendButton.replaceChild(next, prev);
+        } else {
+          sendButton.appendChild(next);
+        }
+      }
+    } else {
+      sendButton.textContent = mode === "stop" ? stopLabel : sendLabel;
+    }
+  };
+
   // Voice recognition mic button
   const voiceRecognitionConfig = config?.voiceRecognition ?? {};
   const voiceRecognitionEnabled = voiceRecognitionConfig.enabled === true;
@@ -515,7 +565,8 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
     // Actions row layout elements
     actionsRow,
     leftActions,
-    rightActions
+    rightActions,
+    setSendButtonMode
   };
 };
 

package/src/components/header-builder.ts

@@ -159,9 +159,11 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
     clearChatButton.style.color =
       clearChatIconColor || HEADER_THEME_CSS.actionIconColor;
 
-    // Add icon
+    // Add icon. display:block eliminates inline-baseline spacing that can
+    // push the icon a fractional pixel off-center inside the button.
     const iconSvg = renderLucideIcon(clearChatIconName, "20px", "currentColor", 1);
     if (iconSvg) {
+      iconSvg.style.display = "block";
       clearChatButton.appendChild(iconSvg);
     }
 
@@ -276,15 +278,17 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
     }
   }
 
-  // Create close button wrapper for tooltip positioning
-  // Only needs ml-auto if clear chat is disabled or top-right positioned
+  // Create close button wrapper for tooltip positioning.
+  // Mirrors the clear-chat wrapper's inline-flex centering so both
+  // header action buttons vertically align identically within the
+  // header's flex row.
   const closeButtonWrapper = createElement(
     "div",
     closeButtonPlacement === "top-right"
       ? "persona-absolute persona-top-4 persona-right-4 persona-z-50"
       : clearChatEnabled && clearChatPlacement === "inline"
-        ? ""
-        : "persona-ml-auto"
+        ? "persona-relative persona-inline-flex persona-items-center persona-justify-center"
+        : "persona-relative persona-ml-auto persona-inline-flex persona-items-center persona-justify-center"
   );
 
   // Create close button with base classes
@@ -309,9 +313,16 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
   closeButton.style.color =
     launcher.closeButtonColor || HEADER_THEME_CSS.actionIconColor;
 
-  // Try to render Lucide icon, fallback to text if not provided or fails
-  const closeIconSvg = renderLucideIcon(closeButtonIconName, "20px", "currentColor", 1);
+  // Try to render Lucide icon, fallback to text if not provided or fails.
+  // The X glyph's paths occupy only the middle 50% of its 24x24 viewBox
+  // (from 6,6 to 18,18), while other header icons (e.g. refresh-cw) span
+  // ~75% of the viewBox. Rendering X at a larger intrinsic size brings
+  // its visible extent into parity with sibling icons in the header.
+  // display:block eliminates inline-baseline spacing that can push the
+  // icon a fractional pixel off-center inside the button.
+  const closeIconSvg = renderLucideIcon(closeButtonIconName, "28px", "currentColor", 1);
   if (closeIconSvg) {
+    closeIconSvg.style.display = "block";
     closeButton.appendChild(closeIconSvg);
   } else {
     closeButton.textContent = closeButtonIconText;

package/src/components/header-layouts.ts

@@ -215,7 +215,9 @@ export const buildMinimalHeader: HeaderLayoutRenderer = (context) => {
     launcher.closeButtonColor || HEADER_THEME_CSS.actionIconColor;
 
   const closeButtonIconName = launcher.closeButtonIconName ?? "x";
-  const closeIconSvg = renderLucideIcon(closeButtonIconName, "20px", "currentColor", 2);
+  // Larger intrinsic size compensates for the X glyph's sparse viewBox
+  // (paths only occupy the middle 50%). Matches header-builder.ts.
+  const closeIconSvg = renderLucideIcon(closeButtonIconName, "28px", "currentColor", 1);
   if (closeIconSvg) {
     closeButton.appendChild(closeIconSvg);
   } else {