@runtypelabs/persona 4.14.0 → 4.15.0

package/src/suggest-replies-tool.ts

@@ -2,14 +2,13 @@
  * Built-in `suggest_replies` client tool.
  *
  * The widget can advertise this tool to the agent on every dispatch via
- * `clientTools[]` (set `features.suggestReplies.expose: true`): the same
+ * `clientTools[]` (set `suggestions.followUps.expose: true`): the same
  * wire surface as `ask_user_question` and WebMCP page tools. When the model
- * calls it, the execution pauses with a `step_await`
- * (`awaitReason: "local_tool_required"`); unlike `ask_user_question`, the
- * widget resolves it FIRE-AND-FORGET: it renders the suggestions as tappable
- * chips above the composer and immediately resumes the execution with a
- * canned "shown" result, so the agent's turn completes without waiting on the
- * user. Tapping a chip sends its text verbatim as the user's next message.
+ * calls it, the execution pauses with a `step_await` (a local-tool pause
+ * carries no `awaitReason`; that discriminator is internal). Unlike
+ * `ask_user_question`, the widget resolves it FIRE-AND-FORGET: it renders the
+ * configured follow-up surface and immediately resumes the execution with a
+ * canned "shown" result, so the turn completes without waiting on the user.
  *
  * Chip visibility is DERIVED state, not imperative show/hide: the chips of
  * the last `suggest_replies` tool message with no user message after it are
@@ -21,6 +20,7 @@
 import type {
   AgentWidgetConfig,
   AgentWidgetMessage,
+  AgentWidgetSuggestion,
   ClientToolDefinition,
 } from "./types";
 
@@ -30,9 +30,10 @@ export const SUGGEST_REPLIES_TOOL_NAME = "suggest_replies";
 export const SUGGEST_REPLIES_MAX = 4;
 
 /**
- * JSON Schema for the tool's parameters. Mirrors what
- * {@link parseSuggestRepliesPayload} hydrates the chips from, so the schema
- * the model is held to and the shape the renderer expects can never drift.
+ * JSON Schema for the tool's parameters. The model owns semantics only: id,
+ * icon, behavior, and emphasis are presentation, and hosts set them with the
+ * `transformSuggestions` plugin hook. A single object type is used because
+ * strict structured-output modes reject or flatten `oneOf`.
  */
 export const SUGGEST_REPLIES_PARAMETERS_SCHEMA = {
   type: "object",
@@ -43,7 +44,16 @@ export const SUGGEST_REPLIES_PARAMETERS_SCHEMA = {
       maxItems: SUGGEST_REPLIES_MAX,
       description:
         "1-4 short, distinct follow-up replies, phrased in the user's voice.",
-      items: { type: "string", minLength: 1, maxLength: 60 },
+      items: {
+        type: "object",
+        properties: {
+          label: { type: "string", minLength: 1, maxLength: 80 },
+          prompt: { type: "string", minLength: 1, maxLength: 500 },
+          description: { type: "string", minLength: 1, maxLength: 160 },
+        },
+        required: ["label"],
+        additionalProperties: false,
+      },
     },
   },
   required: ["suggestions"],
@@ -52,7 +62,7 @@ export const SUGGEST_REPLIES_PARAMETERS_SCHEMA = {
 
 /**
  * The `ClientToolDefinition` shipped on `dispatch.clientTools[]` when
- * `features.suggestReplies.expose` is on. Exported so integrators who prefer
+ * `suggestions.followUps.expose` is on. Exported so integrators who prefer
  * declaring the tool server-side (a flow's `runtimeTools`) can reuse the same
  * description and schema instead of hand-writing them.
  */
@@ -60,12 +70,15 @@ export const SUGGEST_REPLIES_CLIENT_TOOL: ClientToolDefinition = {
   name: SUGGEST_REPLIES_TOOL_NAME,
   description:
     "Offer the user tappable quick-reply suggestions for their next message. " +
-    "Call at most once per turn, as the LAST action after your reply text is " +
-    "complete. Each suggestion is sent verbatim as the user's next message, " +
-    'so phrase suggestions in the user\'s voice (e.g. "Tell me more about ' +
-    'pricing"). Keep them short and distinct. The result only confirms the ' +
-    "suggestions were shown: do not add further commentary after calling " +
-    "this tool; end your turn.",
+    "Call at most once per turn, as the last action after your reply text is " +
+    "complete. Give each suggestion a `label` with the short visible text, an " +
+    "optional `prompt` with the fuller text placed as the user's message " +
+    "(defaults to the label), and an optional `description` with one line of " +
+    "supporting copy. Suggestions are sent as the user's next message, so " +
+    'phrase prompts in the user\'s voice (e.g. "Tell me more about pricing"). ' +
+    "Keep them short and distinct. The result only confirms the suggestions " +
+    "were shown: do not add further commentary after calling this tool; end " +
+    "your turn.",
   parametersSchema: SUGGEST_REPLIES_PARAMETERS_SCHEMA,
   origin: "sdk",
   annotations: { readOnlyHint: true },
@@ -90,11 +103,15 @@ export const isSuggestRepliesMessage = (
   message.toolCall?.name === SUGGEST_REPLIES_TOOL_NAME;
 
 /**
- * Tolerant parse of a `suggest_replies` tool call's args into chip labels:
- * accepts a JSON string or object, coerces items to trimmed strings, drops
- * empties, and truncates past the renderer cap with a console warning.
+ * Tolerant parse of a `suggest_replies` tool call's args into suggestion
+ * items. Plain strings stay strings for older flows that emit
+ * `suggestions: string[]`; objects keep only label, prompt, and description,
+ * so a model that ignores `additionalProperties` cannot set presentation.
+ * Hosts add id, icon, behavior, and emphasis via `transformSuggestions`.
  */
-export const parseSuggestRepliesPayload = (args: unknown): string[] => {
+export const parseSuggestRepliesPayload = (
+  args: unknown
+): AgentWidgetSuggestion[] => {
   let parsed: unknown = args;
   if (typeof parsed === "string") {
     try {
@@ -106,17 +123,32 @@ export const parseSuggestRepliesPayload = (args: unknown): string[] => {
   const raw = (parsed as { suggestions?: unknown } | null | undefined)
     ?.suggestions;
   if (!Array.isArray(raw)) return [];
-  const chips = raw
-    .filter((item): item is string => typeof item === "string")
-    .map((item) => item.trim())
-    .filter((item) => item.length > 0);
-  if (chips.length > SUGGEST_REPLIES_MAX) {
+  const suggestions = raw.flatMap<AgentWidgetSuggestion>((item) => {
+    if (typeof item === "string") {
+      const value = item.trim();
+      return value ? [value] : [];
+    }
+    if (!item || typeof item !== "object") return [];
+    const value = item as Record<string, unknown>;
+    if (typeof value.label !== "string" || !value.label.trim()) return [];
+    const suggestion: Exclude<AgentWidgetSuggestion, string> = {
+      label: value.label.trim(),
+    };
+    if (typeof value.prompt === "string" && value.prompt.trim()) {
+      suggestion.prompt = value.prompt.trim();
+    }
+    if (typeof value.description === "string" && value.description.trim()) {
+      suggestion.description = value.description.trim();
+    }
+    return [suggestion];
+  });
+  if (suggestions.length > SUGGEST_REPLIES_MAX) {
     console.warn(
-      `[persona] suggest_replies: ${chips.length} suggestions exceeds the cap of ${SUGGEST_REPLIES_MAX}; extra suggestions dropped.`,
+      `[persona] suggest_replies: ${suggestions.length} suggestions exceeds the cap of ${SUGGEST_REPLIES_MAX}; extra suggestions dropped.`,
     );
-    return chips.slice(0, SUGGEST_REPLIES_MAX);
+    return suggestions.slice(0, SUGGEST_REPLIES_MAX);
   }
-  return chips;
+  return suggestions;
 };
 
 /**
@@ -127,7 +159,7 @@ export const parseSuggestRepliesPayload = (args: unknown): string[] => {
  */
 export const latestAgentSuggestions = (
   messages: AgentWidgetMessage[],
-): string[] | null => {
+): AgentWidgetSuggestion[] | null => {
   for (let i = messages.length - 1; i >= 0; i--) {
     const message = messages[i];
     if (message.role === "user") return null;
@@ -138,15 +170,59 @@ export const latestAgentSuggestions = (
   return null;
 };
 
+export type ResolvedFollowUpsFeature = {
+  /** Widget renders follow-up chips and auto-resumes the tool call. */
+  enabled: boolean;
+  /** Tool ships on `dispatch.clientTools[]`. */
+  expose: boolean;
+};
+
+// Keyed on the conflict itself, not the config object: `controller.update()`
+// rebuilds the config on every call, so an object-keyed dedupe re-warns
+// forever. Trade-off: two widgets with the identical conflict warn once total
+// per page load.
+const conflictWarnings = new Set<string>();
+
+/** Always warns, debug or not: a config conflict is a developer error. */
+const warnConflict = (
+  key: "enabled" | "expose",
+  legacyValue: boolean,
+  newValue: boolean,
+): void => {
+  const signature = `${key}:${legacyValue}:${newValue}`;
+  if (conflictWarnings.has(signature)) return;
+  conflictWarnings.add(signature);
+  console.warn(
+    `[persona] suggestions.followUps.${key} and features.suggestReplies.${key} disagree; suggestions.followUps.${key} wins.`,
+  );
+};
+
 /**
- * Gate for advertising the tool: `expose` opts it into the agent's catalog,
- * and `enabled !== false` guarantees the widget will actually auto-resolve
- * and render chips for it: exposing the tool with the feature disabled
- * would park the execution on a generic tool bubble with no resume coming.
+ * Single source of truth for the follow-ups capability flags. Resolution is
+ * per key so a `features.suggestReplies` embed that adds presentation-only
+ * `suggestions.followUps` keys is not silently re-enabled. `expose` is forced
+ * off when `enabled` resolves false: advertising the tool without the widget
+ * auto-resolving it parks the execution on a generic tool bubble.
  */
-export const shouldExposeSuggestReplies = (
+export const resolveFollowUpsFeature = (
   config: AgentWidgetConfig | undefined,
-): boolean => {
-  const feature = config?.features?.suggestReplies;
-  return feature?.expose === true && feature.enabled !== false;
+): ResolvedFollowUpsFeature => {
+  const followUps = config?.suggestions?.followUps;
+  const legacy = config?.features?.suggestReplies;
+  const warnIfConflicting = (key: "enabled" | "expose"): void => {
+    const newValue = followUps?.[key];
+    const legacyValue = legacy?.[key];
+    if (newValue === undefined || legacyValue === undefined) return;
+    if (newValue === legacyValue) return;
+    warnConflict(key, legacyValue, newValue);
+  };
+  if (config) {
+    warnIfConflicting("enabled");
+    warnIfConflicting("expose");
+  }
+  const enabled = followUps?.enabled ?? legacy?.enabled ?? true;
+  const expose = enabled
+    ? followUps?.expose ?? legacy?.expose ?? false
+    : false;
+  return { enabled, expose };
 };

package/src/theme-editor/preview-utils.test.ts

@@ -9,6 +9,40 @@ import {
 } from "./preview-utils";
 
 describe("theme editor preview demo data", () => {
+  it("keeps the home scene in a true pre-conversation state", () => {
+    const config = buildPreviewConfig({ scene: "home" });
+
+    expect(config.initialMessages).toEqual([]);
+    expect(config.suggestionChips?.length).toBeGreaterThan(0);
+  });
+
+  it("seeds rich agent suggestions in the follow-ups scene", () => {
+    const config = buildPreviewConfig({ scene: "follow-ups" });
+    const messages = config.initialMessages ?? [];
+    const suggestionMessage = messages.find(
+      (message) =>
+        message.variant === "tool" &&
+        message.toolCall?.name === "suggest_replies",
+    );
+    const suggestions = (
+      suggestionMessage?.toolCall?.args as
+        | { suggestions?: Array<Record<string, unknown>> }
+        | undefined
+    )?.suggestions;
+
+    expect(messages.some((message) => message.role === "user")).toBe(true);
+    expect(suggestionMessage?.toolCall?.status).toBe("complete");
+    expect(suggestions).toHaveLength(4);
+    expect(suggestions?.[0]).toEqual(
+      expect.objectContaining({
+        label: "Show me an implementation",
+        description: expect.any(String),
+        icon: "code-2",
+        emphasis: "primary",
+      }),
+    );
+  });
+
   it("seeds tool call preview messages when advanced tool display modes are enabled", () => {
     const config = buildPreviewConfig({
       scene: "conversation",

package/src/theme-editor/preview-utils.ts

@@ -195,7 +195,12 @@ export function buildSrcdoc(
 
 // ─── Preview Messages ───────────────────────────────────────────
 
-export type PreviewScene = 'home' | 'conversation' | 'minimized' | 'artifact';
+export type PreviewScene =
+  | 'home'
+  | 'conversation'
+  | 'follow-ups'
+  | 'minimized'
+  | 'artifact';
 
 export type PreviewTranscriptEntryPreset =
   | 'user-message'
@@ -543,8 +548,78 @@ export function createPreviewMessages(
   config?: Partial<AgentWidgetConfig>,
   appendedMessages: AgentWidgetMessage[] = []
 ): AgentWidgetMessage[] {
+  if (scene === 'follow-ups') {
+    const now = Date.now();
+    return [
+      {
+        id: 'preview-follow-up-user',
+        role: 'user',
+        content: 'What can Persona help me build?',
+        createdAt: new Date(now - 120000).toISOString(),
+      },
+      {
+        id: 'preview-follow-up-assistant',
+        role: 'assistant',
+        content:
+          'Persona gives you a themeable streaming chat interface with flexible integrations and interaction patterns. Where would you like to go next?',
+        createdAt: new Date(now - 60000).toISOString(),
+      },
+      {
+        id: 'preview-follow-up-suggestions',
+        role: 'assistant',
+        content: '',
+        createdAt: new Date(now - 59000).toISOString(),
+        streaming: false,
+        variant: 'tool',
+        toolCall: {
+          id: 'preview-follow-up-suggestions',
+          name: 'suggest_replies',
+          status: 'complete',
+          args: {
+            suggestions: [
+              {
+                id: 'preview-implementation',
+                label: 'Show me an implementation',
+                prompt: 'Show me a practical implementation',
+                description: 'See a complete integration example',
+                icon: 'code-2',
+                emphasis: 'primary',
+              },
+              {
+                id: 'preview-theming',
+                label: 'Explore theming',
+                prompt: 'Tell me how theming works',
+                description: 'Customize colors, type, and component styles',
+                icon: 'palette',
+              },
+              {
+                id: 'preview-security',
+                label: 'Review security',
+                prompt: 'Explain the security model',
+                description: 'Learn about isolation and safe rendering',
+                icon: 'shield-check',
+              },
+              {
+                id: 'preview-support',
+                label: 'Talk to support',
+                prompt: 'Help me contact support',
+                description: 'Get help choosing the right approach',
+                icon: 'messages-square',
+              },
+            ],
+          },
+          chunks: [],
+        },
+      },
+      ...appendedMessages,
+    ];
+  }
   if (scene === 'home') {
-    return [{ id: 'preview-home-1', role: 'assistant', content: 'Hi there! How can we help today?', createdAt: new Date().toISOString() }];
+    // Home is the pre-conversation state: welcome copy + starter suggestions
+    // already provide the greeting and entry points. Seeding an assistant
+    // bubble here creates a duplicate greeting that the default runtime never
+    // enters unless a host explicitly configures its own initialMessages.
+    return [];
   }
   if (scene === 'minimized') {
     return [{ id: 'preview-min-1', role: 'assistant', content: 'We are here whenever you are ready.', createdAt: new Date().toISOString() }];

package/src/theme-editor/sections.test.ts

@@ -60,6 +60,39 @@ describe("theme editor scroll-to-bottom controls", () => {
     expect(fieldPaths).toContain("theme.components.scrollToBottom.iconSize");
   });
 
+  it("exposes suggestion behavior and component token controls", () => {
+    const suggestions = CONFIGURE_SECTIONS.find(
+      (section) => section.id === "suggestions"
+    );
+    const configPaths =
+      suggestions?.fields.map((field) => field.path) ?? [];
+    expect(configPaths).toEqual(
+      expect.arrayContaining([
+        "suggestions.starters.variant",
+        "suggestions.starters.placement",
+        "suggestions.starters.behavior",
+        "suggestions.followUps.variant",
+        "suggestions.followUps.placement",
+        "suggestions.followUps.behavior",
+        "suggestions.followUps.overflow",
+      ])
+    );
+
+    const componentPaths = COMPONENTS_SECTIONS.flatMap((section) =>
+      section.fields.map((field) => field.path)
+    );
+    expect(componentPaths).toEqual(
+      expect.arrayContaining([
+        "theme.components.suggestion.chip.background",
+        "theme.components.suggestion.chip.hoverBackground",
+        "theme.components.suggestion.chip.focusRing",
+        "theme.components.suggestion.card.background",
+        "theme.components.suggestion.card.shadow",
+        "theme.components.suggestion.list.background",
+      ])
+    );
+  });
+
   it("exposes a shadow control for every themeable component", () => {
     const fieldPaths = COMPONENTS_SECTIONS.flatMap((section) => section.fields.map((field) => field.path));
 

package/src/theme-editor/sections.ts

@@ -369,6 +369,18 @@ const inputShapeSectionDef: SectionDef = {
   ],
 };
 
+const composerSpacingSectionDef: SectionDef = {
+  id: 'comp-composer-spacing',
+  title: 'Composer Spacing',
+  collapsed: true,
+  fields: [
+    { id: 'composer-padding', label: 'Padding', type: 'text', path: 'theme.components.composer.padding', defaultValue: '0.75rem 1rem' },
+    { id: 'composer-gap', label: 'Row Gap', description: 'Space between the textarea row and the actions row', type: 'text', path: 'theme.components.composer.gap', defaultValue: '0.5rem' },
+    { id: 'composer-font-size', label: 'Font Size', type: 'text', path: 'theme.components.composer.fontSize', defaultValue: '0.875rem' },
+    { id: 'composer-line-height', label: 'Line Height', type: 'text', path: 'theme.components.composer.lineHeight', defaultValue: '1.25rem' },
+  ],
+};
+
 const buttonShapeSectionDef: SectionDef = {
   id: 'comp-button-shape',
   title: 'Button Shape',
@@ -466,6 +478,32 @@ const scrollToBottomSectionDef: SectionDef = {
   ],
 };
 
+const suggestionStyleSectionDef: SectionDef = {
+  id: 'comp-suggestions',
+  title: 'Suggestions',
+  description: 'Style starter cards, follow-up chips, and list rows.',
+  collapsed: true,
+  fields: [
+    { id: 'suggestion-chip-bg', label: 'Chip Background', type: 'token-ref', path: 'theme.components.suggestion.chip.background', defaultValue: 'semantic.colors.surface', tokenRef: { tokenType: 'color' } },
+    { id: 'suggestion-chip-fg', label: 'Chip Text', type: 'token-ref', path: 'theme.components.suggestion.chip.foreground', defaultValue: 'semantic.colors.text', tokenRef: { tokenType: 'color' } },
+    { id: 'suggestion-chip-border', label: 'Chip Border', type: 'token-ref', path: 'theme.components.suggestion.chip.border', defaultValue: 'semantic.colors.border', tokenRef: { tokenType: 'color' } },
+    { id: 'suggestion-chip-hover', label: 'Chip Hover', type: 'token-ref', path: 'theme.components.suggestion.chip.hoverBackground', defaultValue: 'palette.colors.gray.100', tokenRef: { tokenType: 'color' } },
+    { id: 'suggestion-chip-focus', label: 'Chip Focus Ring', type: 'token-ref', path: 'theme.components.suggestion.chip.focusRing', defaultValue: 'semantic.colors.interactive.focus', tokenRef: { tokenType: 'color' } },
+    { id: 'suggestion-card-bg', label: 'Card Background', type: 'token-ref', path: 'theme.components.suggestion.card.background', defaultValue: 'semantic.colors.surface', tokenRef: { tokenType: 'color' } },
+    { id: 'suggestion-card-fg', label: 'Card Text', type: 'token-ref', path: 'theme.components.suggestion.card.foreground', defaultValue: 'semantic.colors.text', tokenRef: { tokenType: 'color' } },
+    { id: 'suggestion-card-border', label: 'Card Border', type: 'token-ref', path: 'theme.components.suggestion.card.border', defaultValue: 'semantic.colors.border', tokenRef: { tokenType: 'color' } },
+    { id: 'suggestion-card-hover', label: 'Card Hover', type: 'token-ref', path: 'theme.components.suggestion.card.hoverBackground', defaultValue: 'palette.colors.gray.100', tokenRef: { tokenType: 'color' } },
+    { id: 'suggestion-card-shadow', label: 'Card Shadow', type: 'select', path: 'theme.components.suggestion.card.shadow', defaultValue: 'palette.shadows.sm', options: [
+      { value: 'palette.shadows.none', label: 'None' },
+      { value: 'palette.shadows.sm', label: 'Small' },
+      { value: 'palette.shadows.md', label: 'Medium' },
+      { value: 'palette.shadows.lg', label: 'Large' },
+    ] },
+    { id: 'suggestion-list-bg', label: 'List Background', type: 'color', path: 'theme.components.suggestion.list.background', defaultValue: 'transparent' },
+    { id: 'suggestion-list-border', label: 'List Border', type: 'token-ref', path: 'theme.components.suggestion.list.border', defaultValue: 'semantic.colors.border', tokenRef: { tokenType: 'color' } },
+  ],
+};
+
 // Reusable shadow-scale options matching the launcher / panel / scroll-to-bottom selects.
 const SHADOW_SCALE_OPTIONS: { value: string; label: string }[] = [
   { value: 'palette.shadows.none', label: 'None' },
@@ -502,6 +540,7 @@ export const COMPONENT_SHAPE_SECTIONS: SectionDef[] = [
   launcherLayoutSectionDef,
   messageShapeSectionDef,
   inputShapeSectionDef,
+  composerSpacingSectionDef,
   buttonShapeSectionDef,
   componentShadowsSectionDef,
 ];
@@ -513,6 +552,7 @@ export const COMPONENT_COLOR_SECTIONS: SectionDef[] = [
   inputColorsSectionDef,
   buttonColorsSectionDef,
   scrollToBottomSectionDef,
+  suggestionStyleSectionDef,
 ];
 
 export const COMPONENTS_SECTIONS: SectionDef[] = [
@@ -526,9 +566,9 @@ export const COMPONENTS_SECTIONS: SectionDef[] = [
 
 const MB = 1024 * 1024;
 const DEFAULT_SUGGESTION_CHIPS = [
-  'What can you help me with?',
-  'Tell me about your features',
-  'How does this work?',
+  'Show me what you can help with',
+  'Walk me through getting started',
+  'Answer a question about this page',
 ];
 
 const ATTACHMENT_TYPE_PRESETS: Record<string, string[]> = {
@@ -576,9 +616,17 @@ const copySectionDef: SectionDef = {
 };
 
 const suggestionsSectionDef: SectionDef = {
-  id: 'suggestions', title: 'Suggestion Chips', description: 'Configure chip content and styling.', collapsed: true,
+  id: 'suggestions', title: 'Suggestions', description: 'Configure starter prompts and agent follow-ups.', collapsed: true,
   fields: [
-    { id: 'suggestions-list', label: 'Suggestions', description: 'Add, edit, and remove chips directly.', type: 'chip-list', path: 'suggestionChips', defaultValue: DEFAULT_SUGGESTION_CHIPS },
+    { id: 'suggestions-list', label: 'Starter Prompts', description: 'Add, edit, and remove starter prompts directly.', type: 'chip-list', path: 'suggestionChips', defaultValue: DEFAULT_SUGGESTION_CHIPS },
+    { id: 'suggestions-starter-variant', label: 'Starter Style', type: 'select', path: 'suggestions.starters.variant', defaultValue: 'card', options: [{ value: 'card', label: 'Cards' }, { value: 'chip', label: 'Chips' }, { value: 'list', label: 'List' }] },
+    { id: 'suggestions-starter-placement', label: 'Starter Placement', type: 'select', path: 'suggestions.starters.placement', defaultValue: 'auto', options: [{ value: 'auto', label: 'Automatic' }, { value: 'welcome', label: 'Welcome Surface' }, { value: 'composer', label: 'Above Composer' }] },
+    { id: 'suggestions-starter-behavior', label: 'Starter Click', type: 'select', path: 'suggestions.starters.behavior', defaultValue: 'send', options: [{ value: 'send', label: 'Send Immediately' }, { value: 'fill', label: 'Fill Composer' }] },
+    { id: 'suggestions-starter-overflow', label: 'Starter Overflow', type: 'select', path: 'suggestions.starters.overflow', defaultValue: 'wrap', options: [{ value: 'wrap', label: 'Wrap Rows' }, { value: 'scroll', label: 'Horizontal Scroll' }] },
+    { id: 'suggestions-followup-variant', label: 'Follow-up Style', type: 'select', path: 'suggestions.followUps.variant', defaultValue: 'chip', options: [{ value: 'chip', label: 'Chips' }, { value: 'card', label: 'Cards' }, { value: 'list', label: 'List' }] },
+    { id: 'suggestions-followup-placement', label: 'Follow-up Placement', type: 'select', path: 'suggestions.followUps.placement', defaultValue: 'auto', options: [{ value: 'auto', label: 'Automatic' }, { value: 'after-message', label: 'After Messages' }, { value: 'composer', label: 'Above Composer' }] },
+    { id: 'suggestions-followup-behavior', label: 'Follow-up Click', type: 'select', path: 'suggestions.followUps.behavior', defaultValue: 'send', options: [{ value: 'send', label: 'Send Immediately' }, { value: 'fill', label: 'Fill Composer' }] },
+    { id: 'suggestions-followup-overflow', label: 'Follow-up Overflow', type: 'select', path: 'suggestions.followUps.overflow', defaultValue: 'scroll', options: [{ value: 'scroll', label: 'Horizontal Scroll' }, { value: 'wrap', label: 'Wrap Rows' }] },
   ],
 };
 

package/src/theme-reference.ts

@@ -142,7 +142,8 @@ export const THEME_TOKEN_DOCS = {
         'Floating scroll-to-bottom affordance shared by transcript and event stream: background, foreground, border, size, borderRadius, shadow, padding, gap, fontSize, iconSize.',
       toolBubble: 'shadow: tool call row box-shadow.',
       reasoningBubble: 'shadow: reasoning/thinking row box-shadow.',
-      composer: 'shadow: message input form box-shadow.',
+      composer:
+        'Message input form: shadow (box-shadow), padding (form inset), gap (textarea row to actions row), fontSize and lineHeight (textarea type).',
       artifact:
         'toolbar (icon styling, copy menu), tab (background, active states), pane (background, toolbarBackground).',
     },
@@ -245,8 +246,14 @@ export const THEME_TOKEN_DOCS = {
       properties:
         'enabled, provider ("browser" | "runtype"), browserFallback, voice, rate, pitch.',
     },
+    suggestions: {
+      description:
+        'Rich starter and follow-up suggestion surfaces. Strings remain valid item shorthand.',
+      properties:
+        'starters.items, starters.variant ("card" | "chip" | "list"), starters.placement ("auto" | "welcome" | "composer"), starters.behavior ("send" | "fill"), starters.overflow ("scroll" | "wrap"), starters.maxItems, followUps.enabled, followUps.expose, followUps.variant, followUps.placement ("auto" | "after-message" | "composer"), followUps.behavior, followUps.overflow ("scroll" | "wrap"), followUps.maxItems.',
+    },
     suggestionChips:
-      'string[]: Suggested prompts shown to the user.',
+      'Deprecated string[] shorthand for starter prompts. Prefer suggestions.starters.items.',
     messageActions: {
       description: 'Message action buttons (copy, upvote, downvote).',
       properties:

package/src/types/theme.ts

@@ -365,6 +365,14 @@ export interface ReasoningBubbleTokens {
 export interface ComposerChromeTokens {
   /** Box-shadow on the composer form (raw CSS, e.g. `none`). */
   shadow: string;
+  /** Inner padding of the composer form (raw CSS shorthand). @default "0.75rem 1rem" */
+  padding?: string;
+  /** Gap between the textarea row and the actions row. @default "0.5rem" */
+  gap?: string;
+  /** Composer textarea font-size. @default "0.875rem" */
+  fontSize?: string;
+  /** Composer textarea line-height. @default "1.25rem" */
+  lineHeight?: string;
 }
 
 /** Artifact toolbar chrome. */
@@ -524,6 +532,28 @@ export interface ScrollToBottomTokens extends ComponentTokenSet {
   iconSize?: string;
 }
 
+/** Visual tokens shared by one suggestion presentation variant. */
+export interface SuggestionVariantTokens extends ComponentTokenSet {
+  gap?: string;
+  minHeight?: string;
+  fontSize?: string;
+  lineHeight?: string;
+  iconSize?: string;
+  hoverBackground?: TokenReference<'color'>;
+  hoverForeground?: TokenReference<'color'>;
+  hoverBorder?: TokenReference<'color'>;
+  pressedBackground?: TokenReference<'color'>;
+  focusRing?: TokenReference<'color'>;
+  disabledOpacity?: string;
+}
+
+/** Starter and follow-up suggestion chrome. */
+export interface SuggestionTokens {
+  chip: SuggestionVariantTokens;
+  card: SuggestionVariantTokens;
+  list: SuggestionVariantTokens;
+}
+
 /** Toggle group chrome (used by createToggleGroup). */
 export interface ToggleGroupTokens {
   /** Gap between toggle buttons. Default: 0 (connected). */
@@ -555,6 +585,8 @@ export interface ComponentTokens {
   labelButton?: LabelButtonTokens;
   /** Scroll-to-bottom indicator styling tokens. */
   scrollToBottom?: ScrollToBottomTokens;
+  /** Starter prompt and follow-up suggestion styling tokens. */
+  suggestion?: SuggestionTokens;
   /** Toggle group styling tokens. */
   toggleGroup?: ToggleGroupTokens;
   /** Artifact toolbar, tab strip, and pane chrome. */