@runtypelabs/persona 1.36.0

package/src/postprocessors.ts

@@ -0,0 +1,194 @@
+import { Marked, type RendererObject } from "marked";
+import type { AgentWidgetMarkdownConfig, AgentWidgetMarkdownRendererOverrides, AgentWidgetMarkdownOptions } from "./types";
+
+/**
+ * Options for creating a markdown processor
+ */
+export type MarkdownProcessorOptions = {
+  /** Marked parsing options */
+  markedOptions?: AgentWidgetMarkdownOptions;
+  /** Custom renderer overrides */
+  renderer?: AgentWidgetMarkdownRendererOverrides;
+};
+
+/**
+ * Converts AgentWidgetMarkdownRendererOverrides to marked's RendererObject format
+ */
+const convertRendererOverrides = (
+  overrides?: AgentWidgetMarkdownRendererOverrides
+): Partial<RendererObject> | undefined => {
+  if (!overrides) return undefined;
+  
+  // The token-based API in marked v12+ matches our type definitions
+  // We can pass through the overrides directly
+  return overrides as Partial<RendererObject>;
+};
+
+/**
+ * Creates a configured markdown processor with custom options and renderers.
+ * 
+ * @param options - Configuration options for the markdown processor
+ * @returns A function that converts markdown text to HTML
+ * 
+ * @example
+ * ```typescript
+ * // Basic usage with defaults
+ * const processor = createMarkdownProcessor();
+ * const html = processor("# Hello World");
+ * 
+ * // With custom options
+ * const processor = createMarkdownProcessor({
+ *   markedOptions: { gfm: true, breaks: true },
+ *   renderer: {
+ *     link(token) {
+ *       return `<a href="${token.href}" target="_blank">${token.text}</a>`;
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export const createMarkdownProcessor = (options?: MarkdownProcessorOptions) => {
+  const opts = options?.markedOptions;
+  const markedInstance = new Marked({
+    gfm: opts?.gfm ?? true,
+    breaks: opts?.breaks ?? true,
+    pedantic: opts?.pedantic,
+    silent: opts?.silent,
+  });
+  
+  const rendererOverrides = convertRendererOverrides(options?.renderer);
+  if (rendererOverrides) {
+    markedInstance.use({ renderer: rendererOverrides });
+  }
+  
+  return (text: string): string => {
+    return markedInstance.parse(text) as string;
+  };
+};
+
+/**
+ * Creates a markdown processor from AgentWidgetMarkdownConfig.
+ * This is a convenience function that maps the widget config to processor options.
+ * 
+ * @param config - The markdown configuration from widget config
+ * @returns A function that converts markdown text to HTML
+ */
+export const createMarkdownProcessorFromConfig = (config?: AgentWidgetMarkdownConfig) => {
+  if (!config) {
+    return createMarkdownProcessor();
+  }
+  
+  return createMarkdownProcessor({
+    markedOptions: config.options,
+    renderer: config.renderer,
+  });
+};
+
+// Create default markdown processor instance
+const defaultMarkdownProcessor = createMarkdownProcessor();
+
+/**
+ * Basic markdown renderer using default settings.
+ * Remember to sanitize the returned HTML if you render untrusted content in your host page.
+ * 
+ * For custom configuration, use `createMarkdownProcessor()` or `createMarkdownProcessorFromConfig()`.
+ */
+export const markdownPostprocessor = (text: string): string => {
+  return defaultMarkdownProcessor(text);
+};
+
+/**
+ * Escapes HTML entities. Used as the default safe renderer.
+ */
+export const escapeHtml = (text: string): string =>
+  text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+
+const escapeAttribute = (value: string) =>
+  value.replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+const makeToken = (idx: number) => `%%FORM_PLACEHOLDER_${idx}%%`;
+
+const directiveReplacer = (source: string, placeholders: Array<{ token: string; type: string }>) => {
+  let working = source;
+
+  // JSON directive pattern e.g. <Directive>{"component":"form","type":"init"}</Directive>
+  working = working.replace(/<Directive>([\s\S]*?)<\/Directive>/gi, (match, jsonText) => {
+    try {
+      const parsed = JSON.parse(jsonText.trim());
+      if (parsed && typeof parsed === "object" && parsed.component === "form" && parsed.type) {
+        const token = makeToken(placeholders.length);
+        placeholders.push({ token, type: String(parsed.type) });
+        return token;
+      }
+    } catch (error) {
+      return match;
+    }
+    return match;
+  });
+
+  // XML-style directive e.g. <Form type="init" />
+  working = working.replace(/<Form\s+type="([^"]+)"\s*\/>/gi, (_, type) => {
+    const token = makeToken(placeholders.length);
+    placeholders.push({ token, type });
+    return token;
+  });
+
+  return working;
+};
+
+/**
+ * Creates a directive postprocessor with custom markdown configuration.
+ * Converts special directives (either `<Form type="init" />` or
+ * `<Directive>{"component":"form","type":"init"}</Directive>`) into placeholder
+ * elements that the widget upgrades after render. Remaining text is rendered as
+ * Markdown with the provided configuration.
+ * 
+ * @param markdownConfig - Optional markdown configuration
+ * @returns A function that processes text with directives and markdown
+ */
+export const createDirectivePostprocessor = (markdownConfig?: AgentWidgetMarkdownConfig) => {
+  const processor = createMarkdownProcessorFromConfig(markdownConfig);
+  
+  return (text: string): string => {
+    const placeholders: Array<{ token: string; type: string }> = [];
+    const withTokens = directiveReplacer(text, placeholders);
+    let html = processor(withTokens);
+
+    placeholders.forEach(({ token, type }) => {
+      const tokenRegex = new RegExp(token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
+      const safeType = escapeAttribute(type);
+      const replacement = `<div class="tvw-form-directive" data-tv-form="${safeType}"></div>`;
+      html = html.replace(tokenRegex, replacement);
+    });
+
+    return html;
+  };
+};
+
+/**
+ * Converts special directives (either `<Form type="init" />` or
+ * `<Directive>{"component":"form","type":"init"}</Directive>`) into placeholder
+ * elements that the widget upgrades after render. Remaining text is rendered as
+ * Markdown using default settings.
+ * 
+ * For custom markdown configuration, use `createDirectivePostprocessor()`.
+ */
+export const directivePostprocessor = (text: string): string => {
+  const placeholders: Array<{ token: string; type: string }> = [];
+  const withTokens = directiveReplacer(text, placeholders);
+  let html = markdownPostprocessor(withTokens);
+
+  placeholders.forEach(({ token, type }) => {
+    const tokenRegex = new RegExp(token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
+    const safeType = escapeAttribute(type);
+    const replacement = `<div class="tvw-form-directive" data-tv-form="${safeType}"></div>`;
+    html = html.replace(tokenRegex, replacement);
+  });
+
+  return html;
+};

package/src/runtime/init.ts

@@ -0,0 +1,162 @@
+import { createAgentExperience, AgentWidgetController } from "../ui";
+import { AgentWidgetConfig, AgentWidgetInitOptions, AgentWidgetEvent } from "../types";
+
+const ensureTarget = (target: string | HTMLElement): HTMLElement => {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    throw new Error("Chat widget can only be mounted in a browser environment");
+  }
+
+  if (typeof target === "string") {
+    const element = document.querySelector<HTMLElement>(target);
+    if (!element) {
+      throw new Error(`Chat widget target "${target}" was not found`);
+    }
+    return element;
+  }
+
+  return target;
+};
+
+const widgetCssHref = (): string | null => {
+  try {
+    // This works in ESM builds but not in IIFE builds
+    if (typeof import.meta !== "undefined" && import.meta.url) {
+      return new URL("../widget.css", import.meta.url).href;
+    }
+  } catch {
+    // Fallback for IIFE builds where CSS should be loaded separately
+  }
+  return null;
+};
+
+const mountStyles = (root: ShadowRoot | HTMLElement) => {
+  const href = widgetCssHref();
+
+  const adoptExistingStylesheet = () => {
+    if (!(root instanceof ShadowRoot)) {
+      return;
+    }
+
+    if (root.querySelector('link[data-persona]')) {
+      return;
+    }
+
+    const globalLink = document.head.querySelector<HTMLLinkElement>(
+      'link[data-persona]'
+    );
+    if (!globalLink) {
+      return;
+    }
+
+    const clonedLink = globalLink.cloneNode(true) as HTMLLinkElement;
+    root.insertBefore(clonedLink, root.firstChild);
+  };
+
+  if (root instanceof ShadowRoot) {
+    // For shadow DOM, we need to load CSS into the shadow root
+    if (href) {
+      const link = document.createElement("link");
+      link.rel = "stylesheet";
+      link.href = href;
+      link.setAttribute("data-persona", "true");
+      root.insertBefore(link, root.firstChild);
+    } else {
+      adoptExistingStylesheet();
+    }
+    // If href is null (IIFE build), CSS should already be loaded globally
+  } else {
+    // For non-shadow DOM, check if CSS is already loaded
+    const existing = document.head.querySelector<HTMLLinkElement>(
+      "link[data-persona]"
+    );
+    if (!existing) {
+      if (href) {
+        // ESM build - load CSS dynamically
+        const link = document.createElement("link");
+        link.rel = "stylesheet";
+        link.href = href;
+        link.setAttribute("data-persona", "true");
+        document.head.appendChild(link);
+      }
+      // IIFE build - CSS should be loaded via <link> tag before script
+      // If not found, we'll assume it's loaded globally or warn in dev
+    }
+  }
+};
+
+export type AgentWidgetInitHandle = AgentWidgetController & { host: HTMLElement };
+
+export const initAgentWidget = (
+  options: AgentWidgetInitOptions
+): AgentWidgetInitHandle => {
+  const target = ensureTarget(options.target);
+  const host = document.createElement("div");
+  host.className = "persona-host";
+  
+  // When launcher is disabled (inline embed mode), ensure the host fills its container
+  const launcherEnabled = options.config?.launcher?.enabled ?? true;
+  if (!launcherEnabled) {
+    host.style.height = "100%";
+  }
+  
+  target.appendChild(host);
+
+  const useShadow = options.useShadowDom === true;
+  let mount: HTMLElement;
+  let root: ShadowRoot | HTMLElement;
+
+  if (useShadow) {
+    const shadowRoot = host.attachShadow({ mode: "open" });
+    root = shadowRoot;
+    mount = document.createElement("div");
+    mount.id = "persona-root";
+    // When launcher is disabled, ensure mount fills the host
+    if (!launcherEnabled) {
+      mount.style.height = "100%";
+      mount.style.display = "flex";
+      mount.style.flexDirection = "column";
+      mount.style.flex = "1";
+      mount.style.minHeight = "0";
+    }
+    shadowRoot.appendChild(mount);
+    mountStyles(shadowRoot);
+  } else {
+    root = host;
+    mount = document.createElement("div");
+    mount.id = "persona-root";
+    // When launcher is disabled, ensure mount fills the host
+    if (!launcherEnabled) {
+      mount.style.height = "100%";
+      mount.style.display = "flex";
+      mount.style.flexDirection = "column";
+      mount.style.flex = "1";
+      mount.style.minHeight = "0";
+    }
+    host.appendChild(mount);
+    mountStyles(host);
+  }
+
+  let controller = createAgentExperience(mount, options.config, {
+    debugTools: options.debugTools
+  });
+  options.onReady?.();
+
+  const handle: AgentWidgetInitHandle = {
+    ...controller,
+    host,
+    destroy() {
+      controller.destroy();
+      host.remove();
+      if (options.windowKey && typeof window !== "undefined") {
+        delete (window as any)[options.windowKey];
+      }
+    }
+  };
+
+  // Store on window if windowKey is provided
+  if (options.windowKey && typeof window !== 'undefined') {
+    (window as any)[options.windowKey] = handle;
+  }
+
+  return handle;
+};