@runtypelabs/persona 4.7.0 → 4.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -74,8 +74,7 @@
     "idiomorph": "^0.7.4",
     "lucide": "^1.18.0",
     "marked": "^12.0.2",
-    "partial-json": "^0.1.7",
-    "zod": "^3.22.4"
+    "partial-json": "^0.1.7"
   },
   "devDependencies": {
     "@size-limit/file": "^12.1.0",

package/src/artifacts-session.test.ts

@@ -77,4 +77,182 @@ describe("AgentWidgetSession artifacts", () => {
     expect(session.getArtifacts()).toHaveLength(1);
     expect(session.getArtifacts()[0].markdown).toBe("C");
   });
+
+  it("stores file metadata via applyArtifactStreamEvent and keeps accumulating deltas", () => {
+    const session = new AgentWidgetSession(
+      {},
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    const file = { path: "outputs/cat.html", mimeType: "text/html", language: "html" };
+    session.injectTestEvent({
+      type: "artifact_start",
+      id: "f1",
+      artifactType: "markdown",
+      title: "outputs/cat.html",
+      file
+    });
+    session.injectTestEvent({ type: "artifact_delta", id: "f1", artDelta: "```html\n" });
+    session.injectTestEvent({ type: "artifact_delta", id: "f1", artDelta: "<h1>hi</h1>\n```" });
+    const rec = session.getArtifactById("f1");
+    expect(rec?.file).toEqual(file);
+    expect(rec?.markdown).toBe("```html\n<h1>hi</h1>\n```");
+  });
+
+  it("upsertArtifact injects a card transcript block by default", () => {
+    const session = new AgentWidgetSession(
+      {},
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    const rec = session.upsertArtifact({
+      artifactType: "markdown",
+      title: "Doc",
+      content: "# Hi"
+    });
+    const block = session
+      .getMessages()
+      .find((m) => m.id === `artifact-ref-${rec.id}`);
+    expect(block).toBeDefined();
+    expect(block?.role).toBe("assistant");
+    const parsed = JSON.parse(block!.rawContent!);
+    expect(parsed.component).toBe("PersonaArtifactCard");
+    expect(parsed.props).toMatchObject({
+      artifactId: rec.id,
+      title: "Doc",
+      artifactType: "markdown",
+      status: "complete",
+      markdown: "# Hi"
+    });
+  });
+
+  it("upsertArtifact injects an inline block when display resolves to inline", () => {
+    const session = new AgentWidgetSession(
+      { features: { artifacts: { enabled: true, display: "inline" } } },
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    const rec = session.upsertArtifact({
+      artifactType: "component",
+      title: "Chart",
+      component: "MyChart",
+      props: { series: [1, 2] }
+    });
+    const block = session
+      .getMessages()
+      .find((m) => m.id === `artifact-ref-${rec.id}`);
+    expect(block).toBeDefined();
+    const parsed = JSON.parse(block!.rawContent!);
+    expect(parsed.component).toBe("PersonaArtifactInline");
+    // Inline blocks render component artifacts through the registry, so the
+    // component name AND its props are embedded in the block props (the
+    // registry is not persisted, so hydration re-invokes the renderer from
+    // these).
+    expect(parsed.props.component).toBe("MyChart");
+    expect(parsed.props.componentProps).toEqual({ series: [1, 2] });
+    expect(parsed.props.status).toBe("complete");
+  });
+
+  it("upsertArtifact with transcript: false injects no transcript block", () => {
+    const session = new AgentWidgetSession(
+      {},
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    session.upsertArtifact({
+      id: "pane-only",
+      artifactType: "markdown",
+      content: "C",
+      transcript: false
+    });
+    expect(session.getArtifacts()).toHaveLength(1);
+    expect(session.getMessages()).toHaveLength(0);
+  });
+
+  it("upsertArtifact update to an existing artifact does not duplicate the block", () => {
+    const session = new AgentWidgetSession(
+      {},
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    session.upsertArtifact({ id: "a1", artifactType: "markdown", content: "v1" });
+    session.upsertArtifact({ id: "a1", artifactType: "markdown", content: "v2" });
+    const blocks = session
+      .getMessages()
+      .filter((m) => m.id === "artifact-ref-a1");
+    expect(blocks).toHaveLength(1);
+    expect(session.getArtifacts()).toHaveLength(1);
+    expect(session.getArtifactById("a1")?.markdown).toBe("v2");
+  });
+
+  it("upsertArtifact re-upsert rebuilds the existing block's persisted props", () => {
+    const session = new AgentWidgetSession(
+      {},
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    session.upsertArtifact({
+      id: "a1",
+      artifactType: "markdown",
+      title: "T1",
+      content: "v1"
+    });
+    session.upsertArtifact({
+      id: "a1",
+      artifactType: "markdown",
+      title: "T2",
+      content: "v2"
+    });
+    const blocks = session
+      .getMessages()
+      .filter((m) => m.id === "artifact-ref-a1");
+    expect(blocks).toHaveLength(1);
+    const parsed = JSON.parse(blocks[0].rawContent!);
+    expect(parsed.props.markdown).toBe("v2");
+    expect(parsed.props.title).toBe("T2");
+  });
+
+  it("stores file metadata via upsertArtifact", () => {
+    const session = new AgentWidgetSession(
+      {},
+      {
+        onMessagesChanged: () => {},
+        onStatusChanged: () => {},
+        onStreamingChanged: () => {},
+        onArtifactsState: () => {}
+      }
+    );
+    const file = { path: "notes.md", mimeType: "text/markdown" };
+    session.upsertArtifact({
+      artifactType: "markdown",
+      title: "notes.md",
+      content: "```md\n# Hi\n\n```",
+      file
+    });
+    expect(session.getArtifactById(session.getArtifacts()[0].id)?.file).toEqual(file);
+  });
 });

package/src/client.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { AgentWidgetClient, preferFinalStructuredContent } from './client';
-import { AgentWidgetEvent, AgentWidgetMessage } from './types';
+import { AgentWidgetEvent, AgentWidgetMessage, AgentWidgetArtifactsFeature } from './types';
 import { createJsonStreamParser } from './utils/formatting';
 import { VERSION } from './version';
 import { createUnifiedEventWrite } from './utils/__fixtures__/unified-translator.oracle';
@@ -4357,3 +4357,188 @@ describe('AgentWidgetClient - Wire event vocabulary (default in 4.0)', () => {
     }
   });
 });
+
+describe('AgentWidgetClient - Artifact file metadata', () => {
+  const artifactFrames = (fileField: string | null): string[] => [
+    `data: {"type":"artifact_start","id":"a1","artifactType":"markdown","title":"outputs/cat.html"${
+      fileField === null ? '' : ',"file":' + fileField
+    }}\n\n`,
+    `data: {"type":"artifact_delta","id":"a1","delta":${JSON.stringify('```html\n<h1>hi</h1>\n```')}}\n\n`,
+    `data: {"type":"artifact_complete","id":"a1"}\n\n`,
+  ];
+
+  it('propagates valid file metadata to the artifact_start event and card props', async () => {
+    global.fetch = createRawStreamFetch(
+      artifactFrames('{"path":"outputs/cat.html","mimeType":"text/html","language":"html"}')
+    );
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    const startEv = events.find((e) => e.type === 'artifact_start');
+    expect(startEv).toBeDefined();
+    if (startEv?.type === 'artifact_start') {
+      expect(startEv.file).toEqual({
+        path: 'outputs/cat.html',
+        mimeType: 'text/html',
+        language: 'html',
+      });
+    }
+
+    // The completed card message carries the file metadata in its rawContent props.
+    const cardMsgs = events.filter(
+      (e): e is Extract<AgentWidgetEvent, { type: 'message' }> =>
+        e.type === 'message' && e.message.id === 'artifact-ref-a1'
+    );
+    const lastCard = cardMsgs[cardMsgs.length - 1];
+    expect(lastCard).toBeDefined();
+    const props = JSON.parse(lastCard.message.rawContent ?? '{}').props;
+    expect(props.status).toBe('complete');
+    expect(props.file).toEqual({
+      path: 'outputs/cat.html',
+      mimeType: 'text/html',
+      language: 'html',
+    });
+    expect(props.markdown).toBe('```html\n<h1>hi</h1>\n```');
+  });
+
+  it('drops malformed file metadata without error', async () => {
+    global.fetch = createRawStreamFetch(artifactFrames('{"path":123}'));
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    expect(events.some((e) => e.type === 'error')).toBe(false);
+    const startEv = events.find((e) => e.type === 'artifact_start');
+    expect(startEv).toBeDefined();
+    if (startEv?.type === 'artifact_start') {
+      expect(startEv.file).toBeUndefined();
+    }
+    const cardMsgs = events.filter(
+      (e): e is Extract<AgentWidgetEvent, { type: 'message' }> =>
+        e.type === 'message' && e.message.id === 'artifact-ref-a1'
+    );
+    const props = JSON.parse(cardMsgs[cardMsgs.length - 1].message.rawContent ?? '{}').props;
+    expect(props.file).toBeUndefined();
+  });
+});
+
+describe('AgentWidgetClient - Artifact display modes', () => {
+  const markdownArtifactFrames = (id = 'a1'): string[] => [
+    `data: {"type":"artifact_start","id":"${id}","artifactType":"markdown","title":"Notes"}\n\n`,
+    `data: {"type":"artifact_delta","id":"${id}","delta":"# Hello"}\n\n`,
+    `data: {"type":"artifact_complete","id":"${id}"}\n\n`,
+  ];
+  const componentArtifactFrames = (id = 'c1'): string[] => [
+    `data: {"type":"artifact_start","id":"${id}","artifactType":"component","title":"Chart","component":"MyChart"}\n\n`,
+    `data: {"type":"artifact_complete","id":"${id}"}\n\n`,
+  ];
+
+  const dispatchAndCollect = async (
+    frames: string[],
+    artifacts?: AgentWidgetArtifactsFeature
+  ): Promise<AgentWidgetEvent[]> => {
+    global.fetch = createRawStreamFetch(frames);
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      ...(artifacts ? { features: { artifacts } } : {}),
+    });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+    return events;
+  };
+
+  const blockMessagesFor = (events: AgentWidgetEvent[], artifactId: string) =>
+    events.filter(
+      (e): e is Extract<AgentWidgetEvent, { type: 'message' }> =>
+        e.type === 'message' && e.message.id === `artifact-ref-${artifactId}`
+    );
+
+  const componentNameOf = (msg: AgentWidgetMessage): string =>
+    JSON.parse(msg.rawContent ?? '{}').component;
+
+  it('injects PersonaArtifactCard when display is unset (default "panel")', async () => {
+    const events = await dispatchAndCollect(markdownArtifactFrames());
+    const msgs = blockMessagesFor(events, 'a1');
+    expect(msgs.length).toBeGreaterThan(0);
+    for (const m of msgs) {
+      expect(componentNameOf(m.message)).toBe('PersonaArtifactCard');
+    }
+  });
+
+  it('injects PersonaArtifactCard for display: "card" and display: "panel"', async () => {
+    for (const mode of ['card', 'panel'] as const) {
+      const events = await dispatchAndCollect(markdownArtifactFrames(), {
+        enabled: true,
+        display: mode,
+      });
+      const msgs = blockMessagesFor(events, 'a1');
+      expect(msgs.length).toBeGreaterThan(0);
+      expect(componentNameOf(msgs[0].message)).toBe('PersonaArtifactCard');
+    }
+  });
+
+  it('injects PersonaArtifactInline for display: "inline"', async () => {
+    const events = await dispatchAndCollect(markdownArtifactFrames(), {
+      enabled: true,
+      display: 'inline',
+    });
+    const msgs = blockMessagesFor(events, 'a1');
+    expect(msgs.length).toBeGreaterThan(0);
+    for (const m of msgs) {
+      expect(componentNameOf(m.message)).toBe('PersonaArtifactInline');
+    }
+    const startProps = JSON.parse(msgs[0].message.rawContent ?? '{}').props;
+    expect(startProps).toMatchObject({
+      artifactId: 'a1',
+      artifactType: 'markdown',
+      status: 'streaming',
+    });
+  });
+
+  it('resolves the mode per artifact type via display.byType', async () => {
+    const display: AgentWidgetArtifactsFeature['display'] = {
+      default: 'card',
+      byType: { component: 'inline' },
+    };
+
+    const mdEvents = await dispatchAndCollect(markdownArtifactFrames(), {
+      enabled: true,
+      display,
+    });
+    expect(componentNameOf(blockMessagesFor(mdEvents, 'a1')[0].message)).toBe(
+      'PersonaArtifactCard'
+    );
+
+    const compEvents = await dispatchAndCollect(componentArtifactFrames(), {
+      enabled: true,
+      display,
+    });
+    const compMsgs = blockMessagesFor(compEvents, 'c1');
+    expect(componentNameOf(compMsgs[0].message)).toBe('PersonaArtifactInline');
+    // Inline component artifacts carry the component name for the preview registry.
+    expect(JSON.parse(compMsgs[0].message.rawContent ?? '{}').props.component).toBe('MyChart');
+  });
+
+  it('embeds accumulated markdown and complete status in inline block props on artifact_complete', async () => {
+    const events = await dispatchAndCollect(markdownArtifactFrames(), {
+      enabled: true,
+      display: 'inline',
+    });
+    const msgs = blockMessagesFor(events, 'a1');
+    const last = msgs[msgs.length - 1];
+    expect(last.message.streaming).toBe(false);
+    const props = JSON.parse(last.message.rawContent ?? '{}').props;
+    expect(props.status).toBe('complete');
+    expect(props.markdown).toBe('# Hello');
+  });
+});

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 {
@@ -1701,12 +1706,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 +3123,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 +3181,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 +3214,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 +3237,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 */ }