@runtypelabs/persona 3.18.0 → 3.20.0

package/src/runtime/persist-state.test.ts

@@ -0,0 +1,152 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "../ui";
+import { createLocalStorageAdapter } from "../utils/storage";
+import type { AgentWidgetStorageAdapter } from "../types";
+
+const DEFAULT_KEY = "persona-state";
+
+const baseConfig = () => ({
+  apiUrl: "https://api.example.com/chat",
+  launcher: { enabled: false } as const,
+});
+
+const inject = (controller: ReturnType<typeof createAgentExperience>) =>
+  controller.injectAssistantMessage({ content: "hello world" });
+
+describe("persistState gates storage adapter", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    try {
+      window.localStorage.clear();
+    } catch {
+      /* jsdom edge cases */
+    }
+  });
+
+  it("persistState: false skips the default localStorage adapter", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      persistState: false,
+    });
+
+    inject(controller);
+
+    expect(window.localStorage.getItem(DEFAULT_KEY)).toBeNull();
+    controller.destroy();
+  });
+
+  it("persistState: false ignores any user-supplied storageAdapter (strict semantic)", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const customAdapter: AgentWidgetStorageAdapter = {
+      load: vi.fn(() => null),
+      save: vi.fn(),
+      clear: vi.fn(),
+    };
+
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      persistState: false,
+      storageAdapter: customAdapter,
+    });
+
+    inject(controller);
+
+    expect(customAdapter.load).not.toHaveBeenCalled();
+    expect(customAdapter.save).not.toHaveBeenCalled();
+    controller.destroy();
+  });
+
+  it("default config (persistState undefined) writes to the default localStorage key", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const controller = createAgentExperience(mount, baseConfig());
+
+    inject(controller);
+
+    const stored = window.localStorage.getItem(DEFAULT_KEY);
+    expect(stored).not.toBeNull();
+    const parsed = JSON.parse(stored!);
+    expect(parsed.messages).toBeInstanceOf(Array);
+    expect(parsed.messages.length).toBeGreaterThan(0);
+    controller.destroy();
+  });
+
+  it("persistState: true keeps using the default localStorage adapter", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      persistState: true,
+    });
+
+    inject(controller);
+
+    expect(window.localStorage.getItem(DEFAULT_KEY)).not.toBeNull();
+    controller.destroy();
+  });
+
+  it("two widgets with different storageAdapter keys keep their messages isolated", () => {
+    const mountA = document.createElement("div");
+    const mountB = document.createElement("div");
+    document.body.appendChild(mountA);
+    document.body.appendChild(mountB);
+
+    const controllerA = createAgentExperience(mountA, {
+      ...baseConfig(),
+      storageAdapter: createLocalStorageAdapter("persona-state-test-a"),
+    });
+    const controllerB = createAgentExperience(mountB, {
+      ...baseConfig(),
+      storageAdapter: createLocalStorageAdapter("persona-state-test-b"),
+    });
+
+    controllerA.injectAssistantMessage({ content: "message in A" });
+    controllerB.injectAssistantMessage({ content: "message in B" });
+
+    const storedA = JSON.parse(window.localStorage.getItem("persona-state-test-a")!);
+    const storedB = JSON.parse(window.localStorage.getItem("persona-state-test-b")!);
+
+    const aHasA = storedA.messages.some((m: { content?: string }) => m.content === "message in A");
+    const aHasB = storedA.messages.some((m: { content?: string }) => m.content === "message in B");
+    const bHasA = storedB.messages.some((m: { content?: string }) => m.content === "message in A");
+    const bHasB = storedB.messages.some((m: { content?: string }) => m.content === "message in B");
+
+    expect(aHasA).toBe(true);
+    expect(aHasB).toBe(false);
+    expect(bHasB).toBe(true);
+    expect(bHasA).toBe(false);
+    expect(window.localStorage.getItem(DEFAULT_KEY)).toBeNull();
+
+    controllerA.destroy();
+    controllerB.destroy();
+  });
+
+  it("persistState: false does not read from localStorage on init", () => {
+    // Pre-seed the default key with a stored message.
+    window.localStorage.setItem(
+      DEFAULT_KEY,
+      JSON.stringify({ messages: [{ id: "stale", role: "assistant", content: "stale" }] })
+    );
+
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      persistState: false,
+    });
+
+    expect(controller.getMessages()).toEqual([]);
+    controller.destroy();
+  });
+});

package/src/session.test.ts

@@ -244,6 +244,129 @@ describe('AgentWidgetSession - Message Injection', () => {
       expect(messages[0].content).toBe('Legacy message');
     });
   });
+
+  describe('rawContent forwarding', () => {
+    it('preserves rawContent on injected messages', () => {
+      const directive = JSON.stringify({
+        text: 'Booking form',
+        component: 'BookingForm',
+        props: { title: 'Schedule' }
+      });
+
+      const result = session.injectMessage({
+        role: 'assistant',
+        content: 'Booking form',
+        rawContent: directive
+      });
+
+      expect(result.rawContent).toBe(directive);
+      expect(messages[0].rawContent).toBe(directive);
+    });
+
+    it('forwards rawContent through injectAssistantMessage', () => {
+      const directive = JSON.stringify({ text: 'Form', component: 'Form', props: {} });
+
+      const result = session.injectAssistantMessage({
+        content: 'Form',
+        rawContent: directive
+      });
+
+      expect(result.rawContent).toBe(directive);
+    });
+
+    it('forwards rawContent through injectMessageBatch', () => {
+      const directiveA = JSON.stringify({ text: 'A', component: 'CompA', props: {} });
+      const directiveB = JSON.stringify({ text: 'B', component: 'CompB', props: {} });
+
+      const results = session.injectMessageBatch([
+        { role: 'assistant', content: 'A', rawContent: directiveA },
+        { role: 'assistant', content: 'B', rawContent: directiveB }
+      ]);
+
+      expect(results[0].rawContent).toBe(directiveA);
+      expect(results[1].rawContent).toBe(directiveB);
+    });
+
+    it('omits rawContent when not provided', () => {
+      const result = session.injectMessage({
+        role: 'assistant',
+        content: 'plain'
+      });
+
+      expect(result.rawContent).toBeUndefined();
+    });
+  });
+
+  describe('injectComponentDirective', () => {
+    it('builds rawContent from component + props + text', () => {
+      const result = session.injectComponentDirective({
+        component: 'DynamicForm',
+        props: { title: 'Book a demo', fields: [{ label: 'Email' }] },
+        text: 'Share your details to book a demo.'
+      });
+
+      expect(result.role).toBe('assistant');
+      expect(result.content).toBe('Share your details to book a demo.');
+      expect(result.id).toMatch(/^ast_/);
+      expect(result.rawContent).toBeDefined();
+
+      const parsed = JSON.parse(result.rawContent as string);
+      expect(parsed).toEqual({
+        text: 'Share your details to book a demo.',
+        component: 'DynamicForm',
+        props: { title: 'Book a demo', fields: [{ label: 'Email' }] }
+      });
+    });
+
+    it('defaults text to empty string and props to {}', () => {
+      const result = session.injectComponentDirective({ component: 'DynamicForm' });
+
+      expect(result.content).toBe('');
+      const parsed = JSON.parse(result.rawContent as string);
+      expect(parsed).toEqual({ text: '', component: 'DynamicForm', props: {} });
+    });
+
+    it('forwards llmContent for redacted LLM context', () => {
+      const result = session.injectComponentDirective({
+        component: 'DynamicForm',
+        props: { title: 'Book a demo' },
+        text: 'Booking form below.',
+        llmContent: '[Showed booking form]'
+      });
+
+      expect(result.llmContent).toBe('[Showed booking form]');
+    });
+
+    it('honors custom id, createdAt, sequence', () => {
+      const result = session.injectComponentDirective({
+        component: 'DynamicForm',
+        id: 'my-form-1',
+        createdAt: '2026-01-01T00:00:00.000Z',
+        sequence: 999
+      });
+
+      expect(result.id).toBe('my-form-1');
+      expect(result.createdAt).toBe('2026-01-01T00:00:00.000Z');
+      expect(result.sequence).toBe(999);
+    });
+
+    it('upserts an existing directive by id', () => {
+      session.injectComponentDirective({
+        component: 'DynamicForm',
+        props: { title: 'v1' },
+        id: 'reuse-me'
+      });
+      session.injectComponentDirective({
+        component: 'DynamicForm',
+        props: { title: 'v2' },
+        id: 'reuse-me'
+      });
+
+      expect(messages).toHaveLength(1);
+      const parsed = JSON.parse(messages[0].rawContent as string);
+      expect(parsed.props.title).toBe('v2');
+    });
+  });
 });
 
 describe('AgentWidgetSession - cancel()', () => {

package/src/session.ts

@@ -11,6 +11,7 @@ import {
   InjectAssistantMessageOptions,
   InjectUserMessageOptions,
   InjectSystemMessageOptions,
+  InjectComponentDirectiveOptions,
   PersonaArtifactRecord,
   PersonaArtifactManualUpsert
 } from "./types";
@@ -572,7 +573,8 @@ export class AgentWidgetSession {
       createdAt,
       sequence,
       streaming = false,
-      voiceProcessing
+      voiceProcessing,
+      rawContent
     } = options;
 
     // Generate appropriate ID based on role
@@ -594,7 +596,8 @@ export class AgentWidgetSession {
       // Only include optional fields if provided
       ...(llmContent !== undefined && { llmContent }),
       ...(contentParts !== undefined && { contentParts }),
-      ...(voiceProcessing !== undefined && { voiceProcessing })
+      ...(voiceProcessing !== undefined && { voiceProcessing }),
+      ...(rawContent !== undefined && { rawContent })
     };
 
     // Use upsert to handle both new messages and updates (streaming)
@@ -673,7 +676,9 @@ export class AgentWidgetSession {
         id,
         createdAt,
         sequence,
-        streaming = false
+        streaming = false,
+        voiceProcessing,
+        rawContent
       } = options;
 
       const messageId =
@@ -692,7 +697,9 @@ export class AgentWidgetSession {
         sequence: sequence ?? this.nextSequence(),
         streaming,
         ...(llmContent !== undefined && { llmContent }),
-        ...(contentParts !== undefined && { contentParts })
+        ...(contentParts !== undefined && { contentParts }),
+        ...(voiceProcessing !== undefined && { voiceProcessing }),
+        ...(rawContent !== undefined && { rawContent })
       };
 
       results.push(message);
@@ -705,6 +712,53 @@ export class AgentWidgetSession {
     return results;
   }
 
+  /**
+   * Convenience method for injecting a registered component directive as
+   * an assistant message — the same shape Persona produces from a streamed
+   * `{ "text": "...", "component": "...", "props": {...} }` payload.
+   *
+   * Sets `content` to `text`, `rawContent` to the JSON directive (so
+   * `extractComponentDirectiveFromMessage` can find it), and forwards
+   * `llmContent` / `id` / `createdAt` / `sequence`.
+   *
+   * @example
+   * session.injectComponentDirective({
+   *   component: "DynamicForm",
+   *   props: { title: "Book a demo", fields: [...] },
+   *   text: "Share your details to book a demo.",
+   *   llmContent: "[Showed booking form]"
+   * });
+   */
+  public injectComponentDirective(
+    options: InjectComponentDirectiveOptions
+  ): AgentWidgetMessage {
+    const {
+      component,
+      props = {},
+      text = "",
+      llmContent,
+      id,
+      createdAt,
+      sequence
+    } = options;
+
+    const directive: { text: string; component: string; props: Record<string, unknown> } = {
+      text,
+      component,
+      props
+    };
+
+    return this.injectMessage({
+      role: "assistant",
+      content: text,
+      rawContent: JSON.stringify(directive),
+      ...(llmContent !== undefined && { llmContent }),
+      ...(id !== undefined && { id }),
+      ...(createdAt !== undefined && { createdAt }),
+      ...(sequence !== undefined && { sequence })
+    });
+  }
+
   public async sendMessage(
     rawInput: string,
     options?: {