@antglobal/copilot-cards-core 0.0.0 → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,853 @@
+/**
+ * Action Runner — executes ActionStep chains defined in card schemas.
+ *
+ * Supported action types:
+ * - **request**: HTTP request (fetch / API call)
+ * - **toast**: Display a toast notification
+ * - **url**: Navigate to a URL
+ * - **setVariable**: Update a variable in the card context
+ * - **emit**: Emit a custom event to the host environment
+ * - **copy**: Copy text to clipboard
+ *
+ * Each step can have `onSuccess` / `onFail` branches for chaining.
+ */
+interface ActionStep {
+    type: 'request' | 'emit' | 'url' | 'setVariable' | 'toast' | 'copy' | (string & {});
+    params: Record<string, any>;
+    /** Action chain to run on success (optional). */
+    onSuccess?: ActionStep[];
+    /** Action chain to run on failure (optional). */
+    onFail?: ActionStep[];
+}
+type ActionStepHandler = (step: ActionStep, context: ActionRunnerContext) => Promise<void> | void;
+interface ActionRunnerContext {
+    /** Platform-level HTTP fetcher (web fetch / mini-program request) */
+    fetch?: (url: string, init?: RequestInit) => Promise<Response>;
+    /** Toast display callback */
+    showToast?: (message: string, level?: string, duration?: number) => void;
+    /** URL navigation callback */
+    navigate?: (url: string, target?: string) => void;
+    /** Variable setter — updates the live variables store */
+    setVariable?: (key: string, value: any) => void;
+    /** Emit event to the host application */
+    emit?: (eventName: string, payload?: any) => void;
+    /** Copy text to clipboard */
+    copyText?: (text: string) => void;
+    /** Variables context for resolving expressions in action params */
+    variables?: Record<string, any>;
+    /** Current bot ID — used to look up bot-scoped handlers */
+    botId?: string;
+    /** Abort signal — used to cancel in-flight requests and polling on dispose */
+    abortSignal?: AbortSignal;
+    /**
+     * Per-instance in-flight request map for request deduplication. Each card
+     * instance should supply its own map so two cards using the same default
+     * `responseKey` ("_response") don't dedupe against each other. When omitted,
+     * a shared module-level map is used (legacy fallback).
+     */
+    inflightRequests?: Map<string, Promise<void>>;
+}
+/**
+ * Register a custom action step handler for a specific bot.
+ */
+declare function registerActionHandler(botId: string, type: string, handler: ActionStepHandler): void;
+/**
+ * Execute a single ActionStep.
+ */
+declare function runActionStep(step: ActionStep, context?: ActionRunnerContext): Promise<void>;
+/**
+ * Execute a chain of ActionSteps sequentially.
+ */
+declare function runActionSteps(steps: ActionStep[], context?: ActionRunnerContext): Promise<void>;
+
+/**
+ * Legacy Schema Compatibility — converts old-format card JSON into
+ * the current CardSchema format so it can be rendered by the SDK.
+ *
+ * Old format:
+ * ```json
+ * {
+ *   "cardType": "common",
+ *   "cardContents": [{ "type": "text", "content": { "text": "hello" } }],
+ *   "text": "card text",
+ *   "extInfo": { "language": "zh-CN" }
+ * }
+ * ```
+ *
+ * Usage:
+ * ```ts
+ * import { convertLegacySchema } from '@antglobal/copilot-cards-core';
+ * const schema = convertLegacySchema(oldJson);
+ * renderCard(container, schema);
+ * ```
+ */
+
+type LegacyTrackingType = 'click' | 'expo';
+interface LegacyTracking {
+    spm: string;
+    type: LegacyTrackingType;
+}
+interface LegacyCardSchema {
+    cardType: 'common' | 'special' | string;
+    cardName?: string;
+    cardContents: LegacyCardContentItem[] | LegacyCardContentItem;
+    text: string;
+    extInfo: {
+        language: string;
+        [key: string]: any;
+    };
+    description?: string;
+    tracking?: LegacyTracking;
+}
+interface LegacyCardContentItem {
+    type: 'timeline' | 'button' | 'image' | 'form' | 'group' | 'text' | 'custom' | string;
+    groupInfo?: Record<string, any>;
+    content: Record<string, any>;
+}
+/**
+ * Detect whether an unknown input is a legacy card schema.
+ *
+ * Checks for the presence of legacy-specific fields (`cardContents`, `cardType`)
+ * and the absence of new-format fields (`rootID`, `elements`).
+ */
+declare function isLegacySchema(input: unknown): input is LegacyCardSchema;
+/** Reset counter (useful for deterministic tests). */
+declare function resetIdCounter(): void;
+/**
+ * Convert a legacy CardSchema to the current CardSchema format.
+ *
+ * @example
+ * ```ts
+ * const newSchema = convertLegacySchema(oldJson);
+ * renderCard(container, newSchema);
+ * ```
+ */
+declare function convertLegacySchema(legacy: LegacyCardSchema): CardSchema;
+
+/**
+ * Schema Parser — resolves a CardSchema into a renderable tree.
+ *
+ * A CardSchema contains a flat `elements` map plus a `rootID` entry point,
+ * global `variables`, and optional global `actions`.
+ */
+
+/** Value that can be a static literal or a `${...}` expression. */
+interface ExpressionValue {
+    type: 'static' | 'expression';
+    value: string;
+}
+/**
+ * Slot layout mode — the key name in `props.slots` determines the layout:
+ * - default: no special layout, children appended directly
+ * - columns: multi-column layout using groups (each group = one column)
+ * - grid: CSS grid with configurable column count and gap
+ * - horizontalScroll: horizontal scrollable container with drag and snap
+ * - carousel: center-focused carousel with scale/opacity effects
+ * - list: vertical list with optional ordered/unordered markers
+ * - float: relative container with absolutely positioned overlays
+ */
+type SlotLayout = 'default' | 'columns' | 'grid' | 'horizontalScroll' | 'carousel' | 'list' | 'float' | 'keyValue' | 'table' | 'chart';
+/**
+ * Content of a named slot.
+ *
+ * - `children`  — flat list of child element IDs (default, grid, horizontalScroll, carousel, list)
+ * - `groups`    — grouped child IDs, each sub-array is one region (columns)
+ * - `config`    — layout-specific parameters (grid columns, list style, float overlays, etc.)
+ *
+ * Grid `config` fields:
+ * - `columns`   — column count (default 2)
+ * - `gap`       — track gap (default '8px')
+ * - `rows`      — opt-in: explicit row count. When set, empty cells keep their
+ *                 height and children can be pinned to a cell via their own
+ *                 `style.gridColumn` / `style.gridRow`. Omit for auto-flow.
+ * - `rowHeight` — min height per row when `rows` is set (default '48px')
+ */
+interface SlotContent {
+    children?: string[];
+    groups?: string[][];
+    config?: Record<string, any>;
+}
+/** A single element inside the card. */
+interface ElementNode {
+    id: string;
+    type: string;
+    props: {
+        style?: Record<string, any>;
+        content?: ExpressionValue | string;
+        slots?: Partial<Record<SlotLayout, SlotContent>>;
+        [key: string]: any;
+    };
+    /** Lifecycle hooks — each is a chain of ActionSteps. */
+    lifecycle?: {
+        onMount?: ActionStep[];
+        onExposed?: ActionStep[];
+        onDestroy?: ActionStep[];
+    };
+    /** Interaction events — each is a chain of ActionSteps or a string reference to schema.actions. */
+    events?: {
+        onClick?: ActionStep[] | string;
+        onChange?: ActionStep[] | string;
+        onSubmit?: ActionStep[] | string;
+        [key: string]: ActionStep[] | string | undefined;
+    };
+    /** Directives that control visibility, disabled state, loops, etc. */
+    directives?: {
+        visible?: string;
+        /** Expression that resolves to truthy → element is disabled (greyed out, no events). */
+        disabled?: string;
+        [key: string]: any;
+    };
+}
+/** Top-level card schema handed to the SDK. */
+interface CardSchema {
+    version: string;
+    rootID: string;
+    elements: Record<string, ElementNode>;
+    variables: Record<string, any>;
+    /** Global action definitions reusable across elements. */
+    actions?: Record<string, ActionStep[]>;
+}
+/** Accepted input — either the current CardSchema or a legacy format. */
+type CardSchemaInput = CardSchema | LegacyCardSchema;
+/**
+ * Normalize any supported schema input into the current CardSchema.
+ *
+ * If the input is already a CardSchema, it is returned as-is.
+ * If it is a legacy format, it is automatically converted.
+ */
+declare function normalizeSchema(input: CardSchemaInput): CardSchema;
+/** Nested tree node produced by the parser — ready for a renderer to consume. */
+interface RenderTreeNode {
+    id: string;
+    type: string;
+    props: Record<string, any>;
+    children: RenderTreeNode[];
+    lifecycle: ElementNode['lifecycle'];
+    events: ElementNode['events'];
+    directives: ElementNode['directives'];
+}
+/**
+ * Parse a CardSchema into a nested RenderTreeNode starting from `rootID`.
+ *
+ * Children are resolved through `props.slots` — each slot's `children` array
+ * lists element IDs that become nested RenderTreeNodes.
+ */
+declare function parseSchema(input: CardSchemaInput): RenderTreeNode;
+/**
+ * Validate a CardSchema and return any error messages.
+ */
+declare function validateSchema(input: CardSchemaInput): string[];
+
+/**
+ * Expression Engine — resolves template variables in card schemas.
+ *
+ * Supports expressions like `${user.name}`, `${items.length > 0}`, etc.
+ * Variables are resolved against a provided data context.
+ *
+ * Also handles the ExpressionValue type from CardSchema:
+ *   { type: 'static', value: 'hello' }  → 'hello'
+ *   { type: 'expression', value: '${user.name}' } → resolved value
+ */
+
+interface ExpressionContext {
+    /** Variable data source for expression resolution */
+    [key: string]: unknown;
+}
+/**
+ * Resolve an ExpressionValue against a variables context.
+ *
+ * @example
+ * ```ts
+ * resolveExpressionValue({ type: 'expression', value: '${user.name}' }, { user: { name: 'Alice' } })
+ * // => 'Alice'
+ * ```
+ */
+declare function resolveExpressionValue(expr: ExpressionValue, context: ExpressionContext): unknown;
+/**
+ * Resolve a single expression string against a context.
+ *
+ * @example
+ * ```ts
+ * resolveExpression('${user.name}', { user: { name: 'Alice' } })
+ * // => 'Alice'
+ * ```
+ */
+declare function resolveExpression(expression: string, context: ExpressionContext): unknown;
+/**
+ * Resolve all expressions within a template string, returning a string result.
+ *
+ * @example
+ * ```ts
+ * interpolate('Hello, ${user.name}! You have ${count} items.', { user: { name: 'Bob' }, count: 5 })
+ * // => 'Hello, Bob! You have 5 items.'
+ * ```
+ */
+declare function interpolate(template: string, context: ExpressionContext): string;
+/**
+ * Safely access a nested value by dot-path (e.g. `user.address.city`).
+ */
+declare function getByPath(obj: unknown, path: string): unknown;
+/**
+ * Checks whether a string contains any expression templates.
+ */
+declare function hasExpression(value: string): boolean;
+/**
+ * Recursively resolve all expressions in a data structure (object / array / string).
+ */
+declare function resolveDeep(data: unknown, context: ExpressionContext): unknown;
+
+/**
+ * ActionRegistry — a simplified, business-friendly API for registering
+ * custom action handlers, scoped by botId.
+ *
+ * Usage:
+ * ```ts
+ * import { registry } from '@antglobal/copilot-cards-core';
+ *
+ * // Register a handler for a specific bot
+ * registry.register('10001', 'bizRequest', async (params, ctx) => {
+ *   const res = await fetch(params.api, { method: params.method, body: JSON.stringify(params.data) });
+ *   if (!res.ok) throw new Error('Business request failed');
+ *   return res.json();
+ * });
+ * ```
+ *
+ * When a handler throws, the action chain is interrupted and `onFail` branch
+ * (if defined on the ActionStep) is executed instead.
+ */
+
+/**
+ * A simplified action handler that receives `params` directly
+ * instead of the full ActionStep object.
+ *
+ * - Return value is ignored (treated as success).
+ * - Throw to signal failure and interrupt the action chain.
+ */
+type SimpleActionHandler = (params: Record<string, any>, context: ActionRunnerContext) => Promise<any> | any;
+declare class ActionRegistry {
+    /** botId → Map<type, handler> */
+    private _handlers;
+    /**
+     * Register a custom action handler for a specific bot.
+     *
+     * The handler receives `step.params` directly. If it throws,
+     * the SDK will execute the step's `onFail` branch (if any)
+     * and stop the remaining action chain.
+     *
+     * @param botId  The bot this handler belongs to
+     * @param type   Action type name (e.g. 'bizRequest')
+     * @param handler  The handler function
+     */
+    register(botId: string, type: string, handler: SimpleActionHandler): void;
+    /**
+     * Remove a previously registered handler for a specific bot.
+     */
+    unregister(botId: string, type: string): void;
+    /**
+     * Check whether a handler is registered for the given bot and type.
+     */
+    has(botId: string, type: string): boolean;
+    /**
+     * Get the list of all registered custom action types for a bot.
+     */
+    getRegisteredTypes(botId: string): string[];
+}
+/** Global action registry singleton. */
+declare const registry: ActionRegistry;
+
+/**
+ * Action Config Provider — abstracts where action chain configurations
+ * come from (local mock, remote API, etc.).
+ *
+ * Action chains are declarative ActionStep[] JSON stored per botId
+ * in the server database. The provider fetches them so the SDK can
+ * register and execute them on the frontend.
+ *
+ * Usage:
+ * ```ts
+ * const provider: ActionConfigProvider = new RemoteActionConfigProvider('https://api.example.com');
+ * const configs = await provider.fetchActions('10001');
+ * // configs = [{ name: 'confirmOrder', steps: [...] }]
+ * ```
+ */
+
+/**
+ * A single action chain configuration — corresponds to one row
+ * in the server-side database.
+ *
+ * The `name` is used as a key to reference this action chain
+ * from schema events (e.g. `onClick: "confirmOrder"`).
+ */
+interface ActionChainConfig {
+    /** Action chain name, e.g. 'confirmOrder', 'submitFeedback' */
+    name: string;
+    /** Declarative action chain — an ordered list of ActionSteps */
+    steps: ActionStep[];
+    /** Optional human-readable description */
+    description?: string;
+}
+/**
+ * Action configuration provider interface.
+ *
+ * Implementations fetch action chain configs for a given botId.
+ * - `LocalActionConfigProvider` — for demo / dev (in-memory data)
+ * - `RemoteActionConfigProvider` — for production (server API)
+ */
+interface ActionConfigProvider {
+    /** Fetch all action chain configs for the given botId */
+    fetchActions(botId: string): Promise<ActionChainConfig[]>;
+}
+/**
+ * Resolve action references in event bindings.
+ *
+ * If an event value is a string (e.g. `"confirmOrder"`), look it up
+ * in the `actionsMap` and return the corresponding ActionStep[].
+ * If it's already an ActionStep[], return as-is.
+ */
+declare function resolveActionRef(eventValue: ActionStep[] | string | undefined, actionsMap: Record<string, ActionStep[]>): ActionStep[] | undefined;
+
+/**
+ * Lifecycle Manager — manages mount / exposed / destroy hooks for card elements.
+ *
+ * Each element can declare lifecycle ActionStep chains (onMount, onExposed, onDestroy).
+ * The manager tracks mounted/exposed state and runs the corresponding chains via
+ * the ActionRunner.
+ */
+
+interface ElementLifecycle {
+    onMount?: ActionStep[];
+    onExposed?: ActionStep[];
+    onDestroy?: ActionStep[];
+}
+type CleanupFn = () => void;
+declare class LifecycleManager {
+    private lifecycles;
+    private mounted;
+    private exposed;
+    /**
+     * Register lifecycle hooks for an element identified by `id`.
+     */
+    register(id: string, lifecycle: ElementLifecycle | undefined): CleanupFn;
+    /**
+     * Remove lifecycle hooks for an element.
+     */
+    unregister(id: string): void;
+    /**
+     * Trigger onMount for an element.
+     */
+    mount(id: string, ctx?: ActionRunnerContext): Promise<void>;
+    /**
+     * Trigger onExposed for an element (entered viewport).
+     */
+    markExposed(id: string, ctx?: ActionRunnerContext): Promise<void>;
+    /**
+     * Trigger onDestroy for an element.
+     */
+    destroy(id: string, ctx?: ActionRunnerContext): Promise<void>;
+    /**
+     * Check if an element is currently mounted.
+     */
+    isMounted(id: string): boolean;
+    /**
+     * Destroy all elements and clear all hooks.
+     */
+    dispose(ctx?: ActionRunnerContext): Promise<void>;
+}
+/**
+ * Create a new LifecycleManager instance.
+ */
+declare function createLifecycleManager(): LifecycleManager;
+
+/**
+ * Streaming Protocol Types — defines the message format for streaming card rendering.
+ *
+ * Inspired by A2UI (Agent-to-User Interface) protocol, adapted for copilot-cards SDK.
+ * Messages are sent as a sequence of JSON commands from Agent to Client,
+ * enabling progressive card construction and incremental updates.
+ */
+
+/**
+ * Union of all streaming command types.
+ * Each command represents a discrete UI mutation operation.
+ */
+type StreamingCommand = CreateSurfaceCommand | UpdateComponentsCommand | UpdateDataModelCommand | DeleteSurfaceCommand | AppendContentCommand;
+/**
+ * Create a rendering surface (card container).
+ *
+ * This is typically the first command sent by the Agent.
+ * The schema can be provided upfront for a complete initial render,
+ * or omitted to create an empty placeholder that's filled incrementally.
+ */
+interface CreateSurfaceCommand {
+    type: 'createSurface';
+    /** Unique identifier for this surface */
+    surfaceId: string;
+    /** Initial card schema (optional — allows empty container creation) */
+    schema?: CardSchemaInput;
+}
+/**
+ * Incrementally update the component tree.
+ *
+ * Uses merge semantics: new elements are added, existing elements
+ * with the same ID are replaced. Elements not mentioned are preserved.
+ */
+interface UpdateComponentsCommand {
+    type: 'updateComponents';
+    surfaceId: string;
+    /** Elements to add or update (merged into existing schema.elements) */
+    elements?: Record<string, ElementNode>;
+    /** Update rootID (for initial setup or root node switching) */
+    rootID?: string;
+    /** Element IDs to remove from the component tree */
+    removeElements?: string[];
+}
+/**
+ * Update the data model (variables).
+ *
+ * Uses JSON Pointer-like path to target a specific location in the
+ * variables tree. Supports both leaf value updates and subtree replacement.
+ */
+interface UpdateDataModelCommand {
+    type: 'updateDataModel';
+    surfaceId: string;
+    /** JSON Pointer path, e.g. '/user/name' or '/orderStatus' */
+    path: string;
+    /** The new value to set at the path */
+    value: any;
+}
+/**
+ * Delete (destroy) a surface and clean up all resources.
+ */
+interface DeleteSurfaceCommand {
+    type: 'deleteSurface';
+    surfaceId: string;
+}
+/**
+ * Append text content to a specific element (optimized for streaming text).
+ *
+ * This avoids sending the full content on every update — only the delta
+ * is transmitted, significantly reducing bandwidth for long streaming text.
+ */
+interface AppendContentCommand {
+    type: 'appendContent';
+    surfaceId: string;
+    /** Target element ID (must be a Text-type component) */
+    elementId: string;
+    /** Text fragment to append to the element's current content */
+    content: string;
+}
+/**
+ * Events emitted by the StreamingEngine to notify the rendering layer
+ * about state changes that need to be reflected in the UI.
+ */
+interface StreamingEngineEvents {
+    /** Surface created — renderer should initialize the container */
+    onSurfaceCreated: (surfaceId: string, schema: CardSchemaInput | null) => void;
+    /** Components updated — renderer should perform incremental DOM updates */
+    onComponentsUpdated: (surfaceId: string, changes: ComponentChange[]) => void;
+    /** Data model updated — renderer should re-resolve affected expressions */
+    onDataModelUpdated: (surfaceId: string, path: string, value: any) => void;
+    /** Content appended — renderer should append text to the target element */
+    onContentAppended: (surfaceId: string, elementId: string, content: string) => void;
+    /** Surface deleted — renderer should destroy the container */
+    onSurfaceDeleted: (surfaceId: string) => void;
+}
+/**
+ * Describes a single component tree change for incremental rendering.
+ */
+interface ComponentChange {
+    /** Type of change */
+    changeType: 'add' | 'update' | 'remove';
+    /** The affected element ID */
+    elementId: string;
+    /** The element definition (present for add/update, absent for remove) */
+    element?: ElementNode;
+    /** Parent element ID (used to determine DOM insertion position) */
+    parentId?: string;
+    /** Index within parent's children (for insertion ordering) */
+    index?: number;
+}
+
+/**
+ * Streaming Message Parser — converts raw byte streams into typed command objects.
+ *
+ * Supports multiple transport formats:
+ * - NDJSON (Newline-Delimited JSON): one JSON object per line
+ * - SSE (Server-Sent Events): `data: {...}` format
+ * - Chunked JSON: handles incomplete JSON that spans multiple chunks
+ *
+ * The parser maintains an internal buffer for handling partial messages
+ * that arrive across chunk boundaries.
+ */
+
+interface StreamingParserOptions {
+    /** Message delimiter, defaults to '\n' (NDJSON) */
+    delimiter?: string;
+    /** Called when a malformed message is encountered */
+    onParseError?: (raw: string, error: Error) => void;
+}
+/**
+ * Streaming message parser that converts raw text chunks from
+ * SSE/WebSocket/fetch streaming into typed StreamingCommand objects.
+ *
+ * @example
+ * ```ts
+ * const parser = new StreamingParser();
+ *
+ * // Feed chunks as they arrive from the transport
+ * socket.onmessage = (e) => {
+ *   const commands = parser.parse(e.data);
+ *   commands.forEach(cmd => engine.apply(cmd));
+ * };
+ *
+ * // Flush remaining buffer when stream ends
+ * socket.onclose = () => {
+ *   const remaining = parser.flush();
+ *   remaining.forEach(cmd => engine.apply(cmd));
+ * };
+ * ```
+ */
+declare class StreamingParser {
+    private buffer;
+    private delimiter;
+    private onParseError?;
+    constructor(options?: StreamingParserOptions);
+    /**
+     * Parse a raw text chunk into an array of streaming commands.
+     *
+     * Incomplete lines are buffered internally and will be completed
+     * when the next chunk arrives (or when flush() is called).
+     *
+     * @param chunk - Raw text chunk from the transport layer
+     * @returns Array of successfully parsed commands (may be empty)
+     */
+    parse(chunk: string): StreamingCommand[];
+    /**
+     * Flush the internal buffer and attempt to parse any remaining content.
+     *
+     * Call this when the stream ends to ensure no messages are lost.
+     *
+     * @returns Array of commands parsed from the remaining buffer
+     */
+    flush(): StreamingCommand[];
+    /**
+     * Reset the parser state, clearing any buffered content.
+     */
+    reset(): void;
+    /**
+     * Parse a single line into a StreamingCommand, handling SSE format.
+     */
+    private parseLine;
+}
+
+/**
+ * Streaming Engine — maintains card state and computes incremental changes.
+ *
+ * The engine acts as the central coordinator between the message parser
+ * and the rendering layer. It maintains a mutable CardSchema state for
+ * each surface and emits fine-grained change events that renderers can
+ * use for efficient incremental updates.
+ *
+ * Key responsibilities:
+ * - Manage multiple concurrent surfaces
+ * - Apply streaming commands to internal state
+ * - Compute parent-child relationships for component changes
+ * - Emit typed events for the rendering layer
+ */
+
+declare class StreamingEngine {
+    /** Active surfaces keyed by surfaceId */
+    private surfaces;
+    /** Event listeners provided by the rendering layer */
+    private listeners;
+    constructor(listeners: StreamingEngineEvents);
+    /**
+     * Apply a single streaming command to the engine state.
+     * This triggers the appropriate event listener after state mutation.
+     */
+    apply(command: StreamingCommand): void;
+    /**
+     * Apply multiple streaming commands in order.
+     */
+    applyBatch(commands: StreamingCommand[]): void;
+    /**
+     * Get the current schema for a surface (read-only snapshot).
+     */
+    getSchema(surfaceId: string): CardSchema | undefined;
+    /**
+     * Get the current variables for a surface.
+     */
+    getVariables(surfaceId: string): Record<string, any> | undefined;
+    /**
+     * Check if a surface exists.
+     */
+    hasSurface(surfaceId: string): boolean;
+    /**
+     * Dispose all surfaces and reset state.
+     */
+    dispose(): void;
+    private handleCreateSurface;
+    private handleUpdateComponents;
+    private handleUpdateDataModel;
+    private handleAppendContent;
+    private handleDeleteSurface;
+    /**
+     * Find the parent element ID for a given element by scanning all slots.
+     */
+    private findParentId;
+    /**
+     * Find the index of a child element within its parent's slot children.
+     */
+    private findChildIndex;
+    /**
+     * Check if an element references the given child ID in any of its slots.
+     */
+    private elementContainsChild;
+    /**
+     * Remove a child ID from all parent element slot references.
+     */
+    private removeFromParentSlots;
+}
+/**
+ * Set a value at a JSON Pointer-like path in an object.
+ *
+ * Path format: '/key1/key2/key3' → obj.key1.key2.key3 = value
+ * Root path '/' sets the entire object.
+ *
+ * Prototype-polluting segments (`__proto__` / `constructor` / `prototype`) are
+ * rejected — the whole write is dropped rather than silently retargeted.
+ *
+ * @example
+ * ```ts
+ * const obj = { user: { name: 'Alice' } };
+ * setByPath(obj, '/user/name', 'Bob');
+ * // obj.user.name === 'Bob'
+ * ```
+ */
+declare function setByPath(obj: Record<string, any>, path: string, value: any): void;
+
+/**
+ * A2UI v0.9 Envelope Adapter — converts Google A2UI protocol messages
+ * into internal StreamingCommand objects.
+ *
+ * A2UI (https://a2ui.org) wraps each message as
+ * `{ "version": "v0.9", "<messageType>": { ... } }`, while the internal
+ * command stream uses a `type` discriminator field. The command names are
+ * already aligned (createSurface / updateComponents / updateDataModel /
+ * deleteSurface), so conversion is mostly an envelope unwrap plus a
+ * component-shape mapping:
+ *
+ * - A2UI components are a flat array with a `component` discriminator and
+ *   top-level props (`{"id":"t1","component":"Text","content":...,"children":[...]}`)
+ * - Internal elements are a map with `type` + nested `props`
+ *   (`{"t1":{"id":"t1","type":"Text","props":{content,slots:{default:{children}}}}}`)
+ *
+ * `appendContent` is accepted in envelope form as a non-standard extension
+ * (A2UI has no token-append primitive; we keep ours for typewriter streaming).
+ */
+
+/** A single A2UI v0.9 component (flat form, `component` discriminator). */
+interface A2UIComponent {
+    id: string;
+    component: string;
+    /** Child component IDs — mapped to `props.slots.default.children`. */
+    children?: string[];
+    /** Layout slots pass-through (grid/chart/... — catalog extension). */
+    slots?: Record<string, any>;
+    /** visible/disabled directives (top-level, same as internal schema). */
+    directives?: Record<string, any>;
+    /** Event bindings pass-through (onClick etc.). */
+    events?: Record<string, any>;
+    /** Any other field is treated as a component prop. */
+    [prop: string]: any;
+}
+/** A2UI v0.9 message envelope: exactly one action key per message. */
+interface A2UIEnvelope {
+    version?: string;
+    createSurface?: {
+        surfaceId: string;
+        catalogId?: string;
+        theme?: any;
+        sendDataModel?: boolean;
+        schema?: any;
+    };
+    updateComponents?: {
+        surfaceId: string;
+        components?: A2UIComponent[];
+    };
+    updateDataModel?: {
+        surfaceId: string;
+        path?: string;
+        value?: any;
+    };
+    deleteSurface?: {
+        surfaceId: string;
+    };
+    /** Non-standard extension: token-level text append (see module doc). */
+    appendContent?: {
+        surfaceId: string;
+        elementId: string;
+        content: string;
+    };
+}
+/**
+ * Check whether a parsed JSON object looks like an A2UI envelope
+ * (no internal `type` discriminator, but exactly an A2UI action key).
+ */
+declare function isA2UIEnvelope(msg: unknown): msg is A2UIEnvelope;
+/**
+ * Convert a flat A2UI component into an internal ElementNode.
+ */
+declare function a2uiComponentToElement(comp: A2UIComponent): ElementNode;
+/**
+ * Convert an A2UI v0.9 envelope message into an internal StreamingCommand.
+ * Returns null for unrecognized messages.
+ *
+ * Notes:
+ * - `catalogId` / `theme` / `sendDataModel` are accepted but currently ignored
+ *   (component catalog is built into the renderer).
+ * - `createSurface.schema` is a convenience extension: a full internal schema
+ *   may be attached for template-style cards.
+ * - A component with `id: "root"` sets the surface rootID (A2UI convention).
+ */
+declare function a2uiToCommand(msg: A2UIEnvelope): StreamingCommand | null;
+
+/**
+ * Partial Schema Extractor — pulls completed pieces out of an INCOMPLETE
+ * card-schema JSON text while it is still streaming in from an LLM.
+ *
+ * A card schema is `{"version","rootID","variables","elements":{id:{...},...}}`.
+ * The `elements` map is flat, so every element value becomes parseable the
+ * moment its own braces balance — long before the whole document closes.
+ * This enables progressive rendering: blocks mount as they complete instead
+ * of waiting out the entire (possibly multi-thousand-token) JSON.
+ *
+ * Design constraints:
+ * - Pure & stateless: call it every frame with the ACCUMULATED text
+ *   (append-only); identical input → identical output.
+ * - String-aware scanning: braces/quotes inside JSON string values
+ *   (including escapes) never confuse the balancer.
+ * - Malformed single elements are skipped (the final full-document parse
+ *   in the caller is the correctness backstop).
+ */
+
+interface PartialSchemaResult {
+    version?: string;
+    rootID?: string;
+    variables?: Record<string, any>;
+    /** Elements whose own JSON closed and parsed successfully. */
+    elements: Record<string, ElementNode>;
+    /** True when the WHOLE document parsed — result is then the full schema. */
+    complete: boolean;
+}
+/**
+ * Extract completed pieces from (possibly incomplete) schema JSON text.
+ *
+ * @param text - Accumulated schema JSON text, starting at the document `{`.
+ *               Surrounding whitespace is tolerated; surrounding prose is not
+ *               (strip markers like `<card>` before calling).
+ */
+declare function extractPartialSchema(text: string): PartialSchemaResult;
+
+export { ActionRegistry, LifecycleManager, StreamingEngine, StreamingParser, a2uiComponentToElement, a2uiToCommand, convertLegacySchema, createLifecycleManager, extractPartialSchema, getByPath, hasExpression, interpolate, isA2UIEnvelope, isLegacySchema, normalizeSchema, parseSchema, registerActionHandler, registry, resetIdCounter, resolveActionRef, resolveDeep, resolveExpression, resolveExpressionValue, runActionStep, runActionSteps, setByPath, validateSchema };
+export type { A2UIComponent, A2UIEnvelope, ActionChainConfig, ActionConfigProvider, ActionRunnerContext, ActionStep, ActionStepHandler, AppendContentCommand, CardSchema, CardSchemaInput, CleanupFn, ComponentChange, CreateSurfaceCommand, DeleteSurfaceCommand, ElementLifecycle, ElementNode, ExpressionContext, ExpressionValue, LegacyCardContentItem, LegacyCardSchema, LegacyTracking, LegacyTrackingType, PartialSchemaResult, RenderTreeNode, SimpleActionHandler, SlotContent, SlotLayout, StreamingCommand, StreamingEngineEvents, StreamingParserOptions, UpdateComponentsCommand, UpdateDataModelCommand };