@veil-runtime/ui 0.1.0 → 0.3.0

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/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.3.0.md

@@ -0,0 +1,7 @@
+# Veil UI 0.3.0
+
+Stable release prepared for maintainer approval; publication has not occurred. Intended npm dist-tag: `latest`. After publication: `npm install @veil-runtime/ui@0.3.0`. Before publication, install the exact qualified tarball.
+
+Includes the universal interface engine, DOM mounting, composition, and capability-description APIs from the merged candidate. All 13 review remediations are retained, including bounded notification feedback when onError updates controller state. No public API changes were made during stable preparation. Node.js 24+, ESM; TypeScript baseline 6.0.2. Core 0.4.x is optional for interface/composition and required for capability execution.
+
+See [UNIVERSAL-INTERFACE.md](UNIVERSAL-INTERFACE.md) and [API.md](API.md). Live-model reliability, Firefox, WebKit, and actual screen-reader behavior remain unverified. Custom components are trusted host code.

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/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,7 @@
+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 };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@veil-runtime/ui",
-  "version": "0.1.0",
+  "version": "0.3.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.",
   "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"
   },