@runtypelabs/persona 4.7.0 → 4.9.0

package/src/client.ts

@@ -21,10 +21,15 @@ import {
   ClientFeedbackRequest,
   ClientFeedbackType,
   PersonaArtifactKind,
+  PersonaArtifactFileMeta,
   ContentPart,
   WebMcpConfirmHandler
 } from "./types";
 import { WebMcpBridge, computeClientToolsFingerprint, isWebMcpToolName } from "./webmcp-bridge";
+import {
+  buildArtifactRefRawContent,
+  resolveArtifactDisplayMode
+} from "./utils/artifact-display";
 import { resolveTarget } from "./utils/target";
 import { builtInClientToolsForDispatch } from "./ask-user-question-tool";
 import {
@@ -1177,6 +1182,66 @@ export class AgentWidgetClient {
     });
   }
 
+  /**
+   * The opt-in structured mention channel: the MOST RECENT user turn's
+   * `mentionContext` (set by `session.applyMentionBundle`) namespaced under
+   * `mentions`. Only the latest user message is consulted — otherwise an older
+   * turn's mentions would re-attach to `context.mentions` on every later send.
+   * Returns null when the latest user turn carried no structured mention context.
+   * The default model-visible path (`llmAppend`) already rode into the message's
+   * `llmContent`/`contentParts`, so it needs nothing here.
+   */
+  private latestMentionContext(
+    messages: AgentWidgetMessage[]
+  ): Record<string, unknown> | null {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const m = messages[i];
+      if (m.role !== "user") continue;
+      // First user message from the end IS the latest user turn: use its
+      // mention context if any, and never look further back.
+      if (m.mentionContext && Object.keys(m.mentionContext).length > 0) {
+        return { mentions: m.mentionContext };
+      }
+      return null;
+    }
+    return null;
+  }
+
+  /**
+   * Aggregate request `context`: merge every context provider's result with the
+   * opt-in mention context from the latest user turn. Returns null when nothing
+   * contributed, so callers can skip setting `payload.context`. Shared by the
+   * agent and flow payload builders.
+   */
+  private async buildContextAggregate(
+    messages: AgentWidgetMessage[]
+  ): Promise<Record<string, unknown> | null> {
+    const contextAggregate: Record<string, unknown> = {};
+    if (this.contextProviders.length) {
+      await Promise.all(
+        this.contextProviders.map(async (provider) => {
+          try {
+            const result = await provider({
+              messages,
+              config: this.config
+            });
+            if (result && typeof result === "object") {
+              Object.assign(contextAggregate, result);
+            }
+          } catch (error) {
+            if (typeof console !== "undefined") {
+              // eslint-disable-next-line no-console
+              console.warn("[AgentWidget] Context provider failed:", error);
+            }
+          }
+        })
+      );
+    }
+    const mentionContext = this.latestMentionContext(messages);
+    if (mentionContext) Object.assign(contextAggregate, mentionContext);
+    return Object.keys(contextAggregate).length ? contextAggregate : null;
+  }
+
   private async buildAgentPayload(
     messages: AgentWidgetMessage[]
   ): Promise<AgentWidgetAgentRequestPayload> {
@@ -1226,32 +1291,9 @@ export class AgentWidgetClient {
       payload.clientTools = clientTools;
     }
 
-    // Add context from providers
-    if (this.contextProviders.length) {
-      const contextAggregate: Record<string, unknown> = {};
-      await Promise.all(
-        this.contextProviders.map(async (provider) => {
-          try {
-            const result = await provider({
-              messages,
-              config: this.config
-            });
-            if (result && typeof result === "object") {
-              Object.assign(contextAggregate, result);
-            }
-          } catch (error) {
-            if (typeof console !== "undefined") {
-              // eslint-disable-next-line no-console
-              console.warn("[AgentWidget] Context provider failed:", error);
-            }
-          }
-        })
-      );
-
-      if (Object.keys(contextAggregate).length) {
-        payload.context = contextAggregate;
-      }
-    }
+    // Add context from providers + opt-in mention context.
+    const contextAggregate = await this.buildContextAggregate(messages);
+    if (contextAggregate) payload.context = contextAggregate;
 
     return payload;
   }
@@ -1306,31 +1348,8 @@ export class AgentWidgetClient {
       payload.clientTools = clientTools;
     }
 
-    if (this.contextProviders.length) {
-      const contextAggregate: Record<string, unknown> = {};
-      await Promise.all(
-        this.contextProviders.map(async (provider) => {
-          try {
-            const result = await provider({
-              messages,
-              config: this.config
-            });
-            if (result && typeof result === "object") {
-              Object.assign(contextAggregate, result);
-            }
-          } catch (error) {
-            if (typeof console !== "undefined") {
-              // eslint-disable-next-line no-console
-              console.warn("[AgentWidget] Context provider failed:", error);
-            }
-          }
-        })
-      );
-
-      if (Object.keys(contextAggregate).length) {
-        payload.context = contextAggregate;
-      }
-    }
+    const contextAggregate = await this.buildContextAggregate(messages);
+    if (contextAggregate) payload.context = contextAggregate;
 
     if (this.requestMiddleware) {
       try {
@@ -1701,12 +1720,25 @@ export class AgentWidgetClient {
 
     // Track tool call IDs for artifact emit tools so we can suppress their UI
     const artifactToolCallIds = new Set<string>();
-    // Track artifact reference card messages so we can update them on artifact_complete
+    // Track artifact block messages (reference card or inline block) so we can
+    // update them on artifact_complete
     const artifactCardMessages = new Map<string, AgentWidgetMessage>();
     // Track artifact IDs that already have a reference card (from auto-creation or transcript_insert)
     const artifactIdsWithCards = new Set<string>();
-    // Accumulate artifact markdown content for embedding in card props on complete
-    const artifactContent = new Map<string, { markdown: string; title?: string }>();
+    // Accumulate artifact markdown content (and component props) for embedding
+    // in block props on complete. `props` accumulates across `artifact_update`
+    // events so an inline component block hydrates with its real props after a
+    // refresh (the session artifact registry, which also tracks them live, is
+    // not persisted).
+    const artifactContent = new Map<
+      string,
+      {
+        markdown: string;
+        title?: string;
+        file?: PersonaArtifactFileMeta;
+        props?: Record<string, unknown>;
+      }
+    >();
     const isArtifactEmitToolName = (name: string | undefined): boolean => {
       if (!name) return false;
       const normalized = name.replace(/_+/g, "_").replace(/^_|_$/g, "");
@@ -3105,17 +3137,57 @@ export class AgentWidgetClient {
             const at = payload.artifactType as PersonaArtifactKind;
             const artId = String(payload.id);
             const artTitle = typeof payload.title === "string" ? payload.title : undefined;
+            // Additive `file` metadata: validate shape (object with string path +
+            // string mimeType; optional string language). Drop silently if malformed
+            // so old/new backends and unexpected payloads never break the stream.
+            const rawFile = payload.file;
+            let artFile: PersonaArtifactFileMeta | undefined;
+            if (
+              rawFile &&
+              typeof rawFile === "object" &&
+              !Array.isArray(rawFile) &&
+              typeof rawFile.path === "string" &&
+              typeof rawFile.mimeType === "string"
+            ) {
+              artFile = {
+                path: rawFile.path,
+                mimeType: rawFile.mimeType,
+                ...(typeof rawFile.language === "string" ? { language: rawFile.language } : {}),
+              };
+            }
             onEvent({
               type: "artifact_start",
               id: artId,
               artifactType: at,
               title: artTitle,
-              component: typeof payload.component === "string" ? payload.component : undefined
+              component: typeof payload.component === "string" ? payload.component : undefined,
+              ...(artFile ? { file: artFile } : {})
             });
-            artifactContent.set(artId, { markdown: "", title: artTitle });
-            // Insert inline artifact reference card (skip if already present from transcript_insert)
+            // Seed component props from artifact_start when the payload
+            // carries them; artifact_update events accumulate the rest below.
+            const startProps =
+              payload.props && typeof payload.props === "object" && !Array.isArray(payload.props)
+                ? { ...(payload.props as Record<string, unknown>) }
+                : undefined;
+            artifactContent.set(artId, {
+              markdown: "",
+              title: artTitle,
+              file: artFile,
+              ...(startProps ? { props: startProps } : {})
+            });
+            // Insert the in-thread artifact block (skip if already present from
+            // transcript_insert). The resolved display mode picks the component:
+            // "card"/"panel" inject the reference card; "inline" injects the
+            // inline preview block. Both share the rawContent JSON-component
+            // shape so transcript persistence and hydration work unchanged.
             if (!artifactIdsWithCards.has(artId)) {
               artifactIdsWithCards.add(artId);
+              const displayMode = resolveArtifactDisplayMode(
+                this.config.features?.artifacts,
+                at
+              );
+              const artComponent =
+                typeof payload.component === "string" ? payload.component : undefined;
               const cardMsg: AgentWidgetMessage = {
                 id: `artifact-ref-${artId}`,
                 role: "assistant",
@@ -3123,9 +3195,13 @@ export class AgentWidgetClient {
                 createdAt: new Date().toISOString(),
                 streaming: true,
                 sequence: nextSequence(),
-                rawContent: JSON.stringify({
-                  component: "PersonaArtifactCard",
-                  props: { artifactId: artId, title: artTitle, artifactType: at, status: "streaming" },
+                rawContent: buildArtifactRefRawContent(displayMode, {
+                  artifactId: artId,
+                  title: artTitle,
+                  artifactType: at,
+                  status: "streaming",
+                  ...(artFile ? { file: artFile } : {}),
+                  ...(artComponent ? { component: artComponent } : {}),
                 }),
               };
               artifactCardMessages.set(artId, cardMsg);
@@ -3152,6 +3228,13 @@ export class AgentWidgetClient {
               props,
               component: typeof payload.component === "string" ? payload.component : undefined
             });
+            // Accumulate for hydration: embedded on artifact_complete so an
+            // inline component block re-renders with its real props after a
+            // refresh.
+            const updateAcc = artifactContent.get(String(payload.id));
+            if (updateAcc) {
+              updateAcc.props = { ...(updateAcc.props ?? {}), ...props };
+            }
           } else if (payloadType === "artifact_complete") {
             const artCompleteId = String(payload.id);
             onEvent({ type: "artifact_complete", id: artCompleteId });
@@ -3168,6 +3251,20 @@ export class AgentWidgetClient {
                   if (acc?.markdown) {
                     parsed.props.markdown = acc.markdown;
                   }
+                  // Persist file metadata too so the download path unfences correctly after refresh.
+                  if (acc?.file) {
+                    parsed.props.file = acc.file;
+                  }
+                  // Embed accumulated component props so an inline component
+                  // block hydrates with its real props after a refresh. Only
+                  // the inline block reads them; the card never does.
+                  if (
+                    parsed.component === "PersonaArtifactInline" &&
+                    acc?.props &&
+                    Object.keys(acc.props).length > 0
+                  ) {
+                    parsed.props.componentProps = acc.props;
+                  }
                 }
                 refMsg.rawContent = JSON.stringify(parsed);
               } catch { /* ignore parse errors */ }

package/src/components/artifact-card.test.ts

@@ -0,0 +1,333 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it } from "vitest";
+import { PersonaArtifactCard } from "./artifact-card";
+import { componentRegistry, type ComponentRenderer } from "./registry";
+import type { ComponentContext } from "./registry";
+import type {
+  AgentWidgetArtifactsFeature,
+  AgentWidgetConfig,
+  PersonaArtifactStatusLabelContext,
+} from "../types";
+
+const makeContext = (
+  artifacts?: AgentWidgetArtifactsFeature
+): ComponentContext =>
+  ({
+    message: {},
+    config: {
+      features: { artifacts: { enabled: true, ...(artifacts ?? {}) } },
+    } as AgentWidgetConfig,
+    updateProps: () => {},
+  }) as unknown as ComponentContext;
+
+const render = (
+  props: Record<string, unknown>,
+  artifacts?: AgentWidgetArtifactsFeature
+): HTMLElement => PersonaArtifactCard(props, makeContext(artifacts));
+
+const streamingProps = {
+  artifactId: "a1",
+  title: "index.html",
+  status: "streaming",
+  artifactType: "markdown",
+  file: { path: "index.html", mimeType: "text/html", language: "html" },
+};
+
+const NBSP = String.fromCharCode(0xa0);
+
+const findStatusText = (root: HTMLElement): HTMLElement | null =>
+  root.querySelector(
+    ".persona-tool-loading-shimmer, .persona-tool-loading-shimmer-color, .persona-tool-loading-rainbow, .persona-tool-loading-pulse"
+  ) as HTMLElement | null;
+
+describe("PersonaArtifactCard streaming status", () => {
+  it("renders shimmer animation by default with no pulsing dot", () => {
+    const root = render(streamingProps);
+
+    // No leftover pulsing dot element.
+    expect(root.querySelector(".persona-rounded-full")).toBeNull();
+    expect(root.innerHTML).not.toContain("persona-pulse ");
+
+    const statusText = findStatusText(root);
+    expect(statusText).not.toBeNull();
+    expect(statusText!.classList.contains("persona-tool-loading-shimmer")).toBe(
+      true
+    );
+    expect(statusText!.getAttribute("data-preserve-animation")).toBe("true");
+    expect(
+      statusText!.style.getPropertyValue("--persona-tool-anim-duration")
+    ).toBe("2000ms");
+
+    const chars = statusText!.querySelectorAll(".persona-tool-char");
+    expect(chars.length).toBeGreaterThan(0);
+    expect((chars[0] as HTMLElement).style.getPropertyValue("--char-index")).toBe(
+      "0"
+    );
+    // Reconstruct the animated text from the character spans.
+    const text = Array.from(chars)
+      .map((c) => (c.textContent === NBSP ? " " : c.textContent))
+      .join("");
+    expect(text).toBe("Generating html...");
+  });
+
+  it("renders plain text with no animation classes when loadingAnimation is none", () => {
+    const root = render(streamingProps, { loadingAnimation: "none" });
+
+    expect(findStatusText(root)).toBeNull();
+    expect(root.querySelector(".persona-tool-char")).toBeNull();
+    expect(root.textContent).toContain("Generating html...");
+  });
+
+  it("applies the pulse class to the status element without char spans", () => {
+    const root = render(streamingProps, { loadingAnimation: "pulse" });
+
+    const statusText = root.querySelector(
+      ".persona-tool-loading-pulse"
+    ) as HTMLElement | null;
+    expect(statusText).not.toBeNull();
+    expect(statusText!.getAttribute("data-preserve-animation")).toBe("true");
+    expect(statusText!.querySelector(".persona-tool-char")).toBeNull();
+    expect(statusText!.textContent).toBe("Generating html...");
+  });
+
+  it("sets color CSS vars for shimmer-color mode", () => {
+    const root = render(streamingProps, {
+      loadingAnimation: "shimmer-color",
+      loadingAnimationColor: "#111111",
+      loadingAnimationSecondaryColor: "#eeeeee",
+      loadingAnimationDuration: 3000,
+    });
+
+    const statusText = root.querySelector(
+      ".persona-tool-loading-shimmer-color"
+    ) as HTMLElement | null;
+    expect(statusText).not.toBeNull();
+    expect(
+      statusText!.style.getPropertyValue("--persona-tool-anim-color")
+    ).toBe("#111111");
+    expect(
+      statusText!.style.getPropertyValue("--persona-tool-anim-secondary-color")
+    ).toBe("#eeeeee");
+    expect(
+      statusText!.style.getPropertyValue("--persona-tool-anim-duration")
+    ).toBe("3000ms");
+  });
+
+  it("carries the artifact-card class so radius/border/background come from CSS", () => {
+    const root = render(streamingProps);
+
+    // Standalone card must not hardcode the rounded-xl utility class.
+    expect(root.classList.contains("persona-rounded-xl")).toBe(false);
+    // Radius/border/background now live in widget.css keyed off this class,
+    // following the --persona-artifact-card-radius → assistant-bubble chain.
+    expect(root.classList.contains("persona-artifact-card")).toBe(true);
+  });
+
+  it("keeps border/background off inline styles so they come from CSS", () => {
+    const root = render(streamingProps);
+
+    expect(root.classList.contains("persona-artifact-card")).toBe(true);
+    // Border/bg/radius/cursor moved to widget.css keyed off the card class.
+    expect(root.style.border).toBe("");
+    expect(root.style.background).toBe("");
+    expect(root.style.backgroundColor).toBe("");
+    expect(root.style.borderRadius).toBe("");
+  });
+
+  it("renders the Download button as a label button carrying the artifact id", () => {
+    const root = render({
+      artifactId: "a1",
+      title: "index.html",
+      status: "complete",
+      artifactType: "markdown",
+      file: { path: "index.html", mimeType: "text/html", language: "html" },
+    });
+
+    const dl = root.querySelector(
+      "[data-download-artifact]"
+    ) as HTMLButtonElement | null;
+    expect(dl).not.toBeNull();
+    expect(dl!.tagName).toBe("BUTTON");
+    expect(dl!.classList.contains("persona-label-btn")).toBe(true);
+    expect(dl!.textContent).toBe("Download");
+    expect(dl!.getAttribute("data-download-artifact")).toBe("a1");
+  });
+
+  it("renders the complete state with a Download button and no animation", () => {
+    const root = render({
+      artifactId: "a1",
+      title: "index.html",
+      status: "complete",
+      artifactType: "markdown",
+      file: { path: "index.html", mimeType: "text/html", language: "html" },
+    });
+
+    expect(findStatusText(root)).toBeNull();
+    expect(root.querySelector(".persona-tool-char")).toBeNull();
+
+    const dl = root.querySelector(
+      "[data-download-artifact]"
+    ) as HTMLButtonElement | null;
+    expect(dl).not.toBeNull();
+    expect(dl!.textContent).toBe("Download");
+    // Subtitle shows the file type label, not a "Generating" status.
+    expect(root.textContent).not.toContain("Generating");
+  });
+});
+
+describe("PersonaArtifactCard statusLabel", () => {
+  // Reconstruct the (possibly char-span animated) status label text.
+  const labelText = (root: HTMLElement): string => {
+    const label = root.querySelector(
+      ".persona-artifact-status-label"
+    ) as HTMLElement | null;
+    if (!label) return "";
+    const chars = label.querySelectorAll(".persona-tool-char");
+    if (chars.length === 0) return label.textContent ?? "";
+    return Array.from(chars)
+      .map((c) => (c.textContent === NBSP ? " " : c.textContent))
+      .join("");
+  };
+
+  it("replaces the default status text with a plain string", () => {
+    const root = render(streamingProps, { statusLabel: "Cooking up your file..." });
+    expect(labelText(root)).toBe("Cooking up your file...");
+    expect(root.textContent).not.toContain("Generating");
+  });
+
+  it("calls a statusLabel function with the card surface and ctx", () => {
+    const calls: PersonaArtifactStatusLabelContext[] = [];
+    const root = render(streamingProps, {
+      statusLabel: (ctx) => {
+        calls.push(ctx);
+        return "Custom label";
+      },
+    });
+    expect(calls.length).toBe(1);
+    expect(calls[0].surface).toBe("card");
+    expect(calls[0].artifactId).toBe("a1");
+    expect(calls[0].artifactType).toBe("markdown");
+    // file: index.html -> fileTypeLabel "HTML".
+    expect(calls[0].typeLabel).toBe("HTML");
+    expect(typeof calls[0].content).toBe("function");
+    expect(labelText(root)).toBe("Custom label");
+  });
+
+  it("renders a { label, detail } as an animated label + plain detail span", () => {
+    const root = render(streamingProps, {
+      statusLabel: () => ({ label: "Writing", detail: "just started" }),
+    });
+    expect(labelText(root)).toBe("Writing");
+    const detail = root.querySelector(
+      ".persona-artifact-status-detail"
+    ) as HTMLElement | null;
+    expect(detail).not.toBeNull();
+    expect(detail!.textContent).toBe("just started");
+    // The detail span is un-animated (no char spans / loading classes).
+    expect(detail!.querySelector(".persona-tool-char")).toBeNull();
+  });
+
+  it("falls back to the default label when statusLabel throws", () => {
+    const root = render(streamingProps, {
+      statusLabel: () => {
+        throw new Error("boom");
+      },
+    });
+    expect(labelText(root)).toBe("Generating html...");
+  });
+});
+
+describe("PersonaArtifactCard custom card actions", () => {
+  const completeProps = {
+    artifactId: "a1",
+    title: "index.html",
+    status: "complete",
+    artifactType: "markdown",
+    markdown: "# Hi",
+    file: { path: "index.html", mimeType: "text/html", language: "html" },
+  };
+
+  it("renders a card action button before Download on complete cards", () => {
+    const root = render(completeProps, {
+      cardActions: [
+        { id: "save", label: "Save to Drive", icon: "star", onClick: () => {} },
+      ],
+    });
+
+    const btn = root.querySelector(
+      '[data-artifact-custom-action="save"]'
+    ) as HTMLButtonElement | null;
+    expect(btn).not.toBeNull();
+    expect(btn!.tagName).toBe("BUTTON");
+    // Delegated in ui.ts: the card carries the id attribute, no direct listener.
+    expect(btn!.getAttribute("data-artifact-custom-action")).toBe("save");
+
+    const dl = root.querySelector(
+      "[data-download-artifact]"
+    ) as HTMLElement | null;
+    expect(dl).not.toBeNull();
+    // Custom actions render before Download.
+    expect(
+      btn!.compareDocumentPosition(dl!) & Node.DOCUMENT_POSITION_FOLLOWING
+    ).toBeTruthy();
+  });
+
+  it("does not render card actions while streaming", () => {
+    const root = render(streamingProps, {
+      cardActions: [
+        { id: "save", label: "Save to Drive", icon: "star", onClick: () => {} },
+      ],
+    });
+    expect(root.querySelector("[data-artifact-custom-action]")).toBeNull();
+  });
+
+  it("suppresses a card action whose visible() returns false", () => {
+    const root = render(completeProps, {
+      cardActions: [
+        {
+          id: "save",
+          label: "Save",
+          icon: "star",
+          visible: () => false,
+          onClick: () => {},
+        },
+      ],
+    });
+    expect(root.querySelector("[data-artifact-custom-action]")).toBeNull();
+  });
+});
+
+describe("componentRegistry registration options", () => {
+  const noop: ComponentRenderer = () => document.createElement("div");
+
+  afterEach(() => {
+    componentRegistry.unregister("OptTest");
+  });
+
+  it("registers the built-in artifact card with bubbleChrome:false", () => {
+    expect(componentRegistry.getOptions("PersonaArtifactCard")?.bubbleChrome).toBe(false);
+  });
+
+  it("returns the options passed to register", () => {
+    componentRegistry.register("OptTest", noop, { bubbleChrome: false });
+    expect(componentRegistry.getOptions("OptTest")).toEqual({ bubbleChrome: false });
+  });
+
+  it("returns undefined when a component is registered without options", () => {
+    componentRegistry.register("OptTest", noop);
+    expect(componentRegistry.getOptions("OptTest")).toBeUndefined();
+  });
+
+  it("clears prior options when re-registered without options", () => {
+    componentRegistry.register("OptTest", noop, { bubbleChrome: false });
+    componentRegistry.register("OptTest", noop);
+    expect(componentRegistry.getOptions("OptTest")).toBeUndefined();
+  });
+
+  it("drops options on unregister", () => {
+    componentRegistry.register("OptTest", noop, { bubbleChrome: false });
+    componentRegistry.unregister("OptTest");
+    expect(componentRegistry.getOptions("OptTest")).toBeUndefined();
+  });
+});