@runtypelabs/persona 1.36.0

package/src/index.ts

@@ -0,0 +1,175 @@
+import {
+  initAgentWidget as initAgentWidgetFn,
+  type AgentWidgetInitHandle
+} from "./runtime/init";
+
+export type {
+  AgentWidgetConfig,
+  AgentWidgetTheme,
+  AgentWidgetFeatureFlags,
+  AgentWidgetInitOptions,
+  AgentWidgetMessage,
+  AgentWidgetLauncherConfig,
+  AgentWidgetEvent,
+  AgentWidgetStreamParser,
+  AgentWidgetStreamParserResult,
+  AgentWidgetRequestPayload,
+  AgentWidgetCustomFetch,
+  AgentWidgetSSEEventParser,
+  AgentWidgetSSEEventResult,
+  AgentWidgetHeadersFunction,
+  // Multi-modal content types
+  TextContentPart,
+  ImageContentPart,
+  ContentPart,
+  MessageContent,
+  // Attachment config type
+  AgentWidgetAttachmentsConfig,
+  // Layout types
+  AgentWidgetLayoutConfig,
+  AgentWidgetHeaderLayoutConfig,
+  AgentWidgetMessageLayoutConfig,
+  AgentWidgetAvatarConfig,
+  AgentWidgetTimestampConfig,
+  WidgetLayoutSlot,
+  SlotRenderer,
+  SlotRenderContext,
+  HeaderRenderContext,
+  MessageRenderContext,
+  // Markdown types
+  AgentWidgetMarkdownConfig,
+  AgentWidgetMarkdownOptions,
+  AgentWidgetMarkdownRendererOverrides,
+  // Message actions types
+  AgentWidgetMessageActionsConfig,
+  AgentWidgetMessageFeedback,
+  // Client token types
+  ClientSession,
+  ClientInitResponse,
+  ClientChatRequest,
+  ClientFeedbackRequest,
+  ClientFeedbackType
+} from "./types";
+
+export { initAgentWidgetFn as initAgentWidget };
+export {
+  createAgentExperience,
+  type AgentWidgetController
+} from "./ui";
+export {
+  AgentWidgetSession,
+  type AgentWidgetSessionStatus
+} from "./session";
+export { AgentWidgetClient } from "./client";
+export { createLocalStorageAdapter } from "./utils/storage";
+export {
+  createActionManager,
+  defaultActionHandlers,
+  defaultJsonActionParser
+} from "./utils/actions";
+export {
+  markdownPostprocessor,
+  escapeHtml,
+  directivePostprocessor,
+  createMarkdownProcessor,
+  createMarkdownProcessorFromConfig,
+  createDirectivePostprocessor
+} from "./postprocessors";
+export type { MarkdownProcessorOptions } from "./postprocessors";
+export {
+  createPlainTextParser,
+  createJsonStreamParser,
+  createFlexibleJsonStreamParser,
+  createRegexJsonParser,
+  createXmlParser
+} from "./utils/formatting";
+export {
+  // Multi-modal content utilities
+  normalizeContent,
+  getDisplayText,
+  hasImages,
+  getImageParts,
+  createTextPart,
+  createImagePart,
+  fileToImagePart,
+  validateImageFile
+} from "./utils/content";
+export {
+  AttachmentManager,
+  type PendingAttachment,
+  type AttachmentManagerConfig
+} from "./utils/attachment-manager";
+export {
+  generateMessageId,
+  generateUserMessageId,
+  generateAssistantMessageId
+} from "./utils/message-id";
+export { generateCodeSnippet } from "./utils/code-generators";
+export type { CodeFormat, CodeGeneratorHooks, CodeGeneratorOptions } from "./utils/code-generators";
+export type { AgentWidgetInitHandle };
+
+// Plugin system exports
+export type { AgentWidgetPlugin } from "./plugins/types";
+export { pluginRegistry } from "./plugins/registry";
+
+// Component system exports
+export { componentRegistry } from "./components/registry";
+export type { ComponentRenderer, ComponentContext } from "./components/registry";
+export {
+  createComponentStreamParser,
+  isComponentDirectiveType
+} from "./utils/component-parser";
+export type { ComponentDirective } from "./utils/component-parser";
+export {
+  renderComponentDirective,
+  createComponentMiddleware,
+  hasComponentDirective,
+  extractComponentDirectiveFromMessage
+} from "./utils/component-middleware";
+
+// Default configuration exports
+export {
+  DEFAULT_WIDGET_CONFIG,
+  DEFAULT_LIGHT_THEME,
+  DEFAULT_DARK_THEME,
+  mergeWithDefaults
+} from "./defaults";
+
+// Layout system exports
+export {
+  buildHeader,
+  buildComposer,
+  attachHeaderToContainer
+} from "./components/panel";
+export type {
+  HeaderElements,
+  HeaderBuildContext,
+  ComposerElements,
+  ComposerBuildContext
+} from "./components/panel";
+export {
+  headerLayouts,
+  getHeaderLayout,
+  buildHeaderWithLayout,
+  buildDefaultHeader,
+  buildMinimalHeader,
+  buildExpandedHeader
+} from "./components/header-layouts";
+export type {
+  HeaderLayoutContext,
+  HeaderLayoutRenderer
+} from "./components/header-layouts";
+export {
+  createStandardBubble,
+  createBubbleWithLayout,
+  createTypingIndicator,
+  createMessageActions
+} from "./components/message-bubble";
+export type { MessageTransform, MessageActionCallbacks } from "./components/message-bubble";
+export {
+  createCSATFeedback,
+  createNPSFeedback
+} from "./components/feedback";
+export type { CSATFeedbackOptions, NPSFeedbackOptions } from "./components/feedback";
+
+export default initAgentWidgetFn;

package/src/install.ts

@@ -0,0 +1,284 @@
+/**
+ * Standalone installer script for easy script tag installation
+ * This script automatically loads CSS and JS, then initializes the widget
+ * if configuration is provided via window.siteAgentConfig
+ */
+
+interface SiteAgentInstallConfig {
+  version?: string;
+  cdn?: "unpkg" | "jsdelivr";
+  cssUrl?: string;
+  jsUrl?: string;
+  target?: string | HTMLElement;
+  config?: any;
+  autoInit?: boolean;
+  // Client token mode options (can also be set via data attributes)
+  clientToken?: string;
+  flowId?: string;
+  apiUrl?: string;
+  // Shadow DOM option (defaults to false for better CSS compatibility)
+  useShadowDom?: boolean;
+}
+
+declare global {
+  interface Window {
+    siteAgentConfig?: SiteAgentInstallConfig;
+    AgentWidget?: any;
+  }
+}
+
+(function() {
+  "use strict";
+
+  // Prevent double installation
+  if ((window as any).__siteAgentInstallerLoaded) {
+    return;
+  }
+  (window as any).__siteAgentInstallerLoaded = true;
+
+  /**
+   * Read configuration from data attributes on the current script tag.
+   * Supports: data-config (JSON), data-travrse-token, data-flow-id, data-api-url
+   */
+  const getConfigFromScript = (): Partial<SiteAgentInstallConfig> => {
+    // Try to get the current script element
+    const script = document.currentScript as HTMLScriptElement | null;
+    if (!script) return {};
+
+    const scriptConfig: Partial<SiteAgentInstallConfig> = {};
+
+    // Full config from data-config attribute (JSON string)
+    const configJson = script.getAttribute('data-config');
+    if (configJson) {
+      try {
+        const parsedConfig = JSON.parse(configJson);
+        // If it has nested 'config' property, use it; otherwise treat as widget config
+        if (parsedConfig.config) {
+          Object.assign(scriptConfig, parsedConfig);
+        } else {
+          // Treat the entire object as widget config
+          scriptConfig.config = parsedConfig;
+        }
+      } catch (e) {
+        console.error("Failed to parse data-config JSON:", e);
+      }
+    }
+
+    // Client token from data attribute (primary method for client token mode)
+    const token = script.getAttribute('data-travrse-token');
+    if (token) {
+      scriptConfig.clientToken = token;
+    }
+
+    // Optional flow ID
+    const flowId = script.getAttribute('data-flow-id');
+    if (flowId) {
+      scriptConfig.flowId = flowId;
+    }
+
+    // Optional API URL override
+    const apiUrl = script.getAttribute('data-api-url');
+    if (apiUrl) {
+      scriptConfig.apiUrl = apiUrl;
+    }
+
+    return scriptConfig;
+  };
+
+  // Get config from script attributes (must be called synchronously during script execution)
+  const scriptConfig = getConfigFromScript();
+
+  // Merge script attributes with window config (script attributes take precedence)
+  const windowConfig: SiteAgentInstallConfig = window.siteAgentConfig || {};
+  const config: SiteAgentInstallConfig = { ...windowConfig, ...scriptConfig };
+  
+  const version = config.version || "latest";
+  const cdn = config.cdn || "jsdelivr";
+  const autoInit = config.autoInit !== false; // Default to true
+
+  // Determine CDN base URL
+  const getCdnBase = () => {
+    if (config.cssUrl && config.jsUrl) {
+      return { cssUrl: config.cssUrl, jsUrl: config.jsUrl };
+    }
+    
+    const packageName = "@runtypelabs/persona";
+    const basePath = `/npm/${packageName}@${version}/dist`;
+    
+    if (cdn === "unpkg") {
+      return {
+        cssUrl: `https://unpkg.com${basePath}/widget.css`,
+        jsUrl: `https://unpkg.com${basePath}/index.global.js`
+      };
+    } else {
+      return {
+        cssUrl: `https://cdn.jsdelivr.net${basePath}/widget.css`,
+        jsUrl: `https://cdn.jsdelivr.net${basePath}/index.global.js`
+      };
+    }
+  };
+
+  const { cssUrl, jsUrl } = getCdnBase();
+
+  // Check if CSS is already loaded
+  const isCssLoaded = () => {
+    return !!document.head.querySelector('link[data-persona]') ||
+           !!document.head.querySelector(`link[href*="widget.css"]`);
+  };
+
+  // Check if JS is already loaded
+  const isJsLoaded = () => {
+    return !!(window as any).AgentWidget;
+  };
+
+  /**
+   * Wait for framework hydration to complete (Next.js, Nuxt, etc.)
+   * This prevents the framework from removing dynamically added CSS during reconciliation.
+   * Uses requestIdleCallback + double requestAnimationFrame for reliable detection.
+   */
+  const waitForHydration = (callback: () => void): void => {
+    let executed = false;
+    
+    const execute = () => {
+      if (executed) return;
+      executed = true;
+      callback();
+    };
+
+    const afterDom = () => {
+      // Strategy 1: Use requestIdleCallback if available (best for detecting idle after hydration)
+      if (typeof requestIdleCallback !== 'undefined') {
+        requestIdleCallback(() => {
+          // Double requestAnimationFrame ensures at least one full paint cycle completed
+          requestAnimationFrame(() => {
+            requestAnimationFrame(execute);
+          });
+        }, { timeout: 3000 }); // Max wait 3 seconds, then proceed anyway
+      } else {
+        // Strategy 2: Fallback for Safari (no requestIdleCallback)
+        // 300ms is typically enough for hydration on most pages
+        setTimeout(execute, 300);
+      }
+    };
+
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', afterDom);
+    } else {
+      // DOM already ready, but still wait for potential hydration
+      afterDom();
+    }
+  };
+
+  // Load CSS
+  const loadCSS = (): Promise<void> => {
+    return new Promise((resolve, reject) => {
+      if (isCssLoaded()) {
+        resolve();
+        return;
+      }
+
+      const link = document.createElement("link");
+      link.rel = "stylesheet";
+      link.href = cssUrl;
+      link.setAttribute("data-persona", "true");
+      
+      link.onload = () => resolve();
+      link.onerror = () => reject(new Error(`Failed to load CSS from ${cssUrl}`));
+      document.head.appendChild(link);
+    });
+  };
+
+  // Load JS
+  const loadJS = (): Promise<void> => {
+    return new Promise((resolve, reject) => {
+      if (isJsLoaded()) {
+        resolve();
+        return;
+      }
+
+      const script = document.createElement("script");
+      script.src = jsUrl;
+      script.async = true;
+      script.onload = () => resolve();
+      script.onerror = () => reject(new Error(`Failed to load JS from ${jsUrl}`));
+      document.head.appendChild(script);
+    });
+  };
+
+  // Initialize widget
+  const initWidget = () => {
+    if (!window.AgentWidget || !window.AgentWidget.initAgentWidget) {
+      console.warn("AgentWidget not available. Make sure the script loaded successfully.");
+      return;
+    }
+
+    const target = config.target || "body";
+    // Merge top-level config options into widget config
+    const widgetConfig = { ...config.config };
+    
+    // Merge apiUrl from top-level config into widget config if present
+    if (config.apiUrl && !widgetConfig.apiUrl) {
+      widgetConfig.apiUrl = config.apiUrl;
+    }
+    
+    // Merge clientToken from top-level config into widget config if present
+    if (config.clientToken && !widgetConfig.clientToken) {
+      widgetConfig.clientToken = config.clientToken;
+    }
+    
+    // Merge flowId from top-level config into widget config if present
+    if (config.flowId && !widgetConfig.flowId) {
+      widgetConfig.flowId = config.flowId;
+    }
+
+    // Only initialize if we have either apiUrl OR clientToken (or other config)
+    const hasApiConfig = widgetConfig.apiUrl || widgetConfig.clientToken;
+    if (!hasApiConfig && Object.keys(widgetConfig).length === 0) {
+      return;
+    }
+
+    // Auto-apply markdown postprocessor if not explicitly set and available
+    if (!widgetConfig.postprocessMessage && window.AgentWidget.markdownPostprocessor) {
+      widgetConfig.postprocessMessage = ({ text }: { text: string }) => 
+        window.AgentWidget.markdownPostprocessor(text);
+    }
+
+    try {
+      window.AgentWidget.initAgentWidget({
+        target,
+        config: widgetConfig,
+        // Explicitly disable shadow DOM for better CSS compatibility with host page
+        useShadowDom: config.useShadowDom ?? false
+      });
+    } catch (error) {
+      console.error("Failed to initialize AgentWidget:", error);
+    }
+  };
+
+  // Main installation flow (called after hydration completes)
+  const install = async () => {
+    try {
+      await loadCSS();
+      await loadJS();
+      
+      // Auto-init if we have config OR apiUrl OR clientToken
+      const shouldAutoInit = autoInit && (
+        config.config || 
+        config.apiUrl || 
+        config.clientToken
+      );
+      
+      if (shouldAutoInit) {
+        // Wait a tick to ensure AgentWidget is fully initialized
+        setTimeout(initWidget, 0);
+      }
+    } catch (error) {
+      console.error("Failed to install AgentWidget:", error);
+    }
+  };
+
+  // Start installation after hydration completes
+  // This prevents Next.js/Nuxt/etc. from removing dynamically added CSS
+  waitForHydration(install);
+})();
+

package/src/plugins/registry.ts

@@ -0,0 +1,77 @@
+import { AgentWidgetPlugin } from "./types";
+
+class PluginRegistry {
+  private plugins: Map<string, AgentWidgetPlugin> = new Map();
+
+  /**
+   * Register a plugin
+   */
+  register(plugin: AgentWidgetPlugin): void {
+    if (this.plugins.has(plugin.id)) {
+      console.warn(`Plugin "${plugin.id}" is already registered. Overwriting.`);
+    }
+
+    this.plugins.set(plugin.id, plugin);
+    plugin.onRegister?.();
+  }
+
+  /**
+   * Unregister a plugin
+   */
+  unregister(pluginId: string): void {
+    const plugin = this.plugins.get(pluginId);
+    if (plugin) {
+      plugin.onUnregister?.();
+      this.plugins.delete(pluginId);
+    }
+  }
+
+  /**
+   * Get all plugins sorted by priority
+   */
+  getAll(): AgentWidgetPlugin[] {
+    return Array.from(this.plugins.values()).sort(
+      (a, b) => (b.priority ?? 0) - (a.priority ?? 0)
+    );
+  }
+
+  /**
+   * Get plugins for a specific instance (from config)
+   * Merges instance plugins with globally registered plugins
+   */
+  getForInstance(instancePlugins?: AgentWidgetPlugin[]): AgentWidgetPlugin[] {
+    const allPlugins = this.getAll();
+
+    if (!instancePlugins || instancePlugins.length === 0) {
+      return allPlugins;
+    }
+
+    // Merge instance plugins with global plugins
+    // Instance plugins override global plugins with the same ID
+    const instanceIds = new Set(instancePlugins.map(p => p.id));
+    const merged = [
+      ...allPlugins.filter(p => !instanceIds.has(p.id)),
+      ...instancePlugins
+    ];
+
+    return merged.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+  }
+
+  /**
+   * Clear all plugins
+   */
+  clear(): void {
+    this.plugins.forEach(plugin => plugin.onUnregister?.());
+    this.plugins.clear();
+  }
+}
+
+export const pluginRegistry = new PluginRegistry();
+
+
+
+
+
+
+
+

package/src/plugins/types.ts

@@ -0,0 +1,95 @@
+import { AgentWidgetMessage, AgentWidgetConfig } from "../types";
+
+/**
+ * Plugin interface for customizing widget components
+ */
+export interface AgentWidgetPlugin {
+  /**
+   * Unique identifier for the plugin
+   */
+  id: string;
+
+  /**
+   * Optional priority (higher = runs first). Default: 0
+   */
+  priority?: number;
+
+  /**
+   * Custom renderer for message bubbles
+   * Return null to use default renderer
+   */
+  renderMessage?: (context: {
+    message: AgentWidgetMessage;
+    defaultRenderer: () => HTMLElement;
+    config: AgentWidgetConfig;
+  }) => HTMLElement | null;
+
+  /**
+   * Custom renderer for launcher button
+   * Return null to use default renderer
+   */
+  renderLauncher?: (context: {
+    config: AgentWidgetConfig;
+    defaultRenderer: () => HTMLElement;
+    onToggle: () => void;
+  }) => HTMLElement | null;
+
+  /**
+   * Custom renderer for panel header
+   * Return null to use default renderer
+   */
+  renderHeader?: (context: {
+    config: AgentWidgetConfig;
+    defaultRenderer: () => HTMLElement;
+    onClose?: () => void;
+  }) => HTMLElement | null;
+
+  /**
+   * Custom renderer for composer/input area
+   * Return null to use default renderer
+   */
+  renderComposer?: (context: {
+    config: AgentWidgetConfig;
+    defaultRenderer: () => HTMLElement;
+    onSubmit: (text: string) => void;
+    disabled: boolean;
+  }) => HTMLElement | null;
+
+  /**
+   * Custom renderer for reasoning bubbles
+   * Return null to use default renderer
+   */
+  renderReasoning?: (context: {
+    message: AgentWidgetMessage;
+    defaultRenderer: () => HTMLElement;
+    config: AgentWidgetConfig;
+  }) => HTMLElement | null;
+
+  /**
+   * Custom renderer for tool call bubbles
+   * Return null to use default renderer
+   */
+  renderToolCall?: (context: {
+    message: AgentWidgetMessage;
+    defaultRenderer: () => HTMLElement;
+    config: AgentWidgetConfig;
+  }) => HTMLElement | null;
+
+  /**
+   * Called when plugin is registered
+   */
+  onRegister?: () => void;
+
+  /**
+   * Called when plugin is unregistered
+   */
+  onUnregister?: () => void;
+}
+
+
+
+
+
+
+
+