@antglobal/copilot-cards-core 1.0.5 → 1.0.7

package/dist/index.js

@@ -201,87 +201,106 @@ function evaluateExpression(expr, context) {
         return t;
     }
     // Precedence (low → high): ternary → || → && → equality → relational → unary → atom
-    function parseTernary() {
-        const cond = parseOr();
+    function parseTernary(mode) {
+        const condition = parseOr(mode);
         if (peek()?.type === 'question') {
             consume(); // ?
-            const truthy = parseTernary();
+            const truthyMode = mode === 'evaluate' && Boolean(condition)
+                ? 'evaluate'
+                : 'consume';
+            const truthy = parseTernary(truthyMode);
             expect('colon');
-            const falsy = parseTernary();
-            return cond ? truthy : falsy;
+            const falsyMode = mode === 'evaluate' && !condition
+                ? 'evaluate'
+                : 'consume';
+            const falsy = parseTernary(falsyMode);
+            if (mode === 'consume')
+                return undefined;
+            return condition ? truthy : falsy;
         }
-        return cond;
+        return condition;
     }
-    function parseOr() {
-        let left = parseAnd();
+    function parseOr(mode) {
+        let left = parseAnd(mode);
         while (peek()?.value === '||') {
             consume();
-            left = left || parseAnd();
+            const rightMode = mode === 'evaluate' && !left ? 'evaluate' : 'consume';
+            const right = parseAnd(rightMode);
+            if (rightMode === 'evaluate')
+                left = right;
         }
         return left;
     }
-    function parseAnd() {
-        let left = parseEquality();
+    function parseAnd(mode) {
+        let left = parseEquality(mode);
         while (peek()?.value === '&&') {
             consume();
-            left = left && parseEquality();
+            const rightMode = mode === 'evaluate' && Boolean(left) ? 'evaluate' : 'consume';
+            const right = parseEquality(rightMode);
+            if (rightMode === 'evaluate')
+                left = right;
         }
         return left;
     }
-    function parseEquality() {
-        let left = parseRelational();
+    function parseEquality(mode) {
+        let left = parseRelational(mode);
         while (peek()?.value === '===' || peek()?.value === '!==' || peek()?.value === '==' || peek()?.value === '!=') {
             const op = consume().value;
-            const right = parseRelational();
-            if (op === '===' || op === '==')
-                left = left === right;
-            else
-                left = left !== right;
+            const right = parseRelational(mode);
+            if (mode === 'evaluate') {
+                if (op === '===' || op === '==')
+                    left = left === right;
+                else
+                    left = left !== right;
+            }
         }
         return left;
     }
-    function parseRelational() {
-        let left = parseUnary();
+    function parseRelational(mode) {
+        let left = parseUnary(mode);
         while (peek()?.value === '>' || peek()?.value === '<' || peek()?.value === '>=' || peek()?.value === '<=') {
             const op = consume().value;
-            const right = parseUnary();
-            if (op === '>')
-                left = left > right;
-            else if (op === '<')
-                left = left < right;
-            else if (op === '>=')
-                left = left >= right;
-            else
-                left = left <= right;
+            const right = parseUnary(mode);
+            if (mode === 'evaluate') {
+                if (op === '>')
+                    left = left > right;
+                else if (op === '<')
+                    left = left < right;
+                else if (op === '>=')
+                    left = left >= right;
+                else
+                    left = left <= right;
+            }
         }
         return left;
     }
-    function parseUnary() {
+    function parseUnary(mode) {
         if (peek()?.value === '!') {
             consume();
-            return !parseUnary();
+            const value = parseUnary(mode);
+            return mode === 'evaluate' ? !value : undefined;
         }
-        return parseAtom();
+        return parseAtom(mode);
     }
-    function parseAtom() {
+    function parseAtom(mode) {
         const t = peek();
         if (!t)
             return undefined;
         if (t.type === 'string') {
             consume();
-            return t.value;
+            return mode === 'evaluate' ? t.value : undefined;
         }
         if (t.type === 'number') {
             consume();
-            return Number(t.value);
+            return mode === 'evaluate' ? Number(t.value) : undefined;
         }
         if (t.type === 'boolean') {
             consume();
-            return t.value === 'true';
+            return mode === 'evaluate' ? t.value === 'true' : undefined;
         }
         if (t.type === 'null') {
             consume();
-            return null;
+            return mode === 'evaluate' ? null : undefined;
         }
         if (t.type === 'undefined') {
             consume();
@@ -289,19 +308,19 @@ function evaluateExpression(expr, context) {
         }
         if (t.type === 'ident') {
             consume();
-            return getByPath$1(context, t.value);
+            return mode === 'evaluate' ? getByPath$1(context, t.value) : undefined;
         }
         if (t.type === 'paren' && t.value === '(') {
             consume();
-            const val = parseTernary();
+            const value = parseTernary(mode);
             expect('paren', ')');
-            return val;
+            return value;
         }
         // Fallback
         consume();
         return undefined;
     }
-    const result = parseTernary();
+    const result = parseTernary('evaluate');
     return result;
 }
 /**
@@ -386,7 +405,7 @@ async function parseResponseBody(response) {
  * @param silent - If true, only write to ctx.variables without calling
  *   setVariable (avoids triggering re-render during polling iterations).
  *   When variableWriter is present it owns the write and must synchronously
- *   update the bound variables draft while honoring this flag.
+ *   update the renderer-owned variable view while honoring this flag.
  */
 function writeResponseVariable(ctx, responseKey, data, silent = false) {
     if (ctx.variableWriter) {
@@ -1844,97 +1863,215 @@ function parseSchema(input) {
     }
     return buildNode(rootID);
 }
-// ─── Validation ──────────────────────────────────────────────────
+function encodePointerSegment(segment) {
+    return String(segment).replace(/~/g, '~0').replace(/\//g, '~1');
+}
+function schemaPath(...segments) {
+    return segments.length > 0
+        ? `/${segments.map(encodePointerSegment).join('/')}`
+        : '';
+}
+function elementPath(id, ...segments) {
+    return schemaPath('elements', id, ...segments);
+}
+function slotPath(id, slotName, ...segments) {
+    return elementPath(id, 'props', 'slots', slotName, ...segments);
+}
+function addIssue(issues, code, path, message, params, anchorPath) {
+    issues.push({
+        code,
+        path,
+        ...(anchorPath === undefined ? {} : { anchorPath }),
+        message,
+        ...(params === undefined ? {} : { params }),
+    });
+}
+function displayValue(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return '<unprintable>';
+    }
+}
+function displayError(error) {
+    const message = readOwnData(error, 'message');
+    return displayValue(message.kind === 'value' ? message.value : error);
+}
 /**
- * Validate a CardSchema and return any error messages.
+ * Validate an unknown schema input and return structured diagnostics.
+ *
+ * Component names and component-specific props are deliberately not checked;
+ * this validator only owns the shared card graph and binding protocol.
  */
-function validateSchema(input) {
-    const schema = normalizeSchema(input);
-    const errors = [];
-    if (!schema.version) {
-        errors.push('Missing "version" field');
+function validateSchemaDetailed(input) {
+    const issues = [];
+    if (!isPlainObject(input)) {
+        addIssue(issues, 'SCHEMA_TYPE_MISMATCH', '', 'Schema must be a non-null plain object');
+        return issues;
+    }
+    let schema;
+    try {
+        schema = normalizeSchema(input);
     }
-    if (typeof schema.rootID !== 'string') {
-        errors.push('"rootID" field must be a string');
+    catch (error) {
+        addIssue(issues, 'LEGACY_CONVERSION_FAILED', '', `Legacy schema conversion failed: ${displayError(error)}`);
+        return issues;
     }
-    else if (!schema.rootID) {
-        errors.push('Missing "rootID" field');
+    const version = readOwnData(schema, 'version');
+    if (version.kind !== 'value' || !version.value) {
+        addIssue(issues, 'SCHEMA_REQUIRED_FIELD', schemaPath('version'), 'Missing "version" field', undefined, '');
     }
-    else if (!schema.elements[schema.rootID]) {
-        errors.push(`Root element "${schema.rootID}" not found in elements`);
+    const rootID = readOwnData(schema, 'rootID');
+    if (rootID.kind !== 'value' || typeof rootID.value !== 'string') {
+        addIssue(issues, 'ROOT_TYPE_MISMATCH', schemaPath('rootID'), '"rootID" field must be a string', undefined, rootID.kind === 'missing' ? '' : undefined);
     }
-    const allIds = new Set(Object.keys(schema.elements));
-    for (const [id, element] of Object.entries(schema.elements)) {
-        if (!element.type) {
-            errors.push(`Element "${id}" is missing a "type" field`);
+    else if (!rootID.value) {
+        addIssue(issues, 'SCHEMA_REQUIRED_FIELD', schemaPath('rootID'), 'Missing "rootID" field');
+    }
+    const elementsRead = readOwnData(schema, 'elements');
+    if (elementsRead.kind === 'missing') {
+        addIssue(issues, 'SCHEMA_REQUIRED_FIELD', schemaPath('elements'), 'Missing "elements" field', undefined, '');
+        return issues;
+    }
+    const rawElements = elementsRead.kind === 'value'
+        ? elementsRead.value
+        : undefined;
+    if (!isPlainObject(rawElements)) {
+        addIssue(issues, 'SCHEMA_TYPE_MISMATCH', schemaPath('elements'), '"elements" field must be an object');
+        return issues;
+    }
+    const elements = rawElements;
+    const elementEntries = ownStringDataEntries(elements);
+    for (const id of elementEntries.accessors) {
+        addIssue(issues, 'ELEMENT_ACCESSOR_NOT_ALLOWED', elementPath(id), `Element "${id}" must be an own data property`, { elementId: id });
+    }
+    if (elementEntries.opaque) {
+        addIssue(issues, 'ELEMENTS_UNINSPECTABLE', schemaPath('elements'), 'The "elements" field could not be inspected safely');
+        return issues;
+    }
+    const allIds = new Set([
+        ...elementEntries.entries.map(([id]) => id),
+        ...elementEntries.accessors,
+    ]);
+    const validationElements = Object.create(null);
+    for (const [id, element] of elementEntries.entries) {
+        Object.defineProperty(validationElements, id, {
+            configurable: true,
+            enumerable: true,
+            value: element,
+            writable: true,
+        });
+    }
+    const validationSchema = {
+        rootID: rootID.kind === 'value' && typeof rootID.value === 'string'
+            ? rootID.value
+            : '',
+        elements: validationElements};
+    if (rootID.kind === 'value'
+        && typeof rootID.value === 'string'
+        && rootID.value
+        && !allIds.has(rootID.value)) {
+        addIssue(issues, 'ROOT_REFERENCE_NOT_FOUND', schemaPath('rootID'), `Root element "${rootID.value}" not found in elements`, { rootID: rootID.value });
+    }
+    for (const [id, rawElement] of elementEntries.entries) {
+        if (!isPlainObject(rawElement)) {
+            addIssue(issues, 'ELEMENT_TYPE_MISMATCH', elementPath(id), `Element "${id}" must be an object`, { elementId: id });
+            continue;
+        }
+        const element = rawElement;
+        const type = readOwnData(element, 'type');
+        if (type.kind !== 'value' || !type.value) {
+            addIssue(issues, 'ELEMENT_TYPE_MISSING', elementPath(id, 'type'), `Element "${id}" is missing a "type" field`, { elementId: id }, type.kind === 'missing' ? elementPath(id) : undefined);
+        }
+        const props = readOwnData(element, 'props');
+        if (props.kind !== 'value' || !isPlainObject(props.value)) {
+            addIssue(issues, 'ELEMENT_PROPS_TYPE_MISMATCH', elementPath(id, 'props'), `Element "${id}" "props" field must be an object`, { elementId: id }, props.kind === 'missing' ? elementPath(id) : undefined);
+            continue;
         }
         // Validate slot children and groups references without invoking accessors.
-        const slots = elementSlotEntries(element);
+        const rawSlots = readOwnData(props.value, 'slots');
+        if (rawSlots.kind === 'accessor' || rawSlots.kind === 'opaque') {
+            addIssue(issues, 'SLOTS_UNINSPECTABLE', elementPath(id, 'props', 'slots'), `Element "${id}" slots could not be inspected safely`, { elementId: id });
+            continue;
+        }
+        if (rawSlots.kind === 'value' && !isPlainObject(rawSlots.value)) {
+            addIssue(issues, 'SLOTS_TYPE_MISMATCH', elementPath(id, 'props', 'slots'), `Element "${id}" "slots" field must be an object`, { elementId: id });
+            continue;
+        }
+        const slots = rawSlots.kind === 'value'
+            ? ownStringDataEntries(rawSlots.value)
+            : ownStringDataEntries(undefined);
         for (const slotName of slots.accessors) {
-            errors.push(`Element "${id}" slot "${slotName}" must be an own data property`);
+            addIssue(issues, 'SLOT_ACCESSOR_NOT_ALLOWED', slotPath(id, slotName), `Element "${id}" slot "${slotName}" must be an own data property`, { elementId: id, slotName });
         }
         if (slots.opaque) {
-            errors.push(`Element "${id}" slots could not be inspected safely`);
+            addIssue(issues, 'SLOTS_UNINSPECTABLE', elementPath(id, 'props', 'slots'), `Element "${id}" slots could not be inspected safely`, { elementId: id });
         }
         for (const [slotName, slot] of slots.entries) {
-            if (!slot || typeof slot !== 'object') {
-                errors.push(`Element "${id}" slot "${slotName}" must be an object`);
+            if (!isPlainObject(slot)) {
+                addIssue(issues, 'SLOT_TYPE_MISMATCH', slotPath(id, slotName), `Element "${id}" slot "${slotName}" must be an object`, { elementId: id, slotName });
                 continue;
             }
             const children = readOwnData(slot, 'children');
             if (children.kind === 'value') {
                 const values = ownArrayDataValues(children.value);
                 if (!values) {
-                    errors.push(`Element "${id}" slot "${slotName}" children must be an array`);
+                    addIssue(issues, 'SLOT_CHILDREN_TYPE_MISMATCH', slotPath(id, slotName, 'children'), `Element "${id}" slot "${slotName}" children must be an array`, { elementId: id, slotName });
                 }
                 else {
-                    for (const childId of values) {
+                    for (const [index, childId] of values.entries()) {
                         if (typeof childId !== 'string' || childId.length === 0) {
-                            errors.push(`Element "${id}" slot "${slotName}" child IDs must be non-empty strings; received "${String(childId)}"`);
+                            addIssue(issues, 'SLOT_CHILD_ID_INVALID', slotPath(id, slotName, 'children', index), `Element "${id}" slot "${slotName}" child IDs must be non-empty strings; received "${displayValue(childId)}"`, { elementId: id, slotName, value: childId });
                         }
                         else if (!allIds.has(childId)) {
-                            errors.push(`Element "${id}" slot "${slotName}" references unknown child "${String(childId)}"`);
+                            addIssue(issues, 'ELEMENT_REFERENCE_NOT_FOUND', slotPath(id, slotName, 'children', index), `Element "${id}" slot "${slotName}" references unknown child "${displayValue(childId)}"`, { elementId: id, slotName, reference: childId });
                         }
                     }
                 }
             }
             else if (children.kind === 'accessor' || children.kind === 'opaque') {
-                errors.push(`Element "${id}" slot "${slotName}" children must be an own data property`);
+                addIssue(issues, 'SLOT_ACCESSOR_NOT_ALLOWED', slotPath(id, slotName, 'children'), `Element "${id}" slot "${slotName}" children must be an own data property`, { elementId: id, slotName, field: 'children' });
             }
             const groups = readOwnData(slot, 'groups');
             if (groups.kind === 'value') {
                 const groupValues = ownArrayDataValues(groups.value);
                 if (!groupValues) {
-                    errors.push(`Element "${id}" slot "${slotName}" groups must be an array`);
+                    addIssue(issues, 'SLOT_GROUPS_TYPE_MISMATCH', slotPath(id, slotName, 'groups'), `Element "${id}" slot "${slotName}" groups must be an array`, { elementId: id, slotName });
                 }
                 else {
-                    for (const group of groupValues) {
+                    for (const [groupIndex, group] of groupValues.entries()) {
                         const childrenInGroup = ownArrayDataValues(group);
                         if (!childrenInGroup) {
-                            errors.push(`Element "${id}" slot "${slotName}" groups must contain arrays`);
+                            addIssue(issues, 'SLOT_GROUP_TYPE_MISMATCH', slotPath(id, slotName, 'groups', groupIndex), `Element "${id}" slot "${slotName}" groups must contain arrays`, { elementId: id, slotName });
                             continue;
                         }
-                        for (const childId of childrenInGroup) {
+                        for (const [childIndex, childId] of childrenInGroup.entries()) {
                             if (typeof childId !== 'string' || childId.length === 0) {
-                                errors.push(`Element "${id}" slot "${slotName}" group child IDs must be non-empty strings; received "${String(childId)}"`);
+                                addIssue(issues, 'SLOT_GROUP_CHILD_ID_INVALID', slotPath(id, slotName, 'groups', groupIndex, childIndex), `Element "${id}" slot "${slotName}" group child IDs must be non-empty strings; received "${displayValue(childId)}"`, { elementId: id, slotName, value: childId });
                             }
                             else if (!allIds.has(childId)) {
-                                errors.push(`Element "${id}" slot "${slotName}" group references unknown child "${String(childId)}"`);
+                                addIssue(issues, 'ELEMENT_REFERENCE_NOT_FOUND', slotPath(id, slotName, 'groups', groupIndex, childIndex), `Element "${id}" slot "${slotName}" group references unknown child "${displayValue(childId)}"`, { elementId: id, slotName, reference: childId });
                             }
                         }
                     }
                 }
             }
             else if (groups.kind === 'accessor' || groups.kind === 'opaque') {
-                errors.push(`Element "${id}" slot "${slotName}" groups must be an own data property`);
+                addIssue(issues, 'SLOT_ACCESSOR_NOT_ALLOWED', slotPath(id, slotName, 'groups'), `Element "${id}" slot "${slotName}" groups must be an own data property`, { elementId: id, slotName, field: 'groups' });
             }
         }
     }
-    validateRepeatBindings(schema, errors);
-    return errors;
+    validateRepeatBindings(validationSchema, issues);
+    return issues;
+}
+/** Validate a CardSchema and return backwards-compatible error messages. */
+function validateSchema(input) {
+    return validateSchemaDetailed(input).map(issue => issue.message);
 }
 const REPEAT_SLOT_LAYOUTS = new Set([
     'default',
+    'flex',
     'list',
     'grid',
     'horizontalScroll',
@@ -2032,7 +2169,10 @@ function ownArrayDataValues(value) {
     }
 }
 function elementSlotEntries(element) {
-    const slots = readOwnData(element.props, 'slots');
+    const props = readOwnData(element, 'props');
+    const slots = props.kind === 'value'
+        ? readOwnData(props.value, 'slots')
+        : props;
     return slots.kind === 'value'
         ? ownStringDataEntries(slots.value)
         : {
@@ -2048,11 +2188,15 @@ function readRepeatBindingFields(value) {
     const template = readOwnData(value, 'template');
     const item = readOwnData(value, 'item');
     const index = readOwnData(value, 'index');
+    const emptyTemplate = readOwnData(value, 'emptyTemplate');
     return {
         source: source.kind === 'value' ? source.value : undefined,
         template: template.kind === 'value' ? template.value : undefined,
-        item: item.kind === 'value' ? item.value : undefined,
+        ...(item.kind === 'value' ? { item: item.value } : {}),
         ...(index.kind === 'value' ? { index: index.value } : {}),
+        ...(emptyTemplate.kind === 'value'
+            ? { emptyTemplate: emptyTemplate.value }
+            : {}),
     };
 }
 function slotStaticReferences(slot) {
@@ -2177,6 +2321,10 @@ function elementReferences(element) {
         if (typeof binding?.template === 'string' && binding.template) {
             references.push(binding.template);
         }
+        if (typeof binding?.emptyTemplate === 'string'
+            && binding.emptyTemplate) {
+            references.push(binding.emptyTemplate);
+        }
         const a2ui = getA2UIChildBinding(slot);
         if (typeof a2ui?.templateId === 'string' && a2ui.templateId) {
             references.push(a2ui.templateId);
@@ -2184,14 +2332,14 @@ function elementReferences(element) {
     }
     return references;
 }
-function validateRepeatBindings(schema, errors) {
+function validateRepeatBindings(schema, issues) {
     const dynamicBindings = [];
     for (const [id, element] of Object.entries(schema.elements)) {
         const elementRepeats = elementSlotEntries(element).entries
             .filter((entry) => hasOwn(entry[1], 'repeat')
             || getA2UIChildBinding(entry[1]) !== undefined);
         if (elementRepeats.length > 1) {
-            errors.push(`Element "${id}" has more than one dynamic slot`);
+            addIssue(issues, 'DYNAMIC_SLOT_MULTIPLE', elementPath(id, 'props', 'slots'), `Element "${id}" has more than one dynamic slot`, { elementId: id });
         }
         for (const [slotName, slot] of elementRepeats) {
             const a2ui = getA2UIChildBinding(slot);
@@ -2205,10 +2353,10 @@ function validateRepeatBindings(schema, errors) {
                 });
                 if (typeof a2ui.templateId !== 'string'
                     || a2ui.templateId.length === 0) {
-                    errors.push(`Element "${id}" slot "${slotName}" dynamic children template must be a non-empty string`);
+                    addIssue(issues, 'DYNAMIC_TEMPLATE_INVALID', slotPath(id, slotName), `Element "${id}" slot "${slotName}" dynamic children template must be a non-empty string`, { elementId: id, slotName });
                 }
                 else if (!getOwnElement(schema, a2ui.templateId)) {
-                    errors.push(`Element "${id}" slot "${slotName}" dynamic children reference unknown template "${a2ui.templateId}"`);
+                    addIssue(issues, 'DYNAMIC_TEMPLATE_NOT_FOUND', slotPath(id, slotName), `Element "${id}" slot "${slotName}" dynamic children reference unknown template "${a2ui.templateId}"`, { elementId: id, slotName, reference: a2ui.templateId });
                 }
                 continue;
             }
@@ -2216,7 +2364,7 @@ function validateRepeatBindings(schema, errors) {
                 ? repeat.value
                 : undefined;
             if (!isPlainObject(rawBinding)) {
-                errors.push(`Element "${id}" slot "${slotName}" repeat must be a non-null plain object`);
+                addIssue(issues, 'REPEAT_TYPE_MISMATCH', slotPath(id, slotName, 'repeat'), `Element "${id}" slot "${slotName}" repeat must be a non-null plain object`, { elementId: id, slotName });
                 continue;
             }
             const binding = readRepeatBindingFields(rawBinding);
@@ -2228,7 +2376,7 @@ function validateRepeatBindings(schema, errors) {
                 binding,
             });
             if (!REPEAT_SLOT_LAYOUTS.has(slotName)) {
-                errors.push(`Element "${id}" slot "${slotName}" does not support repeat`);
+                addIssue(issues, 'REPEAT_SLOT_UNSUPPORTED', slotPath(id, slotName, 'repeat'), `Element "${id}" slot "${slotName}" does not support repeat`, { elementId: id, slotName });
             }
             const children = readOwnData(slot, 'children');
             const groups = readOwnData(slot, 'groups');
@@ -2238,49 +2386,78 @@ function validateRepeatBindings(schema, errors) {
                 || (groups.kind === 'value' && !!groups.value)
                 || groups.kind === 'accessor'
                 || groups.kind === 'opaque') {
-                errors.push(`Element "${id}" slot "${slotName}" cannot combine repeat with children or groups`);
+                addIssue(issues, 'REPEAT_CONTENT_CONFLICT', slotPath(id, slotName, 'repeat'), `Element "${id}" slot "${slotName}" cannot combine repeat with children or groups`, { elementId: id, slotName });
             }
             if (typeof binding.source !== 'string') {
-                errors.push(`Element "${id}" slot "${slotName}" repeat source must be a string`);
+                addIssue(issues, 'REPEAT_SOURCE_TYPE_MISMATCH', slotPath(id, slotName, 'repeat', 'source'), `Element "${id}" slot "${slotName}" repeat source must be a string`, { elementId: id, slotName }, hasOwn(rawBinding, 'source')
+                    ? undefined
+                    : slotPath(id, slotName, 'repeat'));
             }
             else if (!isCompleteExpression(binding.source)) {
-                errors.push(`Element "${id}" slot "${slotName}" repeat source must be one complete non-empty \${...} expression`);
+                addIssue(issues, 'REPEAT_SOURCE_INVALID', slotPath(id, slotName, 'repeat', 'source'), `Element "${id}" slot "${slotName}" repeat source must be one complete non-empty \${...} expression`, { elementId: id, slotName });
             }
             if (typeof binding.template !== 'string') {
-                errors.push(`Element "${id}" slot "${slotName}" repeat template must be a string`);
+                addIssue(issues, 'REPEAT_TEMPLATE_TYPE_MISMATCH', slotPath(id, slotName, 'repeat', 'template'), `Element "${id}" slot "${slotName}" repeat template must be a string`, { elementId: id, slotName }, hasOwn(rawBinding, 'template')
+                    ? undefined
+                    : slotPath(id, slotName, 'repeat'));
             }
             else if (!binding.template) {
-                errors.push(`Element "${id}" slot "${slotName}" repeat template must be a non-empty string`);
+                addIssue(issues, 'REPEAT_TEMPLATE_INVALID', slotPath(id, slotName, 'repeat', 'template'), `Element "${id}" slot "${slotName}" repeat template must be a non-empty string`, { elementId: id, slotName });
             }
             else if (!getOwnElement(schema, binding.template)) {
-                errors.push(`Element "${id}" slot "${slotName}" repeat references unknown template "${binding.template}"`);
+                addIssue(issues, 'REPEAT_TEMPLATE_NOT_FOUND', slotPath(id, slotName, 'repeat', 'template'), `Element "${id}" slot "${slotName}" repeat references unknown template "${binding.template}"`, { elementId: id, slotName, reference: binding.template });
+            }
+            if (binding.item !== undefined) {
+                validateAlias(id, slotName, 'item', binding.item, issues);
             }
-            validateAlias(id, slotName, 'item', binding.item, errors);
             if (binding.index !== undefined) {
-                validateAlias(id, slotName, 'index', binding.index, errors);
+                validateAlias(id, slotName, 'index', binding.index, issues);
             }
-            if (binding.index !== undefined && binding.item === binding.index) {
-                errors.push(`Element "${id}" slot "${slotName}" repeat item and index aliases must be different`);
+            if (binding.index !== undefined
+                && (binding.item ?? '$item') === binding.index) {
+                addIssue(issues, 'REPEAT_ALIAS_COLLISION', slotPath(id, slotName, 'repeat', 'index'), `Element "${id}" slot "${slotName}" repeat item and index aliases must be different`, { elementId: id, slotName, alias: binding.index });
+            }
+            if (binding.emptyTemplate !== undefined) {
+                if (typeof binding.emptyTemplate !== 'string') {
+                    addIssue(issues, 'REPEAT_EMPTY_TEMPLATE_TYPE_MISMATCH', slotPath(id, slotName, 'repeat', 'emptyTemplate'), `Element "${id}" slot "${slotName}" repeat emptyTemplate must be a string`, { elementId: id, slotName });
+                }
+                else if (!binding.emptyTemplate) {
+                    addIssue(issues, 'REPEAT_EMPTY_TEMPLATE_INVALID', slotPath(id, slotName, 'repeat', 'emptyTemplate'), `Element "${id}" slot "${slotName}" repeat emptyTemplate must be a non-empty string`, { elementId: id, slotName });
+                }
+                else if (!getOwnElement(schema, binding.emptyTemplate)) {
+                    addIssue(issues, 'REPEAT_EMPTY_TEMPLATE_NOT_FOUND', slotPath(id, slotName, 'repeat', 'emptyTemplate'), `Element "${id}" slot "${slotName}" repeat references unknown empty template "${binding.emptyTemplate}"`, { elementId: id, slotName, reference: binding.emptyTemplate });
+                }
             }
         }
     }
-    validateRepeatNesting(schema, dynamicBindings, errors);
-    validateDynamicClosures(schema, dynamicBindings, errors);
+    validateRepeatNesting(schema, dynamicBindings, issues);
+    validateDynamicClosures(schema, dynamicBindings, issues);
 }
-function validateAlias(owner, slotName, kind, alias, errors) {
+function validateAlias(owner, slotName, kind, alias, issues) {
     if (typeof alias !== 'string') {
-        errors.push(`Element "${owner}" slot "${slotName}" repeat ${kind} must be a string`);
+        addIssue(issues, 'REPEAT_ALIAS_TYPE_MISMATCH', slotPath(owner, slotName, 'repeat', kind), `Element "${owner}" slot "${slotName}" repeat ${kind} must be a string`, { elementId: owner, slotName, field: kind });
     }
     else if (!ALIAS_PATTERN.test(alias)) {
-        errors.push(`Element "${owner}" slot "${slotName}" repeat ${kind} alias "${alias}" is invalid`);
+        addIssue(issues, 'REPEAT_ALIAS_INVALID', slotPath(owner, slotName, 'repeat', kind), `Element "${owner}" slot "${slotName}" repeat ${kind} alias "${alias}" is invalid`, { elementId: owner, slotName, field: kind, alias });
     }
     else if (RESERVED_ALIASES.has(alias)) {
-        errors.push(`Element "${owner}" slot "${slotName}" repeat ${kind} alias "${alias}" is reserved`);
+        addIssue(issues, 'REPEAT_ALIAS_RESERVED', slotPath(owner, slotName, 'repeat', kind), `Element "${owner}" slot "${slotName}" repeat ${kind} alias "${alias}" is reserved`, { elementId: owner, slotName, field: kind, alias });
     }
 }
-function validateRepeatNesting(schema, bindings, errors) {
+function validateRepeatNesting(schema, bindings, issues) {
     const reportedCycles = new Set();
     const reportedCollisions = new Set();
+    function effectiveAliases(binding) {
+        if (!binding)
+            return [];
+        if (binding.item !== undefined) {
+            return [binding.item, binding.index].filter((alias) => typeof alias === 'string');
+        }
+        return [
+            '$item',
+            binding.index === undefined ? '$index' : binding.index,
+        ].filter((alias) => typeof alias === 'string');
+    }
     function visitElement(id, activeAliases, repeatPath, visitedStatic) {
         const element = getOwnElement(schema, id);
         if (!element || visitedStatic.has(id))
@@ -2295,26 +2472,31 @@ function validateRepeatNesting(schema, bindings, errors) {
                 ? readRepeatBindingFields(repeat.value)
                 : undefined;
             const a2uiBinding = getA2UIChildBinding(slot);
-            const template = nativeBinding?.template ?? a2uiBinding?.templateId;
-            if (typeof template === 'string' && template) {
+            const itemTemplate = nativeBinding?.template ?? a2uiBinding?.templateId;
+            const visitDynamicTemplate = (template, aliases) => {
+                if (!template)
+                    return;
                 const cycleAt = repeatPath.indexOf(template);
                 if (cycleAt >= 0) {
                     const cycle = [...repeatPath.slice(cycleAt), template].join(' -> ');
                     if (!reportedCycles.has(cycle)) {
                         reportedCycles.add(cycle);
-                        errors.push(nativeBinding
+                        addIssue(issues, nativeBinding
+                            ? 'REPEAT_TEMPLATE_CYCLE'
+                            : 'DYNAMIC_TEMPLATE_CYCLE', nativeBinding
+                            ? slotPath(id, slotName, 'repeat', 'template')
+                            : slotPath(id, slotName), nativeBinding
                             ? `Element "${id}" slot "${slotName}" has repeat template cycle: ${cycle}`
-                            : `Element "${id}" slot "${slotName}" has dynamic template cycle: ${cycle}`);
+                            : `Element "${id}" slot "${slotName}" has dynamic template cycle: ${cycle}`, { elementId: id, slotName, cycle });
                     }
-                    continue;
+                    return;
                 }
-                const aliases = [nativeBinding?.item, nativeBinding?.index].filter((alias) => typeof alias === 'string');
                 for (const alias of aliases) {
                     if (activeAliases.has(alias)) {
                         const key = `${id}:${slotName}:${alias}`;
                         if (!reportedCollisions.has(key)) {
                             reportedCollisions.add(key);
-                            errors.push(`Element "${id}" slot "${slotName}" repeat alias "${alias}" conflicts with an active repeat alias`);
+                            addIssue(issues, 'REPEAT_ALIAS_COLLISION', slotPath(id, slotName, 'repeat'), `Element "${id}" slot "${slotName}" repeat alias "${alias}" conflicts with an active repeat alias`, { elementId: id, slotName, alias });
                         }
                     }
                 }
@@ -2322,7 +2504,9 @@ function validateRepeatNesting(schema, bindings, errors) {
                 for (const alias of aliases)
                     nestedAliases.add(alias);
                 visitElement(template, nestedAliases, [...repeatPath, template], new Set());
-            }
+            };
+            visitDynamicTemplate(itemTemplate, effectiveAliases(nativeBinding));
+            visitDynamicTemplate(nativeBinding?.emptyTemplate, []);
             for (const child of slotStaticReferences(slot)) {
                 visitElement(child, activeAliases, repeatPath, nextVisitedStatic);
             }
@@ -2330,13 +2514,17 @@ function validateRepeatNesting(schema, bindings, errors) {
     }
     for (const dynamic of bindings) {
         const { owner, binding, template } = dynamic;
-        const aliases = new Set([binding?.item, binding?.index].filter((alias) => typeof alias === 'string'));
+        const aliases = new Set(effectiveAliases(binding));
         if (typeof template === 'string' && template) {
             visitElement(template, aliases, [owner, template], new Set());
         }
+        if (typeof binding?.emptyTemplate === 'string'
+            && binding.emptyTemplate) {
+            visitElement(binding.emptyTemplate, new Set(), [owner, binding.emptyTemplate], new Set());
+        }
     }
 }
-function validateDynamicClosures(schema, repeats, errors) {
+function validateDynamicClosures(schema, repeats, issues) {
     for (const { owner } of repeats) {
         const visited = new Set();
         function visit(id) {
@@ -2350,10 +2538,11 @@ function validateDynamicClosures(schema, repeats, errors) {
             if ((lifecycle.kind === 'value' && !!lifecycle.value)
                 || lifecycle.kind === 'accessor'
                 || lifecycle.kind === 'opaque') {
-                errors.push(`Element "${id}" in dynamic patch closure owned by "${owner}" cannot use lifecycle`);
+                addIssue(issues, 'DYNAMIC_LIFECYCLE_UNSUPPORTED', elementPath(id, 'lifecycle'), `Element "${id}" in dynamic patch closure owned by "${owner}" cannot use lifecycle`, { elementId: id, owner });
             }
-            if (hasOwn(element.props, 'variableKey')) {
-                errors.push(`Element "${id}" in dynamic patch closure owned by "${owner}" cannot use props.variableKey`);
+            const props = readOwnData(element, 'props');
+            if (props.kind === 'value' && hasOwn(props.value, 'variableKey')) {
+                addIssue(issues, 'DYNAMIC_VARIABLE_KEY_UNSUPPORTED', elementPath(id, 'props', 'variableKey'), `Element "${id}" in dynamic patch closure owned by "${owner}" cannot use props.variableKey`, { elementId: id, owner });
             }
             for (const reference of elementReferences(element))
                 visit(reference);
@@ -2880,6 +3069,7 @@ function materializeCard(input, variables, options = {}) {
                         template: native.template,
                         item: native.item,
                         index: native.index,
+                        emptyTemplate: native.emptyTemplate,
                     };
                 }
                 else {
@@ -2907,6 +3097,9 @@ function materializeCard(input, variables, options = {}) {
                     sourceOwnerId: sourceId,
                     slot: slotName,
                     templateId: binding.template,
+                    ...(binding.emptyTemplate
+                        ? { emptyTemplateId: binding.emptyTemplate }
+                        : {}),
                     ...(sourcePath === undefined ? {} : { sourcePath }),
                     dataPath: activeScope.dataPath,
                     instancePath,
@@ -2918,6 +3111,9 @@ function materializeCard(input, variables, options = {}) {
                 repeatOwners.set(ownerKey, owner);
                 slotOwners.set(slotName, { owner, binding, sourcePath, depth });
                 addDependency('component', binding.template, ownerKey);
+                if (binding.emptyTemplate) {
+                    addDependency('component', binding.emptyTemplate, ownerKey);
+                }
                 const runtimeKeys = runtimeOwnerKeys.get(id) ?? [];
                 if (runtimeKeys.length > 0) {
                     for (const key of runtimeKeys)
@@ -2998,15 +3194,30 @@ function materializeCard(input, variables, options = {}) {
             Reflect.deleteProperty(slot, 'repeat');
             Reflect.deleteProperty(slot, A2UI_CHILD_BINDING);
             slot.children = [];
+            if (items.length === 0
+                && binding.dialect === 'native'
+                && binding.emptyTemplate) {
+                const emptyPath = appendOccurrence(structuralPath, 'item', sourceId, slotName, `${binding.emptyTemplate}:empty`);
+                const empty = buildNode(binding.emptyTemplate, activeScope, emptyPath, emptyPath, true, id, depth, owner.key, nextActiveDefinitions);
+                slot.children.push(empty.id);
+                node.children.push(empty);
+            }
             items.forEach((item, index) => {
                 const dataPath = sourcePath === undefined
                     ? activeScope.dataPath
                     : joinPointer(sourcePath, [String(index)]);
-                const locals = binding.dialect === 'native' && binding.item
-                    ? {
-                        [binding.item]: item,
-                        ...(binding.index ? { [binding.index]: index } : {}),
-                    }
+                const locals = binding.dialect === 'native'
+                    ? binding.item !== undefined
+                        ? {
+                            [binding.item]: item,
+                            ...(binding.index === undefined
+                                ? {}
+                                : { [binding.index]: index }),
+                        }
+                        : {
+                            $item: item,
+                            [binding.index ?? '$index']: index,
+                        }
                     : {};
                 const childScope = {
                     root: rootVariables,
@@ -3016,14 +3227,23 @@ function materializeCard(input, variables, options = {}) {
                     bindingDialect: binding.dialect,
                 };
                 const aliases = new Map();
-                if (binding.dialect === 'native' && binding.item) {
-                    aliases.set(binding.item, sourcePath === undefined ? undefined : dataPath);
-                    if (binding.index)
-                        aliases.set(binding.index, sourcePath);
+                if (binding.dialect === 'native') {
+                    const itemAlias = binding.item ?? '$item';
+                    const indexAlias = binding.item === undefined
+                        ? binding.index ?? '$index'
+                        : binding.index;
+                    aliases.set(itemAlias, sourcePath === undefined ? undefined : dataPath);
+                    if (indexAlias !== undefined) {
+                        aliases.set(indexAlias, sourcePath);
+                    }
                 }
                 scopeAliasPaths.set(childScope, aliases);
-                scopeIndexAliases.set(childScope, new Set(binding.dialect === 'native' && binding.index
-                    ? [binding.index]
+                scopeIndexAliases.set(childScope, new Set(binding.dialect === 'native'
+                    ? binding.item === undefined
+                        ? [binding.index ?? '$index']
+                        : binding.index === undefined
+                            ? []
+                            : [binding.index]
                     : []));
                 const itemPath = appendOccurrence(structuralPath, 'item', sourceId, slotName, `${binding.template}:${index}`);
                 const child = buildNode(binding.template, childScope, itemPath, itemPath, true, id, depth, owner.key, nextActiveDefinitions);
@@ -4749,4 +4969,4 @@ function getBuiltinIcon(name) {
     return BUILTIN_ICONS[name];
 }
 
-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$1 as 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 { 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$1 as 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, validateSchemaDetailed };