@antglobal/copilot-cards-core 0.0.0 → 1.0.0

package/dist/index.esm.js

@@ -0,0 +1,2072 @@
+/**
+ * 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
+ */
+/**
+ * Resolve an ExpressionValue against a variables context.
+ *
+ * @example
+ * ```ts
+ * resolveExpressionValue({ type: 'expression', value: '${user.name}' }, { user: { name: 'Alice' } })
+ * // => 'Alice'
+ * ```
+ */
+function resolveExpressionValue(expr, context) {
+    if (expr.type === 'static') {
+        return expr.value;
+    }
+    return resolveExpression(expr.value, context);
+}
+/**
+ * Resolve a single expression string against a context.
+ *
+ * @example
+ * ```ts
+ * resolveExpression('${user.name}', { user: { name: 'Alice' } })
+ * // => 'Alice'
+ * ```
+ */
+function resolveExpression(expression, context) {
+    const trimmed = expression.trim();
+    // If the entire string is a SINGLE expression like `${xxx}`, return the raw value.
+    // Guard: no second `${` may appear — otherwise the string is a concatenation of
+    // multiple expressions (e.g. `${a}${b}`), which must go through interpolation
+    // instead of being mis-parsed as one expression. Checking for a second `${`
+    // (rather than an early `}`) keeps single expressions containing a literal `}`
+    // (e.g. `${x === '}' ? 'a' : 'b'}`) on the original single-expression path.
+    if (trimmed.startsWith('${') &&
+        trimmed.endsWith('}') &&
+        trimmed.indexOf('${', 2) === -1) {
+        const inner = trimmed.slice(2, -1).trim();
+        // Simple path (e.g. "user.name") — fast path
+        if (/^[a-zA-Z_$][a-zA-Z0-9_$.]*$/.test(inner)) {
+            return getByPath$1(context, inner);
+        }
+        // Complex expression (ternary, comparison, logical, etc.)
+        return evaluateExpression(inner, context);
+    }
+    // Otherwise do string interpolation
+    return interpolate(expression, context);
+}
+/**
+ * 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.'
+ * ```
+ */
+function interpolate(template, context) {
+    return template.replace(/\$\{([^}]+)\}/g, (_, inner) => {
+        const trimmed = inner.trim();
+        // Simple path — fast path
+        if (/^[a-zA-Z_$][a-zA-Z0-9_$.]*$/.test(trimmed)) {
+            const value = getByPath$1(context, trimmed);
+            return value == null ? '' : String(value);
+        }
+        // Complex expression
+        const value = evaluateExpression(trimmed, context);
+        return value == null ? '' : String(value);
+    });
+}
+/**
+ * Safely access a nested value by dot-path (e.g. `user.address.city`).
+ */
+function getByPath$1(obj, path) {
+    return path.split('.').reduce((current, key) => {
+        if (current == null)
+            return undefined;
+        return current[key];
+    }, obj);
+}
+function tokenize(expr) {
+    const tokens = [];
+    let i = 0;
+    while (i < expr.length) {
+        const ch = expr[i];
+        // Whitespace
+        if (/\s/.test(ch)) {
+            i++;
+            continue;
+        }
+        // String literal (single or double quote)
+        if (ch === '\'' || ch === '"') {
+            const quote = ch;
+            let str = '';
+            i++; // skip opening quote
+            while (i < expr.length && expr[i] !== quote) {
+                if (expr[i] === '\\' && i + 1 < expr.length) {
+                    str += expr[i + 1];
+                    i += 2;
+                }
+                else {
+                    str += expr[i];
+                    i++;
+                }
+            }
+            i++; // skip closing quote
+            tokens.push({ type: 'string', value: str });
+            continue;
+        }
+        // Number
+        if (/[0-9]/.test(ch) || (ch === '-' && i + 1 < expr.length && /[0-9]/.test(expr[i + 1]) && (tokens.length === 0 || tokens[tokens.length - 1].type === 'op' || tokens[tokens.length - 1].type === 'question' || tokens[tokens.length - 1].type === 'colon'))) {
+            let num = ch;
+            i++;
+            while (i < expr.length && /[0-9.]/.test(expr[i])) {
+                num += expr[i];
+                i++;
+            }
+            tokens.push({ type: 'number', value: num });
+            continue;
+        }
+        // Multi-char operators
+        const twoChar = expr.slice(i, i + 3);
+        if (twoChar === '===' || twoChar === '!==') {
+            tokens.push({ type: 'op', value: twoChar });
+            i += 3;
+            continue;
+        }
+        const pair = expr.slice(i, i + 2);
+        if (pair === '==' || pair === '!=' || pair === '>=' || pair === '<=' || pair === '&&' || pair === '||') {
+            tokens.push({ type: 'op', value: pair });
+            i += 2;
+            continue;
+        }
+        // Single-char operators
+        if (ch === '>' || ch === '<') {
+            tokens.push({ type: 'op', value: ch });
+            i++;
+            continue;
+        }
+        if (ch === '!') {
+            tokens.push({ type: 'op', value: '!' });
+            i++;
+            continue;
+        }
+        if (ch === '?') {
+            tokens.push({ type: 'question', value: '?' });
+            i++;
+            continue;
+        }
+        if (ch === ':') {
+            tokens.push({ type: 'colon', value: ':' });
+            i++;
+            continue;
+        }
+        if (ch === '(' || ch === ')') {
+            tokens.push({ type: 'paren', value: ch });
+            i++;
+            continue;
+        }
+        // Identifiers / keywords (variable paths like user.name)
+        if (/[a-zA-Z_$]/.test(ch)) {
+            let id = '';
+            while (i < expr.length && /[a-zA-Z0-9_$.]/.test(expr[i])) {
+                id += expr[i];
+                i++;
+            }
+            if (id === 'true' || id === 'false')
+                tokens.push({ type: 'boolean', value: id });
+            else if (id === 'null')
+                tokens.push({ type: 'null', value: id });
+            else if (id === 'undefined')
+                tokens.push({ type: 'undefined', value: id });
+            else
+                tokens.push({ type: 'ident', value: id });
+            continue;
+        }
+        // Skip unknown characters
+        i++;
+    }
+    return tokens;
+}
+/** Evaluate a tokenized expression against a variable context. */
+function evaluateExpression(expr, context) {
+    const tokens = tokenize(expr);
+    let pos = 0;
+    function peek() { return tokens[pos]; }
+    function consume() { return tokens[pos++]; }
+    function expect(type, value) {
+        const t = consume();
+        if (!t || t.type !== type || (value !== undefined && t.value !== value)) {
+            throw new Error(`[ExpressionEngine] Expected ${type}${value ? ` '${value}'` : ''}, got ${t ? `'${t.value}'` : 'EOF'}`);
+        }
+        return t;
+    }
+    // Precedence (low → high): ternary → || → && → equality → relational → unary → atom
+    function parseTernary() {
+        const cond = parseOr();
+        if (peek()?.type === 'question') {
+            consume(); // ?
+            const truthy = parseTernary();
+            expect('colon');
+            const falsy = parseTernary();
+            return cond ? truthy : falsy;
+        }
+        return cond;
+    }
+    function parseOr() {
+        let left = parseAnd();
+        while (peek()?.value === '||') {
+            consume();
+            left = left || parseAnd();
+        }
+        return left;
+    }
+    function parseAnd() {
+        let left = parseEquality();
+        while (peek()?.value === '&&') {
+            consume();
+            left = left && parseEquality();
+        }
+        return left;
+    }
+    function parseEquality() {
+        let left = parseRelational();
+        while (peek()?.value === '===' || peek()?.value === '!==' || peek()?.value === '==' || peek()?.value === '!=') {
+            const op = consume().value;
+            const right = parseRelational();
+            if (op === '===' || op === '==')
+                left = left === right;
+            else
+                left = left !== right;
+        }
+        return left;
+    }
+    function parseRelational() {
+        let left = parseUnary();
+        while (peek()?.value === '>' || peek()?.value === '<' || peek()?.value === '>=' || peek()?.value === '<=') {
+            const op = consume().value;
+            const right = parseUnary();
+            if (op === '>')
+                left = left > right;
+            else if (op === '<')
+                left = left < right;
+            else if (op === '>=')
+                left = left >= right;
+            else
+                left = left <= right;
+        }
+        return left;
+    }
+    function parseUnary() {
+        if (peek()?.value === '!') {
+            consume();
+            return !parseUnary();
+        }
+        return parseAtom();
+    }
+    function parseAtom() {
+        const t = peek();
+        if (!t)
+            return undefined;
+        if (t.type === 'string') {
+            consume();
+            return t.value;
+        }
+        if (t.type === 'number') {
+            consume();
+            return Number(t.value);
+        }
+        if (t.type === 'boolean') {
+            consume();
+            return t.value === 'true';
+        }
+        if (t.type === 'null') {
+            consume();
+            return null;
+        }
+        if (t.type === 'undefined') {
+            consume();
+            return undefined;
+        }
+        if (t.type === 'ident') {
+            consume();
+            return getByPath$1(context, t.value);
+        }
+        if (t.type === 'paren' && t.value === '(') {
+            consume();
+            const val = parseTernary();
+            expect('paren', ')');
+            return val;
+        }
+        // Fallback
+        consume();
+        return undefined;
+    }
+    const result = parseTernary();
+    return result;
+}
+/**
+ * Checks whether a string contains any expression templates.
+ */
+function hasExpression(value) {
+    return /\$\{[^}]+\}/.test(value);
+}
+/**
+ * Recursively resolve all expressions in a data structure (object / array / string).
+ */
+function resolveDeep(data, context) {
+    if (typeof data === 'string') {
+        return hasExpression(data) ? resolveExpression(data, context) : data;
+    }
+    if (Array.isArray(data)) {
+        return data.map((item) => resolveDeep(item, context));
+    }
+    if (data !== null && typeof data === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(data)) {
+            result[key] = resolveDeep(value, context);
+        }
+        return result;
+    }
+    return data;
+}
+
+/**
+ * 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.
+ */
+// ─── Constants ──────────────────────────────────────────────────
+/** Default timeout (ms) for a single HTTP request when no poll is configured. */
+const DEFAULT_REQUEST_TIMEOUT = 30000;
+// ─── Request Deduplication ──────────────────────────────────────
+/**
+ * Shared fallback in-flight request map keyed by responseKey. Used only when a
+ * context does not provide its own `inflightRequests` map. Prevents duplicate
+ * request actions (e.g. user double-clicks a button) from spawning concurrent
+ * request/polling loops that race on the same variable.
+ *
+ * Note: prefer a per-instance map via `ctx.inflightRequests` — this shared map
+ * would otherwise let two independent cards using the default `_response` key
+ * dedupe against each other.
+ */
+const sharedInflightRequests = new Map();
+// ─── Built-in Handlers ───────────────────────────────────────────
+/**
+ * Try to parse response body as JSON, fall back to plain text.
+ */
+async function parseResponseBody(response) {
+    const contentType = response.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json')) {
+        return response.json();
+    }
+    // Some APIs return JSON without proper content-type; try JSON first
+    const text = await response.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Write response data into the variables store so downstream actions
+ * can reference it via expressions like `${_response.orderId}`.
+ *
+ * The variable key defaults to `_response` but can be overridden via
+ * `params.responseKey` when a card has multiple request actions.
+ *
+ * @param silent - If true, only write to ctx.variables without calling
+ *   setVariable (avoids triggering re-render during polling iterations).
+ */
+function writeResponseVariable(ctx, responseKey, data, silent = false) {
+    if (ctx.variables) {
+        ctx.variables[responseKey] = data;
+    }
+    if (!silent) {
+        ctx.setVariable?.(responseKey, data);
+    }
+}
+/**
+ * Read a nested field from an object by dot-path, e.g. "data.status".
+ */
+function getByPath(obj, path) {
+    return path.split('.').reduce((cur, key) => cur?.[key], obj);
+}
+/**
+ * Execute a single fetch call, parse body, write to variables.
+ * Returns the parsed response data object `{ ok, status, data }`.
+ *
+ * @param silent - If true, write to variables without triggering re-render.
+ */
+async function executeRequest(fetcher, url, init, ctx, varKey, silent = false, timeoutMs) {
+    // Combine the card-level abortSignal with a per-request timeout signal
+    const signals = [];
+    if (ctx.abortSignal)
+        signals.push(ctx.abortSignal);
+    if (timeoutMs && timeoutMs > 0)
+        signals.push(AbortSignal.timeout(timeoutMs));
+    const combinedSignal = signals.length > 0
+        ? (signals.length === 1 ? signals[0] : AbortSignal.any(signals))
+        : undefined;
+    const response = await fetcher(url, { ...init, signal: combinedSignal });
+    const body = await parseResponseBody(response);
+    const result = {
+        ok: response.ok,
+        status: response.status,
+        data: body,
+    };
+    writeResponseVariable(ctx, varKey, result, silent);
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+    }
+    return result;
+}
+/**
+ * Create a delay that can be aborted via AbortSignal.
+ * Resolves after `ms` milliseconds, or rejects immediately if signal fires.
+ */
+function abortableDelay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new DOMException('Aborted', 'AbortError'));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new DOMException('Aborted', 'AbortError'));
+        }, { once: true });
+    });
+}
+const handleRequest = async (step, ctx) => {
+    const fetcher = ctx.fetch ?? globalThis.fetch;
+    if (!fetcher) {
+        throw new Error('[ActionRunner] No fetch implementation available');
+    }
+    const { url, method, headers, body, responseKey, poll, timeout } = step.params;
+    const varKey = responseKey ?? '_response';
+    // Per-instance dedup map when provided; shared fallback otherwise.
+    const inflight = ctx.inflightRequests ?? sharedInflightRequests;
+    // ── Deduplication: skip if same responseKey is already in-flight ──
+    if (inflight.has(varKey)) {
+        console.warn(`[ActionRunner] Request "${varKey}" already in-flight, skipping duplicate`);
+        return;
+    }
+    // Auto-set Content-Type for JSON body
+    const mergedHeaders = { ...headers };
+    if (body && !mergedHeaders['Content-Type'] && !mergedHeaders['content-type']) {
+        mergedHeaders['Content-Type'] = 'application/json';
+    }
+    const init = {
+        method: method ?? 'GET',
+        headers: mergedHeaders,
+        body: body ? JSON.stringify(body) : undefined,
+    };
+    // Per-request timeout: use schema-defined timeout, or default for non-poll requests
+    const requestTimeout = timeout ?? (poll ? undefined : DEFAULT_REQUEST_TIMEOUT);
+    const task = (async () => {
+        try {
+            const result = await executeRequest(fetcher, url, init, ctx, varKey, false, requestTimeout);
+            // ── Polling mode ──────────────────────────────────────────
+            if (poll) {
+                const { interval = 3000, maxAttempts = 10, until, stopValues = [], } = poll;
+                let currentValue = getByPath(result.data, until);
+                for (let attempt = 1; attempt < maxAttempts && !stopValues.includes(currentValue); attempt++) {
+                    // Abortable sleep — clears timer on dispose
+                    await abortableDelay(interval, ctx.abortSignal);
+                    // Polling iterations write silently (no re-render) to avoid
+                    // DOM rebuild that would destroy user focus / input state
+                    const pollResult = await executeRequest(fetcher, url, init, ctx, varKey, /* silent */ true, requestTimeout);
+                    currentValue = getByPath(pollResult.data, until);
+                }
+                // Polling finished — final write triggers re-render so UI shows result
+                if (!stopValues.includes(currentValue)) {
+                    writeResponseVariable(ctx, varKey, {
+                        ...ctx.variables?.[varKey],
+                        _timeout: true,
+                    });
+                    throw new Error(`Polling timeout after ${maxAttempts} attempts`);
+                }
+                // Terminal value reached — write the final state with re-render
+                writeResponseVariable(ctx, varKey, ctx.variables?.[varKey] ?? {});
+            }
+            if (step.onSuccess) {
+                await runActionSteps(step.onSuccess, ctx);
+            }
+        }
+        catch (error) {
+            // AbortError = card disposed or timeout, check which
+            if (error instanceof DOMException && error.name === 'AbortError') {
+                // If card abortSignal is aborted → dispose, silently stop
+                if (ctx.abortSignal?.aborted) {
+                    return;
+                }
+                // Otherwise it's a timeout — treat as error
+                const timeoutError = new Error(`Request timeout after ${requestTimeout}ms`);
+                writeResponseVariable(ctx, varKey, {
+                    ok: false,
+                    status: 0,
+                    data: null,
+                    _timeout: true,
+                    message: timeoutError.message,
+                });
+                if (step.onFail) {
+                    await runActionSteps(step.onFail, ctx);
+                }
+                else {
+                    throw timeoutError;
+                }
+                return;
+            }
+            // Network errors (no response) — also write to variables
+            if (!ctx.variables?.[varKey]) {
+                writeResponseVariable(ctx, varKey, {
+                    ok: false,
+                    status: 0,
+                    data: null,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+            if (step.onFail) {
+                await runActionSteps(step.onFail, ctx);
+            }
+            else {
+                throw error;
+            }
+        }
+        finally {
+            inflight.delete(varKey);
+        }
+    })();
+    inflight.set(varKey, task);
+    await task;
+};
+const handleToast = (step, ctx) => {
+    const { message, level, duration } = step.params;
+    if (ctx.showToast) {
+        ctx.showToast(message, level, duration);
+    }
+    else {
+        console.log(`[Toast] ${level ?? 'info'}: ${message}`);
+    }
+};
+const handleUrl = (step, ctx) => {
+    const { url, target } = step.params;
+    if (ctx.navigate) {
+        ctx.navigate(url, target);
+    }
+    else if (typeof window !== 'undefined') {
+        window.open(url, target ?? '_blank');
+    }
+};
+const handleSetVariable = (step, ctx) => {
+    const { key, value } = step.params;
+    if (ctx.setVariable) {
+        ctx.setVariable(key, value);
+    }
+    else {
+        console.warn('[ActionRunner] No setVariable handler registered');
+    }
+};
+const handleEmit = (step, ctx) => {
+    const { event, payload } = step.params;
+    if (ctx.emit) {
+        ctx.emit(event, payload);
+    }
+    else {
+        console.warn(`[ActionRunner] No emit handler; event="${event}"`);
+    }
+};
+const handleCopy = (step, ctx) => {
+    const { text } = step.params;
+    if (ctx.copyText) {
+        ctx.copyText(text);
+    }
+    else if (typeof navigator !== 'undefined' && navigator.clipboard) {
+        navigator.clipboard.writeText(text);
+    }
+    else {
+        console.warn('[ActionRunner] No clipboard API available');
+    }
+};
+// ─── Handler Map ─────────────────────────────────────────────────
+const builtInHandlers = {
+    request: handleRequest,
+    toast: handleToast,
+    url: handleUrl,
+    setVariable: handleSetVariable,
+    emit: handleEmit,
+    copy: handleCopy,
+};
+const customHandlers = new Map();
+/**
+ * Register a custom action step handler for a specific bot.
+ */
+function registerActionHandler(botId, type, handler) {
+    let botMap = customHandlers.get(botId);
+    if (!botMap) {
+        botMap = new Map();
+        customHandlers.set(botId, botMap);
+    }
+    botMap.set(type, handler);
+}
+/**
+ * Execute a single ActionStep.
+ */
+async function runActionStep(step, context = {}) {
+    const handler = customHandlers.get(context.botId ?? '')?.get(step.type) ?? builtInHandlers[step.type];
+    if (!handler) {
+        console.warn(`[ActionRunner] Unknown action type: ${step.type}`);
+        return;
+    }
+    // Resolve expression variables in params (e.g. '${order_id}' → 'ORDER_666')
+    const resolvedStep = context.variables
+        ? { ...step, params: resolveDeep(step.params, context.variables) }
+        : step;
+    await handler(resolvedStep, context);
+}
+/**
+ * Execute a chain of ActionSteps sequentially.
+ */
+async function runActionSteps(steps, context = {}) {
+    for (const step of steps) {
+        await runActionStep(step, context);
+    }
+}
+
+var index = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    registerActionHandler: registerActionHandler,
+    runActionStep: runActionStep,
+    runActionSteps: runActionSteps
+});
+
+/**
+ * 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.
+ */
+// ─── ActionRegistry ─────────────────────────────────────────────
+class ActionRegistry {
+    constructor() {
+        /** botId → Map<type, handler> */
+        this._handlers = new Map();
+    }
+    /**
+     * 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, type, handler) {
+        let botMap = this._handlers.get(botId);
+        if (!botMap) {
+            botMap = new Map();
+            this._handlers.set(botId, botMap);
+        }
+        botMap.set(type, handler);
+        // Bridge to core's low-level registerActionHandler (botId-scoped)
+        const wrappedHandler = async (step, context) => {
+            try {
+                await handler(step.params, context);
+                if (step.onSuccess) {
+                    const { runActionSteps } = await Promise.resolve().then(function () { return index; });
+                    await runActionSteps(step.onSuccess, context);
+                }
+            }
+            catch (error) {
+                if (step.onFail) {
+                    const { runActionSteps } = await Promise.resolve().then(function () { return index; });
+                    await runActionSteps(step.onFail, context);
+                }
+                else {
+                    throw error;
+                }
+            }
+        };
+        registerActionHandler(botId, type, wrappedHandler);
+    }
+    /**
+     * Remove a previously registered handler for a specific bot.
+     */
+    unregister(botId, type) {
+        const botMap = this._handlers.get(botId);
+        if (botMap) {
+            botMap.delete(type);
+            if (botMap.size === 0)
+                this._handlers.delete(botId);
+        }
+        registerActionHandler(botId, type, () => {
+            console.warn(`[ActionRegistry] Handler "${type}" for bot "${botId}" has been unregistered`);
+        });
+    }
+    /**
+     * Check whether a handler is registered for the given bot and type.
+     */
+    has(botId, type) {
+        return this._handlers.get(botId)?.has(type) ?? false;
+    }
+    /**
+     * Get the list of all registered custom action types for a bot.
+     */
+    getRegisteredTypes(botId) {
+        return Array.from(this._handlers.get(botId)?.keys() ?? []);
+    }
+}
+// ─── Singleton ──────────────────────────────────────────────────
+/** Global action registry singleton. */
+const registry = new 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: [...] }]
+ * ```
+ */
+// ─── Helpers ────────────────────────────────────────────────────
+/**
+ * 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.
+ */
+function resolveActionRef(eventValue, actionsMap) {
+    if (eventValue == null)
+        return undefined;
+    if (typeof eventValue === 'string') {
+        const steps = actionsMap[eventValue];
+        if (!steps) {
+            console.warn(`[ActionProvider] Unknown action reference: "${eventValue}"`);
+            return undefined;
+        }
+        return steps;
+    }
+    return eventValue;
+}
+
+/**
+ * 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);
+ * ```
+ */
+// ─── Detection ──────────────────────────────────────────────────
+/**
+ * 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`).
+ */
+function isLegacySchema(input) {
+    if (input == null || typeof input !== 'object')
+        return false;
+    const obj = input;
+    return ('cardContents' in obj &&
+        'cardType' in obj &&
+        !('rootID' in obj) &&
+        !('elements' in obj));
+}
+// ─── ID Generator ───────────────────────────────────────────────
+let _idCounter = 0;
+function uid(prefix = 'el') {
+    return `${prefix}_${++_idCounter}`;
+}
+/** Reset counter (useful for deterministic tests). */
+function resetIdCounter() {
+    _idCounter = 0;
+}
+// ─── Type Mapping ───────────────────────────────────────────────
+/**
+ * Map legacy component type names to new schema type names.
+ * Extensible — add more mappings as new component types are built.
+ */
+const TYPE_MAP = {
+    text: 'Text',
+    button: 'Button',
+    image: 'Image',
+    form: 'Form',
+    timeline: 'Timeline',
+    group: 'ColumnSet',
+    custom: 'Custom',
+};
+function mapType(legacyType) {
+    return TYPE_MAP[legacyType] ?? legacyType;
+}
+// ─── Content → Props Converters ─────────────────────────────────
+/**
+ * Convert a legacy `text` content item to ElementNode props.
+ *
+ * Legacy text content may look like:
+ * ```json
+ * { "text": "hello", "color": "red", "fontSize": 16, "bold": true, ... }
+ * ```
+ */
+function convertTextContent(content) {
+    const { text, color, fontSize, fontWeight, bold, align, maxLines, style, ...rest } = content;
+    const props = { ...rest };
+    // content field
+    if (text != null) {
+        props.content = staticValue(String(text));
+    }
+    // Merge style
+    const mergedStyle = { ...style };
+    if (color)
+        mergedStyle.color = color;
+    if (fontSize)
+        mergedStyle.fontSize = fontSize;
+    if (fontWeight)
+        mergedStyle.fontWeight = fontWeight;
+    if (bold)
+        mergedStyle.fontWeight = 'bold';
+    if (align)
+        mergedStyle.textAlign = align;
+    if (Object.keys(mergedStyle).length > 0) {
+        props.style = mergedStyle;
+    }
+    if (maxLines)
+        props.maxLines = maxLines;
+    return props;
+}
+/**
+ * Convert a legacy `button` content item to ElementNode props.
+ *
+ * Legacy button content may look like:
+ * ```json
+ * { "label": "Submit", "url": "https://...", "style": { ... } }
+ * ```
+ */
+function convertButtonContent(content) {
+    const { label, text, url, actionType, style, ...rest } = content;
+    const props = { ...rest };
+    // Button display text
+    const displayText = label ?? text;
+    if (displayText != null) {
+        props.content = staticValue(String(displayText));
+    }
+    if (style)
+        props.style = style;
+    // Convert URL / action to events
+    let events;
+    if (url) {
+        events = {
+            onClick: [{ type: 'url', params: { url } }],
+        };
+    }
+    return { props, events };
+}
+/**
+ * Convert a legacy `image` content item to ElementNode props.
+ *
+ * Legacy image content may look like:
+ * ```json
+ * { "src": "https://...", "alt": "desc", "width": 200, "height": 100 }
+ * ```
+ */
+function convertImageContent(content) {
+    const { src, url, alt, width, height, style, ...rest } = content;
+    const props = { ...rest };
+    props.src = src ?? url;
+    if (alt)
+        props.alt = alt;
+    const mergedStyle = { ...style };
+    if (width)
+        mergedStyle.width = width;
+    if (height)
+        mergedStyle.height = height;
+    if (Object.keys(mergedStyle).length > 0) {
+        props.style = mergedStyle;
+    }
+    return props;
+}
+/**
+ * Convert a legacy `form` content item to ElementNode props.
+ * Passes through all content properties as props.
+ */
+function convertFormContent(content) {
+    return { ...content };
+}
+/**
+ * Generic fallback converter — passes content through as props.
+ */
+function convertGenericContent(content) {
+    return { ...content };
+}
+// ─── Main Converter ─────────────────────────────────────────────
+/**
+ * Convert a legacy CardSchema to the current CardSchema format.
+ *
+ * @example
+ * ```ts
+ * const newSchema = convertLegacySchema(oldJson);
+ * renderCard(container, newSchema);
+ * ```
+ */
+function convertLegacySchema(legacy) {
+    resetIdCounter();
+    const elements = {};
+    // Normalise cardContents to array
+    const contents = Array.isArray(legacy.cardContents)
+        ? legacy.cardContents
+        : [legacy.cardContents];
+    // Convert each content item, collecting top-level child IDs
+    const childIds = [];
+    for (const item of contents) {
+        const converted = convertContentItem(item, elements, legacy.tracking);
+        childIds.push(converted.id);
+    }
+    // Create root container element
+    const rootId = uid('root');
+    if (childIds.length === 1) {
+        // Single child — promote it as root directly
+        const onlyChild = elements[childIds[0]];
+        onlyChild.id = rootId;
+        delete elements[childIds[0]];
+        elements[rootId] = onlyChild;
+    }
+    else {
+        // Multiple children — wrap in a ColumnSet container
+        elements[rootId] = {
+            id: rootId,
+            type: 'ColumnSet',
+            props: {
+                slots: {
+                    default: { children: childIds },
+                },
+            },
+        };
+    }
+    // Build variables from legacy metadata
+    const variables = {
+        _legacy: {
+            cardType: legacy.cardType,
+            cardName: legacy.cardName,
+            text: legacy.text,
+            description: legacy.description,
+            language: legacy.extInfo?.language,
+            extInfo: legacy.extInfo,
+        },
+    };
+    return {
+        version: '1.0',
+        rootID: rootId,
+        elements,
+        variables,
+    };
+}
+// ─── Recursive Item Converter ───────────────────────────────────
+function convertContentItem(item, elements, tracking) {
+    const id = uid(item.type);
+    const type = mapType(item.type);
+    const content = item.content ?? {};
+    let props;
+    let events;
+    // Type-specific conversion
+    switch (item.type) {
+        case 'text':
+            props = convertTextContent(content);
+            break;
+        case 'button': {
+            const result = convertButtonContent(content);
+            props = result.props;
+            events = result.events;
+            break;
+        }
+        case 'image':
+            props = convertImageContent(content);
+            break;
+        case 'form':
+            props = convertFormContent(content);
+            break;
+        case 'group': {
+            // Group contains nested items
+            const groupChildren = Array.isArray(content.items)
+                ? content.items
+                : content.children
+                    ? (Array.isArray(content.children) ? content.children : [content.children])
+                    : [];
+            const groupChildIds = [];
+            for (const child of groupChildren) {
+                const childNode = convertContentItem(child, elements, tracking);
+                groupChildIds.push(childNode.id);
+            }
+            props = {
+                slots: {
+                    default: { children: groupChildIds },
+                },
+            };
+            // Merge groupInfo
+            if (item.groupInfo) {
+                props.groupInfo = item.groupInfo;
+            }
+            break;
+        }
+        default:
+            props = convertGenericContent(content);
+            break;
+    }
+    // Apply tracking as lifecycle / events
+    const lifecycle = convertTracking(tracking);
+    const element = {
+        id,
+        type,
+        props,
+        ...(events ? { events } : {}),
+        ...(lifecycle ? { lifecycle } : {}),
+    };
+    elements[id] = element;
+    return element;
+}
+// ─── Tracking → Lifecycle/Events ────────────────────────────────
+function convertTracking(tracking) {
+    if (!tracking)
+        return undefined;
+    const lifecycle = {};
+    if (tracking.type === 'expo') {
+        lifecycle.onExposed = [
+            {
+                type: 'emit',
+                params: { event: 'tracking', payload: { spm: tracking.spm, type: 'expo' } },
+            },
+        ];
+    }
+    if (tracking.type === 'click') {
+        // Click tracking is handled at the element level via events,
+        // but we also attach an onMount hook to register the tracking context
+        lifecycle.onMount = [
+            {
+                type: 'emit',
+                params: { event: 'tracking:register', payload: { spm: tracking.spm, type: 'click' } },
+            },
+        ];
+    }
+    return Object.keys(lifecycle).length > 0 ? lifecycle : undefined;
+}
+// ─── Helpers ────────────────────────────────────────────────────
+function staticValue(value) {
+    return { type: 'static', value };
+}
+
+/**
+ * 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`.
+ */
+// ─── Normalize ──────────────────────────────────────────────────
+/**
+ * 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.
+ */
+function normalizeSchema(input) {
+    if (isLegacySchema(input)) {
+        return convertLegacySchema(input);
+    }
+    return input;
+}
+// ─── Parser ──────────────────────────────────────────────────────
+/**
+ * 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.
+ */
+function parseSchema(input) {
+    const schema = normalizeSchema(input);
+    const { elements, rootID } = schema;
+    const visited = new Set();
+    function buildNode(id) {
+        if (visited.has(id)) {
+            throw new Error(`[SchemaParser] Circular reference detected at "${id}"`);
+        }
+        const element = elements[id];
+        if (!element) {
+            throw new Error(`[SchemaParser] Missing element for id "${id}"`);
+        }
+        visited.add(id);
+        // Collect children from all slots (children + groups + config.overlays)
+        const children = [];
+        if (element.props.slots) {
+            for (const slot of Object.values(element.props.slots)) {
+                if (slot.children) {
+                    for (const childId of slot.children) {
+                        children.push(buildNode(childId));
+                    }
+                }
+                if (slot.groups) {
+                    for (const group of slot.groups) {
+                        for (const childId of group) {
+                            children.push(buildNode(childId));
+                        }
+                    }
+                }
+                if (slot.config?.overlays) {
+                    for (const overlay of slot.config.overlays) {
+                        if (overlay.children) {
+                            for (const childId of overlay.children) {
+                                children.push(buildNode(childId));
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        visited.delete(id); // allow same element across different branches
+        return {
+            id,
+            type: element.type,
+            props: element.props,
+            children,
+            lifecycle: element.lifecycle,
+            events: element.events,
+            directives: element.directives,
+        };
+    }
+    return buildNode(rootID);
+}
+// ─── Validation ──────────────────────────────────────────────────
+/**
+ * Validate a CardSchema and return any error messages.
+ */
+function validateSchema(input) {
+    const schema = normalizeSchema(input);
+    const errors = [];
+    if (!schema.version) {
+        errors.push('Missing "version" field');
+    }
+    if (!schema.rootID) {
+        errors.push('Missing "rootID" field');
+    }
+    else if (!schema.elements[schema.rootID]) {
+        errors.push(`Root element "${schema.rootID}" not found in elements`);
+    }
+    const allIds = new Set(Object.keys(schema.elements));
+    for (const [id, element] of Object.entries(schema.elements)) {
+        if (!element.type) {
+            errors.push(`Element "${id}" is missing a "type" field`);
+        }
+        // Validate slot children and groups references
+        if (element.props.slots) {
+            for (const [slotName, slot] of Object.entries(element.props.slots)) {
+                if (slot.children) {
+                    for (const childId of slot.children) {
+                        if (!allIds.has(childId)) {
+                            errors.push(`Element "${id}" slot "${slotName}" references unknown child "${childId}"`);
+                        }
+                    }
+                }
+                if (slot.groups) {
+                    for (const group of slot.groups) {
+                        for (const childId of group) {
+                            if (!allIds.has(childId)) {
+                                errors.push(`Element "${id}" slot "${slotName}" group references unknown child "${childId}"`);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return errors;
+}
+
+/**
+ * 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.
+ */
+// ─── Manager ─────────────────────────────────────────────────────
+class LifecycleManager {
+    constructor() {
+        this.lifecycles = new Map();
+        this.mounted = new Set();
+        this.exposed = new Set();
+    }
+    /**
+     * Register lifecycle hooks for an element identified by `id`.
+     */
+    register(id, lifecycle) {
+        if (lifecycle) {
+            this.lifecycles.set(id, lifecycle);
+        }
+        return () => this.unregister(id);
+    }
+    /**
+     * Remove lifecycle hooks for an element.
+     */
+    unregister(id) {
+        this.lifecycles.delete(id);
+        this.mounted.delete(id);
+        this.exposed.delete(id);
+    }
+    /**
+     * Trigger onMount for an element.
+     */
+    async mount(id, ctx = {}) {
+        if (this.mounted.has(id))
+            return;
+        const lc = this.lifecycles.get(id);
+        if (lc?.onMount) {
+            await runActionSteps(lc.onMount, ctx);
+        }
+        this.mounted.add(id);
+    }
+    /**
+     * Trigger onExposed for an element (entered viewport).
+     */
+    async markExposed(id, ctx = {}) {
+        if (this.exposed.has(id))
+            return;
+        const lc = this.lifecycles.get(id);
+        if (lc?.onExposed) {
+            await runActionSteps(lc.onExposed, ctx);
+        }
+        this.exposed.add(id);
+    }
+    /**
+     * Trigger onDestroy for an element.
+     */
+    async destroy(id, ctx = {}) {
+        if (!this.mounted.has(id))
+            return;
+        const lc = this.lifecycles.get(id);
+        if (lc?.onDestroy) {
+            await runActionSteps(lc.onDestroy, ctx);
+        }
+        this.mounted.delete(id);
+        this.exposed.delete(id);
+    }
+    /**
+     * Check if an element is currently mounted.
+     */
+    isMounted(id) {
+        return this.mounted.has(id);
+    }
+    /**
+     * Destroy all elements and clear all hooks.
+     */
+    async dispose(ctx = {}) {
+        const mountedIds = [...this.mounted];
+        for (const id of mountedIds) {
+            await this.destroy(id, ctx);
+        }
+        this.lifecycles.clear();
+        this.mounted.clear();
+        this.exposed.clear();
+    }
+}
+/**
+ * Create a new LifecycleManager instance.
+ */
+function createLifecycleManager() {
+    return new LifecycleManager();
+}
+
+/**
+ * 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).
+ */
+// ─── Detection ───────────────────────────────────────────────────
+const ENVELOPE_KEYS = [
+    'createSurface',
+    'updateComponents',
+    'updateDataModel',
+    'deleteSurface',
+    'appendContent',
+];
+/**
+ * Check whether a parsed JSON object looks like an A2UI envelope
+ * (no internal `type` discriminator, but exactly an A2UI action key).
+ */
+function isA2UIEnvelope(msg) {
+    if (!msg || typeof msg !== 'object')
+        return false;
+    if (typeof msg.type === 'string')
+        return false; // internal command
+    return ENVELOPE_KEYS.some((k) => msg[k] != null);
+}
+// ─── Conversion ──────────────────────────────────────────────────
+/**
+ * Convert a flat A2UI component into an internal ElementNode.
+ */
+function a2uiComponentToElement(comp) {
+    const { id, component, children, slots, directives, events, lifecycle, ...props } = comp;
+    const p = { ...props };
+    if (children) {
+        p.slots = { ...(p.slots ?? {}), default: { children } };
+    }
+    if (slots) {
+        p.slots = { ...(p.slots ?? {}), ...slots };
+    }
+    const element = { id, type: component, props: p };
+    if (directives)
+        element.directives = directives;
+    if (events)
+        element.events = events;
+    if (lifecycle)
+        element.lifecycle = lifecycle;
+    return element;
+}
+/**
+ * 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).
+ */
+function a2uiToCommand(msg) {
+    if (msg.createSurface) {
+        const { surfaceId, schema } = msg.createSurface;
+        return { type: 'createSurface', surfaceId, ...(schema ? { schema } : {}) };
+    }
+    if (msg.updateComponents) {
+        const { surfaceId, components } = msg.updateComponents;
+        const elements = {};
+        let rootID;
+        for (const comp of components ?? []) {
+            if (!comp || typeof comp.id !== 'string' || typeof comp.component !== 'string')
+                continue;
+            elements[comp.id] = a2uiComponentToElement(comp);
+            if (comp.id === 'root')
+                rootID = 'root';
+        }
+        return { type: 'updateComponents', surfaceId, elements, ...(rootID ? { rootID } : {}) };
+    }
+    if (msg.updateDataModel) {
+        const { surfaceId, path = '/', value = null } = msg.updateDataModel;
+        return { type: 'updateDataModel', surfaceId, path, value };
+    }
+    if (msg.appendContent) {
+        const { surfaceId, elementId, content } = msg.appendContent;
+        return { type: 'appendContent', surfaceId, elementId, content };
+    }
+    if (msg.deleteSurface) {
+        return { type: 'deleteSurface', surfaceId: msg.deleteSurface.surfaceId };
+    }
+    return null;
+}
+
+/**
+ * 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.
+ */
+// ─── Parser ──────────────────────────────────────────────────────
+/**
+ * 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));
+ * };
+ * ```
+ */
+class StreamingParser {
+    constructor(options = {}) {
+        this.buffer = '';
+        this.delimiter = options.delimiter ?? '\n';
+        this.onParseError = options.onParseError;
+    }
+    /**
+     * 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) {
+        this.buffer += chunk;
+        const commands = [];
+        // Split by delimiter, keeping the last incomplete line in the buffer
+        const lines = this.buffer.split(this.delimiter);
+        this.buffer = lines.pop() ?? '';
+        for (const line of lines) {
+            const command = this.parseLine(line);
+            if (command) {
+                commands.push(command);
+            }
+        }
+        return commands;
+    }
+    /**
+     * 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() {
+        const remaining = this.buffer.trim();
+        this.buffer = '';
+        if (!remaining)
+            return [];
+        const command = this.parseLine(remaining);
+        return command ? [command] : [];
+    }
+    /**
+     * Reset the parser state, clearing any buffered content.
+     */
+    reset() {
+        this.buffer = '';
+    }
+    // ─── Private ────────────────────────────────────────────────────
+    /**
+     * Parse a single line into a StreamingCommand, handling SSE format.
+     */
+    parseLine(line) {
+        const trimmed = line.trim();
+        // Skip empty lines and SSE comments (lines starting with ':')
+        if (!trimmed || trimmed.startsWith(':'))
+            return null;
+        // Handle SSE format: strip "data:" prefix
+        let data = trimmed;
+        if (data.startsWith('data:')) {
+            data = data.slice(5).trim();
+        }
+        // Skip SSE control messages
+        if (data === '[DONE]')
+            return null;
+        try {
+            const parsed = JSON.parse(data);
+            // Internal command format: has a `type` discriminator field
+            if (parsed && typeof parsed.type === 'string') {
+                return parsed;
+            }
+            // A2UI v0.9 envelope format: `{"version":"v0.9","createSurface":{...}}`
+            if (isA2UIEnvelope(parsed)) {
+                return a2uiToCommand(parsed);
+            }
+            return null;
+        }
+        catch (error) {
+            this.onParseError?.(data, error);
+            return null;
+        }
+    }
+}
+
+/**
+ * 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
+ */
+// ─── Engine ──────────────────────────────────────────────────────
+class StreamingEngine {
+    constructor(listeners) {
+        /** Active surfaces keyed by surfaceId */
+        this.surfaces = new Map();
+        this.listeners = listeners;
+    }
+    // ─── Public API ────────────────────────────────────────────────
+    /**
+     * Apply a single streaming command to the engine state.
+     * This triggers the appropriate event listener after state mutation.
+     */
+    apply(command) {
+        switch (command.type) {
+            case 'createSurface':
+                this.handleCreateSurface(command);
+                break;
+            case 'updateComponents':
+                this.handleUpdateComponents(command);
+                break;
+            case 'updateDataModel':
+                this.handleUpdateDataModel(command);
+                break;
+            case 'appendContent':
+                this.handleAppendContent(command);
+                break;
+            case 'deleteSurface':
+                this.handleDeleteSurface(command);
+                break;
+        }
+    }
+    /**
+     * Apply multiple streaming commands in order.
+     */
+    applyBatch(commands) {
+        for (const command of commands) {
+            this.apply(command);
+        }
+    }
+    /**
+     * Get the current schema for a surface (read-only snapshot).
+     */
+    getSchema(surfaceId) {
+        return this.surfaces.get(surfaceId);
+    }
+    /**
+     * Get the current variables for a surface.
+     */
+    getVariables(surfaceId) {
+        return this.surfaces.get(surfaceId)?.variables;
+    }
+    /**
+     * Check if a surface exists.
+     */
+    hasSurface(surfaceId) {
+        return this.surfaces.has(surfaceId);
+    }
+    /**
+     * Dispose all surfaces and reset state.
+     */
+    dispose() {
+        for (const surfaceId of this.surfaces.keys()) {
+            this.listeners.onSurfaceDeleted(surfaceId);
+        }
+        this.surfaces.clear();
+    }
+    // ─── Command Handlers ──────────────────────────────────────────
+    handleCreateSurface(cmd) {
+        // (Re)creating a surface always resets its state. A2UI semantics: a
+        // surfaceId is fixed once created and must be deleted before reuse, so a
+        // repeated createSurface is treated as delete + create. Without a schema
+        // an empty shell is stored — components then arrive via updateComponents.
+        const schema = cmd.schema
+            ? normalizeSchema(cmd.schema)
+            : { version: '1.0', rootID: 'root', elements: {}, variables: {} };
+        this.surfaces.set(cmd.surfaceId, schema);
+        this.listeners.onSurfaceCreated(cmd.surfaceId, cmd.schema ?? null);
+    }
+    handleUpdateComponents(cmd) {
+        let schema = this.surfaces.get(cmd.surfaceId);
+        if (!schema) {
+            // Implicit surface creation (v0.8 compatibility)
+            schema = {
+                version: '1.0',
+                rootID: cmd.rootID ?? 'root',
+                elements: {},
+                variables: {},
+            };
+            this.surfaces.set(cmd.surfaceId, schema);
+        }
+        const changes = [];
+        // Update rootID if provided
+        if (cmd.rootID) {
+            schema.rootID = cmd.rootID;
+        }
+        // Process element additions/updates.
+        // Merge ALL elements first, THEN compute parent/index against the final
+        // batch state — otherwise parentId depends on key order: a new child
+        // processed before its parent's updated children array would resolve to
+        // no parent, and incremental renderers would silently drop it.
+        if (cmd.elements) {
+            const isNewMap = new Map();
+            for (const [id, element] of Object.entries(cmd.elements)) {
+                isNewMap.set(id, !schema.elements[id]);
+                schema.elements[id] = element;
+            }
+            for (const [id, element] of Object.entries(cmd.elements)) {
+                const parentId = this.findParentId(schema, id);
+                const index = parentId ? this.findChildIndex(schema, parentId, id) : undefined;
+                changes.push({
+                    changeType: isNewMap.get(id) ? 'add' : 'update',
+                    elementId: id,
+                    element,
+                    parentId,
+                    index,
+                });
+            }
+        }
+        // Process element removals
+        if (cmd.removeElements) {
+            for (const id of cmd.removeElements) {
+                if (schema.elements[id]) {
+                    changes.push({
+                        changeType: 'remove',
+                        elementId: id,
+                        parentId: this.findParentId(schema, id),
+                    });
+                    delete schema.elements[id];
+                    // Also remove from any parent's children lists
+                    this.removeFromParentSlots(schema, id);
+                }
+            }
+        }
+        if (changes.length > 0) {
+            this.listeners.onComponentsUpdated(cmd.surfaceId, changes);
+        }
+    }
+    handleUpdateDataModel(cmd) {
+        const schema = this.surfaces.get(cmd.surfaceId);
+        if (!schema)
+            return;
+        // Set value at path in variables
+        setByPath(schema.variables, cmd.path, cmd.value);
+        this.listeners.onDataModelUpdated(cmd.surfaceId, cmd.path, cmd.value);
+    }
+    handleAppendContent(cmd) {
+        const schema = this.surfaces.get(cmd.surfaceId);
+        if (!schema)
+            return;
+        // Update internal schema state
+        const element = schema.elements[cmd.elementId];
+        if (element) {
+            const currentContent = typeof element.props.content === 'string'
+                ? element.props.content
+                : '';
+            element.props.content = currentContent + cmd.content;
+        }
+        this.listeners.onContentAppended(cmd.surfaceId, cmd.elementId, cmd.content);
+    }
+    handleDeleteSurface(cmd) {
+        this.surfaces.delete(cmd.surfaceId);
+        this.listeners.onSurfaceDeleted(cmd.surfaceId);
+    }
+    // ─── Helpers ────────────────────────────────────────────────────
+    /**
+     * Find the parent element ID for a given element by scanning all slots.
+     */
+    findParentId(schema, elementId) {
+        for (const [id, element] of Object.entries(schema.elements)) {
+            if (id === elementId)
+                continue;
+            if (this.elementContainsChild(element, elementId)) {
+                return id;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Find the index of a child element within its parent's slot children.
+     */
+    findChildIndex(schema, parentId, childId) {
+        const parent = schema.elements[parentId];
+        if (!parent?.props.slots)
+            return undefined;
+        for (const slot of Object.values(parent.props.slots)) {
+            if (slot.children) {
+                const idx = slot.children.indexOf(childId);
+                if (idx >= 0)
+                    return idx;
+            }
+            if (slot.groups) {
+                for (const group of slot.groups) {
+                    const idx = group.indexOf(childId);
+                    if (idx >= 0)
+                        return idx;
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Check if an element references the given child ID in any of its slots.
+     */
+    elementContainsChild(element, childId) {
+        if (!element.props.slots)
+            return false;
+        for (const slot of Object.values(element.props.slots)) {
+            if (slot.children?.includes(childId))
+                return true;
+            if (slot.groups?.some(group => group.includes(childId)))
+                return true;
+            if (slot.config?.overlays) {
+                for (const overlay of slot.config.overlays) {
+                    if (overlay.children?.includes(childId))
+                        return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Remove a child ID from all parent element slot references.
+     */
+    removeFromParentSlots(schema, childId) {
+        for (const element of Object.values(schema.elements)) {
+            if (!element.props.slots)
+                continue;
+            for (const slot of Object.values(element.props.slots)) {
+                if (slot.children) {
+                    const idx = slot.children.indexOf(childId);
+                    if (idx >= 0)
+                        slot.children.splice(idx, 1);
+                }
+                if (slot.groups) {
+                    for (const group of slot.groups) {
+                        const idx = group.indexOf(childId);
+                        if (idx >= 0)
+                            group.splice(idx, 1);
+                    }
+                }
+            }
+        }
+    }
+}
+// ─── Utility Functions ────────────────────────────────────────────
+/**
+ * Keys that must never be written through a data-model path. Walking or
+ * assigning into `__proto__` / `constructor` / `prototype` lets a crafted
+ * `updateDataModel` command reach `Object.prototype` and pollute every object
+ * in the runtime. Streaming commands originate from the agent/LLM stream, so
+ * this path is attacker-influenceable and must be guarded.
+ */
+const UNSAFE_PATH_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/** Merge only own, non-dangerous keys of `src` into `target`. */
+function safeMerge(target, src) {
+    for (const key of Object.keys(src)) {
+        if (UNSAFE_PATH_KEYS.has(key))
+            continue;
+        target[key] = src[key];
+    }
+}
+/**
+ * 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'
+ * ```
+ */
+function setByPath(obj, path, value) {
+    // Remove leading slash and split
+    const parts = path.replace(/^\//, '').split('/').filter(Boolean);
+    // Reject any dangerous segment outright — never partially apply.
+    if (parts.some((p) => UNSAFE_PATH_KEYS.has(p))) {
+        console.warn(`[StreamingEngine] Rejected unsafe data-model path "${path}"`);
+        return;
+    }
+    if (parts.length === 0) {
+        // Root-level update: merge value into obj (own, safe keys only)
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            safeMerge(obj, value);
+        }
+        return;
+    }
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const key = parts[i];
+        if (current[key] === undefined || current[key] === null) {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+    current[parts[parts.length - 1]] = value;
+}
+
+/**
+ * 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).
+ */
+const EMPTY = Object.freeze({ elements: {}, complete: false });
+// ─── Scanner primitives ──────────────────────────────────────────
+/**
+ * Scan a balanced JSON value starting at `start` (must point at `{` or `[`).
+ * Returns the index AFTER the closing bracket, or -1 if the text ends first.
+ */
+function scanBalanced(text, start) {
+    const open = text[start];
+    const close = open === '{' ? '}' : ']';
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = start; i < text.length; i++) {
+        const c = text[i];
+        if (esc) {
+            esc = false;
+            continue;
+        }
+        if (c === '\\') {
+            if (inStr)
+                esc = true;
+            continue;
+        }
+        if (c === '"') {
+            inStr = !inStr;
+            continue;
+        }
+        if (inStr)
+            continue;
+        if (c === open)
+            depth++;
+        else if (c === close) {
+            depth--;
+            if (depth === 0)
+                return i + 1;
+        }
+    }
+    return -1;
+}
+/** Scan a JSON string starting at `start` (must point at `"`). Returns index after closing quote, or -1. */
+function scanString(text, start) {
+    let esc = false;
+    for (let i = start + 1; i < text.length; i++) {
+        const c = text[i];
+        if (esc) {
+            esc = false;
+            continue;
+        }
+        if (c === '\\') {
+            esc = true;
+            continue;
+        }
+        if (c === '"')
+            return i + 1;
+    }
+    return -1;
+}
+/** Skip whitespace from `i`. */
+function skipWs(text, i) {
+    while (i < text.length && /\s/.test(text[i]))
+        i++;
+    return i;
+}
+/**
+ * Find the top-level (depth-1) key `"elements"` outside of any string value.
+ * Returns the index of its opening quote, or -1.
+ */
+function findElementsKey(text) {
+    let depth = 0;
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        if (c === '"') {
+            const end = scanString(text, i);
+            if (end < 0)
+                return -1; // unterminated string at stream edge
+            // A depth-1 string followed by `:` is a top-level key
+            if (depth === 1 && text.slice(i, end) === '"elements"') {
+                const after = skipWs(text, end);
+                if (text[after] === ':')
+                    return i;
+            }
+            i = end;
+            continue;
+        }
+        if (c === '{' || c === '[')
+            depth++;
+        else if (c === '}' || c === ']')
+            depth--;
+        i++;
+    }
+    return -1;
+}
+// ─── Main API ────────────────────────────────────────────────────
+/**
+ * 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).
+ */
+function extractPartialSchema(text) {
+    const doc = text.trim();
+    if (!doc.startsWith('{'))
+        return EMPTY;
+    // 1) Whole document already closed → authoritative full parse
+    try {
+        const full = JSON.parse(doc);
+        if (full && typeof full === 'object') {
+            return {
+                version: full.version,
+                rootID: full.rootID,
+                variables: full.variables,
+                elements: full.elements && typeof full.elements === 'object' ? full.elements : {},
+                complete: true,
+            };
+        }
+    }
+    catch {
+        // still streaming — fall through to partial extraction
+    }
+    // 2) Locate the top-level "elements" key
+    const keyStart = findElementsKey(doc);
+    if (keyStart < 0)
+        return EMPTY; // header still streaming
+    // 3) Header fields (version/rootID/variables precede elements per output
+    //    convention; they are scalars/small objects so they closed long ago).
+    //    Rebuild a tiny JSON doc from the prefix and parse it.
+    let version;
+    let rootID;
+    let variables;
+    const headRaw = doc.slice(0, keyStart).replace(/,\s*$/, '') + '}';
+    try {
+        const head = JSON.parse(headRaw);
+        version = typeof head.version === 'string' ? head.version : undefined;
+        rootID = typeof head.rootID === 'string' ? head.rootID : undefined;
+        variables = head.variables && typeof head.variables === 'object' ? head.variables : undefined;
+    }
+    catch {
+        // header irregular (e.g. elements emitted first) — elements still extractable
+    }
+    // 4) Walk the elements object body, harvesting balanced entries
+    const elements = {};
+    let i = skipWs(doc, keyStart + '"elements"'.length);
+    if (doc[i] !== ':')
+        return { version, rootID, variables, elements, complete: false };
+    i = skipWs(doc, i + 1);
+    if (doc[i] !== '{')
+        return { version, rootID, variables, elements, complete: false };
+    i++;
+    for (;;) {
+        i = skipWs(doc, i);
+        if (doc[i] === ',') {
+            i++;
+            continue;
+        }
+        if (i >= doc.length || doc[i] === '}')
+            break; // stream edge or map closed
+        if (doc[i] !== '"')
+            break; // malformed — stop harvesting
+        const keyEnd = scanString(doc, i);
+        if (keyEnd < 0)
+            break; // key itself cut by stream edge
+        let key;
+        try {
+            key = JSON.parse(doc.slice(i, keyEnd));
+        }
+        catch {
+            break;
+        }
+        let j = skipWs(doc, keyEnd);
+        if (doc[j] !== ':')
+            break;
+        j = skipWs(doc, j + 1);
+        if (doc[j] !== '{')
+            break; // element values must be objects
+        const valueEnd = scanBalanced(doc, j);
+        if (valueEnd < 0)
+            break; // this element still streaming
+        try {
+            const el = JSON.parse(doc.slice(j, valueEnd));
+            if (el && typeof el === 'object' && typeof el.type === 'string') {
+                elements[key] = el;
+            }
+            // parse ok but shape wrong → skip silently (final full parse is backstop)
+        }
+        catch {
+            // malformed single element → skip; keep harvesting the rest
+        }
+        i = valueEnd;
+    }
+    return { version, rootID, variables, elements, complete: false };
+}
+
+export { ActionRegistry, LifecycleManager, StreamingEngine, StreamingParser, a2uiComponentToElement, a2uiToCommand, convertLegacySchema, createLifecycleManager, extractPartialSchema, getByPath$1 as getByPath, hasExpression, interpolate, isA2UIEnvelope, isLegacySchema, normalizeSchema, parseSchema, registerActionHandler, registry, resetIdCounter, resolveActionRef, resolveDeep, resolveExpression, resolveExpressionValue, runActionStep, runActionSteps, setByPath, validateSchema };
+//# sourceMappingURL=index.esm.js.map