@mordn/chat-widget 0.9.0 → 0.10.1

package/dist/{chat-store-DdykLpDo.d.mts → chat-store-Dq1Zy_qV.d.mts}

@@ -275,4 +275,4 @@ interface ChatStore {
  */
 type ChatStoreFactory = (userId: string) => ChatStore;
 
-export { type ChatStore as C, type ListMessagesOptions as L, type StoredAttachment as S, type ChatStoreFactory as a, type StoredConversation as b, type StoredMessage as c, type SaveTurnInput as d, ConversationOwnershipError as e };
+export { type ChatStore as C, type ListMessagesOptions as L, type StoredAttachment as S, type StoredConversation as a, type StoredMessage as b, type SaveTurnInput as c, type ChatStoreFactory as d, ConversationOwnershipError as e };

package/dist/{chat-store-DdykLpDo.d.ts → chat-store-Dq1Zy_qV.d.ts}

@@ -275,4 +275,4 @@ interface ChatStore {
  */
 type ChatStoreFactory = (userId: string) => ChatStore;
 
-export { type ChatStore as C, type ListMessagesOptions as L, type StoredAttachment as S, type ChatStoreFactory as a, type StoredConversation as b, type StoredMessage as c, type SaveTurnInput as d, ConversationOwnershipError as e };
+export { type ChatStore as C, type ListMessagesOptions as L, type StoredAttachment as S, type StoredConversation as a, type StoredMessage as b, type SaveTurnInput as c, type ChatStoreFactory as d, ConversationOwnershipError as e };

package/dist/handler-types-Bil94kTX.d.ts

@@ -0,0 +1,204 @@
+import { LanguageModel, ToolSet, ModelMessage, UIMessage, StopCondition } from 'ai';
+import { d as ChatStoreFactory } from './chat-store-Dq1Zy_qV.js';
+import { a as StorageAdapterFactory } from './storage-adapter-DD8uqiAP.js';
+
+/**
+ * Public configuration surface for `createChatHandler`.
+ *
+ * This is the API a host app touches to mount the chat backend. The design
+ * follows one rule, derived from auditing a real power-user integration
+ * (Jarvis): take away the shared, dangerous-to-get-wrong plumbing; keep every
+ * point of genuine per-app variation as an injection point or a hook.
+ *
+ * Three tiers of override, from "you must" to "you rarely will":
+ *
+ *   REQUIRED injections — no safe default exists:
+ *     • getUserId          (identity; the security boundary)
+ *
+ *   OPTIONAL injections — a default exists, swap to take control:
+ *     • model              (which LLM)
+ *     • buildTools         (your tools, incl. per-request resources)
+ *     • store              (persistence; hosted default)
+ *     • storage            (attachments; hosted default)
+ *
+ *   HOOKS — the loop runs fine without them; override one seam at a time:
+ *     • buildSystemPrompt, transformMessages, onChatFinish, onError,
+ *       stopWhen, upload
+ *
+ * Everything NOT in this file — ownership checks, idempotency, pagination,
+ * re-signing, socket teardown, save-on-finish — is owned by the handler and
+ * is intentionally not configurable, because getting it wrong is a security
+ * or correctness bug, not a preference.
+ */
+
+/**
+ * Everything a per-request hook/injection needs to know about the current
+ * request, assembled by the handler AFTER authentication. Passed to
+ * `buildTools`, `model` (when a function), `buildSystemPrompt`, and
+ * `transformMessages`.
+ *
+ * Note `userId` is the server-verified identity — the same value the store
+ * and storage are bound to. Hooks can trust it.
+ */
+interface ChatRequestContext {
+    /** Server-verified user id. Never client-supplied. */
+    userId: string;
+    /** The conversation this request targets. */
+    conversationId: string;
+    /** The raw request, for hooks that need headers/cookies (e.g. an org id). */
+    request: Request;
+}
+/**
+ * Per-agent declarative config returned by a hosted control plane. All fields
+ * optional — only what the dashboard has set is present; the rest falls through
+ * to code/defaults. `model` is a gateway model string (e.g. "anthropic/…").
+ */
+interface HostedAgentConfig {
+    model?: string | null;
+    systemPrompt?: string | null;
+    greeting?: string | null;
+    appearance?: Record<string, unknown> | null;
+}
+/**
+ * What `buildTools` returns. The `cleanup` callback is the critical piece the
+ * naive "just return a ToolSet" design misses: tools backed by a per-request
+ * resource (an MCP client holding a socket, a DB transaction, a temp scope)
+ * MUST be torn down after the stream finishes — exactly once, whether the
+ * stream completed, errored, or the client aborted. The handler guarantees
+ * that single, correctly-timed call so the host app never leaks sockets.
+ */
+interface BuiltTools {
+    tools: ToolSet;
+    /**
+     * Called exactly once when the request is fully done (success, error, or
+     * abort), after the response stream has settled. Optional — omit when your
+     * tools hold no per-request resource.
+     */
+    cleanup?: () => void | Promise<void>;
+}
+/**
+ * Server-side upload policy. Enforced by the handler's upload route BEFORE
+ * any bytes touch storage, so an oversized or disallowed file is rejected
+ * with a clean 4xx instead of a framework body-parse failure. The widget's
+ * client-side `accept`/`maxBytes` should mirror these, but the SERVER is the
+ * source of truth — the client checks are UX, these checks are the boundary.
+ */
+interface UploadPolicy {
+    /**
+     * Allowed MIME types. An exact-match allow-list (not a prefix match) so
+     * `image/svg+xml` can be excluded while `image/png` is allowed. Defaults to
+     * a conservative image+pdf set that current vision models accept natively.
+     */
+    allowedMediaTypes?: string[];
+    /** Per-file size cap in bytes. Defaults to 5 MB. */
+    maxBytes?: number;
+}
+interface CreateChatHandlerOptions {
+    /**
+     * Derive the authenticated user's id from the SERVER session — a verified
+     * cookie/JWT, Clerk `auth()`, NextAuth `getServerSession()`,
+     * `supabase.auth.getUser()`, etc. Return `null` for an unauthenticated
+     * request; the handler responds 401.
+     *
+     * SECURITY: never read the id from the request body, query string, or a
+     * header the browser controls (e.g. `X-User-Id`). Those are forgeable and
+     * doing so reintroduces the IDOR this whole design exists to prevent. The
+     * handler passes you the `Request` so you can read *verified* cookies — not
+     * so you can read a client-asserted id.
+     */
+    getUserId: (request: Request) => Promise<string | null> | string | null;
+    /**
+     * The model to stream from. Either a fixed `LanguageModel` or a function of
+     * the request context (for per-user/per-org model selection). Defaults to a
+     * sensible current model when omitted.
+     */
+    model?: LanguageModel | ((ctx: ChatRequestContext) => LanguageModel | Promise<LanguageModel>);
+    /**
+     * Build the tool set for this request. Async and context-aware so tools can
+     * close over the user and open per-request resources (e.g. an MCP client).
+     * Return `{ tools, cleanup }`; the handler calls `cleanup` exactly once when
+     * the request settles. Omit for a chat with no tools.
+     */
+    buildTools?: (ctx: ChatRequestContext) => Promise<BuiltTools> | BuiltTools;
+    /**
+     * Persistence backend. Omit to use the hosted/default store. Provide a
+     * factory to bring your own DB. The factory is called per request with the
+     * server-verified `userId`; the handler never constructs a store with a
+     * client-supplied id.
+     */
+    store?: ChatStoreFactory;
+    /**
+     * Attachment storage backend. Omit to use the hosted/default adapter.
+     * Provide a factory for BYO storage (S3/R2/own bucket). Same per-request,
+     * verified-userId construction as `store`.
+     */
+    storage?: StorageAdapterFactory;
+    /**
+     * Fetch per-agent declarative config (model / systemPrompt / greeting /
+     * appearance) from a hosted control plane (mordn's GET /v1/config). This is
+     * how dashboard-managed config reaches the loop WITHOUT a redeploy.
+     *
+     * Precedence is always **code > hosted > package default**: any `model` /
+     * `buildSystemPrompt` you pass here in code takes priority; the hosted value
+     * only fills what code leaves unset. Returning `null` (or throwing) falls
+     * through to code/defaults — a control-plane hiccup never breaks a turn.
+     *
+     * Use `createHostedConfig({ apiKey })` from `@mordn/chat-widget/server/hosted`
+     * to get a ready-made fetcher.
+     */
+    getHostedConfig?: (ctx: ChatRequestContext) => Promise<HostedAgentConfig | null> | HostedAgentConfig | null;
+    /**
+     * Produce the system prompt for this request. Receives the context so it
+     * can personalise (e.g. bake in the user's name). Defaults to a generic
+     * assistant prompt.
+     */
+    buildSystemPrompt?: (ctx: ChatRequestContext) => string | Promise<string>;
+    /**
+     * Last-chance transform of the model-ready messages before they're sent to
+     * the model — after the handler has applied its own sliding-window prune.
+     * Use for provider-specific rewrites (e.g. image file-parts → image-parts)
+     * or extra capping. Defaults to identity.
+     */
+    transformMessages?: (messages: ModelMessage[], ctx: ChatRequestContext) => ModelMessage[] | Promise<ModelMessage[]>;
+    /**
+     * Called after the assistant turn has been persisted. For telemetry/usage
+     * logging. NOT where you save messages — the handler already did that. Any
+     * error thrown here is logged and swallowed; it never fails the response
+     * (the user already has their answer).
+     */
+    onChatFinish?: (info: {
+        ctx: ChatRequestContext;
+        messages: UIMessage[];
+        usage?: unknown;
+        providerMetadata?: unknown;
+    }) => void | Promise<void>;
+    /**
+     * Map a stream error to the user-facing string the widget shows. Lets you
+     * downgrade benign post-finish teardown noise and localise messages.
+     * Defaults to a generic message + server-side error log.
+     */
+    onError?: (error: unknown) => string;
+    /**
+     * When the model may chain tool calls, how long to let it run before it
+     * must answer. Defaults to a bounded step count so a misbehaving tool loop
+     * can't run forever. Pass any AI SDK `StopCondition`.
+     */
+    stopWhen?: StopCondition<ToolSet>;
+    /** Server-side upload policy (types + size). See `UploadPolicy`. */
+    upload?: UploadPolicy;
+    /**
+     * How many of the most-recent messages to send to the model (sliding
+     * window). Defaults to 30. The handler always prunes; this tunes the
+     * window. Older messages stay in the store and in the UI — only the model
+     * payload is windowed.
+     */
+    maxHistoryMessages?: number;
+    /**
+     * Defensive per-message character cap applied during pruning so a single
+     * giant pasted blob can't dominate the context window. Defaults to 4000.
+     * Set to `0` to disable.
+     */
+    maxMessageChars?: number;
+}
+
+export type { BuiltTools as B, CreateChatHandlerOptions as C, HostedAgentConfig as H, UploadPolicy as U, ChatRequestContext as a };

package/dist/handler-types-CCSjDZZ9.d.mts

@@ -0,0 +1,204 @@
+import { LanguageModel, ToolSet, ModelMessage, UIMessage, StopCondition } from 'ai';
+import { d as ChatStoreFactory } from './chat-store-Dq1Zy_qV.mjs';
+import { a as StorageAdapterFactory } from './storage-adapter-DD8uqiAP.mjs';
+
+/**
+ * Public configuration surface for `createChatHandler`.
+ *
+ * This is the API a host app touches to mount the chat backend. The design
+ * follows one rule, derived from auditing a real power-user integration
+ * (Jarvis): take away the shared, dangerous-to-get-wrong plumbing; keep every
+ * point of genuine per-app variation as an injection point or a hook.
+ *
+ * Three tiers of override, from "you must" to "you rarely will":
+ *
+ *   REQUIRED injections — no safe default exists:
+ *     • getUserId          (identity; the security boundary)
+ *
+ *   OPTIONAL injections — a default exists, swap to take control:
+ *     • model              (which LLM)
+ *     • buildTools         (your tools, incl. per-request resources)
+ *     • store              (persistence; hosted default)
+ *     • storage            (attachments; hosted default)
+ *
+ *   HOOKS — the loop runs fine without them; override one seam at a time:
+ *     • buildSystemPrompt, transformMessages, onChatFinish, onError,
+ *       stopWhen, upload
+ *
+ * Everything NOT in this file — ownership checks, idempotency, pagination,
+ * re-signing, socket teardown, save-on-finish — is owned by the handler and
+ * is intentionally not configurable, because getting it wrong is a security
+ * or correctness bug, not a preference.
+ */
+
+/**
+ * Everything a per-request hook/injection needs to know about the current
+ * request, assembled by the handler AFTER authentication. Passed to
+ * `buildTools`, `model` (when a function), `buildSystemPrompt`, and
+ * `transformMessages`.
+ *
+ * Note `userId` is the server-verified identity — the same value the store
+ * and storage are bound to. Hooks can trust it.
+ */
+interface ChatRequestContext {
+    /** Server-verified user id. Never client-supplied. */
+    userId: string;
+    /** The conversation this request targets. */
+    conversationId: string;
+    /** The raw request, for hooks that need headers/cookies (e.g. an org id). */
+    request: Request;
+}
+/**
+ * Per-agent declarative config returned by a hosted control plane. All fields
+ * optional — only what the dashboard has set is present; the rest falls through
+ * to code/defaults. `model` is a gateway model string (e.g. "anthropic/…").
+ */
+interface HostedAgentConfig {
+    model?: string | null;
+    systemPrompt?: string | null;
+    greeting?: string | null;
+    appearance?: Record<string, unknown> | null;
+}
+/**
+ * What `buildTools` returns. The `cleanup` callback is the critical piece the
+ * naive "just return a ToolSet" design misses: tools backed by a per-request
+ * resource (an MCP client holding a socket, a DB transaction, a temp scope)
+ * MUST be torn down after the stream finishes — exactly once, whether the
+ * stream completed, errored, or the client aborted. The handler guarantees
+ * that single, correctly-timed call so the host app never leaks sockets.
+ */
+interface BuiltTools {
+    tools: ToolSet;
+    /**
+     * Called exactly once when the request is fully done (success, error, or
+     * abort), after the response stream has settled. Optional — omit when your
+     * tools hold no per-request resource.
+     */
+    cleanup?: () => void | Promise<void>;
+}
+/**
+ * Server-side upload policy. Enforced by the handler's upload route BEFORE
+ * any bytes touch storage, so an oversized or disallowed file is rejected
+ * with a clean 4xx instead of a framework body-parse failure. The widget's
+ * client-side `accept`/`maxBytes` should mirror these, but the SERVER is the
+ * source of truth — the client checks are UX, these checks are the boundary.
+ */
+interface UploadPolicy {
+    /**
+     * Allowed MIME types. An exact-match allow-list (not a prefix match) so
+     * `image/svg+xml` can be excluded while `image/png` is allowed. Defaults to
+     * a conservative image+pdf set that current vision models accept natively.
+     */
+    allowedMediaTypes?: string[];
+    /** Per-file size cap in bytes. Defaults to 5 MB. */
+    maxBytes?: number;
+}
+interface CreateChatHandlerOptions {
+    /**
+     * Derive the authenticated user's id from the SERVER session — a verified
+     * cookie/JWT, Clerk `auth()`, NextAuth `getServerSession()`,
+     * `supabase.auth.getUser()`, etc. Return `null` for an unauthenticated
+     * request; the handler responds 401.
+     *
+     * SECURITY: never read the id from the request body, query string, or a
+     * header the browser controls (e.g. `X-User-Id`). Those are forgeable and
+     * doing so reintroduces the IDOR this whole design exists to prevent. The
+     * handler passes you the `Request` so you can read *verified* cookies — not
+     * so you can read a client-asserted id.
+     */
+    getUserId: (request: Request) => Promise<string | null> | string | null;
+    /**
+     * The model to stream from. Either a fixed `LanguageModel` or a function of
+     * the request context (for per-user/per-org model selection). Defaults to a
+     * sensible current model when omitted.
+     */
+    model?: LanguageModel | ((ctx: ChatRequestContext) => LanguageModel | Promise<LanguageModel>);
+    /**
+     * Build the tool set for this request. Async and context-aware so tools can
+     * close over the user and open per-request resources (e.g. an MCP client).
+     * Return `{ tools, cleanup }`; the handler calls `cleanup` exactly once when
+     * the request settles. Omit for a chat with no tools.
+     */
+    buildTools?: (ctx: ChatRequestContext) => Promise<BuiltTools> | BuiltTools;
+    /**
+     * Persistence backend. Omit to use the hosted/default store. Provide a
+     * factory to bring your own DB. The factory is called per request with the
+     * server-verified `userId`; the handler never constructs a store with a
+     * client-supplied id.
+     */
+    store?: ChatStoreFactory;
+    /**
+     * Attachment storage backend. Omit to use the hosted/default adapter.
+     * Provide a factory for BYO storage (S3/R2/own bucket). Same per-request,
+     * verified-userId construction as `store`.
+     */
+    storage?: StorageAdapterFactory;
+    /**
+     * Fetch per-agent declarative config (model / systemPrompt / greeting /
+     * appearance) from a hosted control plane (mordn's GET /v1/config). This is
+     * how dashboard-managed config reaches the loop WITHOUT a redeploy.
+     *
+     * Precedence is always **code > hosted > package default**: any `model` /
+     * `buildSystemPrompt` you pass here in code takes priority; the hosted value
+     * only fills what code leaves unset. Returning `null` (or throwing) falls
+     * through to code/defaults — a control-plane hiccup never breaks a turn.
+     *
+     * Use `createHostedConfig({ apiKey })` from `@mordn/chat-widget/server/hosted`
+     * to get a ready-made fetcher.
+     */
+    getHostedConfig?: (ctx: ChatRequestContext) => Promise<HostedAgentConfig | null> | HostedAgentConfig | null;
+    /**
+     * Produce the system prompt for this request. Receives the context so it
+     * can personalise (e.g. bake in the user's name). Defaults to a generic
+     * assistant prompt.
+     */
+    buildSystemPrompt?: (ctx: ChatRequestContext) => string | Promise<string>;
+    /**
+     * Last-chance transform of the model-ready messages before they're sent to
+     * the model — after the handler has applied its own sliding-window prune.
+     * Use for provider-specific rewrites (e.g. image file-parts → image-parts)
+     * or extra capping. Defaults to identity.
+     */
+    transformMessages?: (messages: ModelMessage[], ctx: ChatRequestContext) => ModelMessage[] | Promise<ModelMessage[]>;
+    /**
+     * Called after the assistant turn has been persisted. For telemetry/usage
+     * logging. NOT where you save messages — the handler already did that. Any
+     * error thrown here is logged and swallowed; it never fails the response
+     * (the user already has their answer).
+     */
+    onChatFinish?: (info: {
+        ctx: ChatRequestContext;
+        messages: UIMessage[];
+        usage?: unknown;
+        providerMetadata?: unknown;
+    }) => void | Promise<void>;
+    /**
+     * Map a stream error to the user-facing string the widget shows. Lets you
+     * downgrade benign post-finish teardown noise and localise messages.
+     * Defaults to a generic message + server-side error log.
+     */
+    onError?: (error: unknown) => string;
+    /**
+     * When the model may chain tool calls, how long to let it run before it
+     * must answer. Defaults to a bounded step count so a misbehaving tool loop
+     * can't run forever. Pass any AI SDK `StopCondition`.
+     */
+    stopWhen?: StopCondition<ToolSet>;
+    /** Server-side upload policy (types + size). See `UploadPolicy`. */
+    upload?: UploadPolicy;
+    /**
+     * How many of the most-recent messages to send to the model (sliding
+     * window). Defaults to 30. The handler always prunes; this tunes the
+     * window. Older messages stay in the store and in the UI — only the model
+     * payload is windowed.
+     */
+    maxHistoryMessages?: number;
+    /**
+     * Defensive per-message character cap applied during pruning so a single
+     * giant pasted blob can't dominate the context window. Defaults to 4000.
+     * Set to `0` to disable.
+     */
+    maxMessageChars?: number;
+}
+
+export type { BuiltTools as B, CreateChatHandlerOptions as C, HostedAgentConfig as H, UploadPolicy as U, ChatRequestContext as a };

package/dist/index.d.mts

@@ -344,11 +344,30 @@ interface ChatWidgetProps extends ChatWidgetConfig {
      */
     className?: string;
     /**
-     * Widget ID (for loading config from hosted service later)
+     * Agent ID — identifies which agent this widget talks to. Used to scope the
+     * browser cache to (agent, user) so the same browser never surfaces another
+     * agent's cached tabs/config, and (later) to load hosted per-agent config.
+     */
+    agentId?: string;
+    /**
+     * @deprecated Use `agentId`. Kept as an alias for one minor version.
      */
     widgetId?: string;
+    /**
+     * Base path the widget calls for chat / upload / history. Defaults to
+     * `/api/chat`. Override to mount the handler elsewhere (e.g. a dashboard
+     * preview at `/api/preview-chat/<agentId>`). The widget appends `/upload`
+     * and `/history` to this base.
+     */
+    apiBase?: string;
+    /**
+     * Extra headers sent on every chat request. Used by the dashboard playground
+     * to pass an unsaved draft (model / system prompt) for an owner-authed
+     * preview. Not for normal embeds.
+     */
+    extraHeaders?: Record<string, string>;
 }
-declare function ChatWidget({ userId, conversationId, initialMessages, className, model, systemPrompt, temperature, theme, features, display, starterPrompts, onClose, headerActions, open, onOpenChange, inputPlugins, toolRenderers, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
+declare function ChatWidget({ userId, agentId, apiBase, extraHeaders, widgetId, conversationId, initialMessages, className, model, systemPrompt, temperature, theme, features, display, starterPrompts, onClose, headerActions, open, onOpenChange, inputPlugins, toolRenderers, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
 
 interface ChatTheme {
     lightPrimary: string;
@@ -398,13 +417,33 @@ declare function useChatTheme(): {
 };
 
 interface ChatStorageContextValue {
-    storageKeyPrefix: string;
+    /**
+     * Prefix for all browser-stored chat keys, scoped to (agent, user):
+     * `${agentId}-${userId}`. `null` means we do NOT have a complete identity
+     * (missing agentId or userId) and callers MUST NOT persist anything — there
+     * is deliberately no shared/static fallback bucket, which previously let one
+     * user's cached chats leak to another on the same browser.
+     */
+    storageKeyPrefix: string | null;
 }
-declare function ChatStorageProvider({ children, userId, }: {
+declare function ChatStorageProvider({ children, userId, agentId, }: {
     children: ReactNode;
     userId?: string;
+    agentId?: string;
 }): react_jsx_runtime.JSX.Element;
 declare function useChatStorageKey(): ChatStorageContextValue;
+/**
+ * Remove chat data this widget persisted in localStorage. Call this on sign-out
+ * / user switch so a subsequent user on the same browser can never see the
+ * previous user's conversation tabs, titles, prompts, or model.
+ *
+ * - No args → clears EVERY `chat-*` key (safe blanket sign-out clear).
+ * - `{ agentId, userId }` → clears only that scope's keys (`chat-${agentId}-${userId}-*`).
+ */
+declare function clearChatStorage(opts?: {
+    agentId?: string;
+    userId?: string;
+}): void;
 
 declare const buttonVariants: (props?: ({
     variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
@@ -468,4 +507,4 @@ type ToolOutputProps = ComponentProps<"div"> & {
 };
 declare const ToolOutput: ({ className, output, errorText, ...props }: ToolOutputProps) => react_jsx_runtime.JSX.Element | null;
 
-export { Button, ChatStorageProvider, type ChatTheme, ChatWidget, type ChatWidgetConfig, type ChatWidgetProps, type ChatWidgetSize, type ConversationStarter, Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, type DisplayConfig, type FeatureConfig, Input, type InputPlugin, type InputPluginItem, StarterMessageItem, StarterMessages, type StarterPrompt, type ThemeConfig, type ThemeMode, Tool, ToolContent, ToolHeader, ToolInput, ToolOutput, type ToolPartLike, type ToolRenderer, ChatWidget as default, fontOptions, useChatStorageKey, useChatTheme };
+export { Button, ChatStorageProvider, type ChatTheme, ChatWidget, type ChatWidgetConfig, type ChatWidgetProps, type ChatWidgetSize, type ConversationStarter, Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, type DisplayConfig, type FeatureConfig, Input, type InputPlugin, type InputPluginItem, StarterMessageItem, StarterMessages, type StarterPrompt, type ThemeConfig, type ThemeMode, Tool, ToolContent, ToolHeader, ToolInput, ToolOutput, type ToolPartLike, type ToolRenderer, clearChatStorage, ChatWidget as default, fontOptions, useChatStorageKey, useChatTheme };

package/dist/index.d.ts

@@ -344,11 +344,30 @@ interface ChatWidgetProps extends ChatWidgetConfig {
      */
     className?: string;
     /**
-     * Widget ID (for loading config from hosted service later)
+     * Agent ID — identifies which agent this widget talks to. Used to scope the
+     * browser cache to (agent, user) so the same browser never surfaces another
+     * agent's cached tabs/config, and (later) to load hosted per-agent config.
+     */
+    agentId?: string;
+    /**
+     * @deprecated Use `agentId`. Kept as an alias for one minor version.
      */
     widgetId?: string;
+    /**
+     * Base path the widget calls for chat / upload / history. Defaults to
+     * `/api/chat`. Override to mount the handler elsewhere (e.g. a dashboard
+     * preview at `/api/preview-chat/<agentId>`). The widget appends `/upload`
+     * and `/history` to this base.
+     */
+    apiBase?: string;
+    /**
+     * Extra headers sent on every chat request. Used by the dashboard playground
+     * to pass an unsaved draft (model / system prompt) for an owner-authed
+     * preview. Not for normal embeds.
+     */
+    extraHeaders?: Record<string, string>;
 }
-declare function ChatWidget({ userId, conversationId, initialMessages, className, model, systemPrompt, temperature, theme, features, display, starterPrompts, onClose, headerActions, open, onOpenChange, inputPlugins, toolRenderers, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
+declare function ChatWidget({ userId, agentId, apiBase, extraHeaders, widgetId, conversationId, initialMessages, className, model, systemPrompt, temperature, theme, features, display, starterPrompts, onClose, headerActions, open, onOpenChange, inputPlugins, toolRenderers, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
 
 interface ChatTheme {
     lightPrimary: string;
@@ -398,13 +417,33 @@ declare function useChatTheme(): {
 };
 
 interface ChatStorageContextValue {
-    storageKeyPrefix: string;
+    /**
+     * Prefix for all browser-stored chat keys, scoped to (agent, user):
+     * `${agentId}-${userId}`. `null` means we do NOT have a complete identity
+     * (missing agentId or userId) and callers MUST NOT persist anything — there
+     * is deliberately no shared/static fallback bucket, which previously let one
+     * user's cached chats leak to another on the same browser.
+     */
+    storageKeyPrefix: string | null;
 }
-declare function ChatStorageProvider({ children, userId, }: {
+declare function ChatStorageProvider({ children, userId, agentId, }: {
     children: ReactNode;
     userId?: string;
+    agentId?: string;
 }): react_jsx_runtime.JSX.Element;
 declare function useChatStorageKey(): ChatStorageContextValue;
+/**
+ * Remove chat data this widget persisted in localStorage. Call this on sign-out
+ * / user switch so a subsequent user on the same browser can never see the
+ * previous user's conversation tabs, titles, prompts, or model.
+ *
+ * - No args → clears EVERY `chat-*` key (safe blanket sign-out clear).
+ * - `{ agentId, userId }` → clears only that scope's keys (`chat-${agentId}-${userId}-*`).
+ */
+declare function clearChatStorage(opts?: {
+    agentId?: string;
+    userId?: string;
+}): void;
 
 declare const buttonVariants: (props?: ({
     variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
@@ -468,4 +507,4 @@ type ToolOutputProps = ComponentProps<"div"> & {
 };
 declare const ToolOutput: ({ className, output, errorText, ...props }: ToolOutputProps) => react_jsx_runtime.JSX.Element | null;
 
-export { Button, ChatStorageProvider, type ChatTheme, ChatWidget, type ChatWidgetConfig, type ChatWidgetProps, type ChatWidgetSize, type ConversationStarter, Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, type DisplayConfig, type FeatureConfig, Input, type InputPlugin, type InputPluginItem, StarterMessageItem, StarterMessages, type StarterPrompt, type ThemeConfig, type ThemeMode, Tool, ToolContent, ToolHeader, ToolInput, ToolOutput, type ToolPartLike, type ToolRenderer, ChatWidget as default, fontOptions, useChatStorageKey, useChatTheme };
+export { Button, ChatStorageProvider, type ChatTheme, ChatWidget, type ChatWidgetConfig, type ChatWidgetProps, type ChatWidgetSize, type ConversationStarter, Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, type DisplayConfig, type FeatureConfig, Input, type InputPlugin, type InputPluginItem, StarterMessageItem, StarterMessages, type StarterPrompt, type ThemeConfig, type ThemeMode, Tool, ToolContent, ToolHeader, ToolInput, ToolOutput, type ToolPartLike, type ToolRenderer, clearChatStorage, ChatWidget as default, fontOptions, useChatStorageKey, useChatTheme };