@xpert-ai/chatkit-types 0.0.4 → 0.0.5

package/dist/index.d.ts

@@ -1,4 +1,226 @@
 import { ToolCall } from '@langchain/core/messages/tool';
+import { Types } from '@a2ui/lit/0.8';
+
+export declare type AccentColor = {
+    primary: string;
+    level: 0 | 1 | 2 | 3;
+};
+
+declare type ActionConfig = {
+    type: string;
+    payload?: Record<string, unknown>;
+};
+
+declare type Alignment = 'start' | 'center' | 'end' | 'baseline' | 'stretch';
+
+/**
+ * strategies to host files before attaching them to messages.
+ */
+/**
+ * Attachment associated with a user message. When passed to `sendUserMessage` or
+ * `setComposerValue`, it must already be uploaded by your server. We do not currently
+ * support attaching raw Files to a message.
+ */
+export declare type Attachment = {
+    type: 'file';
+    /** Server-generated identifier for the uploaded file. */
+    id: string;
+    /** Original filename shown in the UI. */
+    name: string;
+    /** MIME type of the file. */
+    mime_type: string;
+} | {
+    type: 'image';
+    /** Server-generated identifier for the uploaded image. */
+    id: string;
+    /** URL used to render the image preview in the UI. */
+    preview_url: string;
+    /** Original filename shown in the UI. */
+    name: string;
+    /** MIME type of the image. */
+    mime_type: string;
+};
+
+export declare type Badge = {
+    type: 'Badge';
+    key?: string;
+    id?: string;
+    label: string;
+    color?: 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'discovery';
+    variant?: 'solid' | 'soft' | 'outline';
+    size?: 'sm' | 'md' | 'lg';
+    pill?: boolean;
+};
+
+declare type BaseTextProps = {
+    value: string;
+    color?: string | ThemeColor;
+    weight?: 'normal' | 'medium' | 'semibold' | 'bold';
+    textAlign?: TextAlign;
+    truncate?: boolean;
+    maxLines?: number;
+};
+
+export declare type BasicRoot = {
+    type: 'Basic';
+    key?: string;
+    id?: string;
+    children: (WidgetComponent | WidgetRoot)[];
+    theme?: 'light' | 'dark';
+    direction?: 'row' | 'col';
+} & Pick<BoxBaseProps, 'gap' | 'padding' | 'align' | 'justify'>;
+
+declare type BlockProps = {
+    height?: number | string;
+    width?: number | string;
+    size?: number | string;
+    minHeight?: number | string;
+    minWidth?: number | string;
+    minSize?: number | string;
+    maxHeight?: number | string;
+    maxWidth?: number | string;
+    maxSize?: number | string;
+    aspectRatio?: number | string;
+    radius?: RadiusValue;
+    margin?: number | string | Spacing;
+};
+
+declare type Border = {
+    size: number;
+    color?: string | ThemeColor;
+    style?: 'solid' | 'dashed' | 'dotted' | 'double' | 'groove' | 'ridge' | 'inset' | 'outset';
+};
+
+declare type Borders = {
+    top?: number | Border;
+    right?: number | Border;
+    bottom?: number | Border;
+    left?: number | Border;
+    x?: number | Border;
+    y?: number | Border;
+};
+
+export declare type Box = {
+    type: 'Box';
+    key?: string;
+    id?: string;
+    direction?: 'row' | 'col';
+} & BoxBaseProps;
+
+declare type BoxBaseProps = {
+    children?: WidgetComponent[];
+    align?: Alignment;
+    justify?: Justification;
+    wrap?: 'nowrap' | 'wrap' | 'wrap-reverse';
+    flex?: number | string;
+    gap?: number | string;
+    padding?: number | string | Spacing;
+    border?: number | Border | Borders;
+    background?: string | ThemeColor;
+} & BlockProps;
+
+export declare type Button = {
+    type: 'Button';
+    key?: string;
+    id?: string;
+    submit?: boolean;
+    label?: string;
+    onClickAction?: ActionConfig;
+    iconStart?: WidgetIcon;
+    iconEnd?: WidgetIcon;
+    style?: 'primary' | 'secondary';
+    iconSize?: 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+    color?: 'primary' | 'secondary' | 'info' | 'discovery' | 'success' | 'caution' | 'warning' | 'danger';
+    variant?: ControlVariant;
+    size?: ControlSize;
+    pill?: boolean;
+    uniform?: boolean;
+    block?: boolean;
+    disabled?: boolean;
+};
+
+export declare type Caption = {
+    type: 'Caption';
+    key?: string;
+    id?: string;
+    size?: CaptionSize;
+} & BaseTextProps;
+
+declare type CaptionSize = 'sm' | 'md' | 'lg';
+
+export declare type Card = {
+    type: 'Card';
+    key?: string;
+    id?: string;
+    asForm?: boolean;
+    children: WidgetComponent[];
+    background?: string | ThemeColor;
+    size?: 'sm' | 'md' | 'lg' | 'full';
+    padding?: number | string | Spacing;
+    status?: WidgetStatus;
+    collapsed?: boolean;
+    confirm?: CardAction;
+    cancel?: CardAction;
+    theme?: 'light' | 'dark';
+};
+
+declare type CardAction = {
+    label: string;
+    action: ActionConfig;
+};
+
+export declare interface ChatKitElementEventMap {
+    'chatkit.error': CustomEvent<{
+        error: Error;
+    }>;
+    'chatkit.response.start': CustomEvent<void>;
+    'chatkit.response.end': CustomEvent<void>;
+    'chatkit.thread.change': CustomEvent<{
+        threadId: string | null;
+    }>;
+    'chatkit.log': CustomEvent<{
+        name: string;
+        data?: Record<string, unknown>;
+    }>;
+}
+
+/**
+ * DOM events emitted by the `xpertai-chatkit` custom element.
+ */
+export declare type ChatKitEvents = {
+    /** Emitted when the ChatKit frame has loaded. */
+    'chatkit.ready': CustomEvent<void>;
+    /** Emitted when an error occurs. You should log these for monitoring and debugging. */
+    'chatkit.error': CustomEvent<{
+        error: Error;
+    }>;
+    /** Emitted when a fire-and-forget client effect is triggered. */
+    'chatkit.effect': CustomEvent<{
+        name: string;
+        data?: Record<string, unknown>;
+    }>;
+    /** Emitted when the assistant begins sending a response. */
+    'chatkit.response.start': CustomEvent<void>;
+    /** Emitted when the assistant finishes sending a response. */
+    'chatkit.response.end': CustomEvent<void>;
+    /** Emitted when the active thread changes. Use this along with `initialThread` to persist the current thread across page loads or sessions. */
+    'chatkit.thread.change': CustomEvent<{
+        threadId: string | null;
+    }>;
+    /** Emitted when ChatKit starts loading a thread (initial load or selected from history). */
+    'chatkit.thread.load.start': CustomEvent<{
+        threadId: string;
+    }>;
+    /** Emitted when ChatKit finished loading a thread. */
+    'chatkit.thread.load.end': CustomEvent<{
+        threadId: string;
+    }>;
+    /** Diagnostic events that can be used for logging/analytics. */
+    'chatkit.log': CustomEvent<{
+        name: string;
+        data?: Record<string, unknown>;
+    }>;
+};
 
 export declare interface ChatkitMessage {
     status?: string;
@@ -8,6 +230,226 @@ export declare interface ChatkitMessage {
     id: string;
 }
 
+export declare type ChatKitOptions = {
+    api: CustomApiConfig | HostedApiConfig;
+    /**
+     * Locale override for ChatKit UI. If not provided, the browser's locale
+     * will be used. If the locale is not supported, will fall back to English.
+     *
+     * @default navigator.language
+     */
+    locale?: SupportedLocale;
+    /**
+     * Visual appearance configuration options for ChatKit.
+     * * @default "light"
+     */
+    theme?: ColorScheme | ChatKitTheme;
+    /**
+     * The ID of the thread to show when ChatKit is mounted or opened for the first time.
+     * Passing `null` will show the new thread view.
+     *
+     * @default null
+     */
+    initialThread?: null | string;
+    /**
+     * A map of handlers for the client tools configured on your server. The keys
+     * are the names of the client tools, and the values are functions that
+     * will be called when the client tool is invoked. The object (or promise) returned
+     * from the function will be sent back to the server as the result of the client
+     * tool invocation.
+     */
+    onClientTool?: ({ name, params, id, tool_call_id, }: {
+        name: string;
+        params: Record<string, unknown>;
+        id?: string;
+        tool_call_id?: string;
+    }) => Promise<ClientToolMessageInput> | ClientToolMessageInput;
+    /**
+     * Whether to show the header in ChatKit. A configuration object can be
+     * provided to customize the header.
+     */
+    header?: {
+        enabled?: boolean;
+        /**
+         * Configuration for header title display, which defaults to showing thread titles.
+         */
+        title?: {
+            /**
+             * @default true
+             */
+            enabled?: boolean;
+            /**
+             * Static text to show in the header title area. When not provided, the
+             * title of the current thread will be shown instead.
+             */
+            text?: string;
+        };
+        /**
+         * Configuration for an additional custom button on the left side of the header.
+         */
+        leftAction?: {
+            icon: HeaderIcon;
+            onClick: () => void;
+        };
+        /**
+         * Configuration for an additional custom button on the right side of the header.
+         */
+        rightAction?: {
+            icon: HeaderIcon;
+            onClick: () => void;
+        };
+    };
+    history?: {
+        enabled?: boolean;
+        showDelete?: boolean;
+        showRename?: boolean;
+    };
+    startScreen?: {
+        /**
+         * The greeting text in the new thread view.
+         *
+         * @default "What can I help with today?"
+         */
+        greeting?: string;
+        /**
+         * A list of starter prompts to show above the composer input when in the new thread view.
+         */
+        prompts?: StartScreenPrompt[];
+    };
+    threadItemActions?: {
+        /**
+         * Whether or not to show the response feedback buttons (thumbs up / thumbs
+         * down) in the response view. When the user clicks on one of the buttons, the
+         * feedback will be sent to your server where you can handle it.
+         * @default false
+         */
+        feedback?: boolean;
+        /**
+         * Whether or not to show the retry button in the response view.
+         * When the user retries a message, server events will be sent to handle
+         * removing thread items and begin generation.
+         * @default false
+         */
+        retry?: boolean;
+        /**
+         * Whether or not to show the share button in the response view.
+         * When the user clicks on one of the buttons, the "message.share" event
+         * will be emitted with the shared content, item ids, and thread id.
+         * @default false
+         */
+        share?: boolean;
+    };
+    composer?: {
+        /**
+         * The placeholder text to show in the composer input.
+         * @default "Message the AI"
+         */
+        placeholder?: string;
+        attachments?: {
+            /**
+             * Whether file attachments are enabled in the composer.
+             *
+             * @default false
+             */
+            enabled: boolean;
+            /**
+             * The maximum size of an attachment in bytes.
+             *
+             * @default 100 * 1024 * 1024 (100MB)
+             */
+            maxSize?: number;
+            /**
+             * The maximum number of attachments that can be sent in a single message.
+             *
+             * @default 10
+             */
+            maxCount?: number;
+            /**
+             *
+             * The MIME types and extensions that are accepted for file uploads,
+             * similar to [`showOpenFilePicker`]. When not specified, all MIME types
+             * and extensions are accepted.
+             *
+             * [`showOpenFilePicker`]:
+             * https://developer.mozilla.org/en-US/docs/Web/API/Window/showOpenFilePicker#accept
+             */
+            accept?: Record<string, string[]>;
+        };
+        /**
+         * When provided a list of tool options, the user will be able to select a tool
+         * from a menu in the composer.
+         */
+        tools?: ToolOption[];
+        /** A list of models that users can choose from before sending a message. */
+        models?: ModelOption[];
+    };
+    /**
+     * Disclaimer text to display below the composer. Supports links with markdown formatting.
+     */
+    disclaimer?: {
+        text: string;
+        highContrast?: boolean;
+    };
+    entities?: {
+        /**
+         * Returns a list of entities for the input query.
+         * Powers tag autocomplete within the composer.
+         */
+        onTagSearch?: (query: string) => Promise<Entity[]>;
+        onClick?: (entity: Entity) => void;
+        onRequestPreview?: (entity: Entity) => Promise<{
+            preview: Widgets.BasicRoot | null;
+        }>;
+    };
+    widgets?: {
+        onAction?: (action: {
+            type: string;
+            payload?: Record<string, unknown>;
+        }, widgetItem: {
+            id: string;
+            widget: Widgets.Card | Widgets.ListView;
+        }) => Promise<void>;
+    };
+};
+
+export declare type ChatKitTheme = {
+    /**
+     * The color scheme to use for the ChatKit UI.
+     * @default "light"
+     */
+    colorScheme?: ColorScheme;
+    /**
+     * Typography
+     */
+    typography?: {
+        /**
+         * Base font size in pixels.
+         * @remarks Allowed range: 14-18
+         */
+        baseSize?: 14 | 15 | 16 | 17 | 18;
+        fontSources?: FontObject[];
+        fontFamily?: string;
+        fontFamilyMono?: string;
+    };
+    /**
+     * Determines the overall roundness of the ChatKit UI
+     */
+    radius?: 'pill' | 'round' | 'soft' | 'sharp';
+    /**
+     * Determines the overall spacing of the ChatKit UI
+     * @default "normal"
+     */
+    density?: 'compact' | 'normal' | 'spacious';
+    /**
+     * Color customization options
+     */
+    color?: {
+        grayscale?: GrayscaleOptions;
+        accent?: AccentColor;
+        surface?: SurfaceColors;
+    };
+};
+
 /**
  * https://js.langchain.com/docs/how_to/streaming/#event-reference
  */
@@ -30,7 +472,8 @@ export declare enum ChatMessageEventTypeEnum {
     ON_RETRIEVER_ERROR = "on_retriever_error",
     ON_INTERRUPT = "on_interrupt",
     ON_ERROR = "on_error",
-    ON_CHAT_EVENT = "on_chat_event"
+    ON_CHAT_EVENT = "on_chat_event",
+    ON_CLIENT_EFFECT = "on_client_effect"
 }
 
 /**
@@ -74,6 +517,18 @@ export declare enum ChatMessageTypeEnum {
     EVENT = "event"
 }
 
+export declare type Checkbox = {
+    type: 'Checkbox';
+    key?: string;
+    id?: string;
+    name: string;
+    label?: string;
+    defaultChecked?: boolean;
+    onChangeAction?: ActionConfig;
+    disabled?: boolean;
+    required?: boolean;
+};
+
 export declare interface ClientToolMessageInput {
     content: unknown;
     name?: string;
@@ -90,8 +545,219 @@ export declare interface ClientToolResponse {
     toolMessages: ClientToolMessageInput[];
 }
 
+export declare interface ClientTools {
+}
+
+export declare type Col = {
+    type: 'Col';
+    key?: string;
+    id?: string;
+} & BoxBaseProps;
+
+export declare type ColorScheme = 'light' | 'dark';
+
+declare type ControlSize = '3xs' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+
+declare type ControlVariant = 'solid' | 'soft' | 'outline' | 'ghost';
+
+declare type CustomApiConfig = {
+    /**
+     * The URL (relative or absolute) of the ChatKit API. The configured endpoint
+     * must conform to the specification defined in the ChatKit SDK documentation.
+     * The easiest way to get started is by using the ChatKit SDK which will help
+     * you define your integration in a declarative way.
+     */
+    url: string;
+    /**
+     * Custom fetch function to use for API requests. This is useful for
+     * overriding the default fetch behavior, such as adding custom headers or
+     * setting credentials.
+     */
+    fetch?: typeof fetch;
+    /**
+     * The domain key that will be used to verify the registered domain
+     * for the integration.
+     */
+    domainKey: string;
+    /**
+     * How attachments will be uploaded to your server. Required when attachments are enabled.
+     */
+    uploadStrategy?: FileUploadStrategy;
+};
+
+export declare type DatePicker = {
+    type: 'DatePicker';
+    key?: string;
+    id?: string;
+    name: string;
+    onChangeAction?: ActionConfig;
+    placeholder?: string;
+    defaultValue?: string;
+    min?: string;
+    max?: string;
+    variant?: ControlVariant;
+    size?: ControlSize;
+    side?: 'top' | 'bottom' | 'left' | 'right';
+    align?: 'start' | 'center' | 'end';
+    pill?: boolean;
+    block?: boolean;
+    clearable?: boolean;
+    disabled?: boolean;
+};
+
+export declare type Divider = {
+    type: 'Divider';
+    key?: string;
+    id?: string;
+    color?: string | ThemeColor;
+    size?: number | string;
+    spacing?: number | string;
+    flush?: boolean;
+};
+
+/**
+ * A structured object representing a referenceable item such as a
+ * person, document, or internal business object.
+ */
+export declare type Entity = {
+    /**
+     * Human-readable name shown in tags, sources, previews, etc.
+     * e.g. "Harry Potter", "Claim #A-1023", "Q2 Planning Doc"
+     */
+    title: string;
+    id: string;
+    /**
+     * Optional icon to show when rendering the entity.
+     */
+    icon?: string;
+    /**
+     * Whether the entity is interactive can be clicked or previewed.
+     */
+    interactive?: boolean;
+    /**
+     * Optional human-readable group name to group entities by.
+     * e.g. "People", "Documents"
+     */
+    group?: string;
+    /**
+     * Optional metadata that will be proxied to the server if this entity is part of
+     * a submitted user message (e.g. in tags) or for client entity callbacks (e.g. for
+     * click or preview). This is not directly used in ChatKit.js and can contain
+     * arbitrary metadata.
+     */
+    data?: Record<string, string>;
+};
+
+export declare type EventHandler<K extends keyof ChatKitEvents> = (event: ChatKitEvents[K]) => any;
+
+export declare type FileUploadStrategy = {
+    type: 'two_phase';
+} | {
+    type: 'direct';
+    uploadUrl: string;
+};
+
+/**
+ * 从 Playground 复制的配置中过滤出允许的配置项
+ *
+ * @param options - 从 playground 复制的完整配置
+ * @returns 只包含白名单配置项的对象
+ *
+ * @example
+ * ```ts
+ * // 从 playground 复制的配置
+ * const playgroundConfig = {
+ *   theme: { colorScheme: 'light', radius: 'pill' },
+ *   threadItemActions: { feedback: true }, // 会被过滤掉
+ *   startScreen: { greeting: 'Hello!' },
+ * };
+ *
+ * const filtered = filterPlaygroundOptions(playgroundConfig);
+ * // 结果: { theme: { colorScheme: 'light', radius: 'pill' }, startScreen: { greeting: 'Hello!' } }
+ * ```
+ */
+export declare function filterPlaygroundOptions<T extends Partial<ChatKitOptions>>(options: T): PlaygroundAllowedOptions;
+
+export declare type FontObject = {
+    family: string;
+    src: string;
+    weight?: string | number;
+    style?: 'normal' | 'italic' | 'oblique';
+    display?: 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
+    unicodeRange?: string;
+};
+
+export declare type Form = {
+    type: 'Form';
+    key?: string;
+    id?: string;
+    onSubmitAction?: ActionConfig;
+    direction?: 'row' | 'col';
+} & BoxBaseProps;
+
+export declare type GrayscaleOptions = {
+    hue: number;
+    tint: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+    shade?: -4 | -3 | -2 | -1 | 0 | 1 | 2 | 3 | 4;
+};
+
+export declare type HeaderIcon = 'sidebar-left' | 'sidebar-right' | 'sidebar-open-left' | 'sidebar-open-right' | 'sidebar-open-left-alt' | 'sidebar-open-right-alt' | 'sidebar-floating-left' | 'sidebar-floating-right' | 'sidebar-floating-open-left' | 'sidebar-floating-open-right' | 'sidebar-collapse-left' | 'sidebar-collapse-right' | 'collapse-left' | 'collapse-right' | 'open-left' | 'open-right' | 'double-chevron-left' | 'double-chevron-right' | 'home' | 'home-alt' | 'back-small' | 'back-large' | 'expand-large' | 'collapse-large' | 'expand-small' | 'collapse-small' | 'star' | 'star-filled' | 'chat-temporary' | 'settings-cog' | 'grid' | 'dots-horizontal' | 'dots-vertical' | 'dots-horizontal-circle' | 'dots-vertical-circle' | 'menu' | 'menu-inverted' | 'hamburger' | 'compose' | 'light-mode' | 'dark-mode' | 'close';
+
+declare type HostedApiConfig = {
+    /**
+     * Function to get a client token or refresh if the current token is expired.
+     */
+    getClientSecret: (currentClientSecret: string | null) => Promise<string>;
+};
+
+export declare type Icon = {
+    type: 'Icon';
+    key?: string;
+    id?: string;
+    name: WidgetIcon;
+    color?: string | ThemeColor;
+    size?: IconSize;
+};
+
+export declare type IconName = 'agent' | 'analytics' | 'atom' | 'batch' | 'bolt' | 'book-open' | 'book-closed' | 'bug' | 'calendar' | 'chart' | 'circle-question' | 'compass' | 'cube' | 'globe' | 'keys' | 'lab' | 'images' | 'lifesaver' | 'lightbulb' | 'map-pin' | 'name' | 'notebook' | 'notebook-pencil' | 'page-blank' | 'profile' | 'profile-card' | 'search' | 'sparkle' | 'sparkle-double' | 'square-code' | 'square-image' | 'square-text' | 'suitcase' | 'write' | 'write-alt' | 'write-alt2';
+
+declare type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+
+declare type Image_2 = {
+    type: 'Image';
+    key?: string;
+    id?: string;
+    src: string;
+    alt?: string;
+    frame?: boolean;
+    fit?: 'cover' | 'contain' | 'fill' | 'scale-down' | 'none';
+    position?: 'top left' | 'top' | 'top right' | 'left' | 'center' | 'right' | 'bottom left' | 'bottom' | 'bottom right';
+    flush?: boolean;
+} & BlockProps;
+export { Image_2 as Image }
+
 export declare type ImageDetail = "auto" | "low" | "high";
 
+export declare type Input = {
+    type: 'Input';
+    key?: string;
+    id?: string;
+    name: string;
+    inputType?: 'number' | 'email' | 'text' | 'password' | 'tel' | 'url';
+    defaultValue?: string;
+    required?: boolean;
+    pattern?: string;
+    placeholder?: string;
+    allowAutofillExtensions?: boolean;
+    autoSelect?: boolean;
+    autoFocus?: boolean;
+    disabled?: boolean;
+    variant?: 'soft' | 'outline';
+    size?: ControlSize;
+    gutterSize?: '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    pill?: boolean;
+};
+
 /**
  * When an interrupt occurs during task execution, the system generates an InterruptPayload.
  ```json
@@ -141,6 +807,75 @@ export declare interface InterruptPayload {
 
 export declare function isClientToolRequest(value: any): value is ClientToolRequest;
 
+declare type Justification = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' | 'stretch';
+
+export declare type Label = {
+    type: 'Label';
+    key?: string;
+    id?: string;
+    value: string;
+    fieldName: string;
+    size?: TextSize;
+    weight?: 'normal' | 'medium' | 'semibold' | 'bold';
+    textAlign?: TextAlign;
+    color?: string | ThemeColor;
+};
+
+export declare type ListView = {
+    type: 'ListView';
+    key?: string;
+    id?: string;
+    children: ListViewItem[];
+    limit?: number | 'auto';
+    status?: WidgetStatus;
+    theme?: 'light' | 'dark';
+};
+
+export declare type ListViewItem = {
+    type: 'ListViewItem';
+    key?: string;
+    id?: string;
+    children: WidgetComponent[];
+    onClickAction?: ActionConfig;
+    gap?: number | string;
+    align?: Alignment;
+};
+
+export declare type Markdown = {
+    type: 'Markdown';
+    key?: string;
+    id?: string;
+    value: string;
+    streaming?: boolean;
+};
+
+/**
+ * 合并 Playground 配置与本地配置
+ * Playground 配置会覆盖本地配置中的对应项（只限白名单内的配置）
+ *
+ * @param localOptions - 本地项目中的基础配置（可包含 onClientTool, header 等）
+ * @param playgroundOptions - 从 playground 复制的配置
+ * @returns 合并后的配置
+ *
+ * @example
+ * ```ts
+ * const localConfig = {
+ *   api: { getClientSecret: async () => '...' },
+ *   onClientTool: async () => { ... },  // 保留
+ *   header: { enabled: true },           // 保留
+ * };
+ *
+ * const playgroundConfig = {
+ *   theme: { colorScheme: 'dark' },
+ *   threadItemActions: { feedback: true }, // 被过滤
+ * };
+ *
+ * const merged = mergeWithPlaygroundOptions(localConfig, playgroundConfig);
+ * // 结果: { api, onClientTool, header, theme }
+ * ```
+ */
+export declare function mergeWithPlaygroundOptions<T extends Partial<ChatKitOptions>>(localOptions: T, playgroundOptions: Partial<ChatKitOptions>): T & PlaygroundAllowedOptions;
+
 export declare type MessageContentImageUrl = {
     type: "image_url";
     image_url: string | {
@@ -154,6 +889,114 @@ export declare type MessageContentText = {
     text: string;
 };
 
+export declare type ModelOption = {
+    /** Identifier used when submitting a message. */
+    id: string;
+    /** Label displayed in the model picker. */
+    label: string;
+    /** Optional helper text shown with the option. */
+    description?: string;
+    /** When true the option is visible but cannot be selected. */
+    disabled?: boolean;
+    /** Determines if the model should be the default selected option. */
+    default?: boolean;
+};
+
+/**
+ * Playground 配置白名单 - 只允许这些配置项从 playground 复制过来生效
+ * 过滤掉: locale, initialThread, header, history, threadItemActions, disclaimer, entities, widgets, onClientTool
+ */
+/**
+ * 允许从 Playground 配置的选项类型
+ */
+export declare type PlaygroundAllowedOptions = {
+    api?: ChatKitOptions['api'];
+    theme?: ColorScheme | ChatKitTheme;
+    composer?: ChatKitOptions['composer'];
+    startScreen?: ChatKitOptions['startScreen'];
+};
+
+export declare type RadioGroup = {
+    type: 'RadioGroup';
+    key?: string;
+    id?: string;
+    name: string;
+    options?: {
+        label: string;
+        value: string;
+        disabled?: boolean;
+    }[];
+    ariaLabel?: string;
+    onChangeAction?: ActionConfig;
+    defaultValue?: string;
+    direction?: 'row' | 'col';
+    disabled?: boolean;
+    required?: boolean;
+};
+
+declare type RadiusValue = '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | 'full' | '100%' | 'none';
+
+export declare type Row = {
+    type: 'Row';
+    key?: string;
+    id?: string;
+} & BoxBaseProps;
+
+export declare type Select = {
+    type: 'Select';
+    key?: string;
+    id?: string;
+    name: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    onChangeAction?: ActionConfig;
+    placeholder?: string;
+    defaultValue?: string;
+    variant?: ControlVariant;
+    size?: ControlSize;
+    pill?: boolean;
+    block?: boolean;
+    clearable?: boolean;
+    disabled?: boolean;
+};
+
+export declare type Spacer = {
+    type: 'Spacer';
+    key?: string;
+    id?: string;
+    minSize?: number | string;
+};
+
+declare type Spacing = {
+    top?: number | string;
+    right?: number | string;
+    bottom?: number | string;
+    left?: number | string;
+    x?: number | string;
+    y?: number | string;
+};
+
+export declare type StartScreenPrompt = {
+    label: string;
+    prompt: string;
+    icon?: IconName;
+};
+
+export declare const STATE_VARIABLE_HUMAN = "human";
+
+/**
+ * All locales that are accepted by ChatKit without falling back to English.
+ * Includes language codes that are resolved by ChatKit to a translated locale.
+ */
+export declare type SupportedLocale = TranslatedLocale | 'bg' | 'bn' | 'bs' | 'ca' | 'cs' | 'da' | 'de' | 'el' | 'es' | 'et' | 'fi' | 'fr' | 'gu' | 'hi' | 'hr' | 'hu' | 'hy' | 'id' | 'is' | 'it' | 'ja' | 'ka' | 'kn' | 'ko' | 'lv' | 'mk' | 'mr' | 'ms' | 'my' | 'nb' | 'nl' | 'pl' | 'pt' | 'ro' | 'ru' | 'sk' | 'sl' | 'so' | 'sq' | 'sr' | 'sv' | 'sw' | 'ta' | 'te' | 'th' | 'tr' | 'uk' | 'vi' | 'zh' | 'zh-Hant' | 'en';
+
+export declare type SurfaceColors = {
+    background: string;
+    foreground: string;
+};
+
 /**
  * Data type for chat event message
  */
@@ -172,6 +1015,120 @@ export declare type TChatEventMessage = {
  */
 export declare type TChatMessageStep<T = any> = TMessageComponent<TMessageComponentStep<T>>;
 
+export declare type TChatRequest = {
+    /**
+     * The human input, include parameters
+     */
+    input: TChatRequestHuman;
+    /**
+     * Custom graph state
+     */
+    state?: {
+        [STATE_VARIABLE_HUMAN]: TChatRequestHuman;
+    } & Record<string, any>;
+    agentKey?: string;
+    projectId?: string;
+    conversationId?: string;
+    environmentId?: string;
+    id?: string;
+    executionId?: string;
+    confirm?: boolean;
+    command?: TInterruptCommand;
+    retry?: boolean;
+};
+
+/**
+ * Human input message, include parameters and attachments
+ */
+export declare type TChatRequestHuman = {
+    input?: string;
+    files?: Partial<File>[];
+    [key: string]: unknown;
+};
+
+/**
+ * Data type for client effect message
+ */
+export declare type TClientEeffectMessage = {
+    name: string;
+    args: Record<string, any>;
+    tool_call_id?: string;
+    agentKey?: string;
+    created_date?: Date | string;
+};
+
+declare type TextAlign = 'start' | 'center' | 'end';
+
+export declare type Textarea = {
+    type: 'Textarea';
+    key?: string;
+    id?: string;
+    name: string;
+    defaultValue?: string;
+    required?: boolean;
+    pattern?: string;
+    placeholder?: string;
+    autoSelect?: boolean;
+    autoFocus?: boolean;
+    disabled?: boolean;
+    variant?: 'soft' | 'outline';
+    size?: ControlSize;
+    gutterSize?: '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    rows?: number;
+    autoResize?: boolean;
+    maxRows?: number;
+    allowAutofillExtensions?: boolean;
+};
+
+export declare type TextComponent = {
+    type: 'Text';
+    key?: string;
+    id?: string;
+    value: string;
+    streaming?: boolean;
+    italic?: boolean;
+    lineThrough?: boolean;
+    width?: number | string;
+    size?: TextSize;
+    minLines?: number;
+    editable?: false | {
+        name: string;
+        autoFocus?: boolean;
+        autoSelect?: boolean;
+        autoComplete?: string;
+        allowAutofillExtensions?: boolean;
+        pattern?: string;
+        placeholder?: string;
+        required?: boolean;
+    };
+} & BaseTextProps;
+
+declare type TextSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+declare type ThemeColor = {
+    dark: string;
+    light: string;
+};
+
+/**
+ * Command to resume with streaming after human decision
+ */
+export declare type TInterruptCommand = {
+    resume?: any;
+    update?: any;
+    toolCalls?: ToolCall[];
+    agentKey?: string;
+};
+
+export declare type Title = {
+    type: 'Title';
+    key?: string;
+    id?: string;
+    size?: TitleSize;
+} & BaseTextProps;
+
+declare type TitleSize = 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl';
+
 /**
  * Defines the data type of the sub-message of `component` type in the message `content` {@link MessageContentComplex}
  */
@@ -208,6 +1165,21 @@ export declare type TMessageComponentStep<T = unknown> = {
     artifact?: any;
 };
 
+export declare type TMessageComponentWidget = TMessageComponent<TMessageComponentWidgetData>;
+
+export declare type TMessageComponentWidgetData = {
+    type: 'Widget';
+    mode?: string;
+    widgets: TMessageComponentWidgetItem[];
+    executionId?: string;
+};
+
+export declare type TMessageComponentWidgetItem = {
+    name: string;
+    config: Types.Surface;
+    values?: Record<string, unknown>;
+};
+
 /**
  * Enhance {@link MessageContent} in Langchain.js
  *
@@ -263,6 +1235,206 @@ export declare type TMessageContentText = {
     text: string;
 };
 
+export declare type TMessageContentWidget = TMessageContentComponent<TMessageComponentWidgetData>;
+
 export declare type TMessageItems = TMessageContentComplex[];
 
+export declare type ToolOption = {
+    id: string;
+    /** Label displayed in the tool menu */
+    label: string;
+    /** Label displayed in the button when the tool is selected. */
+    shortLabel?: string;
+    /** Placeholder text to show in the composer input when the tool is selected. */
+    placeholderOverride?: string;
+    /**
+     * Icon displayed next to the tool in the menu.
+     */
+    icon: IconName;
+    /**
+     * Whether the tool is pinned to the composer outside of the tool menu.
+     *
+     * @default false
+     */
+    pinned?: boolean;
+};
+
+export declare type Transition = {
+    type: 'Transition';
+    key?: string;
+    id?: string;
+    children: WidgetComponent;
+};
+
+/**
+ * All locales for which there is an actual translation file.
+ */
+export declare type TranslatedLocale = 'am' | 'ar' | 'bg-BG' | 'bn-BD' | 'bs-BA' | 'ca-ES' | 'cs-CZ' | 'da-DK' | 'de-DE' | 'el-GR' | 'es-419' | 'es-ES' | 'et-EE' | 'fi-FI' | 'fr-CA' | 'fr-FR' | 'gu-IN' | 'hi-IN' | 'hr-HR' | 'hu-HU' | 'hy-AM' | 'id-ID' | 'is-IS' | 'it-IT' | 'ja-JP' | 'ka-GE' | 'kk' | 'kn-IN' | 'ko-KR' | 'lt' | 'lv-LV' | 'mk-MK' | 'ml' | 'mn' | 'mr-IN' | 'ms-MY' | 'my-MM' | 'nb-NO' | 'nl-NL' | 'pa' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ro-RO' | 'ru-RU' | 'sk-SK' | 'sl-SI' | 'so-SO' | 'sq-AL' | 'sr-RS' | 'sv-SE' | 'sw-TZ' | 'ta-IN' | 'te-IN' | 'th-TH' | 'tl' | 'tr-TR' | 'uk-UA' | 'ur' | 'vi-VN' | 'zh-CN' | 'zh-HK' | 'zh-TW';
+
+export declare type WidgetComponent = TextComponent | Title | Caption | Badge | Markdown | Box | Row | Col | Divider | Icon | Image_2 | Button | Checkbox | Spacer | Select | DatePicker | Form | Input | Label | RadioGroup | Textarea | Transition;
+
+export declare type WidgetIcon = 'agent' | 'analytics' | 'atom' | 'batch' | 'bolt' | 'book-open' | 'book-closed' | 'book-clock' | 'bug' | 'calendar' | 'chart' | 'check' | 'check-circle' | 'check-circle-filled' | 'chevron-left' | 'chevron-right' | 'circle-question' | 'compass' | 'confetti' | 'cube' | 'desktop' | 'document' | 'dot' | 'dots-horizontal' | 'dots-vertical' | 'empty-circle' | 'external-link' | 'globe' | 'keys' | 'lab' | 'images' | 'info' | 'lifesaver' | 'lightbulb' | 'mail' | 'map-pin' | 'maps' | 'mobile' | 'name' | 'notebook' | 'notebook-pencil' | 'page-blank' | 'phone' | 'play' | 'plus' | 'profile' | 'profile-card' | 'reload' | 'star' | 'star-filled' | 'search' | 'sparkle' | 'sparkle-double' | 'square-code' | 'square-image' | 'square-text' | 'suitcase' | 'settings-slider' | 'user' | 'wreath' | 'write' | 'write-alt' | 'write-alt2';
+
+export declare type WidgetRoot = Card | ListView | BasicRoot;
+
+declare namespace Widgets {
+    export {
+        WidgetRoot,
+        WidgetComponent,
+        BasicRoot,
+        Card,
+        ListView,
+        ListViewItem,
+        Box,
+        Row,
+        Col,
+        Form,
+        Spacer,
+        Divider,
+        Transition,
+        Title,
+        Caption,
+        TextComponent,
+        Markdown,
+        Badge,
+        Icon,
+        Image_2 as Image,
+        Button,
+        Input,
+        Textarea,
+        Select,
+        DatePicker,
+        Checkbox,
+        RadioGroup,
+        Label,
+        WidgetIcon
+    }
+}
+
+declare type WidgetStatus = {
+    text: string;
+    favicon?: string;
+    frame?: boolean;
+} | {
+    text: string;
+    icon?: WidgetIcon;
+};
+
+/**
+ * A Web Component that serves as the entry point for a ChatKit integration.
+ * * @noInheritDoc
+ */
+export declare interface XpertAIChatKit extends HTMLElement {
+    /**
+     * Applies configuration options to the ChatKit instance.
+     *
+     * **IMPORTANT**: New options are not merged with the existing options. You must provide a full set of options every time you call this method.
+     */
+    setOptions(options: ChatKitOptions): void;
+    /** Focuses the composer input field. */
+    focusComposer(): Promise<void>;
+    /** Changes the active thread. Pass `null` to switch to a new thread. */
+    setThreadId(threadId: string | null): Promise<void>;
+    /**
+     * Sends a custom application-defined action to your backend.
+     */
+    sendCustomAction(action: {
+        type: string;
+        payload?: Record<string, unknown>;
+    }, 
+    /**
+     * The ID of the WidgetItem that the action is associated with. You may
+     * need this if the action was triggered by a widget, gets handled
+     * client-side, and then you want to send the action back to the server to
+     * do additional handling.
+     *
+     * @example
+     * ```ts
+     * chatKit.options = {
+     *   // other options...
+     *   widgets: {
+     *     async onAction(action, widgetItem) {
+     *       await someClientSideHandling(action)
+     *       await chatkit.sendAction(action, widgetItem.id)
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    itemId?: string): Promise<void>;
+    /** Sends a user message. */
+    sendUserMessage(params: {
+        text: string;
+        reply?: string;
+        attachments?: Attachment[];
+        newThread?: boolean;
+    }): Promise<void>;
+    /** Sets the composer's content without sending a message. */
+    setComposerValue(params: {
+        text: string;
+        reply?: string;
+        attachments?: Attachment[];
+    }): Promise<void>;
+    /**
+     * Manually fetches updates from the server.
+     *
+     * Use this when you've manually updated the thread or thread items and need to sync them with the client.
+     */
+    fetchUpdates(): Promise<void>;
+    /**
+     * Adds an event listener for the specified {@link ChatKitEvents} event.
+     *
+     * @example
+     * ```ts
+     * chatKit.addEventListener('chatkit.error', (event) => {
+     *   logToMyErrorLogger(event.detail.error);
+     * });
+     * ```
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener}
+     */
+    addEventListener<K extends keyof ChatKitEvents>(
+    /**
+     * See {@link ChatKitEvents} for available events.
+     */
+    type: K, 
+    /**
+     * The event listener callback.
+     */
+    listener: EventHandler<K>, 
+    /**
+     * An object that specifies characteristics about the event listener.
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options}
+     */
+    options?: boolean | AddEventListenerOptions): void;
+    /* Excluded from this release type: addEventListener */
+    /**
+     * Removes an event listener for the specified event.
+     *
+     * @example
+     * ```ts
+     * chatKit.removeEventListener('chatkit.error', myErrorListener);
+     * ```
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener}
+     */
+    removeEventListener<K extends keyof ChatKitEvents>(
+    /**
+     * See {@link ChatKitEvents} for available events.
+     */
+    type: K, 
+    /**
+     * The event listener callback to remove.
+     */
+    listener: EventHandler<K>, 
+    /**
+     * An object that specifies characteristics about the event listener.
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener#options}
+     */
+    options?: boolean | EventListenerOptions): void;
+    /* Excluded from this release type: removeEventListener */
+}
+
 export { }