@runtypelabs/persona 4.13.0 → 4.15.0

package/src/ask-user-question-tool.ts

@@ -5,15 +5,18 @@
  * `clientTools[]` (set `features.askUserQuestion.expose: true`): the same
  * wire surface WebMCP page tools ride. The server registers it as a LOCAL
  * tool under its bare name (`origin: 'sdk'` tools are not `webmcp:`-prefixed),
- * so when the model calls it the execution pauses with a `step_await`
- * (`awaitReason: "local_tool_required"`), the widget's answer-pill sheet
- * renders, and `session.resolveAskUserQuestion()` resumes the execution with
- * the structured answers.
+ * so when the model calls it the execution pauses with a `step_await`, the
+ * widget's answer-pill sheet renders, and `session.resolveAskUserQuestion()`
+ * resumes the execution with the structured answers. The public await frame
+ * for a local-tool pause carries no `awaitReason`; that discriminator is
+ * internal, and its absence is what marks a client-resolvable pause.
  *
  * This replaces the previous integrator burden of hand-declaring the tool in
  * a flow's `runtimeTools` and keeping that schema in sync with the renderer.
  * Flows that already declare `ask_user_question` server-side should leave
- * `expose` off: the model would otherwise see the tool twice.
+ * `expose` off: the API dedupes a double declaration by name with
+ * `clientTools[]` winning, so the model still sees exactly one tool, but the
+ * widget's description and schema silently replace the flow's.
  */
 
 import {
@@ -22,7 +25,7 @@ import {
 } from "./components/ask-user-question-bubble";
 import {
   SUGGEST_REPLIES_CLIENT_TOOL,
-  shouldExposeSuggestReplies,
+  resolveFollowUpsFeature,
 } from "./suggest-replies-tool";
 import type { AgentWidgetConfig, ClientToolDefinition } from "./types";
 
@@ -129,7 +132,7 @@ export const builtInClientToolsForDispatch = (
   if (ask?.expose === true && ask.enabled !== false) {
     tools.push(ASK_USER_QUESTION_CLIENT_TOOL);
   }
-  if (shouldExposeSuggestReplies(config)) {
+  if (resolveFollowUpsFeature(config).expose) {
     tools.push(SUGGEST_REPLIES_CLIENT_TOOL);
   }
   return tools;

package/src/client.test.ts

@@ -4505,10 +4505,10 @@ describe('AgentWidgetClient - Artifact display modes', () => {
     });
   });
 
-  it('resolves the mode per artifact type via display.byType', async () => {
+  it('resolves the mode per artifact kind via display.byKind', async () => {
     const display: AgentWidgetArtifactsFeature['display'] = {
       default: 'card',
-      byType: { component: 'inline' },
+      byKind: { component: 'inline' },
     };
 
     const mdEvents = await dispatchAndCollect(markdownArtifactFrames(), {

package/src/client.ts

@@ -3184,7 +3184,10 @@ export class AgentWidgetClient {
               artifactIdsWithCards.add(artId);
               const displayMode = resolveArtifactDisplayMode(
                 this.config.features?.artifacts,
-                at
+                {
+                  artifactType: at,
+                  ...(artFile ? { file: artFile } : {}),
+                }
               );
               const artComponent =
                 typeof payload.component === "string" ? payload.component : undefined;

package/src/components/artifact-card.ts

@@ -1,5 +1,9 @@
 import type { ComponentContext, ComponentRenderer } from "./registry";
-import type { PersonaArtifactFileMeta, PersonaArtifactRecord } from "../types";
+import type {
+  PersonaArtifactFileMeta,
+  PersonaArtifactPresentation,
+  PersonaArtifactRecord
+} from "../types";
 import { fileTypeLabel, basenameOf } from "../utils/artifact-file";
 import {
   applyArtifactStatus,
@@ -33,6 +37,12 @@ function renderDefaultArtifactCard(
   const status = props.status === "streaming" ? "streaming" : "complete";
   const artifactType =
     typeof props.artifactType === "string" ? props.artifactType : "markdown";
+  const presentation =
+    props.presentation &&
+    typeof props.presentation === "object" &&
+    !Array.isArray(props.presentation)
+      ? (props.presentation as PersonaArtifactPresentation)
+      : undefined;
   const subtitle = file
     ? fileTypeLabel(file)
     : artifactType === "component"
@@ -83,7 +93,8 @@ function renderDefaultArtifactCard(
       title: rawTitle,
       status: "streaming",
       ...(typeof props.markdown === "string" ? { markdown: props.markdown } : {}),
-      ...(file ? { file } : {})
+      ...(file ? { file } : {}),
+      ...(presentation ? { presentation } : {})
     };
     const resolved = resolveArtifactStatusLabel(record, artifactsCfg, "card");
     applyArtifactStatus(subtitleEl, resolved, artifactsCfg);

package/src/components/artifact-inline.ts

@@ -2,6 +2,7 @@ import type { ComponentContext, ComponentRenderer } from "./registry";
 import type {
   AgentWidgetArtifactsFeature,
   PersonaArtifactFileMeta,
+  PersonaArtifactPresentation,
   PersonaArtifactRecord
 } from "../types";
 import { createElement } from "../utils/dom";
@@ -126,6 +127,12 @@ function recordFromProps(props: Record<string, unknown>): PersonaArtifactRecord
   const title =
     typeof props.title === "string" && props.title ? props.title : undefined;
   const status = props.status === "streaming" ? "streaming" : "complete";
+  const presentation =
+    props.presentation &&
+    typeof props.presentation === "object" &&
+    !Array.isArray(props.presentation)
+      ? (props.presentation as PersonaArtifactPresentation)
+      : undefined;
   if (props.artifactType === "component") {
     const embedded = props.componentProps;
     const componentProps =
@@ -138,7 +145,8 @@ function recordFromProps(props: Record<string, unknown>): PersonaArtifactRecord
       title,
       status,
       component: typeof props.component === "string" ? props.component : "",
-      props: componentProps
+      props: componentProps,
+      ...(presentation ? { presentation } : {})
     };
   }
   const file =
@@ -151,7 +159,8 @@ function recordFromProps(props: Record<string, unknown>): PersonaArtifactRecord
     title,
     status,
     markdown: typeof props.markdown === "string" ? props.markdown : "",
-    ...(file ? { file } : {})
+    ...(file ? { file } : {}),
+    ...(presentation ? { presentation } : {})
   };
 }
 

package/src/components/artifact-preview.ts

@@ -670,7 +670,7 @@ export function renderArtifactPreviewBody(
 
   // Render the syntax-highlighted source. On the inline path the <pre> lives in
   // a scroll window (`fixed` → reserved height + internal scroll + follow/fade);
-  // on the pane path it is a bare child of `el`, byte-identical to before.
+  // on the pane path it is a bare child of `el`, unchanged from before.
   const renderSource = (
     text: string,
     opts: { language?: string; path?: string } | undefined,

package/src/components/composer-builder.test.ts

@@ -17,6 +17,8 @@ describe("buildComposer (full column-stacked composer)", () => {
     expect(elements.composerForm.tagName).toBe("FORM");
     expect(elements.composerForm.getAttribute("data-persona-composer-form")).toBe("");
     expect(elements.composerForm.classList.contains("persona-flex-col")).toBe(true);
+    expect(elements.composerForm.classList.contains("persona-border-persona-border")).toBe(true);
+    expect(elements.composerForm.classList.contains("persona-border-gray-200")).toBe(false);
 
     expect(elements.textarea.getAttribute("data-persona-composer-input")).toBe("");
     expect(elements.sendButton.getAttribute("data-persona-composer-submit")).toBe("");

package/src/components/composer-builder.ts

@@ -67,7 +67,7 @@ export const buildComposer = (context: ComposerBuildContext): ComposerElements =
 
   const composerForm = createNode("form", {
     className:
-      "persona-widget-composer persona-flex persona-flex-col persona-gap-2 persona-rounded-2xl persona-border persona-border-gray-200 persona-bg-persona-input-background persona-px-4 persona-py-3",
+      "persona-widget-composer persona-flex persona-flex-col persona-gap-2 persona-rounded-2xl persona-border persona-border-persona-border persona-bg-persona-input-background persona-px-4 persona-py-3",
     attrs: { "data-persona-composer-form": "" },
     style: { outline: "none" },
   });

package/src/components/composer-parts.test.ts

@@ -19,6 +19,8 @@ describe("createComposerTextarea", () => {
     expect(textarea.tagName).toBe("TEXTAREA");
     expect(textarea.getAttribute("data-persona-composer-input")).toBe("");
     expect(textarea.classList.contains("persona-composer-textarea")).toBe(true);
+    expect(textarea.classList.contains("persona-text-persona-text")).toBe(true);
+    expect(textarea.classList.contains("persona-text-persona-primary")).toBe(false);
   });
 
   it("attachAutoResize wires an input listener that grows up to maxHeight", () => {
@@ -42,8 +44,59 @@ describe("createComposerTextarea", () => {
     Object.defineProperty(textarea, "scrollHeight", { configurable: true, value: 10000 });
     textarea.dispatchEvent(new Event("input"));
     expect(textarea.style.height).toBe("200px");
+    // The override keeps winning on later input events (pill composer path).
+    textarea.dispatchEvent(new Event("input"));
+    expect(textarea.style.height).toBe("200px");
+    expect(textarea.style.maxHeight).toBe("200px");
+    document.body.removeChild(textarea);
+  });
+
+  it("caps at 3 lines of the rendered line height when themed", () => {
+    const { textarea, attachAutoResize } = createComposerTextarea(baseConfig);
+    textarea.style.lineHeight = "24px";
+    document.body.appendChild(textarea);
+    attachAutoResize();
+    Object.defineProperty(textarea, "scrollHeight", { configurable: true, value: 10000 });
+    textarea.dispatchEvent(new Event("input"));
+    expect(textarea.style.height).toBe("72px");
+    expect(textarea.style.maxHeight).toBe("72px");
     document.body.removeChild(textarea);
   });
+
+  it("defaults to 60px (3 × 20px) before any resize", () => {
+    const { textarea } = createComposerTextarea(baseConfig);
+    expect(textarea.style.maxHeight).toBe("60px");
+    expect(textarea.style.overflowY).toBe("auto");
+  });
+
+  it("falls back to 60px when the line height is `normal`", () => {
+    const { textarea, attachAutoResize } = createComposerTextarea(baseConfig);
+    textarea.style.lineHeight = "normal";
+    document.body.appendChild(textarea);
+    attachAutoResize();
+    Object.defineProperty(textarea, "scrollHeight", { configurable: true, value: 10000 });
+    textarea.dispatchEvent(new Event("input"));
+    expect(textarea.style.height).toBe("60px");
+    document.body.removeChild(textarea);
+  });
+
+  it("falls back to 60px for unitless line heights and detached nodes", () => {
+    const unitless = createComposerTextarea(baseConfig);
+    unitless.textarea.style.lineHeight = "1.5";
+    document.body.appendChild(unitless.textarea);
+    unitless.attachAutoResize();
+    Object.defineProperty(unitless.textarea, "scrollHeight", { configurable: true, value: 10000 });
+    unitless.textarea.dispatchEvent(new Event("input"));
+    expect(unitless.textarea.style.height).toBe("60px");
+    document.body.removeChild(unitless.textarea);
+
+    // Never appended: getComputedStyle still must not throw or produce NaN.
+    const detached = createComposerTextarea(baseConfig);
+    detached.attachAutoResize();
+    Object.defineProperty(detached.textarea, "scrollHeight", { configurable: true, value: 10000 });
+    detached.textarea.dispatchEvent(new Event("input"));
+    expect(detached.textarea.style.height).toBe("60px");
+  });
 });
 
 describe("createSendButton", () => {
@@ -95,10 +148,12 @@ describe("createSendButton", () => {
     expect(s.borderWidth).toBe("2px");
     expect(s.borderStyle).toBe("solid");
     expect(s.borderColor).toBe("rgb(7, 8, 9)");
-    expect(s.paddingLeft).toBe("6px");
-    expect(s.paddingRight).toBe("6px");
-    expect(s.paddingTop).toBe("4px");
-    expect(s.paddingBottom).toBe("4px");
+    // Icon mode zeroes padding even when configured: the glyph is drawn at
+    // the button size, so padding would crush it.
+    expect(s.paddingLeft).toBe("0px");
+    expect(s.paddingRight).toBe("0px");
+    expect(s.paddingTop).toBe("0px");
+    expect(s.paddingBottom).toBe("0px");
     // An explicit backgroundColor means the fallback class is not added.
     expect(send.button.classList.contains("persona-bg-persona-primary")).toBe(false);
   });
@@ -140,6 +195,52 @@ describe("createSendButton", () => {
       expect(iconCount(send.button)).toBe(1);
     });
 
+    it("zeroes padding so configured padding cannot crush the glyph", () => {
+      const send = createSendButton({
+        ...baseConfig,
+        sendButton: {
+          useIcon: true,
+          iconName: "send",
+          size: "40px",
+          paddingX: "12px",
+          paddingY: "10px",
+        },
+      });
+      expect(send.button.style.paddingLeft).toBe("0px");
+      expect(send.button.style.paddingTop).toBe("0px");
+    });
+
+    it("draws the glyph at half the button by default and honors iconSize", () => {
+      const send = createSendButton({
+        ...baseConfig,
+        sendButton: { useIcon: true, iconName: "send", size: "32px" },
+      });
+      expect(send.button.querySelector("svg")?.getAttribute("width")).toBe("16");
+
+      const sized = createSendButton({
+        ...baseConfig,
+        sendButton: {
+          useIcon: true,
+          iconName: "send",
+          size: "32px",
+          iconSize: "26px",
+          iconStrokeWidth: 2.5,
+        },
+      });
+      const svg = sized.button.querySelector("svg");
+      expect(svg?.getAttribute("width")).toBe("26");
+      expect(svg?.getAttribute("stroke-width")).toBe("2.5");
+    });
+
+    it("keeps configured padding in text mode", () => {
+      const send = createSendButton({
+        ...baseConfig,
+        sendButton: { useIcon: false, paddingX: "12px", paddingY: "10px" },
+      });
+      expect(send.button.style.paddingLeft).toBe("12px");
+      expect(send.button.style.paddingTop).toBe("10px");
+    });
+
     it("does not stack a stale icon when an external re-render swapped the live icon node", () => {
       const send = createSendButton(iconConfig);
       // Simulate a DOM morph/re-render (e.g. a host calling controller.update())

package/src/components/composer-parts.ts

@@ -32,26 +32,54 @@ export const createComposerTextarea = (config?: AgentWidgetConfig): ComposerText
   textarea.setAttribute("data-persona-composer-input", "");
   textarea.placeholder = config?.copy?.inputPlaceholder ?? "Type your message…";
   textarea.className =
-    "persona-w-full persona-min-h-[24px] persona-resize-none persona-border-none persona-bg-transparent persona-text-sm persona-text-persona-primary focus:persona-outline-none focus:persona-border-none persona-composer-textarea";
+    "persona-w-full persona-min-h-[24px] persona-resize-none persona-border-none persona-bg-transparent persona-text-sm persona-text-persona-text focus:persona-outline-none focus:persona-border-none persona-composer-textarea";
   textarea.rows = 1;
 
   textarea.style.fontFamily =
     'var(--persona-input-font-family, var(--persona-font-family, -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif))';
   textarea.style.fontWeight = "var(--persona-input-font-weight, var(--persona-font-weight, 400))";
 
-  // Auto-resize: expand up to 3 lines for the full composer (line-height ~20px
-  // for text-sm). The pill composer overrides this maxHeight after construction
-  // (allowing more growth in expanded mode), and the closure below honors
-  // whatever maxHeight is set at the time of the input event.
+  // Auto-resize: expand up to 3 lines for the full composer. The pill composer
+  // overrides this maxHeight after construction (allowing more growth in
+  // expanded mode), and the closure below honors whatever maxHeight is set at
+  // the time of the input event.
   const defaultMaxLines = 3;
-  const lineHeight = 20;
-  textarea.style.maxHeight = `${defaultMaxLines * lineHeight}px`;
+  // Used only when the rendered line height can't be resolved (detached node,
+  // jsdom, `normal`); matches the `persona-text-sm` / composer default.
+  const fallbackLineHeight = 20;
+
+  // `theme.components.composer.lineHeight` (--persona-composer-line-height) can
+  // change the rendered line height, so 3 lines is only correct when measured
+  // from the live element. Read lazily: at construction the textarea is usually
+  // still detached and getComputedStyle would report nothing useful.
+  const readLineHeight = (): number => {
+    const view = textarea.ownerDocument?.defaultView;
+    if (!view?.getComputedStyle) return fallbackLineHeight;
+    // Only px values are meaningful here: `normal` and unitless ratios aren't
+    // line box heights we can multiply.
+    const computed = view.getComputedStyle(textarea).lineHeight;
+    if (!computed || !computed.trim().endsWith("px")) return fallbackLineHeight;
+    const parsed = parseFloat(computed);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallbackLineHeight;
+  };
+
+  // Tracks the last maxHeight this module wrote, so a caller's post-construction
+  // override is distinguishable from our own default and always wins.
+  let managedMaxHeight = `${defaultMaxLines * fallbackLineHeight}px`;
+  textarea.style.maxHeight = managedMaxHeight;
   textarea.style.overflowY = "auto";
 
   // Read maxHeight at event time so callers can change it after construction.
   const readMaxHeight = (): number => {
-    const parsed = parseFloat(textarea.style.maxHeight);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultMaxLines * lineHeight;
+    const current = textarea.style.maxHeight;
+    if (current !== managedMaxHeight) {
+      const overridden = parseFloat(current);
+      if (Number.isFinite(overridden) && overridden > 0) return overridden;
+    }
+    const derived = defaultMaxLines * readLineHeight();
+    managedMaxHeight = `${derived}px`;
+    textarea.style.maxHeight = managedMaxHeight;
+    return derived;
   };
 
   const attachAutoResize = () => {
@@ -142,10 +170,13 @@ export const createSendButton = (config?: AgentWidgetConfig): SendButtonParts =>
       borderWidth: sendButtonConfig.borderWidth || undefined,
       borderStyle: sendButtonConfig.borderWidth ? "solid" : undefined,
       borderColor: sendButtonConfig.borderColor || undefined,
-      paddingLeft: sendButtonConfig.paddingX || undefined,
-      paddingRight: sendButtonConfig.paddingX || undefined,
-      paddingTop: sendButtonConfig.paddingY || undefined,
-      paddingBottom: sendButtonConfig.paddingY || undefined,
+      // Padding is text-mode-only: icon mode is a fixed `size` box with the
+      // glyph drawn at that size, so padding just crushes the SVG (the
+      // always-present defaults squeezed a 40px glyph into 16x20).
+      paddingLeft: useIcon ? "0" : sendButtonConfig.paddingX || undefined,
+      paddingRight: useIcon ? "0" : sendButtonConfig.paddingX || undefined,
+      paddingTop: useIcon ? "0" : sendButtonConfig.paddingY || undefined,
+      paddingBottom: useIcon ? "0" : sendButtonConfig.paddingY || undefined,
     },
   });
 
@@ -154,11 +185,18 @@ export const createSendButton = (config?: AgentWidgetConfig): SendButtonParts =>
   let stopIcon: SVGElement | null = null;
 
   if (useIcon) {
-    const iconSize = parseFloat(buttonSize) || 24;
+    // Default glyph box is half the button, the closest clean ratio to the
+    // pre-fix live rendering (a 40px glyph crushed to a ~16px content box).
+    // Dense glyphs like the default "send" plane fill most of their viewBox;
+    // sparse ones (arrow-up) may want a larger explicit `iconSize`.
+    const iconSize =
+      parseFloat(sendButtonConfig.iconSize ?? "") ||
+      Math.round((parseFloat(buttonSize) || 24) * 0.5);
+    const iconStroke = sendButtonConfig.iconStrokeWidth ?? 2;
     const iconColor = textColor?.trim() || "currentColor";
 
     if (iconName) {
-      sendIcon = renderLucideIcon(iconName, iconSize, iconColor, 2);
+      sendIcon = renderLucideIcon(iconName, iconSize, iconColor, iconStroke);
       if (sendIcon) {
         button.appendChild(sendIcon);
       } else {
@@ -168,7 +206,7 @@ export const createSendButton = (config?: AgentWidgetConfig): SendButtonParts =>
       button.textContent = iconText;
     }
 
-    stopIcon = renderLucideIcon(stopIconName, iconSize, iconColor, 2);
+    stopIcon = renderLucideIcon(stopIconName, iconSize, iconColor, iconStroke);
   } else {
     button.textContent = sendLabel;
   }

package/src/components/message-bubble.test.ts

@@ -276,7 +276,7 @@ describe("createStandardBubble", () => {
     expect(userBubble.classList.contains("persona-bg-persona-accent")).toBe(true);
     expect(userBubble.classList.contains("persona-rounded-lg")).toBe(true);
     expect(userBubble.classList.contains("persona-px-3")).toBe(true);
-    expect(assistantBubble.classList.contains("persona-bg-persona-surface")).toBe(
+    expect(assistantBubble.classList.contains("persona-bg-persona-container")).toBe(
       true
     );
     expect(assistantBubble.classList.contains("persona-rounded-lg")).toBe(true);
@@ -302,6 +302,12 @@ describe("createStandardBubble", () => {
 
     expect(userMessage.style.backgroundColor).toBe("transparent");
     expect(assistantMessage.style.backgroundColor).toBe("transparent");
+    expect(assistantMessage.style.color).toBe(
+      "var(--persona-message-assistant-text, var(--persona-text))"
+    );
+    expect(assistantMessage.classList.contains("persona-text-persona-text")).toBe(
+      true
+    );
     expect(userMessage.classList.contains("persona-px-3")).toBe(false);
     expect(assistantMessage.classList.contains("persona-px-3")).toBe(false);
   });

package/src/components/message-bubble.ts

@@ -649,7 +649,7 @@ const createTimestamp = (
 /**
  * Get bubble classes based on layout preset
  */
-const getBubbleClasses = (
+export const getBubbleClasses = (
   role: "user" | "assistant" | "system",
   layout: AgentWidgetMessageLayoutConfig["layout"] = "bubble"
 ): string[] => {
@@ -668,7 +668,7 @@ const getBubbleClasses = (
       } else {
         baseClasses.push(
           "persona-message-assistant-bubble",
-          "persona-text-persona-primary",
+          "persona-text-persona-text",
           "persona-py-2"
         );
       }
@@ -693,8 +693,8 @@ const getBubbleClasses = (
       } else {
         baseClasses.push(
           "persona-message-assistant-bubble",
-          "persona-bg-persona-surface",
-          "persona-text-persona-primary",
+          "persona-bg-persona-container",
+          "persona-text-persona-text",
           "persona-px-3",
           "persona-py-2",
           "persona-rounded-lg"
@@ -723,10 +723,10 @@ const getBubbleClasses = (
       } else {
         baseClasses.push(
           "persona-message-assistant-bubble",
-          "persona-bg-persona-surface",
+          "persona-bg-persona-container",
           "persona-border",
           "persona-border-persona-message-border",
-          "persona-text-persona-primary",
+          "persona-text-persona-text",
           "persona-px-5",
           "persona-py-3"
         );
@@ -879,12 +879,15 @@ export const createStandardBubble = (
   // Apply component-level color overrides via CSS variables
   if (layout === "flat") {
     bubble.style.backgroundColor = "transparent";
-    bubble.style.color = "var(--persona-primary, var(--persona-text))";
+    bubble.style.color =
+      message.role === "user"
+        ? "var(--persona-primary, var(--persona-text))"
+        : "var(--persona-message-assistant-text, var(--persona-text))";
   } else if (message.role === "user") {
     bubble.style.backgroundColor = 'var(--persona-message-user-bg, var(--persona-accent))';
     bubble.style.color = 'var(--persona-message-user-text, white)';
   } else if (message.role === "assistant") {
-    bubble.style.backgroundColor = 'var(--persona-message-assistant-bg, var(--persona-surface))';
+    bubble.style.backgroundColor = 'var(--persona-message-assistant-bg, var(--persona-container))';
     bubble.style.color = 'var(--persona-message-assistant-text, var(--persona-text))';
   }
 

package/src/components/messages.ts

@@ -9,7 +9,10 @@ import {
   isAskUserQuestionMessage,
   removeAskUserQuestionSheet,
 } from "./ask-user-question-bubble";
-import { isSuggestRepliesMessage } from "../suggest-replies-tool";
+import {
+  isSuggestRepliesMessage,
+  resolveFollowUpsFeature,
+} from "../suggest-replies-tool";
 
 export const renderMessages = (
   container: HTMLElement,
@@ -43,7 +46,7 @@ export const renderMessages = (
       return;
     } else if (
       isSuggestRepliesMessage(message) &&
-      config?.features?.suggestReplies?.enabled !== false
+      resolveFollowUpsFeature(config).enabled
     ) {
       // No transcript bubble: the chips above the composer are the only UI.
       // When the feature is disabled the message falls through to the generic

package/src/components/panel.ts

@@ -1,6 +1,7 @@
 import { createElement, createNode } from "../utils/dom";
 import { DEFAULT_FLOATING_LAUNCHER_WIDTH } from "../defaults";
-import { AgentWidgetConfig } from "../types";
+import { AgentWidgetConfig, AgentWidgetSuggestionSurface } from "../types";
+import { suggestionSurfaceAttr } from "./suggestions";
 import { positionMap } from "../utils/positioning";
 import { isComposerBarMountMode, isDockedMountMode } from "../utils/dock";
 import { DEFAULT_OVERLAY_Z_INDEX } from "../utils/constants";
@@ -132,6 +133,10 @@ export interface PanelElements {
   container: HTMLElement;
   body: HTMLElement;
   messagesWrapper: HTMLElement;
+  /** Starter prompts rendered inside the welcome card. */
+  starterSuggestions: HTMLElement;
+  /** Follow-up suggestions rendered after the transcript. */
+  transcriptSuggestions: HTMLElement;
   /**
    * Absolute-positioned slot above the composer footer. Interactive sheets
    * (e.g. the answer-pill sheet for the ask_user_question tool) mount here
@@ -178,6 +183,17 @@ export interface PanelElements {
   peekTextNode?: HTMLElement;
 }
 
+const createSuggestionHost = (
+  surface: AgentWidgetSuggestionSurface
+): HTMLElement => {
+  const host = createNode("div", {
+    className: "persona-suggestions",
+    attrs: { "data-persona-suggestions": suggestionSurfaceAttr(surface) },
+  });
+  host.hidden = true;
+  return host;
+};
+
 /**
  * Composer-bar panel: minimal close-only header (× in the top-right of the
  * chat chrome). The pill (`footer`) and `peekBanner` are NOT children of
@@ -276,6 +292,7 @@ const buildComposerBarPanel = (
       config?.copy?.welcomeSubtitle ??
       "Ask anything about your account or products.",
   });
+  const starterSuggestions = createSuggestionHost("starter");
   const introCard = createNode(
     "div",
     {
@@ -287,13 +304,15 @@ const buildComposerBarPanel = (
       },
     },
     introTitle,
-    introSubtitle
+    introSubtitle,
+    starterSuggestions
   );
 
   const messagesWrapper = createElement(
     "div",
     "persona-flex persona-flex-col persona-gap-3"
   );
+  const transcriptSuggestions = createSuggestionHost("followUp");
   const contentMaxWidth = config?.layout?.contentMaxWidth;
   if (contentMaxWidth) {
     messagesWrapper.style.maxWidth = contentMaxWidth;
@@ -308,7 +327,7 @@ const buildComposerBarPanel = (
     body.classList.remove("persona-gap-6");
     body.classList.add("persona-gap-3");
   }
-  body.append(introCard, messagesWrapper);
+  body.append(introCard, messagesWrapper, transcriptSuggestions);
 
   // Composer overlay (interactive sheets like ask_user_question slide up here).
   // Anchored to the bottom of the container (which is `position: relative`),
@@ -338,6 +357,8 @@ const buildComposerBarPanel = (
     container,
     body,
     messagesWrapper,
+    starterSuggestions,
+    transcriptSuggestions,
     composerOverlay,
     suggestions: composerElements.suggestions,
     textarea: composerElements.textarea,
@@ -413,6 +434,7 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
       config?.copy?.welcomeSubtitle ??
       "Ask anything about your account or products.",
   });
+  const starterSuggestions = createSuggestionHost("starter");
   // Background and box-shadow flow through the themable `components.introCard`
   // tokens (--persona-intro-card-bg / --persona-intro-card-shadow); both
   // default to flat (transparent / none). Docked mode always stays flat,
@@ -430,13 +452,15 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
       },
     },
     introTitle,
-    introSubtitle
+    introSubtitle,
+    starterSuggestions
   );
 
   const messagesWrapper = createElement(
     "div",
     "persona-flex persona-flex-col persona-gap-3"
   );
+  const transcriptSuggestions = createSuggestionHost("followUp");
 
   const contentMaxWidth = config?.layout?.contentMaxWidth;
   if (contentMaxWidth) {
@@ -452,7 +476,7 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     body.classList.remove("persona-gap-6");
     body.classList.add("persona-gap-3");
   }
-  body.append(introCard, messagesWrapper);
+  body.append(introCard, messagesWrapper, transcriptSuggestions);
 
   // composer-bar mode early-returned above with its own pill builder; this
   // path always uses the standard column-stacked composer card.
@@ -500,6 +524,8 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     container,
     body,
     messagesWrapper,
+    starterSuggestions,
+    transcriptSuggestions,
     composerOverlay,
     suggestions: composerElements.suggestions,
     textarea: composerElements.textarea,