@runtypelabs/persona 1.36.0

package/src/utils/component-middleware.ts

@@ -0,0 +1,137 @@
+import { AgentWidgetMessage, AgentWidgetConfig } from "../types";
+import { componentRegistry, ComponentContext } from "../components/registry";
+import { ComponentDirective, createComponentStreamParser } from "./component-parser";
+import { createStandardBubble, MessageTransform } from "../components/message-bubble";
+
+/**
+ * Options for component middleware
+ */
+export interface ComponentMiddlewareOptions {
+  config: AgentWidgetConfig;
+  message: AgentWidgetMessage;
+  transform: MessageTransform;
+  onPropsUpdate?: (props: Record<string, unknown>) => void;
+}
+
+/**
+ * Renders a component directive into an HTMLElement
+ */
+export function renderComponentDirective(
+  directive: ComponentDirective,
+  options: ComponentMiddlewareOptions
+): HTMLElement | null {
+  const { config, message, onPropsUpdate } = options;
+
+  // Get component renderer from registry
+  const renderer = componentRegistry.get(directive.component);
+  if (!renderer) {
+    // Component not found, fall back to default rendering
+    console.warn(
+      `[ComponentMiddleware] Component "${directive.component}" not found in registry. Falling back to default rendering.`
+    );
+    return null;
+  }
+
+  // Create component context
+  const context: ComponentContext = {
+    message,
+    config,
+    updateProps: (newProps: Record<string, unknown>) => {
+      if (onPropsUpdate) {
+        onPropsUpdate(newProps);
+      }
+    }
+  };
+
+  try {
+    // Render the component
+    const element = renderer(directive.props, context);
+    return element;
+  } catch (error) {
+    console.error(
+      `[ComponentMiddleware] Error rendering component "${directive.component}":`,
+      error
+    );
+    return null;
+  }
+}
+
+/**
+ * Creates middleware that processes component directives from streamed JSON
+ */
+export function createComponentMiddleware() {
+  const parser = createComponentStreamParser();
+
+  return {
+    /**
+     * Process accumulated content and extract component directive
+     */
+    processChunk: (accumulatedContent: string): ComponentDirective | null => {
+      return parser.processChunk(accumulatedContent);
+    },
+
+    /**
+     * Get the currently extracted directive
+     */
+    getDirective: (): ComponentDirective | null => {
+      return parser.getExtractedDirective();
+    },
+
+    /**
+     * Reset the parser state
+     */
+    reset: () => {
+      parser.reset();
+    }
+  };
+}
+
+/**
+ * Checks if a message contains a component directive in its raw content
+ */
+export function hasComponentDirective(message: AgentWidgetMessage): boolean {
+  if (!message.rawContent) return false;
+  
+  try {
+    const parsed = JSON.parse(message.rawContent);
+    return (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      "component" in parsed &&
+      typeof parsed.component === "string"
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extracts component directive from a complete message
+ */
+export function extractComponentDirectiveFromMessage(
+  message: AgentWidgetMessage
+): ComponentDirective | null {
+  if (!message.rawContent) return null;
+
+  try {
+    const parsed = JSON.parse(message.rawContent);
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      "component" in parsed &&
+      typeof parsed.component === "string"
+    ) {
+      return {
+        component: parsed.component,
+        props: (parsed.props && typeof parsed.props === "object" && parsed.props !== null
+          ? parsed.props
+          : {}) as Record<string, unknown>,
+        raw: message.rawContent
+      };
+    }
+  } catch {
+    // Not valid JSON or not a component directive
+  }
+
+  return null;
+}

package/src/utils/component-parser.ts

@@ -0,0 +1,119 @@
+import { parse as parsePartialJson, STR, OBJ } from "partial-json";
+
+/**
+ * Represents a component directive extracted from JSON
+ */
+export interface ComponentDirective {
+  component: string;
+  props: Record<string, unknown>;
+  raw: string;
+}
+
+/**
+ * Checks if a parsed object is a component directive
+ */
+function isComponentDirective(obj: unknown): obj is { component: string; props?: unknown } {
+  if (!obj || typeof obj !== "object") return false;
+  if (!("component" in obj)) return false;
+  const component = (obj as { component: unknown }).component;
+  return typeof component === "string" && component.length > 0;
+}
+
+/**
+ * Extracts component directive from parsed JSON object
+ */
+function extractComponentDirective(
+  parsed: unknown,
+  rawJson: string
+): ComponentDirective | null {
+  if (!isComponentDirective(parsed)) {
+    return null;
+  }
+
+  const props = parsed.props && typeof parsed.props === "object" && parsed.props !== null
+    ? (parsed.props as Record<string, unknown>)
+    : {};
+
+  return {
+    component: parsed.component,
+    props,
+    raw: rawJson
+  };
+}
+
+/**
+ * Creates a parser that extracts component directives from JSON streams
+ * This parser looks for objects with a "component" field and extracts
+ * the component name and props incrementally as they stream in.
+ */
+export function createComponentStreamParser() {
+  let extractedDirective: ComponentDirective | null = null;
+  let processedLength = 0;
+
+  return {
+    /**
+     * Get the currently extracted component directive
+     */
+    getExtractedDirective: (): ComponentDirective | null => {
+      return extractedDirective;
+    },
+
+    /**
+     * Process a chunk of JSON and extract component directive if present
+     */
+    processChunk: (accumulatedContent: string): ComponentDirective | null => {
+      // Validate that the accumulated content looks like JSON
+      const trimmed = accumulatedContent.trim();
+      if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+        return null;
+      }
+
+      // Skip if no new content
+      if (accumulatedContent.length <= processedLength) {
+        return extractedDirective;
+      }
+
+      try {
+        // Parse partial JSON - allow partial strings and objects during streaming
+        // STR | OBJ allows incomplete strings and objects during streaming
+        const parsed = parsePartialJson(accumulatedContent, STR | OBJ);
+
+        // Try to extract component directive
+        const directive = extractComponentDirective(parsed, accumulatedContent);
+        if (directive) {
+          extractedDirective = directive;
+        }
+      } catch (error) {
+        // If parsing fails completely, keep the last extracted directive
+        // This can happen with very malformed JSON during streaming
+      }
+
+      // Update processed length
+      processedLength = accumulatedContent.length;
+
+      return extractedDirective;
+    },
+
+    /**
+     * Reset the parser state
+     */
+    reset: () => {
+      extractedDirective = null;
+      processedLength = 0;
+    }
+  };
+}
+
+/**
+ * Type guard to check if an object is a component directive
+ */
+export function isComponentDirectiveType(obj: unknown): obj is ComponentDirective {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "component" in obj &&
+    typeof (obj as { component: unknown }).component === "string" &&
+    "props" in obj &&
+    typeof (obj as { props: unknown }).props === "object"
+  );
+}

package/src/utils/constants.ts

@@ -0,0 +1,16 @@
+import { AgentWidgetSessionStatus } from "../session";
+
+export const statusCopy: Record<AgentWidgetSessionStatus, string> = {
+  idle: "Online",
+  connecting: "Connecting…",
+  connected: "Streaming…",
+  error: "Offline"
+};
+
+
+
+
+
+
+
+

package/src/utils/content.ts

@@ -0,0 +1,306 @@
+/**
+ * Content Utilities
+ *
+ * Helper functions for working with multi-modal message content.
+ */
+
+import type { MessageContent, ContentPart, TextContentPart, ImageContentPart, FileContentPart } from '../types';
+
+/**
+ * Normalize content to ContentPart[] format.
+ * Converts string content to a single text content part.
+ */
+export function normalizeContent(content: MessageContent): ContentPart[] {
+  if (typeof content === 'string') {
+    return [{ type: 'text', text: content }];
+  }
+  return content;
+}
+
+/**
+ * Extract display text from content parts.
+ * Concatenates all text parts into a single string.
+ */
+export function getDisplayText(content: MessageContent): string {
+  if (typeof content === 'string') {
+    return content;
+  }
+  return content
+    .filter((part): part is TextContentPart => part.type === 'text')
+    .map(part => part.text)
+    .join('');
+}
+
+/**
+ * Check if content contains any images.
+ */
+export function hasImages(content: MessageContent): boolean {
+  if (typeof content === 'string') {
+    return false;
+  }
+  return content.some(part => part.type === 'image');
+}
+
+/**
+ * Get all image parts from content.
+ */
+export function getImageParts(content: MessageContent): ImageContentPart[] {
+  if (typeof content === 'string') {
+    return [];
+  }
+  return content.filter((part): part is ImageContentPart => part.type === 'image');
+}
+
+/**
+ * Create a text-only content part.
+ */
+export function createTextPart(text: string): TextContentPart {
+  return { type: 'text', text };
+}
+
+/**
+ * Create an image content part from a base64 data URI or URL.
+ *
+ * @param image - Base64 data URI (data:image/...) or URL
+ * @param options - Optional mimeType and alt text
+ */
+export function createImagePart(
+  image: string,
+  options?: { mimeType?: string; alt?: string }
+): ImageContentPart {
+  return {
+    type: 'image',
+    image,
+    ...(options?.mimeType && { mimeType: options.mimeType }),
+    ...(options?.alt && { alt: options.alt }),
+  };
+}
+
+/**
+ * Convert a File object to an image content part.
+ * Reads the file and converts it to a base64 data URI.
+ */
+export async function fileToImagePart(file: File): Promise<ImageContentPart> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      const dataUri = reader.result as string;
+      resolve({
+        type: 'image',
+        image: dataUri,
+        mimeType: file.type,
+        alt: file.name,
+      });
+    };
+    reader.onerror = () => reject(new Error('Failed to read file'));
+    reader.readAsDataURL(file);
+  });
+}
+
+/**
+ * Validate that a file is an acceptable image type.
+ *
+ * @param file - The file to validate
+ * @param acceptedTypes - Array of accepted MIME types (default: common image types)
+ * @param maxSizeBytes - Maximum file size in bytes (default: 10MB)
+ */
+export function validateImageFile(
+  file: File,
+  acceptedTypes: string[] = ['image/png', 'image/jpeg', 'image/gif', 'image/webp'],
+  maxSizeBytes: number = 10 * 1024 * 1024
+): { valid: boolean; error?: string } {
+  if (!acceptedTypes.includes(file.type)) {
+    return {
+      valid: false,
+      error: `Invalid file type. Accepted types: ${acceptedTypes.join(', ')}`,
+    };
+  }
+
+  if (file.size > maxSizeBytes) {
+    const maxSizeMB = Math.round(maxSizeBytes / (1024 * 1024));
+    return {
+      valid: false,
+      error: `File too large. Maximum size: ${maxSizeMB}MB`,
+    };
+  }
+
+  return { valid: true };
+}
+
+// ============================================================================
+// Generic File Utilities (for PDF, TXT, DOCX, etc.)
+// ============================================================================
+
+/**
+ * Common image MIME types
+ */
+export const IMAGE_MIME_TYPES = [
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/svg+xml',
+  'image/bmp',
+];
+
+/**
+ * Common document MIME types
+ */
+export const DOCUMENT_MIME_TYPES = [
+  'application/pdf',
+  'text/plain',
+  'text/markdown',
+  'text/csv',
+  'application/msword',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  'application/vnd.ms-excel',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  'application/json',
+];
+
+/**
+ * All supported file types (images + documents)
+ */
+export const ALL_SUPPORTED_MIME_TYPES = [...IMAGE_MIME_TYPES, ...DOCUMENT_MIME_TYPES];
+
+/**
+ * Check if a MIME type is an image
+ */
+export function isImageMimeType(mimeType: string): boolean {
+  return IMAGE_MIME_TYPES.includes(mimeType) || mimeType.startsWith('image/');
+}
+
+/**
+ * Check if a file is an image
+ */
+export function isImageFile(file: File): boolean {
+  return isImageMimeType(file.type);
+}
+
+/**
+ * Create a file content part from a base64 data URI.
+ */
+export function createFilePart(
+  data: string,
+  mimeType: string,
+  filename: string
+): FileContentPart {
+  return {
+    type: 'file',
+    data,
+    mimeType,
+    filename,
+  };
+}
+
+/**
+ * Convert a File object to a content part.
+ * Returns ImageContentPart for images, FileContentPart for other files.
+ */
+export async function fileToContentPart(file: File): Promise<ImageContentPart | FileContentPart> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      const dataUri = reader.result as string;
+
+      if (isImageFile(file)) {
+        // Return image content part for images
+        resolve({
+          type: 'image',
+          image: dataUri,
+          mimeType: file.type,
+          alt: file.name,
+        });
+      } else {
+        // Return file content part for documents
+        resolve({
+          type: 'file',
+          data: dataUri,
+          mimeType: file.type,
+          filename: file.name,
+        });
+      }
+    };
+    reader.onerror = () => reject(new Error('Failed to read file'));
+    reader.readAsDataURL(file);
+  });
+}
+
+/**
+ * Validate that a file is an acceptable type.
+ *
+ * @param file - The file to validate
+ * @param acceptedTypes - Array of accepted MIME types
+ * @param maxSizeBytes - Maximum file size in bytes (default: 10MB)
+ */
+export function validateFile(
+  file: File,
+  acceptedTypes: string[] = ALL_SUPPORTED_MIME_TYPES,
+  maxSizeBytes: number = 10 * 1024 * 1024
+): { valid: boolean; error?: string } {
+  if (!acceptedTypes.includes(file.type)) {
+    return {
+      valid: false,
+      error: `Invalid file type "${file.type}". Accepted types: ${acceptedTypes.join(', ')}`,
+    };
+  }
+
+  if (file.size > maxSizeBytes) {
+    const maxSizeMB = Math.round(maxSizeBytes / (1024 * 1024));
+    return {
+      valid: false,
+      error: `File too large. Maximum size: ${maxSizeMB}MB`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Get file parts from content.
+ */
+export function getFileParts(content: MessageContent): FileContentPart[] {
+  if (typeof content === 'string') {
+    return [];
+  }
+  return content.filter((part): part is FileContentPart => part.type === 'file');
+}
+
+/**
+ * Check if content contains any files.
+ */
+export function hasFiles(content: MessageContent): boolean {
+  if (typeof content === 'string') {
+    return false;
+  }
+  return content.some(part => part.type === 'file');
+}
+
+/**
+ * Get file extension from filename
+ */
+export function getFileExtension(filename: string): string {
+  const parts = filename.split('.');
+  return parts.length > 1 ? parts.pop()!.toLowerCase() : '';
+}
+
+/**
+ * Get a display-friendly file type name
+ */
+export function getFileTypeName(mimeType: string, filename: string): string {
+  const ext = getFileExtension(filename).toUpperCase();
+
+  const typeMap: Record<string, string> = {
+    'application/pdf': 'PDF',
+    'text/plain': 'TXT',
+    'text/markdown': 'MD',
+    'text/csv': 'CSV',
+    'application/msword': 'DOC',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'DOCX',
+    'application/vnd.ms-excel': 'XLS',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'XLSX',
+    'application/json': 'JSON',
+  };
+
+  return typeMap[mimeType] || ext || 'FILE';
+}

package/src/utils/dom.ts

@@ -0,0 +1,25 @@
+/**
+ * DOM utility functions
+ */
+export const createElement = <K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  className?: string
+): HTMLElementTagNameMap[K] => {
+  const element = document.createElement(tag);
+  if (className) {
+    element.className = className;
+  }
+  return element;
+};
+
+export const createFragment = (): DocumentFragment => {
+  return document.createDocumentFragment();
+};
+
+
+
+
+
+
+
+

package/src/utils/events.ts

@@ -0,0 +1,41 @@
+type Handler<T> = (payload: T) => void;
+
+export type EventUnsubscribe = () => void;
+
+export const createEventBus = <EventMap extends Record<string, any>>() => {
+  const listeners = new Map<keyof EventMap, Set<Handler<any>>>();
+
+  const on = <K extends keyof EventMap>(
+    event: K,
+    handler: Handler<EventMap[K]>
+  ): EventUnsubscribe => {
+    if (!listeners.has(event)) {
+      listeners.set(event, new Set());
+    }
+    listeners.get(event)!.add(handler as Handler<any>);
+    return () => off(event, handler);
+  };
+
+  const off = <K extends keyof EventMap>(
+    event: K,
+    handler: Handler<EventMap[K]>
+  ) => {
+    listeners.get(event)?.delete(handler as Handler<any>);
+  };
+
+  const emit = <K extends keyof EventMap>(event: K, payload: EventMap[K]) => {
+    listeners.get(event)?.forEach((handler) => {
+      try {
+        handler(payload);
+      } catch (error) {
+        if (typeof console !== "undefined") {
+          // eslint-disable-next-line no-console
+          console.error("[AgentWidget] Event handler error:", error);
+        }
+      }
+    });
+  };
+
+  return { on, off, emit };
+};
+