@antglobal/copilot-cards-core 1.0.2 → 1.0.4

package/dist/index.d.ts

@@ -35,6 +35,18 @@ interface ActionRunnerContext {
     copyText?: (text: string) => void;
     /** Variables context for resolving expressions in action params */
     variables?: Record<string, any>;
+    /** Read-only context for resolving action params; writes still target variables. */
+    expressionContext?: Record<string, any>;
+    /** Optional adapter-specific resolver for structured parameter bindings. */
+    parameterResolver?: (params: Record<string, any>) => Record<string, any>;
+    /**
+     * Bound-renderer write hook. Static callers omit it and retain the existing
+     * direct-write plus setVariable behavior.
+     */
+    variableWriter?: (key: string, value: any, options: {
+        silent: boolean;
+        source: 'setVariable' | 'request';
+    }) => void;
     /** Current bot ID — used to look up bot-scoped handlers */
     botId?: string;
     /** Abort signal — used to cancel in-flight requests and polling on dispose */
@@ -147,6 +159,13 @@ interface ExpressionValue {
  * - float: relative container with absolutely positioned overlays
  */
 type SlotLayout = 'default' | 'columns' | 'grid' | 'horizontalScroll' | 'carousel' | 'list' | 'float' | 'keyValue' | 'table' | 'chart';
+/** Binds a slot to a template that is instantiated once per source item. */
+interface RepeatBinding {
+    source: string;
+    template: string;
+    item: string;
+    index?: string;
+}
 /**
  * Content of a named slot.
  *
@@ -165,6 +184,7 @@ type SlotLayout = 'default' | 'columns' | 'grid' | 'horizontalScroll' | 'carouse
 interface SlotContent {
     children?: string[];
     groups?: string[][];
+    repeat?: RepeatBinding;
     config?: Record<string, any>;
 }
 /** A single element inside the card. */
@@ -216,6 +236,20 @@ type CardSchemaInput = CardSchema | LegacyCardSchema;
  * If it is a legacy format, it is automatically converted.
  */
 declare function normalizeSchema(input: CardSchemaInput): CardSchema;
+/** Whether a schema contains native repeat or adapter-owned dynamic children. */
+declare function hasDynamicChildren(input: CardSchemaInput): boolean;
+/**
+ * Whether a renderer must use the scoped binding/materialization path.
+ *
+ * Literal native/static schemas deliberately remain on the legacy parser path.
+ * The private A2UI marker cannot be forged by JSON input.
+ */
+declare function requiresBindingMaterialization(input: CardSchemaInput): boolean;
+/**
+ * Stable fingerprint of the definition graph that controls binding topology.
+ * Runtime data and materialized occurrence counts are intentionally excluded.
+ */
+declare function bindingTopologyFingerprint(input: CardSchemaInput): string;
 /** Nested tree node produced by the parser — ready for a renderer to consume. */
 interface RenderTreeNode {
     id: string;
@@ -406,6 +440,134 @@ interface ActionConfigProvider {
  */
 declare function resolveActionRef(eventValue: ActionStep[] | string | undefined, actionsMap: Record<string, ActionStep[]>): ActionStep[] | undefined;
 
+interface BindingScope {
+    root: Record<string, any>;
+    locals: Record<string, any>;
+    parent?: BindingScope;
+    dataPath: string;
+    bindingDialect: 'native' | 'a2ui';
+}
+interface BoundRenderTreeNode extends RenderTreeNode {
+    sourceId: string;
+    instancePath: string;
+    dataPath: string;
+    scope: BindingScope;
+    bindingDialect: 'native' | 'a2ui';
+    children: BoundRenderTreeNode[];
+}
+interface BoundInstance {
+    id: string;
+    sourceId: string;
+    parentId?: string;
+    node: BoundRenderTreeNode;
+}
+interface RepeatOwner {
+    key: string;
+    parentKey?: string;
+    runtimeOwnerId: string;
+    sourceOwnerId: string;
+    slot: SlotLayout;
+    templateId: string;
+    sourcePath?: string;
+    dataPath: string;
+    instancePath: string;
+    depth: number;
+}
+interface MaterializeDiagnostic {
+    code: 'REPEAT_SOURCE_NOT_ARRAY';
+    message: string;
+    ownerId: string;
+    source: string;
+}
+interface MaterializedCard {
+    root: BoundRenderTreeNode;
+    hasRepeat: boolean;
+    instances: Map<string, BoundInstance>;
+    repeatOwners: Map<string, RepeatOwner>;
+    dependencies: Map<string, Set<string>>;
+    valueDependencies: Map<string, Set<string>>;
+    unresolvedRepeatOwners: Set<string>;
+    diagnostics: MaterializeDiagnostic[];
+}
+interface MaterializeOptions {
+    maxDepth?: number;
+    maxItems?: number;
+    onDiagnostic?: (diagnostic: MaterializeDiagnostic) => void;
+}
+/** Build a live expression object whose own properties are the current aliases. */
+declare function createExpressionContext(scope: BindingScope): Record<string, any>;
+declare function isBoundRenderTreeNode(value: unknown): value is BoundRenderTreeNode;
+/** Select repeat owners affected by a JSON Pointer data update. */
+declare function findAffectedRepeatOwners(card: MaterializedCard, updatePath: string): RepeatOwner[];
+/** Select repeat owners whose materialized closure contains a source definition. */
+declare function findTemplateRepeatOwners(card: MaterializedCard, sourceIds: Iterable<string>): RepeatOwner[];
+/**
+ * Normalize a card and recursively turn native repeat declarations into a
+ * renderer-ready tree with ordinary children and occurrence-specific IDs.
+ */
+declare function materializeCard(input: CardSchemaInput, variables?: Record<string, any>, options?: MaterializeOptions): MaterializedCard;
+
+/** Official A2UI dynamic ChildList descriptor supported by the adapter. */
+interface A2UIDynamicChildList {
+    path: string;
+    componentId: string;
+}
+/** Official A2UI ChildList forms supported by the adapter. */
+type A2UIChildList = string[] | A2UIDynamicChildList;
+/** Official A2UI data-binding shape supported by the adapter. */
+interface A2UIPathBinding {
+    path: string;
+}
+/** Runtime guard for the exact dynamic ChildList common-type shape. */
+declare function isA2UIDynamicChildList(value: unknown): value is A2UIDynamicChildList;
+/** Runtime guard for either supported ChildList form. */
+declare function isA2UIChildList(value: unknown): value is A2UIChildList;
+/** Runtime guard for the exact A2UI DataBinding.path common-type shape. */
+declare function isA2UIPathBinding(value: unknown): value is A2UIPathBinding;
+/**
+ * Resolve one A2UI path from the data-model root or the current item scope.
+ *
+ * Absolute paths use strict JSON Pointer syntax. Relative paths are an A2UI
+ * extension and are appended to the current strict-pointer scope.
+ */
+declare function resolveA2UIPath(root: Record<string, any>, path: string, scopePath: string): unknown;
+/**
+ * Resolve every exact A2UI `{ path }` binding in a nested value.
+ *
+ * Plain records and arrays are cloned with their property descriptors, so
+ * accessors are preserved but never invoked. Cycles in non-JSON direct API
+ * inputs remain cycles in the cloned output.
+ */
+declare function resolveA2UIDeep(value: unknown, root: Record<string, any>, scopePath: string): unknown;
+/** Create an ActionRunner-compatible resolver bound to one item scope. */
+declare function createA2UIParameterResolver(root: Record<string, any>, scopePath: string): (params: Record<string, any>) => Record<string, any>;
+
+type JsonPointerPathErrorCode = 'SYNTAX' | 'UNSAFE_SEGMENT' | 'INVALID_ARRAY_INDEX';
+/** A rejected pointer spelling or array location, rather than a data failure. */
+declare class JsonPointerPathError extends Error {
+    readonly code: JsonPointerPathErrorCode;
+    constructor(code: JsonPointerPathErrorCode, message: string);
+}
+/**
+ * Decode one RFC 6901 JSON Pointer reference token.
+ *
+ * Only `~0` and `~1` are legal escapes. URI/percent decoding is deliberately
+ * outside this helper's contract.
+ */
+declare function decodeJsonPointerSegment(segment: string): string;
+/**
+ * Parse a strict RFC 6901 JSON Pointer.
+ *
+ * The canonical root is `''`; `/` names an empty-string property.
+ */
+declare function parseJsonPointer(pointer: string): string[];
+/** Read an own-property value through a strict JSON Pointer. */
+declare function getByJsonPointer(root: unknown, pointer: string): unknown;
+/** Deep-clone a value from the JSON data-model domain. */
+declare function cloneJsonData<T>(value: T): T;
+declare function replaceRootContents(root: Record<string, any>, next: Record<string, any>): void;
+declare function setByJsonPointer(root: Record<string, any>, pointer: string, value: unknown): void;
+
 /**
  * Lifecycle Manager — manages mount / exposed / destroy hooks for card elements.
  *
@@ -512,6 +674,8 @@ interface UpdateDataModelCommand {
     surfaceId: string;
     /** JSON Pointer path, e.g. '/user/name' or '/orderStatus' */
     path: string;
+    /** Internal path interpretation. Omitted commands retain legacy semantics. */
+    pathDialect?: 'legacy' | 'a2ui';
     /** The new value to set at the path */
     value: any;
 }
@@ -546,7 +710,7 @@ interface StreamingEngineEvents {
     /** Components updated — renderer should perform incremental DOM updates */
     onComponentsUpdated: (surfaceId: string, changes: ComponentChange[]) => void;
     /** Data model updated — renderer should re-resolve affected expressions */
-    onDataModelUpdated: (surfaceId: string, path: string, value: any) => void;
+    onDataModelUpdated: (surfaceId: string, path: string, value: any, pathDialect?: 'legacy' | 'a2ui') => void;
     /** Content appended — renderer should append text to the target element */
     onContentAppended: (surfaceId: string, elementId: string, content: string) => void;
     /** Surface deleted — renderer should destroy the container */
@@ -688,7 +852,12 @@ declare class StreamingEngine {
     dispose(): void;
     private handleCreateSurface;
     private handleUpdateComponents;
+    private applyStaticComponentMutation;
+    private applyComponentMutation;
+    private commandMayIntroduceBinding;
     private handleUpdateDataModel;
+    private applyDataModelWrite;
+    private emitDataModelUpdated;
     private handleAppendContent;
     private handleDeleteSurface;
     /**
@@ -707,15 +876,23 @@ declare class StreamingEngine {
      * Remove a child ID from all parent element slot references.
      */
     private removeFromParentSlots;
+    private elementStillUsesA2UIBinding;
+    /**
+     * Source definitions inside a dynamic template closure have no unique
+     * runtime address. Token appends must therefore target their data model,
+     * not the shared source definition.
+     */
+    private dynamicClosureSourceIds;
 }
 /**
  * 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.
+ * Legacy root path '/' merges the value's own safe fields into the object.
  *
  * Prototype-polluting segments (`__proto__` / `constructor` / `prototype`) are
- * rejected — the whole write is dropped rather than silently retargeted.
+ * rejected — the whole write is dropped rather than silently retargeting it.
+ * Other assignments preserve the legacy writer's direct-reference behavior.
  *
  * @example
  * ```ts
@@ -750,8 +927,8 @@ declare function setByPath(obj: Record<string, any>, path: string, value: any):
 interface A2UIComponent {
     id: string;
     component: string;
-    /** Child component IDs — mapped to `props.slots.default.children`. */
-    children?: string[];
+    /** Static child IDs or an A2UI dynamic ChildList descriptor. */
+    children?: A2UIChildList;
     /** Layout slots pass-through (grid/chart/... — catalog extension). */
     slots?: Record<string, any>;
     /** visible/disabled directives (top-level, same as internal schema). */
@@ -926,6 +1103,14 @@ declare const BUILTIN_ICONS: Readonly<{
         viewBox: "0 0 32 32";
         body: "<path d=\"M17.5 16C17.5 16.2967 17.412 16.5867 17.2472 16.8334C17.0824 17.0801 16.8481 17.2723 16.574 17.3859C16.2999 17.4994 15.9983 17.5291 15.7074 17.4712C15.4164 17.4133 15.1491 17.2705 14.9393 17.0607C14.7296 16.8509 14.5867 16.5836 14.5288 16.2927C14.4709 16.0017 14.5006 15.7001 14.6142 15.426C14.7277 15.1519 14.92 14.9177 15.1666 14.7528C15.4133 14.588 15.7033 14.5 16 14.5C16.3978 14.5 16.7794 14.6581 17.0607 14.9394C17.342 15.2207 17.5 15.6022 17.5 16ZM10.5 14.5C10.2033 14.5 9.91332 14.588 9.66664 14.7528C9.41997 14.9177 9.22771 15.1519 9.11418 15.426C9.00065 15.7001 8.97094 16.0017 9.02882 16.2927C9.0867 16.5836 9.22956 16.8509 9.43934 17.0607C9.64912 17.2705 9.91639 17.4133 10.2074 17.4712C10.4983 17.5291 10.7999 17.4994 11.074 17.3859C11.3481 17.2723 11.5824 17.0801 11.7472 16.8334C11.912 16.5867 12 16.2967 12 16C12 15.6022 11.842 15.2207 11.5607 14.9394C11.2794 14.6581 10.8978 14.5 10.5 14.5ZM21.5 14.5C21.2033 14.5 20.9133 14.588 20.6666 14.7528C20.42 14.9177 20.2277 15.1519 20.1142 15.426C20.0007 15.7001 19.9709 16.0017 20.0288 16.2927C20.0867 16.5836 20.2296 16.8509 20.4393 17.0607C20.6491 17.2705 20.9164 17.4133 21.2074 17.4712C21.4983 17.5291 21.7999 17.4994 22.074 17.3859C22.3481 17.2723 22.5824 17.0801 22.7472 16.8334C22.912 16.5867 23 16.2967 23 16C23 15.6022 22.842 15.2207 22.5607 14.9394C22.2794 14.6581 21.8978 14.5 21.5 14.5ZM29 16C29.0005 18.2445 28.4199 20.4508 27.3147 22.4042C26.2095 24.3577 24.6174 25.9917 22.6934 27.1473C20.7693 28.3029 18.5788 28.9407 16.3352 28.9986C14.0915 29.0564 11.8711 28.5324 9.89 27.4775L5.63375 28.8963C5.28136 29.0138 4.9032 29.0309 4.54166 28.9455C4.18012 28.8602 3.84948 28.6759 3.58681 28.4132C3.32414 28.1506 3.13982 27.8199 3.0545 27.4584C2.96918 27.0968 2.98623 26.7187 3.10375 26.3663L4.5225 22.11C3.59519 20.3666 3.07725 18.4348 3.008 16.4613C2.93875 14.4877 3.32001 12.5244 4.12284 10.7202C4.92567 8.91604 6.12897 7.31847 7.6414 6.04878C9.15383 4.77909 10.9356 3.87063 12.8516 3.39238C14.7675 2.91413 16.7672 2.87865 18.699 3.28862C20.6307 3.6986 22.4436 4.54327 24.0001 5.7585C25.5566 6.97374 26.8158 8.52761 27.6822 10.3022C28.5485 12.0767 28.9992 14.0253 29 16ZM27 16C26.9995 14.3127 26.6109 12.6481 25.8641 11.135C25.1174 9.62186 24.0325 8.30083 22.6935 7.27408C21.3545 6.24733 19.7973 5.54238 18.1422 5.21377C16.4872 4.88517 14.7787 4.94171 13.149 5.37904C11.5194 5.81636 10.0121 6.62274 8.74394 7.73578C7.47577 8.84882 6.48065 10.2387 5.83558 11.7979C5.1905 13.357 4.91277 15.0437 5.02387 16.7274C5.13496 18.4111 5.63191 20.0466 6.47625 21.5075C6.54712 21.6302 6.59112 21.7665 6.60534 21.9074C6.61956 22.0484 6.60368 22.1907 6.55875 22.325L5 27L9.675 25.4413C9.77683 25.4066 9.88367 25.3888 9.99125 25.3888C10.1669 25.3891 10.3393 25.4357 10.4912 25.5238C12.1635 26.4913 14.0611 27.0013 15.9931 27.0026C17.925 27.0038 19.8232 26.4961 21.4967 25.5307C23.1702 24.5653 24.5599 23.1762 25.526 21.5031C26.492 19.83 27.0004 17.932 27 16Z\" fill=\"currentColor\" fill-rule=\"evenodd\"></path>";
     }>;
+    check: Readonly<{
+        viewBox: "0 0 32 32";
+        body: "<path d=\"M27.7071 8.29289C28.0976 8.68342 28.0976 9.31658 27.7071 9.70711L13.7071 23.7071C13.3166 24.0976 12.6834 24.0976 12.2929 23.7071L5.29289 16.7071C4.90237 16.3166 4.90237 15.6834 5.29289 15.2929C5.68342 14.9024 6.31658 14.9024 6.70711 15.2929L13 21.5858L26.2929 8.29289C26.6834 7.90237 27.3166 7.90237 27.7071 8.29289Z\" fill=\"currentColor\" fill-rule=\"evenodd\"></path>";
+    }>;
+    check_bold: Readonly<{
+        viewBox: "0 0 32 32";
+        body: "<path d=\"M26.66453 8L11.99933 22.6656L5.33333 15.99941\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"5.33333\" stroke-linecap=\"round\"></path>";
+    }>;
     check_circle: Readonly<{
         viewBox: "0 0 32 32";
         body: "<path d=\"M21.7075 12.2925C21.8005 12.3854 21.8742 12.4957 21.9246 12.6171C21.9749 12.7385 22.0008 12.8686 22.0008 13C22.0008 13.1314 21.9749 13.2615 21.9246 13.3829C21.8742 13.5043 21.8005 13.6146 21.7075 13.7075L14.7075 20.7075C14.6146 20.8005 14.5043 20.8742 14.3829 20.9246C14.2615 20.9749 14.1314 21.0008 14 21.0008C13.8686 21.0008 13.7385 20.9749 13.6171 20.9246C13.4957 20.8742 13.3854 20.8005 13.2925 20.7075L10.2925 17.7075C10.1049 17.5199 9.99945 17.2654 9.99945 17C9.99945 16.7346 10.1049 16.4801 10.2925 16.2925C10.4801 16.1049 10.7346 15.9994 11 15.9994C11.2654 15.9994 11.5199 16.1049 11.7075 16.2925L14 18.5863L20.2925 12.2925C20.3854 12.1995 20.4957 12.1258 20.6171 12.0754C20.7385 12.0251 20.8686 11.9992 21 11.9992C21.1314 11.9992 21.2615 12.0251 21.3829 12.0754C21.5043 12.1258 21.6146 12.1995 21.7075 12.2925ZM29 16C29 18.5712 28.2376 21.0846 26.8091 23.2224C25.3807 25.3603 23.3503 27.0265 20.9749 28.0104C18.5995 28.9944 15.9856 29.2518 13.4638 28.7502C10.9421 28.2486 8.6257 27.0105 6.80762 25.1924C4.98953 23.3743 3.75141 21.0579 3.2498 18.5362C2.74819 16.0144 3.00563 13.4006 3.98957 11.0251C4.97351 8.64968 6.63975 6.61935 8.77759 5.1909C10.9154 3.76244 13.4288 3 16 3C19.4467 3.00364 22.7512 4.37445 25.1884 6.81163C27.6256 9.24882 28.9964 12.5533 29 16ZM27 16C27 13.8244 26.3549 11.6977 25.1462 9.88873C23.9375 8.07979 22.2195 6.66989 20.2095 5.83733C18.1995 5.00476 15.9878 4.78692 13.854 5.21136C11.7202 5.6358 9.76021 6.68345 8.22183 8.22183C6.68345 9.7602 5.63581 11.7202 5.21137 13.854C4.78693 15.9878 5.00477 18.1995 5.83733 20.2095C6.66989 22.2195 8.07979 23.9375 9.88873 25.1462C11.6977 26.3549 13.8244 27 16 27C18.9164 26.9967 21.7123 25.8367 23.7745 23.7745C25.8367 21.7123 26.9967 18.9164 27 16Z\" fill=\"currentColor\" fill-rule=\"evenodd\"></path>";
@@ -1245,5 +1430,5 @@ interface BuiltinIconDefinition {
 declare const BUILTIN_ICON_NAMES: readonly (keyof typeof BUILTIN_ICONS)[];
 declare function getBuiltinIcon(name: string | undefined): BuiltinIconDefinition | undefined;
 
-export { ActionRegistry, BUILTIN_ICONS, BUILTIN_ICON_NAMES, LifecycleManager, StreamingEngine, StreamingParser, a2uiComponentToElement, a2uiToCommand, convertLegacySchema, createLifecycleManager, extractPartialSchema, getBuiltinIcon, getByPath, hasExpression, interpolate, isA2UIEnvelope, isLegacySchema, normalizeSchema, parseSchema, registerActionHandler, registry, resetIdCounter, resolveActionRef, resolveDeep, resolveExpression, resolveExpressionValue, runActionStep, runActionSteps, setByPath, validateSchema };
-export type { A2UIComponent, A2UIEnvelope, ActionChainConfig, ActionConfigProvider, ActionRunnerContext, ActionStep, ActionStepHandler, AppendContentCommand, BuiltinIconDefinition, BuiltinIconName, CardSchema, CardSchemaInput, CleanupFn, ComponentChange, CreateSurfaceCommand, DeleteSurfaceCommand, ElementLifecycle, ElementNode, ExpressionContext, ExpressionValue, LegacyCardContentItem, LegacyCardSchema, LegacyTracking, LegacyTrackingType, PartialSchemaResult, RenderTreeNode, SimpleActionHandler, SlotContent, SlotLayout, StreamingCommand, StreamingEngineEvents, StreamingParserOptions, UpdateComponentsCommand, UpdateDataModelCommand };
+export { ActionRegistry, BUILTIN_ICONS, BUILTIN_ICON_NAMES, JsonPointerPathError, LifecycleManager, StreamingEngine, StreamingParser, a2uiComponentToElement, a2uiToCommand, bindingTopologyFingerprint, cloneJsonData, convertLegacySchema, createA2UIParameterResolver, createExpressionContext, createLifecycleManager, decodeJsonPointerSegment, extractPartialSchema, findAffectedRepeatOwners, findTemplateRepeatOwners, getBuiltinIcon, getByJsonPointer, getByPath, hasDynamicChildren, hasExpression, interpolate, isA2UIChildList, isA2UIDynamicChildList, isA2UIEnvelope, isA2UIPathBinding, isBoundRenderTreeNode, isLegacySchema, materializeCard, normalizeSchema, parseJsonPointer, parseSchema, registerActionHandler, registry, replaceRootContents, requiresBindingMaterialization, resetIdCounter, resolveA2UIDeep, resolveA2UIPath, resolveActionRef, resolveDeep, resolveExpression, resolveExpressionValue, runActionStep, runActionSteps, setByJsonPointer, setByPath, validateSchema };
+export type { A2UIChildList, A2UIComponent, A2UIDynamicChildList, A2UIEnvelope, A2UIPathBinding, ActionChainConfig, ActionConfigProvider, ActionRunnerContext, ActionStep, ActionStepHandler, AppendContentCommand, BindingScope, BoundInstance, BoundRenderTreeNode, BuiltinIconDefinition, BuiltinIconName, CardSchema, CardSchemaInput, CleanupFn, ComponentChange, CreateSurfaceCommand, DeleteSurfaceCommand, ElementLifecycle, ElementNode, ExpressionContext, ExpressionValue, JsonPointerPathErrorCode, LegacyCardContentItem, LegacyCardSchema, LegacyTracking, LegacyTrackingType, MaterializeDiagnostic, MaterializeOptions, MaterializedCard, PartialSchemaResult, RenderTreeNode, RepeatBinding, RepeatOwner, SimpleActionHandler, SlotContent, SlotLayout, StreamingCommand, StreamingEngineEvents, StreamingParserOptions, UpdateComponentsCommand, UpdateDataModelCommand };