@runtypelabs/persona 3.19.0 → 3.21.0

package/dist/theme-editor.cjs

@@ -3790,6 +3790,28 @@ var SequenceReorderBuffer = class {
 // src/client.ts
 var DEFAULT_ENDPOINT = "https://api.runtype.com/v1/dispatch";
 var DEFAULT_CLIENT_API_BASE = "https://api.runtype.com";
+function filenameFromMediaType(mediaType) {
+  var _a, _b;
+  const lower = mediaType.toLowerCase();
+  const knownExtensions = {
+    "application/pdf": "pdf",
+    "application/json": "json",
+    "application/zip": "zip",
+    "text/plain": "txt",
+    "text/csv": "csv",
+    "text/markdown": "md"
+  };
+  const ext = knownExtensions[lower];
+  if (ext) return `attachment.${ext}`;
+  const slash = lower.indexOf("/");
+  if (slash > 0) {
+    const subtype = (_b = (_a = lower.slice(slash + 1).split(";")[0]) == null ? void 0 : _a.trim()) != null ? _b : "";
+    if (subtype && subtype !== "octet-stream" && /^[a-z0-9.+-]+$/i.test(subtype)) {
+      return `attachment.${subtype}`;
+    }
+  }
+  return "attachment";
+}
 var hasValidContent = (message) => {
   if (message.contentParts && message.contentParts.length > 0) {
     return true;
@@ -5742,6 +5764,89 @@ var AgentWidgetClient = class {
               }
             }
           }
+        } else if (payloadType === "agent_media") {
+          const rawMedia = Array.isArray(payload.media) ? payload.media : [];
+          const mediaContentParts = [];
+          for (const part of rawMedia) {
+            if (!part || typeof part !== "object") continue;
+            const rec = part;
+            const partType = typeof rec.type === "string" ? rec.type : void 0;
+            const rawMediaType = typeof rec.mediaType === "string" ? rec.mediaType.toLowerCase() : "";
+            let src = null;
+            let mediaType = "";
+            if (partType === "media") {
+              const data = typeof rec.data === "string" ? rec.data : void 0;
+              if (!data) continue;
+              mediaType = rawMediaType.length > 0 ? rawMediaType : "application/octet-stream";
+              src = `data:${mediaType};base64,${data}`;
+            } else if (partType === "image-url") {
+              const url = typeof rec.url === "string" ? rec.url : void 0;
+              if (!url) continue;
+              mediaType = rawMediaType;
+              src = url;
+            } else if (partType === "file-url") {
+              const url = typeof rec.url === "string" ? rec.url : void 0;
+              if (!url) continue;
+              mediaType = rawMediaType;
+              src = url;
+            } else {
+              continue;
+            }
+            if (!src) continue;
+            if (partType === "image-url" || mediaType.startsWith("image/")) {
+              mediaContentParts.push({
+                type: "image",
+                image: src,
+                ...mediaType ? { mimeType: mediaType } : {}
+              });
+            } else if (mediaType.startsWith("audio/")) {
+              mediaContentParts.push({
+                type: "audio",
+                audio: src,
+                mimeType: mediaType
+              });
+            } else if (mediaType.startsWith("video/")) {
+              mediaContentParts.push({
+                type: "video",
+                video: src,
+                mimeType: mediaType
+              });
+            } else {
+              const resolvedMediaType = mediaType || "application/octet-stream";
+              mediaContentParts.push({
+                type: "file",
+                data: src,
+                mimeType: resolvedMediaType,
+                filename: filenameFromMediaType(resolvedMediaType)
+              });
+            }
+          }
+          if (mediaContentParts.length > 0) {
+            const seq = nextSequence();
+            const toolCallIdRaw = payload.toolCallId;
+            const mediaIdSuffix = typeof toolCallIdRaw === "string" && toolCallIdRaw.length > 0 ? `${toolCallIdRaw}-${seq}` : String(seq);
+            const mediaMessage = {
+              id: `agent-media-${mediaIdSuffix}`,
+              role: "assistant",
+              content: "",
+              contentParts: mediaContentParts,
+              createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+              streaming: false,
+              sequence: seq,
+              agentMetadata: {
+                executionId: payload.executionId,
+                iteration: payload.iteration
+              }
+            };
+            emitMessage(mediaMessage);
+            const prevAssistant = assistantMessage;
+            if (prevAssistant) {
+              prevAssistant.streaming = false;
+              emitMessage(prevAssistant);
+            }
+            assistantMessage = null;
+            assistantMessageRef.current = null;
+          }
         } else if (payloadType === "agent_iteration_complete") {
         } else if (payloadType === "agent_reflection" || payloadType === "agent_reflect") {
           const reflectionId = `agent-reflection-${payload.executionId}-${payload.iteration}`;
@@ -7505,7 +7610,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 +7624,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 +7690,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 +7703,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 +7713,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();
@@ -11074,6 +11227,19 @@ var isSafeImageSrc = (src) => {
   if (!src.includes(":")) return true;
   return false;
 };
+var isSafeMediaSrc = (src) => {
+  const lower = src.toLowerCase();
+  if (lower.startsWith("javascript:")) return false;
+  if (lower.startsWith("data:text/html")) return false;
+  if (lower.startsWith("data:text/javascript")) return false;
+  if (lower.startsWith("data:text/xml")) return false;
+  if (lower.startsWith("data:application/xhtml")) return false;
+  if (lower.startsWith("data:image/svg+xml")) return false;
+  if (/^(?:https?|blob):/i.test(src)) return true;
+  if (lower.startsWith("data:")) return true;
+  if (!src.includes(":")) return true;
+  return false;
+};
 var MESSAGE_IMAGE_PREVIEW_MAX_WIDTH_PX = 320;
 var MESSAGE_IMAGE_PREVIEW_MAX_HEIGHT_PX = 320;
 var getMessageImageParts = (message) => {
@@ -11084,6 +11250,24 @@ var getMessageImageParts = (message) => {
     (part) => part.type === "image" && typeof part.image === "string" && part.image.trim().length > 0
   );
 };
+var getMessageAudioParts = (message) => {
+  if (!message.contentParts || message.contentParts.length === 0) return [];
+  return message.contentParts.filter(
+    (part) => part.type === "audio" && typeof part.audio === "string" && part.audio.trim().length > 0
+  );
+};
+var getMessageVideoParts = (message) => {
+  if (!message.contentParts || message.contentParts.length === 0) return [];
+  return message.contentParts.filter(
+    (part) => part.type === "video" && typeof part.video === "string" && part.video.trim().length > 0
+  );
+};
+var getMessageFileParts = (message) => {
+  if (!message.contentParts || message.contentParts.length === 0) return [];
+  return message.contentParts.filter(
+    (part) => part.type === "file" && typeof part.data === "string" && part.data.trim().length > 0
+  );
+};
 var createMessageImagePreviews = (imageParts, hasVisibleText, onPreviewFailed) => {
   if (imageParts.length === 0) return null;
   try {
@@ -11152,6 +11336,109 @@ var createMessageImagePreviews = (imageParts, hasVisibleText, onPreviewFailed) =
     return null;
   }
 };
+var createMessageAudioPreviews = (audioParts) => {
+  if (audioParts.length === 0) return null;
+  try {
+    const container = createElement(
+      "div",
+      "persona-flex persona-flex-col persona-gap-2"
+    );
+    container.setAttribute("data-message-attachments", "audio");
+    let visible = 0;
+    audioParts.forEach((part) => {
+      if (!isSafeMediaSrc(part.audio)) return;
+      const audioElement = createElement("audio");
+      audioElement.controls = true;
+      audioElement.preload = "metadata";
+      audioElement.src = part.audio;
+      audioElement.style.display = "block";
+      audioElement.style.width = "100%";
+      audioElement.style.maxWidth = `${MESSAGE_IMAGE_PREVIEW_MAX_WIDTH_PX}px`;
+      container.appendChild(audioElement);
+      visible += 1;
+    });
+    if (visible === 0) {
+      container.remove();
+      return null;
+    }
+    return container;
+  } catch {
+    return null;
+  }
+};
+var createMessageVideoPreviews = (videoParts) => {
+  if (videoParts.length === 0) return null;
+  try {
+    const container = createElement(
+      "div",
+      "persona-flex persona-flex-col persona-gap-2"
+    );
+    container.setAttribute("data-message-attachments", "video");
+    let visible = 0;
+    videoParts.forEach((part) => {
+      if (!isSafeMediaSrc(part.video)) return;
+      const videoElement = createElement("video");
+      videoElement.controls = true;
+      videoElement.preload = "metadata";
+      videoElement.src = part.video;
+      videoElement.style.display = "block";
+      videoElement.style.width = "100%";
+      videoElement.style.maxWidth = `${MESSAGE_IMAGE_PREVIEW_MAX_WIDTH_PX}px`;
+      videoElement.style.maxHeight = `${MESSAGE_IMAGE_PREVIEW_MAX_HEIGHT_PX}px`;
+      videoElement.style.borderRadius = "10px";
+      videoElement.style.backgroundColor = "var(--persona-attachment-image-bg, var(--persona-container, #f3f4f6))";
+      container.appendChild(videoElement);
+      visible += 1;
+    });
+    if (visible === 0) {
+      container.remove();
+      return null;
+    }
+    return container;
+  } catch {
+    return null;
+  }
+};
+var createMessageFilePreviews = (fileParts) => {
+  if (fileParts.length === 0) return null;
+  try {
+    const container = createElement(
+      "div",
+      "persona-flex persona-flex-col persona-gap-2"
+    );
+    container.setAttribute("data-message-attachments", "files");
+    let visible = 0;
+    fileParts.forEach((part) => {
+      if (!isSafeMediaSrc(part.data)) return;
+      const link = createElement("a");
+      link.href = part.data;
+      link.download = part.filename;
+      link.target = "_blank";
+      link.rel = "noopener noreferrer";
+      link.textContent = part.filename;
+      link.className = "persona-message-file-attachment";
+      link.style.display = "inline-flex";
+      link.style.alignItems = "center";
+      link.style.gap = "6px";
+      link.style.padding = "6px 10px";
+      link.style.borderRadius = "8px";
+      link.style.fontSize = "0.875rem";
+      link.style.textDecoration = "underline";
+      link.style.backgroundColor = "var(--persona-attachment-file-bg, var(--persona-container, #f3f4f6))";
+      link.style.border = "1px solid var(--persona-attachment-file-border, var(--persona-border, #e5e7eb))";
+      link.style.color = "inherit";
+      container.appendChild(link);
+      visible += 1;
+    });
+    if (visible === 0) {
+      container.remove();
+      return null;
+    }
+    return container;
+  } catch {
+    return null;
+  }
+};
 var createTypingIndicator = () => {
   const container = document.createElement("div");
   container.className = "persona-flex persona-items-center persona-space-x-1 persona-h-5 persona-mt-2";
@@ -11482,6 +11769,27 @@ var createStandardBubble = (message, transform, layoutConfig, actionsConfig, act
       textContentDiv.style.display = "";
     }
   }
+  const audioParts = getMessageAudioParts(message);
+  if (audioParts.length > 0) {
+    const audioPreviews = createMessageAudioPreviews(audioParts);
+    if (audioPreviews) {
+      bubble.appendChild(audioPreviews);
+    }
+  }
+  const videoParts = getMessageVideoParts(message);
+  if (videoParts.length > 0) {
+    const videoPreviews = createMessageVideoPreviews(videoParts);
+    if (videoPreviews) {
+      bubble.appendChild(videoPreviews);
+    }
+  }
+  const fileParts = getMessageFileParts(message);
+  if (fileParts.length > 0) {
+    const filePreviews = createMessageFilePreviews(fileParts);
+    if (filePreviews) {
+      bubble.appendChild(filePreviews);
+    }
+  }
   bubble.appendChild(contentDiv);
   if (showTimestamp && timestampPosition === "below" && message.createdAt) {
     const timestamp = createTimestamp(message, timestampConfig);
@@ -15326,24 +15634,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 +21066,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

@@ -728,10 +728,28 @@ type FileContentPart = {
     mimeType: string;
     filename: string;
 };
+/**
+ * Audio content part for multi-modal messages
+ * Supports base64 data URIs or URLs
+ */
+type AudioContentPart = {
+    type: 'audio';
+    audio: string;
+    mimeType?: string;
+};
+/**
+ * Video content part for multi-modal messages
+ * Supports base64 data URIs or URLs
+ */
+type VideoContentPart = {
+    type: 'video';
+    video: string;
+    mimeType?: string;
+};
 /**
  * Union type for all content part types
  */
-type ContentPart = TextContentPart | ImageContentPart | FileContentPart;
+type ContentPart = TextContentPart | ImageContentPart | FileContentPart | AudioContentPart | VideoContentPart;
 /**
  * Message content can be a simple string or an array of content parts
  */
@@ -4097,6 +4115,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 +4147,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 +4565,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

@@ -728,10 +728,28 @@ type FileContentPart = {
     mimeType: string;
     filename: string;
 };
+/**
+ * Audio content part for multi-modal messages
+ * Supports base64 data URIs or URLs
+ */
+type AudioContentPart = {
+    type: 'audio';
+    audio: string;
+    mimeType?: string;
+};
+/**
+ * Video content part for multi-modal messages
+ * Supports base64 data URIs or URLs
+ */
+type VideoContentPart = {
+    type: 'video';
+    video: string;
+    mimeType?: string;
+};
 /**
  * Union type for all content part types
  */
-type ContentPart = TextContentPart | ImageContentPart | FileContentPart;
+type ContentPart = TextContentPart | ImageContentPart | FileContentPart | AudioContentPart | VideoContentPart;
 /**
  * Message content can be a simple string or an array of content parts
  */
@@ -4097,6 +4115,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 +4147,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 +4565,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.
      */