vanilla-agent 1.20.0 → 1.22.0

package/src/types.ts

@@ -93,6 +93,66 @@ export type AgentWidgetActionEventPayload = {
   message: AgentWidgetMessage;
 };
 
+/**
+ * Feedback event payload for upvote/downvote actions on messages
+ */
+export type AgentWidgetMessageFeedback = {
+  type: "upvote" | "downvote";
+  messageId: string;
+  message: AgentWidgetMessage;
+};
+
+/**
+ * Configuration for message action buttons (copy, upvote, downvote)
+ */
+export type AgentWidgetMessageActionsConfig = {
+  /**
+   * Enable/disable message actions entirely
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Show copy button
+   * @default true
+   */
+  showCopy?: boolean;
+  /**
+   * Show upvote button
+   * @default false (requires backend)
+   */
+  showUpvote?: boolean;
+  /**
+   * Show downvote button
+   * @default false (requires backend)
+   */
+  showDownvote?: boolean;
+  /**
+   * Visibility mode: 'always' shows buttons always, 'hover' shows on hover only
+   * @default 'hover'
+   */
+  visibility?: "always" | "hover";
+  /**
+   * Horizontal alignment of action buttons
+   * @default 'right'
+   */
+  align?: "left" | "center" | "right";
+  /**
+   * Layout style for action buttons
+   * - 'pill-inside': Compact floating pill around just the buttons (default for hover)
+   * - 'row-inside': Full-width row at the bottom of the message
+   * @default 'pill-inside'
+   */
+  layout?: "pill-inside" | "row-inside";
+  /**
+   * Callback when user submits feedback (upvote/downvote)
+   */
+  onFeedback?: (feedback: AgentWidgetMessageFeedback) => void;
+  /**
+   * Callback when user copies a message
+   */
+  onCopy?: (message: AgentWidgetMessage) => void;
+};
+
 export type AgentWidgetStateEvent = {
   open: boolean;
   source: "user" | "auto" | "api" | "system";
@@ -114,6 +174,8 @@ export type AgentWidgetControllerEventMap = {
   "widget:opened": AgentWidgetStateEvent;
   "widget:closed": AgentWidgetStateEvent;
   "widget:state": AgentWidgetStateSnapshot;
+  "message:feedback": AgentWidgetMessageFeedback;
+  "message:copy": AgentWidgetMessage;
 };
 
 export type AgentWidgetFeatureFlags = {
@@ -250,6 +312,18 @@ export 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;
 };
 
 export type AgentWidgetSendButtonConfig = {
@@ -442,6 +516,62 @@ export type AgentWidgetCustomFetch = (
  */
 export type AgentWidgetHeadersFunction = () => Record<string, string> | Promise<Record<string, string>>;
 
+// ============================================================================
+// Client Token Types
+// ============================================================================
+
+/**
+ * Session information returned after client token initialization.
+ * Contains session ID, expiry time, flow info, and config from the server.
+ */
+export type ClientSession = {
+  /** Unique session identifier */
+  sessionId: string;
+  /** When the session expires */
+  expiresAt: Date;
+  /** Flow information */
+  flow: {
+    id: string;
+    name: string;
+    description: string | null;
+  };
+  /** Configuration from the server */
+  config: {
+    welcomeMessage: string | null;
+    placeholder: string;
+    theme: Record<string, unknown> | null;
+  };
+};
+
+/**
+ * Raw API response from /v1/client/init endpoint
+ */
+export type ClientInitResponse = {
+  session_id: string;
+  expires_at: string;
+  flow: {
+    id: string;
+    name: string;
+    description: string | null;
+  };
+  config: {
+    welcome_message: string | null;
+    placeholder: string;
+    theme: Record<string, unknown> | null;
+  };
+};
+
+/**
+ * Request payload for /v1/client/chat endpoint
+ */
+export type ClientChatRequest = {
+  session_id: string;
+  messages: Array<{
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+  }>;
+};
+
 // ============================================================================
 // Layout Configuration Types
 // ============================================================================
@@ -610,9 +740,315 @@ export type AgentWidgetLayoutConfig = {
   slots?: Partial<Record<WidgetLayoutSlot, SlotRenderer>>;
 };
 
+// ============================================================================
+// Markdown Configuration Types
+// ============================================================================
+
+/**
+ * Token types for marked renderer methods
+ */
+export type AgentWidgetMarkdownHeadingToken = {
+  type: "heading";
+  raw: string;
+  depth: 1 | 2 | 3 | 4 | 5 | 6;
+  text: string;
+  tokens: unknown[];
+};
+
+export type AgentWidgetMarkdownCodeToken = {
+  type: "code";
+  raw: string;
+  text: string;
+  lang?: string;
+  escaped?: boolean;
+};
+
+export type AgentWidgetMarkdownBlockquoteToken = {
+  type: "blockquote";
+  raw: string;
+  text: string;
+  tokens: unknown[];
+};
+
+export 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>;
+};
+
+export type AgentWidgetMarkdownLinkToken = {
+  type: "link";
+  raw: string;
+  href: string;
+  title: string | null;
+  text: string;
+  tokens: unknown[];
+};
+
+export type AgentWidgetMarkdownImageToken = {
+  type: "image";
+  raw: string;
+  href: string;
+  title: string | null;
+  text: string;
+};
+
+export type AgentWidgetMarkdownListToken = {
+  type: "list";
+  raw: string;
+  ordered: boolean;
+  start: number | "";
+  loose: boolean;
+  items: unknown[];
+};
+
+export type AgentWidgetMarkdownListItemToken = {
+  type: "list_item";
+  raw: string;
+  task: boolean;
+  checked?: boolean;
+  loose: boolean;
+  text: string;
+  tokens: unknown[];
+};
+
+export type AgentWidgetMarkdownParagraphToken = {
+  type: "paragraph";
+  raw: string;
+  text: string;
+  tokens: unknown[];
+};
+
+export type AgentWidgetMarkdownCodespanToken = {
+  type: "codespan";
+  raw: string;
+  text: string;
+};
+
+export type AgentWidgetMarkdownStrongToken = {
+  type: "strong";
+  raw: string;
+  text: string;
+  tokens: unknown[];
+};
+
+export 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>`;
+ *   }
+ * }
+ * ```
+ */
+export 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)
+ */
+export 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>`;
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export 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;
+};
+
 export type AgentWidgetConfig = {
   apiUrl?: string;
   flowId?: string;
+  /**
+   * Client token for direct browser-to-API communication.
+   * When set, the widget uses /v1/client/* endpoints instead of /v1/dispatch.
+   * Mutually exclusive with apiKey/headers authentication.
+   * 
+   * @example
+   * ```typescript
+   * config: {
+   *   clientToken: 'ct_live_flow01k7_a8b9c0d1e2f3g4h5i6j7k8l9'
+   * }
+   * ```
+   */
+  clientToken?: string;
+  /**
+   * Callback when session is initialized (client token mode only).
+   * Receives session info including expiry time.
+   * 
+   * @example
+   * ```typescript
+   * config: {
+   *   onSessionInit: (session) => {
+   *     console.log('Session started:', session.sessionId);
+   *   }
+   * }
+   * ```
+   */
+  onSessionInit?: (session: ClientSession) => void;
+  /**
+   * Callback when session expires or errors (client token mode only).
+   * Widget should prompt user to refresh.
+   * 
+   * @example
+   * ```typescript
+   * config: {
+   *   onSessionExpired: () => {
+   *     alert('Your session has expired. Please refresh the page.');
+   *   }
+   * }
+   * ```
+   */
+  onSessionExpired?: () => void;
   /**
    * Static headers to include with each request.
    * For dynamic headers (e.g., auth tokens), use `getHeaders` instead.
@@ -819,6 +1255,57 @@ export 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;
+  
+  /**
+   * Configuration for message action buttons (copy, upvote, downvote).
+   * Shows action buttons on assistant messages for user feedback.
+   * 
+   * @example
+   * ```typescript
+   * config: {
+   *   messageActions: {
+   *     enabled: true,
+   *     showCopy: true,
+   *     showUpvote: true,
+   *     showDownvote: true,
+   *     visibility: 'hover',
+   *     onFeedback: (feedback) => {
+   *       console.log('Feedback:', feedback.type, feedback.messageId);
+   *     },
+   *     onCopy: (message) => {
+   *       console.log('Copied message:', message.id);
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  messageActions?: AgentWidgetMessageActionsConfig;
 };
 
 export type AgentWidgetMessageRole = "user" | "assistant" | "system";

package/src/ui.ts

@@ -1,4 +1,4 @@
-import { escapeHtml } from "./postprocessors";
+import { escapeHtml, createMarkdownProcessorFromConfig } from "./postprocessors";
 import { AgentWidgetSession, AgentWidgetSessionStatus } from "./session";
 import {
   AgentWidgetConfig,
@@ -11,7 +11,8 @@ import {
   AgentWidgetStateEvent,
   AgentWidgetStateSnapshot,
   WidgetLayoutSlot,
-  SlotRenderer
+  SlotRenderer,
+  AgentWidgetMessageFeedback
 } from "./types";
 import { applyThemeVariables } from "./utils/theme";
 import { renderLucideIcon } from "./utils/icons";
@@ -21,7 +22,7 @@ import { createLauncherButton } from "./components/launcher";
 import { createWrapper, buildPanel, buildHeader, buildComposer, attachHeaderToContainer } from "./components/panel";
 import { positionMap } from "./utils/positioning";
 import type { HeaderElements, ComposerElements } from "./components/panel";
-import { MessageTransform } from "./components/message-bubble";
+import { MessageTransform, MessageActionCallbacks } from "./components/message-bubble";
 import { createStandardBubble, createTypingIndicator } from "./components/message-bubble";
 import { createReasoningBubble } from "./components/reasoning-bubble";
 import { createToolBubble } from "./components/tool-bubble";
@@ -96,6 +97,12 @@ const buildPostprocessor = (
   cfg: AgentWidgetConfig | undefined,
   actionManager?: ReturnType<typeof createActionManager>
 ): MessageTransform => {
+  // Create markdown processor from config if markdown config is provided
+  // This allows users to enable markdown rendering via config.markdown
+  const markdownProcessor = cfg?.markdown 
+    ? createMarkdownProcessorFromConfig(cfg.markdown)
+    : null;
+
   return (context) => {
     let nextText = context.text ?? "";
     const rawPayload = context.message.rawContent ?? null;
@@ -116,6 +123,7 @@ const buildPostprocessor = (
       }
     }
 
+    // Priority: postprocessMessage > markdown config > escapeHtml
     if (cfg?.postprocessMessage) {
       return cfg.postprocessMessage({
         ...context,
@@ -124,6 +132,11 @@ const buildPostprocessor = (
       });
     }
 
+    // Use markdown processor if markdown config is provided
+    if (markdownProcessor) {
+      return markdownProcessor(nextText);
+    }
+
     return escapeHtml(nextText);
   };
 };
@@ -216,6 +229,16 @@ export const createAgentExperience = (
   let showReasoning = config.features?.showReasoning ?? true;
   let showToolCalls = config.features?.showToolCalls ?? true;
   
+  // Create message action callbacks that emit events
+  const messageActionCallbacks: MessageActionCallbacks = {
+    onCopy: (message: AgentWidgetMessage) => {
+      eventBus.emit("message:copy", message);
+    },
+    onFeedback: (feedback: AgentWidgetMessageFeedback) => {
+      eventBus.emit("message:feedback", feedback);
+    }
+  };
+  
   // Get status indicator config
   const statusConfig = config.statusIndicator ?? {};
   const getStatusText = (status: AgentWidgetSessionStatus): string => {
@@ -865,7 +888,13 @@ export const createAgentExperience = (
           bubble = matchingPlugin.renderMessage({
             message,
             defaultRenderer: () => {
-              const b = createStandardBubble(message, transform, messageLayoutConfig);
+              const b = createStandardBubble(
+                message, 
+                transform, 
+                messageLayoutConfig, 
+                config.messageActions, 
+                messageActionCallbacks
+              );
               if (message.role !== "user") {
                 enhanceWithForms(b, message, config, session);
               }
@@ -945,7 +974,13 @@ export const createAgentExperience = (
               streaming: Boolean(message.streaming)
             });
           } else {
-            bubble = createStandardBubble(message, transform, messageLayoutConfig);
+            bubble = createStandardBubble(
+              message, 
+              transform, 
+              messageLayoutConfig, 
+              config.messageActions, 
+              messageActionCallbacks
+            );
           }
           if (message.role !== "user" && bubble) {
             enhanceWithForms(bubble, message, config, session);