@antglobal/copilot-cards-web 0.0.20260828032020-dev.1 → 0.0.20260828032020-dev.5

package/README.md

@@ -113,10 +113,44 @@ Renders a complete schema and returns a `CardInstance`:
 ```ts
 interface CardInstance {
   updateVariables(variables: Record<string, unknown>): void;
+  onScroll(nodeId: string, listener: CardScrollListener): () => void;
   dispose(): void;
 }
 ```
 
+`CardScrollEvent` and `CardScrollListener` are top-level package exports. The
+event contains readonly `node`, `scrollTop`, `scrollLeft`, `scrollHeight`,
+`scrollWidth`, `clientHeight`, and `clientWidth` values:
+
+```ts
+import type {
+  CardScrollEvent,
+  CardScrollListener,
+} from "@antglobal/copilot-cards-web";
+
+const unsubscribe = card.onScroll("friendsList", event => {
+  const remaining =
+    event.scrollHeight - event.clientHeight - event.scrollTop;
+});
+
+unsubscribe(); // Idempotent; card.dispose() also removes the subscription.
+```
+
+The subscription follows the logical node ID across physical replacement and
+reports native-frequency values. It does not emit an initial, render, resize,
+or `updateVariables` callback. Generated internal scroll tracks and scroll
+ports inside Shadow DOM are not observed. Thresholds, throttling, requests,
+locks, cursors, retries, and deduplication remain host responsibilities.
+
+For pagination, continue passing the complete next array to `updateVariables`.
+The SDK retains the Repeat owner and old prefix only when it can strictly prove
+a structurally equal tail extension whose retained rendering is unchanged, on
+a default-rendered `Container` with an unambiguous direct-child `default` or
+`flex` layout. Every unproven case uses the existing replacement behavior; this
+is not a general keyed diff or public append API. A trailing control object is
+eligible only when it does not change retained rows. Put temporary loading UI
+outside the Repeat owner when scroll identity matters.
+
 Common render options include:
 
 | Option | Purpose |

package/dist/index.d.ts

@@ -55,6 +55,23 @@ interface CardFocusChangeEvent {
     previousNode: CardNodeHandle | null;
 }
 type CardFocusChangeListener = (event: CardFocusChangeEvent) => void;
+interface CardScrollEvent {
+    /** Stable logical handle for the scrolling card node. */
+    readonly node: CardNodeHandle;
+    /** Raw native vertical scroll offset. */
+    readonly scrollTop: number;
+    /** Raw native horizontal scroll offset, including negative RTL values. */
+    readonly scrollLeft: number;
+    /** Raw native scrollable content height. */
+    readonly scrollHeight: number;
+    /** Raw native scrollable content width. */
+    readonly scrollWidth: number;
+    /** Raw native viewport height. */
+    readonly clientHeight: number;
+    /** Raw native viewport width. */
+    readonly clientWidth: number;
+}
+type CardScrollListener = (event: CardScrollEvent) => void;
 
 interface ResponsiveMobileOptions {
     readonly unit: 'rem';
@@ -108,6 +125,8 @@ interface CardInstance {
     getNode: (id: string) => CardNodeHandle;
     /** Observe logical focus changes within this card. */
     onFocusChange: (listener: CardFocusChangeListener) => () => void;
+    /** Observe native scroll metrics for one logical card node. */
+    onScroll: (nodeId: string, listener: CardScrollListener) => () => void;
 }
 /**
  * Render a card schema into a container element.
@@ -1841,4 +1860,4 @@ declare const componentRenderers: Record<string, ComponentRenderer>;
 declare function registerComponent(type: string, renderer: ComponentRenderer): void;
 
 export { BaseElement, BotSDK, CardButton, CardChoiceItem, CardChoiceList, CardCollapse, CardCounter, CardDivider, CardForm, CardHtml, CardIcon, CardImage, CardInput, CardLoading, CardPasscodeInput, CardProgress, CardRate, CardSelect, CardSteps, CardSwitch, CardTag, CardText, DEFAULT_MOBILE_RESPONSIVE, LocalActionConfigProvider, RemoteActionConfigProvider, buildStyleString, componentRenderers, connectSSE, connectStreaming, convertPixelTokens, createResponsiveContext, createWebActionContext, isMobileViewport, onViewportChange, pxToRem, pxToVw, registerComponent, renderCard, renderStreamingCard, resolveSize, sanitizeHtml, trimIncompleteTag };
-export type { A2UIActionPayload, BotSDKOptions, ButtonProps, CardFocusChangeEvent, CardFocusChangeListener, CardInstance, CardNodeHandle, ChoiceIndicatorIcon, ChoiceItemProps, ChoiceListProps, ChoiceListValue, CollapseProps, ComponentRenderer, ConnectorConfig, CounterIcon, CounterProps, DividerProps, FormField, FormProps, FormRule, HtmlProps, IconProps, ImageProps, InputAffix, InputAffixConfig, InputProps, LoadingProps, PartialFinalizeResult, PasscodeInputProps, ProgressProps, ProgressSegment, RateProps, RenderCardOptions, ResponsiveContext, ResponsiveMobileOptions, ResponsiveOptions, SSEConnectOptions, SelectOption, SelectProps, SelectSize, SelectStyles, SelectVariant, StepIcon, StepItem, StepsProps, StreamingCardInstance, StreamingCardOptions, StreamingConnectOptions, StreamingConnection, SwitchProps, TagProps, TextProps, WebActionContextOptions };
+export type { A2UIActionPayload, BotSDKOptions, ButtonProps, CardFocusChangeEvent, CardFocusChangeListener, CardInstance, CardNodeHandle, CardScrollEvent, CardScrollListener, ChoiceIndicatorIcon, ChoiceItemProps, ChoiceListProps, ChoiceListValue, CollapseProps, ComponentRenderer, ConnectorConfig, CounterIcon, CounterProps, DividerProps, FormField, FormProps, FormRule, HtmlProps, IconProps, ImageProps, InputAffix, InputAffixConfig, InputProps, LoadingProps, PartialFinalizeResult, PasscodeInputProps, ProgressProps, ProgressSegment, RateProps, RenderCardOptions, ResponsiveContext, ResponsiveMobileOptions, ResponsiveOptions, SSEConnectOptions, SelectOption, SelectProps, SelectSize, SelectStyles, SelectVariant, StepIcon, StepItem, StepsProps, StreamingCardInstance, StreamingCardOptions, StreamingConnectOptions, StreamingConnection, SwitchProps, TagProps, TextProps, WebActionContextOptions };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { getBuiltinIcon, cloneJsonData, createLifecycleManager, materializeCard, findAffectedRepeatOwners, createA2UIParameterResolver, createExpressionContext, replaceRootContents, resolveA2UIDeep, resolveDeep, resolveExpressionValue, resolveActionRef, isBoundRenderTreeNode, hasExpression, resolveExpression, runActionSteps, normalizeSchema, validateSchema, requiresBindingMaterialization, parseSchema, StreamingParser, StreamingEngine, bindingTopologyFingerprint, findTemplateRepeatOwners, extractPartialSchema, runActionStep, registry } from '@antglobal/copilot-cards-core';
+import { getBuiltinIcon, cloneJsonData, createLifecycleManager, materializeCard, findAffectedRepeatOwners, createA2UIParameterResolver, createExpressionContext, replaceRootContents, getByJsonPointer, resolveA2UIDeep, resolveDeep, resolveExpressionValue, resolveActionRef, isBoundRenderTreeNode, hasExpression, resolveExpression, runActionSteps, normalizeSchema, validateSchema, requiresBindingMaterialization, parseSchema, StreamingParser, StreamingEngine, 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';
@@ -763,9 +763,33 @@ const CAROUSEL_HOST_PRESENTATION_OWNERSHIP = {
     attributes: [CAROUSEL_SCROLL_ID_ATTRIBUTE],
     styleProperties: Object.keys(carouselHostStyles(0)).map(toCSSPropertyName),
 };
+function getNonDefaultSlotKeys(props) {
+    const slots = props.slots;
+    return slots
+        ? Object.keys(slots).filter(key => key !== SLOT_LAYOUT.DEFAULT)
+        : [];
+}
 function findSpecialSlotKey(props) {
+    return getNonDefaultSlotKeys(props)[0];
+}
+/**
+ * Report whether a materialized Repeat slot maps directly onto its owner host.
+ * Ambiguous and wrapper/controller layouts deliberately fail closed.
+ */
+function getDirectChildRepeatAppendLayout(props, repeatSlot) {
     const slots = props.slots;
-    return slots && Object.keys(slots).find(key => key !== SLOT_LAYOUT.DEFAULT);
+    if (!slots || slots[repeatSlot] == null)
+        return undefined;
+    const nonDefaultKeys = getNonDefaultSlotKeys(props);
+    if (nonDefaultKeys.length > 1)
+        return undefined;
+    const effectiveSlot = findSpecialSlotKey(props) ?? SLOT_LAYOUT.DEFAULT;
+    if (effectiveSlot !== repeatSlot)
+        return undefined;
+    return effectiveSlot === SLOT_LAYOUT.DEFAULT
+        || effectiveSlot === SLOT_LAYOUT.FLEX
+        ? effectiveSlot
+        : undefined;
 }
 /** Host attributes/styles owned by the active slot renderer after shell render. */
 function getSlotHostPresentationOwnership(props) {
@@ -8917,12 +8941,14 @@ const FOCUS_TARGET_SELECTOR = [
  */
 function createCardNodeAccess(container) {
     const handles = new Map();
-    const listeners = new Set();
+    const focusListeners = new Set();
+    const scrollSubscriptions = new Map();
     let focusedId = null;
     let focusSyncScheduled = false;
-    let observing = false;
+    let focusObserving = false;
+    let scrollObserving = false;
     let observationEpoch = 0;
-    let observer = null;
+    let focusObserver = null;
     let disposed = false;
     const resolveElement = (id) => {
         if (disposed)
@@ -8993,7 +9019,7 @@ function createCardNodeAccess(container) {
         return null;
     };
     const syncFocus = () => {
-        if (disposed || !observing)
+        if (disposed || !focusObserving)
             return;
         const nextId = resolveFocusedId();
         if (nextId === focusedId)
@@ -9001,7 +9027,7 @@ function createCardNodeAccess(container) {
         const previousNode = focusedId ? getNode(focusedId) : null;
         const node = nextId ? getNode(nextId) : null;
         focusedId = nextId;
-        for (const listener of [...listeners]) {
+        for (const listener of [...focusListeners]) {
             try {
                 listener({ node, previousNode });
             }
@@ -9011,7 +9037,7 @@ function createCardNodeAccess(container) {
         }
     };
     const scheduleFocusSync = () => {
-        if (disposed || !observing || focusSyncScheduled)
+        if (disposed || !focusObserving || focusSyncScheduled)
             return;
         focusSyncScheduled = true;
         const scheduledEpoch = observationEpoch;
@@ -9022,29 +9048,29 @@ function createCardNodeAccess(container) {
             syncFocus();
         });
     };
-    const startObserving = () => {
-        if (disposed || observing)
+    const startFocusObserving = () => {
+        if (disposed || focusObserving)
             return;
-        observing = true;
+        focusObserving = true;
         observationEpoch += 1;
         focusedId = resolveFocusedId();
         container.addEventListener('focusin', scheduleFocusSync, true);
         container.addEventListener('focusout', scheduleFocusSync, true);
         if (typeof MutationObserver !== 'undefined') {
-            observer ?? (observer = new MutationObserver(scheduleFocusSync));
-            observer.observe(container, { childList: true, subtree: true });
+            focusObserver ?? (focusObserver = new MutationObserver(scheduleFocusSync));
+            focusObserver.observe(container, { childList: true, subtree: true });
         }
     };
-    const stopObserving = () => {
-        if (!observing)
+    const stopFocusObserving = () => {
+        if (!focusObserving)
             return;
-        observing = false;
+        focusObserving = false;
         observationEpoch += 1;
         focusSyncScheduled = false;
         const cleanupSteps = [
             () => container.removeEventListener('focusin', scheduleFocusSync, true),
             () => container.removeEventListener('focusout', scheduleFocusSync, true),
-            () => observer?.disconnect(),
+            () => focusObserver?.disconnect(),
         ];
         for (const cleanup of cleanupSteps) {
             try {
@@ -9056,30 +9082,111 @@ function createCardNodeAccess(container) {
         }
         focusedId = null;
     };
+    const handleScroll = (event) => {
+        if (disposed || !scrollObserving)
+            return;
+        const path = typeof event.composedPath === 'function'
+            ? event.composedPath()
+            : [];
+        const target = path[0] ?? event.target;
+        if (!(target instanceof HTMLElement)
+            || !target.matches(CARD_NODE_SELECTOR)) {
+            return;
+        }
+        const nodeId = target.getAttribute('data-card-id');
+        if (!nodeId || resolveElement(nodeId) !== target)
+            return;
+        const subscriptions = scrollSubscriptions.get(nodeId);
+        if (!subscriptions?.size)
+            return;
+        const snapshot = Object.freeze({
+            node: getNode(nodeId),
+            scrollTop: target.scrollTop,
+            scrollLeft: target.scrollLeft,
+            scrollHeight: target.scrollHeight,
+            scrollWidth: target.scrollWidth,
+            clientHeight: target.clientHeight,
+            clientWidth: target.clientWidth,
+        });
+        for (const subscription of [...subscriptions]) {
+            try {
+                subscription.listener(snapshot);
+            }
+            catch (error) {
+                console.error('[CardInstance] scroll listener failed', error);
+            }
+        }
+    };
+    const startScrollObserving = () => {
+        if (disposed || scrollObserving)
+            return;
+        scrollObserving = true;
+        container.addEventListener('scroll', handleScroll, {
+            capture: true,
+            passive: true,
+        });
+    };
+    const stopScrollObserving = () => {
+        if (!scrollObserving)
+            return;
+        scrollObserving = false;
+        try {
+            container.removeEventListener('scroll', handleScroll, true);
+        }
+        catch (error) {
+            console.error('[CardInstance] Scroll observation cleanup failed', error);
+        }
+    };
     return {
         getNode,
         onFocusChange(listener) {
             if (disposed)
                 return () => { };
-            listeners.add(listener);
-            if (listeners.size === 1)
-                startObserving();
+            focusListeners.add(listener);
+            if (focusListeners.size === 1)
+                startFocusObserving();
+            let subscribed = true;
+            return () => {
+                if (!subscribed)
+                    return;
+                subscribed = false;
+                focusListeners.delete(listener);
+                if (focusListeners.size === 0)
+                    stopFocusObserving();
+            };
+        },
+        onScroll(nodeId, listener) {
+            if (disposed)
+                return () => { };
+            const subscription = { listener };
+            let subscriptions = scrollSubscriptions.get(nodeId);
+            if (!subscriptions) {
+                subscriptions = new Set();
+                scrollSubscriptions.set(nodeId, subscriptions);
+            }
+            subscriptions.add(subscription);
+            startScrollObserving();
             let subscribed = true;
             return () => {
                 if (!subscribed)
                     return;
                 subscribed = false;
-                listeners.delete(listener);
-                if (listeners.size === 0)
-                    stopObserving();
+                const active = scrollSubscriptions.get(nodeId);
+                active?.delete(subscription);
+                if (active?.size === 0)
+                    scrollSubscriptions.delete(nodeId);
+                if (scrollSubscriptions.size === 0)
+                    stopScrollObserving();
             };
         },
         dispose() {
             if (disposed)
                 return;
-            stopObserving();
+            stopFocusObserving();
+            stopScrollObserving();
             disposed = true;
-            listeners.clear();
+            focusListeners.clear();
+            scrollSubscriptions.clear();
             handles.clear();
         },
     };
@@ -9120,6 +9227,7 @@ function applyDisabledDescendants(element, disabled) {
 }
 
 const FORCE_REPLACE = Symbol('bound-force-replace');
+const REPEAT_APPEND = Symbol('bound-repeat-append');
 /**
  * Render the scoped/materialized branch of a card.
  *
@@ -9386,9 +9494,12 @@ function renderBoundCard(container, schema, options) {
             collectMountedOccurrences(child, occurrences);
         }
     }
-    function prepareBoundNode(node, occurrenceKey, renderVariables, forcedOwnerIds, current) {
+    function prepareBoundNode(node, occurrenceKey, renderVariables, forcedOwnerIds, appendPlans, current) {
         const metadata = resolveBoundMetadata(node, occurrenceKey, renderVariables);
         const forceReplace = forcedOwnerIds.has(node.id);
+        const appendPlan = current
+            ? appendPlans.get(current.occurrenceKey)
+            : undefined;
         if (!metadata.visible || forceReplace) {
             return {
                 ...metadata,
@@ -9414,14 +9525,17 @@ function renderBoundCard(container, schema, options) {
             const ordinal = nextChildOrdinals.get(currentChild.nodeId) ?? 0;
             nextChildOrdinals.set(currentChild.nodeId, ordinal + 1);
             const child = matching[Math.min(ordinal, matching.length - 1)];
-            children.push(prepareBoundNode(child, currentChild.occurrenceKey, renderVariables, forcedOwnerIds, currentChild));
+            children.push(prepareBoundNode(child, currentChild.occurrenceKey, renderVariables, forcedOwnerIds, appendPlans, currentChild));
         }
         return {
             ...metadata,
+            ...(appendPlan ? { [REPEAT_APPEND]: true } : {}),
             children,
         };
     }
     function decideBoundUpdate(current, next) {
+        if (next[REPEAT_APPEND])
+            return 'retain';
         if (next[FORCE_REPLACE]
             || current.occurrenceKey !== next.occurrenceKey
             || current.nodeId !== next.nodeId
@@ -9483,11 +9597,308 @@ function renderBoundCard(container, schema, options) {
         }
         return changed;
     }
-    function selectForcedRepeatOwnerIds(before, draft) {
-        if (currentMaterialized.unresolvedRepeatOwners.size > 0) {
-            return new Set([currentMaterialized.root.id]);
+    function pointerOverlaps(left, right) {
+        return left === right
+            || left === ''
+            || right === ''
+            || left.startsWith(`${right}/`)
+            || right.startsWith(`${left}/`);
+    }
+    function changedPointersOutsideSuffix(before, draft, sourcePath) {
+        const changed = collectChangedPointers(before, draft)
+            .filter(pointer => pointer !== sourcePath);
+        changed.push(`${sourcePath}/length`);
+        return [...new Set(changed)];
+    }
+    function repeatOwnerIdentityEqual(current, next) {
+        return current.key === next.key
+            && current.parentKey === next.parentKey
+            && current.runtimeOwnerId === next.runtimeOwnerId
+            && current.sourceOwnerId === next.sourceOwnerId
+            && current.slot === next.slot
+            && current.templateId === next.templateId
+            && current.emptyTemplateId === next.emptyTemplateId
+            && current.sourcePath === next.sourcePath
+            && current.dataPath === next.dataPath
+            && current.instancePath === next.instancePath
+            && current.depth === next.depth;
+    }
+    function hasStrictJsonPrefix(previous, next) {
+        return next.length > previous.length
+            && previous.every((value, index) => jsonDataEqual(value, next[index]));
+    }
+    function childNodeSequenceEqual(parent, expected) {
+        const actual = Array.from(parent.childNodes);
+        return actual.length === expected.length
+            && actual.every((node, index) => node === expected[index]);
+    }
+    function occurrenceKeysForChildren(parentOccurrenceKey, children) {
+        const ordinals = new Map();
+        return children.map((child) => {
+            const ordinal = ordinals.get(child.id) ?? 0;
+            ordinals.set(child.id, ordinal + 1);
+            return childOccurrenceKey(parentOccurrenceKey, child.id, ordinal);
+        });
+    }
+    function findMountedByOccurrenceKey(root, occurrenceKey) {
+        if (root.occurrenceKey === occurrenceKey)
+            return root;
+        for (const child of root.children) {
+            const match = findMountedByOccurrenceKey(child, occurrenceKey);
+            if (match)
+                return match;
+        }
+        return null;
+    }
+    function replaceMountedByOccurrenceKey(root, occurrenceKey, replacement) {
+        if (root.occurrenceKey === occurrenceKey)
+            return replacement;
+        for (let index = 0; index < root.children.length; index += 1) {
+            const replacedChild = replaceMountedByOccurrenceKey(root.children[index], occurrenceKey, replacement);
+            if (!replacedChild)
+                continue;
+            const children = root.children.slice();
+            children[index] = replacedChild;
+            return { ...root, children };
+        }
+        return null;
+    }
+    function mountedNodesById(root, nodeId) {
+        const matches = [];
+        const visit = (node) => {
+            if (node.nodeId === nodeId)
+                matches.push(node);
+            for (const child of node.children)
+                visit(child);
+        };
+        visit(root);
+        return matches;
+    }
+    function mountedTreeOrderMatchesDom(root) {
+        if (root.element.parentNode !== container
+            || container.childNodes.length !== 1
+            || container.firstChild !== root.element) {
+            return false;
+        }
+        const visit = (node) => {
+            let previous = null;
+            for (const child of node.children) {
+                if (!node.element.contains(child.element))
+                    return false;
+                if (previous
+                    && previous.compareDocumentPosition(child.element)
+                        !== Node.DOCUMENT_POSITION_FOLLOWING) {
+                    return false;
+                }
+                previous = child.element;
+                if (!visit(child))
+                    return false;
+            }
+            return true;
+        };
+        return visit(root);
+    }
+    function retainedSubtreeEquivalent(current, next) {
+        return current.occurrenceKey === next.occurrenceKey
+            && current.nodeId === next.nodeId
+            && current.nodeType === next.nodeType
+            && current.node.sourceId === next.node.sourceId
+            && current.node.instancePath === next.node.instancePath
+            && current.node.dataPath === next.node.dataPath
+            && current.node.bindingDialect === next.node.bindingDialect
+            && current.rendererToken === next.rendererToken
+            && current.visible === next.visible
+            && current.disabled === next.disabled
+            && current.propsFingerprint === next.propsFingerprint
+            && current.layoutFingerprint === next.layoutFingerprint
+            && current.bindingFingerprint === next.bindingFingerprint
+            && current.children.length === next.children.length
+            && current.children.every((child, index) => (retainedSubtreeEquivalent(child, next.children[index])));
+    }
+    function prepareComparableRetainedNode(node, occurrenceKey, renderVariables, current) {
+        const expectedKeys = occurrenceKeysForChildren(occurrenceKey, node.children);
+        if (current.children.length !== node.children.length
+            || current.children.some((child, index) => (child.occurrenceKey !== expectedKeys[index]))) {
+            return null;
+        }
+        const children = [];
+        for (let index = 0; index < node.children.length; index += 1) {
+            const child = prepareComparableRetainedNode(node.children[index], expectedKeys[index], renderVariables, current.children[index]);
+            if (!child)
+                return null;
+            children.push(child);
+        }
+        return {
+            ...resolveBoundMetadata(node, occurrenceKey, renderVariables),
+            children,
+        };
+    }
+    function projectRepeatOwnerPrefix(node, owner, current) {
+        const slots = node.props.slots;
+        const slot = slots?.[owner.slot];
+        const currentSlots = current.node.props.slots;
+        const currentSlot = currentSlots?.[owner.slot];
+        if (!slots
+            || !slot
+            || !Array.isArray(slot.children)
+            || !currentSlot
+            || !Array.isArray(currentSlot.children)
+            || currentSlot.children.length >= slot.children.length
+            || currentSlot.children.some((childId, index) => (childId !== slot.children[index]))) {
+            return null;
+        }
+        const appendedChildIds = new Set(slot.children.slice(currentSlot.children.length));
+        const children = node.children.filter(child => (!appendedChildIds.has(child.id)));
+        if (children.length !== current.children.length
+            || node.children.length - children.length !== appendedChildIds.size) {
+            return null;
+        }
+        return {
+            ...node,
+            props: {
+                ...node.props,
+                slots: {
+                    ...slots,
+                    [owner.slot]: {
+                        ...slot,
+                        children: slot.children.slice(0, currentSlot.children.length),
+                    },
+                },
+            },
+            children,
+        };
+    }
+    function collectRetainedRepeatOwnerKeys(materialized, outerOwner) {
+        const retained = new Set([outerOwner.key]);
+        for (const candidate of materialized.repeatOwners.values()) {
+            let parentKey = candidate.parentKey;
+            while (parentKey) {
+                if (parentKey === outerOwner.key) {
+                    retained.add(candidate.key);
+                    break;
+                }
+                parentKey = materialized.repeatOwners.get(parentKey)?.parentKey;
+            }
+        }
+        return retained;
+    }
+    function retainedOwnersConsumeChangedPointer(materialized, retainedOwnerKeys, pointers) {
+        for (const [key, dependencyOwners] of materialized.valueDependencies) {
+            if (!key.startsWith('data:')
+                || ![...dependencyOwners].some(ownerKey => (retainedOwnerKeys.has(ownerKey)))) {
+                continue;
+            }
+            const dependency = key.slice('data:'.length);
+            if (pointers.some(pointer => pointerOverlaps(pointer, dependency))) {
+                return true;
+            }
+        }
+        return false;
+    }
+    function createRepeatAppendPlan(currentOwner, nextMaterialized, before, draft) {
+        if (!currentMountedTree || !mountedTreeOrderMatchesDom(currentMountedTree)) {
+            return null;
+        }
+        const nextOwner = nextMaterialized.repeatOwners.get(currentOwner.key);
+        if (!nextOwner || !repeatOwnerIdentityEqual(currentOwner, nextOwner)) {
+            return null;
+        }
+        const currentOwnerCount = [...currentMaterialized.repeatOwners.values()]
+            .filter(owner => owner.runtimeOwnerId === currentOwner.runtimeOwnerId)
+            .length;
+        const nextOwnerCount = [...nextMaterialized.repeatOwners.values()]
+            .filter(owner => owner.runtimeOwnerId === nextOwner.runtimeOwnerId)
+            .length;
+        if (currentOwnerCount !== 1 || nextOwnerCount !== 1)
+            return null;
+        const mountedMatches = mountedNodesById(currentMountedTree, currentOwner.runtimeOwnerId);
+        if (mountedMatches.length !== 1)
+            return null;
+        const current = mountedMatches[0];
+        const nextNode = nextMaterialized.instances
+            .get(nextOwner.runtimeOwnerId)?.node;
+        if (!nextNode
+            || current.nodeType !== 'Container'
+            || nextNode.type !== 'Container'
+            || current.rendererToken !== componentRenderers._default
+            || !current.visible
+            || !current.resolvedProps
+            || !currentOwner.sourcePath
+            || !nextOwner.sourcePath) {
+            return null;
+        }
+        const nextMetadata = resolveBoundMetadata(nextNode, current.occurrenceKey, draft);
+        const currentLayout = getDirectChildRepeatAppendLayout(current.resolvedProps, currentOwner.slot);
+        const nextLayout = nextMetadata.resolvedProps
+            ? getDirectChildRepeatAppendLayout(nextMetadata.resolvedProps, nextOwner.slot)
+            : undefined;
+        if (!currentLayout || currentLayout !== nextLayout)
+            return null;
+        let previousSource;
+        let nextSource;
+        try {
+            previousSource = getByJsonPointer(lastPublishedVariables, currentOwner.sourcePath);
+            nextSource = getByJsonPointer(draft, nextOwner.sourcePath);
         }
-        const selectedKeys = new Set();
+        catch {
+            return null;
+        }
+        if (!Array.isArray(previousSource)
+            || !Array.isArray(nextSource)
+            || !hasStrictJsonPrefix(previousSource, nextSource)) {
+            return null;
+        }
+        const nextOccurrenceKeys = occurrenceKeysForChildren(current.occurrenceKey, nextNode.children);
+        if (current.children.length >= nextNode.children.length
+            || current.children.some((child, index) => (child.occurrenceKey !== nextOccurrenceKeys[index]))
+            || !childNodeSequenceEqual(current.element, current.children.map(child => child.element))) {
+            return null;
+        }
+        const projectedOwner = projectRepeatOwnerPrefix(nextNode, nextOwner, current);
+        if (!projectedOwner)
+            return null;
+        const comparableOwner = prepareComparableRetainedNode(projectedOwner, current.occurrenceKey, draft, current);
+        if (!comparableOwner || !retainedSubtreeEquivalent(current, comparableOwner)) {
+            return null;
+        }
+        const retainedOwnerKeys = collectRetainedRepeatOwnerKeys(currentMaterialized, currentOwner);
+        if (retainedOwnersConsumeChangedPointer(currentMaterialized, retainedOwnerKeys, changedPointersOutsideSuffix(before, draft, currentOwner.sourcePath))) {
+            return null;
+        }
+        return { currentOwner, nextOwner, current, nextNode };
+    }
+    function classifyRepeatOwners(before, draft, nextMaterialized) {
+        let isolatedUnresolvedAppendKey;
+        if (currentMaterialized.repeatOwners.size === 1
+            && nextMaterialized.repeatOwners.size === 1
+            && currentMaterialized.unresolvedRepeatOwners.size === 1
+            && nextMaterialized.unresolvedRepeatOwners.size === 1) {
+            const [currentKey] = currentMaterialized.unresolvedRepeatOwners;
+            const [nextKey] = nextMaterialized.unresolvedRepeatOwners;
+            const currentOwner = currentMaterialized.repeatOwners.get(currentKey);
+            const nextOwner = nextMaterialized.repeatOwners.get(nextKey);
+            const changedPointers = collectChangedPointers(before, draft);
+            if (currentKey === nextKey
+                && currentOwner?.sourcePath
+                && currentOwner.sourcePath === nextOwner?.sourcePath
+                && changedPointers.length === 1
+                && changedPointers[0] === currentOwner.sourcePath) {
+                // Complex expressions inside one Repeat are conservatively unresolved.
+                // A source-only update may still enter the existing append proof: the
+                // strict JSON prefix and retained-subtree comparison below must both
+                // succeed before any live DOM is adopted.
+                isolatedUnresolvedAppendKey = currentKey;
+            }
+        }
+        if ((currentMaterialized.unresolvedRepeatOwners.size > 0
+            || nextMaterialized.unresolvedRepeatOwners.size > 0)
+            && isolatedUnresolvedAppendKey === undefined) {
+            return {
+                forcedOwnerIds: new Set([currentMaterialized.root.id]),
+                appendPlans: new Map(),
+            };
+        }
+        const selectedKeys = new Set(isolatedUnresolvedAppendKey ? [isolatedUnresolvedAppendKey] : []);
         for (const pointer of collectChangedPointers(before, draft)) {
             for (const owner of findAffectedRepeatOwners(currentMaterialized, pointer)) {
                 selectedKeys.add(owner.key);
@@ -9503,10 +9914,19 @@ function renderBoundCard(container, schema, options) {
                 parentKey = currentMaterialized.repeatOwners.get(parentKey)?.parentKey;
             }
         }
-        return new Set([...selectedKeys].flatMap((key) => {
-            const id = currentMaterialized.repeatOwners.get(key)?.runtimeOwnerId;
-            return id ? [id] : [];
-        }));
+        const forcedOwnerIds = new Set();
+        const appendPlans = new Map();
+        for (const key of selectedKeys) {
+            const owner = currentMaterialized.repeatOwners.get(key);
+            if (!owner)
+                continue;
+            const plan = createRepeatAppendPlan(owner, nextMaterialized, before, draft);
+            if (plan)
+                appendPlans.set(plan.current.occurrenceKey, plan);
+            else
+                forcedOwnerIds.add(owner.runtimeOwnerId);
+        }
+        return { forcedOwnerIds, appendPlans };
     }
     function collectMountedLifecycleIds(root) {
         const ids = new Set();
@@ -9538,15 +9958,77 @@ function renderBoundCard(container, schema, options) {
             prepareReplacementRoots(current.children[index], next.children[index], draft, replacements);
         }
     }
+    function findPreparedByOccurrenceKey(root, occurrenceKey) {
+        if (root.occurrenceKey === occurrenceKey)
+            return root;
+        for (const child of root.children) {
+            const match = findPreparedByOccurrenceKey(child, occurrenceKey);
+            if (match)
+                return match;
+        }
+        return null;
+    }
+    function disposePreparedRepeatAppend(candidate) {
+        if (candidate.state === 'disposed' || candidate.state === 'adopted')
+            return;
+        for (const suffix of candidate.suffix) {
+            disposeBoundSubtreeWithoutThrow(suffix);
+        }
+        candidate.fragment.replaceChildren();
+        candidate.state = 'disposed';
+    }
+    function prepareRepeatAppendCandidates(preparedRoot, appendPlans, draft) {
+        const candidates = new Map();
+        try {
+            for (const [occurrenceKey, plan] of appendPlans) {
+                const prepared = findPreparedByOccurrenceKey(preparedRoot, occurrenceKey);
+                if (!prepared?.[REPEAT_APPEND]) {
+                    throw new Error(`[renderCard] Missing prepared repeat append owner "${occurrenceKey}"`);
+                }
+                const nextOccurrenceKeys = occurrenceKeysForChildren(plan.current.occurrenceKey, plan.nextNode.children);
+                const suffix = [];
+                const fragment = document.createDocumentFragment();
+                const candidate = {
+                    occurrenceKey,
+                    current: plan.current,
+                    next: prepared,
+                    suffix,
+                    fragment,
+                    previousChildNodes: Array.from(plan.current.element.childNodes),
+                    expectedChildNodes: [],
+                    state: 'prepared',
+                };
+                candidates.set(occurrenceKey, candidate);
+                for (let index = plan.current.children.length; index < plan.nextNode.children.length; index += 1) {
+                    const mounted = mountBoundSubtree(plan.nextNode.children[index], nextOccurrenceKeys[index], draft);
+                    suffix.push(mounted);
+                    fragment.appendChild(mounted.element);
+                }
+                candidate.expectedChildNodes = [
+                    ...candidate.previousChildNodes,
+                    ...suffix.map(node => node.element),
+                ];
+            }
+            return candidates;
+        }
+        catch (error) {
+            for (const candidate of candidates.values()) {
+                disposePreparedRepeatAppend(candidate);
+            }
+            throw error;
+        }
+    }
     function prepareIncrementalCandidate(before, draft) {
         const materialized = materializeCard(schema, draft);
-        const forcedOwnerIds = currentMountedTree
-            ? materialized.unresolvedRepeatOwners.size > 0
-                ? new Set([materialized.root.id])
-                : selectForcedRepeatOwnerIds(before, draft)
-            : new Set();
-        const preparedRoot = prepareBoundNode(materialized.root, `${materialized.root.id}#0`, draft, forcedOwnerIds, currentMountedTree);
+        const classification = currentMountedTree
+            ? classifyRepeatOwners(before, draft, materialized)
+            : {
+                forcedOwnerIds: new Set(),
+                appendPlans: new Map(),
+            };
+        const preparedRoot = prepareBoundNode(materialized.root, `${materialized.root.id}#0`, draft, classification.forcedOwnerIds, classification.appendPlans, currentMountedTree);
         const replacementRoots = new Map();
+        const repeatAppends = prepareRepeatAppendCandidates(preparedRoot, classification.appendPlans, draft);
         try {
             if (currentMountedTree) {
                 prepareReplacementRoots(currentMountedTree, preparedRoot, draft, replacementRoots);
@@ -9558,6 +10040,7 @@ function renderBoundCard(container, schema, options) {
                 materialized,
                 preparedRoot,
                 replacementRoots,
+                repeatAppends,
                 autoFocusIds: currentMountedTree
                     ? collectAutoFocusRevealIds(currentMaterialized, materialized, draft)
                     : new Set(),
@@ -9567,6 +10050,9 @@ function renderBoundCard(container, schema, options) {
             for (const replacement of replacementRoots.values()) {
                 disposeBoundSubtreeWithoutThrow(replacement);
             }
+            for (const append of repeatAppends.values()) {
+                disposePreparedRepeatAppend(append);
+            }
             throw error;
         }
     }
@@ -9820,6 +10306,10 @@ function renderBoundCard(container, schema, options) {
             disposeBoundSubtreeWithoutThrow(replacement);
         }
         candidate.replacementRoots.clear();
+        for (const append of candidate.repeatAppends.values()) {
+            disposePreparedRepeatAppend(append);
+        }
+        candidate.repeatAppends.clear();
     }
     function restoreChangedSubtreeState(previous, next, scrollPositions, mediaStates) {
         if (previous.element !== next.element) {
@@ -9868,6 +10358,111 @@ function renderBoundCard(container, schema, options) {
             throw adoptionError;
         throw new Error(failureMessage);
     }
+    function rollbackRepeatAppend(candidate) {
+        for (let index = candidate.suffix.length - 1; index >= 0; index -= 1) {
+            const element = candidate.suffix[index].element;
+            if (element.parentNode !== candidate.current.element)
+                continue;
+            try {
+                candidate.current.element.removeChild(element);
+            }
+            catch {
+                // The exact previous-sequence postcondition below decides success.
+            }
+        }
+        const restored = childNodeSequenceEqual(candidate.current.element, candidate.previousChildNodes);
+        candidate.state = restored ? 'rolled-back' : 'rollback-failed';
+        return restored;
+    }
+    function tryAdoptRepeatAppend(candidate) {
+        let adoptionError;
+        try {
+            candidate.current.element.appendChild(candidate.fragment);
+        }
+        catch (error) {
+            adoptionError = error;
+        }
+        if (childNodeSequenceEqual(candidate.current.element, candidate.expectedChildNodes)) {
+            candidate.state = 'adopted';
+            return { status: 'adopted' };
+        }
+        const error = adoptionError ?? new Error('[renderCard] Bound repeat append postcondition failed');
+        if (rollbackRepeatAppend(candidate)) {
+            return { status: 'rolled-back', error };
+        }
+        return { status: 'rollback-failed', error };
+    }
+    function mountedSnapshotStillMatches(previous, working) {
+        const appendOwner = Boolean(working[REPEAT_APPEND]);
+        if (previous.element !== working.element
+            || previous.occurrenceKey !== working.occurrenceKey
+            || previous.nodeId !== working.nodeId
+            || previous.nodeType !== working.nodeType
+            || previous.rendererToken !== working.rendererToken
+            || previous.visible !== working.visible
+            || previous.disabled !== working.disabled
+            || previous.bindingFingerprint !== working.bindingFingerprint
+            || previous.children.length !== working.children.length
+            || (!appendOwner && (previous.propsFingerprint !== working.propsFingerprint
+                || previous.layoutFingerprint !== working.layoutFingerprint))) {
+            return false;
+        }
+        if (appendOwner
+            && !childNodeSequenceEqual(previous.element, previous.children.map(child => child.element))) {
+            return false;
+        }
+        return previous.children.every((child, index) => (mountedSnapshotStillMatches(child, working.children[index])));
+    }
+    function adoptCompleteNextEmergencyRoot(candidate, renderVariables, previous, working, scrollPositions, mediaStates) {
+        const emergency = mountBoundSubtree(candidate.materialized.root, candidate.preparedRoot.occurrenceKey, renderVariables);
+        let adopted = false;
+        try {
+            syncMountedBindings(emergency);
+            replaceContainerRoot(emergency.element, '[renderCard] Bound emergency root was not adopted');
+            adopted = true;
+        }
+        finally {
+            if (!adopted)
+                disposeBoundSubtreeWithoutThrow(emergency);
+        }
+        disposeBoundSubtreeWithoutThrow(working);
+        try {
+            restoreChangedSubtreeState(previous, emergency, scrollPositions, mediaStates);
+        }
+        catch {
+            // Presentation restoration cannot undo an adopted complete next root.
+        }
+        restoreDisabledDescendantPresentation(emergency);
+        return emergency;
+    }
+    function recoverPreviousCommittedRoot(previous, working, scrollPositions, mediaStates) {
+        const recovery = mountBoundSubtree(currentMaterialized.root, previous.occurrenceKey, lastPublishedVariables);
+        let adopted = false;
+        try {
+            syncMountedBindings(recovery);
+            replaceContainerRoot(recovery.element, '[renderCard] Previous bound root recovery was not adopted');
+            adopted = true;
+        }
+        finally {
+            if (!adopted)
+                disposeBoundSubtreeWithoutThrow(recovery);
+        }
+        disposeBoundSubtreeWithoutThrow(working);
+        try {
+            restoreChangedSubtreeState(previous, recovery, scrollPositions, mediaStates);
+        }
+        catch {
+            // Recovery validity is the adopted previous tree, not presentation state.
+        }
+        restoreDisabledDescendantPresentation(recovery);
+        currentMountedTree = recovery;
+        return recovery;
+    }
+    function repeatAppendUnreconciledError(failures) {
+        const error = new Error('[renderCard] Bound repeat append unreconciled');
+        error.failures = failures;
+        return error;
+    }
     function commitIncrementalCandidate(candidate, renderVariables) {
         const replacements = candidate.replacementRoots;
         try {
@@ -9889,7 +10484,10 @@ function renderBoundCard(container, schema, options) {
             const scrollPositions = captureScrollPositions$1(container);
             const mediaStates = captureMediaStates$1(container);
             let unreconciled = false;
-            const next = reconcileIncrementalNode(previous, candidate.preparedRoot, {
+            let previousRecoveryRequired = false;
+            let appendFailure;
+            let repeatAppendTransaction = false;
+            let next = reconcileIncrementalNode(previous, candidate.preparedRoot, {
                 decide: (current, prepared) => decideBoundUpdate(current, prepared),
                 update: (current, prepared) => updateBoundNode(current, prepared),
                 mountReplacement: (prepared) => {
@@ -9923,6 +10521,60 @@ function renderBoundCard(container, schema, options) {
                     unreconciled = true;
                 },
             });
+            if (!unreconciled) {
+                for (const appendCandidate of candidate.repeatAppends.values()) {
+                    const reconciledOwner = findMountedByOccurrenceKey(next, appendCandidate.occurrenceKey);
+                    if (!reconciledOwner
+                        || reconciledOwner.element !== appendCandidate.current.element) {
+                        disposePreparedRepeatAppend(appendCandidate);
+                        candidate.repeatAppends.delete(appendCandidate.occurrenceKey);
+                        continue;
+                    }
+                    repeatAppendTransaction = true;
+                    const grafted = {
+                        ...appendCandidate.next,
+                        element: reconciledOwner.element,
+                        children: [
+                            ...reconciledOwner.children,
+                            ...appendCandidate.suffix,
+                        ],
+                    };
+                    const graftedRoot = replaceMountedByOccurrenceKey(next, appendCandidate.occurrenceKey, grafted);
+                    if (!graftedRoot) {
+                        disposePreparedRepeatAppend(appendCandidate);
+                        candidate.repeatAppends.delete(appendCandidate.occurrenceKey);
+                        unreconciled = true;
+                        appendFailure = new Error('[renderCard] Bound repeat append owner disappeared before adoption');
+                        break;
+                    }
+                    const result = tryAdoptRepeatAppend(appendCandidate);
+                    if (result.status === 'adopted') {
+                        next = graftedRoot;
+                        candidate.repeatAppends.delete(appendCandidate.occurrenceKey);
+                        continue;
+                    }
+                    appendFailure = result.error;
+                    if (result.status === 'rolled-back') {
+                        unreconciled = true;
+                    }
+                    else {
+                        previousRecoveryRequired = true;
+                    }
+                    break;
+                }
+            }
+            if (previousRecoveryRequired) {
+                try {
+                    recoverPreviousCommittedRoot(previous, next, scrollPositions, mediaStates);
+                }
+                catch (recoveryError) {
+                    throw repeatAppendUnreconciledError([
+                        appendFailure,
+                        recoveryError,
+                    ]);
+                }
+                throw appendFailure;
+            }
             if (!unreconciled
                 && (next.element.parentNode !== container
                     || container.firstElementChild !== next.element)) {
@@ -9936,7 +10588,7 @@ function renderBoundCard(container, schema, options) {
                     unreconciled = true;
                 }
             }
-            if (unreconciled) {
+            if (unreconciled && !repeatAppendTransaction) {
                 let emergency;
                 try {
                     emergency = mountBoundSubtree(candidate.materialized.root, candidate.preparedRoot.occurrenceKey, renderVariables);
@@ -9967,6 +10619,29 @@ function renderBoundCard(container, schema, options) {
                 restoreDisabledDescendantPresentation(emergency);
                 return emergency;
             }
+            if (unreconciled) {
+                try {
+                    return adoptCompleteNextEmergencyRoot(candidate, renderVariables, previous, next, scrollPositions, mediaStates);
+                }
+                catch (emergencyError) {
+                    if (mountedTreeOrderMatchesDom(previous)
+                        && mountedSnapshotStillMatches(previous, next)) {
+                        syncMountedBindings(previous);
+                        throw appendFailure ?? emergencyError;
+                    }
+                    try {
+                        recoverPreviousCommittedRoot(previous, next, scrollPositions, mediaStates);
+                    }
+                    catch (recoveryError) {
+                        throw repeatAppendUnreconciledError([
+                            appendFailure,
+                            emergencyError,
+                            recoveryError,
+                        ]);
+                    }
+                    throw appendFailure ?? emergencyError;
+                }
+            }
             try {
                 restoreChangedSubtreeState(previous, next, scrollPositions, mediaStates);
             }
@@ -10221,6 +10896,7 @@ function renderBoundCard(container, schema, options) {
     return {
         getNode: nodeAccess.getNode,
         onFocusChange: nodeAccess.onFocusChange,
+        onScroll: nodeAccess.onScroll,
         dispose() {
             if (disposed || disposeRequested)
                 return;
@@ -11047,6 +11723,7 @@ function renderStaticCard(container, schema, options) {
     return {
         getNode: nodeAccess.getNode,
         onFocusChange: nodeAccess.onFocusChange,
+        onScroll: nodeAccess.onScroll,
         dispose() {
             if (disposed || disposeRequested)
                 return;
@@ -13074,6 +13751,7 @@ function renderStreamingCard(container, options = {}) {
     return {
         getNode: nodeAccess.getNode,
         onFocusChange: nodeAccess.onFocusChange,
+        onScroll: nodeAccess.onScroll,
         applyCommand(command) {
             if (!lockMode('commands'))
                 return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antglobal/copilot-cards-web",
-  "version": "0.0.20260828032020-dev.1",
+  "version": "0.0.20260828032020-dev.5",
   "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": "0.0.20260828032020-dev.1",
+    "@antglobal/copilot-cards-core": "0.0.20260828032020-dev.5",
     "echarts": "^5.6.0",
     "marked": "^18.0.5",
     "tslib": "^2.8.1",