@runtypelabs/persona 4.13.0 → 4.15.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/artifact-file.test.ts

@@ -10,7 +10,7 @@ import {
 // Canonical cross-repo fixture. The zero-width space is written as a
 // backslash-u200b escape sequence (not a literal invisible char) so the bytes
 // are unambiguous in source.
-// Mirrors core/packages/shared/src/file-artifact.ts escapeFenceTerminators fixture — keep byte-identical.
+// Mirrors core/packages/shared/src/file-artifact.ts escapeFenceTerminators fixture — keep in sync.
 const ZWSP = "\u200b";
 const FIXTURE_RAW = "# Title\n\n```js\nconsole.log('hi')\n```\n";
 const FIXTURE_ESCAPED =

package/src/utils/code-generators.test.ts

@@ -563,6 +563,46 @@ describe("Full Config with Hooks Integration", () => {
 // Backward Compatibility Tests
 // =============================================================================
 
+describe("Suggestions Serialization", () => {
+  it("preserves structured suggestion configuration in every format", () => {
+    const config = {
+      ...minimalConfig,
+      suggestions: {
+        starters: {
+          variant: "card",
+          behavior: "fill",
+          items: [
+            {
+              id: "compare",
+              label: "Compare plans",
+              prompt: "Compare plans for my team",
+            },
+          ],
+        },
+        followUps: {
+          placement: "after-message",
+          overflow: "scroll",
+        },
+      },
+    };
+    const formats: CodeFormat[] = [
+      "esm",
+      "react-component",
+      "react-advanced",
+      "script-installer",
+      "script-manual",
+      "script-advanced",
+    ];
+
+    for (const format of formats) {
+      const code = generateCodeSnippet(config, format);
+      expect(code).toContain("suggestions");
+      expect(code).toContain("Compare plans");
+      expect(code).toContain("after-message");
+    }
+  });
+});
+
 describe("Backward Compatibility", () => {
   it("should work without options parameter", () => {
     const code = generateCodeSnippet(minimalConfig, "esm");

package/src/utils/code-generators.ts

@@ -430,6 +430,19 @@ function generateMarkdownConfig(config: any, indent: string): string[] {
   return lines;
 }
 
+// Suggestions may contain nested rich items. JSON object syntax is also valid
+// JavaScript/TypeScript, so preserve the complete public shape instead of
+// duplicating every leaf in each output-format generator.
+function generateSuggestionsConfig(config: any, indent: string): string[] {
+  if (!config.suggestions) return [];
+  const serialized = JSON.stringify(config.suggestions, null, 2).split("\n");
+  return serialized.map((line, index) => {
+    const prefix = index === 0 ? `${indent}suggestions: ` : indent;
+    const suffix = index === serialized.length - 1 ? "," : "";
+    return `${prefix}${line}${suffix}`;
+  });
+}
+
 // Helper to generate layout config (excluding render functions and slots)
 function generateLayoutConfig(config: any, indent: string): string[] {
   const lines: string[] = [];
@@ -697,6 +710,8 @@ function generateESMCode(config: any, options?: CodeGeneratorOptions): string {
     lines.push("    },");
   }
 
+  lines.push(...generateSuggestionsConfig(config, "    "));
+
   if (config.suggestionChips && config.suggestionChips.length > 0) {
     lines.push("    suggestionChips: [");
     config.suggestionChips.forEach((chip: string) => {
@@ -845,6 +860,8 @@ function generateReactComponentCode(config: any, options?: CodeGeneratorOptions)
     lines.push("        },");
   }
 
+  lines.push(...generateSuggestionsConfig(config, "        "));
+
   if (config.suggestionChips && config.suggestionChips.length > 0) {
     lines.push("        suggestionChips: [");
     config.suggestionChips.forEach((chip: string) => {
@@ -1110,6 +1127,8 @@ function generateReactAdvancedCode(config: any, options?: CodeGeneratorOptions):
     lines.push("        },");
   }
 
+  lines.push(...generateSuggestionsConfig(config, "        "));
+
   if (config.suggestionChips && config.suggestionChips.length > 0) {
     lines.push("        suggestionChips: [");
     config.suggestionChips.forEach((chip: string) => {
@@ -1312,6 +1331,7 @@ function buildSerializableConfig(config: any): Record<string, any> {
   if (config.voiceRecognition) serializableConfig.voiceRecognition = config.voiceRecognition;
   if (config.statusIndicator) serializableConfig.statusIndicator = config.statusIndicator;
   if (config.features) serializableConfig.features = config.features;
+  if (config.suggestions) serializableConfig.suggestions = config.suggestions;
   if (config.suggestionChips?.length > 0) serializableConfig.suggestionChips = config.suggestionChips;
   if (config.suggestionChipsConfig) serializableConfig.suggestionChipsConfig = config.suggestionChipsConfig;
   if (config.debug) serializableConfig.debug = config.debug;
@@ -1520,6 +1540,8 @@ function generateScriptManualCode(config: any, options?: CodeGeneratorOptions):
     lines.push("      },");
   }
 
+  lines.push(...generateSuggestionsConfig(config, "      "));
+
   if (config.suggestionChips && config.suggestionChips.length > 0) {
     lines.push("      suggestionChips: [");
     config.suggestionChips.forEach((chip: string) => {

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

@@ -32,6 +32,30 @@ describe("mergeConfigUpdate", () => {
     expect(next.suggestionChips).toEqual(["x"]);
   });
 
+  it("patches suggestion surfaces without dropping sibling behavior", () => {
+    const prev = base({
+      suggestions: {
+        starters: { variant: "card", behavior: "fill" },
+        followUps: { variant: "chip", placement: "after-message" },
+      },
+    });
+    const next = mergeConfigUpdate(prev, {
+      suggestions: {
+        followUps: { overflow: "wrap" },
+      },
+    });
+
+    expect(next.suggestions?.starters).toEqual({
+      variant: "card",
+      behavior: "fill",
+    });
+    expect(next.suggestions?.followUps).toEqual({
+      variant: "chip",
+      placement: "after-message",
+      overflow: "wrap",
+    });
+  });
+
   it("replaces callbacks wholesale", () => {
     const first = vi.fn();
     const second = vi.fn();
@@ -66,6 +90,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