claudius-chat-widget 1.11.0 → 1.13.0

package/dist/index.d.cts

@@ -106,571 +106,663 @@ export declare class ChatApiClient {
          * @throws {@link ChatApiError} when the request fails after all retries.
              */
          sendMessage(messages: ChatMessage[]): Promise<ChatResponse>;
-         private fetchWithTimeout;
-         private isRetryable;
-         private getRetryDelay;
-         private delay;
-     }
-
-     /**
-      * Options for {@link ChatApiClient}.
-      */
-     export declare interface ChatApiClientOptions {
          /**
-          * Maximum retries after the first attempt, for retryable failures (HTTP
-          * 429/503, network errors, timeouts).
-          * @defaultValue `2`
-          */
-         maxRetries?: number;
-         /**
-          * Minimum gap between sends, in milliseconds. A send inside this window
-          * rejects with {@link DebounceError}. Set to 0 to disable.
-          * @defaultValue `300`
-          */
-         debounceMs?: number;
-         /**
-          * Per-attempt request timeout in milliseconds. Aborts the in-flight fetch
-          * via `AbortController` and surfaces a retryable {@link ChatApiError} with
-          * code `"TIMEOUT"`. Set to 0 to disable.
-          * @defaultValue `30000`
-          */
-         timeoutMs?: number;
-     }
-
-     /**
-      * Error thrown by {@link ChatApiClient} when a chat request ultimately fails:
-      * either after exhausting retries, or immediately for a non-retryable status.
-      */
-     export declare class ChatApiError extends Error {
-         /** HTTP status code, or `0` for network and timeout failures. */
-         readonly status: number;
-         /** Machine-readable error code, when available (e.g. `"TIMEOUT"`). */
-         readonly code?: string | undefined;
-         /** Seconds to wait before retrying, parsed from the `Retry-After` header. */
-         readonly retryAfter?: number | undefined;
-         /**
-          * Create a {@link ChatApiError}.
+          * Send the conversation to the streaming chat endpoint and resolve with the
+          * assistant's full reply once the stream completes. Text deltas are
+          * delivered through {@link ChatStreamOptions.onChunk} as they arrive.
           *
-          * @param message - Human-readable error message.
-          * @param status - HTTP status code, or `0` for network and timeout failures.
-          * @param code - Optional machine-readable error code (e.g. `"TIMEOUT"`, `"NETWORK_ERROR"`).
-          * @param retryAfter - Seconds to wait before retrying, from the `Retry-After` header.
-          */
-         constructor(message: string, 
-         /** HTTP status code, or `0` for network and timeout failures. */
-         status: number, 
-         /** Machine-readable error code, when available (e.g. `"TIMEOUT"`). */
-         code?: string | undefined, 
-         /** Seconds to wait before retrying, parsed from the `Retry-After` header. */
-         retryAfter?: number | undefined);
-     }
-
-     /**
-      * Error response body returned by the Worker when a chat request fails.
-      */
-     export declare interface ChatErrorResponse {
-         /** Human-readable error message. */
-         error: string;
-         /** Optional machine-readable error code (e.g. `"RATE_LIMITED"`). */
-         code?: string;
-     }
-
-     /**
-      * A single chat message exchanged between the user and the assistant.
-      */
-     export declare interface ChatMessage {
-         /** Stable unique identifier, used as the React list key. */
-         id: string;
-         /** Who authored the message. */
-         role: "user" | "assistant";
-         /** Plain-text message body. */
-         content: string;
-         /** Sources cited by the assistant for this message, when any. */
-         sources?: Source[];
-     }
-
-     /**
-      * Request payload sent to the Worker `POST /api/chat` endpoint.
-      */
-     export declare interface ChatRequest {
-         /** The full conversation so far, oldest message first. */
-         messages: ChatMessage[];
-     }
-
-     /**
-      * Successful response body from `POST /api/chat`.
-      */
-     export declare interface ChatResponse {
-         /** The assistant's reply text. */
-         reply: string;
-         /** Sources the assistant cited, when any. */
-         sources?: Source[];
-     }
-
-     /**
-      * Root Claudius chat widget: a floating toggle button that opens a chat window
-      * backed by the Worker chat API. Render a single instance on the page.
-      *
-      * @param props - See {@link ChatWidgetProps}.
-      * @example
-      * ```tsx
-      * <ChatWidget apiUrl="https://api.example.com" title="Support" />
-      * ```
-      */
-     export declare function ChatWidget({ apiUrl, title, subtitle, welcomeMessage, placeholder, persistMessages, storageKeyPrefix, requestTimeoutMs, theme, accentColor, position, locale, translations: translationOverrides, triggers, plugins, }: ChatWidgetProps): JSX_2.Element;
-
-     /**
-      * Props for the {@link ChatWidget} component.
-      */
-     export declare interface ChatWidgetProps {
-         /** Absolute URL of the Worker chat endpoint (e.g. `https://api.example.com`). */
-         apiUrl: string;
-         /** Header title. Falls back to the active locale's default title. */
-         title?: string;
-         /** Header subtitle shown beneath the title. */
-         subtitle?: string;
-         /** First assistant message shown when the chat opens. */
-         welcomeMessage?: string;
-         /** Placeholder text for the message input. */
-         placeholder?: string;
-         /**
-          * Persist the conversation to storage so it survives reloads.
-          * @defaultValue `false`
-          */
-         persistMessages?: boolean;
-         /** Prefix for the storage key used when {@link ChatWidgetProps.persistMessages} is enabled. */
-         storageKeyPrefix?: string;
-         /** Abort a chat request after this many milliseconds. */
-         requestTimeoutMs?: number;
-         /**
-          * Color-scheme mode ("light" | "dark" | "auto"), a built-in theme name
-          * ("default" | "minimal" | "playful" | "corporate"), an inline
-          * ClaudiusTheme object, or a URL to a theme JSON file.
-          * @defaultValue `"light"`
-          */
-         theme?: ClaudiusThemeInput;
-         /** Accent color override; wins over the theme's accent in both light and dark. */
-         accentColor?: string;
-         /**
-          * Corner of the viewport the widget docks to.
-          * @defaultValue `"bottom-right"`
-          */
-         position?: WidgetPosition;
-         /** BCP-47 locale used to select built-in translations. */
-         locale?: LocaleCode;
-         /** Partial overrides merged over the resolved locale translations. */
-         translations?: Partial<ClaudiusTranslations>;
-         /** Proactive open/greeting rules evaluated against the current page. */
-         triggers?: Trigger[];
-         /**
-          * Middleware run around each message: `onBeforeSend`, `onAfterReceive`, and
-          * `onError`. Hooks run in array order and may modify, replace, or
-          * short-circuit messages. See {@link ClaudiusPlugin}.
-          */
-         plugins?: ClaudiusPlugin[];
-     }
-
-     /** An analytics event emitted by {@link pluginAnalytics}. */
-     export declare type ClaudiusAnalyticsEvent = {
-         /** Event discriminant. */
-         type: "message_sent";
-         /** Always `"user"`. */
-         role: "user";
-         /** Message text, or `""` when `includeContent` is `false`. */
-         content: string;
-         /** Length of the message in characters. */
-         chars: number;
-     } | {
-         /** Event discriminant. */
-         type: "message_received";
-         /** Always `"assistant"`. */
-         role: "assistant";
-         /** Reply text, or `""` when `includeContent` is `false`. */
-         content: string;
-         /** Length of the reply in characters. */
-         chars: number;
-     } | {
-         /** Event discriminant. */
-         type: "chat_error";
-         /** The error message. */
-         message: string;
-         /** Machine-readable error code, when available (e.g. `"TIMEOUT"`). */
-         code?: string;
-     };
-
-     /**
-      * A client-side middleware that runs around the chat message lifecycle. Pass
-      * an array of plugins to {@link ChatWidget} via the `plugins` prop; hooks run
-      * in array order.
-      *
-      * Hooks may be async, and may modify, replace, or short-circuit messages. A
-      * hook that throws is caught and logged — a misbehaving plugin will not break
-      * the chat — so security-sensitive transforms (e.g. PII redaction) should be
-      * written defensively.
-      *
-      * @example
-      * ```ts
-      * const logger: ClaudiusPlugin = {
-      *   name: "logger",
-      *   onBeforeSend: (message) => { console.log("sending", message.content); },
-      *   onAfterReceive: (message) => { console.log("received", message.content); },
-      * };
-      * ```
-      */
-     export declare interface ClaudiusPlugin {
-         /** Stable identifier, used in log messages. */
-         name: string;
-         /**
-          * Runs before the user message is sent. Return a {@link ChatMessage} to
-          * replace it (the returned message is both displayed and sent), return
-          * nothing to leave it unchanged, or call {@link BeforeSendContext.respondWith}
-          * / {@link BeforeSendContext.abort} to short-circuit.
-          */
-         onBeforeSend?(message: ChatMessage, ctx: BeforeSendContext): MaybePromise<ChatMessage | void>;
-         /**
-          * Runs after the assistant reply is received, before it is rendered. Return
-          * a {@link ChatMessage} to replace it, or nothing to leave it unchanged.
-          */
-         onAfterReceive?(message: ChatMessage, ctx: PluginContext): MaybePromise<ChatMessage | void>;
-         /**
-          * Runs when a send fails. Observe the error, or call
-          * {@link ErrorContext.respondWith} to render a fallback reply instead of the
-          * error UI.
-          */
-         onError?(error: Error, ctx: ErrorContext): MaybePromise<void>;
-     }
-
-     /**
-      * A Claudius design-token theme. Every value is a CSS string applied via
-      * --cl-* custom properties. `colors` apply to both light and dark modes
-      * unless `colorsDark` overrides a token for dark mode specifically.
-      *
-      * JSON theme files validate against
-      * https://claudius-docs.pages.dev/schema/theme.v1.json
-      */
-     export declare interface ClaudiusTheme {
-         /** Optional JSON Schema URL, for editor validation and autocomplete. */
-         $schema?: string;
-         /** Human-readable theme name. */
-         name?: string;
-         /** Initial color scheme this theme is designed for. Defaults to "light". */
-         colorScheme?: "light" | "dark" | "auto";
-         /** Color token overrides applied in both light and dark mode. */
-         colors?: Partial<Record<ThemeColorToken, string>>;
-         /** Color token overrides applied only in dark mode, layered over {@link ClaudiusTheme.colors}. */
-         colorsDark?: Partial<Record<ThemeColorToken, string>>;
-         /** Border-radius token overrides. */
-         radii?: Partial<Record<ThemeRadiusToken, string>>;
-         /** Box-shadow token overrides. */
-         shadows?: Partial<Record<ThemeShadowToken, string>>;
-         /** Font-family token overrides. */
-         fonts?: Partial<Record<ThemeFontToken, string>>;
-     }
-
-     /**
-      * Everything the `theme` option accepts: the original color-scheme modes, a
-      * built-in theme name, an inline theme object, or a URL to a theme JSON file.
-      * `(string & {})` keeps literal autocomplete while allowing URLs.
-      */
-     export declare type ClaudiusThemeInput = "light" | "dark" | "auto" | BuiltinThemeName | ClaudiusTheme | (string & {});
-
-     /**
-      * Every user-facing string the widget renders. Pass a {@link ClaudiusTranslations}
-      * (or a partial override) to localize the UI. English is the source of truth;
-      * see {@link defaultTranslations}.
-      */
-     export declare interface ClaudiusTranslations {
-         /** Chat window header title. */
-         title: string;
-         /** Chat window header subtitle. */
-         subtitle: string;
-         /** First assistant message shown when the chat opens. */
-         welcomeMessage: string;
-         /** Accessible label for the close button. */
-         closeChat: string;
-         /** Accessible label for the message list region. */
-         chatMessages: string;
-         /** Accessible label for the typing indicator. */
-         typingIndicator: string;
-         /** Placeholder text for the message input. */
-         placeholder: string;
-         /** Accessible label for the send button. */
-         sendMessage: string;
-         /** Accessible label for the message input field. */
-         typeYourMessage: string;
-         /** Accessible label for the button that opens the chat. */
-         openChat: string;
-         /** Accessible label for dismissing the greeting bubble. */
-         dismissGreeting: string;
-         /** Generic fallback error message. */
-         errorGeneric: string;
-         /** Error shown when the network request fails. */
-         errorConnection: string;
-         /** Error shown when a request times out. */
-         errorTimeout: string;
-         /** Error shown when rate-limited (per-minute limit). */
-         errorRateLimitMinute: string;
-         /** Error shown when rate-limited (per-hour limit). */
-         errorRateLimitHour: string;
-         /** Label for the retry action on a failed message. */
-         errorRetry: string;
-     }
-
-     /**
-      * Build a complete {@link ClaudiusTranslations} from the English defaults,
-      * applying the given overrides.
-      *
-      * @param overrides - Strings to override on top of {@link defaultTranslations}.
-      * @returns A complete translations object.
-      */
-     export declare function createTranslations(overrides?: Partial<ClaudiusTranslations>): ClaudiusTranslations;
-
-     /**
-      * Error thrown by {@link ChatApiClient.sendMessage} when a send is rejected
-      * for arriving within the configured debounce window.
-      */
-     export declare class DebounceError extends Error {
-         /** Creates a `DebounceError` with a fixed message. */
-         constructor();
-     }
-
-     /**
-      * Default PII patterns: email addresses, North-American-style phone numbers,
-      * US Social Security numbers, and 13–16 digit card-like sequences. These are
-      * intentionally conservative starting points — tune {@link RedactPiiOptions.patterns}
-      * for your data.
-      */
-     export declare const DEFAULT_PII_PATTERNS: readonly RegExp[];
-
-     /** The default (English) translations, used when no locale or override applies. */
-     export declare const defaultTranslations: ClaudiusTranslations;
-
-     /**
-      * Detect the best {@link LocaleCode} for the current environment: the document
-      * `lang` attribute first, then the browser language, falling back to `"en"`.
-      *
-      * @returns The detected locale code.
-      */
-     export declare function detectLocale(): LocaleCode;
-
-     /**
-      * Context for {@link ClaudiusPlugin.onError}. Adds the ability to recover from
-      * a failed send by rendering a reply in place of the error UI.
-      */
-     export declare interface ErrorContext extends PluginContext {
-         /**
-          * Recover from the failure by rendering this assistant reply instead of the
-          * error state. Stops the hook chain — later plugins' `onError` hooks do not
-          * run.
-          */
-         respondWith(reply: string | PluginReply): void;
-     }
-
-     /** BCP-47 primary language subtags the widget ships built-in translations for. */
-     export declare type LocaleCode = "en" | "es" | "fr" | "de";
-
-     /** Built-in translations keyed by {@link LocaleCode}. */
-     export declare const locales: Record<LocaleCode, ClaudiusTranslations>;
-
-     /** A value that may be returned synchronously or as a promise. */
-     export declare type MaybePromise<T> = T | Promise<T>;
-
-     /**
-      * Reference plugin that emits a structured analytics event for every message
-      * sent, every reply received, and every error. It never modifies messages.
-      *
-      * @example
-      * ```ts
-      * <ChatWidget
-      *   apiUrl={url}
-      *   plugins={[pluginAnalytics({ onEvent: (e) => gtag("event", e.type, e) })]}
-      * />
-      * ```
-      */
-     export declare function pluginAnalytics(options: AnalyticsPluginOptions): ClaudiusPlugin;
-
-     /**
-      * Reference plugin that answers matching messages locally, without calling the
-      * API. The first rule whose matcher fires short-circuits the send via
-      * `ctx.respondWith`, so the network is never hit for that turn.
-      *
-      * @example
-      * ```ts
-      * <ChatWidget
-      *   apiUrl={url}
-      *   plugins={[pluginCannedResponses({
-      *     rules: [
-      *       { match: "hours", reply: "We're open 9-5, Mon-Fri." },
-      *       { match: /pricing|cost/i, reply: "See https://example.com/pricing." },
-      *     ],
-      *   })]}
-      * />
-      * ```
-      */
-     export declare function pluginCannedResponses(options: CannedResponsesOptions): ClaudiusPlugin;
-
-     /**
-      * Read-only context shared by every plugin hook.
-      *
-      * `messages` is a snapshot of the conversation at the moment the hook runs:
-      * in {@link ClaudiusPlugin.onBeforeSend} it excludes the in-flight user
-      * message; in {@link ClaudiusPlugin.onAfterReceive} and
-      * {@link ClaudiusPlugin.onError} it includes it.
-      */
-     export declare interface PluginContext {
-         /** Conversation snapshot, oldest message first. Treat as immutable. */
-         readonly messages: readonly ChatMessage[];
-         /** The Worker chat endpoint URL the widget posts to. */
-         readonly apiUrl: string;
-     }
-
-     /**
-      * Reference plugin that strips PII from the user's message before it leaves the
-      * browser. The redacted text is what gets displayed and sent, so the user sees
-      * that redaction happened. Optionally redacts assistant replies too.
-      *
-      * @example
-      * ```ts
-      * <ChatWidget apiUrl={url} plugins={[pluginRedactPII()]} />
-      * ```
-      */
-     export declare function pluginRedactPII(options?: RedactPiiOptions): ClaudiusPlugin;
-
-     /**
-      * A synthesized assistant reply, produced by a plugin instead of (or in
-      * recovery from) a network round-trip. Passed to
-      * {@link BeforeSendContext.respondWith} and {@link ErrorContext.respondWith}.
-      */
-     export declare interface PluginReply {
-         /** The assistant reply text to render. */
-         content: string;
-         /** Optional sources to attach to the synthesized reply. */
-         sources?: Source[];
-     }
-
-     /** Options for {@link pluginRedactPII}. */
-     export declare interface RedactPiiOptions {
-         /**
-          * Patterns to redact. Each must carry the global (`g`) flag.
-          * @defaultValue {@link DEFAULT_PII_PATTERNS}
-          */
-         patterns?: readonly RegExp[];
-         /**
-          * Text substituted for each match.
-          * @defaultValue `"[redacted]"`
-          */
-         replacement?: string;
-         /**
-          * Also redact the assistant's replies, not just outgoing user messages.
-          * @defaultValue `false`
-          */
-         redactReplies?: boolean;
-     }
-
-     /** Replace every match of every pattern in `text` with `replacement`. */
-     export declare function redactText(text: string, patterns: readonly RegExp[], replacement: string): string;
-
-     /**
-      * Resolve the final translations for a locale, applying any per-string
-      * overrides on top of the chosen locale's defaults.
-      *
-      * @param options - Locale and override settings.
-      * @returns A complete translations object.
-      */
-     export declare function resolveTranslations(options?: ResolveTranslationsOptions): ClaudiusTranslations;
-
-     /** Options for {@link resolveTranslations}. */
-     export declare interface ResolveTranslationsOptions {
-         /** Locale to use. Defaults to the result of {@link detectLocale}. */
-         locale?: LocaleCode;
-         /** Per-string overrides layered over the chosen locale's translations. */
-         translations?: Partial<ClaudiusTranslations>;
-     }
-
-     /**
-      * A cited source the assistant referenced when answering. Rendered as a link
-      * in the chat and grouped in the sources sidebar.
-      */
-     export declare interface Source {
-         /** Absolute URL of the source. */
-         url: string;
-         /** Human-readable link title shown to the user. */
-         title: string;
-         /** Origin category, used to group and label the source. */
-         type: "blog" | "page" | "external";
-     }
-
-     declare const THEME_COLOR_TOKENS: readonly ["accent", "accentText", "accentSoft", "accentTextMuted", "surface", "surfaceMuted", "text", "textMuted", "border", "userBubble", "userBubbleText", "assistantBubble", "assistantBubbleText", "field", "error", "errorSurface", "errorText", "link", "scrim"];
-
-     declare const THEME_FONT_TOKENS: readonly ["heading", "body"];
-
-     declare const THEME_RADIUS_TOKENS: readonly ["sm", "md", "lg", "full", "tail"];
-
-     declare const THEME_SHADOW_TOKENS: readonly ["elevated", "floating", "floatingHover"];
-
-     /** Names of the color tokens a theme can override (e.g. `accent`, `surface`, `text`). */
-     export declare type ThemeColorToken = (typeof THEME_COLOR_TOKENS)[number];
-
-     /** Names of the font-family tokens a theme can override. */
-     export declare type ThemeFontToken = (typeof THEME_FONT_TOKENS)[number];
-
-     /** Names of the border-radius tokens a theme can override. */
-     export declare type ThemeRadiusToken = (typeof THEME_RADIUS_TOKENS)[number];
-
-     /** Names of the box-shadow tokens a theme can override. */
-     export declare type ThemeShadowToken = (typeof THEME_SHADOW_TOKENS)[number];
-
-     /**
-      * A proactive engagement rule. Each variant fires at most once per page on a
-      * different signal: elapsed time, scroll depth, exit intent, or URL match.
-      */
-     export declare type Trigger = {
-         /** Fire after a fixed dwell time. */
-         on: "time";
-         /** Seconds to wait before firing. */
-         seconds: number;
-         /** Only fire when the current URL matches this pattern. */
-         matchUrl?: UrlPattern;
-         /** Action to run when the trigger fires. */
-         action: TriggerAction;
-     } | {
-         /** Fire once the user scrolls past a depth threshold. */
-         on: "scroll";
-         /** Scroll depth (0-100) that fires the trigger. */
-         percent: number;
-         /** Only fire when the current URL matches this pattern. */
-         matchUrl?: UrlPattern;
-         /** Action to run when the trigger fires. */
-         action: TriggerAction;
-     } | {
-         /** Fire when the pointer leaves the top of the viewport (exit intent). */
-         on: "exit-intent";
-         /** Only fire when the current URL matches this pattern. */
-         matchUrl?: UrlPattern;
-         /** Action to run when the trigger fires. */
-         action: TriggerAction;
-     } | {
-         /** Fire immediately when the current URL matches. */
-         on: "url";
-         /** URL pattern that must match for the trigger to fire. */
-         pattern: UrlPattern;
-         /** Action to run when the trigger fires. */
-         action: TriggerAction;
-     };
-
-     /**
-      * What a {@link Trigger} does when it fires: open the chat, or show a greeting
-      * bubble with the given message.
-      */
-     export declare type TriggerAction = "open" | {
-         /** Greeting bubble message to display. */
-         greeting: string;
-     };
-
-     /** A URL match: a case-insensitive substring, or a regular expression. */
-     export declare type UrlPattern = string | RegExp;
-
-     /** Corner of the viewport the widget docks to. */
-     export declare type WidgetPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
-
-     export { }
+          * Falls back to {@link sendMessage} (non-streaming) when the browser can't
+          * read response streams or the Worker doesn't expose `/api/chat/stream`
+          * (HTTP 404/405), so callers never need their own feature detection.
+          *
+          * Failures before the first byte follow the same retry policy as
+          * {@link sendMessage}; once streaming has begun there are no automatic
+          * retries. Aborting via {@link ChatStreamOptions.signal} is not an error:
+          * the promise resolves with the partial reply and `aborted: true`.
+          *
+          * @param messages - The full conversation so far, oldest message first.
+          * @param options - Chunk callback and cancellation signal.
+          * @throws {@link DebounceError} when called within the debounce window.
+              * @throws {@link ChatApiError} when the request fails after all retries, or
+                  *   the stream errors or is interrupted mid-reply (code `"STREAM_ERROR"`).
+                  */
+              streamMessage(messages: ChatMessage[], options?: ChatStreamOptions): Promise<ChatStreamResult>;
+              /**
+               * Consumes an SSE body, invoking `onChunk` per `chunk` event, resolving on
+               * `done`, throwing on `error` events or an interrupted connection, and
+               * resolving with the partial text when the caller aborts.
+               */
+              private readSseStream;
+              private fetchStream;
+              private fetchWithTimeout;
+              private isRetryable;
+              private getRetryDelay;
+              private delay;
+          }
+
+          /**
+           * Options for {@link ChatApiClient}.
+           */
+          export declare interface ChatApiClientOptions {
+              /**
+               * Maximum retries after the first attempt, for retryable failures (HTTP
+               * 429/503, network errors, timeouts).
+               * @defaultValue `2`
+               */
+              maxRetries?: number;
+              /**
+               * Minimum gap between sends, in milliseconds. A send inside this window
+               * rejects with {@link DebounceError}. Set to 0 to disable.
+               * @defaultValue `300`
+               */
+              debounceMs?: number;
+              /**
+               * Per-attempt request timeout in milliseconds. Aborts the in-flight fetch
+               * via `AbortController` and surfaces a retryable {@link ChatApiError} with
+               * code `"TIMEOUT"`. Set to 0 to disable.
+               * @defaultValue `30000`
+               */
+              timeoutMs?: number;
+          }
+
+          /**
+           * Error thrown by {@link ChatApiClient} when a chat request ultimately fails:
+           * either after exhausting retries, or immediately for a non-retryable status.
+           */
+          export declare class ChatApiError extends Error {
+              /** HTTP status code, or `0` for network and timeout failures. */
+              readonly status: number;
+              /** Machine-readable error code, when available (e.g. `"TIMEOUT"`). */
+              readonly code?: string | undefined;
+              /** Seconds to wait before retrying, parsed from the `Retry-After` header. */
+              readonly retryAfter?: number | undefined;
+              /**
+               * Create a {@link ChatApiError}.
+               *
+               * @param message - Human-readable error message.
+               * @param status - HTTP status code, or `0` for network and timeout failures.
+               * @param code - Optional machine-readable error code (e.g. `"TIMEOUT"`, `"NETWORK_ERROR"`).
+               * @param retryAfter - Seconds to wait before retrying, from the `Retry-After` header.
+               */
+              constructor(message: string, 
+              /** HTTP status code, or `0` for network and timeout failures. */
+              status: number, 
+              /** Machine-readable error code, when available (e.g. `"TIMEOUT"`). */
+              code?: string | undefined, 
+              /** Seconds to wait before retrying, parsed from the `Retry-After` header. */
+              retryAfter?: number | undefined);
+          }
+
+          /**
+           * Error response body returned by the Worker when a chat request fails.
+           */
+          export declare interface ChatErrorResponse {
+              /** Human-readable error message. */
+              error: string;
+              /** Optional machine-readable error code (e.g. `"RATE_LIMITED"`). */
+              code?: string;
+          }
+
+          /**
+           * A single chat message exchanged between the user and the assistant.
+           */
+          export declare interface ChatMessage {
+              /** Stable unique identifier, used as the React list key. */
+              id: string;
+              /** Who authored the message. */
+              role: "user" | "assistant";
+              /** Plain-text message body. */
+              content: string;
+              /** Sources cited by the assistant for this message, when any. */
+              sources?: Source[];
+              /** Tools the assistant called while producing this message, when any. */
+              toolUses?: ToolUse[];
+          }
+
+          /**
+           * Request payload sent to the Worker `POST /api/chat` endpoint.
+           */
+          export declare interface ChatRequest {
+              /** The full conversation so far, oldest message first. */
+              messages: ChatMessage[];
+          }
+
+          /**
+           * Successful response body from `POST /api/chat`.
+           */
+          export declare interface ChatResponse {
+              /** The assistant's reply text. */
+              reply: string;
+              /** Sources the assistant cited, when any. */
+              sources?: Source[];
+              /** Tools the assistant called while producing the reply, when any. */
+              toolUses?: ToolUse[];
+          }
+
+          /**
+           * Options for {@link ChatApiClient.streamMessage}.
+           */
+          export declare interface ChatStreamOptions {
+              /**
+               * Called once per streamed text delta, as tokens arrive.
+               *
+               * @param text - The incremental text of this chunk.
+               * @param fullText - The full reply accumulated so far, including this chunk.
+               */
+              onChunk?: (text: string, fullText: string) => void;
+              /**
+               * Called when the assistant finishes a tool call mid-stream, so the UI can
+               * show a "used tool" affordance before the reply completes.
+               */
+              onToolUse?: (toolUse: ToolUse, allToolUses: ToolUse[]) => void;
+              /**
+               * Cancels the stream when aborted. Cancellation is not an error: the
+               * promise resolves with the partial reply and `aborted: true`.
+               */
+              signal?: AbortSignal;
+          }
+
+          /**
+           * Result of a completed or cancelled streaming chat request.
+           */
+          export declare interface ChatStreamResult extends ChatResponse {
+              /** `true` when the caller cancelled the stream before it finished. */
+              aborted?: boolean;
+          }
+
+          /**
+           * Root Claudius chat widget: a floating toggle button that opens a chat window
+           * backed by the Worker chat API. Render a single instance on the page.
+           *
+           * @param props - See {@link ChatWidgetProps}.
+           * @example
+           * ```tsx
+           * <ChatWidget apiUrl="https://api.example.com" title="Support" />
+           * ```
+           */
+          export declare function ChatWidget({ apiUrl, title, subtitle, welcomeMessage, placeholder, persistMessages, storageKeyPrefix, requestTimeoutMs, theme, accentColor, position, locale, translations: translationOverrides, triggers, plugins, streaming, }: ChatWidgetProps): JSX_2.Element;
+
+          /**
+           * Props for the {@link ChatWidget} component.
+           */
+          export declare interface ChatWidgetProps {
+              /** Absolute URL of the Worker chat endpoint (e.g. `https://api.example.com`). */
+              apiUrl: string;
+              /** Header title. Falls back to the active locale's default title. */
+              title?: string;
+              /** Header subtitle shown beneath the title. */
+              subtitle?: string;
+              /** First assistant message shown when the chat opens. */
+              welcomeMessage?: string;
+              /** Placeholder text for the message input. */
+              placeholder?: string;
+              /**
+               * Persist the conversation to storage so it survives reloads.
+               * @defaultValue `false`
+               */
+              persistMessages?: boolean;
+              /** Prefix for the storage key used when {@link ChatWidgetProps.persistMessages} is enabled. */
+              storageKeyPrefix?: string;
+              /** Abort a chat request after this many milliseconds. */
+              requestTimeoutMs?: number;
+              /**
+               * Color-scheme mode ("light" | "dark" | "auto"), a built-in theme name
+               * ("default" | "minimal" | "playful" | "corporate"), an inline
+               * ClaudiusTheme object, or a URL to a theme JSON file.
+               * @defaultValue `"light"`
+               */
+              theme?: ClaudiusThemeInput;
+              /** Accent color override; wins over the theme's accent in both light and dark. */
+              accentColor?: string;
+              /**
+               * Corner of the viewport the widget docks to.
+               * @defaultValue `"bottom-right"`
+               */
+              position?: WidgetPosition;
+              /** BCP-47 locale used to select built-in translations. */
+              locale?: LocaleCode;
+              /** Partial overrides merged over the resolved locale translations. */
+              translations?: Partial<ClaudiusTranslations>;
+              /** Proactive open/greeting rules evaluated against the current page. */
+              triggers?: Trigger[];
+              /**
+               * Middleware run around each message: `onBeforeSend`, `onAfterReceive`, and
+               * `onError`. Hooks run in array order and may modify, replace, or
+               * short-circuit messages. See {@link ClaudiusPlugin}.
+               */
+              plugins?: ClaudiusPlugin[];
+              /**
+               * Stream assistant replies token-by-token from the Worker's SSE endpoint,
+               * with automatic fallback to the non-streaming API on older browsers or
+               * Workers without `/api/chat/stream`. Set to `false` to always use the
+               * blocking request/response flow.
+               * @defaultValue `true`
+               */
+              streaming?: boolean;
+          }
+
+          /** An analytics event emitted by {@link pluginAnalytics}. */
+          export declare type ClaudiusAnalyticsEvent = {
+              /** Event discriminant. */
+              type: "message_sent";
+              /** Always `"user"`. */
+              role: "user";
+              /** Message text, or `""` when `includeContent` is `false`. */
+              content: string;
+              /** Length of the message in characters. */
+              chars: number;
+          } | {
+              /** Event discriminant. */
+              type: "message_received";
+              /** Always `"assistant"`. */
+              role: "assistant";
+              /** Reply text, or `""` when `includeContent` is `false`. */
+              content: string;
+              /** Length of the reply in characters. */
+              chars: number;
+          } | {
+              /** Event discriminant. */
+              type: "chat_error";
+              /** The error message. */
+              message: string;
+              /** Machine-readable error code, when available (e.g. `"TIMEOUT"`). */
+              code?: string;
+          };
+
+          /**
+           * A client-side middleware that runs around the chat message lifecycle. Pass
+           * an array of plugins to {@link ChatWidget} via the `plugins` prop; hooks run
+           * in array order.
+           *
+           * Hooks may be async, and may modify, replace, or short-circuit messages. A
+           * hook that throws is caught and logged — a misbehaving plugin will not break
+           * the chat — so security-sensitive transforms (e.g. PII redaction) should be
+           * written defensively.
+           *
+           * @example
+           * ```ts
+           * const logger: ClaudiusPlugin = {
+           *   name: "logger",
+           *   onBeforeSend: (message) => { console.log("sending", message.content); },
+           *   onAfterReceive: (message) => { console.log("received", message.content); },
+           * };
+           * ```
+           */
+          export declare interface ClaudiusPlugin {
+              /** Stable identifier, used in log messages. */
+              name: string;
+              /**
+               * Runs before the user message is sent. Return a {@link ChatMessage} to
+               * replace it (the returned message is both displayed and sent), return
+               * nothing to leave it unchanged, or call {@link BeforeSendContext.respondWith}
+               * / {@link BeforeSendContext.abort} to short-circuit.
+               */
+              onBeforeSend?(message: ChatMessage, ctx: BeforeSendContext): MaybePromise<ChatMessage | void>;
+              /**
+               * Runs after the assistant reply is received, before it is rendered. Return
+               * a {@link ChatMessage} to replace it, or nothing to leave it unchanged.
+               */
+              onAfterReceive?(message: ChatMessage, ctx: PluginContext): MaybePromise<ChatMessage | void>;
+              /**
+               * Runs when a send fails. Observe the error, or call
+               * {@link ErrorContext.respondWith} to render a fallback reply instead of the
+               * error UI.
+               */
+              onError?(error: Error, ctx: ErrorContext): MaybePromise<void>;
+          }
+
+          /**
+           * A Claudius design-token theme. Every value is a CSS string applied via
+           * --cl-* custom properties. `colors` apply to both light and dark modes
+           * unless `colorsDark` overrides a token for dark mode specifically.
+           *
+           * JSON theme files validate against
+           * https://claudius-docs.pages.dev/schema/theme.v1.json
+           */
+          export declare interface ClaudiusTheme {
+              /** Optional JSON Schema URL, for editor validation and autocomplete. */
+              $schema?: string;
+              /** Human-readable theme name. */
+              name?: string;
+              /** Initial color scheme this theme is designed for. Defaults to "light". */
+              colorScheme?: "light" | "dark" | "auto";
+              /** Color token overrides applied in both light and dark mode. */
+              colors?: Partial<Record<ThemeColorToken, string>>;
+              /** Color token overrides applied only in dark mode, layered over {@link ClaudiusTheme.colors}. */
+              colorsDark?: Partial<Record<ThemeColorToken, string>>;
+              /** Border-radius token overrides. */
+              radii?: Partial<Record<ThemeRadiusToken, string>>;
+              /** Box-shadow token overrides. */
+              shadows?: Partial<Record<ThemeShadowToken, string>>;
+              /** Font-family token overrides. */
+              fonts?: Partial<Record<ThemeFontToken, string>>;
+          }
+
+          /**
+           * Everything the `theme` option accepts: the original color-scheme modes, a
+           * built-in theme name, an inline theme object, or a URL to a theme JSON file.
+           * `(string & {})` keeps literal autocomplete while allowing URLs.
+           */
+          export declare type ClaudiusThemeInput = "light" | "dark" | "auto" | BuiltinThemeName | ClaudiusTheme | (string & {});
+
+          /**
+           * Every user-facing string the widget renders. Pass a {@link ClaudiusTranslations}
+           * (or a partial override) to localize the UI. English is the source of truth;
+           * see {@link defaultTranslations}.
+           */
+          export declare interface ClaudiusTranslations {
+              /** Chat window header title. */
+              title: string;
+              /** Chat window header subtitle. */
+              subtitle: string;
+              /** First assistant message shown when the chat opens. */
+              welcomeMessage: string;
+              /** Accessible label for the close button. */
+              closeChat: string;
+              /** Accessible label for the message list region. */
+              chatMessages: string;
+              /** Accessible label for the typing indicator. */
+              typingIndicator: string;
+              /** Placeholder text for the message input. */
+              placeholder: string;
+              /** Accessible label for the send button. */
+              sendMessage: string;
+              /** Accessible label for the stop button shown while a reply streams in. */
+              stopGenerating: string;
+              /** Label prefix for the "used tool" chip on assistant messages. */
+              toolUsed: string;
+              /** Accessible label for the tool-details disclosure toggle. */
+              toolDetails: string;
+              /** Accessible label for the message input field. */
+              typeYourMessage: string;
+              /** Accessible label for the button that opens the chat. */
+              openChat: string;
+              /** Accessible label for dismissing the greeting bubble. */
+              dismissGreeting: string;
+              /** Generic fallback error message. */
+              errorGeneric: string;
+              /** Error shown when the network request fails. */
+              errorConnection: string;
+              /** Error shown when a request times out. */
+              errorTimeout: string;
+              /** Error shown when rate-limited (per-minute limit). */
+              errorRateLimitMinute: string;
+              /** Error shown when rate-limited (per-hour limit). */
+              errorRateLimitHour: string;
+              /** Label for the retry action on a failed message. */
+              errorRetry: string;
+          }
+
+          /**
+           * Build a complete {@link ClaudiusTranslations} from the English defaults,
+           * applying the given overrides.
+           *
+           * @param overrides - Strings to override on top of {@link defaultTranslations}.
+           * @returns A complete translations object.
+           */
+          export declare function createTranslations(overrides?: Partial<ClaudiusTranslations>): ClaudiusTranslations;
+
+          /**
+           * Error thrown by {@link ChatApiClient.sendMessage} when a send is rejected
+           * for arriving within the configured debounce window.
+           */
+          export declare class DebounceError extends Error {
+              /** Creates a `DebounceError` with a fixed message. */
+              constructor();
+          }
+
+          /**
+           * Default PII patterns: email addresses, North-American-style phone numbers,
+           * US Social Security numbers, and 13–16 digit card-like sequences. These are
+           * intentionally conservative starting points — tune {@link RedactPiiOptions.patterns}
+           * for your data.
+           */
+          export declare const DEFAULT_PII_PATTERNS: readonly RegExp[];
+
+          /** The default (English) translations, used when no locale or override applies. */
+          export declare const defaultTranslations: ClaudiusTranslations;
+
+          /**
+           * Detect the best {@link LocaleCode} for the current environment: the document
+           * `lang` attribute first, then the browser language, falling back to `"en"`.
+           *
+           * @returns The detected locale code.
+           */
+          export declare function detectLocale(): LocaleCode;
+
+          /**
+           * Context for {@link ClaudiusPlugin.onError}. Adds the ability to recover from
+           * a failed send by rendering a reply in place of the error UI.
+           */
+          export declare interface ErrorContext extends PluginContext {
+              /**
+               * Recover from the failure by rendering this assistant reply instead of the
+               * error state. Stops the hook chain — later plugins' `onError` hooks do not
+               * run.
+               */
+              respondWith(reply: string | PluginReply): void;
+          }
+
+          /** BCP-47 primary language subtags the widget ships built-in translations for. */
+          export declare type LocaleCode = "en" | "es" | "fr" | "de";
+
+          /** Built-in translations keyed by {@link LocaleCode}. */
+          export declare const locales: Record<LocaleCode, ClaudiusTranslations>;
+
+          /** A value that may be returned synchronously or as a promise. */
+          export declare type MaybePromise<T> = T | Promise<T>;
+
+          /**
+           * Reference plugin that emits a structured analytics event for every message
+           * sent, every reply received, and every error. It never modifies messages.
+           *
+           * @example
+           * ```ts
+           * <ChatWidget
+           *   apiUrl={url}
+           *   plugins={[pluginAnalytics({ onEvent: (e) => gtag("event", e.type, e) })]}
+           * />
+           * ```
+           */
+          export declare function pluginAnalytics(options: AnalyticsPluginOptions): ClaudiusPlugin;
+
+          /**
+           * Reference plugin that answers matching messages locally, without calling the
+           * API. The first rule whose matcher fires short-circuits the send via
+           * `ctx.respondWith`, so the network is never hit for that turn.
+           *
+           * @example
+           * ```ts
+           * <ChatWidget
+           *   apiUrl={url}
+           *   plugins={[pluginCannedResponses({
+           *     rules: [
+           *       { match: "hours", reply: "We're open 9-5, Mon-Fri." },
+           *       { match: /pricing|cost/i, reply: "See https://example.com/pricing." },
+           *     ],
+           *   })]}
+           * />
+           * ```
+           */
+          export declare function pluginCannedResponses(options: CannedResponsesOptions): ClaudiusPlugin;
+
+          /**
+           * Read-only context shared by every plugin hook.
+           *
+           * `messages` is a snapshot of the conversation at the moment the hook runs:
+           * in {@link ClaudiusPlugin.onBeforeSend} it excludes the in-flight user
+           * message; in {@link ClaudiusPlugin.onAfterReceive} and
+           * {@link ClaudiusPlugin.onError} it includes it.
+           */
+          export declare interface PluginContext {
+              /** Conversation snapshot, oldest message first. Treat as immutable. */
+              readonly messages: readonly ChatMessage[];
+              /** The Worker chat endpoint URL the widget posts to. */
+              readonly apiUrl: string;
+          }
+
+          /**
+           * Reference plugin that strips PII from the user's message before it leaves the
+           * browser. The redacted text is what gets displayed and sent, so the user sees
+           * that redaction happened. Optionally redacts assistant replies too.
+           *
+           * @example
+           * ```ts
+           * <ChatWidget apiUrl={url} plugins={[pluginRedactPII()]} />
+           * ```
+           */
+          export declare function pluginRedactPII(options?: RedactPiiOptions): ClaudiusPlugin;
+
+          /**
+           * A synthesized assistant reply, produced by a plugin instead of (or in
+           * recovery from) a network round-trip. Passed to
+           * {@link BeforeSendContext.respondWith} and {@link ErrorContext.respondWith}.
+           */
+          export declare interface PluginReply {
+              /** The assistant reply text to render. */
+              content: string;
+              /** Optional sources to attach to the synthesized reply. */
+              sources?: Source[];
+          }
+
+          /** Options for {@link pluginRedactPII}. */
+          export declare interface RedactPiiOptions {
+              /**
+               * Patterns to redact. Each must carry the global (`g`) flag.
+               * @defaultValue {@link DEFAULT_PII_PATTERNS}
+               */
+              patterns?: readonly RegExp[];
+              /**
+               * Text substituted for each match.
+               * @defaultValue `"[redacted]"`
+               */
+              replacement?: string;
+              /**
+               * Also redact the assistant's replies, not just outgoing user messages.
+               * @defaultValue `false`
+               */
+              redactReplies?: boolean;
+          }
+
+          /** Replace every match of every pattern in `text` with `replacement`. */
+          export declare function redactText(text: string, patterns: readonly RegExp[], replacement: string): string;
+
+          /**
+           * Resolve the final translations for a locale, applying any per-string
+           * overrides on top of the chosen locale's defaults.
+           *
+           * @param options - Locale and override settings.
+           * @returns A complete translations object.
+           */
+          export declare function resolveTranslations(options?: ResolveTranslationsOptions): ClaudiusTranslations;
+
+          /** Options for {@link resolveTranslations}. */
+          export declare interface ResolveTranslationsOptions {
+              /** Locale to use. Defaults to the result of {@link detectLocale}. */
+              locale?: LocaleCode;
+              /** Per-string overrides layered over the chosen locale's translations. */
+              translations?: Partial<ClaudiusTranslations>;
+          }
+
+          /**
+           * A cited source the assistant referenced when answering. Rendered as a link
+           * in the chat and grouped in the sources sidebar.
+           */
+          export declare interface Source {
+              /** Absolute URL of the source. */
+              url: string;
+              /** Human-readable link title shown to the user. */
+              title: string;
+              /** Origin category, used to group and label the source. */
+              type: "blog" | "page" | "external";
+          }
+
+          declare const THEME_COLOR_TOKENS: readonly ["accent", "accentText", "accentSoft", "accentTextMuted", "surface", "surfaceMuted", "text", "textMuted", "border", "userBubble", "userBubbleText", "assistantBubble", "assistantBubbleText", "field", "error", "errorSurface", "errorText", "link", "scrim"];
+
+          declare const THEME_FONT_TOKENS: readonly ["heading", "body"];
+
+          declare const THEME_RADIUS_TOKENS: readonly ["sm", "md", "lg", "full", "tail"];
+
+          declare const THEME_SHADOW_TOKENS: readonly ["elevated", "floating", "floatingHover"];
+
+          /** Names of the color tokens a theme can override (e.g. `accent`, `surface`, `text`). */
+          export declare type ThemeColorToken = (typeof THEME_COLOR_TOKENS)[number];
+
+          /** Names of the font-family tokens a theme can override. */
+          export declare type ThemeFontToken = (typeof THEME_FONT_TOKENS)[number];
+
+          /** Names of the border-radius tokens a theme can override. */
+          export declare type ThemeRadiusToken = (typeof THEME_RADIUS_TOKENS)[number];
+
+          /** Names of the box-shadow tokens a theme can override. */
+          export declare type ThemeShadowToken = (typeof THEME_SHADOW_TOKENS)[number];
+
+          /**
+           * One tool call the assistant made while producing a reply. Rendered as a
+           * compact "used tool" affordance with an optional details disclosure.
+           */
+          export declare interface ToolUse {
+              /** Tool name (e.g. `"get_current_time"`). */
+              name: string;
+              /** Input the model supplied to the tool. */
+              input?: Record<string, unknown>;
+              /** Serialized tool result, as the model saw it. */
+              result?: string;
+              /** Present when the tool call failed. */
+              isError?: boolean;
+          }
+
+          /**
+           * A proactive engagement rule. Each variant fires at most once per page on a
+           * different signal: elapsed time, scroll depth, exit intent, or URL match.
+           */
+          export declare type Trigger = {
+              /** Fire after a fixed dwell time. */
+              on: "time";
+              /** Seconds to wait before firing. */
+              seconds: number;
+              /** Only fire when the current URL matches this pattern. */
+              matchUrl?: UrlPattern;
+              /** Action to run when the trigger fires. */
+              action: TriggerAction;
+          } | {
+              /** Fire once the user scrolls past a depth threshold. */
+              on: "scroll";
+              /** Scroll depth (0-100) that fires the trigger. */
+              percent: number;
+              /** Only fire when the current URL matches this pattern. */
+              matchUrl?: UrlPattern;
+              /** Action to run when the trigger fires. */
+              action: TriggerAction;
+          } | {
+              /** Fire when the pointer leaves the top of the viewport (exit intent). */
+              on: "exit-intent";
+              /** Only fire when the current URL matches this pattern. */
+              matchUrl?: UrlPattern;
+              /** Action to run when the trigger fires. */
+              action: TriggerAction;
+          } | {
+              /** Fire immediately when the current URL matches. */
+              on: "url";
+              /** URL pattern that must match for the trigger to fire. */
+              pattern: UrlPattern;
+              /** Action to run when the trigger fires. */
+              action: TriggerAction;
+          };
+
+          /**
+           * What a {@link Trigger} does when it fires: open the chat, or show a greeting
+           * bubble with the given message.
+           */
+          export declare type TriggerAction = "open" | {
+              /** Greeting bubble message to display. */
+              greeting: string;
+          };
+
+          /** A URL match: a case-insensitive substring, or a regular expression. */
+          export declare type UrlPattern = string | RegExp;
+
+          /** Corner of the viewport the widget docks to. */
+          export declare type WidgetPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+
+          export { }