@runtypelabs/persona 4.13.0 → 4.14.0

package/src/ui.typing-indicator.test.ts

@@ -0,0 +1,135 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+/**
+ * Mount a widget with a never-resolving fetch, send a message, and return the
+ * standalone typing indicator bubble rendered during the silent gap.
+ */
+const renderTypingBubble = async (
+  config: Record<string, unknown>
+): Promise<{ bubble: HTMLElement; destroy: () => void }> => {
+  global.fetch = vi.fn().mockImplementation(
+    () => new Promise(() => {})
+  ) as unknown as typeof fetch;
+
+  const mount = createMount();
+  const controller = createAgentExperience(mount, {
+    apiUrl: "https://api.example.com/chat",
+    launcher: { enabled: false },
+    ...config,
+  } as unknown as Parameters<typeof createAgentExperience>[1]);
+
+  controller.submitMessage("hello");
+  await Promise.resolve();
+  await Promise.resolve();
+
+  const bubble = mount.querySelector<HTMLElement>('[data-typing-indicator="true"]')!;
+  return { bubble, destroy: () => controller.destroy() };
+};
+
+describe("standalone typing indicator bubble", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    if (typeof localStorage !== "undefined") localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("uses the assistant bubble classes under the default bubble layout", async () => {
+    const { bubble, destroy } = await renderTypingBubble({});
+
+    expect(bubble).not.toBeNull();
+    expect(bubble.classList.contains("persona-message-assistant-bubble")).toBe(true);
+    expect(bubble.classList.contains("persona-shadow-sm")).toBe(true);
+    expect(bubble.classList.contains("persona-border")).toBe(true);
+    expect(bubble.classList.contains("persona-px-5")).toBe(true);
+
+    destroy();
+  });
+
+  it("drops the shadow and border under the minimal layout", async () => {
+    const { bubble, destroy } = await renderTypingBubble({
+      layout: { messages: { layout: "minimal" } },
+    });
+
+    expect(bubble.classList.contains("persona-message-assistant-bubble")).toBe(true);
+    expect(bubble.classList.contains("persona-shadow-sm")).toBe(false);
+    expect(bubble.classList.contains("persona-border")).toBe(false);
+    expect(bubble.classList.contains("persona-px-3")).toBe(true);
+    // Minimal keeps the surface background, matching its message bubbles.
+    expect(bubble.style.backgroundColor).toContain("--persona-message-assistant-bg");
+
+    destroy();
+  });
+
+  it("drops the background entirely under the flat layout", async () => {
+    const { bubble, destroy } = await renderTypingBubble({
+      layout: { messages: { layout: "flat" } },
+    });
+
+    expect(bubble.classList.contains("persona-shadow-sm")).toBe(false);
+    expect(bubble.classList.contains("persona-border")).toBe(false);
+    expect(bubble.style.backgroundColor).toBe("");
+    expect(bubble.style.color).toBe(
+      "var(--persona-message-assistant-text, var(--persona-text))"
+    );
+
+    destroy();
+  });
+
+  it("renders bare text classes when loadingIndicator.showBubble is false", async () => {
+    const { bubble, destroy } = await renderTypingBubble({
+      loadingIndicator: { showBubble: false },
+    });
+
+    expect(bubble.classList.contains("persona-message-assistant-bubble")).toBe(false);
+    expect(bubble.classList.contains("persona-shadow-sm")).toBe(false);
+    expect(bubble.classList.contains("persona-border")).toBe(false);
+    expect(bubble.classList.contains("persona-text-persona-text")).toBe(true);
+    expect(bubble.classList.contains("persona-text-persona-primary")).toBe(false);
+    expect(bubble.style.backgroundColor).toBe("");
+
+    destroy();
+  });
+
+  it("honors the assistant bubble theme background token", async () => {
+    const { bubble, destroy } = await renderTypingBubble({
+      layout: { messages: { layout: "minimal" } },
+      theme: {
+        semantic: {
+          colors: {
+            container: "#112233",
+            text: "#ddeeff",
+            border: "#445566",
+          },
+        },
+      },
+    });
+
+    // The bubble reads the same variable the assistant message bubbles read,
+    // so `theme.components.message.assistant.background` covers both.
+    expect(bubble.style.backgroundColor).toBe(
+      "var(--persona-message-assistant-bg, var(--persona-container))"
+    );
+    const root = bubble.closest<HTMLElement>("[data-persona-root]");
+    expect(root?.style.getPropertyValue("--persona-message-assistant-bg")).toBe(
+      "#112233"
+    );
+    expect(root?.style.getPropertyValue("--persona-message-assistant-text")).toBe(
+      "#ddeeff"
+    );
+    expect(root?.style.getPropertyValue("--persona-message-assistant-border")).toBe(
+      "#445566"
+    );
+
+    destroy();
+  });
+});

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/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