@veil-runtime/ui 0.1.0 → 0.3.0

package/dist/interface.d.ts

@@ -0,0 +1,196 @@
+export type InterfaceValue = string | number | boolean | null;
+export interface InterfaceBinding {
+    source: "data" | "state";
+    path: string;
+}
+export interface InterfaceCondition {
+    binding: InterfaceBinding;
+    equals: InterfaceValue;
+}
+export interface InterfaceColumn {
+    key: string;
+    label: string;
+}
+export interface InterfaceNode {
+    key: string;
+    component: string;
+    children?: InterfaceNode[];
+    text?: string | InterfaceBinding;
+    binding?: InterfaceBinding;
+    visible?: InterfaceCondition;
+    action?: string;
+    label?: string;
+    inputType?: "text" | "number" | "checkbox";
+    columns?: InterfaceColumn[];
+    ariaLabel?: string;
+}
+export interface InterfaceDefinition {
+    id: string;
+    screen: InterfaceNode;
+    actions?: string[];
+    data?: Record<string, unknown>;
+    state?: Record<string, unknown>;
+}
+/** Use `satisfies BuiltinInterfaceDefinition` for compile-time checks on JSON-only built-in screens. */
+type BuiltinBase = Pick<InterfaceNode, "key" | "visible" | "ariaLabel">;
+export type BuiltinInterfaceNode = (BuiltinBase & {
+    component: "Stack" | "Row";
+    children?: BuiltinInterfaceNode[];
+}) | (BuiltinBase & {
+    component: "Text" | "Status";
+    text?: string | InterfaceBinding;
+}) | (BuiltinBase & {
+    component: "Heading";
+    text: string | InterfaceBinding;
+}) | (BuiltinBase & {
+    component: "Input";
+    label: string;
+    binding: InterfaceBinding & {
+        source: "state";
+    };
+    inputType?: "text" | "number" | "checkbox";
+}) | (BuiltinBase & {
+    component: "Button";
+    text: string | InterfaceBinding;
+    action: string;
+}) | (BuiltinBase & {
+    component: "Table";
+    binding: InterfaceBinding;
+    columns: InterfaceColumn[];
+}) | (BuiltinBase & {
+    component: "List";
+    binding: InterfaceBinding;
+});
+export type BuiltinInterfaceDefinition = Omit<InterfaceDefinition, "screen"> & {
+    screen: BuiltinInterfaceNode;
+};
+export interface InterfaceEvent {
+    action: string;
+    source: string;
+    state: Record<string, unknown>;
+    revision: number;
+}
+export interface InterfaceSnapshot {
+    definition: InterfaceDefinition;
+    data: Record<string, unknown>;
+    state: Record<string, unknown>;
+    revision: number;
+}
+export interface InterfaceController {
+    snapshot(): InterfaceSnapshot;
+    updateData(data: Record<string, unknown>, expectedRevision?: number): boolean;
+    updateDefinition(definition: InterfaceDefinition, expectedRevision?: number): boolean;
+    setState(path: string, value: InterfaceValue): void;
+    dispatch(action: string, source: string): void;
+    subscribe(listener: (snapshot: InterfaceSnapshot) => void): () => void;
+    dispose(): void;
+}
+/** JSON-safe description of the built-in vocabulary. Host extensions are trusted code and are never advertised here. */
+export declare function getInterfaceCapabilities(): {
+    version: number;
+    components: {
+        readonly Stack: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "children"];
+            readonly required: readonly [];
+            readonly children: true;
+            readonly event: null;
+        };
+        readonly Row: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "children"];
+            readonly required: readonly [];
+            readonly children: true;
+            readonly event: null;
+        };
+        readonly Text: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "text"];
+            readonly required: readonly [];
+            readonly children: false;
+            readonly event: null;
+        };
+        readonly Heading: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "text"];
+            readonly required: readonly ["text"];
+            readonly children: false;
+            readonly event: null;
+        };
+        readonly Status: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "text"];
+            readonly required: readonly [];
+            readonly children: false;
+            readonly event: null;
+        };
+        readonly Input: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "label", "binding", "inputType"];
+            readonly required: readonly ["label", "binding"];
+            readonly children: false;
+            readonly event: "state change";
+        };
+        readonly Button: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "text", "action"];
+            readonly required: readonly ["text", "action"];
+            readonly children: false;
+            readonly event: "action";
+        };
+        readonly Table: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "binding", "columns"];
+            readonly required: readonly ["binding", "columns"];
+            readonly children: false;
+            readonly event: null;
+        };
+        readonly List: {
+            readonly properties: readonly ["key", "component", "visible", "ariaLabel", "binding"];
+            readonly required: readonly ["binding"];
+            readonly children: false;
+            readonly event: null;
+        };
+    };
+    bindings: {
+        sources: string[];
+        path: string;
+        missing: string;
+        visibility: string;
+    };
+    propertyTypes: {
+        key: string;
+        component: string;
+        children: string;
+        text: string;
+        binding: string;
+        visible: string;
+        action: string;
+        label: string;
+        inputType: string[];
+        columns: string;
+        ariaLabel: string;
+    };
+    events: {
+        action: {
+            fields: string[];
+            declaration: string;
+        };
+        state: {
+            type: string;
+            source: string;
+        };
+    };
+    limits: {
+        treeDepth: number;
+        nodes: number;
+        textLength: number;
+        tableRows: number;
+        tableColumns: number;
+        listItems: number;
+        transportBytes: number;
+    };
+};
+export declare function defineInterface<const T extends InterfaceDefinition>(definition: T): T;
+/** Validate untrusted structured data before creating a controller or mounting it. */
+export declare function validateInterfaceDefinition(value: unknown, components?: readonly string[]): asserts value is InterfaceDefinition;
+export declare function createInterfaceController(definition: InterfaceDefinition, options?: {
+    components?: readonly string[];
+    allowedActions?: readonly string[];
+    onEvent?: (event: InterfaceEvent) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+}): InterfaceController;
+export declare function resolveInterfaceBinding(snapshot: InterfaceSnapshot, bindingValue: InterfaceBinding): unknown;
+export {};

package/dist/interface.js

@@ -0,0 +1,375 @@
+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"], required: ["label", "binding"], children: false, event: "state change" },
+    Button: { properties: [...commonProperties, "text", "action"], 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"]);
+/** 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" },
+        propertyTypes: { key: "identifier", component: "component name", children: "node array", text: "string or binding", binding: "binding", visible: "{binding,equals:scalar}", 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 (node.component === "Input") {
+            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 (node.component === "Input")
+        inputs.set(node.key, node); });
+    visitNodes(next.screen, (node) => {
+        if (node.component !== "Input")
+            return;
+        const old = inputs.get(node.key);
+        if (!old || 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) {
+            if (!plain(node.visible))
+                throw new Error("Invalid visibility condition");
+            exact(node.visible, new Set(["binding", "equals"]));
+            binding(node.visible.binding);
+            if (!scalar(node.visible.equals))
+                throw new Error("Invalid visibility condition");
+        }
+        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.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 (node.component === "Input" && (!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();
+            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");
+            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 && valueAt(node.visible.binding.source === "data" ? data : state, node.visible.binding.path) !== node.visible.equals)
+        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);
+}

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.