vanilla-agent 1.20.0 → 1.21.0

package/dist/index.d.ts

@@ -287,6 +287,18 @@ type AgentWidgetLauncherConfig = {
     closeButtonTooltipText?: string;
     closeButtonShowTooltip?: boolean;
     clearChat?: AgentWidgetClearChatConfig;
+    /**
+     * Border style for the launcher button.
+     * @example "1px solid #e5e7eb" | "2px solid #3b82f6" | "none"
+     * @default "1px solid #e5e7eb"
+     */
+    border?: string;
+    /**
+     * Box shadow for the launcher button.
+     * @example "0 10px 15px -3px rgba(0,0,0,0.1)" | "none"
+     * @default "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)"
+     */
+    shadow?: string;
 };
 type AgentWidgetSendButtonConfig = {
     borderWidth?: string;
@@ -597,6 +609,271 @@ type AgentWidgetLayoutConfig = {
     /** Slot renderers for custom content injection */
     slots?: Partial<Record<WidgetLayoutSlot, SlotRenderer>>;
 };
+/**
+ * Token types for marked renderer methods
+ */
+type AgentWidgetMarkdownHeadingToken = {
+    type: "heading";
+    raw: string;
+    depth: 1 | 2 | 3 | 4 | 5 | 6;
+    text: string;
+    tokens: unknown[];
+};
+type AgentWidgetMarkdownCodeToken = {
+    type: "code";
+    raw: string;
+    text: string;
+    lang?: string;
+    escaped?: boolean;
+};
+type AgentWidgetMarkdownBlockquoteToken = {
+    type: "blockquote";
+    raw: string;
+    text: string;
+    tokens: unknown[];
+};
+type AgentWidgetMarkdownTableToken = {
+    type: "table";
+    raw: string;
+    header: Array<{
+        text: string;
+        tokens: unknown[];
+    }>;
+    rows: Array<Array<{
+        text: string;
+        tokens: unknown[];
+    }>>;
+    align: Array<"left" | "center" | "right" | null>;
+};
+type AgentWidgetMarkdownLinkToken = {
+    type: "link";
+    raw: string;
+    href: string;
+    title: string | null;
+    text: string;
+    tokens: unknown[];
+};
+type AgentWidgetMarkdownImageToken = {
+    type: "image";
+    raw: string;
+    href: string;
+    title: string | null;
+    text: string;
+};
+type AgentWidgetMarkdownListToken = {
+    type: "list";
+    raw: string;
+    ordered: boolean;
+    start: number | "";
+    loose: boolean;
+    items: unknown[];
+};
+type AgentWidgetMarkdownListItemToken = {
+    type: "list_item";
+    raw: string;
+    task: boolean;
+    checked?: boolean;
+    loose: boolean;
+    text: string;
+    tokens: unknown[];
+};
+type AgentWidgetMarkdownParagraphToken = {
+    type: "paragraph";
+    raw: string;
+    text: string;
+    tokens: unknown[];
+};
+type AgentWidgetMarkdownCodespanToken = {
+    type: "codespan";
+    raw: string;
+    text: string;
+};
+type AgentWidgetMarkdownStrongToken = {
+    type: "strong";
+    raw: string;
+    text: string;
+    tokens: unknown[];
+};
+type AgentWidgetMarkdownEmToken = {
+    type: "em";
+    raw: string;
+    text: string;
+    tokens: unknown[];
+};
+/**
+ * Custom renderer overrides for markdown elements.
+ * Each method receives the token and should return an HTML string.
+ * Return `false` to use the default renderer.
+ *
+ * @example
+ * ```typescript
+ * renderer: {
+ *   heading(token) {
+ *     return `<h${token.depth} class="custom-heading">${token.text}</h${token.depth}>`;
+ *   },
+ *   link(token) {
+ *     return `<a href="${token.href}" target="_blank" rel="noopener">${token.text}</a>`;
+ *   }
+ * }
+ * ```
+ */
+type AgentWidgetMarkdownRendererOverrides = {
+    /** Override heading rendering (h1-h6) */
+    heading?: (token: AgentWidgetMarkdownHeadingToken) => string | false;
+    /** Override code block rendering */
+    code?: (token: AgentWidgetMarkdownCodeToken) => string | false;
+    /** Override blockquote rendering */
+    blockquote?: (token: AgentWidgetMarkdownBlockquoteToken) => string | false;
+    /** Override table rendering */
+    table?: (token: AgentWidgetMarkdownTableToken) => string | false;
+    /** Override link rendering */
+    link?: (token: AgentWidgetMarkdownLinkToken) => string | false;
+    /** Override image rendering */
+    image?: (token: AgentWidgetMarkdownImageToken) => string | false;
+    /** Override list rendering (ul/ol) */
+    list?: (token: AgentWidgetMarkdownListToken) => string | false;
+    /** Override list item rendering */
+    listitem?: (token: AgentWidgetMarkdownListItemToken) => string | false;
+    /** Override paragraph rendering */
+    paragraph?: (token: AgentWidgetMarkdownParagraphToken) => string | false;
+    /** Override inline code rendering */
+    codespan?: (token: AgentWidgetMarkdownCodespanToken) => string | false;
+    /** Override strong/bold rendering */
+    strong?: (token: AgentWidgetMarkdownStrongToken) => string | false;
+    /** Override emphasis/italic rendering */
+    em?: (token: AgentWidgetMarkdownEmToken) => string | false;
+    /** Override horizontal rule rendering */
+    hr?: () => string | false;
+    /** Override line break rendering */
+    br?: () => string | false;
+    /** Override deleted/strikethrough rendering */
+    del?: (token: {
+        type: "del";
+        raw: string;
+        text: string;
+        tokens: unknown[];
+    }) => string | false;
+    /** Override checkbox rendering (in task lists) */
+    checkbox?: (token: {
+        checked: boolean;
+    }) => string | false;
+    /** Override HTML passthrough */
+    html?: (token: {
+        type: "html";
+        raw: string;
+        text: string;
+    }) => string | false;
+    /** Override text rendering */
+    text?: (token: {
+        type: "text";
+        raw: string;
+        text: string;
+    }) => string | false;
+};
+/**
+ * Markdown parsing options (subset of marked options)
+ */
+type AgentWidgetMarkdownOptions = {
+    /**
+     * Enable GitHub Flavored Markdown (tables, strikethrough, autolinks).
+     * @default true
+     */
+    gfm?: boolean;
+    /**
+     * Convert \n in paragraphs into <br>.
+     * @default true
+     */
+    breaks?: boolean;
+    /**
+     * Conform to original markdown.pl as much as possible.
+     * @default false
+     */
+    pedantic?: boolean;
+    /**
+     * Add id attributes to headings.
+     * @default false
+     */
+    headerIds?: boolean;
+    /**
+     * Prefix for heading id attributes.
+     * @default ""
+     */
+    headerPrefix?: string;
+    /**
+     * Mangle email addresses for spam protection.
+     * @default true
+     */
+    mangle?: boolean;
+    /**
+     * Silent mode - don't throw on parse errors.
+     * @default false
+     */
+    silent?: boolean;
+};
+/**
+ * Markdown configuration for customizing how markdown is rendered in chat messages.
+ * Provides three levels of control:
+ *
+ * 1. **CSS Variables** - Override styles via `--cw-md-*` CSS custom properties
+ * 2. **Parsing Options** - Configure marked behavior via `options`
+ * 3. **Custom Renderers** - Full control via `renderer` overrides
+ *
+ * @example
+ * ```typescript
+ * // Level 2: Configure parsing options
+ * config: {
+ *   markdown: {
+ *     options: {
+ *       gfm: true,
+ *       breaks: true,
+ *       headerIds: true
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Level 3: Custom renderers
+ * config: {
+ *   markdown: {
+ *     renderer: {
+ *       heading(token) {
+ *         return `<h${token.depth} class="custom-h${token.depth}">${token.text}</h${token.depth}>`;
+ *       },
+ *       link(token) {
+ *         return `<a href="${token.href}" target="_blank">${token.text}</a>`;
+ *       },
+ *       table(token) {
+ *         // Wrap tables in a scrollable container
+ *         return `<div class="table-scroll">${this.parser.parse(token.tokens)}</div>`;
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type AgentWidgetMarkdownConfig = {
+    /**
+     * Markdown parsing options.
+     * These are passed directly to the marked parser.
+     */
+    options?: AgentWidgetMarkdownOptions;
+    /**
+     * Custom renderer overrides for specific markdown elements.
+     * Each method receives a token object and should return an HTML string.
+     * Return `false` to fall back to the default renderer.
+     */
+    renderer?: AgentWidgetMarkdownRendererOverrides;
+    /**
+     * Disable default markdown CSS styles.
+     * When true, the widget won't apply any default styles to markdown elements,
+     * allowing you to provide your own CSS.
+     *
+     * @default false
+     */
+    disableDefaultStyles?: boolean;
+};
 type AgentWidgetConfig = {
     apiUrl?: string;
     flowId?: string;
@@ -806,6 +1083,31 @@ type AgentWidgetConfig = {
      * ```
      */
     layout?: AgentWidgetLayoutConfig;
+    /**
+     * Markdown rendering configuration.
+     * Customize how markdown is parsed and rendered in chat messages.
+     *
+     * Override methods:
+     * 1. **CSS Variables** - Override `--cw-md-*` variables in your stylesheet
+     * 2. **Options** - Configure marked parser behavior
+     * 3. **Renderers** - Custom rendering functions for specific elements
+     * 4. **postprocessMessage** - Complete control over message transformation
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   markdown: {
+     *     options: { breaks: true, gfm: true },
+     *     renderer: {
+     *       link(token) {
+     *         return `<a href="${token.href}" target="_blank">${token.text}</a>`;
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    markdown?: AgentWidgetMarkdownConfig;
 };
 type AgentWidgetMessageRole = "user" | "assistant" | "system";
 type AgentWidgetReasoning = {
@@ -1006,19 +1308,75 @@ declare const createActionManager: (options: ActionManagerOptions) => {
 };
 
 /**
- * Basic markdown renderer. Remember to sanitize the returned HTML if you render
- * untrusted content in your host page.
+ * Options for creating a markdown processor
+ */
+type MarkdownProcessorOptions = {
+    /** Marked parsing options */
+    markedOptions?: AgentWidgetMarkdownOptions;
+    /** Custom renderer overrides */
+    renderer?: AgentWidgetMarkdownRendererOverrides;
+};
+/**
+ * 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>`;
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const createMarkdownProcessor: (options?: MarkdownProcessorOptions) => (text: string) => 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
+ */
+declare const createMarkdownProcessorFromConfig: (config?: AgentWidgetMarkdownConfig) => (text: string) => string;
+/**
+ * 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()`.
  */
 declare const markdownPostprocessor: (text: string) => string;
 /**
  * Escapes HTML entities. Used as the default safe renderer.
  */
 declare const escapeHtml: (text: string) => string;
+/**
+ * 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
+ */
+declare const createDirectivePostprocessor: (markdownConfig?: AgentWidgetMarkdownConfig) => (text: string) => string;
 /**
  * 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.
+ * Markdown using default settings.
+ *
+ * For custom markdown configuration, use `createDirectivePostprocessor()`.
  */
 declare const directivePostprocessor: (text: string) => string;
 
@@ -1326,4 +1684,4 @@ declare const getHeaderLayout: (layoutName: string) => HeaderLayoutRenderer;
  */
 declare const buildHeaderWithLayout: (config: AgentWidgetConfig, layoutConfig?: AgentWidgetHeaderLayoutConfig, context?: Partial<HeaderLayoutContext>) => HeaderElements;
 
-export { type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetCustomFetch, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetMessage, type AgentWidgetMessageLayoutConfig, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, type AgentWidgetTimestampConfig, type CodeFormat, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComposerBuildContext, type ComposerElements, DEFAULT_WIDGET_CONFIG, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type MessageRenderContext, type MessageTransform, type SlotRenderContext, type SlotRenderer, type WidgetLayoutSlot, attachHeaderToContainer, buildComposer, buildDefaultHeader, buildExpandedHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, componentRegistry, createActionManager, createAgentExperience, createBubbleWithLayout, createComponentMiddleware, createComponentStreamParser, createFlexibleJsonStreamParser, createJsonStreamParser, createLocalStorageAdapter, createPlainTextParser, createRegexJsonParser, createStandardBubble, createTypingIndicator, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, generateCodeSnippet, getHeaderLayout, hasComponentDirective, headerLayouts, initAgentWidget, isComponentDirectiveType, markdownPostprocessor, mergeWithDefaults, pluginRegistry, renderComponentDirective };
+export { type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetCustomFetch, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageLayoutConfig, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, type AgentWidgetTimestampConfig, type CodeFormat, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComposerBuildContext, type ComposerElements, DEFAULT_WIDGET_CONFIG, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type MarkdownProcessorOptions, type MessageRenderContext, type MessageTransform, type SlotRenderContext, type SlotRenderer, type WidgetLayoutSlot, attachHeaderToContainer, buildComposer, buildDefaultHeader, buildExpandedHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, componentRegistry, createActionManager, createAgentExperience, createBubbleWithLayout, createComponentMiddleware, createComponentStreamParser, createDirectivePostprocessor, createFlexibleJsonStreamParser, createJsonStreamParser, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createPlainTextParser, createRegexJsonParser, createStandardBubble, createTypingIndicator, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, generateCodeSnippet, getHeaderLayout, hasComponentDirective, headerLayouts, initAgentWidget, isComponentDirectiveType, markdownPostprocessor, mergeWithDefaults, pluginRegistry, renderComponentDirective };