@veil-runtime/ui 0.4.1 → 0.5.0

package/docs/UNIVERSAL-INTERFACE.md

@@ -1,4 +1,6 @@
-# Universal interface foundation (0.3.0-rc.2 Developer Preview candidate)
+# Universal interface foundation (v0.5.0 Developer Preview candidate)
+
+The `/interface` contract and optional `/dom` adapter work without Veil Core. The package declares Core as an optional peer with range `^0.4.0` for legacy capability integrations; no Core v0.6.0 compatibility is claimed here. The [v0.4.0 contract guide](v0.4.0.md) documents validation, input, and condition additions retained from the published v0.4.2 baseline.
 
 ## Smallest working interface
 
@@ -58,9 +60,11 @@ Every update follows one acceptance path: validate and copy the proposed definit
 
 ## 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.
+The separate `ComposedApplication` API is a 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. Composition and v0.1 capability graph APIs remain available.
+
+Nodes have stable unique keys, a component name, and optional children. The built-ins are `Stack`, `Row`, `Grid`, `Text`, `Heading`, `Status`, `Input`, `Select`, `Textarea`, `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`. `Input`, `Select`, and `Textarea` write scalar state. Their optional declarative validation uses `required`, `minLength`, `maxLength`, `min`, and `max` where applicable. `getInterfaceValidation(snapshot)` reports errors for visible, enabled fields. Disabled fields retain state and skip validation. A Button with `validate: true` blocks dispatch when visible fields are invalid; other Buttons retain their existing behavior. `Button` emits `{ action, source, state, revision }` after an accepted dispatch. Table row actions add an opaque `rowId`; see [Interactive Tables](INTERACTIVE-COLLECTIONS-0.5.0.md).
 
-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.
+All nodes accept a `visible` condition; Buttons and fields also accept `disabled`; text/number inputs and textareas support `readOnly`. Conditions support strict equality, `ne`, numeric `lt`/`lte`/`gt`/`gte`, and bounded `all`/`any`/`not` combinations. Hidden ancestors and disabled Buttons cannot dispatch actions. These conditions and validation rules do not authorize effects; the host still owns action policy and service-side checks. See [v0.4.0.md](v0.4.0.md) and [the validated example](../examples/universal/validated.mjs) for exact rules. 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`.
 
@@ -82,24 +86,28 @@ const unmount = mountInterface(target, controller, components);
 // 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.
+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. Responsive Grid, row actions, richer forms and phased Status are specified in the [v0.5.0 release notes](RELEASE-0.5.0.md). Repeat templates, asynchronous validation and navigation state remain outside this contract.
 
 ## 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.
+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 15 child edges; aggregate traversal may reject shallower definitions. The conservative accounting budget is 1 MiB, independently applied to definition, data and state. See [capability limits](INTERFACE-CAPABILITIES-0.5.0.md); this does not bound raw JSON bytes before parsing. 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.
+Controller disposal clears subscriptions and blocks dispatch and updates. The lower-level mount disposer removes DOM listeners, component resources and renderer styles; call both disposers, or use `createMountedInterface().dispose()` to own both. 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
+## 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.
+`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. The [validated example](../examples/universal/validated.mjs) covers multi-input validation and conditions. Build with `node packages/ui/examples/universal/build.mjs`; open `examples/universal/index.html`. `npm --workspace @veil-runtime/ui run test:browser` exercises the browser examples 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.
+`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 headless scenarios covering information, forms, structured data, responsive Grid, interactive collections, field descriptions and disabled validation, asynchronous presentation and stale completion, JSON acceptance, event updates, and disposal. Core is not installed; the only production dependency is Zod. The single-call mount helper creates a controller and mount together with one `dispose()` and derives trusted component names from its 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.
+
+## Candidate qualification and historical release assessment
+
+This is an unpublished v0.5.0 Developer Preview candidate. Existing v0.4.2 definitions remain accepted, with source compatibility changes for controller implementers and broad Table-column readers. See [release notes and migration](RELEASE-0.5.0.md) and the [qualification report](RELEASE-QUALIFICATION-0.5.0.md).
 
-## Release assessment
+Chromium covers the original composition/universal demonstrations and Grid breakpoint edges. Chromium, Firefox and WebKit cover collections, forms, asynchronous presentation and text stability; manual assistive-technology certification remains unverified. Heading remains fixed at h2. Sorting, pagination, list templates and implicit field submission remain outside scope. Publication requires separate authorization of the exact qualified artifact.
 
-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.
+At the v0.3.0-rc.2 checkpoint, this interface preserved the qualified v0.2.0 RC APIs. The old RC commit and tarball remain a reproducible historical checkpoint. Its candidate-time limitations and publication gate do not describe the current v0.4.2 package: declarative form-field validation, Select, Textarea, compound conditions, and conditional Button disabling were added by v0.4.0. The v0.4.2 renderer stability patch was qualified in Chromium, Firefox, and WebKit; physical Safari, screen readers, and framework-specific adapters are not established by that browser-engine evidence.

package/docs/V0.5.0-HANDOVER.md

@@ -0,0 +1,144 @@
+# UI v0.5.0 development handover
+
+Qualification follow-up: see [release notes](RELEASE-0.5.0.md) and [audit report](RELEASE-QUALIFICATION-0.5.0.md). The historical increment snapshot below used `0.5.0-dev.0`; qualification prepares `0.5.0` locally and does not publish.
+
+Snapshot: 2026-11-14, `/home/mustapha/dev/ai/veil-ui-v050`.
+Unpublished candidate `0.5.0-dev.0`; publication hold remains active.
+**All planned v0.5.0 feature increments are complete and ready for release
+qualification. This is not a release.**
+
+## Git checkpoint
+
+Branch: `feature/ui-v0.5-contract-metadata`.
+Verified starting HEAD: `e622054260b1d508aacd6a92baa1fe86dafa5185`.
+Starting working tree was clean. The Host-Driven Asynchronous Presentation States
+increment is one local checkpoint with message
+`feat(ui): add host-driven asynchronous presentation states`.
+Its SHA is available with `git log -1 --format=%H` after creation; a commit cannot
+embed its own SHA. The common Git directory is `/home/mustapha/dev/ai/veil-ui-lab/.git`.
+
+The user authorized design, implementation, verification, exact staging and one
+local checkpoint commit. No merge, push, tag, publication, release or deployment
+is authorized. Veil Core, the separate showcase and published v0.4.2 artifacts
+remain untouched. Generated distribution, bundles, logs and tarballs are not
+commit inputs.
+
+## Completed feature scope
+
+- Capability metadata describes aggregate and effective validation bounds.
+- Responsive Grid provides bounded 1–4 columns, viewport breakpoints at
+  600px/1024px, finite gaps, keyed children and stable DOM/keyboard order.
+- Interactive Tables provide keyed rows, neutral badges and host-allowlisted,
+  revision-checked row actions.
+- Richer Forms provides bounded descriptions, disabled conditions, text/number
+  readOnly flags, accessible eager feedback and first-invalid submission focus.
+- Host-driven asynchronous presentation adds optional Status `phase` literals or
+  bindings for `loading`, `ready`, `empty`, `error`, safe defaults, strict bounded
+  string messages, polite atomic semantics and focus recovery.
+
+Specifications: [`INTERFACE-CAPABILITIES-0.5.0.md`](INTERFACE-CAPABILITIES-0.5.0.md),
+[`INTERACTIVE-COLLECTIONS-0.5.0.md`](INTERACTIVE-COLLECTIONS-0.5.0.md),
+[`RICHER-FORMS-0.5.0.md`](RICHER-FORMS-0.5.0.md), and
+[`ASYNC-PRESENTATION-0.5.0.md`](ASYNC-PRESENTATION-0.5.0.md).
+The asynchronous presentation document records the design before implementation,
+including the alternatives considered and the exact JSON/TypeScript contract.
+
+## Final increment behavior
+
+Manifest v5 adds Status `phase` and `behavior.presentation`. Existing definitions,
+controller signatures and event fields remain compatible. Exact manifest-version
+consumers must accept v5. The separate composition API's Status is unchanged.
+
+A phased Status keeps its keyed paragraph, `role=status`, `aria-live=polite`,
+`aria-atomic=true`, `data-phase` and `tabindex=-1`. Loading messages are not marked
+aria-busy, so their announcements are not deferred. Optional text uses existing
+string/binding syntax but must resolve to a string of at most 4096 UTF-16 units
+when phase is present. Invalid or missing bound phase/text rejects the candidate
+atomically, including when hidden. Absent text uses a safe phase default; explicit
+empty strings remain permitted. Supplied messages render only as textContent.
+Hosts must sanitize public messages: Veil cannot recognize secrets in strings.
+Exceptions, callback errors and diagnostics are never automatically displayed.
+
+Existing conditions select content and ordinary Buttons request retry. Host action
+allowlists and current visibility/disabled checks remain authoritative. Phase
+alone does not authorize, disable, hide or validate anything. Hosts own operation
+execution, cancellation, deduplication, business authorization and result handling.
+Veil introduces no fetching, timers, retries, jobs, queues, promise ownership or
+second state engine. The example includes host-side revision protocol helpers.
+
+Use existing revision-protected updates: capture the revision after accepting
+loading and supply it on completion. Any intervening accepted edit or update
+invalidates it; stale updates return false. Hosts decide whether to discard or
+rebase. Compatible controls retain state, identity, focus and selection. If an
+accepted update removes/disables/hides the focused control, focus moves to the
+first visible phased Status in screen order. Focus outside the interface remains
+untouched. Hidden children retain their existing mounted lifecycle and field
+state; hidden controls remain ineligible. Disposal remains authoritative.
+
+## Increment files
+
+Paths relative to `packages/ui/`:
+
+- `src/interface.ts`: public phase type, strict definition/data validation,
+  manifest v5 and behavioral metadata. No controller API changes.
+- `src/dom.ts`: phased messages/semantics and focus recovery during reconciliation.
+- `test/interface-async-presentation.test.ts`,
+  `test/browser-async-presentation.mjs`: contract/state and three-browser coverage.
+- Existing manifest unit tests: v5 expectations, with existing assertions retained.
+- `scripts/verify-universal-consumer.mjs`: installed strict TypeScript phase types
+  and independent JavaScript host transition/retry/stale-result scenarios.
+- `examples/universal/async-presentation.mjs`: JSON-only definition and explicit
+  host protocol helpers, composing Grid, Table, List and fields.
+- `package.json`: dedicated `test:browser:async` command.
+- README, CHANGELOG, capability documentation, async contract and this handover.
+
+## Verification
+
+All required gates pass:
+
+- `npm --workspace @veil-runtime/ui run check`: build, test typecheck, **110/110 UI
+  tests**, distribution integrity (54 files), source/dist boundary and circular
+  import checks.
+- `npm --workspace @veil-runtime/ui run test:browser`: existing composition and
+  universal suites, including accessibility tree, mobile/desktop/narrow layout,
+  Grid, input behavior, reconciliation, focus, escaping and teardown.
+- With `VEIL_PLAYWRIGHT_MODULE=/tmp/veil-v050-publication-main/node_modules/playwright/index.mjs`:
+  `test:browser:async`, `test:browser:forms`, `test:browser:collections`, and
+  `node packages/ui/test/browser-text-stability.mjs` pass on Chromium
+  151.0.7922.108, Firefox 157.0 and WebKit 27.2.
+- Async tests cover accessible loading/ready/empty/error messages and defaults,
+  native retry Enter/Space, Tab order, state/identity/focus/selection retention,
+  hidden-ancestor/removal/disabled focus recovery and hidden destination exclusion,
+  rapid transitions, out-of-order results, intervening edits, revision/disposal,
+  atomic rejection, escaping and Table/List/Grid/form composition.
+- `npm --workspace @veil-runtime/ui run verify:consumer`: repeat npm packs have
+  identical hashes; independent installed strict TypeScript and JavaScript
+  consumers pass without optional Core. Only zod is a runtime dependency.
+- `git diff --check` and exact staged inventory/diff review before checkpoint.
+
+Local logs: `/tmp/veil-async-{check,browser,regressions,forms,collections,text,consumer}.log`.
+Browser launch and npm packaging failed under the sandbox and passed with
+authorized host execution. No validation was weakened or failing test skipped.
+
+## Limits and release qualification
+
+Host revisions are snapshot-wide, not per-operation tokens. Multi-region focus
+recovery uses the first visible phased Status; hosts should order destinations or
+manage focus explicitly. No automatic return to a formerly hidden control is
+provided. Automated accessibility tests do not certify assistive-technology
+announcements. No progress percentage, urgent alert mode, async validator,
+server-error field mapping, implicit submit or asynchronous orchestration is added.
+
+Forms retain eager validation and existing five rules. Native number controls
+normalize incomplete spelling. Hidden/disabled values remain in event.state;
+field flags and phase are not confidentiality/authorization controls.
+
+Collections still omit sorting/filtering/pagination/selection, interactive Lists,
+rich cell objects, URLs, custom formatters and arrow-key grid mode. Row IDs remain
+opaque host-authorized references. Table gestures retain their existing revision
+protection; ordinary Buttons keep their existing eligibility semantics. Grid uses
+viewport breakpoints; host CSP must permit finite renderer styles.
+
+Next: separately authorized release qualification of this completed feature scope.
+Release, publication, merge, push, tagging and deployment require separate
+instructions. The candidate remains unpublished and publication hold stays active.

package/examples/universal/async-presentation.mjs

@@ -0,0 +1,32 @@
+// JSON-only definition. The host supplies approved public messages and valid
+// collections in every snapshot, including while their views are hidden.
+const isPhase = equals => ({ binding: { source: 'data', path: 'phase' }, equals });
+export const asyncPresentation = {
+  id: 'async-results', actions: ['retry'],
+  data: { phase: 'loading', message: 'Loading results…', rows: [], items: [] },
+  state: { notes: '' },
+  screen: { key: 'root', component: 'Grid', columnsAt: { sm: 2 }, children: [
+    { key: 'status', component: 'Status', phase: { source: 'data', path: 'phase' }, text: { source: 'data', path: 'message' } },
+    { key: 'retry', component: 'Button', text: 'Retry', action: 'retry', visible: isPhase('error') },
+    { key: 'results', component: 'Stack', visible: isPhase('ready'), children: [
+      { key: 'table', component: 'Table', binding: { source: 'data', path: 'rows' }, rowKey: 'id', columns: [{ key: 'name', label: 'Name' }] },
+      { key: 'list', component: 'List', binding: { source: 'data', path: 'items' } },
+    ] },
+    { key: 'notes', component: 'Textarea', label: 'Notes', binding: { source: 'state', path: 'notes' } },
+  ] },
+};
+
+// Host-side protocol helpers, not an asynchronous engine. The host authorizes
+// retry, starts/cancels its operation, and retains the returned revision token.
+export function beginLoading(controller, expectedRevision = controller.snapshot().revision) {
+  const data = controller.snapshot().data;
+  if (!controller.updateData({ ...data, phase: 'loading', message: 'Loading results…' }, expectedRevision)) return null;
+  return controller.snapshot().revision;
+}
+export function presentResult(controller, revision, rows, items) {
+  return controller.updateData({ phase: rows.length || items.length ? 'ready' : 'empty', message: rows.length || items.length ? 'Results ready.' : 'No results.', rows, items }, revision);
+}
+export function presentError(controller, revision) {
+  // Never pass an exception or its message through to the screen.
+  return controller.updateData({ phase: 'error', message: 'Results are unavailable. You can try again.', rows: [], items: [] }, revision);
+}

package/examples/universal/collections.mjs

@@ -0,0 +1,22 @@
+import { createMountedInterface } from '../../dist/dom.js';
+
+// Trusted host code supplies openRecord. It must resolve and authorize the actual
+// record for the current principal before opening it. An ID is only a reference.
+export function mountCollections(target, rows, openRecord) {
+  const controller = createMountedInterface(target, {
+    id: 'collection-example', actions: ['record.open'], data: { rows },
+    screen: {
+      key: 'records', component: 'Table', ariaLabel: 'Records',
+      binding: { source: 'data', path: 'rows' }, rowKey: 'id',
+      columns: [{ key: 'name', label: 'Name' }, { key: 'status', label: 'Status', presentation: 'badge' }],
+      rowActions: [{ action: 'record.open', label: 'Open record' }],
+    },
+  }, {
+    allowedActions: ['record.open'],
+    async onEvent(event) {
+      if (event.action !== 'record.open' || event.source !== 'records' || event.rowId === undefined) return;
+      await openRecord(event.rowId); // Host owns lookup, record authorization and execution.
+    },
+  });
+  return controller;
+}

package/examples/universal/forms.mjs

@@ -0,0 +1,21 @@
+// JSON-only definition. The host handles the declared action and owns authorization
+// and persistence. Hidden/disabled values remain in event.state.
+export const requestForm = {
+  id: 'request', actions: ['submit'],
+  state: { reference: 'REQ-42', summary: '', priority: 'normal', expedited: false, reason: '', units: 1 },
+  screen: { key: 'request', component: 'Stack', children: [
+    { key: 'reference', component: 'Input', label: 'Reference', readOnly: true,
+      binding: { source: 'state', path: 'reference' } },
+    { key: 'summary', component: 'Input', label: 'Summary', description: 'Describe the operational request in 5–100 characters.',
+      binding: { source: 'state', path: 'summary' }, validation: { required: true, minLength: 5, maxLength: 100 } },
+    { key: 'priority', component: 'Select', label: 'Priority', description: 'The host reviews all urgent requests.',
+      binding: { source: 'state', path: 'priority' }, options: [{ value: 'normal', label: 'Normal' }, { value: 'urgent', label: 'Urgent' }] },
+    { key: 'expedited', component: 'Input', inputType: 'checkbox', label: 'Request expedited handling', binding: { source: 'state', path: 'expedited' } },
+    { key: 'reason', component: 'Textarea', label: 'Expedited reason', description: 'Required when expedited handling is selected.',
+      binding: { source: 'state', path: 'reason' }, visible: { binding: { source: 'state', path: 'expedited' }, equals: true },
+      validation: { required: true, maxLength: 500 } },
+    { key: 'units', component: 'Input', inputType: 'number', label: 'Units', description: 'Choose between 1 and 20 units.',
+      binding: { source: 'state', path: 'units' }, disabled: { binding: { source: 'state', path: 'expedited' }, equals: true }, validation: { required: true, min: 1, max: 20 } },
+    { key: 'submit', component: 'Button', text: 'Submit request', action: 'submit', validate: true },
+  ] },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veil-runtime/ui",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
@@ -50,13 +50,16 @@
     "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",
+    "test:browser:collections": "cd ../.. && node packages/ui/test/browser-collections.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"
+    "check": "npm run build && npm run typecheck:test && npm test && npm run verify:dist && npm run check:boundary",
+    "test:browser:forms": "cd ../.. && node packages/ui/test/browser-forms.mjs",
+    "test:browser:async": "cd ../.. && node packages/ui/test/browser-async-presentation.mjs"
   },
   "peerDependencies": {
     "@veil-runtime/core": "^0.4.0"