@antglobal/copilot-cards-web 1.0.4 → 1.0.6

package/README.md

@@ -78,14 +78,19 @@ Common render options include:
 | Option | Purpose |
 | --- | --- |
 | `variables` | Overrides initial schema variables |
-| `botId` | Selects bot-scoped custom action handlers |
-| `isMobile` | Overrides automatic viewport detection |
+| `botId` | Optionally selects bot-scoped custom action handlers |
+| `isMobile` | Explicitly enables mobile component layout; defaults to `false` |
+| `responsive` | Explicitly enables mobile px-to-rem conversion when configured |
 | `fetch` | Supplies a custom request implementation |
 | `showToast` | Connects toast actions to the host UI |
 | `navigate` | Connects URL actions to host navigation |
 | `emit` | Receives events emitted by a card |
 | `copyText` | Connects copy actions to the host clipboard |
 
+The SDK does not infer mobile mode or CSS units from viewport width. Pass only
+`isMobile: true` for mobile layout with px output. To opt into REM conversion,
+also pass `responsive: { mobile: { unit: "rem", rootValue: 100 } }`.
+
 ### Streaming
 
 Use `renderStreamingCard` when the card arrives incrementally from an AI model or server:
@@ -121,6 +126,8 @@ const bot = new BotSDK({
 await bot.renderCard(container, schema);
 ```
 
+`botId` is optional. Omit it when the application uses only one default action scope; provide it when isolating custom handlers or loading per-bot action configuration.
+
 ## Built-in components
 
 The renderer includes:

package/dist/index.d.ts

@@ -42,6 +42,7 @@ interface ResponsiveContext {
     resolveLength(value: string | number): string;
     convertCSS(value: string): string;
 }
+/** Reusable REM preset; applied only when passed explicitly as `responsive.mobile`. */
 declare const DEFAULT_MOBILE_RESPONSIVE: ResponsiveMobileOptions;
 /** Convert CSS px lengths while preserving strings, comments, and URLs. */
 declare function convertPixelTokens(value: string, rootValue: number): string;
@@ -62,9 +63,9 @@ declare function createResponsiveContext(isMobile: boolean, responsive?: Respons
  */
 
 interface RenderCardOptions extends WebActionContextOptions {
-    /** Force mobile mode; auto-detected from viewport if omitted */
+    /** Enable mobile component layout explicitly (default false). */
     isMobile?: boolean;
-    /** Mobile sizing conversion. `isMobile: true` defaults to rem/rootValue 100. */
+    /** Optional mobile sizing conversion; omitted values preserve px output. */
     responsive?: ResponsiveOptions;
     /** External variables to merge into schema.variables (overrides schema defaults) */
     variables?: Record<string, any>;
@@ -282,8 +283,8 @@ declare function connectSSE(instance: StreamingCardInstance, options: SSEConnect
  */
 
 interface BotSDKOptions {
-    /** Bot ID — identifies which bot this instance is for */
-    botId: string;
+    /** Optional bot ID used to scope custom actions and action configuration */
+    botId?: string;
     /** Base URL for business API requests (e.g. 'https://api.example.com') */
     baseUrl?: string;
     /**
@@ -433,7 +434,7 @@ declare function buildStyleString(styles: Record<string, string | number | undef
  * common style helpers. Designed to be used by `renderCard` which
  * passes resolved props via `setData()`.
  *
- * Note: lifecycle management, event binding, and viewport detection
+ * Note: lifecycle management, event binding, and mobile-mode selection
  * are handled externally by `renderCard` / the render pipeline.
  * BaseElement keeps itself lightweight and focused on DOM rendering.
  */
@@ -620,6 +621,8 @@ declare class CardButton extends BaseElement {
 declare class CardInput extends BaseElement {
     static readonly is = "ai-card-input";
     protected render(): void;
+    private getAutoFocusControl;
+    private isFirstAvailableAutoFocusInput;
     /** Escape HTML entities for safe insertion. */
     private escapeHtml;
     /** Escape attribute values for safe insertion. */
@@ -1017,6 +1020,8 @@ type InputAffix = string | InputAffixConfig;
 interface InputProps {
     /** Placeholder text */
     placeholder?: string;
+    /** Focus the native input after the component is mounted (default false) */
+    autoFocus?: boolean;
     /** HTML input type: text / textarea / password / number etc. */
     inputType?: 'text' | 'textarea' | 'password' | (string & {});
     /** Label text displayed above the input */
@@ -1290,7 +1295,7 @@ interface ChoiceListProps {
     indicatorStyle?: Record<string, any>;
     /** Style merged into selected indicators */
     selectedIndicatorStyle?: Record<string, any>;
-    /** Checked mark used by multiple mode; defaults to built-in `check_bold` */
+    /** Selected mark override; single mode keeps its radio dot when omitted, while multiple mode defaults to `check_bold` */
     checkedIcon?: ChoiceIndicatorIcon;
 }
 interface ChoiceIndicatorIcon {
@@ -1318,7 +1323,7 @@ interface ChoiceItemProps {
     indicatorStyle?: Record<string, any>;
     /** Per-item selected indicator style */
     selectedIndicatorStyle?: Record<string, any>;
-    /** Per-item checked mark override */
+    /** Per-item selected mark override; also replaces the single-select radio dot */
     checkedIcon?: ChoiceIndicatorIcon;
 }
 interface PasscodeInputProps {

package/dist/index.js

@@ -1,4 +1,4 @@
-import { getBuiltinIcon, cloneJsonData, createLifecycleManager, materializeCard, resolveActionRef, createA2UIParameterResolver, createExpressionContext, resolveA2UIDeep, hasExpression, resolveExpression, resolveDeep, resolveExpressionValue, replaceRootContents, isBoundRenderTreeNode, runActionSteps, normalizeSchema, validateSchema, requiresBindingMaterialization, parseSchema, StreamingParser, StreamingEngine, findAffectedRepeatOwners, bindingTopologyFingerprint, findTemplateRepeatOwners, extractPartialSchema, runActionStep, registry } from '@antglobal/copilot-cards-core';
+import { getBuiltinIcon, cloneJsonData, createLifecycleManager, materializeCard, createA2UIParameterResolver, createExpressionContext, resolveActionRef, replaceRootContents, resolveA2UIDeep, hasExpression, resolveExpression, resolveDeep, resolveExpressionValue, isBoundRenderTreeNode, runActionSteps, normalizeSchema, validateSchema, requiresBindingMaterialization, parseSchema, StreamingParser, StreamingEngine, findAffectedRepeatOwners, bindingTopologyFingerprint, findTemplateRepeatOwners, extractPartialSchema, runActionStep, registry } from '@antglobal/copilot-cards-core';
 export { ActionRegistry, a2uiComponentToElement, a2uiToCommand, convertLegacySchema, createLifecycleManager, hasExpression, isA2UIEnvelope, isLegacySchema, normalizeSchema, parseSchema, registerActionHandler, registry, resolveActionRef, resolveDeep, resolveExpression, resolveExpressionValue, runActionStep, runActionSteps, validateSchema } from '@antglobal/copilot-cards-core';
 import * as echarts from 'echarts/core';
 import { LineChart, BarChart, PieChart, ScatterChart, FunnelChart, HeatmapChart } from 'echarts/charts';
@@ -96,6 +96,7 @@ function buildStyleString(styles) {
         .join(';');
 }
 
+/** Reusable REM preset; applied only when passed explicitly as `responsive.mobile`. */
 const DEFAULT_MOBILE_RESPONSIVE = Object.freeze({
     unit: 'rem',
     rootValue: 100,
@@ -236,10 +237,10 @@ function convertPixelTokens(value, rootValue) {
     return result;
 }
 function createResponsiveContext(isMobile, responsive) {
-    const mobile = responsive?.mobile ?? DEFAULT_MOBILE_RESPONSIVE;
-    const unit = mobile.unit;
-    const rootValue = mobile.rootValue;
-    if (!Number.isFinite(rootValue) || rootValue <= 0) {
+    const mobile = responsive?.mobile;
+    const unit = mobile?.unit;
+    const rootValue = mobile?.rootValue ?? DEFAULT_MOBILE_RESPONSIVE.rootValue;
+    if (mobile && (!Number.isFinite(rootValue) || rootValue <= 0)) {
         throw new Error('[renderCard] responsive.mobile.rootValue must be a positive number');
     }
     const active = isMobile && unit === 'rem';
@@ -705,6 +706,7 @@ function buildHeatmapOption(config) {
  */
 // ─── Slot Layout Constants ──────────────────────────────────────
 const SLOT_LAYOUT = {
+    FLEX: 'flex',
     COLUMNS: 'columns',
     GRID: 'grid',
     HORIZONTAL_SCROLL: 'horizontalScroll',
@@ -715,6 +717,30 @@ const SLOT_LAYOUT = {
     TABLE: 'table',
     CHART: 'chart',
 };
+// ─── Dispatcher ─────────────────────────────────────────────────
+/**
+ * Apply host-level layout styles based on the slot key.
+ * Called from renderDefault BEFORE props.style so explicit styles can override.
+ * Layouts that require wrapper DOM continue to render in renderSlotLayout.
+ */
+function applySlotBaseStyle(container, props) {
+    const flex = props.slots?.[SLOT_LAYOUT.FLEX];
+    if (!flex || typeof flex !== 'object')
+        return;
+    const config = flex.config && typeof flex.config === 'object' ? flex.config : {};
+    container.style.display = 'flex';
+    container.style.flexDirection = config.direction ?? 'column';
+    container.style.alignItems = config.align ?? 'flex-start';
+    container.style.justifyContent = config.justify ?? 'flex-start';
+    container.style.flexWrap = config.wrap ?? 'nowrap';
+    container.style.gap = resolveFlexGap(config.gap);
+}
+function resolveFlexGap(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return `${value}px`;
+    }
+    return typeof value === 'string' && value.length > 0 ? value : '0px';
+}
 /**
  * Render children into a container using the slot layout strategy.
  * Returns true if a special layout was applied (children already appended).
@@ -852,40 +878,12 @@ function applyGridPlacement(el, child) {
 function isCssPlacement(value) {
     return typeof value === 'string' || typeof value === 'number';
 }
-// ─── Horizontal Scroll ──────────────────────────────────────────
-/**
- * Horizontal scrollable row with mouse drag support.
- *
- * Schema: `slots: { horizontalScroll: { children: [...], config: { gap, itemWidth, snap, arrows, arrowStyle, scrollStep, mask, maskWidth, maskColor, itemHoverStyle, autoScroll, autoScrollInterval, autoScrollLoop } } }`
- *
- * Optional config:
- * - `arrows`         — show prev/next arrow buttons; each is only visible while
- *                      the track can actually scroll in that direction (default false)
- * - `arrowStyle`     — free-form CSS object merged onto both arrow buttons; every
- *                      default (circle, background, shadow…) can be overridden
- * - `arrowIcon`      — replaces the built-in chevron on both buttons: an image URL
- *                      (http/https/data:image) or a text glyph/emoji. The left
- *                      button gets a mirrored copy.
- * - `arrowIconLeft` / `arrowIconRight` — per-side icon, same formats, never
- *                      mirrored; takes precedence over `arrowIcon`
- * - `arrowOffset`    — distance of each arrow from its own edge (default '8px');
- *                      number = px, negative values push the arrows outside /
- *                      straddling the container edge
- * - `scrollStep`     — px scrolled per arrow click (default 80% of the visible width)
- * - `mask`           — show translucent edge-fade masks hinting at more content;
- *                      follows the same can-scroll state as the arrows (default false)
- * - `maskWidth`      — width of each edge mask (default '48px')
- * - `maskColor`      — base color the mask fades out from; any CSS color incl.
- *                      rgba for translucency (default '#fff')
- * - `maskOpacity`    — opacity of a mask while visible (default 1)
- * - `itemHoverStyle` — CSS object applied to an item on hover and reverted on
- *                      leave; pure inline-style swap, never triggers a re-render
- * - `autoScroll`     — while the pointer hovers the track, auto-advance one item
- *                      every `autoScrollInterval` ms (default false)
- * - `autoScrollInterval` — ms each item stays before advancing (default 2000)
- * - `autoScrollLoop` — loop back to the first item after the last (default true);
- *                      when false it stops on the last item until re-hovered
- */
+function resolveScrollbarMode(value) {
+    if (value === 'auto' || value === 'hidden' || value === 'visible') {
+        return value;
+    }
+    return undefined;
+}
 function renderHorizontalScrollSlot(container, children, slotContent, renderChild) {
     const config = slotContent?.config ?? {};
     const gap = config.gap ?? '8px';
@@ -897,13 +895,16 @@ function renderHorizontalScrollSlot(container, children, slotContent, renderChil
     const autoScroll = config.autoScroll === true;
     const autoScrollInterval = typeof config.autoScrollInterval === 'number' ? config.autoScrollInterval : 2000;
     const autoScrollLoop = config.autoScrollLoop !== false;
+    const scrollbar = resolveScrollbarMode(config.scrollbar);
+    const hidesScrollbar = scrollbar == null || scrollbar === 'hidden';
     const track = document.createElement('div');
     track.style.cssText = [
         'display:flex',
         'overflow-x:auto',
         'overflow-y:hidden',
         '-webkit-overflow-scrolling:touch',
-        'scrollbar-width:none',
+        hidesScrollbar ? 'scrollbar-width:none' : '',
+        scrollbar === 'visible' ? 'scrollbar-width:auto' : '',
         `gap:${gap}`,
         'cursor:grab',
         snap ? 'scroll-snap-type:x mandatory' : '',
@@ -912,11 +913,8 @@ function renderHorizontalScrollSlot(container, children, slotContent, renderChil
     // across variable-driven re-renders (see captureScrollPositions/restoreScrollPositions).
     const cardId = container.getAttribute('data-card-id') ?? 'x';
     track.setAttribute('data-scroll-id', cardId);
-    // Hide scrollbar for WebKit
-    const styleEl = document.createElement('style');
-    const trackClass = `card-scroll-${cardId}`;
-    styleEl.textContent = `.${trackClass}::-webkit-scrollbar{display:none}`;
-    track.classList.add(trackClass);
+    if (scrollbar)
+        track.dataset.scrollbar = scrollbar;
     for (const child of children) {
         const item = renderChild(child);
         item.style.flexShrink = '0';
@@ -1040,7 +1038,18 @@ function renderHorizontalScrollSlot(container, children, slotContent, renderChil
         track.addEventListener('mouseleave', stopAuto);
         track.addEventListener('mousedown', stopAuto);
     }
-    container.appendChild(styleEl);
+    if (hidesScrollbar) {
+        const trackClass = `card-scroll-${cardId}`;
+        track.classList.add(trackClass);
+        const styleEl = document.createElement('style');
+        styleEl.textContent = `.${trackClass}::-webkit-scrollbar{display:none}`;
+        container.appendChild(styleEl);
+    }
+    else if (scrollbar === 'visible') {
+        const styleEl = document.createElement('style');
+        styleEl.textContent = '[data-scroll-id][data-scrollbar="visible"]::-webkit-scrollbar{display:block}';
+        container.appendChild(styleEl);
+    }
     // Plain track — no overlay chrome requested
     if (!arrows && !mask) {
         container.appendChild(track);
@@ -1113,13 +1122,41 @@ function applyHoverStyle(item, hoverStyle) {
     const previous = {};
     item.addEventListener('mouseenter', () => {
         for (const [key, value] of Object.entries(hoverStyle)) {
-            previous[key] = item.style[key];
-            item.style[key] = value;
+            if (key.startsWith('--')) {
+                const previousValue = item.style.getPropertyValue(key);
+                const previousPriority = item.style.getPropertyPriority(key);
+                previous[key] = {
+                    value: previousValue,
+                    priority: previousPriority,
+                    wasPresent: previousValue !== '' || previousPriority !== '',
+                    isCustomProperty: true,
+                };
+                item.style.setProperty(key, String(value));
+            }
+            else {
+                previous[key] = {
+                    value: item.style[key],
+                    priority: '',
+                    wasPresent: true,
+                    isCustomProperty: false,
+                };
+                item.style[key] = value;
+            }
         }
     });
     item.addEventListener('mouseleave', () => {
-        for (const [key, value] of Object.entries(previous)) {
-            item.style[key] = value;
+        for (const [key, state] of Object.entries(previous)) {
+            if (state.isCustomProperty) {
+                if (state.wasPresent) {
+                    item.style.setProperty(key, state.value, state.priority);
+                }
+                else {
+                    item.style.removeProperty(key);
+                }
+            }
+            else {
+                item.style[key] = state.value;
+            }
         }
     });
 }
@@ -1647,7 +1684,7 @@ function renderTableSlot(container, slotContent) {
  * common style helpers. Designed to be used by `renderCard` which
  * passes resolved props via `setData()`.
  *
- * Note: lifecycle management, event binding, and viewport detection
+ * Note: lifecycle management, event binding, and mobile-mode selection
  * are handled externally by `renderCard` / the render pipeline.
  * BaseElement keeps itself lightweight and focused on DOM rendering.
  */
@@ -2335,6 +2372,30 @@ function sanitizeIconHtml(icon) {
     walk(tpl.content);
     return tpl.innerHTML;
 }
+function escapeIconAttribute(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+function isDirectImageUrl(icon) {
+    const normalized = icon.replace(/[\s\x00-\x1f]/g, '').toLowerCase();
+    return /^(?:https?:\/\/|\/\/|data:image\/)/.test(normalized)
+        || /^(?:\.{0,2}\/).+\.(?:avif|gif|jpe?g|png|svg|webp)(?:[?#].*)?$/i.test(icon);
+}
+/**
+ * Button.icon historically accepts sanitized HTML or text. A direct image URL
+ * is a common shorthand, so convert only recognizable image URLs to markup and
+ * leave inline SVG, <img> HTML, emoji, and other text on the existing path.
+ */
+function renderButtonIcon(icon) {
+    const value = String(icon ?? '').trim();
+    if (isDirectImageUrl(value)) {
+        return `<img class="card-btn-url-icon" src="${escapeIconAttribute(value)}" alt="" aria-hidden="true" />`;
+    }
+    return sanitizeIconHtml(value);
+}
 class CardButton extends BaseElement {
     render() {
         if (!this.shadowRoot || !this._node)
@@ -2489,12 +2550,18 @@ class CardButton extends BaseElement {
           width: 1em;
           height: 1em;
         }
+        .card-btn-url-icon {
+          display: block;
+          width: 100%;
+          height: 100%;
+          object-fit: contain;
+        }
       </style>
       <button
         class="card-btn ${variant} ${isMobile ? 'card-mobile' : 'card-desktop'}"
         ${disabled ? 'disabled' : ''}
         style="${inlineStyle}"
-      ><span class="card-btn-content">${icon ? `<span class="card-btn-icon">${sanitizeIconHtml(String(icon))}</span>` : ''}${displayText}</span></button>
+      ><span class="card-btn-content">${icon ? `<span class="card-btn-icon">${renderButtonIcon(icon)}</span>` : ''}${displayText}</span></button>
     `);
     }
 }
@@ -2681,7 +2748,7 @@ class CardInput extends BaseElement {
     render() {
         if (!this.shadowRoot || !this._node)
             return;
-        const { placeholder = '', inputType = 'text', label, defaultValue = '', disabled = false, readonly: readOnly = false, maxLength, rows, min, max, step = 1, controls = true, prefix, suffix, style, inputStyle, isExpressionResultStyle, } = this._props;
+        const { placeholder = '', autoFocus = false, inputType = 'text', label, defaultValue = '', disabled = false, readonly: readOnly = false, maxLength, rows, min, max, step = 1, controls = true, prefix, suffix, style, inputStyle, isExpressionResultStyle, } = this._props;
         const inlineStyle = this.buildInlineStyle(style, isExpressionResultStyle);
         const legacyInputStyle = style && typeof style === 'object' && style.resize != null
             ? { resize: style.resize }
@@ -2967,6 +3034,14 @@ class CardInput extends BaseElement {
                     detail: { value: inputEl.value },
                 }));
             });
+            if (autoFocus && !disabled) {
+                queueMicrotask(() => {
+                    const control = this.getAutoFocusControl();
+                    if (control && this.isFirstAvailableAutoFocusInput()) {
+                        control.focus();
+                    }
+                });
+            }
             if (isNumber &&
                 showNumberStepper &&
                 inputEl instanceof HTMLInputElement) {
@@ -2995,6 +3070,22 @@ class CardInput extends BaseElement {
         }
     }
     // ─── Helpers ──────────────────────────────────────────────────
+    getAutoFocusControl() {
+        if (!this.isConnected
+            || !this._props.autoFocus
+            || this.hasAttribute('data-disabled')) {
+            return null;
+        }
+        const control = this.shadowRoot?.querySelector('.card-input');
+        return control && !control.disabled ? control : null;
+    }
+    isFirstAvailableAutoFocusInput() {
+        const root = this.getRootNode();
+        if (!('querySelectorAll' in root))
+            return false;
+        const firstAvailable = Array.from(root.querySelectorAll(CardInput.is)).find(input => input.getAutoFocusControl() !== null);
+        return firstAvailable === this;
+    }
     /** Escape HTML entities for safe insertion. */
     escapeHtml(str) {
         return str
@@ -4716,7 +4807,7 @@ class CardForm extends BaseElement {
         this._bindEvents(fields, disabled);
     }
     _renderField(field, index) {
-        const { name, label, type = 'text', placeholder = '', required = false, rules = [], prefix, suffix, options = [], length = 6, } = field;
+        const { name, label, type = 'text', placeholder = '', required = false, rules = [], prefix, suffix, length = 6, } = field;
         const val = this._values[name] ?? '';
         const error = this._errors[name] || '';
         const errorClass = error ? 'error' : '';
@@ -6988,11 +7079,12 @@ class CardChoiceItem extends BaseElement {
             ...(selected ? selectedIndicatorStyle || {} : {}),
         }, isExpressionResultStyle);
         const indicatorRole = selectionMode === 'single' ? 'radio' : 'checkbox';
-        const resolvedCheckedIcon = checkedIcon ?? listCheckedIcon ?? {
+        const configuredCheckedIcon = checkedIcon ?? listCheckedIcon;
+        const resolvedCheckedIcon = configuredCheckedIcon ?? {
             name: 'check_bold',
             size: 12,
         };
-        const checkedMark = selectionMode === 'multiple'
+        const checkedMark = selectionMode === 'multiple' || configuredCheckedIcon
             ? `<span class="choice-icon" aria-hidden="true">${renderIconContent(resolvedCheckedIcon)}</span>`
             : '<span class="radio-dot" aria-hidden="true"></span>';
         this.setAttribute('data-selected', String(selected));
@@ -7631,6 +7723,8 @@ function renderDefault(node, props, isMobile, responsive) {
     div.className = `card-element card-${node.type.toLowerCase()} ${isMobile ? 'card-mobile' : 'card-desktop'}`;
     div.setAttribute('data-card-id', node.id);
     div.setAttribute('data-card-type', node.type);
+    // Apply slot base styles FIRST (so props.style can override)
+    applySlotBaseStyle(div, props);
     if (props.style && typeof props.style === 'object') {
         const resolvedStyle = buildStyleString(props.isExpressionResultStyle
             ? props.style
@@ -7713,18 +7807,9 @@ function renderBoundCard(container, schema, options) {
     let currentMaterialized;
     let revision = 0;
     let disposed = false;
-    let isMobile = options.isMobile ?? isMobileViewport();
+    const isMobile = options.isMobile === true;
     let actionQueue = Promise.resolve();
     let lifecycleQueue = Promise.resolve();
-    const removeViewportListener = options.isMobile == null
-        ? onViewportChange((mobile) => {
-            if (disposed)
-                return;
-            isMobile = mobile;
-            const candidate = prepareCandidate(variables);
-            publishDOM(candidate, false);
-        })
-        : () => { };
     function expressionContextFor(node) {
         return isBoundRenderTreeNode(node)
             ? createExpressionContext(node.scope)
@@ -7961,6 +8046,33 @@ function renderBoundCard(container, schema, options) {
             writable: true,
         });
     }
+    function jsonDataEqual(before, after) {
+        if (Object.is(before, after))
+            return true;
+        if (Array.isArray(before) || Array.isArray(after)) {
+            if (!Array.isArray(before) || !Array.isArray(after))
+                return false;
+            return before.length === after.length
+                && before.every((value, index) => jsonDataEqual(value, after[index]));
+        }
+        if (before === null
+            || after === null
+            || typeof before !== 'object'
+            || typeof after !== 'object') {
+            return false;
+        }
+        const beforeRecord = before;
+        const afterRecord = after;
+        const beforeKeys = Object.keys(beforeRecord);
+        const afterKeys = Object.keys(afterRecord);
+        return beforeKeys.length === afterKeys.length
+            && beforeKeys.every(key => Object.prototype.hasOwnProperty.call(afterRecord, key)
+                && jsonDataEqual(beforeRecord[key], afterRecord[key]));
+    }
+    function hasVariableChanges(before, after) {
+        const validatedAfter = cloneJsonData(after);
+        return !jsonDataEqual(before, validatedAfter);
+    }
     function createDraftActionContext(node, draft) {
         const write = (key, value) => {
             writeDraftVariable(draft, key, value);
@@ -7989,6 +8101,7 @@ function renderBoundCard(container, schema, options) {
         if (eventDetail !== undefined) {
             writeDraftVariable(draft, '_event', cloneJsonData(eventDetail));
         }
+        const actionBaseline = cloneJsonData(draft);
         const freshMaterialized = materializeCard(schema, draft);
         const freshNode = indexNodes(freshMaterialized.root).get(runtimeId);
         if (!freshNode) {
@@ -8002,6 +8115,8 @@ function renderBoundCard(container, schema, options) {
             return;
         await runActionSteps(steps, createDraftActionContext(freshNode, draft));
         assertCurrentRevision(baseRevision);
+        if (!hasVariableChanges(actionBaseline, draft))
+            return;
         const candidate = prepareCandidate(draft);
         commitDraft(draft, candidate, baseRevision);
     }
@@ -8041,7 +8156,6 @@ function renderBoundCard(container, schema, options) {
                 return;
             disposed = true;
             abortController.abort();
-            removeViewportListener();
             disposeChartsIn(container);
             container.replaceChildren();
             const lifecycleNodes = [...activeLifecycleNodes.entries()];
@@ -8169,50 +8283,124 @@ function renderStaticCard(container, schema, options) {
     const tree = parseSchema(schema);
     // 3. Reactive variables store (mutable copy, merged with external variables)
     let variables = { ...schema.variables, ...options.variables };
-    // 4. Create action context with setVariable wired into re-render
-    const lifecycleManager = createLifecycleManager();
+    let disposed = false;
+    let hostAuthorityEpoch = 0;
+    const lifecycleRecords = new Map();
     const abortController = new AbortController();
     // Per-instance request dedup map (isolated from other cards on the page).
     const inflightRequests = new Map();
     function buildActionContext() {
-        return {
+        const baseAuthorityEpoch = hostAuthorityEpoch;
+        let context;
+        const writeVariable = (key, value, { silent }) => {
+            let actionVariables = context.variables;
+            if (disposed || baseAuthorityEpoch !== hostAuthorityEpoch) {
+                if (actionVariables === variables) {
+                    actionVariables = { ...actionVariables };
+                    context.variables = actionVariables;
+                }
+                actionVariables[key] = value;
+                return;
+            }
+            actionVariables[key] = value;
+            if (!silent)
+                rerender();
+        };
+        context = {
             ...createWebActionContext({
                 ...options,
                 setVariable: (key, value) => {
-                    variables[key] = value;
-                    // Trigger re-render after variable change
-                    rerender();
+                    writeVariable(key, value, { silent: false});
                 },
                 abortSignal: abortController.signal,
             }),
             variables,
+            variableWriter: writeVariable,
             botId: options.botId,
             inflightRequests,
         };
+        return context;
     }
     let actionContext = buildActionContext();
     // 5. Responsive
-    let isMobile = options.isMobile ?? isMobileViewport();
-    const removeViewportListener = options.isMobile == null
-        ? onViewportChange((mobile) => {
-            isMobile = mobile;
-            rerender();
-        })
-        : () => { };
+    const isMobile = options.isMobile === true;
     // 6. Schema-level action definitions (for string references in events)
     const schemaActions = schema.actions ?? {};
+    function destroyLifecycle(record) {
+        if (record.state !== 'mounted')
+            return;
+        record.state = 'destroying';
+        void runActionSteps(record.lifecycle.onDestroy ?? [], buildActionContext())
+            .catch((error) => {
+            console.error('[renderCard] Static lifecycle destroy failed', error);
+        })
+            .finally(() => {
+            record.state = 'destroyed';
+        });
+    }
+    function startLifecycleMount(id, lifecycle) {
+        if (disposed || lifecycleRecords.has(id))
+            return;
+        const record = { lifecycle, state: 'mounting' };
+        lifecycleRecords.set(id, record);
+        void runActionSteps(lifecycle.onMount ?? [], buildActionContext())
+            .then(() => {
+            record.state = 'mounted';
+            if (disposed)
+                destroyLifecycle(record);
+        })
+            .catch((error) => {
+            console.error('[renderCard] Static lifecycle mount failed', error);
+            if (disposed) {
+                record.state = 'destroyed';
+            }
+            else if (lifecycleRecords.get(id) === record) {
+                lifecycleRecords.delete(id);
+            }
+        });
+    }
     // 7. Render function
+    let renderGeneration = 0;
     function render() {
+        if (disposed)
+            return;
+        const generation = ++renderGeneration;
+        const collectedLifecycles = [];
         const scrollPositions = captureScrollPositions(container);
         const mediaStates = captureMediaStates(container);
         disposeChartsIn(container); // tear down old chart instances before clearing
-        container.innerHTML = '';
-        const dom = renderNode(tree, variables, actionContext, isMobile, options.responsive, lifecycleManager, schemaActions);
-        container.appendChild(dom);
+        const dom = renderNode(tree, variables, actionContext, isMobile, options.responsive, schemaActions, (key, value, sourceVariables) => {
+            if (disposed || sourceVariables !== variables)
+                return;
+            variables[key] = value;
+            hostAuthorityEpoch += 1;
+        }, (steps, detail) => {
+            if (disposed)
+                return;
+            if (detail != null)
+                variables._event = detail;
+            void runActionSteps(steps, buildActionContext()).catch((error) => {
+                console.error('[renderCard] Static action failed', error);
+            });
+        }, (id, lifecycle) => {
+            collectedLifecycles.push({ id, lifecycle });
+        });
+        if (disposed || generation !== renderGeneration)
+            return;
+        container.replaceChildren(dom);
         restoreScrollPositions(container, scrollPositions);
         restoreMediaStates(container, mediaStates);
+        if (disposed || generation !== renderGeneration)
+            return;
+        for (const { id, lifecycle } of collectedLifecycles) {
+            if (disposed || generation !== renderGeneration)
+                break;
+            startLifecycleMount(id, lifecycle);
+        }
     }
     function rerender() {
+        if (disposed)
+            return;
         actionContext = buildActionContext();
         render();
     }
@@ -8221,13 +8409,20 @@ function renderStaticCard(container, schema, options) {
     // 8. Return instance handle
     return {
         dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            hostAuthorityEpoch += 1;
             abortController.abort();
-            removeViewportListener();
-            lifecycleManager.dispose(actionContext);
             disposeChartsIn(container);
-            container.innerHTML = '';
+            container.replaceChildren();
+            for (const record of lifecycleRecords.values())
+                destroyLifecycle(record);
         },
         updateVariables(newVars) {
+            if (disposed)
+                return;
+            hostAuthorityEpoch += 1;
             variables = { ...variables, ...newVars };
             rerender();
         },
@@ -8305,7 +8500,7 @@ function restoreMediaStates(root, states) {
     });
 }
 // ─── Recursive Node Renderer ─────────────────────────────────────
-function renderNode(node, variables, actionContext, isMobile, responsive, lifecycleManager, schemaActions) {
+function renderNode(node, variables, actionContext, isMobile, responsive, schemaActions, writeInputVariable, runEventActions, collectLifecycle) {
     // Check directives.visible
     if (node.directives?.visible) {
         const visibleExpr = node.directives.visible;
@@ -8363,7 +8558,7 @@ function renderNode(node, variables, actionContext, isMobile, responsive, lifecy
                 ?? e.target?.value;
             if (value !== undefined) {
                 // Write silently — do NOT trigger rerender (avoids losing focus)
-                variables[variableKey] = value;
+                writeInputVariable(variableKey, value, variables);
             }
         }));
     }
@@ -8385,21 +8580,17 @@ function renderNode(node, variables, actionContext, isMobile, responsive, lifecy
                     && VALUE_CONTROL_TYPES.has(node.type));
                 if (ownsValueEvent && e.target !== el)
                     return;
-                // Write event.detail to _event variable so action params can use ${_event.xxx}
-                if (e instanceof CustomEvent && e.detail != null) {
-                    variables._event = e.detail;
-                }
-                runActionSteps(resolvedSteps, actionContext);
+                const detail = e instanceof CustomEvent ? e.detail : undefined;
+                runEventActions(resolvedSteps, detail);
             }));
         }
     }
     // Register lifecycle
     if (node.lifecycle) {
-        lifecycleManager.register(node.id, node.lifecycle);
-        lifecycleManager.mount(node.id, actionContext);
+        collectLifecycle(node.id, node.lifecycle);
     }
     // Render children — use slot layout if applicable, otherwise flat append
-    const renderChild = (child) => renderNode(child, variables, actionContext, isMobile, responsive, lifecycleManager, schemaActions);
+    const renderChild = (child) => renderNode(child, variables, actionContext, isMobile, responsive, schemaActions, writeInputVariable, runEventActions, collectLifecycle);
     // Build children-by-id map for layouts that reference IDs (columns groups, float overlays)
     const childrenMap = {};
     for (const child of node.children) {
@@ -8495,7 +8686,7 @@ function renderStreamingCard(container, options = {}) {
     let partialVariablesSent = false;
     let partialFinalized = false;
     let variables = { ...options.variables };
-    let isMobile = options.isMobile ?? isMobileViewport();
+    const isMobile = options.isMobile === true;
     let currentSchema = null;
     let currentSurfaceId = null;
     let currentMaterialized = null;
@@ -8507,16 +8698,6 @@ function renderStreamingCard(container, options = {}) {
     const activeBoundLifecycles = new Map();
     const mountedBoundLifecycles = new Map();
     const boundLifecycleGenerations = new Map();
-    // Responsive viewport detection
-    const removeViewportListener = options.isMobile == null
-        ? onViewportChange((mobile) => {
-            isMobile = mobile;
-            // Re-render all elements with new mobile state if schema exists
-            if (currentSchema) {
-                rerenderAll();
-            }
-        })
-        : () => { };
     // ─── Action Context ─────────────────────────────────────────────
     function buildActionContext() {
         return {
@@ -9888,14 +10069,6 @@ function renderStreamingCard(container, options = {}) {
             console.warn('[renderStreamingCard] Deferred render (incomplete schema):', error);
         }
     }
-    /**
-     * Re-render all elements (viewport changes — isMobile affects every renderer's
-     * output, so the incremental diff cache cannot be reused here).
-     */
-    function rerenderAll() {
-        actionContext = buildActionContext();
-        safeRenderFull();
-    }
     // ─── Engine Event Handlers ──────────────────────────────────────
     const engine = new StreamingEngine({
         onSurfaceCreated(surfaceId, schemaInput) {
@@ -10240,7 +10413,7 @@ function renderStreamingCard(container, options = {}) {
                 }
             }
         },
-        onSurfaceDeleted(surfaceId) {
+        onSurfaceDeleted(_surfaceId) {
             disposeChartsIn(container); // release old ECharts instances before clearing
             container.innerHTML = '';
             elementMap.clear();
@@ -10335,7 +10508,6 @@ function renderStreamingCard(container, options = {}) {
             disposed = true;
             boundRevision += 1;
             abortController.abort();
-            removeViewportListener();
             teardownBoundLifecycles();
             lifecycleManager.dispose(actionContext);
             disposeChartsIn(container); // release ECharts instances before clearing
@@ -10504,7 +10676,7 @@ class BotSDK {
         this._instances = [];
         /** Declarative action chains loaded from actionProvider */
         this._actionChains = new Map();
-        this.botId = options.botId;
+        this.botId = options.botId ?? '';
         this.baseUrl = options.baseUrl ?? '';
         // Source B: Batch-register action handler functions (sync, immediate)
         if (options.onAction) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antglobal/copilot-cards-web",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Web Component renderer for copilot bot card SDK — PC + Mobile + WebView unified rendering via Custom Elements",
   "type": "module",
   "module": "./dist/index.js",
@@ -28,7 +28,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@antglobal/copilot-cards-core": "^1.0.4",
+    "@antglobal/copilot-cards-core": "^1.0.6",
     "echarts": "^5.6.0",
     "marked": "^18.0.5",
     "tslib": "^2.8.1",