@runtypelabs/persona 4.13.0 → 4.14.0

package/src/types.ts

@@ -685,6 +685,15 @@ export type AgentToolsConfig = {
 /** Artifact kinds for the Persona sidebar and dispatch payload */
 export type PersonaArtifactKind = "markdown" | "component";
 
+export type PersonaArtifactPresentation = {
+  /**
+   * Producer hint for where this artifact renders (content-disposition
+   * model). Beats configured defaults; loses to explicit `files`/`byKind`
+   * rules. Persona never infers it; the producer or host supplies it.
+   */
+  preferredMode?: PersonaArtifactDisplayModeInput;
+};
+
 /**
  * Agent configuration for agent execution mode.
  * When provided in the widget config, enables agent loop execution instead of flow dispatch.
@@ -1375,10 +1384,60 @@ export type AgentWidgetArtifactsLayoutConfig = {
   }) => void | Promise<void>;
 };
 
+/**
+ * Where the artifact body renders by default. Every mode shows the compact
+ * reference in the transcript; the mode names where the body goes:
+ * nowhere yet (`collapsed`), the side panel (`panel`), or the conversation
+ * itself (`inline`).
+ */
 export type PersonaArtifactDisplayMode =
-  | "card"    // reference card in transcript; pane opens on click
-  | "panel"   // reference card in transcript; pane also auto-opens on artifact_start (current default behavior)
-  | "inline"; // artifact preview renders directly in the transcript; no pane involvement
+  | "collapsed" // body renders nowhere until the user selects the reference; pane opens on click
+  | "panel" // body renders in the side panel, which auto-opens on artifact_start (default behavior)
+  | "inline"; // body renders directly in the transcript; no pane involvement
+
+/**
+ * Accepted wherever a display mode is written. `"card"` is a deprecated
+ * alias of `"collapsed"` (the old name described the reference card, which
+ * every mode shows, instead of where the body renders). Resolution and
+ * parsing always canonicalize to `"collapsed"`.
+ */
+export type PersonaArtifactDisplayModeInput =
+  | PersonaArtifactDisplayMode
+  | "card";
+
+/**
+ * Display rules for file-backed artifacts. `byMediaType` keys are exact MIME
+ * types (`"text/html"`) or major-type wildcards (`"image/*"`), matched
+ * case-insensitively without parameters; exact beats wildcard.
+ */
+export type PersonaArtifactFilesDisplayRules = {
+  default?: PersonaArtifactDisplayModeInput;
+  byMediaType?: Record<string, PersonaArtifactDisplayModeInput>;
+};
+
+/**
+ * Scoped artifact display rules. Matching resolves from the most specific
+ * selector to `default`; see `resolveArtifactDisplay`.
+ *
+ * Across preference layers, one merge rule applies everywhere: a string value
+ * replaces the whole subtree it names; an object refines it per key. So
+ * `files: "inline"` overrides every lower-layer file rule, while
+ * `files: { default: "inline" }` keeps lower-layer MIME exceptions.
+ */
+export type PersonaArtifactDisplayRules = {
+  default?: PersonaArtifactDisplayModeInput;
+  byKind?: Partial<
+    Record<PersonaArtifactKind, PersonaArtifactDisplayModeInput>
+  >;
+  /**
+   * @deprecated Use `byKind`. When both are present, `byKind` wins.
+   */
+  byType?: Partial<
+    Record<PersonaArtifactKind, PersonaArtifactDisplayModeInput>
+  >;
+  /** Rules for any artifact carrying file metadata. */
+  files?: PersonaArtifactDisplayModeInput | PersonaArtifactFilesDisplayRules;
+};
 
 /** Context handed to custom artifact actions. Content fields are best-effort: resolved from live session state or, after a refresh, from the persisted reference-card payload. */
 export type PersonaArtifactActionContext = {
@@ -1439,15 +1498,12 @@ export type AgentWidgetArtifactsFeature = {
   allowedTypes?: PersonaArtifactKind[];
   /**
    * Where artifact bodies render. A single mode applies to all artifacts;
-   * the object form sets a default plus per-type overrides.
+   * the object form sets a default plus scoped overrides.
    * Defaults to "panel" (current behavior).
    */
   display?:
-    | PersonaArtifactDisplayMode
-    | {
-        default?: PersonaArtifactDisplayMode;
-        byType?: Partial<Record<PersonaArtifactKind, PersonaArtifactDisplayMode>>;
-      };
+    | PersonaArtifactDisplayModeInput
+    | PersonaArtifactDisplayRules;
   /** Split / drawer dimensions and launcher widen behavior */
   layout?: AgentWidgetArtifactsLayoutConfig;
   /**
@@ -2209,6 +2265,67 @@ export type AgentWidgetFeatureFlags = {
   suggestReplies?: AgentWidgetSuggestRepliesFeature;
 };
 
+export type WidgetPreferenceCapabilities = {
+  artifacts?: boolean;
+  tools?: boolean;
+  reasoning?: boolean;
+};
+
+/**
+ * Persistable artifact-layout choices. The full layout config deliberately is
+ * not exposed because it also contains callbacks and embedder-owned chrome.
+ */
+export type WidgetArtifactLayoutPreference = Pick<
+  AgentWidgetArtifactsLayoutConfig,
+  | "paneWidth"
+  | "paneMaxWidth"
+  | "paneMinWidth"
+  | "expandLauncherPanelWhenOpen"
+  | "expandedPanelWidth"
+  | "resizable"
+  | "resizableMinWidth"
+  | "resizableMaxWidth"
+>;
+
+/**
+ * Curated, JSON-serializable display preferences in native `features` shape.
+ *
+ * Absence means inherit the next preference layer and ultimately Persona's
+ * current default. Persist only explicit choices; resetting a choice deletes
+ * its key.
+ *
+ * Capability facts (`artifacts.enabled`, `allowedTypes`), trusted iframe
+ * security, callbacks, actions, renderers, labels, and theme styling are
+ * intentionally excluded because they remain embedder/code-owned.
+ */
+export type WidgetPreferenceSlice = {
+  showToolCalls?: boolean;
+  showReasoning?: boolean;
+  toolCallDisplay?: Pick<
+    AgentWidgetToolCallDisplayFeature,
+    | "collapsedMode"
+    | "expandable"
+    | "grouped"
+    | "groupedMode"
+    | "loadingAnimation"
+  >;
+  reasoningDisplay?: Pick<
+    AgentWidgetReasoningDisplayFeature,
+    "expandable" | "activePreview"
+  >;
+  artifacts?: {
+    /**
+     * String and object forms are both persistable and mean different things
+     * when layers merge: a string replaces every lower-layer display rule; an
+     * object refines lower layers per selector key (same rule applies to
+     * `display.files`).
+     */
+    display?: PersonaArtifactDisplayModeInput | PersonaArtifactDisplayRules;
+    filePreview?: { enabled?: boolean };
+    layout?: WidgetArtifactLayoutPreference;
+  };
+};
+
 /**
  * Feature config for the built-in `suggest_replies` quick-reply chips.
  * Chips render in the existing suggestions slot above the composer and are
@@ -4902,6 +5019,15 @@ export type AgentWidgetConfig = {
    */
   colorScheme?: 'auto' | 'light' | 'dark';
   features?: AgentWidgetFeatureFlags;
+  /**
+   * Per-instance display overrides, applied over `features` through the
+   * preference allowlist (security/capability keys cannot pass). String
+   * `display` values replace the base rule subtree; objects refine it per
+   * key. Each `controller.update({ preferences })` replaces the previous
+   * slice wholesale (dropped keys revert to the base `features`); an
+   * explicit-undefined patch clears it entirely.
+   */
+  preferences?: WidgetPreferenceSlice;
   /**
    * When true, focus the chat input after the panel opens and the open animation completes.
    * Applies to launcher mode (user click, controller.open(), autoExpand) and inline mode (on init).
@@ -5864,6 +5990,8 @@ export type PersonaArtifactRecord = {
   props?: Record<string, unknown>;
   /** Present when this markdown artifact is a previewable file (see PersonaArtifactFileMeta). */
   file?: PersonaArtifactFileMeta;
+  /** Optional presentation metadata such as the producer's display-mode hint. */
+  presentation?: PersonaArtifactPresentation;
 };
 
 /** Programmatic artifact upsert (controller / window API) */
@@ -5875,6 +6003,7 @@ export type PersonaArtifactManualUpsert =
       content: string;
       /** Optional file metadata for previewable file artifacts. */
       file?: PersonaArtifactFileMeta;
+      presentation?: PersonaArtifactPresentation;
       /** Set false to update the registry/pane without a transcript block (pre-4.x behavior). */
       transcript?: boolean;
     }
@@ -5884,6 +6013,7 @@ export type PersonaArtifactManualUpsert =
       title?: string;
       component: string;
       props?: Record<string, unknown>;
+      presentation?: PersonaArtifactPresentation;
       /** Set false to update the registry/pane without a transcript block (pre-4.x behavior). */
       transcript?: boolean;
     };

package/src/ui.artifact-pane-gating.test.ts

@@ -27,7 +27,7 @@ beforeAll(() => {
  *
  * The pane's own `update()` unhides its shell whenever records exist, so the
  * gate in `syncArtifactPane` must re-assert `persona-hidden` for artifacts
- * whose resolved mode is "card" or "inline". The original implementation only
+ * whose resolved mode is "collapsed" or "inline". The original implementation only
  * removed the class in the show branch and never re-added it, so inline-mode
  * artifacts still auto-opened the pane.
  */
@@ -88,8 +88,8 @@ describe("artifact pane auto-open gating by display mode", () => {
     controller.destroy();
   });
 
-  it('keeps the pane hidden for "card" mode until an explicit open', () => {
-    const { mount, controller } = mountWithDisplay("card");
+  it('keeps the pane hidden for "collapsed" mode until an explicit open', () => {
+    const { mount, controller } = mountWithDisplay("collapsed");
     upsertSample(controller);
     expect(paneEl(mount).classList.contains("persona-hidden")).toBe(true);
 
@@ -109,7 +109,7 @@ describe("artifact pane auto-open gating by display mode", () => {
     urlWithBlob.createObjectURL = () => "blob:persona-test";
     urlWithBlob.revokeObjectURL = () => {};
     try {
-      const { mount, controller } = mountWithDisplay("card");
+      const { mount, controller } = mountWithDisplay("collapsed");
       upsertSample(controller);
 
       // Recreate the reference card the way the default renderer shapes it
@@ -170,7 +170,7 @@ describe("artifact card custom actions (full widget)", () => {
         artifacts: {
           enabled: true,
           allowedTypes: ["markdown", "component"],
-          display: "card",
+          display: "collapsed",
           cardActions,
         },
       },

package/src/ui.config-preferences.test.ts

@@ -0,0 +1,166 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+
+import { createAgentExperience } from "./ui";
+import type {
+  AgentWidgetArtifactsFeature,
+  AgentWidgetConfig,
+  WidgetPreferenceSlice,
+} from "./types";
+
+beforeAll(() => {
+  // jsdom does not implement matchMedia; the pane's layout code touches it.
+  if (!window.matchMedia) {
+    window.matchMedia = ((query: string) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addListener: () => {},
+      removeListener: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      dispatchEvent: () => false,
+    })) as unknown as typeof window.matchMedia;
+  }
+});
+
+/**
+ * Config-level `preferences` are per-instance display overrides baked over
+ * `features` (utils/feature-preferences.ts `resolveConfigPreferences`). The
+ * pane's auto-open state is the observable for the effective display mode:
+ * "panel" opens it on upsert, "inline"/"collapsed" keep it hidden.
+ *
+ * The update() path must re-resolve from the pre-preference base features:
+ * changing or clearing preferences may not stack onto previously overlaid
+ * values.
+ */
+describe("config preferences overrides", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    try {
+      window.localStorage.clear();
+    } catch {
+      /* jsdom edge cases */
+    }
+  });
+
+  function mountWith(
+    display: AgentWidgetArtifactsFeature["display"],
+    preferences?: WidgetPreferenceSlice
+  ) {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+    const config: AgentWidgetConfig = {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      features: {
+        artifacts: {
+          enabled: true,
+          allowedTypes: ["markdown", "component"],
+          ...(display ? { display } : {}),
+        },
+      },
+      ...(preferences ? { preferences } : {}),
+    };
+    const controller = createAgentExperience(mount, config);
+    return { mount, controller };
+  }
+
+  function paneHidden(mount: HTMLElement): boolean {
+    const el = mount.querySelector<HTMLElement>(".persona-artifact-pane");
+    expect(el).not.toBeNull();
+    return el!.classList.contains("persona-hidden");
+  }
+
+  function upsertSample(
+    controller: ReturnType<typeof createAgentExperience>,
+    id = "prefs-test"
+  ) {
+    controller.upsertArtifact({
+      id,
+      title: "Preferences test",
+      artifactType: "markdown",
+      content: "# Hello",
+    });
+  }
+
+  it("applies initial preferences over base features", () => {
+    // Base says panel (auto-open); the instance preference says inline.
+    const { mount, controller } = mountWith("panel", {
+      artifacts: { display: "inline" },
+    });
+    upsertSample(controller);
+    expect(paneHidden(mount)).toBe(true);
+    controller.destroy();
+  });
+
+  it("applies preferences passed through controller.update()", () => {
+    const { mount, controller } = mountWith("panel");
+    controller.update({ preferences: { artifacts: { display: "collapsed" } } });
+    upsertSample(controller);
+    expect(paneHidden(mount)).toBe(true);
+    controller.destroy();
+  });
+
+  // A "panel" upsert marks the pane user-opened, which is sticky by design,
+  // so the remaining tests observe the effective mode through the transcript
+  // block type instead: refreshArtifactReferenceBlocks re-materializes blocks
+  // on a live display change ("inline" → .persona-artifact-inline preview,
+  // otherwise the reference card).
+  function inlineBlockCount(mount: HTMLElement): number {
+    return mount.querySelectorAll(".persona-artifact-inline").length;
+  }
+
+  it("clearing preferences reverts to the base features", () => {
+    const { mount, controller } = mountWith("inline", {
+      artifacts: { display: "panel" },
+    });
+    upsertSample(controller);
+    expect(inlineBlockCount(mount)).toBe(0);
+
+    // Explicit-undefined deletes the key (config-merge reset semantics); the
+    // effective mode must fall back to the base "inline", not keep "panel".
+    controller.update({ preferences: undefined });
+    expect(inlineBlockCount(mount)).toBe(1);
+    controller.destroy();
+  });
+
+  it("an update's slice replaces the previous slice; dropped keys revert", () => {
+    const { mount, controller } = mountWith("collapsed");
+    controller.update({
+      preferences: {
+        showReasoning: false,
+        artifacts: { display: "inline" },
+      },
+    });
+    upsertSample(controller);
+    expect(inlineBlockCount(mount)).toBe(1);
+
+    // The new slice keeps showReasoning but drops the artifacts key. Patch
+    // semantics would strand display:"inline"; replace semantics revert the
+    // block to the base "collapsed" card.
+    controller.update({ preferences: { showReasoning: false } });
+    expect(inlineBlockCount(mount)).toBe(0);
+    controller.destroy();
+  });
+
+  it("replacing preferences re-resolves from the base, not the prior overlay", () => {
+    const { mount, controller } = mountWith(
+      { default: "collapsed", byKind: { markdown: "inline" } },
+      { artifacts: { display: "panel" } }
+    );
+    upsertSample(controller);
+    expect(inlineBlockCount(mount)).toBe(0);
+
+    // The object-form preference refines the base, so byKind.markdown →
+    // "inline" survives and the block converts to an inline preview. If the
+    // prior "panel" string overlay had been folded into the base, byKind
+    // would be gone and this would resolve "collapsed" (a card).
+    controller.update({
+      preferences: { artifacts: { display: { default: "collapsed" } } },
+    });
+    expect(inlineBlockCount(mount)).toBe(1);
+    controller.destroy();
+  });
+});

package/src/ui.ts

@@ -91,7 +91,7 @@ import { buildHeaderWithLayout } from "./components/header-layouts";
 import { positionMap } from "./utils/positioning";
 import type { HeaderElements as _HeaderElements, ComposerElements as _ComposerElements } from "./components/panel";
 import { MessageTransform, MessageActionCallbacks, LoadingIndicatorRenderer } from "./components/message-bubble";
-import { createStandardBubble, createTypingIndicator } from "./components/message-bubble";
+import { createStandardBubble, createTypingIndicator, getBubbleClasses } from "./components/message-bubble";
 import { createReasoningBubble, reasoningExpansionState, updateReasoningBubbleUI } from "./components/reasoning-bubble";
 import { createToolBubble, toolExpansionState, updateToolBubbleUI } from "./components/tool-bubble";
 import {
@@ -133,6 +133,7 @@ import {
   shouldExpandLauncherForArtifacts
 } from "./utils/artifact-gate";
 import { resolveArtifactDisplayMode } from "./utils/artifact-display";
+import { resolveConfigPreferences } from "./utils/feature-preferences";
 import { readFlexGapPx, resolveArtifactPaneWidthPx } from "./utils/artifact-resize";
 import { enhanceWithForms } from "./components/forms";
 import { pluginRegistry } from "./plugins/registry";
@@ -596,6 +597,11 @@ export const createAgentExperience = (
   }
 
   let config = mergeWithDefaults(initialConfig) as AgentWidgetConfig;
+  // `config.features` holds the preference-resolved view every read site uses;
+  // `baseFeatures` keeps the pre-preference base so update() re-resolves from
+  // it instead of stacking new preferences onto already-overlaid values.
+  let baseFeatures = config.features;
+  config = resolveConfigPreferences(config);
   // Note: applyThemeVariables is called after applyFullHeightStyles() below
   // because applyFullHeightStyles resets mount.style.cssText
 
@@ -1800,7 +1806,7 @@ export const createAgentExperience = (
   let artifactPaneExpandedPinned = false;
   // Whether the user explicitly opened the pane (card click, inline Expand,
   // showArtifacts(), programmatic upsert). Auto-open is otherwise reserved for
-  // artifacts whose resolved display mode is "panel": "card" keeps the card as
+  // artifacts whose resolved display mode is "panel": "collapsed" keeps the card as
   // the only affordance and "inline" renders in the transcript. "inline" no
   // longer *auto*-opens the pane, but its Expand control is a deliberate,
   // user-driven open (setting artifactsPaneUserOpened, same as a card click);
@@ -1811,7 +1817,7 @@ export const createAgentExperience = (
     artifactsPaneUserOpened ||
     lastArtifactsState.artifacts.some(
       (a) =>
-        resolveArtifactDisplayMode(config.features?.artifacts, a.artifactType) === "panel"
+        resolveArtifactDisplayMode(config.features?.artifacts, a) === "panel"
     );
   const artifactPaneVisible = () =>
     lastArtifactsState.artifacts.length > 0 &&
@@ -2010,7 +2016,7 @@ export const createAgentExperience = (
     event.preventDefault();
     event.stopPropagation();
     artifactsPaneUserHidden = false;
-    // Card click is an explicit open: it overrides the "card"/"inline"
+    // Card click is an explicit open: it overrides the "collapsed"/"inline"
     // auto-open suppression for as long as artifacts exist.
     artifactsPaneUserOpened = true;
     session.selectArtifact(artifactId);
@@ -2518,7 +2524,7 @@ export const createAgentExperience = (
     } else if (lastArtifactsState.artifacts.length > 0 && artifactPaneCanShow()) {
       // User chose “show” again (e.g. programmatic showArtifacts): clear dismiss chrome
       // and force drawer open so narrow-host / mobile slide-out is not stuck off-screen.
-      // Artifacts whose display mode is "card" or "inline" don't auto-open the
+      // Artifacts whose display mode is "collapsed" or "inline" don't auto-open the
       // pane (artifactPaneCanShow); it stays hidden until an explicit open or
       // until a "panel"-mode artifact arrives.
       artifactPaneApi.element.classList.remove("persona-hidden");
@@ -5045,28 +5051,30 @@ export const createAgentExperience = (
 
       // Only render if we have an indicator (allows hiding via returning null)
       if (typingIndicator) {
-        // Create a bubble wrapper for the typing indicator (similar to assistant messages)
+        // Bubble wrapper for the typing indicator. It borrows the assistant
+        // bubble's classes and background so the "thinking" bubble matches the
+        // message bubbles that replace it under every layout preset.
         const typingBubble = document.createElement("div");
         const showBubble = config.loadingIndicator?.showBubble !== false; // default true
+        const messageLayout = config.layout?.messages?.layout ?? "bubble";
         typingBubble.className = showBubble
-          ? [
-              "persona-rounded-2xl",
-              "persona-text-sm",
-              "persona-leading-relaxed",
-              "persona-shadow-sm",
-              "persona-bg-persona-surface",
-              "persona-border",
-              "persona-text-persona-primary",
-              "persona-px-5",
-              "persona-py-3"
-            ].join(" ")
+          ? getBubbleClasses("assistant", messageLayout).join(" ")
           : [
               "persona-text-sm",
               "persona-leading-relaxed",
-              "persona-text-persona-primary"
+              "persona-text-persona-text"
             ].join(" ");
         typingBubble.setAttribute("data-typing-indicator", "true");
-        typingBubble.style.borderColor = "var(--persona-message-assistant-border, var(--persona-border, #e5e7eb))";
+        if (showBubble) {
+          typingBubble.style.color =
+            "var(--persona-message-assistant-text, var(--persona-text))";
+          if (messageLayout !== "flat") {
+            typingBubble.style.backgroundColor =
+              "var(--persona-message-assistant-bg, var(--persona-container))";
+            typingBubble.style.borderColor =
+              "var(--persona-message-assistant-border, var(--persona-border, #e5e7eb))";
+          }
+        }
 
         typingBubble.appendChild(typingIndicator);
 
@@ -7846,8 +7854,11 @@ export const createAgentExperience = (
       const previousStreamAnimationType = config.features?.streamAnimation?.type;
       // One consistent recursive patch policy across the live controller and the
       // init handle. See utils/config-merge.ts for the replace-leaf list and
-      // explicit-undefined reset semantics.
-      config = mergeConfigUpdate(config, nextConfig);
+      // explicit-undefined reset semantics. The patch merges over the
+      // pre-preference base features, then preferences re-resolve on top.
+      config = mergeConfigUpdate({ ...config, features: baseFeatures }, nextConfig);
+      baseFeatures = config.features;
+      config = resolveConfigPreferences(config);
       // applyFullHeightStyles resets mount.style.cssText, so call it before applyThemeVariables
       applyFullHeightStyles();
       applyThemeVariables(mount, config);
@@ -9282,13 +9293,20 @@ export const createAgentExperience = (
       if (!artifactsSidebarEnabled(config)) return null;
       // Programmatic upserts match the streamed UX: only "panel"-mode
       // artifacts auto-open the pane (overriding a previous Close), while
-      // "card"/"inline" stay calm — the injected transcript block is the
+      // "collapsed"/"inline" stay calm — the injected transcript block is the
       // affordance. Independent of `transcript: false`: pane-only callers
-      // (e.g. the theme editor preview) rely on the panel-default surfacing;
-      // callers that want the pane in a non-panel mode call showArtifacts().
+      // (e.g. the theme editor preview) rely on the auto-open default
+      // surfacing; callers that want the pane in another mode call
+      // showArtifacts().
       const mode = resolveArtifactDisplayMode(
         config.features?.artifacts,
-        manual.artifactType
+        {
+          artifactType: manual.artifactType,
+          ...(manual.artifactType === "markdown" && manual.file
+            ? { file: manual.file }
+            : {}),
+          ...(manual.presentation ? { presentation: manual.presentation } : {}),
+        }
       );
       if (mode === "panel") {
         artifactsPaneUserHidden = false;