@runtypelabs/persona 3.19.0 → 3.20.0

package/dist/theme-editor.cjs

@@ -7505,7 +7505,8 @@ var AgentWidgetSession = class _AgentWidgetSession {
       createdAt,
       sequence,
       streaming = false,
-      voiceProcessing
+      voiceProcessing,
+      rawContent
     } = options;
     const messageId = id != null ? id : role === "user" ? generateUserMessageId() : role === "assistant" ? generateAssistantMessageId() : `system-${Date.now()}-${Math.random().toString(16).slice(2)}`;
     const message = {
@@ -7518,7 +7519,8 @@ var AgentWidgetSession = class _AgentWidgetSession {
       // Only include optional fields if provided
       ...llmContent !== void 0 && { llmContent },
       ...contentParts !== void 0 && { contentParts },
-      ...voiceProcessing !== void 0 && { voiceProcessing }
+      ...voiceProcessing !== void 0 && { voiceProcessing },
+      ...rawContent !== void 0 && { rawContent }
     };
     this.upsertMessage(message);
     return message;
@@ -7583,7 +7585,9 @@ var AgentWidgetSession = class _AgentWidgetSession {
         id,
         createdAt,
         sequence,
-        streaming = false
+        streaming = false,
+        voiceProcessing,
+        rawContent
       } = options;
       const messageId = id != null ? id : role === "user" ? generateUserMessageId() : role === "assistant" ? generateAssistantMessageId() : `system-${Date.now()}-${Math.random().toString(16).slice(2)}`;
       const message = {
@@ -7594,7 +7598,9 @@ var AgentWidgetSession = class _AgentWidgetSession {
         sequence: sequence != null ? sequence : this.nextSequence(),
         streaming,
         ...llmContent !== void 0 && { llmContent },
-        ...contentParts !== void 0 && { contentParts }
+        ...contentParts !== void 0 && { contentParts },
+        ...voiceProcessing !== void 0 && { voiceProcessing },
+        ...rawContent !== void 0 && { rawContent }
       };
       results.push(message);
     }
@@ -7602,6 +7608,48 @@ var AgentWidgetSession = class _AgentWidgetSession {
     this.callbacks.onMessagesChanged([...this.messages]);
     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]"
+   * });
+   */
+  injectComponentDirective(options) {
+    const {
+      component,
+      props = {},
+      text = "",
+      llmContent,
+      id,
+      createdAt,
+      sequence
+    } = options;
+    const directive = {
+      text,
+      component,
+      props
+    };
+    return this.injectMessage({
+      role: "assistant",
+      content: text,
+      rawContent: JSON.stringify(directive),
+      ...llmContent !== void 0 && { llmContent },
+      ...id !== void 0 && { id },
+      ...createdAt !== void 0 && { createdAt },
+      ...sequence !== void 0 && { sequence }
+    });
+  }
   async sendMessage(rawInput, options) {
     var _a, _b, _c, _d, _e;
     const input = rawInput.trim();
@@ -15326,24 +15374,39 @@ function renderComponentDirective(directive, options) {
     return null;
   }
 }
+function selectDirectiveSource(message) {
+  if (typeof message.rawContent === "string" && message.rawContent.length > 0) {
+    return message.rawContent;
+  }
+  if (typeof message.content === "string") {
+    const trimmed = message.content.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+      return message.content;
+    }
+  }
+  return null;
+}
 function hasComponentDirective(message) {
-  if (!message.rawContent) return false;
+  const source = selectDirectiveSource(message);
+  if (!source) return false;
   try {
-    const parsed = JSON.parse(message.rawContent);
+    const parsed = JSON.parse(source);
     return typeof parsed === "object" && parsed !== null && "component" in parsed && typeof parsed.component === "string";
   } catch {
     return false;
   }
 }
 function extractComponentDirectiveFromMessage(message) {
-  if (!message.rawContent) return null;
+  const source = selectDirectiveSource(message);
+  if (!source) return null;
   try {
-    const parsed = JSON.parse(message.rawContent);
+    const parsed = JSON.parse(source);
     if (typeof parsed === "object" && parsed !== null && "component" in parsed && typeof parsed.component === "string") {
+      const directive = parsed;
       return {
-        component: parsed.component,
-        props: parsed.props && typeof parsed.props === "object" && parsed.props !== null ? parsed.props : {},
-        raw: message.rawContent
+        component: directive.component,
+        props: directive.props && typeof directive.props === "object" && directive.props !== null ? directive.props : {},
+        raw: source
       };
     }
   } catch {
@@ -20743,6 +20806,12 @@ var createAgentExperience = (mount, initialConfig, runtimeOptions) => {
       }
       return session.injectMessageBatch(optionsList);
     },
+    injectComponentDirective(options) {
+      if (!open && isPanelToggleable()) {
+        setOpenState(true, "system");
+      }
+      return session.injectComponentDirective(options);
+    },
     /** @deprecated Use injectMessage() instead */
     injectTestMessage(event) {
       if (!open && isPanelToggleable()) {

package/dist/theme-editor.d.cts

@@ -4097,6 +4097,22 @@ type InjectMessageOptions = {
      * Consumers can detect this in `messageTransform` to render custom UI.
      */
     voiceProcessing?: boolean;
+    /**
+     * Raw structured payload (typically a JSON string) representing the
+     * full directive that produced this message — e.g. `{ "text": "...",
+     * "component": "Foo", "props": {...} }`.
+     *
+     * Mirrors the field populated by stream parsers during normal LLM
+     * responses. Set this when injecting a message that should render as a
+     * component directive (`hasComponentDirective` /
+     * `extractComponentDirectiveFromMessage` look at `rawContent` first).
+     *
+     * Priority for the API payload remains:
+     * `contentParts > llmContent > rawContent > content`. Pass `llmContent`
+     * alongside `rawContent` if the LLM should see something other than the
+     * raw directive.
+     */
+    rawContent?: string;
 };
 /**
  * Options for injecting assistant messages (most common case).
@@ -4113,6 +4129,57 @@ type InjectUserMessageOptions = Omit<InjectMessageOptions, "role">;
  * Role defaults to 'system'.
  */
 type InjectSystemMessageOptions = Omit<InjectMessageOptions, "role">;
+/**
+ * Options for injecting an assistant message that renders as a component
+ * directive — sugar over `injectAssistantMessage` for the common case of
+ * "render this registered component, same as if the LLM had emitted it".
+ *
+ * Equivalent to calling `injectAssistantMessage({ content: text, rawContent:
+ * JSON.stringify({ text, component, props }), llmContent })`.
+ *
+ * @example
+ * widget.injectComponentDirective({
+ *   component: "DynamicForm",
+ *   props: { title: "Book a demo", fields: [...] },
+ *   text: "Share your details to book a demo.",
+ *   llmContent: "[Showed booking form]"
+ * });
+ */
+type InjectComponentDirectiveOptions = {
+    /**
+     * Name of a renderer registered via `componentRegistry.register(...)`.
+     */
+    component: string;
+    /**
+     * Props passed to the component renderer.
+     */
+    props?: Record<string, unknown>;
+    /**
+     * Bubble copy displayed above (or with) the rendered component.
+     * Mirrors the `text` field in a streamed JSON directive.
+     * @default ""
+     */
+    text?: string;
+    /**
+     * Content sent to the LLM in API requests. When omitted, the raw
+     * directive JSON is what the LLM would see (per the standard
+     * priority chain). Provide a redacted/short version to avoid sending
+     * the full directive in subsequent turns.
+     */
+    llmContent?: string;
+    /**
+     * Optional message ID. If omitted, an assistant id is auto-generated.
+     */
+    id?: string;
+    /**
+     * Optional creation timestamp (ISO string). If omitted, uses current time.
+     */
+    createdAt?: string;
+    /**
+     * Optional sequence number for ordering.
+     */
+    sequence?: number;
+};
 type PersonaArtifactRecord = {
     id: string;
     artifactType: PersonaArtifactKind;
@@ -4480,6 +4547,12 @@ type Controller = {
      * Inject multiple messages in a single batch with one sort and one render pass.
      */
     injectMessageBatch: (optionsList: InjectMessageOptions[]) => AgentWidgetMessage[];
+    /**
+     * Convenience method for injecting an assistant message that renders as a
+     * registered component — same shape Persona produces from a streamed
+     * `{ "text": "...", "component": "...", "props": {...} }` payload.
+     */
+    injectComponentDirective: (options: InjectComponentDirectiveOptions) => AgentWidgetMessage;
     /**
      * @deprecated Use injectMessage() instead.
      */

package/dist/theme-editor.d.ts

@@ -4097,6 +4097,22 @@ type InjectMessageOptions = {
      * Consumers can detect this in `messageTransform` to render custom UI.
      */
     voiceProcessing?: boolean;
+    /**
+     * Raw structured payload (typically a JSON string) representing the
+     * full directive that produced this message — e.g. `{ "text": "...",
+     * "component": "Foo", "props": {...} }`.
+     *
+     * Mirrors the field populated by stream parsers during normal LLM
+     * responses. Set this when injecting a message that should render as a
+     * component directive (`hasComponentDirective` /
+     * `extractComponentDirectiveFromMessage` look at `rawContent` first).
+     *
+     * Priority for the API payload remains:
+     * `contentParts > llmContent > rawContent > content`. Pass `llmContent`
+     * alongside `rawContent` if the LLM should see something other than the
+     * raw directive.
+     */
+    rawContent?: string;
 };
 /**
  * Options for injecting assistant messages (most common case).
@@ -4113,6 +4129,57 @@ type InjectUserMessageOptions = Omit<InjectMessageOptions, "role">;
  * Role defaults to 'system'.
  */
 type InjectSystemMessageOptions = Omit<InjectMessageOptions, "role">;
+/**
+ * Options for injecting an assistant message that renders as a component
+ * directive — sugar over `injectAssistantMessage` for the common case of
+ * "render this registered component, same as if the LLM had emitted it".
+ *
+ * Equivalent to calling `injectAssistantMessage({ content: text, rawContent:
+ * JSON.stringify({ text, component, props }), llmContent })`.
+ *
+ * @example
+ * widget.injectComponentDirective({
+ *   component: "DynamicForm",
+ *   props: { title: "Book a demo", fields: [...] },
+ *   text: "Share your details to book a demo.",
+ *   llmContent: "[Showed booking form]"
+ * });
+ */
+type InjectComponentDirectiveOptions = {
+    /**
+     * Name of a renderer registered via `componentRegistry.register(...)`.
+     */
+    component: string;
+    /**
+     * Props passed to the component renderer.
+     */
+    props?: Record<string, unknown>;
+    /**
+     * Bubble copy displayed above (or with) the rendered component.
+     * Mirrors the `text` field in a streamed JSON directive.
+     * @default ""
+     */
+    text?: string;
+    /**
+     * Content sent to the LLM in API requests. When omitted, the raw
+     * directive JSON is what the LLM would see (per the standard
+     * priority chain). Provide a redacted/short version to avoid sending
+     * the full directive in subsequent turns.
+     */
+    llmContent?: string;
+    /**
+     * Optional message ID. If omitted, an assistant id is auto-generated.
+     */
+    id?: string;
+    /**
+     * Optional creation timestamp (ISO string). If omitted, uses current time.
+     */
+    createdAt?: string;
+    /**
+     * Optional sequence number for ordering.
+     */
+    sequence?: number;
+};
 type PersonaArtifactRecord = {
     id: string;
     artifactType: PersonaArtifactKind;
@@ -4480,6 +4547,12 @@ type Controller = {
      * Inject multiple messages in a single batch with one sort and one render pass.
      */
     injectMessageBatch: (optionsList: InjectMessageOptions[]) => AgentWidgetMessage[];
+    /**
+     * Convenience method for injecting an assistant message that renders as a
+     * registered component — same shape Persona produces from a streamed
+     * `{ "text": "...", "component": "...", "props": {...} }` payload.
+     */
+    injectComponentDirective: (options: InjectComponentDirectiveOptions) => AgentWidgetMessage;
     /**
      * @deprecated Use injectMessage() instead.
      */

package/dist/theme-editor.js

@@ -7394,7 +7394,8 @@ var AgentWidgetSession = class _AgentWidgetSession {
       createdAt,
       sequence,
       streaming = false,
-      voiceProcessing
+      voiceProcessing,
+      rawContent
     } = options;
     const messageId = id != null ? id : role === "user" ? generateUserMessageId() : role === "assistant" ? generateAssistantMessageId() : `system-${Date.now()}-${Math.random().toString(16).slice(2)}`;
     const message = {
@@ -7407,7 +7408,8 @@ var AgentWidgetSession = class _AgentWidgetSession {
       // Only include optional fields if provided
       ...llmContent !== void 0 && { llmContent },
       ...contentParts !== void 0 && { contentParts },
-      ...voiceProcessing !== void 0 && { voiceProcessing }
+      ...voiceProcessing !== void 0 && { voiceProcessing },
+      ...rawContent !== void 0 && { rawContent }
     };
     this.upsertMessage(message);
     return message;
@@ -7472,7 +7474,9 @@ var AgentWidgetSession = class _AgentWidgetSession {
         id,
         createdAt,
         sequence,
-        streaming = false
+        streaming = false,
+        voiceProcessing,
+        rawContent
       } = options;
       const messageId = id != null ? id : role === "user" ? generateUserMessageId() : role === "assistant" ? generateAssistantMessageId() : `system-${Date.now()}-${Math.random().toString(16).slice(2)}`;
       const message = {
@@ -7483,7 +7487,9 @@ var AgentWidgetSession = class _AgentWidgetSession {
         sequence: sequence != null ? sequence : this.nextSequence(),
         streaming,
         ...llmContent !== void 0 && { llmContent },
-        ...contentParts !== void 0 && { contentParts }
+        ...contentParts !== void 0 && { contentParts },
+        ...voiceProcessing !== void 0 && { voiceProcessing },
+        ...rawContent !== void 0 && { rawContent }
       };
       results.push(message);
     }
@@ -7491,6 +7497,48 @@ var AgentWidgetSession = class _AgentWidgetSession {
     this.callbacks.onMessagesChanged([...this.messages]);
     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]"
+   * });
+   */
+  injectComponentDirective(options) {
+    const {
+      component,
+      props = {},
+      text = "",
+      llmContent,
+      id,
+      createdAt,
+      sequence
+    } = options;
+    const directive = {
+      text,
+      component,
+      props
+    };
+    return this.injectMessage({
+      role: "assistant",
+      content: text,
+      rawContent: JSON.stringify(directive),
+      ...llmContent !== void 0 && { llmContent },
+      ...id !== void 0 && { id },
+      ...createdAt !== void 0 && { createdAt },
+      ...sequence !== void 0 && { sequence }
+    });
+  }
   async sendMessage(rawInput, options) {
     var _a, _b, _c, _d, _e;
     const input = rawInput.trim();
@@ -15329,24 +15377,39 @@ function renderComponentDirective(directive, options) {
     return null;
   }
 }
+function selectDirectiveSource(message) {
+  if (typeof message.rawContent === "string" && message.rawContent.length > 0) {
+    return message.rawContent;
+  }
+  if (typeof message.content === "string") {
+    const trimmed = message.content.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+      return message.content;
+    }
+  }
+  return null;
+}
 function hasComponentDirective(message) {
-  if (!message.rawContent) return false;
+  const source = selectDirectiveSource(message);
+  if (!source) return false;
   try {
-    const parsed = JSON.parse(message.rawContent);
+    const parsed = JSON.parse(source);
     return typeof parsed === "object" && parsed !== null && "component" in parsed && typeof parsed.component === "string";
   } catch {
     return false;
   }
 }
 function extractComponentDirectiveFromMessage(message) {
-  if (!message.rawContent) return null;
+  const source = selectDirectiveSource(message);
+  if (!source) return null;
   try {
-    const parsed = JSON.parse(message.rawContent);
+    const parsed = JSON.parse(source);
     if (typeof parsed === "object" && parsed !== null && "component" in parsed && typeof parsed.component === "string") {
+      const directive = parsed;
       return {
-        component: parsed.component,
-        props: parsed.props && typeof parsed.props === "object" && parsed.props !== null ? parsed.props : {},
-        raw: message.rawContent
+        component: directive.component,
+        props: directive.props && typeof directive.props === "object" && directive.props !== null ? directive.props : {},
+        raw: source
       };
     }
   } catch {
@@ -20746,6 +20809,12 @@ var createAgentExperience = (mount, initialConfig, runtimeOptions) => {
       }
       return session.injectMessageBatch(optionsList);
     },
+    injectComponentDirective(options) {
+      if (!open && isPanelToggleable()) {
+        setOpenState(true, "system");
+      }
+      return session.injectComponentDirective(options);
+    },
     /** @deprecated Use injectMessage() instead */
     injectTestMessage(event) {
       if (!open && isPanelToggleable()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.19.0",
+  "version": "3.20.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",

package/src/index.ts

@@ -61,6 +61,7 @@ export type {
   InjectAssistantMessageOptions,
   InjectUserMessageOptions,
   InjectSystemMessageOptions,
+  InjectComponentDirectiveOptions,
   // Loading indicator types
   LoadingIndicatorRenderContext,
   AgentWidgetLoadingIndicatorConfig,

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()', () => {