@veil-runtime/ui 0.1.0 → 0.4.0

package/docs/RELEASE-0.3.0-rc.1.md

@@ -0,0 +1,25 @@
+# Veil UI 0.3.0-rc.1 Developer Preview candidate
+
+This is a review candidate, not a publication announcement. Install the qualified tarball by its absolute path with `npm install /absolute/path/veil-runtime-ui-0.3.0-rc.1.tgz`. Node.js 24 or newer and ESM imports are supported. The universal interface engine does not require Veil Core, a frontend framework, or an AI provider. The old capability description APIs use Core types and may use Core in the host.
+
+## Quick start and examples
+
+[UNIVERSAL-INTERFACE.md](UNIVERSAL-INTERFACE.md) contains the smallest TypeScript and JavaScript examples. The packaged [human authored example](../examples/universal/human.mjs) mounts an input, button, and status. The [agent JSON example](../examples/universal/agent.mjs) validates simulated generated definitions and applies controlled updates. The [application composition example](../examples/universal/application.mjs) switches between two screens. These are executable demonstrations, not live model reliability evidence.
+
+## Supported contract
+
+The `/interface` export validates bounded JSON definitions and creates a framework neutral controller. The `/dom` export mounts built-in controls and trusted host components. Built-ins are Stack, Row, Text, Heading, Status, Input, Button, Table, and List. `getInterfaceCapabilities()` describes their names, properties, events, and limits. State is local scalar input state; data is host supplied. Bindings read own-property dot paths. Equality conditions hide nodes. Buttons emit declared action IDs, source keys, state copies, and revision numbers to the host. Definition and data updates preserve compatible state and keyed DOM nodes; failed renderer preparation leaves the accepted revision and view in place. `createMountedInterface()` combines one controller and mount with one disposal call.
+
+The root and `/inspection` exports preserve v0.1.0 capability descriptions. `/composition` and the composition portion of `/dom` preserve v0.2.0 form composition. See [API.md](API.md) for the public inventory and [COMPOSITION.md](COMPOSITION.md) for the form contract. The candidate does not remove those APIs.
+
+## Host responsibilities and limits
+
+Generated definitions are untrusted data. Cap raw model response bytes before JSON parsing; validate each definition; pass an explicit `allowedActions` list; authenticate and authorize every external effect in the host; validate inputs again at the service boundary. Definitions cannot supply JavaScript, custom factory code, raw HTML, URLs, or arbitrary attributes. The DOM adapter writes text through `textContent`. Trusted custom factories execute host code and must clean up timers, subscriptions, and network work using the abort signal and disposal hook. The transaction cannot undo external effects performed by trusted factories during preparation.
+
+The interface vocabulary has no row actions, sorting, repeating templates, navigation router, or form-level validation. Heading is a fixed `h2`; List and Table have bounded simple scalar content. The package is not an autonomous application generator or a production-ready AI framework. Live model reliability, Firefox, WebKit, and screen-reader behavior require separate evidence when those environments are available.
+
+## Migration and release order
+
+Existing v0.1.0 imports remain valid. Hosts using v0.2.0 composition can keep their form controller and add `/interface` separately; the interface tree is a separate contract, not a schema replacement. New agent hosts should send the capability manifest and an explicit list of allowed actions, then validate returned JSON. Direct CommonJS `require()` remains unsupported; dynamic `import()` works from CommonJS.
+
+If this RC passes maintainer review, skip a public v0.2.0 release and make v0.3.0 the next public preview. v0.2.0-rc.1 is qualified but unpublished; publishing it first adds an extra migration and npm version without a user benefit when v0.3.0 retains its APIs. Keep the v0.2.0 checkpoint for provenance and explain in release communication that the composition API first ships publicly with v0.3.0. Do not publish, tag, or merge from this candidate automatically.

package/docs/RELEASE-0.3.0-rc.2.md

@@ -0,0 +1,9 @@
+# Veil UI 0.3.0-rc.2 Developer Preview candidate
+
+This is a review candidate, not a publication announcement. Install only the newly qualified tarball by its absolute path with `npm install /absolute/path/veil-runtime-ui-0.3.0-rc.2.tgz`. The rc.1 checksum does not qualify this corrected source.
+
+The supported public surface and release strategy remain those described for rc.1: Node.js 24+, ESM, the framework-neutral `/interface` engine, `/dom` mounting, the v0.2 composition APIs, and the v0.1 capability-description APIs. Veil Core remains optional for the new interface and composition entry points. See [UNIVERSAL-INTERFACE.md](UNIVERSAL-INTERFACE.md), [COMPOSITION.md](COMPOSITION.md), and [API.md](API.md).
+
+This candidate remediates the pull-request review findings without adding public APIs. It makes composition field access own-property-only and state changes atomic under the snapshot budget; treats definition, data, and state as independently bounded interface resources; corrects conditional layout display; preserves numeric editing, focus, selection, and accessibility updates; keeps IDs and form action routing local and unique; makes replacement mounting failure-safe; and limits model-harness interaction to visible controls.
+
+Generated definitions remain untrusted data. Hosts must cap bytes before parsing, pass explicit action allowlists, authorize effects, validate service inputs, and treat custom components as trusted host code. Live-model reliability, Firefox, WebKit, and actual screen-reader behavior remain outside the available qualification evidence. Do not publish, tag, or merge from this candidate automatically.

package/docs/RELEASE-0.4.0.md

@@ -0,0 +1,9 @@
+# Veil UI 0.4.0 — Developer Preview
+
+Veil UI 0.4.0 adds bounded compound conditions, conditional visibility and Button disabling, validated multi-input submissions, Select, and Textarea to the universal interface API. Existing root, `/inspection`, `/composition`, `/interface`, and `/dom` entry points remain available. The [validated request example](../examples/universal/validated.mjs) demonstrates the new controls. [v0.4.0.md](v0.4.0.md) describes the contract and migration details.
+
+The package is ESM. Node.js 24 or newer is the qualified server baseline; the DOM entry point is qualified in Chrome at mobile and desktop sizes. TypeScript 6.0.2 with strict NodeNext resolution is the qualified type baseline. UI has one runtime dependency, Zod 4.x. Core remains an optional peer with range `^0.4.0`: the interface and DOM APIs do not require it, while capability graph consumers can install Core. Published Core 0.4.0 is the supported and qualified integration baseline. Isolated 0.5.0 and 0.6.0 probes do not expand the declared peer range.
+
+Hosts must bound raw bytes before parsing, allowlist actions, validate inputs again at the service boundary, and authorize effects. Trusted custom components own their external resources. Candidate preparation failures preserve controller state, revision, and mounted view. A commit-phase exception preserves controller state and revision, but cannot generally undo already applied DOM changes or external effects; renderer commits must be nonthrowing. Live-model reliability, Firefox, WebKit, and actual screen-reader behavior are outside the current qualification evidence.
+
+Install the exact qualified tarball for review with `npm install /absolute/path/veil-runtime-ui-0.4.0.tgz`. Publication and the proposed `v0.4.0` Git tag require separate maintainer approval of the final source commit and artifact SHA-256. This document is release text, not a publication announcement.

package/docs/THIRD_PARTY.md

@@ -13,4 +13,4 @@ The npm tarball includes this library's compiled JavaScript/declarations, docume
 
 MIT, Apache-2.0, ISC, BSD-2-Clause, BSD-3-Clause, and 0BSD are the reviewed permissive license categories accepted by the qualification inventory. The [Apache Software Foundation third-party policy, Category A](https://www.apache.org/legal/resolved.html#category-a) lists Apache, MIT/ISC, BSD, and 0BSD as acceptable for inclusion subject to their notice requirements. Here those packages remain external dependencies; their own grants/notices are retained. No compatibility exception or relicensing of dependencies is claimed.
 
-The release gate checks the actual downloaded production graph, including the nonoptional Core peer, against this explicit license list and writes a versioned inventory. It also extracts the exact tarball and checks LICENSE and NOTICE byte-for-byte against the reviewed source files. Neither a package.json license label alone nor root lab dependency metadata is treated as proof of distribution contents.
+The release gate checks the actual downloaded production graph in its Core consumer, as well as UI's runtime dependency independently, against this explicit license list and writes a versioned inventory. Core is an optional peer for UI, but is installed explicitly in that consumer. It also extracts the exact tarball and checks LICENSE and NOTICE byte-for-byte against the reviewed source files. Neither a package.json license label alone nor root lab dependency metadata is treated as proof of distribution contents.

package/docs/UNIVERSAL-INTERFACE.md

@@ -0,0 +1,105 @@
+# Universal interface foundation (0.3.0-rc.2 Developer Preview candidate)
+
+## Smallest working interface
+
+For a single DOM mount, `createMountedInterface` owns the controller and mount together. Its `dispose()` unmounts the DOM and disposes the controller. The lower-level controller and `mountInterface` exports remain available for multiple mounts or another renderer.
+
+```ts
+import { type BuiltinInterfaceDefinition } from '@veil-runtime/ui/interface';
+import { createMountedInterface } from '@veil-runtime/ui/dom';
+
+const definition = { id: 'hello', actions: ['greet'], state: { name: '' }, data: { message: '' },
+  screen: { key: 'root', component: 'Stack', children: [
+    { key: 'title', component: 'Heading', text: 'Greeting' },
+    { key: 'name', component: 'Input', label: 'Name', binding: { source: 'state', path: 'name' } },
+    { key: 'greet', component: 'Button', text: 'Greet', action: 'greet' },
+    { key: 'message', component: 'Status', text: { source: 'data', path: 'message' } },
+  ] } } satisfies BuiltinInterfaceDefinition;
+const ui = createMountedInterface(document.getElementById('app')!, definition, {
+  allowedActions: ['greet'],
+  onEvent(event) { ui.updateData({ message: `Hello ${event.state.name}` }, event.revision); },
+});
+// On teardown: ui.dispose();
+```
+
+JavaScript uses the same calls without `satisfies` or the non-null assertion. `allowedActions` is a host policy; keep it explicit for untrusted definitions. `components` is a map of trusted host factories, so the helper derives the registry names from its keys. Definitions cannot provide factory code.
+
+Definitions are plain JSON data. Import the neutral runtime through `/interface` and the optional native DOM adapter through `/dom`.
+
+```ts
+import { createInterfaceController, defineInterface } from '@veil-runtime/ui/interface';
+import { mountInterface } from '@veil-runtime/ui/dom';
+
+const definition = defineInterface({
+  id: 'hello', actions: ['greet'], state: { name: '' }, data: { message: '' },
+  screen: { key: 'root', component: 'Stack', children: [
+    { key: 'name', component: 'Input', label: 'Name', binding: { source: 'state', path: 'name' } },
+    { key: 'greet', component: 'Button', text: 'Greet', action: 'greet' },
+    { key: 'message', component: 'Text', text: { source: 'data', path: 'message' } },
+  ] },
+});
+const controller = createInterfaceController(definition, {
+  allowedActions: ['greet'],
+  onEvent(event) {
+    if (event.action === 'greet') controller.updateData(
+      { message: `Hello ${event.state.name}` }, event.revision,
+    );
+  },
+});
+const unmount = mountInterface(document.getElementById('app')!, controller);
+// On teardown:
+unmount();
+controller.dispose();
+```
+
+The host owns the controller, mount point, component implementations, event callback, and teardown. Use `updateData` to refresh host data and `updateDefinition` to replace a view. Both accept an optional expected revision and return `false` if it is stale or disposed. Invalid or unrenderable updates throw; the controller and mounted view keep their last accepted revision. `setState` changes local scalar state and throws on rejection. `snapshot` returns isolated copies. The same imports work in JavaScript; omit the TypeScript non-null assertion on `getElementById`.
+
+Every update follows one acceptance path: validate and copy the proposed definition/data/state; derive compatible local state; prepare candidate DOM and custom components for every mount; discard all candidates if any mount fails; otherwise commit DOM, controller values, and revision; finally notify ordinary subscribers. A candidate is not visible through `snapshot()` or subscriptions during preparation. A synchronous reentrant update is rejected; asynchronous responses should pass their expected revision. A rejected update does not increment the revision. Mounted renderers use the controller's internal preparation bridge; hosts do not need a rollback call.
+
+## Architecture and alternatives
+
+The RC's `ComposedApplication` is a good focused form controller: it validates field schemas, submits one action at a time, and protects late results. Its required `Form`/`Field`/`Submit` nesting cannot express arbitrary UI. `InterfaceDefinition` keeps the separation of plain data and trusted host callbacks, and adds a small node tree instead of extending the form schema with unrelated cases. This is a separate public API for broader experiences; composition and v0.1 capability graph APIs remain unchanged.
+
+Nodes have stable unique keys, a component name, and optional children. The built-ins are `Stack`, `Row`, `Text`, `Heading`, `Status`, `Input`, `Button`, `Table`, and `List`. `Stack` and wrapping `Row` nest layouts. `Heading` renders an `h2`; `Status` has a polite live region; `List` renders up to 100 scalar items. `Table` presents up to 100 rows and 20 columns. Text, list, and table values use one path binding from `data` or `state`. An optional equality condition controls visibility. `Input` writes scalar state. `Button` emits `{ action, source, state, revision }`. Host code registers trusted DOM components by passing their names to the controller and implementations to `mountInterface`. Registrations are local to an instance.
+
+`getInterfaceCapabilities()` returns an isolated JSON-safe manifest: component names, allowed and required properties, child composition, events, property types, binding semantics, and limits. The built-in validator uses the same component property lists. An agent host can serialize the manifest alongside its own allowed action IDs, ask a provider-neutral agent for JSON, cap bytes before parsing, and call `validateInterfaceDefinition` before `createMountedInterface` or `updateDefinition`. Component properties that do not belong to a built-in are rejected. `BuiltinInterfaceDefinition` supports TypeScript `satisfies` checks for built-in-only authored screens; the runtime validator remains mandatory for received JSON. The manifest intentionally excludes trusted custom factories and privileged actions. A host may add a trusted component after receiving the generated definition, as the agent demonstration does with `Activity`.
+
+The DOM adapter retains built-in elements by key and component within the same parent. It reorders them without remounting and updates text, labels, tables and visibility in place. An `Input` also requires the same binding path and type; a `Button` requires the same action. This preserves focus and selection on retained inputs. Reparenting, replacing a key, or changing component identity remounts it. The controller retains local input values when the interface id, input key, binding path, and type match and the new state declares a compatible default. A new interface id or removed input resets those values. Host data is replaced by each definition's `data` or by `updateData`; it is never merged with local state. Another adapter can consume snapshots and subscriptions without importing `/dom`.
+
+Custom DOM factories may return an `HTMLElement` for the original contract, or `{ element, update?, dispose? }`. For an update, the adapter prepares a **new detached custom instance**, calls its optional `update` with the candidate snapshot, and swaps it in only after every renderer prepares successfully. This isolates a throwing `update` from the displayed instance. It remounts custom components on accepted updates; built-in keyed nodes remain in place. The factory receives `{ snapshot, renderChildren, signal }`. The signal aborts before `dispose` when a candidate is discarded, an instance is replaced, or the mount is torn down. Use it to cancel subscriptions, timers, fetches, and delayed callbacks. `dispose` must release resources owned by the instance. `renderChildren` may be called once. Trusted factory and update code must validate their own assumptions.
+
+```js
+const components = {
+  Clock(node, { signal }) {
+    const element = document.createElement('span');
+    const timer = setInterval(() => { if (!signal.aborted) element.textContent = new Date().toLocaleTimeString(); }, 1000);
+    return { element, update(next, snapshot) { /* refresh trusted props */ }, dispose() { clearInterval(timer); } };
+  },
+};
+const controller = createInterfaceController(definition, { components: ['Clock'], allowedActions: ['refresh'], onEvent });
+const unmount = mountInterface(target, controller, components);
+// Later: controller.updateData(data); controller.updateDefinition(nextDefinition);
+// Teardown: unmount(); controller.dispose();
+```
+
+Alternatives considered: extending the form schema in place would weaken its focused validation and compatibility; accepting HTML or generated framework code would grant definitions executable behavior; a full virtual DOM or application framework adds scope before use cases justify it. This foundation chooses a bounded tree and explicit event boundary. More complex layout, row actions, repeat templates, validation vocabulary, and navigation state need later designs.
+
+## Trust boundary and limits
+
+Treat model responses as untrusted bytes. The host must cap bytes before `JSON.parse` (the example uses 64 KiB). The runtime rejects cyclic data, accessors, unsafe property names, unsupported values, unknown node properties and components, undeclared actions, excessive depth and size, malformed bindings, table rows over 100, and invalid input state. Interface trees are limited to 512 nodes and depth 16; the underlying transport limit is 1 MiB. Text is assigned with `textContent`, never `innerHTML`. `allowedActions` narrows action IDs accepted from a definition. These checks do not grant authority: the host must authenticate, authorize, validate inputs on the server, and execute external effects. Trusted component code is outside the untrusted definition boundary.
+
+Subscriptions and DOM listeners are removed on disposal. Disposed controllers ignore later data updates; revision checks help hosts reject stale asynchronous responses. Events are delivered synchronously in interaction order with a copy of the current state. Reentrant dispatch is ignored, but repeated later clicks are separate events. The host must deduplicate or serialize effects, check revisions when applying asynchronous results, and authorize every capability independently. Hidden actions cannot be dispatched. Listener feedback is capped at 32 passes per update. Failed DOM preparation calls the mount's `onError` and causes the initiating update to throw. Errors from ordinary subscribers are reported through the controller's `onError` after acceptance and do not reject the update. An input edit rejected during rendering restores its displayed value from accepted state.
+
+The transaction covers Veil-owned controller data and DOM operations under normal DOM ownership. It cannot reverse effects that arbitrary trusted component code performs outside its candidate element. Factories should attach cleanup to their abort signal as soon as they acquire a resource; if a factory throws before returning an instance, Veil can abort the signal but cannot call a `dispose` it never received. Components must not mutate the mounted tree or perform privileged effects during preparation. External code that removes or monkey-patches Veil-owned DOM nodes can break commit assumptions. Report such failures as integration defects.
+
+## Three public API demonstrations
+
+`examples/universal/human.mjs` defines an interactive interface with the single-call mount helper. `agent.mjs` reads the built-in manifest, parses simulated JSON responses, rejects an unknown component, filters data, continues to a summary, and starts over. The host adds a trusted Activity component after parsing; the agent never supplies its implementation. It retains the query and focus, and disposes Activity on removal. `application.mjs` switches between reusable home and detail definitions and displays a list. Build with `node packages/ui/examples/universal/build.mjs`; open `examples/universal/index.html`. `npm --workspace @veil-runtime/ui run test:browser` exercises all three in Chromium at mobile and desktop widths.
+
+## External consumer assessment
+
+`npm --workspace @veil-runtime/ui run verify:consumer` packs twice, compares tarball hashes, installs the packed artifact into separate TypeScript and JavaScript projects offline, and runs six headless scenarios: information, form, structured data, JSON acceptance, event update, and disposal. Core is not installed; the only production dependency is Zod. Before this increment, a one-mount app called `createInterfaceController`, `mountInterface`, then both `unmount()` and `controller.dispose()`; custom component names had to be listed separately from the factory map. The helper reduces these to one creation call, one `dispose()`, and one registry map. The host still supplies an action allowlist, event handling, pre-parse byte limit, and domain authorization. There is no bundled AI provider or framework.
+
+## Release assessment
+
+This is a 0.3.0 release candidate that preserves the qualified 0.2.0 RC APIs. Chromium coverage is available; Firefox, WebKit, screen readers, and framework-specific adapters remain unverified. The `Heading` primitive has a fixed h2 level; richer heading hierarchy, row controls, table sorting, list item templates, and form-level validation are outside this increment. The old RC commit and its tarball remain the reproducible 0.2.0 checkpoint. Publication requires maintainer approval of the exact qualified artifact.

package/docs/v0.4.0.md

@@ -0,0 +1,47 @@
+# v0.4.0 Developer Preview
+
+Version 0.4.0 extends the existing universal interface descriptor. Existing descriptors and controller APIs remain supported. No historical tag is changed.
+
+## Fields and submission
+
+Input, Select, and Textarea accept `validation: { required, minLength, maxLength, min, max }`. Every property is optional. Required is boolean; lengths are integers from 0 to 4096; numeric bounds are finite numbers. Reversed bounds are rejected. Length rules apply to text fields; numeric bounds require Input with inputType number. Checkbox required means true. String lengths count UTF-16 code units. Whitespace is text, not empty.
+
+Missing, null, and empty string are empty. Optional empty fields pass. Nonempty values must match the field type; Select values must be declared options. Validation does not prevent editing invalid intermediate state. `getInterfaceValidation(snapshot)` returns field-keyed errors for visible fields, excluding hidden ancestors. Errors are recomputed after state, data, and definition changes without an extra revision or event.
+
+A Button with `validate: true` validates all visible fields before dispatch. Invalid submission throws `Interface validation failed`, delivers no host event, and does not change state or revision. The DOM click handler isolates the error through onError. Buttons without this flag retain existing behavior, supporting cancel/navigation actions. Hosts must use validated buttons for submission and still authorize and validate requests at their service boundary.
+
+Fields have native labels, required state, aria-invalid, and aria-describedby linked to live field feedback. Errors appear immediately, including initial required errors. Hidden field state is retained but not validated for submission. There is no asynchronous validation or executable rule language.
+
+## Components
+
+```json
+{"key":"kind","component":"Select","label":"Kind","binding":{"source":"state","path":"kind"},"options":[{"value":"supplies","label":"Supplies"}],"validation":{"required":true}}
+```
+
+Select accepts 1–100 unique string values and labels, each at most 256 characters. Empty string denotes no selection. A native empty prompt precedes nonempty options.
+
+```json
+{"key":"notes","component":"Textarea","label":"Details","binding":{"source":"state","path":"notes"},"validation":{"maxLength":1000}}
+```
+
+Both components use scalar state bindings and the existing lifecycle/transaction machinery. State retention requires unchanged definition ID, field key, component, input type, binding path, and a default of the same scalar type. Group related fields with Stack and Heading; no competing form container is introduced.
+
+## Conditions
+
+Legacy `{ "binding": { "source":"state", "path":"name" }, "equals":"Ada" }` remains valid. Comparisons use `{binding, operator, value}` with ne, lt, lte, gt, gte. Numeric comparisons require finite numeric operands and never coerce strings. Missing values fail numeric comparisons; strict inequality against a scalar is true for missing values.
+
+Compose conditions with `{all:[condition,...]}`, `{any:[condition,...]}`, or `{not:condition}`. Each condition tree permits depth 8, 64 nodes, and 1–16 operands per logical array. Unknown properties/operators are rejected. Conditions read own-property data/state bindings only.
+
+All nodes accept visible; Buttons also accept disabled conditions. Hidden ancestors and disabled Buttons prevent direct controller dispatch as well as DOM interaction. Host allowedActions remains independent of conditions.
+
+## Integration and boundaries
+
+Import universal APIs from `@veil-runtime/ui/interface` and DOM APIs from `@veil-runtime/ui/dom`; no Core or AI provider is required. Capability APIs retain legitimate Core types. The optional peer range remains ^0.4.0; isolated 0.5.0/0.6.0 probes are evidence, not a claim that all integration contracts have been qualified.
+
+The existing component allowlist, safe bindings, bounded data/tree limits, text-only rendering, revisions, and atomic candidate rejection remain in force. New fields do not execute actions or network calls. See `examples/universal/validated.mjs` for a validated form, conditional fields, multiple input types, and host-controlled submission. The repository-local universal playground includes it; no external website is changed.
+
+## Compatibility and transaction qualification
+
+The exported `InterfaceCondition` retains the v0.3.0 equality interface with required `binding` and `equals`. `InterfaceConditionExpression` is the expanded union used by visibility, disabling, and the evaluator. Existing interface inheritance and direct equality-binding access remain supported.
+
+Candidate preparation failures leave controller state, revision, and the mounted DOM unchanged. Disposal during preparation or commit rejects controller state advancement and stops subsequent commits. A commit-phase exception preserves controller state/revision and discards prepared candidates in reverse order, but discard is resource cleanup, not a general rollback of already-applied DOM or external side effects. Renderer commits must therefore be nonthrowing; arbitrary commit failures cannot promise cross-renderer visual rollback. This limitation is explicitly tested rather than claimed as full transaction atomicity.

package/examples/composed/app.mjs

@@ -0,0 +1,44 @@
+import { createCompositionController, defineComposedApplication } from '@veil-runtime/ui/composition';
+import { mountComposedApplication } from '@veil-runtime/ui/dom';
+
+const definition = defineComposedApplication({
+  id: 'stock-treatment', title: 'Stock treatment entry',
+  fields: {
+    lot: { type: 'string', required: true, description: 'Stock lot', minLength: 2, maxLength: 40 },
+    treatment: { type: 'string', required: true, description: 'Treatment', enum: ['Clean', 'Inspect', 'Spray'] },
+    quantity: { type: 'number', required: true, description: 'Quantity treated', minimum: 0.01, maximum: 100000 },
+    date: { type: 'string', required: true, description: 'Treatment date', format: 'date' },
+    notes: { type: 'string', required: false, description: 'Notes', format: 'multiline', maxLength: 500 },
+  },
+  actions: ['record'],
+  screen: { component: 'Card', children: [
+    { component: 'Form', children: [
+      { component: 'Text', text: 'Fields marked * are required.' },
+      { component: 'Field', field: 'lot' },
+      { component: 'Field', field: 'treatment' },
+      { component: 'Field', field: 'quantity' },
+      { component: 'Field', field: 'date' },
+      { component: 'Field', field: 'notes' },
+      { component: 'Submit', action: 'record', text: 'Record treatment' },
+      { component: 'Status' },
+    ] },
+  ] },
+});
+
+const components = {
+  Card(_node, { renderChildren }) {
+    const card = document.createElement('section');
+    card.className = 'card';
+    card.append(...renderChildren());
+    return card;
+  },
+};
+
+const controller = createCompositionController(definition, {
+  async record(input) {
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    return { ok: input.lot !== 'FAIL' };
+  },
+}, Object.keys(components));
+
+mountComposedApplication(document.getElementById('app'), controller, components);

package/examples/composed/build.mjs

@@ -0,0 +1,7 @@
+import { build } from 'esbuild';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+await build({ entryPoints: [join(here, 'app.mjs')], outfile: join(here, 'app.bundle.js'), bundle: true, format: 'esm', platform: 'browser', target: 'es2022' });
+console.log('Built examples/composed/app.bundle.js');

package/examples/composed/index.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Veil UI · Treatment entry</title>
+  <style>
+    :root { font: 16px system-ui, sans-serif; color: #172b25; background: #f2f6f2; }
+    * { box-sizing: border-box; }
+    body { margin: 0; padding: clamp(1rem, 4vw, 3rem); }
+    main { max-width: 40rem; margin: auto; }
+    h1 { margin: 0 0 .5rem; font-size: clamp(1.65rem, 5vw, 2.4rem); }
+    .intro { margin: 0 0 1.5rem; color: #42584e; }
+    .card { background: white; border: 1px solid #d5e2d6; border-radius: 1rem; padding: clamp(1rem, 4vw, 2rem); box-shadow: 0 10px 30px #1b3b2310; }
+    input, select, textarea { border: 1px solid #8ca69a; border-radius: .5rem; padding: .65rem .75rem; background: white; color: inherit; }
+    input:focus-visible, select:focus-visible, textarea:focus-visible, button:focus-visible { outline: 3px solid #89b9ed; outline-offset: 2px; }
+    input[aria-invalid="true"], select[aria-invalid="true"] { border-color: #af3737; }
+    .veil-error { color: #9c2929; min-height: 1em; }
+    button { border: 0; border-radius: .55rem; padding: .7rem 1rem; background: #126b43; color: white; font-weight: 700; cursor: pointer; }
+    button:disabled { opacity: .65; cursor: wait; }
+    .veil-status[data-status="error"] { color: #9c2929; }
+    .veil-status[data-status="success"] { color: #126b43; }
+    .hint { font-size: .875rem; color: #42584e; }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>Record stock treatment</h1>
+    <p class="intro">A small declarative Veil UI application. Enter lot <strong>FAIL</strong> to see the mocked operation fail.</p>
+    <div id="app"></div>
+  </main>
+  <script type="module" src="./app.bundle.js"></script>
+</body>
+</html>

package/examples/universal/agent.mjs

@@ -0,0 +1,52 @@
+import { getInterfaceCapabilities } from '@veil-runtime/ui/interface';
+import { createMountedInterface } from '@veil-runtime/ui/dom';
+
+const rows = [{ name: 'Alpha', status: 'Open' }, { name: 'Beta', status: 'Open' }];
+const query = { key: 'query', component: 'Input', label: 'Filter requests', binding: { source: 'state', path: 'query' } };
+const table = { key: 'results', component: 'Table', binding: { source: 'data', path: 'rows' }, columns: [{ key: 'name', label: 'Request' }, { key: 'status', label: 'Status' }] };
+const title = { key: 'title', component: 'Text', text: { source: 'data', path: 'title' } };
+function generated(stage, filtered = rows) {
+  const children = stage === 0
+    ? [title, query, { key: 'filter', component: 'Button', text: 'Filter', action: 'filter' }, table]
+    : stage === 1
+      ? [title, query, { key: 'filter', component: 'Button', text: 'Filter again', action: 'filter' }, table,
+        { key: 'advance', component: 'Button', text: 'Continue', action: 'advance' }]
+      : [title, query, { key: 'summary', component: 'Text', text: 'Review complete' },
+        { key: 'reset', component: 'Button', text: 'Start over', action: 'reset' }];
+  return { id: 'agent', actions: ['filter', 'advance', 'reset'], state: { query: '' },
+    data: { title: stage === 2 ? 'Request summary' : stage === 1 ? 'Filtered requests' : 'Open requests', rows: filtered },
+    screen: { key: 'root', component: 'Stack', children } };
+}
+
+export function mountAgent(target) {
+  const metrics = { events: [], rejected: 0, mounted: 0, disposed: 0, ticks: 0 };
+  const capabilities = getInterfaceCapabilities();
+  if (!capabilities.components.Table || !capabilities.components.Input || !capabilities.events.action) throw new Error('Agent vocabulary unavailable');
+  // Simulate an agent transport: cap the response before parsing, then let Veil validate it.
+  const parse = (value) => { const response = JSON.stringify(value); if (response.length > 65536) throw new Error('Agent response too large'); return JSON.parse(response); };
+  // Trusted host decoration is separate from the JSON vocabulary given to the agent.
+  const decorate = (definition) => ({ ...definition, screen: { ...definition.screen, children: [...definition.screen.children.slice(0, -1), { key: 'activity', component: 'Activity' }, definition.screen.children.at(-1)] } });
+  const controller = createMountedInterface(target, parse(generated(0)), {
+    allowedActions: ['filter', 'advance', 'reset'],
+    components: {
+      Activity() {
+        metrics.mounted++;
+        const element = document.createElement('p'); element.textContent = 'Agent activity';
+        const timer = setInterval(() => { metrics.ticks++; }, 1000);
+        return { element, update() {}, dispose() { clearInterval(timer); metrics.disposed++; } };
+      },
+    },
+    onEvent(event) {
+      metrics.events.push(event.action);
+      if (event.action === 'filter') {
+        // A rejected generated definition leaves the last valid view interactive.
+        try { controller.updateDefinition(parse({ ...generated(1), screen: { key: 'root', component: 'Script' } }), event.revision); }
+        catch { metrics.rejected++; }
+        const filtered = rows.filter((row) => row.name.toLowerCase().includes(String(event.state.query).toLowerCase()));
+        controller.updateDefinition(decorate(parse(generated(1, filtered))), event.revision);
+      } else if (event.action === 'advance') controller.updateDefinition(parse(generated(2)), event.revision);
+      else if (event.action === 'reset') controller.updateDefinition(parse(generated(0)), event.revision);
+    },
+  });
+  return { controller, metrics, capabilities, dispose() { controller.dispose(); } };
+}

package/examples/universal/application.mjs

@@ -0,0 +1,16 @@
+import { createMountedInterface } from '@veil-runtime/ui/dom';
+
+export function mountApplication(target) {
+  const home = { id: 'application', actions: ['details'], data: { steps: ['Open details', 'Return home'] }, screen: { key: 'root', component: 'Stack', children: [
+    { key: 'heading', component: 'Heading', text: 'Application home' },
+    { key: 'steps', component: 'List', binding: { source: 'data', path: 'steps' } },
+    { key: 'details', component: 'Button', action: 'details', text: 'View details' },
+  ] } };
+  const details = { id: 'application', actions: ['back'], screen: { key: 'root', component: 'Stack', children: [
+    { key: 'heading', component: 'Heading', text: 'Item details' },
+    { key: 'description', component: 'Text', text: 'A bounded two-view workflow.' },
+    { key: 'back', component: 'Button', action: 'back', text: 'Back' },
+  ] } };
+  const controller = createMountedInterface(target, home, { allowedActions: ['details', 'back'], onEvent(event) { controller.updateDefinition(event.action === 'details' ? details : home, event.revision); } });
+  return { controller, dispose() { controller.dispose(); } };
+}

package/examples/universal/build.mjs

@@ -0,0 +1,6 @@
+import { build } from 'esbuild';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const here = dirname(fileURLToPath(import.meta.url));
+await build({ entryPoints: [join(here, 'main.mjs')], outfile: join(here, 'main.bundle.js'), bundle: true, format: 'esm', platform: 'browser', target: 'es2022' });
+console.log('Built examples/universal/main.bundle.js');

package/examples/universal/human.mjs

@@ -0,0 +1,16 @@
+import { defineInterface } from '@veil-runtime/ui/interface';
+import { createMountedInterface } from '@veil-runtime/ui/dom';
+
+export function mountHuman(target) {
+  const definition = defineInterface({
+    id: 'human', actions: ['show'], state: { selected: 'All' }, data: { summary: '3 items available' },
+    screen: { key: 'root', component: 'Stack', children: [
+      { key: 'heading', component: 'Heading', text: 'Human-authored inventory' },
+      { key: 'selection', component: 'Input', label: 'Category', binding: { source: 'state', path: 'selected' } },
+      { key: 'show', component: 'Button', action: 'show', text: 'Show category' },
+      { key: 'summary', component: 'Status', text: { source: 'data', path: 'summary' } },
+    ] },
+  });
+  const controller = createMountedInterface(target, definition, { allowedActions: ['show'], onEvent(event) { controller.updateData({ summary: `Showing ${event.state.selected}` }, event.revision); } });
+  return { controller, dispose() { controller.dispose(); } };
+}

package/examples/universal/index.html

@@ -0,0 +1,4 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Veil UI universal foundation</title>
+<style>body{font:16px system-ui;max-width:64rem;margin:auto;padding:1rem;color:#172b25}h1{overflow-wrap:anywhere}main{display:grid;gap:1.5rem;min-width:0}.card,.demo{border:1px solid #bbcbbf;border-radius:.7rem;padding:1rem;min-width:0;overflow-wrap:anywhere}button,input{font:inherit;padding:.6rem;max-width:100%;box-sizing:border-box}button:focus-visible,input:focus-visible{outline:3px solid #2675b8;outline-offset:2px}table{border-collapse:collapse;width:100%;max-width:100%}td,th{text-align:left;border-bottom:1px solid #bbcbbf;padding:.5rem}@media(max-width:480px){body{padding:.5rem}}</style></head>
+<body><h1>Veil UI: one foundation, three experiences</h1><main><section class="demo"><h2>Human authored</h2><div id="human"></div></section><section class="demo"><h2>Simulated agent</h2><div id="agent"></div></section><section class="demo"><h2>Application composition</h2><div id="application"></div></section></main><script type="module" src="./main.bundle.js"></script></body></html>

package/examples/universal/main.mjs

@@ -0,0 +1,11 @@
+import { mountHuman } from './human.mjs';
+import { mountAgent } from './agent.mjs';
+import { mountApplication } from './application.mjs';
+const human = mountHuman(document.getElementById('human'));
+const agent = mountAgent(document.getElementById('agent'));
+const application = mountApplication(document.getElementById('application'));
+globalThis.veilExamples = { human, agent, application };
+
+import { mountValidated } from './validated.mjs';
+const validatedTarget = document.createElement('section'); validatedTarget.id = 'validated'; document.body.append(validatedTarget);
+globalThis.veilValidated = mountValidated(validatedTarget);

package/examples/universal/validated.mjs

@@ -0,0 +1,21 @@
+import { createMountedInterface } from '../../dist/dom.js';
+export const validatedDefinition = {
+  id: 'request', actions: ['submit'], state: { name: '', kind: '', notes: '', quantity: 1 },
+  screen: { key: 'request', component: 'Stack', children: [
+    { key: 'title', component: 'Heading', text: 'Request supplies' },
+    { key: 'name', component: 'Input', label: 'Your name', binding: { source: 'state', path: 'name' }, validation: { required: true, minLength: 2, maxLength: 80 } },
+    { key: 'kind', component: 'Select', label: 'Request type', binding: { source: 'state', path: 'kind' }, options: [{ value: 'supplies', label: 'Supplies' }, { value: 'other', label: 'Other' }], validation: { required: true } },
+    { key: 'quantity', component: 'Input', inputType: 'number', label: 'Quantity', binding: { source: 'state', path: 'quantity' }, validation: { required: true, min: 1, max: 20 }, visible: { binding: { source: 'state', path: 'kind' }, equals: 'supplies' } },
+    { key: 'notes', component: 'Textarea', label: 'Details', binding: { source: 'state', path: 'notes' }, validation: { required: true, maxLength: 1000 }, visible: { binding: { source: 'state', path: 'kind' }, equals: 'other' } },
+    { key: 'submit', component: 'Button', text: 'Submit request', action: 'submit', validate: true },
+    { key: 'feedback', component: 'Status', text: { source: 'data', path: 'message' } },
+  ] },
+};
+export function mountValidated(target) {
+  const controller = createMountedInterface(target, validatedDefinition, {
+    allowedActions: ['submit'],
+    onEvent(event) { controller.updateData({ message: `Received request from ${event.state.name}.` }); },
+    onError() { /* Field feedback explains invalid submissions; hosts may also log errors. */ },
+  });
+  return controller;
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@veil-runtime/ui",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "tag": "preview"
+    "tag": "latest"
   },
   "type": "module",
-  "description": "Veil UI \u2014 Deterministic Composition Engine (Developer Preview). Framework-neutral interface descriptions from governed capabilities.",
+  "description": "Veil UI universal interface foundation and deterministic capability descriptions (Developer Preview).",
   "files": [
     "dist",
     "README.md",
@@ -15,6 +15,8 @@
     "SECURITY.md",
     "docs",
     "examples/standalone",
+    "examples/composed",
+    "examples/universal",
     "LICENSE",
     "NOTICE"
   ],
@@ -28,6 +30,18 @@
     "./inspection": {
       "types": "./dist/composition-inspection.d.ts",
       "import": "./dist/composition-inspection.js"
+    },
+    "./dom": {
+      "types": "./dist/dom.d.ts",
+      "import": "./dist/dom.js"
+    },
+    "./composition": {
+      "types": "./dist/composition.d.ts",
+      "import": "./dist/composition.js"
+    },
+    "./interface": {
+      "types": "./dist/interface.d.ts",
+      "import": "./dist/interface.js"
     }
   },
   "sideEffects": false,
@@ -35,9 +49,11 @@
     "build": "node scripts/build.mjs",
     "build:no-dom": "node scripts/build.mjs",
     "test": "node --import tsx --test --test-isolation=none test/*.test.ts test/*.test.mjs",
+    "test:browser": "node examples/composed/build.mjs && node test/browser-composition.mjs && node examples/universal/build.mjs && node test/browser-interface.mjs",
     "check:boundary": "node scripts/check-boundary.mjs",
     "typecheck:test": "tsc -p tsconfig.test.json",
     "verify:dist": "node scripts/verify-dist.mjs",
+    "verify:consumer": "node scripts/verify-universal-consumer.mjs",
     "prepack": "npm run build && npm run verify:dist && npm run check:boundary",
     "prepublishOnly": "node scripts/publication-hold.mjs",
     "check": "npm run build && npm run typecheck:test && npm test && npm run verify:dist && npm run check:boundary"
@@ -45,6 +61,11 @@
   "peerDependencies": {
     "@veil-runtime/core": "^0.4.0"
   },
+  "peerDependenciesMeta": {
+    "@veil-runtime/core": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "zod": "^4.6.6"
   },