@veil-runtime/ui 0.4.1 → 0.5.0

package/dist/interface.js

@@ -1,28 +1,45 @@
-import { assertBoundedData, assertSafeKey, copyData } from "./validation-safety.js";
+import { assertBoundedData, assertSafeKey, boundedDataLimits, copyData } from "./validation-safety.js";
 import { attachInterfaceRenderers, detachInterfaceRenderers } from "./interface-transaction.js";
+const rowIdentifier = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const rowName = (value) => typeof value === "string" && rowIdentifier.exec(value)?.[0] === value;
 const identifier = /^[A-Za-z][A-Za-z0-9._-]{0,127}$/;
+const interfaceLimits = { treeDepth: 15, nodes: 512, textLength: 4096, tableRows: 100, tableColumns: 20, listItems: 100, selectOptions: 100, conditionDepth: 8, conditionNodes: 64, conditionTerms: 16, rowActions: 8, rowIdLength: 128 };
+const presentationPhases = ["loading", "ready", "empty", "error"];
 const commonProperties = ["key", "component", "visible", "ariaLabel"];
 const vocabulary = {
     Stack: { properties: [...commonProperties, "children"], required: [], children: true, event: null },
     Row: { properties: [...commonProperties, "children"], required: [], children: true, event: null },
+    Grid: { properties: [...commonProperties, "children", "columns", "columnsAt", "gap"], required: [], children: true, event: null },
     Text: { properties: [...commonProperties, "text"], required: [], children: false, event: null },
     Heading: { properties: [...commonProperties, "text"], required: ["text"], children: false, event: null },
-    Status: { properties: [...commonProperties, "text"], required: [], children: false, event: null },
-    Input: { properties: [...commonProperties, "label", "binding", "inputType", "validation"], required: ["label", "binding"], children: false, event: "state change" },
-    Textarea: { properties: [...commonProperties, "label", "binding", "validation"], required: ["label", "binding"], children: false, event: "state change" },
-    Select: { properties: [...commonProperties, "label", "binding", "validation", "options"], required: ["label", "binding", "options"], children: false, event: "state change" },
+    Status: { properties: [...commonProperties, "text", "phase"], required: [], children: false, event: null },
+    Input: { properties: [...commonProperties, "description", "disabled", "readOnly", "label", "binding", "inputType", "validation"], required: ["label", "binding"], children: false, event: "state change" },
+    Textarea: { properties: [...commonProperties, "description", "disabled", "readOnly", "label", "binding", "validation"], required: ["label", "binding"], children: false, event: "state change" },
+    Select: { properties: [...commonProperties, "description", "disabled", "label", "binding", "validation", "options"], required: ["label", "binding", "options"], children: false, event: "state change" },
     Button: { properties: [...commonProperties, "text", "action", "disabled", "validate"], required: ["text", "action"], children: false, event: "action" },
-    Table: { properties: [...commonProperties, "binding", "columns"], required: ["binding", "columns"], children: false, event: null },
+    Table: { properties: [...commonProperties, "binding", "columns", "rowKey", "rowActions"], required: ["binding", "columns"], children: false, event: "row action (opt-in)" },
     List: { properties: [...commonProperties, "binding"], required: ["binding"], children: false, event: null },
 };
 const builtins = new Set(Object.keys(vocabulary));
-const nodeKeys = new Set(["key", "component", "children", "text", "binding", "visible", "action", "label", "inputType", "columns", "ariaLabel", "disabled", "validation", "options", "validate"]);
+const nodeKeys = new Set(["phase", "key", "component", "children", "text", "binding", "visible", "action", "label", "inputType", "columns", "columnsAt", "gap", "ariaLabel", "disabled", "validation", "options", "validate", "rowKey", "rowActions", "description", "readOnly"]);
 /** JSON-safe description of the built-in vocabulary. Host extensions are trusted code and are never advertised here. */
 export function getInterfaceCapabilities() {
-    return copyData({ version: 1, components: vocabulary, bindings: { sources: ["data", "state"], path: "dot-separated own-property path", missing: "empty display", visibility: "strict scalar equality; ne, lt, lte, gt, gte; all, any, not" },
-        propertyTypes: { key: "identifier", component: "component name", children: "node array", text: "string or binding", binding: "binding", visible: "condition", disabled: "Button condition", validation: "{required,minLength,maxLength,min,max}", validate: "Button boolean", options: "Select array of {value:string,label:string}", action: "declared action identifier", label: "string", inputType: ["text", "number", "checkbox"], columns: "array of {key:identifier,label:string}", ariaLabel: "string" },
-        events: { action: { fields: ["action", "source", "state", "revision"], declaration: "definition.actions and host allowedActions" }, state: { type: "scalar", source: "state binding" } },
-        limits: { treeDepth: 16, nodes: 512, textLength: 4096, tableRows: 100, tableColumns: 20, listItems: 100, transportBytes: 1048576 } });
+    return copyData({ version: 5, components: vocabulary, bindings: { sources: ["data", "state"], path: "dot-separated own-property path", missing: "empty display", visibility: "strict scalar equality; ne, lt, lte, gt, gte; all, any, not",
+            pathPattern: identifier.source, separator: ".", emptyInteriorSegmentsAccepted: true, forbiddenSegments: ["__proto__", "prototype", "constructor"], ownPropertiesOnly: true, exactProperties: ["source", "path"] },
+        propertyTypes: { phase: "Status loading|ready|empty|error literal or binding", rowKey: "direct own-property identifier", rowActions: "array of {action:declared identifier,label:string}", key: "identifier", component: "component name", children: "node array", text: "string or binding", binding: "binding", visible: "condition", disabled: "Button or field condition", description: "field plain string; maximum 4096 UTF-16 units", readOnly: "text/number Input or Textarea boolean", validation: "{required,minLength,maxLength,min,max}", validate: "Button boolean", options: "Select array of {value:string,label:string}", action: "declared action identifier", label: "string", inputType: ["text", "number", "checkbox"], columns: "Table array of {key:identifier,label:string,presentation?:text|badge} or Grid column count", columnsAt: "Grid {sm?,lg?} column counts", gap: ["none", "sm", "md", "lg"], ariaLabel: "string" },
+        events: { action: { fields: ["action", "source", "state", "revision"], optionalFields: ["rowId"], declaration: "definition.actions and host allowedActions" }, state: { type: "scalar", source: "state binding" } },
+        limits: { treeDepth: interfaceLimits.treeDepth, nodes: interfaceLimits.nodes, textLength: interfaceLimits.textLength, tableRows: interfaceLimits.tableRows, tableColumns: interfaceLimits.tableColumns, listItems: interfaceLimits.listItems, transportBytes: boundedDataLimits.bytes,
+            selectOptions: interfaceLimits.selectOptions, conditionDepth: interfaceLimits.conditionDepth, conditionNodes: interfaceLimits.conditionNodes, conditionTerms: interfaceLimits.conditionTerms,
+            rowActions: interfaceLimits.rowActions, rowIdLength: interfaceLimits.rowIdLength, aggregate: boundedDataLimits, treeDepthMeaning: "maximum child edges; aggregate traversal can reject shallower definitions with nested data or conditions" },
+        behavior: {
+            presentation: { component: "Status", phases: ["loading", "ready", "empty", "error"], phaseBinding: "required exact enum at every snapshot", message: "plain string; maximum 4096 UTF-16 units; absent text uses phase default", defaults: { loading: "Loading…", ready: "Ready.", empty: "No results.", error: "Unable to complete the request." }, accessibility: "polite atomic status; no aria-busy on message; tabindex=-1", focus: "retain eligible focus; lost/hidden/disabled focus moves to first visible phased Status", retry: "ordinary host-allowlisted Button; no automatic execution", transitions: "existing revision-protected updates; host must supply expectedRevision", orchestration: "host-owned" },
+            collections: { component: "Table", rowKey: "direct own property; optional without actions", rowIdPattern: rowIdentifier.source, rowIdMatching: "entire string; no trailing line terminators", duplicateOrMissingIds: "reject candidate atomically", missingBinding: "empty", rowActionsRequire: ["rowKey", "explicit host allowedActions"], presentations: ["text", "badge"], defaultPresentation: "text", badge: "neutral text; no inferred semantics or live region", dispatch: "dispatchRow(action,source,rowId,expectedRevision)", source: "Table.key", staleRevisionOrMissingRow: "false; no event", identityScope: ["interface id", "Table key", "binding source", "binding path", "rowKey", "rowId"], reconciliation: "retain matching rows and action buttons; focus follows retained controls", keyboard: "native Tab/Shift+Tab; Enter/Space", gesture: "capture revision at pointerdown/activation keydown; click-only activation uses rendered revision; reject changes during propagation", authorization: "rowId is an opaque lookup reference; host must authorize actual record", eventRowData: false },
+            grid: { columns: [1, 2, 3, 4], defaultColumns: 1, breakpoints: { sm: 600, lg: 1024 }, semantics: "mobile-first; sm applies at 600px and lg at 1024px; omitted values inherit the preceding count", gaps: { none: "0", sm: "0.5rem", md: "0.75rem", lg: "1.5rem" }, defaultGap: "md", tracks: "equal minmax(0,1fr)", order: "DOM and keyboard order follow children" },
+            conditions: { forms: ["equals", "operator", "all", "any", "not"], operators: ["ne", "lt", "lte", "gt", "gte"], orderedValueType: "finite number", equality: "strict", minTerms: 1, maxTerms: interfaceLimits.conditionTerms, maxDepth: interfaceLimits.conditionDepth, maxNodes: interfaceLimits.conditionNodes, missingNumericMatches: false },
+            validation: { fields: ["Input", "Textarea", "Select"], rules: ["required", "minLength", "maxLength", "min", "max"], lengthIntegerRange: [0, 4096], numericRulesRequire: { component: "Input", inputType: "number" }, lengthExcludedInputTypes: ["number", "checkbox"], reversedBounds: "reject", hiddenFields: "excluded", disabledFields: "excluded; state retained", readOnlyFields: "validated; host may set state", feedback: "eager on every accepted snapshot; describedby and errormessage", submissionFocus: "first invalid field on DOM validating button activation", trigger: "Button.validate true" },
+            actions: { declaration: "definition.actions", hostAllowlist: "allowedActions", source: "Button.key or Table.key for row events", optionalEventFields: ["rowId"], hiddenOrDisabled: "not dispatchable", eventFields: ["action", "source", "state", "revision"], stateCopy: true, authorization: "host-owned" },
+            updates: { data: "replace", definition: "replace", expectedRevision: "optional; stale returns false", invalidCandidate: "throws without advancing accepted revision", rendererPreparation: "before acceptance", subscriptions: "after acceptance", listenerFeedbackPasses: 32, compatibleState: ["same interface id", "same input key", "same component and input type", "same binding path", "compatible declared default"], disposal: "later data and definition updates return false" },
+        } });
 }
 const plain = (value) => !!value && typeof value === "object" && !Array.isArray(value);
 const exact = (value, allowed) => {
@@ -54,20 +71,37 @@ function visitNodes(node, callback) {
 }
 function validateBindings(definition, data, state) {
     visitNodes(definition.screen, (node) => {
+        if (node.component === "Status" && node.phase !== undefined) {
+            const phase = typeof node.phase === "string" ? node.phase : valueAt(node.phase.source === "data" ? data : state, node.phase.path);
+            if (!presentationPhases.includes(phase))
+                throw new Error("Invalid Status phase");
+            const text = typeof node.text === "object" ? valueAt(node.text.source === "data" ? data : state, node.text.path) : node.text;
+            if (node.text !== undefined && (typeof text !== "string" || text.length > interfaceLimits.textLength))
+                throw new Error("Invalid Status message");
+        }
         if (node.component === "Table") {
             const rows = valueAt(node.binding.source === "data" ? data : state, node.binding.path);
             if (rows === undefined)
                 return;
-            if (!Array.isArray(rows) || rows.length > 100 || rows.some((row) => !plain(row)))
+            if (!Array.isArray(rows) || rows.length > interfaceLimits.tableRows || rows.some((row) => !plain(row)))
                 throw new Error("Invalid or oversized table rows");
+            if (node.rowKey) {
+                const ids = new Set();
+                for (const row of rows) {
+                    const id = Object.hasOwn(row, node.rowKey) ? row[node.rowKey] : undefined;
+                    if (!rowName(id) || ids.has(id))
+                        throw new Error("Invalid, missing or duplicate row ID");
+                    ids.add(id);
+                }
+            }
             for (const row of rows)
-                for (const col of node.columns ?? [])
+                for (const col of Array.isArray(node.columns) ? node.columns : [])
                     if (Object.hasOwn(row, col.key) && !scalar(row[col.key]))
                         throw new Error("Invalid table cell");
         }
         if (node.component === "List") {
             const items = valueAt(node.binding.source === "data" ? data : state, node.binding.path);
-            if (items !== undefined && (!Array.isArray(items) || items.length > 100 || items.some((item) => !scalar(item))))
+            if (items !== undefined && (!Array.isArray(items) || items.length > interfaceLimits.listItems || items.some((item) => !scalar(item))))
                 throw new Error("Invalid or oversized list items");
         }
         if (isInterfaceField(node)) {
@@ -128,7 +162,7 @@ export function validateInterfaceDefinition(value, components = []) {
     const keys = new Set();
     let count = 0;
     function visit(node, depth) {
-        if (!plain(node) || depth > 16 || ++count > 512)
+        if (!plain(node) || depth > interfaceLimits.treeDepth || ++count > interfaceLimits.nodes)
             throw new Error("Interface tree limit exceeded");
         exact(node, nodeKeys);
         if (!name(node.key) || keys.has(node.key))
@@ -147,21 +181,35 @@ export function validateInterfaceDefinition(value, components = []) {
         }
         if (node.text !== undefined) {
             if (typeof node.text === "string") {
-                if (node.text.length > 4096)
+                if (node.text.length > interfaceLimits.textLength)
                     throw new Error("Text limit exceeded");
             }
             else
                 binding(node.text);
         }
+        if (node.phase !== undefined) {
+            if (node.component !== "Status")
+                throw new Error("Only Status accepts phase");
+            if (typeof node.phase === "string") {
+                if (!presentationPhases.includes(node.phase))
+                    throw new Error("Invalid Status phase");
+            }
+            else
+                binding(node.phase);
+        }
         if (node.binding !== undefined)
             binding(node.binding);
         if (node.visible !== undefined)
             validateCondition(node.visible);
         if (node.disabled !== undefined) {
-            if (node.component !== "Button")
-                throw new Error("Only Button accepts disabled");
+            if (node.component !== "Button" && !isInterfaceField(node))
+                throw new Error("Only Button or fields accept disabled");
             validateCondition(node.disabled);
         }
+        if (node.description !== undefined && (!isInterfaceField(node) || typeof node.description !== "string" || node.description.length > interfaceLimits.textLength))
+            throw new Error("Invalid field description");
+        if (node.readOnly !== undefined && (typeof node.readOnly !== "boolean" || !(node.component === "Textarea" || (node.component === "Input" && node.inputType !== "checkbox"))))
+            throw new Error("Invalid readOnly field");
         for (const field of ["label", "ariaLabel"])
             if (node[field] !== undefined && (typeof node[field] !== "string" || node[field].length > 256))
                 throw new Error(`Invalid ${field}`);
@@ -172,7 +220,7 @@ export function validateInterfaceDefinition(value, components = []) {
         if (node.validate !== undefined && (node.component !== "Button" || typeof node.validate !== "boolean"))
             throw new Error("Invalid validate flag");
         if (node.options !== undefined) {
-            if (node.component !== "Select" || !Array.isArray(node.options) || node.options.length < 1 || node.options.length > 100)
+            if (node.component !== "Select" || !Array.isArray(node.options) || node.options.length < 1 || node.options.length > interfaceLimits.selectOptions)
                 throw new Error("Invalid select options");
             const values = new Set();
             for (const option of node.options) {
@@ -202,10 +250,36 @@ export function validateInterfaceDefinition(value, components = []) {
             if (rules.minLength > rules.maxLength || rules.min > rules.max)
                 throw new Error("Reversed validation bounds");
         }
-        if (node.columns !== undefined) {
-            if (!Array.isArray(node.columns) || node.columns.length < 1 || node.columns.length > 20 || node.columns.some((col) => !plain(col) || Object.keys(col).some((key) => key !== "key" && key !== "label") || !name(col.key) || typeof col.label !== "string" || col.label.length > 256))
+        if (node.component === "Grid") {
+            if (node.columns !== undefined && ![1, 2, 3, 4].includes(node.columns))
+                throw new Error("Invalid Grid columns");
+            if (node.columnsAt !== undefined && (!plain(node.columnsAt) || Object.keys(node.columnsAt).some((key) => !["sm", "lg"].includes(key)) || Object.values(node.columnsAt).some((count) => ![1, 2, 3, 4].includes(count))))
+                throw new Error("Invalid Grid breakpoints");
+            if (node.gap !== undefined && !["none", "sm", "md", "lg"].includes(node.gap))
+                throw new Error("Invalid Grid gap");
+        }
+        else if (node.columns !== undefined) {
+            if (!Array.isArray(node.columns) || node.columns.length < 1 || node.columns.length > interfaceLimits.tableColumns || node.columns.some((col) => !plain(col) || Object.keys(col).some((key) => key !== "key" && key !== "label" && key !== "presentation") || (col.presentation !== undefined && !["text", "badge"].includes(col.presentation)) || !name(col.key) || typeof col.label !== "string" || col.label.length > 256))
                 throw new Error("Invalid table columns");
         }
+        if (node.rowKey !== undefined) {
+            if (node.component !== "Table" || !name(node.rowKey))
+                throw new Error("Invalid Table rowKey");
+            assertSafeKey(node.rowKey);
+        }
+        if (node.rowActions !== undefined) {
+            if (node.component !== "Table" || !node.rowKey || !Array.isArray(node.rowActions) || node.rowActions.length < 1 || node.rowActions.length > interfaceLimits.rowActions)
+                throw new Error("Invalid Table rowActions");
+            const ids = new Set();
+            for (const item of node.rowActions) {
+                if (!plain(item))
+                    throw new Error("Invalid row action");
+                exact(item, new Set(["action", "label"]));
+                if (!name(item.action) || !actions.includes(item.action) || ids.has(item.action) || typeof item.label !== "string" || !item.label.trim() || item.label.length > 256)
+                    throw new Error("Invalid or undeclared row action");
+                ids.add(item.action);
+            }
+        }
         if (isInterfaceField(node) && (!node.binding || node.binding.source !== "state" || !node.label))
             throw new Error("Input needs a state binding and label");
         if (node.component === "Button" && (!node.action || !node.text))
@@ -216,9 +290,9 @@ export function validateInterfaceDefinition(value, components = []) {
             throw new Error("Only Button accepts an action");
         if (node.component !== "Input" && node.inputType !== undefined)
             throw new Error("Only Input accepts inputType");
-        if (node.component !== "Table" && node.columns !== undefined)
-            throw new Error("Only Table accepts columns");
-        if (node.children !== undefined && (!Array.isArray(node.children) || (!(["Stack", "Row"].includes(node.component)) && !components.includes(node.component))))
+        if (node.component !== "Table" && node.component !== "Grid" && node.columns !== undefined)
+            throw new Error("Only Table and Grid accept columns");
+        if (node.children !== undefined && (!Array.isArray(node.children) || (!(["Stack", "Row", "Grid"].includes(node.component)) && !components.includes(node.component))))
             throw new Error("Invalid children");
         for (const child of node.children ?? [])
             visit(child, depth + 1);
@@ -228,9 +302,17 @@ export function validateInterfaceDefinition(value, components = []) {
 }
 export function createInterfaceController(definition, options = {}) {
     const components = options.components ?? [];
+    const allowedActions = options.allowedActions ? [...options.allowedActions] : undefined;
+    const checkActions = (candidate) => {
+        visitNodes(candidate.screen, node => {
+            if (node.rowActions && !allowedActions)
+                throw new Error("Table row actions require explicit host allowedActions");
+        });
+        if (allowedActions && candidate.actions?.some(action => !allowedActions.includes(action)))
+            throw new Error("Action is not allowed by host");
+    };
     validateInterfaceDefinition(definition, components);
-    if (options.allowedActions && definition.actions?.some((action) => !options.allowedActions.includes(action)))
-        throw new Error("Action is not allowed by host");
+    checkActions(definition);
     let current = copyData(definition);
     let data = copyData(definition.data ?? {});
     let state = copyData(definition.state ?? {});
@@ -334,8 +416,7 @@ export function createInterfaceController(definition, options = {}) {
             if (updating)
                 throw new Error("Interface update already in progress");
             validateInterfaceDefinition(next, components);
-            if (options.allowedActions && next.actions?.some((action) => !options.allowedActions.includes(action)))
-                throw new Error("Action is not allowed by host");
+            checkActions(next);
             const copy = copyData(next);
             const nextData = copyData(copy.data ?? {});
             const nextState = retainedState(current, copy, state);
@@ -369,6 +450,44 @@ export function createInterfaceController(definition, options = {}) {
             validateBindings(current, data, next);
             accept(current, data, next);
         },
+        dispatchRow(action, source, rowId, expectedRevision) {
+            if (!name(action) || !name(source) || !rowName(rowId) || !Number.isSafeInteger(expectedRevision) || expectedRevision < 0)
+                throw new Error("Invalid row dispatch");
+            if (disposed || dispatching)
+                return false;
+            if (updating)
+                throw new Error("Interface update already in progress");
+            if (expectedRevision !== revision)
+                return false;
+            let table;
+            const find = (node) => {
+                if (node.visible && !evaluateInterfaceCondition(node.visible, { data, state }))
+                    return;
+                if (node.key === source && node.component === "Table")
+                    table = node;
+                for (const child of node.children ?? [])
+                    find(child);
+            };
+            find(current.screen);
+            if (!table?.rowKey || !allowedActions?.includes(action) || !current.actions?.includes(action) || !table.rowActions?.some(item => item.action === action))
+                throw new Error("Row action is not available");
+            const rows = valueAt(table.binding.source === "data" ? data : state, table.binding.path);
+            if (!Array.isArray(rows) || rows.filter(row => Object.hasOwn(row, table.rowKey) && row[table.rowKey] === rowId).length !== 1)
+                return false;
+            dispatching = true;
+            try {
+                const result = options.onEvent?.({ action, source, rowId, state: copyData(state), revision });
+                if (result && typeof result === "object" && "then" in result)
+                    void Promise.resolve(result).catch(report);
+            }
+            catch (error) {
+                report(error);
+            }
+            finally {
+                dispatching = false;
+            }
+            return true;
+        },
         dispatch(action, source) {
             if (disposed || dispatching)
                 return;
@@ -420,13 +539,13 @@ export function resolveInterfaceBinding(snapshot, bindingValue) {
 function validateCondition(value) {
     let count = 0;
     function visit(value, depth) {
-        if (!plain(value) || depth > 8 || ++count > 64)
+        if (!plain(value) || depth > interfaceLimits.conditionDepth || ++count > interfaceLimits.conditionNodes)
             throw new Error("Invalid condition or condition limit exceeded");
         if (Object.hasOwn(value, "all") || Object.hasOwn(value, "any")) {
             const key = Object.hasOwn(value, "all") ? "all" : "any";
             exact(value, new Set([key]));
             const terms = value[key];
-            if (!Array.isArray(terms) || terms.length < 1 || terms.length > 16)
+            if (!Array.isArray(terms) || terms.length < 1 || terms.length > interfaceLimits.conditionTerms)
                 throw new Error("Invalid condition terms");
             for (const term of terms)
                 visit(term, depth + 1);
@@ -478,13 +597,13 @@ export function evaluateInterfaceCondition(condition, snapshot) {
 export function isInterfaceField(node) {
     return ["Input", "Textarea", "Select"].includes(node.component);
 }
-/** Errors are recomputed from accepted state; hidden fields are excluded, including hidden ancestors. */
+/** Errors are recomputed from accepted state; hidden and disabled fields are excluded, including hidden ancestors. */
 export function getInterfaceValidation(snapshot) {
     const errors = {};
     function visit(node) {
         if (node.visible && !evaluateInterfaceCondition(node.visible, snapshot))
             return;
-        if (isInterfaceField(node)) {
+        if (isInterfaceField(node) && !(node.disabled && evaluateInterfaceCondition(node.disabled, snapshot))) {
             const value = valueAt(snapshot.state, node.binding.path);
             const rules = node.validation ?? {};
             const empty = value === undefined || value === null || value === "";

package/dist/validation-safety.d.ts

@@ -1,3 +1,13 @@
+/** Internal transport limits. Hosts must also limit bytes before decoding JSON. */
+/** Internal aggregate traversal budget, shared with public capability metadata. */
+export declare const boundedDataLimits: {
+    readonly depth: 32;
+    readonly nodes: 10000;
+    readonly keys: 256;
+    readonly items: 1000;
+    readonly string: 65536;
+    readonly bytes: 1048576;
+};
 export declare function assertSafeKey(key: string): void;
 /** Inspect descriptors, never getters; bound work before recursive or Zod validation. */
 export declare function assertBoundedData(value: unknown): void;

package/dist/validation-safety.js

@@ -1,5 +1,7 @@
 /** Internal transport limits. Hosts must also limit bytes before decoding JSON. */
-const limits = { depth: 32, nodes: 10000, keys: 256, items: 1000, string: 65536, bytes: 1048576 };
+/** Internal aggregate traversal budget, shared with public capability metadata. */
+export const boundedDataLimits = { depth: 32, nodes: 10000, keys: 256, items: 1000, string: 65536, bytes: 1048576 };
+const limits = boundedDataLimits;
 const reserved = new Set(["__proto__", "prototype", "constructor"]);
 export function assertSafeKey(key) {
     if (reserved.has(key))

package/docs/API.md

@@ -1,8 +1,10 @@
 # Public API inventory
 
-The v0.3.0-rc.2 candidate adds `@veil-runtime/ui/interface` (`defineInterface`, `validateInterfaceDefinition`, `createInterfaceController`, `getInterfaceCapabilities`, `resolveInterfaceBinding`, and types including `BuiltinInterfaceDefinition`) and `mountInterface`, `createMountedInterface`, plus `InterfaceDOMComponentInstance` in `/dom`. `InterfaceDOMComponent` may still return an `HTMLElement`; it may now return `{ element, update?, dispose? }`. Updates prepare detached custom instances before controller acceptance. See [UNIVERSAL-INTERFACE.md](UNIVERSAL-INTERFACE.md). The v0.2.0 composition API remains available through `/composition` and `/dom`. The inventory below describes preserved v0.1.0 APIs.
+The current source is the unpublished **@veil-runtime/ui v0.5.0 candidate**; v0.4.2 is the published baseline recorded by this repository. Its package exports are the root `@veil-runtime/ui` and the `/inspection`, `/composition`, `/interface`, and `/dom` subpaths. Import through these entry points rather than internal `dist` files. The root also re-exports the interface and composition modules; the subpaths make their boundaries explicit. Updates prepare detached custom instances before controller acceptance.
 
-The preview keeps all existing root exports; no existing symbol or subpath was removed. The root index exports modules below. All interfaces/types exported by those modules remain available in the declarations. Package consumers import through the root or documented `/inspection`, `/composition`, `/interface`, and `/dom` subpaths, not paths inside dist.
+`/interface` exports `defineInterface`, `validateInterfaceDefinition`, `createInterfaceController`, `getInterfaceCapabilities`, `resolveInterfaceBinding`, `getInterfaceValidation`, and `evaluateInterfaceCondition`, with their public types including `BuiltinInterfaceDefinition` and `InterfaceConditionExpression`. `/dom` exports `mountInterface` and `createMountedInterface` alongside the composition mount. A trusted `InterfaceDOMComponent` can return an `HTMLElement` or `{ element, update?, dispose? }`. See [UNIVERSAL-INTERFACE.md](UNIVERSAL-INTERFACE.md) and the [v0.4.0 contract guide](v0.4.0.md) for the preserved validation and conditions. The v0.5.0 built-ins and migration requirements are described in the current universal guide and [release notes](RELEASE-0.5.0.md).
+
+The table below inventories the preserved capability-description API that first shipped in v0.1.0; `/composition` preserves the later one-screen composition API. The v0.3.0 release-candidate records describe when `/interface` and its DOM adapter were introduced, not their current release status or complete current behavior.
 
 | Area | Root modules / representative API |
 |---|---|
@@ -16,4 +18,14 @@ The preview keeps all existing root exports; no existing symbol or subpath was r
 | Experimental optional presentation | `capability-view-derivation` provider interfaces and `deriveCapabilityView`; `presentation-composition`, `buildPresentationEnvelope`, `deterministicPresentation`, `validatePresentationPlan`, `composePresentation`, `presentationPlanSchema`, `sectionId` |
 | Inspection subpath | `@veil-runtime/ui/inspection`: `buildCompositionInspection` and inspection model types |
 
-Qualification exercises the legacy Core capability API and the independent universal interface subpaths, strict public declarations, and browser bundling. Published export conditions intentionally support ESM import, not direct CommonJS require. Core is an optional peer and is unnecessary for `/interface` and `/dom` consumers. UI has no compiled Core runtime import. A host may use UI's descriptors in a browser and keep Core execution on its server.
+Qualification exercises the legacy Core capability API and the independent universal interface subpaths, strict public declarations, and browser bundling. Published export conditions intentionally support ESM import, not direct CommonJS require. Core is an optional peer with declared range `^0.4.0` and is unnecessary for standalone `/interface` and `/dom` consumers. This range does not claim Core v0.6.0 compatibility. UI has no compiled Core runtime import. A host may use UI's descriptors in a browser and keep Core execution on its server.
+
+## v0.5.0 interface additions
+
+`/interface` and the root export `GridColumns`, `GridGap`, `GridBreakpoints`, `InterfaceCellPresentation`, `InterfaceRowAction`, `InterfaceTableOptions` and `InterfacePresentationPhase`. `InterfaceColumn` adds `presentation`; `InterfaceEvent` adds optional `rowId`; `InterfaceController` requires `dispatchRow(action, source, rowId, expectedRevision): boolean`. The final manifest version is 5.
+
+Other public interface helpers are `evaluateInterfaceCondition`, `getInterfaceValidation` and `isInterfaceField`. `defineInterface` is a typing helper, not validation. Call `validateInterfaceDefinition` or create a controller to validate received JSON. The broad `InterfaceNode` permits registered custom names; use `BuiltinInterfaceDefinition` for component-specific static checks. Runtime validation remains authoritative.
+
+`/dom` exports `mountComposedApplication`, `DOMComponent`, `DOMComponentRegistry`, `mountInterface`, `createMountedInterface`, `InterfaceDOMComponent`, `InterfaceDOMComponentInstance` and `InterfaceDOMRegistry`. `/composition` exports its definition/controller, handler, snapshot and result types, and `defineComposedApplication`, `validateComposedApplication`, `createCompositionController`.
+
+Custom controller implementations must implement the required row method with the documented governance checks. The native `mountInterface` additionally requires the private preparation bridge installed by `createInterfaceController`; a structurally matching custom controller alone cannot mount with this adapter. Use the supplied controller for native mounts, or a custom adapter consuming snapshots/subscriptions. No private bridge import is supported. See [migration guidance](RELEASE-0.5.0.md).

package/docs/ASYNC-PRESENTATION-0.5.0.md

@@ -0,0 +1,109 @@
+# Host-driven asynchronous presentation (v0.5.0)
+
+## Design decision (before implementation)
+
+Extend the existing Status leaf with optional `phase`, a literal `loading`,
+`ready`, `empty` or `error`, or an existing `{source,path}` binding resolving to
+exactly one of those strings. No phase means legacy Status behavior. A phased
+Status supplies a reusable accessible message and focus destination. Existing
+conditions compose content and ordinary Buttons request retry. A state container
+would duplicate condition evaluation, subtree lifecycle and field validation;
+conditions alone lack reusable state semantics, safe message bounds and a focus
+destination. No new state engine or controller API is needed.
+
+TypeScript: `InterfacePresentationPhase = "loading" | "ready" | "empty" | "error"`;
+`Status.phase?: InterfacePresentationPhase | InterfaceBinding`. Text remains the
+existing string or binding. For phased Status only, supplied text must resolve to
+a string of at most 4096 UTF-16 units, even when hidden. A missing text property
+uses `Loading…`, `Ready.`, `No results.` or `Unable to complete the request.`.
+An explicit empty string is accepted. Missing/invalid phase or supplied bound text
+rejects the whole candidate without revision/DOM changes. Unknown properties,
+unsafe paths, aggregate bounds and existing tree limits remain authoritative.
+
+## JSON contract example
+
+```json
+{
+  "id": "results",
+  "actions": ["retry"],
+  "data": { "phase": "error", "message": "Results are unavailable." },
+  "screen": {
+    "key": "root", "component": "Stack", "children": [
+      {
+        "key": "status", "component": "Status",
+        "phase": { "source": "data", "path": "phase" },
+        "text": { "source": "data", "path": "message" }
+      },
+      {
+        "key": "retry", "component": "Button", "text": "Retry", "action": "retry",
+        "visible": { "binding": { "source": "data", "path": "phase" }, "equals": "error" }
+      }
+    ]
+  }
+}
+```
+
+Mount with `allowedActions: ["retry"]` and an `onEvent` host handler. In that
+handler, authorize the action, accept a loading snapshot using `event.revision`,
+then capture `controller.snapshot().revision` for the operation's completion.
+Submit ready/empty/error with that captured revision. Each data update replaces
+the entire data object, so retain other data explicitly. `ready` and `empty` are
+host decisions; Veil does not infer them from collection length.
+
+## Semantics and lifecycle
+
+Phased Status retains its keyed paragraph, `role=status`, `aria-live=polite` and
+`aria-atomic=true` across transitions. `data-phase` exposes the accepted phase.
+The message is not marked aria-busy, so loading announcements are not deferred.
+Errors are polite informational messages, not automatic urgent alerts. Text is
+rendered as textContent, never HTML. Veil cannot identify credentials in strings:
+the host must supply approved public messages, never raw exception details,
+stack traces or credentials. Object-valued messages are rejected, not serialized.
+Actual live announcements depend on the browser and assistive technology;
+automated accessibility checks do not certify screen reader behavior.
+
+`tabindex=-1` makes phased Status a programmatic focus destination without adding
+a Tab stop. Compatible controls retain identity, focus, selection and user state.
+If an accepted snapshot removes, disables or hides the focused control (including
+an ancestor), focus moves to the first visible phased Status in screen order.
+No move occurs on mount, while focus is outside this interface, when the focused
+control remains eligible, or when there is no visible phased Status. Legacy
+screens retain their existing behavior. Hosts with multiple independent regions
+should keep the intended destination first, or manage focus themselves after the
+update. No automatic focus returns to a formerly hidden control.
+
+Hidden children remain mounted under existing conditional semantics, retain field
+state and cannot dispatch actions or edit state. Hidden fields skip validation.
+Disposal removes listeners and DOM; later updates return false. Phase itself does
+not hide, disable, authorize or validate anything. Tables, Lists, Grid and forms
+compose through existing children, conditions and bindings without special cases.
+All bindings (including hidden collections) must remain valid in every snapshot.
+
+## Host protocol and trust boundary
+
+Use `updateData(fullReplacement, expectedRevision)` or
+`updateDefinition(definition, expectedRevision)`. Every accepted update advances
+the existing revision. Capture the revision **after** accepting loading; submit
+completion with that revision. A stale completion returns false. Any intervening
+edit/update invalidates that token, including unrelated field edits. A host must
+explicitly decide whether to discard or rebase a result; never blindly retry a
+stale write. Revisions prevent older snapshots overwriting newer snapshots only
+when the host supplies the token. Host operation IDs, cancellation, deduplication,
+authorization and idempotency remain host responsibilities.
+
+Retry is an ordinary declared Button action governed by `allowedActions` and
+current visibility/disabled conditions. The host must explicitly allow `retry`,
+authorize the operation and handle its result. No special retry flag, automatic
+retry, timer, network request, promise ownership, job or task queue is introduced.
+As with existing Buttons, dispatch checks current eligibility; phase does not
+provide a gesture revision lock or business authorization. Host callbacks and
+onError diagnostics are never copied into a Status by the renderer.
+
+The capability manifest advances from v4 to v5 with phase vocabulary and behavior
+metadata. Existing definitions and controller/event signatures remain compatible;
+consumers pinning an exact manifest version must accept v5. The separate composed
+application Status contract is unchanged.
+
+See `examples/universal/async-presentation.mjs` for JSON and the host revision
+protocol. v0.5.0 is an unpublished candidate ready for release qualification only
+after verification, not a release.