@runtypelabs/persona 2.1.0 → 2.3.0

package/src/postprocessors.test.ts

@@ -0,0 +1,84 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from "vitest";
+import {
+  createMarkdownProcessor,
+  createDirectivePostprocessor,
+  escapeHtml,
+} from "./postprocessors";
+import { createDefaultSanitizer } from "./utils/sanitize";
+
+describe("markdown + sanitization integration", () => {
+  const md = createMarkdownProcessor();
+  const sanitize = createDefaultSanitizer();
+
+  it("strips script tags from markdown output", () => {
+    const html = sanitize(md("# Title\n<script>alert(1)</script>"));
+    expect(html).toContain("<h1>Title</h1>");
+    expect(html).not.toContain("<script>");
+    expect(html).not.toContain("alert(1)");
+  });
+
+  it("strips onerror handlers from img tags in markdown", () => {
+    const html = sanitize(md('<img src="x" onerror="alert(1)">'));
+    expect(html).not.toContain("onerror");
+  });
+
+  it("strips javascript: URIs from markdown links", () => {
+    const html = sanitize(md('[click](javascript:alert(1))'));
+    expect(html).not.toContain("javascript:");
+  });
+
+  it("preserves safe markdown headings", () => {
+    const html = sanitize(md("## Hello\n\nParagraph text."));
+    expect(html).toContain("<h2>Hello</h2>");
+    expect(html).toContain("<p>Paragraph text.</p>");
+  });
+
+  it("preserves safe markdown code blocks", () => {
+    const html = sanitize(md("```js\nconst x = 1;\n```"));
+    expect(html).toContain("<code");
+    expect(html).toContain("const x = 1;");
+  });
+
+  it("preserves safe links", () => {
+    const html = sanitize(md("[example](https://example.com)"));
+    expect(html).toContain('href="https://example.com"');
+  });
+});
+
+describe("directive postprocessor + sanitization", () => {
+  const directive = createDirectivePostprocessor();
+  const sanitize = createDefaultSanitizer();
+
+  it("preserves form directive placeholders", () => {
+    const html = sanitize(directive('<Form type="init" />'));
+    expect(html).toContain('data-tv-form="init"');
+    expect(html).toContain("persona-form-directive");
+  });
+
+  it("sanitizes content surrounding directives", () => {
+    const html = sanitize(directive('<Form type="init" />\n<script>bad</script>'));
+    expect(html).toContain('data-tv-form="init"');
+    expect(html).not.toContain("<script>");
+    expect(html).not.toContain("bad");
+  });
+
+  it("handles JSON-style directives", () => {
+    const html = sanitize(
+      directive('<Directive>{"component":"form","type":"contact"}</Directive>')
+    );
+    expect(html).toContain('data-tv-form="contact"');
+  });
+});
+
+describe("escapeHtml", () => {
+  it("escapes all HTML special characters", () => {
+    expect(escapeHtml('<script>alert("xss")&</script>')).toBe(
+      "&lt;script&gt;alert(&quot;xss&quot;)&amp;&lt;/script&gt;"
+    );
+  });
+
+  it("escapes single quotes", () => {
+    expect(escapeHtml("it's")).toBe("it&#39;s");
+  });
+});

package/src/presets.ts

@@ -0,0 +1,127 @@
+import type { AgentWidgetConfig } from './types';
+
+/**
+ * A named preset containing partial widget configuration.
+ * Apply with: `createAgentExperience(el, { ...PRESET_SHOP.config, apiUrl: '...' })`
+ * or via IIFE: `{ ...AgentWidget.PRESETS.shop.config, apiUrl: '...' }`
+ */
+export interface WidgetPreset {
+  id: string;
+  label: string;
+  config: Partial<AgentWidgetConfig>;
+}
+
+/**
+ * Shopping / e-commerce preset.
+ * Dark header, rounded launchers, shopping-oriented copy.
+ */
+export const PRESET_SHOP: WidgetPreset = {
+  id: 'shop',
+  label: 'Shopping Assistant',
+  config: {
+    theme: {
+      primary: '#111827',
+      accent: '#1d4ed8',
+      surface: '#ffffff',
+      muted: '#6b7280',
+      container: '#f8fafc',
+      border: '#f1f5f9',
+      divider: '#f1f5f9',
+      messageBorder: '#f1f5f9',
+      inputBackground: '#ffffff',
+      callToAction: '#000000',
+      callToActionBackground: '#ffffff',
+      sendButtonBackgroundColor: '#111827',
+      sendButtonTextColor: '#ffffff',
+      radiusSm: '0.75rem',
+      radiusMd: '1rem',
+      radiusLg: '1.5rem',
+      launcherRadius: '9999px',
+      buttonRadius: '9999px',
+    },
+    launcher: {
+      title: 'Shopping Assistant',
+      subtitle: 'Here to help you find what you need',
+      agentIconText: '🛍️',
+      position: 'bottom-right',
+      width: 'min(400px, calc(100vw - 24px))',
+    },
+    copy: {
+      welcomeTitle: 'Welcome to our shop!',
+      welcomeSubtitle: 'I can help you find products and answer questions',
+      inputPlaceholder: 'Ask me anything...',
+      sendButtonLabel: 'Send',
+    },
+    suggestionChips: [
+      'What can you help me with?',
+      'Tell me about your features',
+      'How does this work?',
+    ],
+  },
+};
+
+/**
+ * Minimal preset.
+ * Stripped-down header, no launcher button, suitable for inline embeds.
+ */
+export const PRESET_MINIMAL: WidgetPreset = {
+  id: 'minimal',
+  label: 'Minimal',
+  config: {
+    launcher: {
+      enabled: false,
+      fullHeight: true,
+    },
+    layout: {
+      header: {
+        layout: 'minimal',
+        showCloseButton: false,
+      },
+      messages: {
+        layout: 'minimal',
+      },
+    },
+    theme: {
+      panelBorderRadius: '0',
+      panelShadow: 'none',
+    },
+  },
+};
+
+/**
+ * Fullscreen assistant preset.
+ * No launcher, content-max-width constrained, minimal header.
+ */
+export const PRESET_FULLSCREEN: WidgetPreset = {
+  id: 'fullscreen',
+  label: 'Fullscreen Assistant',
+  config: {
+    launcher: {
+      enabled: false,
+      fullHeight: true,
+    },
+    layout: {
+      header: {
+        layout: 'minimal',
+        showCloseButton: false,
+      },
+      contentMaxWidth: '72ch',
+    },
+    theme: {
+      panelBorderRadius: '0',
+      panelShadow: 'none',
+    },
+  },
+};
+
+/** All named presets keyed by ID. */
+export const PRESETS: Record<string, WidgetPreset> = {
+  shop: PRESET_SHOP,
+  minimal: PRESET_MINIMAL,
+  fullscreen: PRESET_FULLSCREEN,
+};
+
+/** Look up a preset by ID. */
+export function getPreset(id: string): WidgetPreset | undefined {
+  return PRESETS[id];
+}

package/src/styles/widget.css

@@ -2064,9 +2064,9 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  padding: 0.25rem;
-  border-radius: var(--persona-radius-md, 0.375rem);
-  border: 1px solid var(--persona-border, #e5e7eb);
+  padding: var(--persona-artifact-toolbar-icon-padding, 0.25rem);
+  border-radius: var(--persona-artifact-toolbar-icon-radius, var(--persona-radius-md, 0.375rem));
+  border: var(--persona-artifact-toolbar-icon-border, 1px solid var(--persona-border, #e5e7eb));
   background: var(--persona-surface, #ffffff);
   color: var(--persona-artifact-doc-toolbar-icon-color, var(--persona-text, #111827));
   cursor: pointer;
@@ -2074,7 +2074,8 @@
 }
 
 #persona-root .persona-artifact-toolbar-document .persona-artifact-doc-icon-btn:hover {
-  background: var(--persona-container, #f3f4f6);
+  color: var(--persona-artifact-toolbar-icon-hover-color, inherit);
+  background: var(--persona-artifact-toolbar-icon-hover-bg, var(--persona-container, #f3f4f6));
 }
 
 #persona-root .persona-artifact-toolbar-document .persona-artifact-doc-icon-btn[aria-pressed="true"] {
@@ -2086,24 +2087,53 @@
   display: inline-flex;
   align-items: center;
   gap: 0.35rem;
-  padding: 0.25rem 0.5rem;
-  border-radius: var(--persona-radius-md, 0.375rem);
-  border: 1px solid var(--persona-border, #e5e7eb);
-  background: var(--persona-surface, #ffffff);
-  color: var(--persona-artifact-doc-toolbar-icon-color, var(--persona-text, #111827));
+  padding: var(--persona-artifact-toolbar-copy-padding, 0.25rem 0.5rem);
+  border-radius: var(--persona-artifact-toolbar-copy-radius, var(--persona-radius-md, 0.375rem));
+  border: var(--persona-artifact-toolbar-copy-border, 1px solid var(--persona-border, #e5e7eb));
+  background: var(--persona-artifact-toolbar-copy-bg, var(--persona-surface, #ffffff));
+  color: var(--persona-artifact-toolbar-copy-color, var(--persona-artifact-doc-toolbar-icon-color, var(--persona-text, #111827)));
   cursor: pointer;
   font-size: 0.75rem;
   line-height: 1.25;
 }
 
 #persona-root .persona-artifact-toolbar-document .persona-artifact-doc-copy-btn:hover {
-  background: var(--persona-container, #f3f4f6);
+  background: var(--persona-artifact-toolbar-icon-hover-bg, var(--persona-container, #f3f4f6));
 }
 
 #persona-root .persona-artifact-toolbar-document .persona-artifact-doc-copy-label {
   font-weight: 500;
 }
 
+/* Copy menu dropdown theming */
+#persona-root .persona-artifact-doc-copy-menu {
+  background: var(--persona-artifact-toolbar-copy-menu-bg, var(--persona-surface, #fff));
+  border: var(--persona-artifact-toolbar-copy-menu-border, 1px solid var(--persona-border, #e5e7eb));
+  box-shadow: var(--persona-artifact-toolbar-copy-menu-shadow, 0 4px 6px -1px rgba(0,0,0,.1));
+  border-radius: var(--persona-artifact-toolbar-copy-menu-radius, 0.375rem);
+}
+
+#persona-root .persona-artifact-doc-copy-menu button:hover {
+  background: var(--persona-artifact-toolbar-copy-menu-item-hover-bg, var(--persona-container, #f3f4f6));
+}
+
+/* Artifact tab theming */
+#persona-root .persona-artifact-tab {
+  background: var(--persona-artifact-tab-bg, transparent);
+  border-radius: var(--persona-artifact-tab-radius, 0.5rem);
+  color: var(--persona-artifact-tab-color, inherit);
+}
+
+#persona-root .persona-artifact-tab.persona-bg-persona-container {
+  background: var(--persona-artifact-tab-active-bg, var(--persona-container, #f3f4f6));
+  border-color: var(--persona-artifact-tab-active-border, var(--persona-border, #e5e7eb));
+}
+
+/* Artifact toolbar background theming */
+#persona-root .persona-artifact-toolbar {
+  background: var(--persona-artifact-toolbar-bg, var(--persona-surface, #fff));
+}
+
 /* Draggable split handle (desktop split only; hidden in drawer / narrow host / small viewport) */
 #persona-root .persona-artifact-split-handle {
   width: 6px;

package/src/types/theme.ts

@@ -298,6 +298,41 @@ export interface ComposerChromeTokens {
   shadow: string;
 }
 
+/** Artifact toolbar chrome. */
+export interface ArtifactToolbarTokens {
+  iconHoverColor?: string;
+  iconHoverBackground?: string;
+  iconPadding?: string;
+  iconBorderRadius?: string;
+  iconBorder?: string;
+  toggleGroupGap?: string;
+  toggleBorderRadius?: string;
+  copyBackground?: string;
+  copyBorder?: string;
+  copyColor?: string;
+  copyBorderRadius?: string;
+  copyPadding?: string;
+  copyMenuBackground?: string;
+  copyMenuBorder?: string;
+  copyMenuShadow?: string;
+  copyMenuBorderRadius?: string;
+  copyMenuItemHoverBackground?: string;
+}
+
+/** Artifact tab strip chrome. */
+export interface ArtifactTabTokens {
+  background?: string;
+  activeBackground?: string;
+  activeBorder?: string;
+  borderRadius?: string;
+  textColor?: string;
+}
+
+/** Artifact pane chrome. */
+export interface ArtifactPaneTokens {
+  toolbarBackground?: string;
+}
+
 export interface ComponentTokens {
   button: ButtonTokens;
   input: InputTokens;
@@ -313,6 +348,12 @@ export interface ComponentTokens {
   toolBubble: ToolBubbleTokens;
   reasoningBubble: ReasoningBubbleTokens;
   composer: ComposerChromeTokens;
+  /** Artifact toolbar, tab strip, and pane chrome. */
+  artifact?: {
+    toolbar?: ArtifactToolbarTokens;
+    tab?: ArtifactTabTokens;
+    pane?: ArtifactPaneTokens;
+  };
 }
 
 export interface PaletteExtras {

package/src/types.ts

@@ -525,6 +525,14 @@ export type AgentWidgetArtifactsFeature = {
   allowedTypes?: PersonaArtifactKind[];
   /** Split / drawer dimensions and launcher widen behavior */
   layout?: AgentWidgetArtifactsLayoutConfig;
+  /**
+   * Called when an artifact card action is triggered (open, download).
+   * Return `true` to prevent the default behavior.
+   */
+  onArtifactAction?: (action: {
+    type: 'open' | 'download';
+    artifactId: string;
+  }) => boolean | void;
 };
 
 export type AgentWidgetFeatureFlags = {
@@ -1452,6 +1460,12 @@ export type AgentWidgetHeaderLayoutConfig = {
   trailingActions?: AgentWidgetHeaderTrailingAction[];
   /** Called when a `trailingActions` button is clicked. */
   onAction?: (actionId: string) => void;
+  /**
+   * Called when the header title row is clicked.
+   * Useful for dropdown menus or navigation triggered from the header.
+   * When set, the title row becomes visually interactive (cursor: pointer).
+   */
+  onTitleClick?: () => void;
 };
 
 /**
@@ -2557,7 +2571,21 @@ export type AgentWidgetConfig = {
    * ```
    */
   markdown?: AgentWidgetMarkdownConfig;
-  
+
+  /**
+   * HTML sanitization for rendered message content.
+   *
+   * The widget renders AI-generated markdown as HTML. By default, all HTML
+   * output is sanitized using DOMPurify to prevent XSS attacks.
+   *
+   * - `true` (default): sanitize using built-in DOMPurify
+   * - `false`: disable sanitization (only use with fully trusted content sources)
+   * - `(html: string) => string`: custom sanitizer function
+   *
+   * @default true
+   */
+  sanitize?: boolean | ((html: string) => string);
+
   /**
    * Configuration for message action buttons (copy, upvote, downvote).
    * Shows action buttons on assistant messages for user feedback.

package/src/ui.ts

@@ -1,4 +1,5 @@
 import { escapeHtml, createMarkdownProcessorFromConfig } from "./postprocessors";
+import { resolveSanitizer } from "./utils/sanitize";
 import { AgentWidgetSession, AgentWidgetSessionStatus } from "./session";
 import {
   AgentWidgetConfig,
@@ -321,6 +322,9 @@ const buildPostprocessor = (
     ? createMarkdownProcessorFromConfig(cfg.markdown)
     : null;
 
+  // Resolve sanitizer: enabled by default, can be disabled or replaced
+  const sanitize = resolveSanitizer(cfg?.sanitize);
+
   return (context) => {
     let nextText = context.text ?? "";
     const rawPayload = context.message.rawContent ?? null;
@@ -347,20 +351,20 @@ const buildPostprocessor = (
     }
 
     // Priority: postprocessMessage > markdown config > escapeHtml
+    let html: string;
     if (cfg?.postprocessMessage) {
-      return cfg.postprocessMessage({
+      html = cfg.postprocessMessage({
         ...context,
         text: nextText,
         raw: rawPayload ?? context.text ?? ""
       });
+    } else if (markdownProcessor) {
+      html = markdownProcessor(nextText);
+    } else {
+      html = escapeHtml(nextText);
     }
 
-    // Use markdown processor if markdown config is provided
-    if (markdownProcessor) {
-      return markdownProcessor(nextText);
-    }
-
-    return escapeHtml(nextText);
+    return sanitize ? sanitize(html) : html;
   };
 };
 
@@ -1142,6 +1146,9 @@ export const createAgentExperience = (
     event.stopPropagation();
     const artifactId = dlBtn.getAttribute('data-download-artifact');
     if (!artifactId) return;
+    // Let integrator intercept
+    const dlPrevented = config.features?.artifacts?.onArtifactAction?.({ type: 'download', artifactId });
+    if (dlPrevented === true) return;
     // Try session state first, fall back to content stored in the card's rawContent props
     const artifact = session.getArtifactById(artifactId);
     let markdown = artifact?.markdown;
@@ -1180,6 +1187,9 @@ export const createAgentExperience = (
     if (!card) return;
     const artifactId = card.getAttribute('data-open-artifact');
     if (!artifactId) return;
+    // Let integrator intercept
+    const openPrevented = config.features?.artifacts?.onArtifactAction?.({ type: 'open', artifactId });
+    if (openPrevented === true) return;
     event.preventDefault();
     event.stopPropagation();
     session.selectArtifact(artifactId);
@@ -3560,6 +3570,8 @@ export const createAgentExperience = (
       const previousMessageActions = config.messageActions;
       const previousLayoutMessages = config.layout?.messages;
       const previousColorScheme = config.colorScheme;
+      const previousLoadingIndicator = config.loadingIndicator;
+      const previousIterationDisplay = config.iterationDisplay;
       config = { ...config, ...nextConfig };
       // applyFullHeightStyles resets mount.style.cssText, so call it before applyThemeVariables
       applyFullHeightStyles();
@@ -3790,7 +3802,12 @@ export const createAgentExperience = (
       const toolCallConfigChanged = JSON.stringify(nextConfig.toolCall) !== JSON.stringify(previousToolCallConfig);
       const messageActionsChanged = JSON.stringify(config.messageActions) !== JSON.stringify(previousMessageActions);
       const layoutMessagesChanged = JSON.stringify(config.layout?.messages) !== JSON.stringify(previousLayoutMessages);
-      const messagesConfigChanged = toolCallConfigChanged || messageActionsChanged || layoutMessagesChanged;
+      const loadingIndicatorChanged = config.loadingIndicator?.render !== previousLoadingIndicator?.render
+        || config.loadingIndicator?.renderIdle !== previousLoadingIndicator?.renderIdle
+        || config.loadingIndicator?.showBubble !== previousLoadingIndicator?.showBubble;
+      const iterationDisplayChanged = config.iterationDisplay !== previousIterationDisplay;
+      const messagesConfigChanged = toolCallConfigChanged || messageActionsChanged || layoutMessagesChanged
+        || loadingIndicatorChanged || iterationDisplayChanged;
       if (messagesConfigChanged && session) {
         configVersion++;
         renderMessagesWithPlugins(messagesWrapper, session.getMessages(), postprocess);

package/src/utils/actions.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  defaultJsonActionParser,
+  defaultActionHandlers,
+  createActionManager,
+} from "./actions";
+import type { AgentWidgetMessage } from "../types";
+
+const makeMessage = (overrides: Partial<AgentWidgetMessage> = {}): AgentWidgetMessage => ({
+  id: "msg-1",
+  role: "assistant",
+  content: "",
+  createdAt: new Date().toISOString(),
+  ...overrides,
+});
+
+describe("defaultJsonActionParser", () => {
+  it("parses valid action JSON", () => {
+    const result = defaultJsonActionParser({
+      text: '{"action":"message","text":"hi"}',
+      message: makeMessage(),
+    });
+    expect(result).toEqual({
+      type: "message",
+      payload: { text: "hi" },
+      raw: { action: "message", text: "hi" },
+    });
+  });
+
+  it("returns null for non-action JSON", () => {
+    const result = defaultJsonActionParser({
+      text: '{"foo":"bar"}',
+      message: makeMessage(),
+    });
+    expect(result).toBeNull();
+  });
+
+  it("returns null for non-JSON text", () => {
+    const result = defaultJsonActionParser({
+      text: "hello world",
+      message: makeMessage(),
+    });
+    expect(result).toBeNull();
+  });
+
+  it("returns null for empty text", () => {
+    expect(defaultJsonActionParser({ text: "", message: makeMessage() })).toBeNull();
+  });
+
+  it("strips code fences before parsing", () => {
+    const text = '```json\n{"action":"message","text":"fenced"}\n```';
+    const result = defaultJsonActionParser({ text, message: makeMessage() });
+    expect(result).toEqual({
+      type: "message",
+      payload: { text: "fenced" },
+      raw: { action: "message", text: "fenced" },
+    });
+  });
+});
+
+describe("createActionManager.process", () => {
+  const makeManager = (overrides?: Record<string, unknown>) => {
+    let metadata: Record<string, unknown> = {};
+    return createActionManager({
+      parsers: [defaultJsonActionParser],
+      handlers: [defaultActionHandlers.message],
+      getSessionMetadata: () => metadata,
+      updateSessionMetadata: (updater) => { metadata = updater(metadata); },
+      emit: vi.fn(),
+      documentRef: null,
+      ...overrides,
+    });
+  };
+
+  it("skips streaming messages", () => {
+    const manager = makeManager();
+    const result = manager.process({
+      text: '{"action":"message","text":"hi"}',
+      message: makeMessage(),
+      streaming: true,
+    });
+    expect(result).toBeNull();
+  });
+
+  it("skips non-assistant messages", () => {
+    const manager = makeManager();
+    const result = manager.process({
+      text: '{"action":"message","text":"hi"}',
+      message: makeMessage({ role: "user" }),
+      streaming: false,
+    });
+    expect(result).toBeNull();
+  });
+
+  it("deduplicates by message ID", () => {
+    const manager = makeManager();
+    const msg = makeMessage({ content: '{"action":"message","text":"hi"}' });
+    const first = manager.process({ text: msg.content, message: msg, streaming: false });
+    expect(first).not.toBeNull();
+
+    const second = manager.process({ text: msg.content, message: msg, streaming: false });
+    expect(second).toBeNull();
+  });
+
+  it("processes valid action and returns display text", () => {
+    const manager = makeManager();
+    const result = manager.process({
+      text: '{"action":"message","text":"hello"}',
+      message: makeMessage(),
+      streaming: false,
+    });
+    expect(result).toEqual({ text: "hello", persist: true, resubmit: undefined });
+  });
+});