@runtypelabs/persona 4.12.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();
+  });
+});