@veil-runtime/ui 0.1.0 → 0.4.0

package/dist/interface.js

@@ -0,0 +1,524 @@
+import { assertBoundedData, assertSafeKey, copyData } from "./validation-safety.js";
+import { attachInterfaceRenderers, detachInterfaceRenderers } from "./interface-transaction.js";
+const identifier = /^[A-Za-z][A-Za-z0-9._-]{0,127}$/;
+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 },
+    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" },
+    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 },
+    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"]);
+/** 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 } });
+}
+const plain = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const exact = (value, allowed) => {
+    for (const key of Object.keys(value))
+        if (!allowed.has(key))
+            throw new Error(`Unknown interface property: ${key}`);
+};
+const name = (value) => typeof value === "string" && identifier.test(value);
+const scalar = (value) => value === null || typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value));
+function binding(value) {
+    if (!plain(value))
+        throw new Error("Invalid binding");
+    exact(value, new Set(["source", "path"]));
+    if ((value.source !== "data" && value.source !== "state") || !name(value.path))
+        throw new Error("Invalid binding");
+    for (const part of value.path.split("."))
+        assertSafeKey(part);
+}
+function valueAt(source, path) {
+    let value = source;
+    for (const part of path.split("."))
+        value = plain(value) && Object.hasOwn(value, part) ? value[part] : undefined;
+    return value;
+}
+function visitNodes(node, callback) {
+    callback(node);
+    for (const child of node.children ?? [])
+        visitNodes(child, callback);
+}
+function validateBindings(definition, data, state) {
+    visitNodes(definition.screen, (node) => {
+        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)))
+                throw new Error("Invalid or oversized table rows");
+            for (const row of rows)
+                for (const col of 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))))
+                throw new Error("Invalid or oversized list items");
+        }
+        if (isInterfaceField(node)) {
+            const current = valueAt(state, node.binding.path);
+            if (current !== undefined && !scalar(current))
+                throw new Error("Invalid input state");
+        }
+    });
+}
+/** A definition owns its state shape. Retain values only for unchanged input identities. */
+function retainedState(previous, next, oldState) {
+    const state = copyData(next.state ?? {});
+    if (previous.id !== next.id)
+        return state;
+    const inputs = new Map();
+    visitNodes(previous.screen, (node) => { if (isInterfaceField(node))
+        inputs.set(node.key, node); });
+    visitNodes(next.screen, (node) => {
+        if (!isInterfaceField(node))
+            return;
+        const old = inputs.get(node.key);
+        if (!old || old.component !== node.component || old.inputType !== node.inputType || old.binding?.path !== node.binding?.path)
+            return;
+        const path = node.binding.path;
+        const oldValue = valueAt(oldState, path);
+        const defaultValue = valueAt(state, path);
+        if (!scalar(oldValue) || defaultValue === undefined || typeof oldValue !== typeof defaultValue)
+            return;
+        const parts = path.split(".");
+        let target = state;
+        for (const part of parts.slice(0, -1)) {
+            if (!plain(target[part]))
+                return;
+            target = target[part];
+        }
+        target[parts.at(-1)] = oldValue;
+    });
+    return state;
+}
+export function defineInterface(definition) { return definition; }
+/** Validate untrusted structured data before creating a controller or mounting it. */
+export function validateInterfaceDefinition(value, components = []) {
+    assertBoundedData(value);
+    if (!plain(value))
+        throw new Error("Invalid interface definition");
+    exact(value, new Set(["id", "screen", "actions", "data", "state"]));
+    if (!name(value.id) || !plain(value.screen))
+        throw new Error("Invalid interface identity or screen");
+    for (const key of ["data", "state"])
+        if (value[key] !== undefined && !plain(value[key]))
+            throw new Error(`Invalid ${key}`);
+    if (value.actions !== undefined && (!Array.isArray(value.actions) || value.actions.some((action) => !name(action)) || new Set(value.actions).size !== value.actions.length))
+        throw new Error("Invalid actions");
+    const actions = (value.actions ?? []);
+    if (components.some((component) => !name(component) || builtins.has(component)) || new Set(components).size !== components.length)
+        throw new Error("Invalid component registry");
+    const known = new Set([...builtins, ...components]);
+    const keys = new Set();
+    let count = 0;
+    function visit(node, depth) {
+        if (!plain(node) || depth > 16 || ++count > 512)
+            throw new Error("Interface tree limit exceeded");
+        exact(node, nodeKeys);
+        if (!name(node.key) || keys.has(node.key))
+            throw new Error("Invalid or duplicate node key");
+        keys.add(node.key);
+        if (typeof node.component !== "string" || !known.has(node.component))
+            throw new Error(`Unknown component: ${String(node.component)}`);
+        if (builtins.has(node.component)) {
+            const spec = vocabulary[node.component];
+            for (const property of Object.keys(node))
+                if (!spec.properties.includes(property))
+                    throw new Error(`Unsupported ${node.component} property: ${property}`);
+            for (const property of spec.required)
+                if (node[property] === undefined)
+                    throw new Error(`${node.component} needs ${property}`);
+        }
+        if (node.text !== undefined) {
+            if (typeof node.text === "string") {
+                if (node.text.length > 4096)
+                    throw new Error("Text limit exceeded");
+            }
+            else
+                binding(node.text);
+        }
+        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");
+            validateCondition(node.disabled);
+        }
+        for (const field of ["label", "ariaLabel"])
+            if (node[field] !== undefined && (typeof node[field] !== "string" || node[field].length > 256))
+                throw new Error(`Invalid ${field}`);
+        if (node.action !== undefined && (!name(node.action) || !actions.includes(node.action)))
+            throw new Error("Action is not declared by the host");
+        if (node.inputType !== undefined && !["text", "number", "checkbox"].includes(node.inputType))
+            throw new Error("Invalid input type");
+        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)
+                throw new Error("Invalid select options");
+            const values = new Set();
+            for (const option of node.options) {
+                if (!plain(option))
+                    throw new Error("Invalid option");
+                exact(option, new Set(["value", "label"]));
+                if (typeof option.value !== "string" || option.value.length > 256 || typeof option.label !== "string" || option.label.length > 256 || values.has(option.value))
+                    throw new Error("Invalid option");
+                values.add(option.value);
+            }
+        }
+        if (node.validation !== undefined) {
+            if (!isInterfaceField(node) || !plain(node.validation))
+                throw new Error("Invalid validation");
+            exact(node.validation, new Set(["required", "minLength", "maxLength", "min", "max"]));
+            const rules = node.validation;
+            if (rules.required !== undefined && typeof rules.required !== "boolean")
+                throw new Error("Invalid required rule");
+            for (const key of ["minLength", "maxLength", "min", "max"])
+                if (rules[key] !== undefined && (typeof rules[key] !== "number" || !Number.isFinite(rules[key])))
+                    throw new Error("Invalid validation bound");
+            for (const key of ["minLength", "maxLength"])
+                if (rules[key] !== undefined && (!Number.isInteger(rules[key]) || rules[key] < 0 || rules[key] > 4096 || node.inputType === "number" || node.inputType === "checkbox"))
+                    throw new Error("Invalid length rule");
+            if ((rules.min !== undefined || rules.max !== undefined) && (node.component !== "Input" || node.inputType !== "number"))
+                throw new Error("Numeric rules require number input");
+            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))
+                throw new Error("Invalid table columns");
+        }
+        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))
+            throw new Error("Button needs an action and text");
+        if (node.component === "Table" && (!node.binding || !node.columns))
+            throw new Error("Table needs rows and columns");
+        if (node.component !== "Button" && node.action !== undefined)
+            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))))
+            throw new Error("Invalid children");
+        for (const child of node.children ?? [])
+            visit(child, depth + 1);
+    }
+    visit(value.screen, 0);
+    validateBindings(value, (value.data ?? {}), (value.state ?? {}));
+}
+export function createInterfaceController(definition, options = {}) {
+    const components = options.components ?? [];
+    validateInterfaceDefinition(definition, components);
+    if (options.allowedActions && definition.actions?.some((action) => !options.allowedActions.includes(action)))
+        throw new Error("Action is not allowed by host");
+    let current = copyData(definition);
+    let data = copyData(definition.data ?? {});
+    let state = copyData(definition.state ?? {});
+    validateBindings(current, data, state);
+    let revision = 0;
+    let disposed = false;
+    let dispatching = false;
+    let emitting = false;
+    let pending = false;
+    let updating = false;
+    const listeners = new Set();
+    const participants = new Set();
+    const copySnapshot = (value) => ({
+        definition: copyData(value.definition), data: copyData(value.data), state: copyData(value.state), revision: value.revision,
+    });
+    const snapshot = () => copySnapshot({ definition: current, data, state, revision });
+    const report = (error) => { try {
+        options.onError?.(error);
+    }
+    catch { /* Error reporting must not enter the interface runtime. */ } };
+    const emit = () => {
+        if (emitting) {
+            pending = true;
+            return;
+        }
+        emitting = true;
+        try {
+            let passes = 0;
+            do {
+                pending = false;
+                const accepted = snapshot();
+                for (const listener of listeners) {
+                    try {
+                        listener(copySnapshot(accepted));
+                    }
+                    catch (error) {
+                        report(error);
+                    }
+                    if (revision !== accepted.revision) {
+                        pending = true;
+                        break;
+                    }
+                }
+                if (++passes >= 32 && pending) {
+                    report(new Error("Interface update loop limit exceeded"));
+                    pending = false;
+                    break;
+                }
+            } while (pending && !disposed);
+        }
+        finally {
+            emitting = false;
+        }
+    };
+    const accept = (nextDefinition, nextData, nextState) => {
+        if (updating)
+            throw new Error("Interface update already in progress");
+        updating = true;
+        const prepared = [];
+        try {
+            const candidate = { definition: nextDefinition, data: nextData, state: nextState, revision: revision + 1 };
+            for (const renderer of participants)
+                prepared.push(renderer(copySnapshot(candidate)));
+            if (disposed)
+                throw new Error("Interface controller was disposed during update");
+            for (const renderer of prepared) {
+                renderer.commit();
+                if (disposed)
+                    throw new Error("Interface controller was disposed during update");
+            }
+            current = nextDefinition;
+            data = nextData;
+            state = nextState;
+            revision++;
+        }
+        catch (error) {
+            for (const renderer of prepared.reverse()) {
+                try {
+                    renderer.discard();
+                }
+                catch (cleanupError) {
+                    report(cleanupError);
+                }
+            }
+            throw error;
+        }
+        finally {
+            updating = false;
+        }
+        emit();
+    };
+    const controller = {
+        snapshot,
+        updateData(next, expectedRevision) { if (disposed || (expectedRevision !== undefined && expectedRevision !== revision))
+            return false; if (updating)
+            throw new Error("Interface update already in progress"); assertBoundedData(next); if (!plain(next))
+            throw new Error("Invalid data"); const copy = copyData(next); validateBindings(current, copy, state); accept(current, copy, state); return true; },
+        updateDefinition(next, expectedRevision) {
+            if (disposed || (expectedRevision !== undefined && expectedRevision !== revision))
+                return false;
+            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");
+            const copy = copyData(next);
+            const nextData = copyData(copy.data ?? {});
+            const nextState = retainedState(current, copy, state);
+            assertBoundedData(nextState);
+            validateBindings(copy, nextData, nextState);
+            accept(copy, nextData, nextState);
+            return true;
+        },
+        setState(path, value) {
+            if (disposed)
+                return;
+            if (updating)
+                throw new Error("Interface update already in progress");
+            if (!name(path) || !scalar(value))
+                throw new Error("Invalid state update");
+            const parts = path.split(".");
+            for (const part of parts)
+                assertSafeKey(part);
+            const next = copyData(state);
+            let target = next;
+            for (const part of parts.slice(0, -1)) {
+                const child = target[part];
+                if (child !== undefined && !plain(child))
+                    throw new Error("State path is not an object");
+                if (child === undefined)
+                    target[part] = {};
+                target = target[part];
+            }
+            target[parts.at(-1)] = value;
+            assertBoundedData(next);
+            validateBindings(current, data, next);
+            accept(current, data, next);
+        },
+        dispatch(action, source) {
+            if (disposed || dispatching)
+                return;
+            if (updating)
+                throw new Error("Interface update already in progress");
+            if (!current.actions?.includes(action) || !findAction(current.screen, source, action, data, state))
+                throw new Error("Action is not available");
+            let submit = false;
+            visitNodes(current.screen, node => { if (node.key === source)
+                submit = node.validate === true; });
+            if (submit && Object.keys(getInterfaceValidation({ definition: current, data, state })).length)
+                throw new Error("Interface validation failed");
+            dispatching = true;
+            try {
+                const result = options.onEvent?.({ action, source, 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;
+            }
+        },
+        subscribe(listener) { if (disposed)
+            throw new Error("Interface controller is disposed"); listeners.add(listener); try {
+            listener(snapshot());
+        }
+        catch (error) {
+            listeners.delete(listener);
+            throw error;
+        } return () => { listeners.delete(listener); }; },
+        dispose() { disposed = true; listeners.clear(); participants.clear(); detachInterfaceRenderers(controller); },
+    };
+    attachInterfaceRenderers(controller, participants);
+    return controller;
+}
+function findAction(node, key, action, data, state) {
+    if (node.visible && !evaluateInterfaceCondition(node.visible, { data, state }))
+        return false;
+    if (node.disabled && evaluateInterfaceCondition(node.disabled, { data, state }))
+        return false;
+    return (node.key === key && node.action === action) || (node.children?.some((child) => findAction(child, key, action, data, state)) ?? false);
+}
+export function resolveInterfaceBinding(snapshot, bindingValue) {
+    return valueAt(bindingValue.source === "data" ? snapshot.data : snapshot.state, bindingValue.path);
+}
+function validateCondition(value) {
+    let count = 0;
+    function visit(value, depth) {
+        if (!plain(value) || depth > 8 || ++count > 64)
+            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)
+                throw new Error("Invalid condition terms");
+            for (const term of terms)
+                visit(term, depth + 1);
+        }
+        else if (Object.hasOwn(value, "not")) {
+            exact(value, new Set(["not"]));
+            visit(value.not, depth + 1);
+        }
+        else {
+            binding(value.binding);
+            if (Object.hasOwn(value, "equals")) {
+                exact(value, new Set(["binding", "equals"]));
+                if (!scalar(value.equals))
+                    throw new Error("Invalid condition value");
+            }
+            else {
+                exact(value, new Set(["binding", "operator", "value"]));
+                if (!["ne", "lt", "lte", "gt", "gte"].includes(value.operator) || !scalar(value.value))
+                    throw new Error("Invalid condition operator or value");
+                if (value.operator !== "ne" && typeof value.value !== "number")
+                    throw new Error("Numeric condition needs a number");
+            }
+        }
+    }
+    visit(value, 0);
+}
+/** Evaluate a validated condition without coercion or side effects. Missing numeric values never match. */
+export function evaluateInterfaceCondition(condition, snapshot) {
+    if ("all" in condition)
+        return condition.all.every(term => evaluateInterfaceCondition(term, snapshot));
+    if ("any" in condition)
+        return condition.any.some(term => evaluateInterfaceCondition(term, snapshot));
+    if ("not" in condition)
+        return !evaluateInterfaceCondition(condition.not, snapshot);
+    const value = valueAt(snapshot[condition.binding.source], condition.binding.path);
+    if ("equals" in condition)
+        return value === condition.equals;
+    if (condition.operator === "ne")
+        return value !== condition.value;
+    if (typeof value !== "number" || !Number.isFinite(value) || typeof condition.value !== "number")
+        return false;
+    switch (condition.operator) {
+        case "lt": return value < condition.value;
+        case "lte": return value <= condition.value;
+        case "gt": return value > condition.value;
+        case "gte": return value >= condition.value;
+    }
+}
+export function isInterfaceField(node) {
+    return ["Input", "Textarea", "Select"].includes(node.component);
+}
+/** Errors are recomputed from accepted state; hidden 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)) {
+            const value = valueAt(snapshot.state, node.binding.path);
+            const rules = node.validation ?? {};
+            const empty = value === undefined || value === null || value === "";
+            let error = "";
+            if (rules.required && (empty || (node.inputType === "checkbox" && value !== true)))
+                error = "This field is required.";
+            else if (!empty) {
+                if (node.inputType === "number") {
+                    if (typeof value !== "number" || !Number.isFinite(value))
+                        error = "Enter a number.";
+                    else if (rules.min !== undefined && value < rules.min)
+                        error = `Minimum value is ${rules.min}.`;
+                    else if (rules.max !== undefined && value > rules.max)
+                        error = `Maximum value is ${rules.max}.`;
+                }
+                else if (node.inputType === "checkbox") {
+                    if (typeof value !== "boolean")
+                        error = "Enter a boolean.";
+                }
+                else if (typeof value !== "string")
+                    error = "Enter text.";
+                else if (rules.minLength !== undefined && value.length < rules.minLength)
+                    error = `Minimum length is ${rules.minLength}.`;
+                else if (rules.maxLength !== undefined && value.length > rules.maxLength)
+                    error = `Maximum length is ${rules.maxLength}.`;
+                else if (node.component === "Select" && !node.options.some(option => option.value === value))
+                    error = "Choose an available option.";
+            }
+            if (error)
+                errors[node.key] = error;
+        }
+        for (const child of node.children ?? [])
+            visit(child);
+    }
+    visit(snapshot.definition.screen);
+    return errors;
+}

package/dist/presentation-composition.d.ts

@@ -13,8 +13,8 @@ export declare const presentationPlanSchema: z.ZodObject<{
             subtle: "subtle";
         }>;
         density: z.ZodEnum<{
-            compact: "compact";
             comfortable: "comfortable";
+            compact: "compact";
         }>;
         sections: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>;

package/dist/presentation-composition.js

@@ -1,6 +1,8 @@
 import { assertBoundedData, copyData } from "./validation-safety.js";
 import { z } from "zod";
-const groupSchema = z.object({ id: z.string().regex(/^[a-zA-Z0-9_-]+$/).max(48), title: z.string().min(1).max(80).optional(), description: z.string().min(1).max(240).optional(), emphasis: z.enum(["normal", "prominent", "subtle"]), density: z.enum(["comfortable", "compact"]), sections: z.array(z.string().min(1).max(120)).min(1).max(256) }).strict();
+const emphasisSchema = z.enum(["normal", "prominent", "subtle"]);
+const densitySchema = z.enum(["comfortable", "compact"]);
+const groupSchema = z.object({ id: z.string().regex(/^[a-zA-Z0-9_-]+$/).max(48), title: z.string().min(1).max(80).optional(), description: z.string().min(1).max(240).optional(), emphasis: emphasisSchema, density: densitySchema, sections: z.array(z.string().min(1).max(120)).min(1).max(256) }).strict();
 export const presentationPlanSchema = z.object({ title: z.string().min(1).max(100).optional(), description: z.string().min(1).max(240).optional(), groups: z.array(groupSchema).max(12) }).strict();
 export function sectionId(kind, capability) { return kind + ":" + capability; }
 export function buildPresentationEnvelope(primary, related) { return { applicationSurface: primary.capability, sections: [{ id: sectionId("primary", primary.capability), capability: primary.capability, surface: primary.view.surface, label: primary.view.title, required: true, movable: false, groupable: false, defaultOrder: 0 }, ...related.map((section, index) => ({ id: sectionId("related", section.capability), capability: section.capability, surface: section.view?.surface ?? "error", label: section.label, required: true, movable: true, groupable: true, defaultOrder: index + 1 }))], immutable: ["capabilities", "fields", "metrics", "bindings", "workflow", "risk", "actions", "surface semantics", "execution"] }; }

package/docs/API.md

@@ -1,6 +1,8 @@
 # Public API inventory
 
-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 `/inspection`, not paths inside dist.
+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 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.
 
 | Area | Root modules / representative API |
 |---|---|
@@ -14,4 +16,4 @@ 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 |
 
-The qualification consumer exercises both supported subpaths, actual Core capability creation, strict public declarations, and browser bundling. Published export conditions intentionally support ESM import, not direct CommonJS require. Core is a nonoptional peer for the TypeScript capability contract; 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 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.

package/docs/COMPOSITION.md

@@ -0,0 +1,67 @@
+# Application composition foundation (v0.2.0-rc.1)
+
+## Architecture assessment
+
+**Confirmed in v0.1.0:** `ApplicationManifest` and `createUIRegistry` describe Core capability graphs. `deriveUIFields`, rich input schemas, and `validateRichCapabilityInput` supply field metadata and bounded validation. Relationships, actions, transitions, and workflow metadata describe possible interactions. The package does not render, own client state, or call a host operation. The React laboratory is outside the published package. The v0.1.0 Git tag exists and `npm view @veil-runtime/ui@0.1.0 version` confirms npm publication; package metadata and documentation call it a Developer Preview. The root exports and `/inspection` remain supported.
+
+**New in this branch:** `ComposedApplication` defines one screen tree with a form, field bindings, action IDs, and optional initial values. `createCompositionController` owns one instance's state and submission lifecycle. `mountComposedApplication` renders a native HTML form and subscribes to that controller. Registered DOM components can wrap or extend the tree. These are separate from `ApplicationManifest`; neither replaces the capability graph.
+
+The new architecture is deliberately one-screen and one-level of form state. A composed definition is plain bounded data. It holds no executable code; handlers and custom components are registered separately by trusted host code. The controller snapshots the definition, validates all fields before action execution, passes a copied input to a handler, prevents duplicate submissions, and exposes copied state snapshots. The host owns the handler's authorization, transport, persistence, result reconciliation, and server validation. The mount disposer removes DOM listeners and its subscription. Call `controller.dispose()` when the application instance is finished; pending handler results are ignored, and the host remains responsible for cancelling its own network request if needed.
+
+## Install and use
+
+`@veil-runtime/core` is an optional peer for this API. New composition consumers may install only `@veil-runtime/ui`; existing Core-based graph APIs continue to work when Core is installed. The package remains ESM with Node 24+ for server-side use. Use a browser bundler for the DOM entry point.
+
+```ts
+import { createCompositionController, defineComposedApplication } from '@veil-runtime/ui/composition';
+import { mountComposedApplication } from '@veil-runtime/ui/dom';
+
+const definition = defineComposedApplication({
+  id: 'entry', title: 'Treatment entry',
+  fields: { lot: { type: 'string', required: true, description: 'Lot', minLength: 2 } },
+  actions: ['save'],
+  screen: { component: 'Form', children: [
+    { component: 'Field', field: 'lot' },
+    { component: 'Submit', action: 'save', text: 'Save' },
+    { component: 'Status' },
+  ] },
+});
+const controller = createCompositionController(definition, {
+  save: async (input) => { await myAuthorizedOperation(input); return { ok: true }; },
+});
+const dispose = mountComposedApplication(document.getElementById('app')!, controller);
+// When finished with this instance:
+dispose();
+controller.dispose();
+```
+
+The complete browser example is in [`examples/composed`](../examples/composed). From the repository root, build the package, run `node packages/ui/examples/composed/build.mjs`, then serve `packages/ui/examples/composed` with any static HTTP server. Its action is mocked: lot `FAIL` returns `{ ok: false }`, while other valid entries succeed. The bundle is generated and is not source control input. With Chrome installed, `npm --workspace @veil-runtime/ui run test:browser` checks mobile layout, field errors, Enter-key submission, success, and failure.
+
+## Contracts
+
+Built-in components are `Stack`, `Form`, `Field`, `Submit`, `Text`, and `Status`. The schema requires every declared field and action to appear once. Fields and submits must be inside a form; nested forms are rejected. `Field` uses the existing rich input field vocabulary for labels, constraints, and control choice. Primitive fields, dates, multiline text, and finite enums are supported. Structured object and array fields require future work; they are rejected in this renderer. `setField` updates one value and emits a snapshot. `submit` validates the complete input and invokes only its registered handler. The handler must return exactly `{ ok: true }` or `{ ok: false }`; malformed results, rejection, and thrown errors fail safely. States are `idle`, `submitting`, `success`, and `error`. Failures produce a generic public message, without leaking handler details.
+
+To register an application-specific component, include its name when creating the controller and supply the same name to the DOM mount:
+
+```ts
+const components = {
+  Card(_node, { renderChildren }) {
+    const card = document.createElement('section');
+    card.className = 'card';
+    card.append(...renderChildren());
+    return card;
+  },
+};
+const controller = createCompositionController(definition, handlers, Object.keys(components));
+mountComposedApplication(target, controller, components);
+```
+
+The DOM renderer writes strings with `textContent`, uses native label/control association, native submit behavior (including Enter), visible field errors, `aria-invalid`, and a polite live status region. On invalid submission it focuses the first invalid field. It uses a single-column layout with full-width controls. Mounting a new screen into the same target disposes the previous mount after the replacement renders successfully; a failed replacement leaves the prior screen mounted. The caller still owns the controller and must dispose it separately. Host CSS controls theme and may strengthen contrast and focus styles. Custom renderers are trusted code and must implement their own accessibility and escaping.
+
+Untrusted definitions and inputs must be byte-limited before decoding. The library then applies the v0.1.0 bounded-data rules and rejects unknown components, invalid bindings, duplicate fields/actions, unsafe keys, and invalid initial values. Schema validation is not authorization or server-side business validation. Avoid rendering or running untrusted custom component code.
+
+## Core boundary and compatibility
+
+Core integration is an action-handler choice. A host may call its authorized Core operation in `save`; the composition package does not import Core at runtime, construct Core capabilities, or change Core's policies. The server must revalidate input and enforce authorization independently. Existing v0.1.0 root exports, `/inspection`, graph behavior, and deterministic validation remain available. The new `/composition` and `/dom` subpaths let an independent TypeScript consumer avoid Core declarations. The root declaration surface still includes legacy Core-based types and therefore still requires Core for strict type-checking of legacy imports.
+
+This foundation does not provide navigation, nested or repeating forms, asynchronous field validation, conditional visibility, persistence, a drag-and-drop builder, backend APIs, or automatic Core mapping. Chromium mobile and desktop smoke checks cover labels, focus, errors, keyboard submission, escaping and remounting. Firefox, WebKit, and assistive technology behavior remain unverified. A release candidate requires maintainer review of compatibility and security evidence.

package/docs/DECISIONS.md

@@ -9,7 +9,7 @@ Baseline: commit `4c073681e69ef5e323e5ba1a0ff11b4e93898eac`, Astra audit dated 2
 5. Real calendar dates/UTC instants are required across backend and field validators. Format-only acceptance of impossible dates is intentionally removed. Existing schema vocabulary and signatures remain intact.
 6. Compiler output has no source/declaration maps, avoiding references to omitted source files. Build manifests fingerprint the source, build scripts, package metadata, compiler configuration and outputs. Packing builds and verifies; artifacts and legal files are inspected in a clean consumer. Repeated tarball bytes must match.
 7. LICENSE/NOTICE apply to this independent package. No third-party dependency is bundled in dist; dependency licenses remain in their own packages. Production licenses are inventoried separately from laboratory tooling, with an explicit allowlist that fails on an unreviewed license.
-8. Publication enablement removes `private: true` while retaining the failing `prepublishOnly` guard against source-directory publication. Only an exact qualified tarball is eligible for separately authorized publication; npm does not run directory lifecycle hooks for a tarball. Public npm access and the `preview` tag are explicit defaults. Qualification requires the public metadata, verifies directory refusal and performs a tarball-only dry-run with matching integrity. Neither qualification nor CI publishes or supplies publication credentials. The maintainer must approve the final SHA-256 and release action explicitly.
+8. Publication enablement removes `private: true` while retaining the failing `prepublishOnly` guard against source-directory publication. Only an exact qualified tarball is eligible for separately authorized publication; npm does not run directory lifecycle hooks for a tarball. Public npm access was the initial default, with the `preview` tag for release candidates. The stable 0.4.0 metadata sets `latest`. Qualification requires the public metadata, verifies directory refusal and performs a tarball-only dry-run with matching integrity. Neither qualification nor CI publishes or supplies publication credentials. The maintainer must approve the final SHA-256 and release action explicitly.
 
 Strict output checks exposed previously undeclared lab results. Required compatibility-only fixes now return explicit public DTOs for Orders, Tickets, and Tasks; history remains available through order.history instead of the undeclared order.get.history field. No validator exception was added. A targeted output-contract regression covers the adapters.