@runtypelabs/persona 4.12.0 → 4.14.0

package/src/utils/artifact-display.test.ts

@@ -1,42 +1,206 @@
 import { describe, it, expect } from "vitest";
-import { resolveArtifactDisplayMode } from "./artifact-display";
+import {
+  resolveArtifactDisplay,
+  resolveArtifactDisplayMode,
+} from "./artifact-display";
 
 describe("resolveArtifactDisplayMode", () => {
+  const markdown = { artifactType: "markdown" as const };
+  const component = { artifactType: "component" as const };
+
   it("returns 'panel' when the feature is undefined", () => {
-    expect(resolveArtifactDisplayMode(undefined, "markdown")).toBe("panel");
+    expect(resolveArtifactDisplayMode(undefined, markdown)).toBe("panel");
   });
 
   it("returns 'panel' when display is unset", () => {
-    expect(resolveArtifactDisplayMode({ enabled: true }, "markdown")).toBe("panel");
+    expect(resolveArtifactDisplayMode({ enabled: true }, markdown)).toBe("panel");
+  });
+
+  it("canonicalizes the deprecated 'card' alias to 'collapsed'", () => {
+    expect(resolveArtifactDisplayMode({ display: "card" }, markdown)).toBe(
+      "collapsed"
+    );
+    expect(
+      resolveArtifactDisplayMode(
+        { display: { files: "card" } },
+        {
+          artifactType: "markdown",
+          file: { path: "a.txt", mimeType: "text/plain" },
+        }
+      )
+    ).toBe("collapsed");
+    expect(
+      resolveArtifactDisplayMode(
+        { display: { byKind: { component: "card" } } },
+        component
+      )
+    ).toBe("collapsed");
   });
 
   it("returns the string form directly", () => {
-    expect(resolveArtifactDisplayMode({ display: "inline" }, "markdown")).toBe("inline");
-    expect(resolveArtifactDisplayMode({ display: "card" }, "component")).toBe("card");
+    expect(resolveArtifactDisplayMode({ display: "inline" }, markdown)).toBe("inline");
+    expect(resolveArtifactDisplayMode({ display: "collapsed" }, component)).toBe("collapsed");
   });
 
-  it("uses the object default when no byType entry matches", () => {
-    expect(resolveArtifactDisplayMode({ display: { default: "card" } }, "markdown")).toBe("card");
+  it("uses the object default when no byKind entry matches", () => {
+    expect(resolveArtifactDisplayMode({ display: { default: "collapsed" } }, markdown)).toBe("collapsed");
   });
 
-  it("prefers a byType override over the default", () => {
+  it("prefers a byKind override over the default", () => {
     const feature = {
-      display: { default: "panel" as const, byType: { markdown: "inline" as const } }
+      display: { default: "panel" as const, byKind: { markdown: "inline" as const } }
     };
-    expect(resolveArtifactDisplayMode(feature, "markdown")).toBe("inline");
+    expect(resolveArtifactDisplayMode(feature, markdown)).toBe("inline");
   });
 
-  it("falls back to the default on a byType miss", () => {
+  it("falls back to the default on a byKind miss", () => {
     const feature = {
-      display: { default: "card" as const, byType: { markdown: "inline" as const } }
+      display: { default: "collapsed" as const, byKind: { markdown: "inline" as const } }
     };
-    expect(resolveArtifactDisplayMode(feature, "component")).toBe("card");
+    expect(resolveArtifactDisplayMode(feature, component)).toBe("collapsed");
   });
 
-  it("returns 'panel' for an object with neither default nor a matching byType", () => {
-    expect(resolveArtifactDisplayMode({ display: {} }, "markdown")).toBe("panel");
+  it("returns 'panel' for an object with neither default nor a matching byKind", () => {
+    expect(resolveArtifactDisplayMode({ display: {} }, markdown)).toBe("panel");
     expect(
-      resolveArtifactDisplayMode({ display: { byType: { component: "inline" } } }, "markdown")
+      resolveArtifactDisplayMode({ display: { byKind: { component: "inline" } } }, markdown)
     ).toBe("panel");
   });
+
+  it("supports deprecated byType but lets canonical byKind win", () => {
+    const feature = {
+      display: {
+        byType: { component: "collapsed" as const },
+        byKind: { component: "inline" as const },
+      },
+    };
+    expect(resolveArtifactDisplayMode(feature, component)).toBe("inline");
+  });
+
+  it("resolves exact MIME, wildcard MIME, files default, kind, and default precedence", () => {
+    const feature = {
+      display: {
+        default: "collapsed" as const,
+        byKind: { component: "panel" as const },
+        files: {
+          default: "collapsed" as const,
+          byMediaType: {
+            "text/html": "inline" as const,
+            "image/*": "panel" as const,
+          },
+        },
+      },
+    };
+    expect(
+      resolveArtifactDisplayMode(feature, {
+        artifactType: "markdown",
+        file: { path: "a.html", mimeType: "Text/HTML; charset=utf-8" },
+      })
+    ).toBe("inline");
+    expect(
+      resolveArtifactDisplayMode(feature, {
+        artifactType: "markdown",
+        file: { path: "chart.png", mimeType: "image/png" },
+      })
+    ).toBe("panel");
+    expect(
+      resolveArtifactDisplayMode(feature, {
+        artifactType: "markdown",
+        file: { path: "a.txt", mimeType: "text/plain" },
+      })
+    ).toBe("collapsed");
+    expect(resolveArtifactDisplayMode(feature, component)).toBe("panel");
+    expect(resolveArtifactDisplayMode(feature, markdown)).toBe("collapsed");
+  });
+
+  it("prefers an exact MIME rule over a wildcard for the same major type", () => {
+    const feature = {
+      display: {
+        files: {
+          byMediaType: {
+            "image/*": "collapsed" as const,
+            "image/svg+xml": "inline" as const,
+          },
+        },
+      },
+    };
+    expect(
+      resolveArtifactDisplayMode(feature, {
+        artifactType: "markdown",
+        file: { path: "logo.svg", mimeType: "image/svg+xml" },
+      })
+    ).toBe("inline");
+  });
+
+  it("applies a files string to every file-backed artifact", () => {
+    const feature = { display: { files: "inline" as const } };
+    expect(
+      resolveArtifactDisplayMode(feature, {
+        artifactType: "markdown",
+        file: { path: "a.csv", mimeType: "text/csv" },
+      })
+    ).toBe("inline");
+    expect(resolveArtifactDisplayMode(feature, markdown)).toBe("panel");
+  });
+
+  it("honors the producer preferredMode hint over defaults but not explicit rules", () => {
+    const hinted = {
+      artifactType: "markdown" as const,
+      presentation: { preferredMode: "inline" as const },
+    };
+    expect(resolveArtifactDisplayMode(undefined, hinted)).toBe("inline");
+    expect(resolveArtifactDisplayMode({ display: "collapsed" }, hinted)).toBe(
+      "inline"
+    );
+    expect(
+      resolveArtifactDisplayMode({ display: { default: "collapsed" } }, hinted)
+    ).toBe("inline");
+    expect(
+      resolveArtifactDisplayMode(
+        { display: { byKind: { markdown: "panel" } } },
+        hinted
+      )
+    ).toBe("panel");
+    expect(
+      resolveArtifactDisplayMode(
+        { display: { files: "panel" } },
+        { ...hinted, file: { path: "a.txt", mimeType: "text/plain" } }
+      )
+    ).toBe("panel");
+  });
+
+  it("returns the winning rule and configured selector for explainable host UI", () => {
+    expect(
+      resolveArtifactDisplay(
+        {
+          display: {
+            files: {
+              default: "panel",
+              byMediaType: { "text/html": "inline" },
+            },
+          },
+        },
+        {
+          artifactType: "markdown",
+          file: { path: "a.html", mimeType: "Text/HTML; charset=utf-8" },
+        }
+      )
+    ).toEqual({
+      mode: "inline",
+      matchedBy: {
+        type: "mediaType",
+        mediaType: "text/html",
+        selector: "text/html",
+      },
+    });
+    expect(
+      resolveArtifactDisplay(
+        { display: { files: { byMediaType: { "image/*": "inline" } } } },
+        {
+          artifactType: "markdown",
+          file: { path: "a.png", mimeType: "image/png" },
+        }
+      ).matchedBy
+    ).toEqual({ type: "mediaType", mediaType: "image/png", selector: "image/*" });
+  });
 });

package/src/utils/artifact-display.ts

@@ -1,27 +1,166 @@
 import type {
   AgentWidgetArtifactsFeature,
   PersonaArtifactDisplayMode,
-  PersonaArtifactFileMeta
+  PersonaArtifactDisplayModeInput,
+  PersonaArtifactFileMeta,
+  PersonaArtifactKind,
+  PersonaArtifactPresentation,
+  PersonaArtifactRecord,
 } from "../types";
 
+/** Canonicalize the deprecated `"card"` alias to `"collapsed"`. */
+export function canonicalArtifactDisplayMode(
+  mode: PersonaArtifactDisplayModeInput
+): PersonaArtifactDisplayMode {
+  return mode === "card" ? "collapsed" : mode;
+}
+
+export type PersonaArtifactDisplayDescriptor = Pick<
+  PersonaArtifactRecord,
+  "artifactType" | "file" | "presentation"
+>;
+
+export type PersonaArtifactDisplayMatch =
+  /** `selector` is the configured `byMediaType` key ("text/html" or "image/*"). */
+  | { type: "mediaType"; mediaType: string; selector: string }
+  | { type: "files" }
+  | {
+      type: "kind";
+      kind: PersonaArtifactKind;
+      configuredBy: "byKind" | "byType";
+    }
+  | { type: "preferredMode" }
+  | { type: "default" }
+  | { type: "personaDefault" };
+
+export type PersonaArtifactDisplayResolution = {
+  mode: PersonaArtifactDisplayMode;
+  matchedBy: PersonaArtifactDisplayMatch;
+};
+
+export function normalizeMediaType(mediaType: string): string {
+  return mediaType.split(";", 1)[0].trim().toLowerCase();
+}
+
+function matchMediaType(
+  byMediaType: Record<string, PersonaArtifactDisplayModeInput> | undefined,
+  mediaType: string
+): { mode: PersonaArtifactDisplayMode; selector: string } | undefined {
+  if (!byMediaType) return undefined;
+  const entries = Object.entries(byMediaType);
+  for (const [candidate, mode] of entries) {
+    if (normalizeMediaType(candidate) === mediaType) {
+      return {
+        mode: canonicalArtifactDisplayMode(mode),
+        selector: normalizeMediaType(candidate),
+      };
+    }
+  }
+  const wildcard = `${mediaType.split("/", 1)[0]}/*`;
+  for (const [candidate, mode] of entries) {
+    if (normalizeMediaType(candidate) === wildcard) {
+      return { mode: canonicalArtifactDisplayMode(mode), selector: wildcard };
+    }
+  }
+  return undefined;
+}
+
 /**
- * Resolves the display mode for an artifact of the given type from
- * `features.artifacts.display`.
+ * Resolve an artifact's display mode together with the rule that selected it.
+ * Always returns a canonical mode ("card" inputs resolve as "collapsed").
  *
- * Resolution order: `display.byType[artifactType]`, else `display.default`,
- * else `display` (string form), else `"panel"` (current behavior).
+ * Resolution order: file rules (exact MIME, then `major/*` wildcard, then the
+ * files default), kind, the producer's `presentation.preferredMode` hint,
+ * configured default, then `"panel"`.
+ */
+export function resolveArtifactDisplay(
+  feature: AgentWidgetArtifactsFeature | undefined,
+  artifact: PersonaArtifactDisplayDescriptor
+): PersonaArtifactDisplayResolution {
+  const display = feature?.display;
+  const rules =
+    typeof display === "string" ? { default: display } : display ?? {};
+
+  if (artifact.file && rules.files) {
+    if (typeof rules.files === "string") {
+      return {
+        mode: canonicalArtifactDisplayMode(rules.files),
+        matchedBy: { type: "files" },
+      };
+    }
+    const mediaType = artifact.file.mimeType
+      ? normalizeMediaType(artifact.file.mimeType)
+      : undefined;
+    const byMediaType = mediaType
+      ? matchMediaType(rules.files.byMediaType, mediaType)
+      : undefined;
+    if (mediaType && byMediaType) {
+      return {
+        mode: byMediaType.mode,
+        matchedBy: {
+          type: "mediaType",
+          mediaType,
+          selector: byMediaType.selector,
+        },
+      };
+    }
+    if (rules.files.default) {
+      return {
+        mode: canonicalArtifactDisplayMode(rules.files.default),
+        matchedBy: { type: "files" },
+      };
+    }
+  }
+
+  const byKind = rules.byKind?.[artifact.artifactType];
+  if (byKind) {
+    return {
+      mode: canonicalArtifactDisplayMode(byKind),
+      matchedBy: {
+        type: "kind",
+        kind: artifact.artifactType,
+        configuredBy: "byKind",
+      },
+    };
+  }
+  const byType = rules.byType?.[artifact.artifactType];
+  if (byType) {
+    return {
+      mode: canonicalArtifactDisplayMode(byType),
+      matchedBy: {
+        type: "kind",
+        kind: artifact.artifactType,
+        configuredBy: "byType",
+      },
+    };
+  }
+
+  const preferred = artifact.presentation?.preferredMode;
+  if (preferred) {
+    return {
+      mode: canonicalArtifactDisplayMode(preferred),
+      matchedBy: { type: "preferredMode" },
+    };
+  }
+
+  if (rules.default) {
+    return {
+      mode: canonicalArtifactDisplayMode(rules.default),
+      matchedBy: { type: "default" },
+    };
+  }
+  return { mode: "panel", matchedBy: { type: "personaDefault" } };
+}
+
+/**
+ * Resolve only the mode. Use `resolveArtifactDisplay` when a host needs to
+ * explain which rule selected it.
  */
 export function resolveArtifactDisplayMode(
   feature: AgentWidgetArtifactsFeature | undefined,
-  artifactType: string
+  artifact: PersonaArtifactDisplayDescriptor
 ): PersonaArtifactDisplayMode {
-  const display = feature?.display;
-  if (!display) return "panel";
-  if (typeof display === "string") return display;
-  const byType = display.byType as
-    | Partial<Record<string, PersonaArtifactDisplayMode>>
-    | undefined;
-  return byType?.[artifactType] ?? display.default ?? "panel";
+  return resolveArtifactDisplay(feature, artifact).mode;
 }
 
 /** Props embedded in an in-thread artifact block's rawContent JSON. */
@@ -32,6 +171,7 @@ export type ArtifactRefBlockProps = {
   status: "streaming" | "complete";
   /** File metadata for previewable file artifacts (persists the download path). */
   file?: PersonaArtifactFileMeta;
+  presentation?: PersonaArtifactPresentation;
   /**
    * Component name for component-type artifacts. Only embedded for the
    * "inline" display mode: the inline block renders component artifacts
@@ -54,7 +194,7 @@ export type ArtifactRefBlockProps = {
  * Builds the `rawContent` JSON for the synthetic assistant message that
  * anchors an artifact in the transcript (message id `artifact-ref-<id>`).
  *
- * "card"/"panel" modes render the compact `PersonaArtifactCard`; "inline"
+ * "collapsed"/"panel" modes render the compact `PersonaArtifactCard`; "inline"
  * renders the `PersonaArtifactInline` preview block. Both share this shape so
  * transcript persistence and hydration work unchanged. Used by the streaming
  * client (`artifact_start`) and the programmatic `session.upsertArtifact()`.
@@ -72,6 +212,7 @@ export function buildArtifactRefRawContent(
       artifactType: props.artifactType,
       status: props.status,
       ...(props.file ? { file: props.file } : {}),
+      ...(props.presentation ? { presentation: props.presentation } : {}),
       ...(displayMode === "inline" && props.component
         ? { component: props.component }
         : {}),

package/src/utils/auto-follow.test.ts

@@ -6,10 +6,12 @@ import {
   createFollowStateController,
   getScrollBottomOffset,
   hasSelectionWithin,
+  isAttentionWorthyMessage,
   isElementNearBottom,
   resolveFollowStateFromScroll,
   resolveFollowStateFromWheel
 } from "./auto-follow";
+import type { AgentWidgetMessage } from "../types";
 
 describe("auto-follow utilities", () => {
   it("tracks pause and resume state", () => {
@@ -199,3 +201,39 @@ describe("auto-follow utilities", () => {
     ).toBe("resume");
   });
 });
+
+describe("isAttentionWorthyMessage", () => {
+  const msg = (over: Partial<AgentWidgetMessage>): AgentWidgetMessage => ({
+    id: "m",
+    role: "assistant",
+    content: "",
+    createdAt: "2026-07-28T00:00:00.000Z",
+    ...over,
+  });
+
+  it("treats prose, artifacts/components, images and approvals as output", () => {
+    expect(isAttentionWorthyMessage(msg({ content: "Here is the answer." }))).toBe(true);
+    // Artifact / component blocks carry their payload in rawContent with an
+    // empty `content` — the case a text-only test silently drops.
+    expect(
+      isAttentionWorthyMessage(msg({ rawContent: '{"component":"Chart","props":{}}' }))
+    ).toBe(true);
+    expect(
+      isAttentionWorthyMessage(
+        msg({ contentParts: [{ type: "image", image: "data:image/png;base64,x" }] as never })
+      )
+    ).toBe(true);
+    // Blocked on the reader deciding: must never sit off-screen.
+    expect(isAttentionWorthyMessage(msg({ variant: "approval" }))).toBe(true);
+  });
+
+  it("treats tool calls and reasoning as progress chrome", () => {
+    expect(isAttentionWorthyMessage(msg({ variant: "tool", content: "searching" }))).toBe(false);
+    expect(isAttentionWorthyMessage(msg({ variant: "reasoning", content: "thinking" }))).toBe(false);
+  });
+
+  it("skips the empty streaming placeholder and non-assistant roles", () => {
+    expect(isAttentionWorthyMessage(msg({ content: "   " }))).toBe(false);
+    expect(isAttentionWorthyMessage(msg({ role: "user", content: "hi" }))).toBe(false);
+  });
+});

package/src/utils/auto-follow.ts

@@ -1,3 +1,38 @@
+import type { AgentWidgetMessage } from "../types";
+
+/**
+ * Is this message *output a human came for*, as opposed to progress chrome?
+ *
+ * This is the classifier behind anchor-top's "first unread" positioning: the
+ * transcript anchors to the first attention-worthy block of a response and
+ * leaves everything else to scroll past underneath. Two categories:
+ *
+ * - **Chrome** — tool calls and reasoning. Rendered so the reader *can* audit
+ *   the work, never positioned to. A response that opens with six tool calls
+ *   should not park the reader on the sixth one.
+ * - **Attention-worthy** — anything that carries the answer: prose, an
+ *   artifact or component block (charts, forms, documents — these carry their
+ *   payload in `rawContent` with an EMPTY `content`, so testing text alone
+ *   silently drops them), multi-modal parts (images), and approval requests
+ *   (which are the strongest case of all: the turn is blocked on the reader
+ *   deciding, so it must never sit off-screen).
+ *
+ * The empty streaming placeholder — an assistant bubble created at
+ * `text_start` before its first token — is deliberately NOT attention-worthy,
+ * so the anchor waits for content rather than jumping to a blank bubble.
+ */
+export function isAttentionWorthyMessage(message: AgentWidgetMessage): boolean {
+  if (message.role !== "assistant") return false;
+  if (message.variant === "tool" || message.variant === "reasoning") return false;
+  // Blocked on the reader: attention-worthy even with no text of its own.
+  if (message.variant === "approval") return true;
+  return Boolean(
+    message.content?.trim() ||
+      message.rawContent?.trim() ||
+      message.contentParts?.length
+  );
+}
+
 export type FollowStateAction = "none" | "pause" | "resume";
 
 export type FollowStateController = {

package/src/utils/config-merge.test.ts

@@ -66,6 +66,66 @@ describe("mergeConfigUpdate", () => {
     expect(next.features?.streamAnimation?.plugins?.p1).toBeUndefined();
   });
 
+  it("replaces artifact display scope maps so reset preferences do not strand stale keys", () => {
+    const previous = mergeWithDefaults({
+      features: {
+        artifacts: {
+          enabled: true,
+          display: {
+            default: "card",
+            files: {
+              byMediaType: {
+                "text/html": "inline",
+                "text/csv": "inline",
+              },
+            },
+          },
+        },
+      },
+    });
+
+    const next = mergeConfigUpdate(previous, {
+      features: {
+        artifacts: {
+          display: {
+            default: "card",
+            files: {
+              byMediaType: {
+                "text/csv": "panel",
+              },
+            },
+          },
+        },
+      },
+    });
+
+    expect(next.features?.artifacts?.display).toEqual({
+      default: "card",
+      files: {
+        byMediaType: {
+          "text/csv": "panel",
+        },
+      },
+    });
+  });
+
+  it("replaces the preferences slice wholesale so dropped overrides do not strand", () => {
+    const prev = base({
+      preferences: {
+        showToolCalls: false,
+        artifacts: { display: "inline", filePreview: { enabled: false } },
+      },
+    });
+    // The host's new slice dropped showToolCalls and filePreview: both must go.
+    const next = mergeConfigUpdate(prev, {
+      preferences: { artifacts: { display: "inline" } },
+    });
+    expect(next.preferences).toEqual({ artifacts: { display: "inline" } });
+    // Explicit-undefined still clears the whole slice.
+    const cleared = mergeConfigUpdate(next, { preferences: undefined });
+    expect(cleared.preferences).toBeUndefined();
+  });
+
   it("replaces storageAdapter wholesale (no hybrid: new adapter's absent save is not inherited)", () => {
     const oldSave = vi.fn();
     const oldLoad = vi.fn();

package/src/utils/config-merge.ts

@@ -9,9 +9,12 @@ const isPlainObject = (value: unknown): value is Record<string, unknown> =>
 
 // Dotted paths whose plain-object value replaces wholesale instead of recursing.
 // - user-defined key maps: recursive merge would strand stale keys from the old value
-//   (headers, targetProviders, components, features.streamAnimation.plugins).
+//   (headers, targetProviders, components, artifact display scopes,
+//   features.streamAnimation.plugins).
 // - implementation objects: partial merge splices two impls into a broken hybrid
 //   (agent, storageAdapter, voiceRecognition.provider.custom).
+// - preferences: the sparse slice a host passes IS its full opinion; recursive
+//   merge would keep overrides the host dropped from its slice.
 const REPLACE_LEAF_PATHS = new Set<string>([
   "headers",
   "agent",
@@ -19,7 +22,9 @@ const REPLACE_LEAF_PATHS = new Set<string>([
   "components",
   "targetProviders",
   "voiceRecognition.provider.custom",
+  "features.artifacts.display",
   "features.streamAnimation.plugins",
+  "preferences",
 ]);
 
 // Recursive patch merge. A key merges recursively iff both previous and patch