@antglobal/copilot-cards-web 0.0.0 → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1353 @@
+import { ActionRunnerContext, CardSchemaInput, StreamingCommand, CardSchema, StreamingParserOptions, SimpleActionHandler, ActionConfigProvider, ActionChainConfig, RenderTreeNode } from '@antglobal/copilot-cards-core';
+export { A2UIComponent, A2UIEnvelope, ActionChainConfig, ActionConfigProvider, ActionRegistry, ActionRunnerContext, ActionStep, CardSchema, CardSchemaInput, ElementLifecycle, ElementNode, ExpressionContext, ExpressionValue, LegacyCardContentItem, LegacyCardSchema, LegacyTracking, LegacyTrackingType, LifecycleManager, RenderTreeNode, SimpleActionHandler, SlotContent, SlotLayout, a2uiComponentToElement, a2uiToCommand, convertLegacySchema, createLifecycleManager, hasExpression, isA2UIEnvelope, isLegacySchema, normalizeSchema, parseSchema, registerActionHandler, registry, resolveActionRef, resolveDeep, resolveExpression, resolveExpressionValue, runActionStep, runActionSteps, validateSchema } from '@antglobal/copilot-cards-core';
+
+/**
+ * Core Adapter — bridges @antglobal/copilot-cards-core logic for the web-component layer.
+ *
+ * Provides a single import surface for all core functionality
+ * and adds a web-specific ActionRunnerContext factory.
+ */
+
+interface WebActionContextOptions {
+    /** Override the global fetch */
+    fetch?: typeof globalThis.fetch;
+    /** Custom toast handler */
+    showToast?: (message: string, level?: string, duration?: number) => void;
+    /** Custom navigation handler */
+    navigate?: (url: string, target?: string) => void;
+    /** Variable setter for setVariable actions */
+    setVariable?: (key: string, value: any) => void;
+    /** Event emitter for emit actions */
+    emit?: (eventName: string, payload?: any) => void;
+    /** Copy text to clipboard */
+    copyText?: (text: string) => void;
+    /** Abort signal for cancelling in-flight requests on dispose */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Create an ActionRunnerContext with sensible web defaults.
+ */
+declare function createWebActionContext(options?: WebActionContextOptions): ActionRunnerContext;
+
+/**
+ * renderCard — the primary public API for @antglobal/copilot-cards-web.
+ *
+ * Users pass in a container element and a CardSchema JSON:
+ *
+ * ```ts
+ * import { renderCard } from '@card-sdk/web-component';
+ *
+ * const container = document.getElementById('card-container');
+ * const schema = { rootID: "root", elements: { ... }, variables: {} };
+ * renderCard(container, schema);
+ * ```
+ */
+
+interface RenderCardOptions extends WebActionContextOptions {
+    /** Force mobile mode; auto-detected from viewport if omitted */
+    isMobile?: boolean;
+    /** External variables to merge into schema.variables (overrides schema defaults) */
+    variables?: Record<string, any>;
+    /** Bot ID — used to look up bot-scoped action handlers */
+    botId?: string;
+}
+interface CardInstance {
+    /** Dispose the card: unmount all lifecycles, remove DOM, detach listeners. */
+    dispose: () => void;
+    /** Update variables and re-render. */
+    updateVariables: (variables: Record<string, any>) => void;
+}
+/**
+ * Render a card schema into a container element.
+ *
+ * @returns A `CardInstance` with `dispose()` and `updateVariables()` methods.
+ */
+declare function renderCard(container: HTMLElement, schemaInput: CardSchemaInput, options?: RenderCardOptions): CardInstance;
+
+/**
+ * Streaming Card Renderer — enables progressive card rendering via streaming commands.
+ *
+ * Unlike `renderCard()` which requires a complete schema upfront,
+ * `renderStreamingCard()` creates a card instance that can be incrementally
+ * built and updated through streaming commands from an Agent/LLM.
+ *
+ * Architecture:
+ * - StreamingParser: converts raw text chunks into typed commands
+ * - StreamingEngine: maintains state and emits change events
+ * - This module: handles DOM operations based on engine events
+ */
+
+interface StreamingCardOptions extends RenderCardOptions {
+    /** Parser options (delimiter, error handler) */
+    parserOptions?: StreamingParserOptions;
+    /**
+     * Called when a card component runs an `action` step (A2UI-style user
+     * action). The payload matches the A2UI v0.9 client→server `action`
+     * message body — forward it to your agent/server as-is.
+     */
+    onAction?: (action: A2UIActionPayload) => void;
+    /** Entrance transition for incrementally streamed-in blocks (default true). */
+    appearTransition?: boolean;
+}
+/** A2UI v0.9 client→server user-action payload (https://a2ui.org). */
+interface A2UIActionPayload {
+    name: string;
+    surfaceId: string | null;
+    sourceComponentId: string;
+    timestamp: string;
+    context: Record<string, any>;
+}
+/** Result of finalizePartialSchema(). */
+interface PartialFinalizeResult {
+    /** Whether the schema JSON document ultimately closed and parsed. */
+    complete: boolean;
+    /** validateSchema errors (or a stream-incomplete note). Empty = success. */
+    errors: string[];
+}
+interface StreamingCardInstance extends CardInstance {
+    /** Apply a single streaming command directly */
+    applyCommand(command: StreamingCommand): void;
+    /** Apply multiple commands in batch */
+    applyCommands(commands: StreamingCommand[]): void;
+    /** Feed raw text chunk (auto-parsed via StreamingParser) */
+    feed(chunk: string): void;
+    /** Flush remaining buffered content in the parser */
+    flush(): void;
+    /**
+     * Progressive rendering for LLM-emitted schema JSON that is still streaming.
+     * Call every frame with the ACCUMULATED text (append-only) — idempotent, so
+     * dropped/replayed frames are safe. Completed blocks mount incrementally;
+     * the incomplete tail never renders. Mutually exclusive with `feed()` /
+     * `applyCommand()` on the same instance.
+     */
+    feedPartialSchema(accumulatedText: string): void;
+    /**
+     * Call when the stream ends: runs the authoritative full-document parse +
+     * validateSchema, applies the final (unpruned) tree, and reports status.
+     * `{complete:false}` = stream cut before the JSON closed (rendered blocks
+     * are kept; the host decides whether to degrade).
+     */
+    finalizePartialSchema(): PartialFinalizeResult;
+    /** Get current schema state for a surface */
+    getSchema(surfaceId?: string): CardSchema | undefined;
+}
+/**
+ * Create a streaming card instance that supports progressive rendering.
+ *
+ * @example
+ * ```ts
+ * const card = renderStreamingCard(container);
+ *
+ * // Feed raw SSE/NDJSON chunks as they arrive
+ * eventSource.onmessage = (e) => card.feed(e.data + '\n');
+ *
+ * // Or apply commands directly
+ * card.applyCommand({
+ *   type: 'createSurface',
+ *   surfaceId: 'main',
+ *   schema: { version: '1.0', rootID: 'root', elements: {...}, variables: {} }
+ * });
+ * ```
+ */
+declare function renderStreamingCard(container: HTMLElement, options?: StreamingCardOptions): StreamingCardInstance;
+
+/**
+ * Streaming Transport — connects a StreamingCardInstance to a streaming data source.
+ *
+ * Provides utility functions to bridge common transport protocols
+ * (SSE, fetch streaming, WebSocket) with the streaming card renderer.
+ */
+
+interface StreamingConnectOptions {
+    /** URL of the streaming endpoint */
+    url: string;
+    /** HTTP method, defaults to 'GET' */
+    method?: 'GET' | 'POST';
+    /** Request body (will be JSON.stringify'd for POST) */
+    body?: any;
+    /** Custom request headers */
+    headers?: Record<string, string>;
+    /** Called when the stream ends normally */
+    onComplete?: () => void;
+    /** Called when a transport error occurs */
+    onError?: (error: Error) => void;
+    /** Called when connection is established */
+    onOpen?: () => void;
+}
+interface StreamingConnection {
+    /** Abort the streaming connection */
+    abort(): void;
+    /** The underlying AbortController */
+    controller: AbortController;
+}
+/**
+ * Connect to a fetch streaming endpoint and feed chunks to the card instance.
+ *
+ * Uses the Fetch API with ReadableStream to consume server-sent data progressively.
+ * Supports both NDJSON and SSE format responses.
+ *
+ * @example
+ * ```ts
+ * const card = renderStreamingCard(container);
+ * const connection = await connectStreaming(card, {
+ *   url: '/api/agent/chat',
+ *   method: 'POST',
+ *   body: { message: 'Show me my order status' },
+ *   onComplete: () => console.log('Stream finished'),
+ *   onError: (err) => console.error('Stream error:', err),
+ * });
+ *
+ * // To cancel the stream:
+ * connection.abort();
+ * ```
+ */
+declare function connectStreaming(instance: StreamingCardInstance, options: StreamingConnectOptions): Promise<StreamingConnection>;
+interface SSEConnectOptions {
+    /** URL of the SSE endpoint */
+    url: string;
+    /** Event type to listen for, defaults to 'message' */
+    eventType?: string;
+    /** Called when the stream ends */
+    onComplete?: () => void;
+    /** Called on error */
+    onError?: (error: Event) => void;
+    /** Called when connection opens */
+    onOpen?: () => void;
+}
+/**
+ * Connect to a Server-Sent Events (EventSource) endpoint.
+ *
+ * This is a simpler alternative to fetch streaming for servers that
+ * support the standard SSE protocol. Each SSE message is parsed and
+ * fed to the card instance.
+ *
+ * @example
+ * ```ts
+ * const card = renderStreamingCard(container);
+ * const connection = connectSSE(card, {
+ *   url: '/api/agent/stream?session=abc123',
+ *   onComplete: () => console.log('Done'),
+ * });
+ *
+ * // Later: close the connection
+ * connection.close();
+ * ```
+ */
+declare function connectSSE(instance: StreamingCardInstance, options: SSEConnectOptions): EventSource;
+
+/**
+ * BotSDK — high-level wrapper for integrating copilot bot cards
+ * into business applications.
+ *
+ * Usage:
+ * ```ts
+ * import { BotSDK, registry } from '@antglobal/copilot-cards-web';
+ *
+ * const bot = new BotSDK({
+ *   botId: '10001',
+ *   baseUrl: 'https://api.example.com',
+ *   onAction: {
+ *     bizRequest: async (params, ctx) => {
+ *       const res = await axios.post(params.api, params.data);
+ *       if (res.data.code !== 200) throw new Error('Failed');
+ *     },
+ *   },
+ * });
+ *
+ * // Render a card from server-delivered schema
+ * const instance = bot.renderCard(container, cardSchema, {
+ *   variables: { order_id: 'ORDER_666' },
+ * });
+ * ```
+ */
+
+interface BotSDKOptions {
+    /** Bot ID — identifies which bot this instance is for */
+    botId: string;
+    /** Base URL for business API requests (e.g. 'https://api.example.com') */
+    baseUrl?: string;
+    /**
+     * Source B: Batch-register custom action handler functions.
+     * These are imperative JS handlers written in the frontend project.
+     * Shorthand for calling `registry.register()` for each entry.
+     */
+    onAction?: Record<string, SimpleActionHandler>;
+    /**
+     * Source A: Action configuration provider.
+     * Fetches declarative ActionStep[] chains from a data source
+     * (local mock for dev, remote API for production).
+     */
+    actionProvider?: ActionConfigProvider;
+}
+declare class BotSDK {
+    readonly botId: string;
+    readonly baseUrl: string;
+    private _instances;
+    /** Declarative action chains loaded from actionProvider */
+    private _actionChains;
+    /** Promise that resolves when action configs are loaded */
+    private _ready;
+    constructor(options: BotSDKOptions);
+    private _loadActionConfigs;
+    /**
+     * Render a card schema into a container element.
+     *
+     * If an actionProvider was configured, this method waits for
+     * action configs to load before rendering. Declarative action
+     * chains are merged into `schema.actions`.
+     *
+     * @returns A `CardInstance` with `dispose()` and `updateVariables()` methods.
+     */
+    renderCard(container: HTMLElement, schemaInput: CardSchemaInput, options?: RenderCardOptions): Promise<CardInstance>;
+    /**
+     * Merge loaded action chain configs into schema.actions.
+     * Provider configs are used as defaults; schema.actions takes precedence.
+     */
+    private _mergeSchemaActions;
+    /**
+     * Dispose all card instances created by this BotSDK instance.
+     */
+    disposeAll(): void;
+}
+
+/**
+ * LocalActionConfigProvider — loads action chain configs from an in-memory
+ * object. Used for demo / development / testing.
+ *
+ * Usage:
+ * ```ts
+ * const provider = new LocalActionConfigProvider({
+ *   '10001': [
+ *     { name: 'confirmOrder', steps: [{ type: 'request', params: { ... } }] },
+ *   ],
+ * });
+ * ```
+ */
+
+declare class LocalActionConfigProvider implements ActionConfigProvider {
+    private _configs;
+    constructor(configs?: Record<string, ActionChainConfig[]>);
+    /**
+     * Add or replace action configs for a botId.
+     */
+    addBot(botId: string, actions: ActionChainConfig[]): void;
+    /**
+     * Remove all action configs for a botId.
+     */
+    removeBot(botId: string): void;
+    fetchActions(botId: string): Promise<ActionChainConfig[]>;
+}
+
+/**
+ * RemoteActionConfigProvider — fetches action chain configs from a
+ * server-side API. Used in production environments.
+ *
+ * The server stores action chain configs per botId in the database.
+ * This provider fetches them via HTTP.
+ *
+ * Expected API response format:
+ * ```json
+ * [
+ *   { "name": "confirmOrder", "steps": [...], "description": "..." },
+ *   { "name": "submitFeedback", "steps": [...] }
+ * ]
+ * ```
+ *
+ * Usage:
+ * ```ts
+ * const provider = new RemoteActionConfigProvider('https://api.example.com');
+ * const configs = await provider.fetchActions('10001');
+ * ```
+ */
+
+declare class RemoteActionConfigProvider implements ActionConfigProvider {
+    private _baseUrl;
+    private _headers;
+    private _cache;
+    constructor(baseUrl: string, options?: {
+        /** Additional HTTP headers (e.g. Authorization) */
+        headers?: Record<string, string>;
+    });
+    fetchActions(botId: string): Promise<ActionChainConfig[]>;
+    /**
+     * Clear the cache for a specific botId or all bots.
+     */
+    clearCache(botId?: string): void;
+}
+
+/**
+ * Responsive & unit conversion utilities for web-component rendering.
+ */
+/**
+ * Convert a `px` value to `rem` based on a root font-size.
+ */
+declare function pxToRem(px: number, rootFontSize?: number): string;
+/**
+ * Convert a `px` value to `vw` based on a design-width.
+ */
+declare function pxToVw(px: number, designWidth?: number): string;
+/**
+ * Resolve a size value: if it's a number, append `px`; otherwise return as-is.
+ */
+declare function resolveSize(value: string | number): string;
+/**
+ * Check if the current viewport matches "mobile" via media query.
+ * Falls back to `false` in non-browser environments.
+ */
+declare function isMobileViewport(breakpoint?: number): boolean;
+/**
+ * Create a `MediaQueryList` listener that fires when mobile/desktop changes.
+ * Returns a cleanup function to remove the listener.
+ */
+declare function onViewportChange(callback: (isMobile: boolean) => void, breakpoint?: number): () => void;
+/**
+ * Build an inline style string from a Record.
+ * Values are used as-is; Schema should provide complete CSS values (e.g., "14px", "500").
+ */
+declare function buildStyleString(styles: Record<string, string | number | undefined>): string;
+
+/**
+ * BaseElement — abstract Custom Element base class for card components.
+ *
+ * Provides Shadow DOM encapsulation, data-driven rendering, and
+ * common style helpers. Designed to be used by `renderCard` which
+ * passes resolved props via `setData()`.
+ *
+ * Note: lifecycle management, event binding, and viewport detection
+ * are handled externally by `renderCard` / the render pipeline.
+ * BaseElement keeps itself lightweight and focused on DOM rendering.
+ */
+
+declare abstract class BaseElement extends HTMLElement {
+    protected _node: RenderTreeNode | null;
+    protected _props: Record<string, any>;
+    protected _isMobile: boolean;
+    constructor();
+    /**
+     * Set component data and trigger render.
+     * Called by the component renderer (from `renderCard` pipeline).
+     */
+    setData(node: RenderTreeNode, props: Record<string, any>, isMobile: boolean): void;
+    /**
+     * Update props only (e.g. on variable change + re-render).
+     */
+    updateProps(props: Record<string, any>, isMobile?: boolean): void;
+    /**
+     * Subclasses must implement this to render their UI into `this.shadowRoot`.
+     */
+    protected abstract render(): void;
+    /** Convert any content value to a safe display string. */
+    protected resolveContent(content: any): string;
+    /**
+     * Build an inline CSS string from a style props object.
+     * Numeric values are resolved to `px`.
+     */
+    protected buildInlineStyle(style?: Record<string, any>, isExpressionResult?: boolean): string;
+    /** Resolve a single size value (number → px). */
+    protected toCSS(value: string | number): string;
+    /**
+     * CSS properties whose numeric values are unitless — appending `px`
+     * to these produces invalid CSS the browser silently drops
+     * (e.g. `opacity: 0.5px`, `font-weight: 500px`, `flex: 1px`).
+     */
+    private static readonly UNITLESS_PROPS;
+    private resolveSizeInStyle;
+}
+
+declare class CardText extends BaseElement {
+    static readonly is = "ai-card-text";
+    private _prevContent;
+    private _displayedContent;
+    private _streamTimer;
+    private _contentEl;
+    private _cursorEl;
+    private _isInitialRender;
+    private _mdThrottleTimer;
+    private _mdPendingUpdate;
+    private _tooltipEl;
+    private _tooltipTimer;
+    setData(node: RenderTreeNode, props: Record<string, any>, isMobile: boolean): void;
+    protected render(): void;
+    /**
+     * Handle incremental content update in streaming mode.
+     * Called when render() is triggered again with new content while streaming.
+     */
+    private _handleStreamingUpdate;
+    /**
+     * Start initial streaming animation from empty to full content.
+     */
+    private _startStreamingAnimation;
+    /**
+     * Update the content DOM element with current displayed content.
+     * When markdown is enabled, throttle parsing to avoid O(n²) cost.
+     */
+    private _updateContentDOM;
+    /**
+     * Flush pending markdown parse to DOM.
+     */
+    private _flushMarkdown;
+    /**
+     * Remove the streaming cursor from DOM.
+     */
+    private _removeCursor;
+    /**
+     * Remove cursor when streaming ends.
+     * Called externally when streaming prop changes to false.
+     */
+    updateProps(props: Record<string, any>, isMobile?: boolean): void;
+    /**
+     * Parse markdown to HTML using marked.
+     */
+    private _parseMarkdown;
+    /**
+     * When `maxLines` clamps the text, show the full text in a styled tooltip
+     * on hover — but only when the content is actually truncated, so text that
+     * fits gets no redundant tooltip. Overflow is measured after layout (rAF):
+     * a `-webkit-line-clamp` box reports the full content height via scrollHeight
+     * while clientHeight stays at the clamped line box.
+     *
+     * The tooltip replaces the native `title` (which is unstyled and takes ~1s
+     * to appear): it shows after a short 200ms hover, renders in the shadow root
+     * with `position: fixed` so ancestor `overflow: hidden` can't clip it, and
+     * flips above the anchor when it would overflow the viewport bottom.
+     */
+    private _updateClampTitle;
+    /** Show the clamp tooltip below (or above) the anchor, kept inside the viewport. */
+    private _showClampTooltip;
+    /** Remove the clamp tooltip if present. */
+    private _hideClampTooltip;
+    /**
+     * Escape HTML to prevent XSS when not in markdown mode.
+     */
+    private _escapeHTML;
+    disconnectedCallback(): void;
+}
+
+/**
+ * CardButton — Custom Element for rendering button content in a card.
+ *
+ * Uses Shadow DOM for style encapsulation so card button styles
+ * never leak into or get affected by the host page.
+ *
+ * Registered as `<ai-card-button>`. Created internally by the
+ * component renderer; end-users interact via `renderCard()`.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "Button",
+ *   "props": {
+ *     "content": { "type": "static", "value": "Submit" },
+ *     "variant": "primary",
+ *     "size": "medium",
+ *     "disabled": false,
+ *     "block": false,
+ *     "style": { "borderRadius": 6 }
+ *   },
+ *   "events": {
+ *     "onClick": [{ "type": "emit", "params": { "event": "submit" } }]
+ *   }
+ * }
+ * ```
+ */
+
+declare class CardButton extends BaseElement {
+    static readonly is = "ai-card-button";
+    protected render(): void;
+}
+
+/**
+ * CardInput — Custom Element for rendering input fields in a card.
+ *
+ * Uses Shadow DOM for style encapsulation so card input styles
+ * never leak into or get affected by the host page.
+ *
+ * Registered as `<ai-card-input>`. Created internally by the
+ * component renderer; end-users interact via `renderCard()`.
+ *
+ * The input value is synced to schema variables via `setVariable`
+ * action on every input/change event, enabling reactive data flow.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "Input",
+ *   "props": {
+ *     "placeholder": "Enter your name",
+ *     "inputType": "text",
+ *     "variableKey": "userName",
+ *     "label": "Name",
+ *     "maxLength": 100,
+ *     "disabled": false,
+ *     "style": { "width": 300 }
+ *   },
+ *   "events": {
+ *     "onChange": [{ "type": "emit", "params": { "event": "inputChanged" } }]
+ *   }
+ * }
+ * ```
+ */
+
+declare class CardInput extends BaseElement {
+    static readonly is = "ai-card-input";
+    protected render(): void;
+    /** Escape HTML entities for safe insertion. */
+    private escapeHtml;
+    /** Escape attribute values for safe insertion. */
+    private escapeAttr;
+}
+
+/**
+ * CardImage — Custom Element for rendering images in a card.
+ *
+ * Uses Shadow DOM for style encapsulation. Supports click-to-zoom
+ * lightbox functionality for viewing full-size images.
+ *
+ * Registered as `<ai-card-image>`. Created internally by the
+ * component renderer; end-users interact via `renderCard()`.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "Image",
+ *   "props": {
+ *     "src": "https://example.com/image.jpg",
+ *     "alt": "Description",
+ *     "width": "200px",
+ *     "height": "auto",
+ *     "objectFit": "cover",
+ *     "preview": true,
+ *     "style": { "borderRadius": "8px" }
+ *   }
+ * }
+ * ```
+ */
+
+declare class CardImage extends BaseElement {
+    static readonly is = "ai-card-image";
+    private _lightbox;
+    protected render(): void;
+    private bindEvents;
+    private openLightbox;
+    private closeLightbox;
+    disconnectedCallback(): void;
+}
+
+/**
+ * CardDivider — Custom Element for rendering a divider/separator line.
+ *
+ * Supports horizontal/vertical orientation, dashed style, and text label.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "Divider",
+ *   "props": {
+ *     "direction": "horizontal",
+ *     "dashed": false,
+ *     "text": "OR",
+ *     "color": "#e8e8e8",
+ *     "thickness": 1
+ *   }
+ * }
+ * ```
+ */
+
+declare class CardDivider extends BaseElement {
+    static readonly is = "ai-card-divider";
+    protected render(): void;
+}
+
+/**
+ * CardRate — Custom Element for star rating display/input.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "Rate",
+ *   "props": {
+ *     "value": 3,
+ *     "count": 5,
+ *     "readonly": false,
+ *     "size": 24,
+ *     "gap": 4,
+ *     "color": "#fadb14",
+ *     "variableKey": "rating"
+ *   }
+ * }
+ * ```
+ */
+
+declare class CardRate extends BaseElement {
+    static readonly is = "ai-card-rate";
+    /** Internal interactive value (tracks clicks before external update) */
+    private _currentValue;
+    protected render(): void;
+    /** Reset internal state when props update externally */
+    updateProps(props: Record<string, any>, isMobile?: boolean): void;
+}
+
+/**
+ * CardTag — Custom Element for rendering a tag/badge label.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "Tag",
+ *   "props": {
+ *     "content": "NEW",
+ *     "color": "blue",
+ *     "closable": false
+ *   }
+ * }
+ * ```
+ */
+
+declare class CardTag extends BaseElement {
+    static readonly is = "ai-card-tag";
+    protected render(): void;
+}
+
+/**
+ * CardSelect — Custom Element for a dropdown selector.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "Select",
+ *   "props": {
+ *     "placeholder": "请选择",
+ *     "options": [
+ *       { "label": "选项一", "value": "1" },
+ *       { "label": "选项二", "value": "2" }
+ *     ],
+ *     "value": ""
+ *   }
+ * }
+ * ```
+ *
+ * The value is semi-controlled: a user-picked option shows on the trigger
+ * immediately even when no `onChange` action is wired, while any external
+ * `props.value` change (e.g. a variable update re-render) overrides the
+ * local pick.
+ */
+
+declare class CardSelect extends BaseElement {
+    private _open;
+    /** Option picked locally; shown until props.value changes externally. */
+    private _localValue;
+    /** Last seen props.value — detects external changes vs. re-renders. */
+    private _propValue;
+    private _onDocClick;
+    static readonly is = "ai-card-select";
+    protected render(): void;
+    disconnectedCallback(): void;
+    private _setOpen;
+}
+
+/**
+ * CardPasscodeInput — Custom Element for N-digit passcode/PIN input.
+ *
+ * Renders N individual square boxes. Auto-advances focus on input.
+ * Supports paste, backspace navigation, and masked mode.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "PasscodeInput",
+ *   "props": {
+ *     "length": 6,
+ *     "mask": false,
+ *     "size": 48
+ *   }
+ * }
+ * ```
+ */
+
+declare class CardPasscodeInput extends BaseElement {
+    static readonly is = "ai-card-passcode-input";
+    protected render(): void;
+    private _emitValue;
+}
+
+/**
+ * CardIcon — Custom Element for rendering icons.
+ *
+ * Supports URL-based icons (png/svg) and built-in emoji/SVG icons.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "Icon",
+ *   "props": {
+ *     "name": "check",
+ *     "src": "https://...",
+ *     "size": 24,
+ *     "color": "#1677ff"
+ *   }
+ * }
+ * ```
+ */
+
+declare class CardIcon extends BaseElement {
+    static readonly is = "ai-card-icon";
+    protected render(): void;
+}
+
+/**
+ * CardForm — Custom Element for rendering a complete form.
+ *
+ * Renders fields (text / textarea / select / passcode / rate) with
+ * labels, validation, and a submit button. On submit it collects
+ * all values and dispatches a `submit` CustomEvent.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "Form",
+ *   "props": {
+ *     "fields": [
+ *       { "name": "username", "label": "用户名", "type": "text", "required": true, "placeholder": "请输入" },
+ *       { "name": "gender", "label": "性别", "type": "select", "options": [{"label":"男","value":"male"},{"label":"女","value":"female"}] },
+ *       { "name": "code", "label": "验证码", "type": "passcode", "length": 6 },
+ *       { "name": "score", "label": "评分", "type": "rate" },
+ *       { "name": "remark", "label": "备注", "type": "textarea" }
+ *     ],
+ *     "submitText": "提交",
+ *     "layout": "vertical"
+ *   }
+ * }
+ * ```
+ */
+
+declare class CardForm extends BaseElement {
+    static readonly is = "ai-card-form";
+    private _values;
+    private _errors;
+    private _submitted;
+    protected render(): void;
+    private _renderField;
+    private _bindEvents;
+    private _validate;
+    updateProps(props: Record<string, any>, isMobile?: boolean): void;
+}
+
+/**
+ * CardLoading — Custom Element for rendering a spinner loading indicator.
+ *
+ * Supports configurable spin duration, size, color, and optional text.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "Loading",
+ *   "props": {
+ *     "size": 32,
+ *     "color": "#1677ff",
+ *     "duration": 1,
+ *     "text": "加载中..."
+ *   }
+ * }
+ * ```
+ */
+
+declare class CardLoading extends BaseElement {
+    static readonly is = "ai-card-loading";
+    protected render(): void;
+}
+
+/**
+ * Component Props Type Declarations
+ *
+ * Provides TypeScript type definitions for all built-in component props.
+ * These types correspond to the props destructured from `this._props`
+ * in each component's `render()` method.
+ */
+interface TextProps {
+    /** Text content (static string or expression-resolved value) */
+    content?: string;
+    /** Text alignment: left / center / right */
+    align?: string;
+    /** Font size (number → px, or CSS string) */
+    fontSize?: string | number;
+    /** Font weight (e.g. 'bold', 500) */
+    fontWeight?: string | number;
+    /** Text color */
+    color?: string;
+    /** Max visible lines — enables CSS line-clamp truncation */
+    maxLines?: number;
+    /** Inline style object */
+    style?: Record<string, any>;
+}
+interface ButtonProps {
+    /** Button label text */
+    content?: string;
+    /** Visual variant */
+    variant?: 'primary' | 'secondary' | 'text' | 'danger';
+    /** Button size */
+    size?: 'small' | 'medium' | 'large';
+    /** Whether the button is disabled */
+    disabled?: boolean;
+    /** Whether the button stretches to full width */
+    block?: boolean;
+    /** Icon HTML rendered before text */
+    icon?: string;
+    /** Inline style object */
+    style?: Record<string, any>;
+}
+interface InputProps {
+    /** Placeholder text */
+    placeholder?: string;
+    /** HTML input type: text / textarea / password / number etc. */
+    inputType?: 'text' | 'textarea' | 'password' | (string & {});
+    /** Label text displayed above the input */
+    label?: string;
+    /** Initial value */
+    defaultValue?: string;
+    /** Whether the input is disabled */
+    disabled?: boolean;
+    /** Whether the input is read-only */
+    readonly?: boolean;
+    /** Maximum character length */
+    maxLength?: number;
+    /** Number of rows for textarea (default 3) */
+    rows?: number;
+    /** Inline style object */
+    style?: Record<string, any>;
+}
+interface ImageProps {
+    /** Image URL */
+    src?: string;
+    /** Alt text for accessibility */
+    alt?: string;
+    /** Image width (CSS value) */
+    width?: string;
+    /** Image height (CSS value) */
+    height?: string;
+    /** CSS object-fit mode (default 'cover') */
+    objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+    /** Whether lightbox preview is enabled (default true) */
+    preview?: boolean;
+    /** Inline style object */
+    style?: Record<string, any>;
+}
+interface DividerProps {
+    /** Orientation (default 'horizontal') */
+    direction?: 'horizontal' | 'vertical';
+    /** Whether to use dashed line (default false) */
+    dashed?: boolean;
+    /** Optional text displayed on the divider */
+    text?: string;
+    /** Line color (default '#e8e8e8') */
+    color?: string;
+    /** Line thickness in px (default 1) */
+    thickness?: number;
+    /** Inline style object */
+    style?: Record<string, any>;
+}
+interface RateProps {
+    /** Current rating value (default 0) */
+    value?: number;
+    /** Total number of stars (default 5) */
+    count?: number;
+    /** Whether the rating is read-only (default false) */
+    readonly?: boolean;
+    /** Whether half-star selection is allowed (default false) */
+    allowHalf?: boolean;
+    /** Star size in px (default 24) */
+    size?: number;
+    /** Active star color (default '#fadb14') */
+    color?: string;
+    /** Inactive star color (default '#e8e8e8') */
+    inactiveColor?: string;
+    /** Inline style object */
+    style?: Record<string, any>;
+}
+interface TagProps {
+    /** Tag label text */
+    content?: string;
+    /** Preset color name or custom hex color (default 'default') */
+    color?: 'blue' | 'green' | 'red' | 'orange' | 'gold' | 'cyan' | 'purple' | 'default' | (string & {});
+    /** Whether the close button is shown (default false) */
+    closable?: boolean;
+    /** Whether to show border (default true) */
+    bordered?: boolean;
+    /** Inline style object */
+    style?: Record<string, any>;
+}
+interface SelectOption {
+    label: string;
+    value: string;
+}
+interface SelectProps {
+    /** Dropdown options list */
+    options?: SelectOption[];
+    /** Placeholder text (default '请选择') */
+    placeholder?: string;
+    /** Currently selected value */
+    value?: string;
+    /** Whether the select is disabled (default false) */
+    disabled?: boolean;
+    /** Inline style object */
+    style?: Record<string, any>;
+}
+interface PasscodeInputProps {
+    /** Number of passcode cells (default 6, max 10) */
+    length?: number;
+    /** Whether to mask input as password (default false) */
+    mask?: boolean;
+    /** Cell size in px (default 48) */
+    size?: number;
+    /** Gap between cells in px (default 8) */
+    gap?: number;
+    /** Whether the input is disabled (default false) */
+    disabled?: boolean;
+    /** Inline style object */
+    style?: Record<string, any>;
+}
+interface IconProps {
+    /** Built-in icon name (check/close/info/warning/error/success/star/heart/search/arrow_right) or emoji */
+    name?: string;
+    /** URL to a remote icon image */
+    src?: string;
+    /** Icon size in px (default 24) */
+    size?: number;
+    /** Icon color (default 'currentColor') */
+    color?: string;
+    /** Inline style object */
+    style?: Record<string, any>;
+}
+interface FormField {
+    /** Field identifier (used as key in submitted values) */
+    name: string;
+    /** Display label */
+    label?: string;
+    /** Field type (default 'text') */
+    type?: 'text' | 'textarea' | 'select' | 'passcode' | 'rate' | 'number' | 'password';
+    /** Placeholder text */
+    placeholder?: string;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Options for select type */
+    options?: {
+        label: string;
+        value: string;
+    }[];
+    /** Number of cells for passcode type (default 6) */
+    length?: number;
+    /** Initial value */
+    defaultValue?: any;
+}
+interface FormProps {
+    /** Form field definitions */
+    fields?: FormField[];
+    /** Submit button text (default '提交') */
+    submitText?: string;
+    /** Form layout direction (default 'vertical') */
+    layout?: 'vertical' | 'horizontal';
+    /** Whether the entire form is disabled (default false) */
+    disabled?: boolean;
+    /** Inline style object */
+    style?: Record<string, any>;
+}
+interface LoadingProps {
+    /** Spinner size in px (default 32) */
+    size?: number | string;
+    /** Spinner color (default '#1677ff') */
+    color?: string;
+    /** Animation duration in seconds (default 1) */
+    duration?: number | string;
+    /** Spinner border thickness in px (default 3) */
+    thickness?: number;
+    /** Optional loading text */
+    text?: string;
+    /** Inline style object */
+    style?: Record<string, any>;
+}
+interface ProgressSegment {
+    /** Numeric contribution of this segment */
+    value: number;
+    /** Optional legend text */
+    label?: string;
+    /** Segment color; falls back to ProgressProps.color */
+    color?: string;
+}
+interface ProgressProps {
+    /** Single progress value (default 0); ignored when segments is non-empty */
+    value?: number;
+    /** Maximum value; defaults to 100 in single mode or the segment total */
+    max?: number;
+    /** Segmented progress data; a non-empty array selects segmented mode */
+    segments?: ProgressSegment[];
+    /** Track height (number → px, or CSS string; default 8) */
+    height?: number | string;
+    /** Gap between colored segments (number → px, or CSS string; default 0) */
+    gap?: number | string;
+    /** Default fill and fallback segment color (default '#1677ff') */
+    color?: string;
+    /** Unfilled track color (default '#f0f0f0') */
+    inactiveColor?: string;
+    /** Show labels for labeled segments (default false) */
+    showLegend?: boolean;
+    /** Legend placement relative to the track (default 'bottom') */
+    legendPosition?: 'top' | 'bottom';
+    /** Outer wrapper inline style */
+    style?: Record<string, any>;
+    /** Track inline style */
+    trackStyle?: Record<string, any>;
+    /** Legend container inline style */
+    legendStyle?: Record<string, any>;
+}
+interface StepIcon {
+    /** URL to icon image */
+    src?: string;
+    /** Built-in name or emoji text */
+    name?: string;
+    /** Icon color (for emoji/SVG) */
+    color?: string;
+    /** Background color */
+    bgColor?: string;
+    /** Override global iconSize for this step */
+    size?: number;
+}
+interface StepItem {
+    /** Step title (required) */
+    title: string;
+    /** Optional description text */
+    description?: string;
+    /** Step status (default 'pending') */
+    status?: 'pending' | 'processing' | 'completed' | 'failed';
+    /** Whether this step is clickable (triggers onStepClick event) */
+    clickable?: boolean;
+    /** Custom event name — used to distinguish different steps in onStepClick */
+    event?: string;
+    /** Custom icon — overrides status default */
+    icon?: StepIcon;
+}
+interface ConnectorConfig {
+    /** Line width in px (default 2) */
+    width?: number;
+    /** Minimum line height in px (default 24) */
+    minHeight?: number;
+    /** Line style (default 'solid') */
+    style?: 'solid' | 'dashed' | 'dotted';
+    /** Default line color (default '#e8e8e8') */
+    color?: string;
+    /** Line color for completed steps (default '#52c41a') */
+    completedColor?: string;
+    /** Custom image URL for the connector (replaces color line) */
+    src?: string;
+}
+interface StepsProps {
+    /** Step items list */
+    items?: StepItem[];
+    /** Global icon size in px (default 28) */
+    iconSize?: number;
+    /** Title text style overrides */
+    titleProps?: {
+        fontSize?: string;
+        fontWeight?: string | number;
+        color?: string;
+    };
+    /** Description text style overrides */
+    descriptionProps?: {
+        fontSize?: string;
+        color?: string;
+    };
+    /** Connector line configuration */
+    connector?: ConnectorConfig;
+    /** Inline style object */
+    style?: Record<string, any>;
+}
+interface HtmlProps {
+    /**
+     * HTML fragment emitted by the model (semantic tags only — content is
+     * allow-list sanitized before rendering; script/style/iframe/on* never
+     * reach the DOM).
+     */
+    content?: string;
+    /** Max height (e.g. '480px' or 480) — overflow scrolls inside the card */
+    maxHeight?: string | number;
+    /** Wrapper inline style (fontSize/color act as typography baseline) */
+    style?: Record<string, any>;
+}
+interface CollapseProps {
+    /** Header title text (always visible) */
+    title?: string;
+    /** Body content (shown when expanded) */
+    content?: string;
+    /** Whether expanded by default (default false) */
+    defaultExpanded?: boolean;
+    /** Header icon (emoji or text, default '💭') */
+    icon?: string;
+    /** Enable Markdown rendering for body content */
+    markdown?: boolean;
+    /** Custom arrow icon URL (replaces built-in SVG chevron) */
+    arrowIcon?: string;
+    /** Wrapper inline style */
+    style?: Record<string, any>;
+    /** Header inline style */
+    headerStyle?: Record<string, any>;
+    /** Content area inline style */
+    contentStyle?: Record<string, any>;
+    /** Body container inline style (for layout breakout, negative margins, etc.) */
+    bodyStyle?: Record<string, any>;
+}
+
+/** Display-only horizontal progress indicator. */
+declare class CardProgress extends BaseElement {
+    static readonly is = "ai-card-progress";
+    protected render(): void;
+    private buildLegend;
+    private applyInlineStyle;
+}
+
+/**
+ * CardSteps — Custom Element for rendering a vertical progress/step list.
+ *
+ * Each step shows a status icon (built-in or custom) with a title,
+ * optional description, and a connector line between steps.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "Steps",
+ *   "props": {
+ *     "items": [
+ *       { "title": "Document upload", "status": "completed" },
+ *       { "title": "Verifying document", "status": "processing", "description": "Usually takes 1-2 min" },
+ *       { "title": "Final review", "status": "pending" }
+ *     ],
+ *     "iconSize": 28,
+ *     "titleProps": { "fontSize": "14px", "fontWeight": 500, "color": "#1a1a1a" },
+ *     "descriptionProps": { "fontSize": "12px", "color": "#8c8c8c" },
+ *     "connector": { "width": 2, "minHeight": 24, "style": "solid", "color": "#e8e8e8", "completedColor": "#52c41a" }
+ *   }
+ * }
+ * ```
+ *
+ * Custom icon per step (overrides status default):
+ * ```json
+ * { "title": "Payment", "status": "completed", "icon": { "src": "https://cdn/pay.svg" } }
+ * { "title": "Shipped", "status": "processing", "icon": { "name": "🚚" } }
+ * ```
+ *
+ * Step click event (uses standard schema events, same as Button onClick):
+ * ```json
+ * {
+ *   "type": "Steps",
+ *   "props": {
+ *     "items": [
+ *       { "title": "Approval detail", "status": "completed", "clickable": true, "event": "openApproval" },
+ *       { "title": "Retry submit", "status": "failed", "clickable": true, "event": "retrySubmit" },
+ *       { "title": "Pending", "status": "pending" }
+ *     ]
+ *   },
+ *   "events": {
+ *     "onStepClick": [{ "type": "emit", "params": { "event": "${_event.item.event}", "payload": "${_event.item}" } }]
+ *   }
+ * }
+ * ```
+ */
+
+declare class CardSteps extends BaseElement {
+    static readonly is = "ai-card-steps";
+    protected render(): void;
+    /**
+     * Render icon HTML for a step.
+     * Priority: custom icon.src > custom icon.name > status default.
+     */
+    private renderIcon;
+}
+
+/**
+ * CardCollapse — Expandable/Collapsible panel component.
+ *
+ * Designed for AI "thinking" scenarios: a clickable header bar
+ * that toggles the visibility of a detail content section.
+ *
+ * Uses Shadow DOM for style encapsulation.
+ * Registered as `<ai-card-collapse>`.
+ */
+
+declare class CardCollapse extends BaseElement {
+    static readonly is = "ai-card-collapse";
+    private _expanded;
+    protected render(): void;
+    private _toggle;
+    private _parseMarkdown;
+    private _escapeHTML;
+}
+
+/**
+ * CardHtml — Custom Element for rendering model-emitted HTML fragments.
+ *
+ * The LLM outputs HTML (h1-h6/p/ul/table/strong/... plus inline styles) as
+ * `props.content`; this component renders it inside Shadow DOM **as-is**:
+ * content owns its presentation (browser semantic defaults + the model's
+ * inline `style` attributes). The component adds no typography of its own —
+ * only functional styles (container sizing, image containment, maxHeight
+ * scrolling, disabled passthrough). Shadow DOM keeps author styles of the
+ * host page out while inherited font/color still flow in.
+ *
+ * Security: content is ALWAYS passed through `sanitizeHtml` before touching
+ * innerHTML. Sanitization is tag/attribute allow-listed:
+ * - non-allow-listed elements are removed WHOLE (script/style-tag/iframe/svg/…)
+ * - all `on*` handlers and non-http(s) URLs are stripped
+ * - inline `style` attributes render as-authored, minus layout-escape
+ *   declarations (position / z-index)
+ * - links are forced to `target="_blank" rel="noopener noreferrer"`
+ * Prompt-injected `<img onerror=...>` / `<script>` therefore never execute.
+ *
+ * Registered as `<ai-card-html>`. Created internally by the component
+ * renderer; end-users interact via `renderCard()` / `renderStreamingCard()`.
+ */
+
+/**
+ * Trim a trailing incomplete tag from streaming HTML (`<div`, `</p`, `<!--`
+ * cut mid-way by a chunk boundary). The fragment renders cleanly this frame
+ * and the tag completes on the next one. Textual `<` (e.g. "a < b") is left
+ * alone — only `<` followed by a letter, `/` or `!` (or stream-edge `<`)
+ * counts as a tag opener, matching HTML5 tokenizer rules.
+ */
+declare function trimIncompleteTag(html: string): string;
+/**
+ * Allow-list sanitize an HTML fragment. Returns markup safe for innerHTML.
+ *
+ * Removal is whole-node for disallowed elements (their text is NOT kept —
+ * a `<script>`'s body must never surface), attributes are stripped down to
+ * the per-tag allow-list, and anchors get hardened targets.
+ */
+declare function sanitizeHtml(html: string): string;
+declare class CardHtml extends BaseElement {
+    static readonly is = "ai-card-html";
+    protected render(): void;
+}
+
+/**
+ * Component Renderer Registry — maps schema `type` to render functions.
+ *
+ * Each renderer creates a Custom Element (extending BaseElement) with
+ * Shadow DOM for style encapsulation, then returns it as an HTMLElement
+ * for the `renderCard` pipeline to attach events and children.
+ */
+
+type ComponentRenderer = (node: RenderTreeNode, props: Record<string, any>, isMobile: boolean) => HTMLElement;
+declare const componentRenderers: Record<string, ComponentRenderer>;
+/**
+ * Register a custom component renderer.
+ * Use this to extend the SDK with your own component types.
+ *
+ * @example
+ * ```ts
+ * registerComponent('MyWidget', (node, props, isMobile) => {
+ *   const el = document.createElement('div');
+ *   // ... build your element
+ *   return el;
+ * });
+ * ```
+ */
+declare function registerComponent(type: string, renderer: ComponentRenderer): void;
+
+export { BaseElement, BotSDK, CardButton, CardCollapse, CardDivider, CardForm, CardHtml, CardIcon, CardImage, CardInput, CardLoading, CardPasscodeInput, CardProgress, CardRate, CardSelect, CardSteps, CardTag, CardText, LocalActionConfigProvider, RemoteActionConfigProvider, buildStyleString, componentRenderers, connectSSE, connectStreaming, createWebActionContext, isMobileViewport, onViewportChange, pxToRem, pxToVw, registerComponent, renderCard, renderStreamingCard, resolveSize, sanitizeHtml, trimIncompleteTag };
+export type { A2UIActionPayload, BotSDKOptions, ButtonProps, CardInstance, CollapseProps, ComponentRenderer, ConnectorConfig, DividerProps, FormField, FormProps, HtmlProps, IconProps, ImageProps, InputProps, LoadingProps, PartialFinalizeResult, PasscodeInputProps, ProgressProps, ProgressSegment, RateProps, RenderCardOptions, SSEConnectOptions, SelectOption, SelectProps, StepIcon, StepItem, StepsProps, StreamingCardInstance, StreamingCardOptions, StreamingConnectOptions, StreamingConnection, TagProps, TextProps, WebActionContextOptions };