@runtypelabs/persona 4.13.0 → 4.15.0

package/src/index-core.ts

@@ -5,6 +5,8 @@ import {
 
 export type {
   AgentWidgetConfig,
+  AgentWidgetStorageAdapter,
+  AgentWidgetStoredState,
   AgentWidgetConfigPatch,
   TargetResolver,
   ResolvedTarget,
@@ -12,12 +14,19 @@ export type {
   AgentWidgetArtifactsFeature,
   AgentWidgetArtifactsLayoutConfig,
   PersonaArtifactDisplayMode,
+  PersonaArtifactDisplayModeInput,
+  PersonaArtifactDisplayRules,
+  PersonaArtifactFilesDisplayRules,
   PersonaArtifactKind,
+  PersonaArtifactPresentation,
   PersonaArtifactRecord,
   PersonaArtifactActionContext,
   PersonaArtifactStatusLabelContext,
   PersonaArtifactCustomAction,
   PersonaArtifactManualUpsert,
+  WidgetPreferenceCapabilities,
+  WidgetArtifactLayoutPreference,
+  WidgetPreferenceSlice,
   ArtifactConfigPayload,
   AgentWidgetInitOptions,
   AgentWidgetMessage,
@@ -131,9 +140,45 @@ export type {
   AskUserQuestionPrompt,
   AskUserQuestionOption,
   AgentWidgetAskUserQuestionFeature,
-  AgentWidgetAskUserQuestionStyles
+  AgentWidgetAskUserQuestionStyles,
+  AgentWidgetSuggestion,
+  AgentWidgetSuggestionChipsConfig,
+  AgentWidgetResolvedSuggestion,
+  AgentWidgetSuggestionBehavior,
+  AgentWidgetSuggestionVariant,
+  AgentWidgetSuggestionSurface,
+  AgentWidgetSuggestionSource,
+  AgentWidgetSuggestionSurfaceConfig,
+  AgentWidgetStarterSuggestionsConfig,
+  AgentWidgetFollowUpSuggestionsConfig,
+  AgentWidgetSuggestionsConfig
 } from "./types";
 
+export {
+  applyFeaturePreferences,
+  parseWidgetPreferenceSlice,
+  resolveConfigPreferences,
+  normalizeMediaType,
+} from "./utils/feature-preferences";
+
+export type {
+  WidgetPreferenceParseIssueCode,
+  WidgetPreferenceParseIssue,
+  WidgetPreferenceParseResult,
+} from "./utils/feature-preferences";
+
+export {
+  canonicalArtifactDisplayMode,
+  resolveArtifactDisplay,
+  resolveArtifactDisplayMode,
+} from "./utils/artifact-display";
+
+export type {
+  PersonaArtifactDisplayDescriptor,
+  PersonaArtifactDisplayMatch,
+  PersonaArtifactDisplayResolution,
+} from "./utils/artifact-display";
+
 export type {
   RuntypeExecutionStreamEvent,
   RuntypeStreamEventOf,
@@ -292,7 +337,12 @@ export { VERSION } from "./version";
 export type { AgentWidgetInitHandle };
 
 // Plugin system exports
-export type { AgentWidgetPlugin } from "./plugins/types";
+export type {
+  AgentWidgetPlugin,
+  AgentWidgetTransformSuggestionsContext,
+  AgentWidgetRenderSuggestionContext,
+  AgentWidgetSuggestionSelectContext
+} from "./plugins/types";
 export { pluginRegistry } from "./plugins/registry";
 
 // Stream animation plugin API: lets consumers register custom animations

package/src/launcher-global.ts

@@ -76,7 +76,7 @@ const mergeCriticalLauncherConfig = (
  * Mirrors the full widget's DOM exactly (`runtime/init.ts` + `ui.ts`): a
  * `[data-persona-root]` wrapper carries the theme CSS variables and the launcher
  * button is its child. Keeping the theme vars on the wrapper (not the button)
- * leaves the button's own inline style byte-identical to the full widget's, so
+ * leaves the button's own inline style matching the full widget's, so
  * the eventual mount-then-remove handoff is invisible.
  */
 export const mount = (

package/src/plugins/types.ts

@@ -8,9 +8,51 @@ import {
   EventStreamViewRenderContext,
   EventStreamRowRenderContext,
   EventStreamToolbarRenderContext,
-  EventStreamPayloadRenderContext
+  EventStreamPayloadRenderContext,
+  AgentWidgetSuggestion,
+  AgentWidgetResolvedSuggestion,
+  AgentWidgetSuggestionSource,
+  AgentWidgetSuggestionSurface,
+  AgentWidgetSuggestionVariant
 } from "../types";
 
+export type AgentWidgetTransformSuggestionsContext = {
+  /**
+   * Fresh copy of the suggestions entering this plugin, already normalized:
+   * shorthand strings expanded and the effective send/fill behavior resolved.
+   */
+  suggestions: AgentWidgetResolvedSuggestion[];
+  surface: AgentWidgetSuggestionSurface;
+  source: AgentWidgetSuggestionSource;
+  config: AgentWidgetConfig;
+};
+
+export type AgentWidgetRenderSuggestionContext = {
+  /** Fully normalized suggestion, including the effective send/fill behavior. */
+  suggestion: AgentWidgetResolvedSuggestion;
+  index: number;
+  surface: AgentWidgetSuggestionSurface;
+  source: AgentWidgetSuggestionSource;
+  variant: AgentWidgetSuggestionVariant;
+  streaming: boolean;
+  config: AgentWidgetConfig;
+  /** Build Persona's standard chip, card, or list item. */
+  defaultRenderer: () => HTMLElement;
+  /**
+   * Run the normal selection pipeline: DOM event, plugin selection hooks, then
+   * send or fill. Custom renderers should call this instead of sending directly.
+   */
+  select: () => void;
+};
+
+export type AgentWidgetSuggestionSelectContext = {
+  suggestion: AgentWidgetResolvedSuggestion;
+  surface: AgentWidgetSuggestionSurface;
+  source: AgentWidgetSuggestionSource;
+  variant: AgentWidgetSuggestionVariant;
+  config: AgentWidgetConfig;
+};
+
 /**
  * Plugin interface for customizing widget components
  */
@@ -25,6 +67,34 @@ export interface AgentWidgetPlugin {
    */
   priority?: number;
 
+  /**
+   * Transform, filter, enrich, or reorder suggestions. Hooks receive normalized
+   * items and compose in plugin priority order; the return value may use the
+   * loose shape (string shorthand included) and is re-normalized before the next
+   * hook. A per-item `behavior` set here survives. `maxItems` caps the list
+   * after the full chain. Return an empty array to hide the surface.
+   */
+  transformSuggestions?: (
+    context: AgentWidgetTransformSuggestionsContext
+  ) => AgentWidgetSuggestion[];
+
+  /**
+   * Render one starter or follow-up suggestion. Return null to use Persona's
+   * default chip/card/list renderer. Call `select()` from custom interaction
+   * controls to preserve events, selection hooks, and send/fill behavior.
+   */
+  renderSuggestion?: (
+    context: AgentWidgetRenderSuggestionContext
+  ) => HTMLElement | null;
+
+  /**
+   * Observe or intercept a suggestion selection. Return false to cancel the
+   * built-in send/fill action. Hooks run in plugin priority order.
+   */
+  onSuggestionSelect?: (
+    context: AgentWidgetSuggestionSelectContext
+  ) => void | boolean;
+
   /**
    * Custom renderer for message bubbles
    * Return null to use default renderer
@@ -298,5 +368,3 @@ export interface AgentWidgetPlugin {
 
 
 
-
-

package/src/presets.ts

@@ -75,9 +75,9 @@ export const PRESET_SHOP: WidgetPreset = {
       sendButtonLabel: "Send",
     },
     suggestionChips: [
-      "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",
     ],
   },
 };

package/src/session.ts

@@ -2,6 +2,7 @@ import { AgentWidgetClient, type SSEEventCallback } from "./client";
 import { isWebMcpToolName } from "./webmcp-bridge";
 import {
   SUGGEST_REPLIES_TOOL_NAME,
+  resolveFollowUpsFeature,
   suggestRepliesToolResult,
 } from "./suggest-replies-tool";
 import {
@@ -77,10 +78,11 @@ export type AgentWidgetSessionStatus =
  * request. When NONE of these change, `updateConfig` can refresh the live
  * client in place (preserving the WebMCP bridge and any in-flight stream/resume)
  * instead of swapping in a fresh client and tearing down WebMCP state. Fields
- * outside this list (theme, copy, layout, suggestionChips, iterationDisplay,
- * postprocessMessage, feature display toggles, …) are display-only and safe to
- * apply mid-turn: which is what a self-styling widget needs when a `webmcp:*`
- * theme tool re-renders the widget while the agent's turn is still streaming.
+ * outside this list (theme, copy, layout, suggestions, suggestionChips,
+ * iterationDisplay, postprocessMessage, feature display toggles, …) are
+ * display-only and safe to apply mid-turn: which is what a self-styling widget
+ * needs when a `webmcp:*` theme tool re-renders the widget while the agent's
+ * turn is still streaming.
  *
  * Compared by identity (`!==`): primitives by value, functions/objects by
  * reference. A consumer that rebuilds these objects on every render simply
@@ -858,7 +860,11 @@ export class AgentWidgetSession {
   }
 
   public updateConfig(next: AgentWidgetConfig) {
+    const previousArtifactDisplay = this.config.features?.artifacts?.display;
     const merged = { ...this.config, ...next };
+    const artifactDisplayChanged =
+      JSON.stringify(previousArtifactDisplay) !==
+      JSON.stringify(merged.features?.artifacts?.display);
 
     // Connection/request-shaping change (apiUrl, clientToken, webmcp, headers,
     // parser, agent, …) → full client rebuild. UI-only change (theme, copy,
@@ -870,6 +876,7 @@ export class AgentWidgetSession {
     if (!connectionConfigChanged(this.config, merged)) {
       this.config = merged;
       this.client.updateConfig(merged);
+      if (artifactDisplayChanged) this.refreshArtifactReferenceBlocks();
       return;
     }
 
@@ -886,6 +893,7 @@ export class AgentWidgetSession {
     const prevSSECallback = this.client.getSSEEventCallback();
     this.config = merged;
     this.client = new AgentWidgetClient(this.config);
+    if (artifactDisplayChanged) this.refreshArtifactReferenceBlocks();
     this.wireDefaultWebMcpConfirm();
     if (prevSSECallback) {
       this.client.setSSEEventCallback(prevSSECallback);
@@ -2735,7 +2743,8 @@ export class AgentWidgetSession {
             title: manual.title,
             status: "complete",
             markdown: manual.content,
-            ...(manual.file ? { file: manual.file } : {})
+            ...(manual.file ? { file: manual.file } : {}),
+            ...(manual.presentation ? { presentation: manual.presentation } : {})
           }
         : {
             id,
@@ -2743,7 +2752,8 @@ export class AgentWidgetSession {
             title: manual.title,
             status: "complete",
             component: manual.component,
-            props: manual.props ?? {}
+            props: manual.props ?? {},
+            ...(manual.presentation ? { presentation: manual.presentation } : {})
           };
     this.artifacts.set(id, rec);
     this.selectedArtifactId = id;
@@ -2757,7 +2767,7 @@ export class AgentWidgetSession {
   /**
    * Injects (or refreshes) the in-thread artifact block for a programmatically
    * upserted artifact, matching the streamed UX: the resolved display mode
-   * picks the component ("card"/"panel" → reference card, "inline" → inline
+   * picks the component ("collapsed"/"panel" → reference card, "inline" → inline
    * preview).
    *
    * Unlike the streamed path (which embeds content on `artifact_complete`),
@@ -2774,7 +2784,7 @@ export class AgentWidgetSession {
     const refId = `artifact-ref-${rec.id}`;
     const displayMode = resolveArtifactDisplayMode(
       this.config.features?.artifacts,
-      rec.artifactType
+      rec
     );
     const rawContent = buildArtifactRefRawContent(displayMode, {
       artifactId: rec.id,
@@ -2782,6 +2792,7 @@ export class AgentWidgetSession {
       artifactType: rec.artifactType,
       status: "complete",
       ...(rec.file ? { file: rec.file } : {}),
+      ...(rec.presentation ? { presentation: rec.presentation } : {}),
       ...(rec.component ? { component: rec.component } : {}),
       ...(rec.props ? { componentProps: rec.props } : {}),
       ...(rec.markdown !== undefined ? { markdown: rec.markdown } : {})
@@ -2803,6 +2814,38 @@ export class AgentWidgetSession {
     });
   }
 
+  /**
+   * Re-materialize existing transcript artifact blocks after a live display
+   * preference update. One messages callback keeps conversion atomic.
+   */
+  private refreshArtifactReferenceBlocks(): void {
+    let changed = false;
+    for (const rec of this.artifacts.values()) {
+      const message = this.messages.find((candidate) => candidate.id === `artifact-ref-${rec.id}`);
+      if (!message) continue;
+      const displayMode = resolveArtifactDisplayMode(
+        this.config.features?.artifacts,
+        rec
+      );
+      const rawContent = buildArtifactRefRawContent(displayMode, {
+        artifactId: rec.id,
+        title: rec.title,
+        artifactType: rec.artifactType,
+        status: rec.status,
+        ...(rec.file ? { file: rec.file } : {}),
+        ...(rec.presentation ? { presentation: rec.presentation } : {}),
+        ...(rec.component ? { component: rec.component } : {}),
+        ...(rec.props ? { componentProps: rec.props } : {}),
+        ...(rec.markdown !== undefined ? { markdown: rec.markdown } : {}),
+      });
+      if (message.rawContent === rawContent) continue;
+      message.rawContent = rawContent;
+      message.streaming = rec.status === "streaming";
+      changed = true;
+    }
+    if (changed) this.callbacks.onMessagesChanged([...this.messages]);
+  }
+
   private clearArtifactState(): void {
     if (this.artifacts.size === 0 && this.selectedArtifactId === null) return;
     this.artifacts.clear();
@@ -2942,15 +2985,15 @@ export class AgentWidgetSession {
       // indefinitely: `resolveWebMcpToolCall` translates the missing-bridge
       // case into an isError result that resumes the flow cleanly.
       // `suggest_replies`, by contrast, is gated on its feature flag: when
-      // `features.suggestReplies.enabled === false` the widget neither
-      // renders chips nor resumes: the same parked-execution posture as a
-      // server-declared ask_user_question with its sheet disabled.
+      // the resolved `enabled` is false the widget neither renders chips nor
+      // resumes: the same parked-execution posture as a server-declared
+      // ask_user_question with its sheet disabled.
       const tc = event.message.toolCall;
       const autoResolvable =
         !!tc?.name &&
         (isWebMcpToolName(tc.name) ||
           (tc.name === SUGGEST_REPLIES_TOOL_NAME &&
-            this.config.features?.suggestReplies?.enabled !== false));
+            resolveFollowUpsFeature(this.config).enabled));
       if (
         event.message.agentMetadata?.awaitingLocalTool === true &&
         autoResolvable

package/src/styles/widget-styles.test.ts

@@ -0,0 +1,162 @@
+import { readFileSync } from "node:fs";
+
+import { describe, expect, it } from "vitest";
+
+const widgetCss = readFileSync(
+  new URL("./widget.css", import.meta.url),
+  "utf8",
+);
+
+describe("suggestion interaction styles", () => {
+  it("keeps suggestion surfaces from collapsing inside constrained transcripts", () => {
+    const selector = ".persona-suggestions {";
+    const start = widgetCss.indexOf(selector);
+    const end = widgetCss.indexOf("\n}", start);
+    const surfaceRule = widgetCss.slice(start, end);
+
+    expect(start).toBeGreaterThan(-1);
+    expect(surfaceRule).toContain("flex-shrink: 0");
+  });
+
+  it("keeps the primary emphasis a quiet accent rather than a solid fill", () => {
+    const selector = '.persona-suggestion[data-emphasis="primary"] {';
+    const start = widgetCss.indexOf(selector);
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(rule).toContain("border-color: var(--persona-primary)");
+    // Plain declaration first so engines without color-mix stay transparent.
+    expect(rule).toContain("background: transparent");
+    expect(rule).toContain(
+      "background: color-mix(in srgb, var(--persona-primary) 6%, transparent)",
+    );
+    expect(rule).not.toContain("--persona-text-inverse");
+  });
+
+  it("strengthens the primary wash on hover instead of filling it", () => {
+    const selector =
+      '.persona-suggestion[data-emphasis="primary"]:hover {';
+    const start = widgetCss.indexOf(selector);
+    const hoverRule = widgetCss.slice(start, widgetCss.indexOf("\n  }", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(hoverRule).toContain("border-color: var(--persona-primary)");
+    expect(hoverRule).toContain(
+      "color-mix(in srgb, var(--persona-primary) 12%, transparent)",
+    );
+    expect(hoverRule).not.toContain("filter: brightness");
+  });
+
+  it("rests cards flat and reserves the shadow plus lift for hover", () => {
+    const restStart = widgetCss.indexOf(".persona-suggestion--card {");
+    const restRule = widgetCss.slice(
+      restStart,
+      widgetCss.indexOf("\n}", restStart),
+    );
+
+    expect(restStart).toBeGreaterThan(-1);
+    expect(restRule).toContain(
+      "box-shadow: var(--persona-components-suggestion-card-shadow, none)",
+    );
+
+    const hoverStart = widgetCss.indexOf(".persona-suggestion--card:hover {");
+    const hoverRule = widgetCss.slice(
+      hoverStart,
+      widgetCss.indexOf("\n  }", hoverStart),
+    );
+
+    expect(hoverStart).toBeGreaterThan(-1);
+    expect(hoverRule).toContain("box-shadow: var(--persona-shadow-sm)");
+    expect(hoverRule).toContain("transform: translateY(-1px)");
+  });
+
+  it("reveals the suggestion arrow only on hover and keyboard focus", () => {
+    // Searched past `__copy`: the bare selector also appears in the shared
+    // `flex: 0 0 auto` group above it and the coarse-pointer override below.
+    const restStart = widgetCss.indexOf(
+      ".persona-suggestion__arrow {",
+      widgetCss.indexOf(".persona-suggestion__copy {"),
+    );
+    const restRule = widgetCss.slice(
+      restStart,
+      widgetCss.indexOf("\n}", restStart),
+    );
+
+    expect(restStart).toBeGreaterThan(-1);
+    expect(restRule).toContain("opacity: 0;");
+    expect(restRule).toContain("transition: opacity");
+    expect(widgetCss).toContain(
+      ".persona-suggestion:focus-visible .persona-suggestion__arrow",
+    );
+    expect(widgetCss).toContain(
+      ".persona-suggestion:hover .persona-suggestion__arrow",
+    );
+  });
+
+  it("caps the starter card grid so wide panels get two columns", () => {
+    expect(widgetCss).toContain(
+      "grid-template-columns: repeat(auto-fit, minmax(min(100%, 240px), 1fr))",
+    );
+    const selector =
+      '.persona-suggestions[data-variant="card"][data-persona-suggestion-surface="starter"] {';
+    const start = widgetCss.indexOf(selector);
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(rule).toContain("max-width: 600px");
+  });
+
+  it("masks only the scrollable chip edges that still contain content", () => {
+    expect(widgetCss).toContain(
+      '[data-overflow="scroll"][data-scroll-right]:not(',
+    );
+    expect(widgetCss).toContain(
+      '[data-overflow="scroll"][data-scroll-left]:not(',
+    );
+    expect(widgetCss).toContain(
+      '[data-overflow="scroll"][data-scroll-left][data-scroll-right]',
+    );
+    expect(widgetCss).toContain(
+      "--persona-suggestion-scroll-fade-size: 32px",
+    );
+  });
+});
+
+describe("composer spacing styles", () => {
+  it("themes the composer form padding and gap with utility-matching fallbacks", () => {
+    const selector =
+      "[data-persona-root] .persona-widget-composer:not(.persona-pill-composer) {";
+    const start = widgetCss.indexOf(selector);
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    // Fallbacks reproduce `persona-px-4 persona-py-3` and `persona-gap-2`.
+    expect(rule).toContain(
+      "padding: var(--persona-composer-padding, 0.75rem 1rem)",
+    );
+    expect(rule).toContain("gap: var(--persona-composer-gap, 0.5rem)");
+  });
+
+  it("themes the composer textarea type with text-sm fallbacks", () => {
+    const selector = "[data-persona-root] .persona-composer-textarea {";
+    const start = widgetCss.indexOf(selector);
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(rule).toContain(
+      "font-size: var(--persona-composer-font-size, 0.875rem)",
+    );
+    expect(rule).toContain(
+      "line-height: var(--persona-composer-line-height, 1.25rem)",
+    );
+  });
+
+  it("leaves the pill composer on its own single-row geometry", () => {
+    const start = widgetCss.indexOf(".persona-pill-composer {");
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(rule).toContain("padding: 6px 14px");
+    expect(rule).toContain("gap: 8px");
+  });
+});