@runtypelabs/persona 4.12.0 → 4.14.0

package/src/artifacts-session.test.ts

@@ -255,4 +255,110 @@ describe("AgentWidgetSession artifacts", () => {
     });
     expect(session.getArtifactById(session.getArtifacts()[0].id)?.file).toEqual(file);
   });
+
+  it("uses exact media-type file rules and the producer preferredMode hint", () => {
+    const session = new AgentWidgetSession(
+      {
+        features: {
+          artifacts: {
+            enabled: true,
+            display: {
+              default: "card",
+              files: { byMediaType: { "text/html": "inline" } },
+            },
+          },
+        },
+      },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {},
+      }
+    );
+    const rec = session.upsertArtifact({
+      id: "html-app",
+      artifactType: "markdown",
+      content: "<h1>App</h1>",
+      file: { path: "app.html", mimeType: "TEXT/HTML; charset=utf-8" },
+    });
+    const block = session.getMessages().find((message) => message.id === `artifact-ref-${rec.id}`);
+    expect(JSON.parse(block!.rawContent!).component).toBe("PersonaArtifactInline");
+
+    const hinted = session.upsertArtifact({
+      id: "hinted-doc",
+      artifactType: "markdown",
+      content: "# Live preview",
+      presentation: { preferredMode: "inline" },
+    });
+    const hintedBlock = session
+      .getMessages()
+      .find((message) => message.id === `artifact-ref-${hinted.id}`);
+    expect(JSON.parse(hintedBlock!.rawContent!).component).toBe(
+      "PersonaArtifactInline"
+    );
+  });
+
+  it("re-materializes existing artifact blocks after a live display update", () => {
+    const onMessagesChanged = vi.fn();
+    const session = new AgentWidgetSession(
+      { features: { artifacts: { enabled: true, display: "card" } } },
+      {
+        onMessagesChanged,
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {},
+      }
+    );
+    session.upsertArtifact({
+      id: "live",
+      artifactType: "component",
+      component: "Chart",
+      props: { values: [1, 2] },
+    });
+    session.upsertArtifact({
+      id: "live-markdown",
+      artifactType: "markdown",
+      content: "# Report",
+    });
+    const unmatchedRawContent = JSON.stringify({
+      component: "PersonaArtifactCard",
+      props: {
+        artifactId: "hydrated-without-record",
+        artifactType: "markdown",
+        status: "complete",
+      },
+    });
+    session.injectAssistantMessage({
+      id: "artifact-ref-hydrated-without-record",
+      content: "",
+      rawContent: unmatchedRawContent,
+    });
+    onMessagesChanged.mockClear();
+
+    session.updateConfig({
+      features: { artifacts: { enabled: true, display: "inline" } },
+    });
+
+    expect(onMessagesChanged).toHaveBeenCalledTimes(1);
+    const block = session.getMessages().find((message) => message.id === "artifact-ref-live");
+    const parsed = JSON.parse(block!.rawContent!);
+    expect(parsed.component).toBe("PersonaArtifactInline");
+    expect(parsed.props.component).toBe("Chart");
+    expect(parsed.props.componentProps).toEqual({ values: [1, 2] });
+    const markdownBlock = session
+      .getMessages()
+      .find((message) => message.id === "artifact-ref-live-markdown");
+    const parsedMarkdown = JSON.parse(markdownBlock!.rawContent!);
+    expect(parsedMarkdown.component).toBe("PersonaArtifactInline");
+    expect(parsedMarkdown.props.markdown).toBe("# Report");
+    expect(
+      session
+        .getMessages()
+        .find(
+          (message) =>
+            message.id === "artifact-ref-hydrated-without-record"
+        )?.rawContent
+    ).toBe(unmatchedRawContent);
+  });
 });

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/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", () => {

package/src/components/composer-parts.ts

@@ -32,7 +32,7 @@ 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 =

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/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,
@@ -134,6 +143,31 @@ export type {
   AgentWidgetAskUserQuestionStyles
 } 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,

package/src/session.ts

@@ -858,7 +858,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 +874,7 @@ export class AgentWidgetSession {
     if (!connectionConfigChanged(this.config, merged)) {
       this.config = merged;
       this.client.updateConfig(merged);
+      if (artifactDisplayChanged) this.refreshArtifactReferenceBlocks();
       return;
     }
 
@@ -886,6 +891,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 +2741,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 +2750,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 +2765,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 +2782,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 +2790,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 +2812,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();

package/src/styles/widget.css

@@ -294,6 +294,10 @@
   color: var(--persona-primary, #171717);
 }
 
+.persona-text-persona-text {
+  color: var(--persona-text, #111827);
+}
+
 .persona-text-persona-call-to-action {
   color: var(--persona-call-to-action, var(--persona-text-inverse, #ffffff));
 }
@@ -930,6 +934,11 @@
   box-shadow: none !important;
 }
 
+.persona-composer-textarea::placeholder {
+  color: var(--persona-input-placeholder, var(--persona-text-muted, #9ca3af));
+  opacity: 1;
+}
+
 /* Prevent iOS Safari from zooming on input focus (requires 16px minimum) */
 @media (hover: none) and (pointer: coarse) {
   .persona-composer-textarea {
@@ -4928,7 +4937,7 @@
 
 .persona-composer-contenteditable:empty::before {
   content: attr(data-placeholder);
-  color: var(--persona-placeholder, var(--persona-muted, #9ca3af));
+  color: var(--persona-input-placeholder, var(--persona-text-muted, #9ca3af));
   pointer-events: none;
 }
 

package/src/theme-editor/index.ts

@@ -43,6 +43,8 @@ export {
   COMPONENT_COLOR_SECTIONS,
   CONFIGURE_SECTIONS,
   CONFIGURE_SUB_GROUPS,
+  STREAM_AND_ARTIFACTS_SUB_GROUP,
+  ARTIFACT_DISPLAY_PREFERENCE_SECTION,
   ALL_TABS,
   scopeSection,
   findSection,
@@ -90,6 +92,9 @@ export type {
   TranscriptStreamFrame,
   BuildTranscriptStreamFramesOptions,
 } from './preview-utils';
+// Type-only: the full preview implementation stays in
+// `@runtypelabs/persona/theme-editor/preview`.
+export type { CompareMode, PreviewShellMode } from './preview';
 
 // Role mappings (Interface Roles editor)
 export {

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

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import type { AgentWidgetConfig } from '../types';
+import { getActiveTheme, themeToCssVariables } from '../utils/theme';
+import { BUILT_IN_PRESETS, getThemeEditorPreset } from './presets';
+
+describe('theme editor presets', () => {
+  it('offers the paired Persona default before the single-scheme presets', () => {
+    const preset = getThemeEditorPreset('persona-default');
+
+    expect(BUILT_IN_PRESETS[0]).toBe(preset);
+    expect(preset).toMatchObject({
+      name: 'Persona Default',
+      tags: ['light', 'dark', 'adaptive'],
+      preview: { surface: '#ffffff' },
+      darkPreview: { surface: '#1f2937' },
+    });
+    expect(preset?.darkTheme).toBeDefined();
+  });
+
+  it('resolves the paired default to distinct light and dark surfaces', () => {
+    const preset = getThemeEditorPreset('persona-default')!;
+    const config = {
+      theme: preset.theme,
+      darkTheme: preset.darkTheme,
+    } as AgentWidgetConfig;
+
+    const light = themeToCssVariables(getActiveTheme({ ...config, colorScheme: 'light' }));
+    const dark = themeToCssVariables(getActiveTheme({ ...config, colorScheme: 'dark' }));
+
+    expect(light).toMatchObject({
+      '--persona-surface': '#f9fafb',
+      '--persona-background': '#f9fafb',
+      '--persona-text': '#111827',
+      '--persona-border': '#e5e7eb',
+    });
+    expect(dark).toMatchObject({
+      '--persona-surface': '#1f2937',
+      '--persona-background': '#111827',
+      '--persona-text': '#f3f4f6',
+      '--persona-border': '#374151',
+    });
+  });
+});