@veil-runtime/ui 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,44 @@
+# 0.3.0 — stable release preparation
+
+- Promote the merged rc.2 implementation and all 13 review remediations, including notification-loop termination, to stable metadata with the `latest` dist-tag.
+- Preserve all existing public APIs; no additional functionality.
+- Publication awaits maintainer approval of the exact qualified artifact.
+
+# 0.3.0-rc.2 — review remediation candidate
+
+- Reject inherited composition field names and stage bounded state changes before acceptance.
+- Apply independent resource limits to interface definition, data, and state snapshot copies.
+- Preserve conditional layout visibility, numeric edit spelling, focus and selection, current accessibility labels, and the previous screen when replacement mounting fails.
+- Route form fallback submissions locally, keep field/error IDs unique, and exercise only visible actions in the model qualification harness.
+- Add controller, browser, harness, and adversarial boundary regressions for all review findings.
+
+# 0.3.0-rc.1 — Developer Preview release candidate
+
+- Prepare the universal interface engine for independent qualification and external consumption.
+- Add a provider-neutral six-scenario model harness with deterministic fixtures; live model reliability remains unverified until provider access is available.
+- Preserve the v0.1.0 and v0.2.0 APIs. Publication remains subject to maintainer approval of the exact candidate artifact.
+
+# 0.3.0-dev.0 — dynamic universal interface work
+
+- Add a single-call DOM mount helper with one teardown, a JSON-safe built-in capability manifest, and a strict TypeScript type for built-in screens.
+- Add Row, Heading, List, and Status primitives; reject unsupported properties on built-ins and validate bound collections before mounting.
+- Exercise six workflows from an independently installed tarball in TypeScript and JavaScript; update the three browser demonstrations to use the public helper and manifest.
+- Make controller and mounted DOM acceptance transactional for generated definition, data, and local state updates; failed preparation preserves the accepted revision and view.
+- Prepare detached custom replacements before commit and dispose rejected candidates; restore rejected input edits in the DOM.
+- Retain compatible input state and DOM identity across definition updates, including keyed reordering and focus/selection.
+- Add optional custom DOM component update/dispose hooks and an abort signal for owned resources.
+- Stage new DOM subtrees before structural changes; reject invalid definitions without changing the current controller.
+- Reject dispatch to hidden actions and expand the simulated agent and browser lifecycle regressions.
+- Keep the development version unpublished; the 0.2.0-rc.1 checkpoint remains at `c65e752`.
+
+# 0.2.0-rc.1 — application composition foundation (release candidate)
+
+- Added a bounded one-screen composition schema, reactive controller, typed action result, and native DOM renderer.
+- Added `/composition` and `/dom` subpaths and an independently installable example without Core.
+- Marked Core as an optional peer for the new API; preserved the existing capability graph APIs and `/inspection` export.
+- Hardened field metadata and child validation; added controller disposal, late-result suppression, DOM listener cleanup on remount, external field synchronization, and focus on invalid submission.
+- This is a release candidate for maintainer review. No package has been published from this branch.
+
 # Proposed v0.1.0 release notes — release candidate
 
 Veil UI — Deterministic Composition Engine (Developer Preview).

package/README.md

@@ -1,10 +1,14 @@
-# Veil UI — Deterministic Composition Engine (Developer Preview)
+# Veil UI — Deterministic Composition Engine
+
+The v0.3.0 stable release's framework-neutral interface engine is documented in [UNIVERSAL-INTERFACE.md](docs/UNIVERSAL-INTERFACE.md). It supports bounded JSON definitions, keyed dynamic updates, local state retention, trusted component lifecycles, and host-controlled actions without Veil Core. It uses the same public package alongside the existing composition and capability description APIs. See [RELEASE-0.3.0.md](docs/RELEASE-0.3.0.md) for release scope and limits.
+
+**v0.2.0-rc.1 candidate:** a one-screen declarative composition foundation and DOM renderer are documented in [COMPOSITION.md](docs/COMPOSITION.md), with a working [stock treatment example](examples/composed). These additions are pending maintainer approval and are not a release announcement. The text below documents the v0.1.0 Developer Preview baseline.
 
 `@veil-runtime/ui@0.1.0` derives and validates interface descriptions from governed capability contracts. It is framework-neutral: the package returns graphs, fields, surfaces, and interaction descriptors. Your host renders those descriptions and executes authorized operations through Core.
 
 **Developer Preview: publication requires explicit maintainer approval of the exact qualified tarball and release action.**
 
-## Install and run the candidate
+## Install and run 0.3.0
 
 Requires Node.js 24 or newer and npm. The supported TypeScript baseline is 6.0.2, ESM with NodeNext resolution. Strict consumer checks use `ES2022` and `DOM` libraries plus Node types because public Core/MCP declarations reference web transport types. UI itself makes no DOM or Core runtime calls. Direct CommonJS `require()` is unsupported; use ESM imports or dynamic `import()` from a CommonJS host.
 
@@ -17,11 +21,11 @@ npm run qualify:ui
 
 Qualification prints the candidate artifact and evidence directory. It builds and tests a source-only snapshot, installs the tarball into a new consumer with **published Core 0.4.0**, runs the standalone example, checks declarations and browser bundling, compares repeated tarballs, audits production dependencies, and inspects legal files. It never publishes.
 
-In a separate application, use the printed absolute tarball path:
+After maintainer-approved publication, install with `npm install @veil-runtime/ui@0.3.0`. Before publication, use the qualified absolute tarball path:
 
 ```sh
 npm init -y
-npm install /absolute/path/veil-runtime-ui-0.1.0.tgz @veil-runtime/core@0.4.0
+npm install /absolute/path/veil-runtime-ui-0.3.0.tgz
 ```
 
 Then copy [examples/standalone/index.mjs](examples/standalone/index.mjs) into that application and run:
@@ -30,7 +34,7 @@ Then copy [examples/standalone/index.mjs](examples/standalone/index.mjs) into th
 node index.mjs
 ```
 
-The example prints derived input controls, rejects invalid input, demonstrates a policy-denied execution without calling the service, and displays an approved result. It uses a tiny host-owned terminal renderer, a local identity fixture, an existing-service-style operation, and authoritative Core authorization. No model, Emergence, React, or Sandbox is involved. The included example `package.json` intentionally omits the unpublished UI dependency: install the candidate tarball explicitly using the command above.
+For the v0.3.0 interface quick start, use [UNIVERSAL-INTERFACE.md](docs/UNIVERSAL-INTERFACE.md) and [examples/universal](examples/universal). The v0.1.0 standalone example below also needs `@veil-runtime/core@0.4.0`; install that peer separately when running it. The example prints derived input controls, rejects invalid input, demonstrates a policy-denied execution without calling the service, and displays an approved result. It uses a tiny host-owned terminal renderer, a local identity fixture, an existing-service-style operation, and authoritative Core authorization. No model, Emergence, React, or Sandbox is involved. The included example `package.json` intentionally omits the unpublished UI dependency: install the candidate tarball explicitly using the command above.
 
 ## Minimal derivation
 

package/dist/build-manifest.json

@@ -1,27 +1,32 @@
 {
   "inputs": {
-    "package.json": "c157a9da53acaef17d77f2c26c31b66c0709ff389eb660ac83889de64f4a39bb",
+    "package.json": "b2bfc55dd16c0ffb130a5f86823791cf68eea2115f94be87eb947e55683eb8d5",
     "scripts/artifact.mjs": "92d2ffd8836d0e14742528da9ddc96e0834ef873ffa81097a3ebae58d825aace",
-    "scripts/build.mjs": "e0a8a0dd359c09a76b70d93865247f8d4404064442e76ff4b8d4d3e3390cb9aa",
-    "scripts/check-boundary.mjs": "f5c0efe0b0f720b6e78dfa6bb5d22a1ab784e173e4d4db97adcb08d3ce889e8b",
+    "scripts/build.mjs": "54ca91e728925b1efefa61e5aeeb9e5bf549d25c2faa8ceb618009c214a7e03c",
+    "scripts/check-boundary.mjs": "5c09c118f7340f3a111e3947c2d98579f73903728ded9d604ac13b93077a5b29",
     "scripts/publication-hold.mjs": "2c7a00f8f23ac34d888813e76c4ab8f5bb112526002fd6be15993825dff118ca",
     "scripts/verify-dist.mjs": "668d5b105b7762cc2fd812091dba24f6985597da4519f72d572d5b7e63b880c0",
+    "scripts/verify-universal-consumer.mjs": "09c77f374c32ce6ec3b8887f6fa5bf1026800c1890adeace5ab226606c78b5be",
     "src/application.ts": "18cee45849d0ef9858d673b35aa42b77c4469b637669a0ab8a1ffc1f2c980d5d",
     "src/capability-view-derivation.ts": "07367b08e115c4022c873d2d01888d0d2c26ab58ac7518500fd95331301bbaa4",
     "src/capability-view.ts": "fda1db85ffcb26b45b60890b3a20b875ee4aff76bd3c35ce5d41018b22a64de7",
     "src/composed-surface.ts": "b2c2fc4cfbc8c5a07048f5482f9a2807ff936f62a99cd93c5a794133d6a31175",
     "src/composition-inspection.ts": "a9265c68bab785ba9e38ea83899997daec9322de10b98fdafaa44bc523ca0c3a",
+    "src/composition.ts": "4d06b8fe4ed61b2e0a4daf07770be708b2f0167a35ae41140b4047b7cd8fbd78",
     "src/derive-input-fields.ts": "cf8c7ee9f98ed0838dbf299fb4653814c3e70004fc121d8c99752aa137331efd",
     "src/derive-output-view.ts": "81d622d5430f7b9333a41c33794d8d22e3e539e861e04830ce089d83a6790a8e",
+    "src/dom.ts": "27724ba587addc050fdb0abd2ee1c6226971b6e7ce5dd5564fb67780e7ede486",
     "src/execution-request.ts": "775c3beba47aae482acbc2a48461ab8f947ca7b773c71a69077af387557ae344",
     "src/experience-orchestration.ts": "f156497d99828d15da2b42f3155e4ec0b77fc72ad6e6d846bb9bbea4d6791fa4",
     "src/format-semantic-value.ts": "2192cd723c5a9d64164287ddae99c0aa105024e1d0778a597d0b71a2ea8ab9dd",
-    "src/index.ts": "44b876d7a7f0aaf333a6a03c72bcc48911f6d15e8717fad6fb6b77ea0f47db21",
-    "src/input-schema.ts": "8c03637abeb80958881475ab049494a8905d19deb76df61c23c76d9b19eb692f",
+    "src/index.ts": "403cb5e536fe1df95c4911de7fe221dcf5d118f097cbd56bbdf7d19f6da1b7c7",
+    "src/input-schema.ts": "3f40e707882efc81f5e537c8ad8a2cdc4fd279e6362d32ee6fb55a09ac298ee7",
     "src/interaction-resolution.ts": "e9a75d501ded82fe773f03d2dcb1e2fa8b396a98d9c2902888a3f6b3cbf8f55e",
+    "src/interface-transaction.ts": "fe415c5318d0f0df78760dc374968dcfee42b0327e8796f3195aef07ccd19e91",
+    "src/interface.ts": "80843613765e7adc18b7f1e3b3c8ed46a3b8de41859ce06d8e2cb4750e2173c4",
     "src/output-presentation-suggestion-schema.ts": "2421d9f152cb4ce5e4d560f8ebe1d4029147dcab01a187c67008f36a3dfd6bf4",
     "src/output-schema.ts": "68f7f49fed5badafb5ca509365802dec6526a56c23d2bf2837b350852823688b",
-    "src/presentation-composition.ts": "b591c0b041f3518fc0287934a063e75c217355987e9da9c4ed604d10e3acc940",
+    "src/presentation-composition.ts": "0116ae011d577396b5eff5b11a4c6c58b196b7610e71f0f3a0898e63de6457f0",
     "src/presentation-context.ts": "34c2796cb23c6086e6ee9474b756a03fb69d713aca28c0cdb7d6b0bd60f5c248",
     "src/presentation-suggestion-schema.ts": "f618db5e8caf439e0ae758a74a38edf8db57485662f1ddad29614e68425b1d41",
     "src/registry.ts": "de906003b8098202c905532cfd497ab0e2f9092226be2d9f469c5cf883891a8c",
@@ -29,7 +34,7 @@
     "src/validate-application.ts": "f76874d49955d7ade1d0f8c5f995b63a6026102173b3e50b710517ccbc1442f4",
     "src/validation-safety.ts": "e0bcc379269e3f51a0021dd4797c422f813b41141274125705b425d2b1b1eb2b",
     "src/workflow.ts": "6c5b31242474c0a37b1a9f85717eebf3b1d4b373c17c8d47861804e28d3302e5",
-    "tsconfig.json": "eb3e08c27d8ac0302b339a13814c0f4416372f7b5f10fbafe3f4f16751978e9e"
+    "tsconfig.json": "d4ec334afc2daeccd982d4c3410b53f39df080f3cd1b761557f8e46dc96ab8aa"
   },
   "outputs": {
     "application.d.ts": "2c3091787abcd5a8005bfe951dc012056219b5ba6d70e5d8ad275281cf481d86",
@@ -42,28 +47,36 @@
     "composed-surface.js": "8e609bb71c20b858c77f0e9f90bb1319db8477b13f9f965f1a1e18524bf50881",
     "composition-inspection.d.ts": "dca099a4a9776626a3b0fffe16f65aeecf4de100eab84287906c03f94c059941",
     "composition-inspection.js": "29527de641d75b0ea6710aa5407f9d0362ef5c61595694ced3745dd2ace92b72",
+    "composition.d.ts": "b76e23e686ca428378274bf74d55986ccb0bc91b95edc32beb6f82427e7a9c8b",
+    "composition.js": "6840719dac8b9239a67c647961fe32552b6fa98d30422bf3438edca993267147",
     "derive-input-fields.d.ts": "417aa8a884416e1a679a69d938592908488611fb453cb4e84b3666d351ca1045",
     "derive-input-fields.js": "de940148e3c029b786fec95a520a3d8a8d1eef1d361436fa607b2990b63f2adc",
     "derive-output-view.d.ts": "9ca3c32ac65215bb85ae74b75121c55c2ac82d04d7754d38ebc0de94d3fa898a",
     "derive-output-view.js": "e54de4b2ece567a518d346cfd8d96fe2179f5a1fcf76cc6306c5222184e19b73",
+    "dom.d.ts": "ae12ba88b9bf43bdc99a9c2ca8923764cf28e77d55b132a05dc5965cba34a6a5",
+    "dom.js": "cfc237bc80931652b54726efc65585970c386d851471d68e603e14c999053e84",
     "execution-request.d.ts": "f8b68cf456bfbeb63a968378e5ccaef5f55a908022e323901668ca99ebe75a3a",
     "execution-request.js": "f32bd2e9de70dd9f243d08d0fce4898e847fa3d34d77d3376a1b3c5839edb611",
     "experience-orchestration.d.ts": "45fa9770a37acccaeb6e0f267e0a566c6d6cda6133d6e1077589859478effd77",
     "experience-orchestration.js": "3ffccbcdc94bb2083f8e2227755651825d279f93b48f0c71d32d595c297b3fc2",
     "format-semantic-value.d.ts": "8ecb9dff99d819af71251a909e307e11e07f5c76bec1e8796a8cefcd0692a921",
     "format-semantic-value.js": "dd36b084312a57949a0a6e104e1c84a92ba334488e5e4dc7555f5d16a7eea7aa",
-    "index.d.ts": "44b876d7a7f0aaf333a6a03c72bcc48911f6d15e8717fad6fb6b77ea0f47db21",
-    "index.js": "44b876d7a7f0aaf333a6a03c72bcc48911f6d15e8717fad6fb6b77ea0f47db21",
-    "input-schema.d.ts": "9f93c761ca0936ca18dd6a9df250fb16ba43f0da48a74897918765851edfacc2",
+    "index.d.ts": "403cb5e536fe1df95c4911de7fe221dcf5d118f097cbd56bbdf7d19f6da1b7c7",
+    "index.js": "403cb5e536fe1df95c4911de7fe221dcf5d118f097cbd56bbdf7d19f6da1b7c7",
+    "input-schema.d.ts": "e3cf583d925bc65d54250cfa3c1c3230b5df15dcb7be300a5de5fd9f0f0ab81d",
     "input-schema.js": "f5747d9b6acdced514c1c8c80d7a8a36e972d703fc234e1ac266f02dfd19c045",
     "interaction-resolution.d.ts": "fc3af3c0405e78e85bacf67262d7566f1b9f9ea6263bc4c200d0318795b805cf",
     "interaction-resolution.js": "498ea435bbb9ba0c814728664652491ba6c4be5c3407233984df4cf4f16103d7",
+    "interface-transaction.d.ts": "e93b9188ebfd497a4ef180e31fb93b48052a25c5905bf94a6b018a41538f33ac",
+    "interface-transaction.js": "9bf1a2bf576576ccb25d993581980e06280fa35107c96e49f962c47a72c1dbb3",
+    "interface.d.ts": "ec4973c9c99f2def7e6e2946b5652bff2f9877b256f181d0364ac85f35aca86b",
+    "interface.js": "7a29e93f17b32f5d5a3d978603a2cd235617b6474e5690d7f2c7e13ef61da19b",
     "output-presentation-suggestion-schema.d.ts": "88072dc37afeaab8ac05182b5d49fdf52099bbb18518ce2485feea476ea85895",
     "output-presentation-suggestion-schema.js": "708d2f821132978ba44a2e01812e41e3eec70266e5dbeb7053f55f88142ad634",
     "output-schema.d.ts": "8dbf090a79ab489e068e4a290dccd57e222c377f111d38e990308db8a3debca8",
     "output-schema.js": "29345dd93ccc27fafbdc29c66fbd35e38ab9d382392ca40fcdf643dbedefc662",
-    "presentation-composition.d.ts": "42dcb9fd0a7478907e30bac5288f4a6508b24ffc78dbacb0eaa51f0ac99f5378",
-    "presentation-composition.js": "35a310e39a660ba2f2ba322272db369dfdb27bc6d8608f77a75651f2ff0baad6",
+    "presentation-composition.d.ts": "e2b80f670230104e6b29e6447d842d0962c2ebcbde6dd064620d5194c2cd4689",
+    "presentation-composition.js": "c3d1666f55173f4e9f839e2b6e69acd2172a086f7e002e8332fde0b7edc8aec4",
     "presentation-context.d.ts": "f3565bd1666882a0ddd6041cb379270fd3fcb2c172a8e011b9c07ff189a404a9",
     "presentation-context.js": "8e609bb71c20b858c77f0e9f90bb1319db8477b13f9f965f1a1e18524bf50881",
     "presentation-suggestion-schema.d.ts": "9fdd12079f822a608c9a3f2f3330b953fc247c65c5b6181a595ddc0b4440f37c",

package/dist/composition.d.ts

@@ -0,0 +1,43 @@
+import type { UIField } from "./capability-view.js";
+import { type RichCapabilityInputSchema } from "./input-schema.js";
+export interface ComponentNode {
+    component: string;
+    field?: string;
+    action?: string;
+    text?: string;
+    children?: ComponentNode[];
+}
+export interface ComposedApplication {
+    id: string;
+    title: string;
+    fields: RichCapabilityInputSchema;
+    initialState?: Record<string, unknown>;
+    screen: ComponentNode;
+    actions: readonly string[];
+}
+export type SubmissionStatus = "idle" | "submitting" | "success" | "error";
+export interface CompositionSnapshot {
+    values: Record<string, unknown>;
+    errors: Record<string, string>;
+    status: SubmissionStatus;
+    message: string;
+}
+export type ActionResult = {
+    ok: true;
+} | {
+    ok: false;
+};
+export type ActionHandler = (input: Readonly<Record<string, unknown>>) => Promise<ActionResult> | ActionResult;
+export type ActionHandlers = Readonly<Record<string, ActionHandler>>;
+export declare function defineComposedApplication<const T extends ComposedApplication>(definition: T): T;
+export declare function validateComposedApplication(definition: ComposedApplication, customComponents?: readonly string[]): void;
+export interface CompositionController<Action extends string = string, Field extends string = string> {
+    readonly definition: ComposedApplication;
+    snapshot(): CompositionSnapshot;
+    field(name: Field): UIField;
+    setField(name: Field, value: unknown): void;
+    submit(action: Action): Promise<boolean>;
+    subscribe(listener: (snapshot: CompositionSnapshot) => void): () => void;
+    dispose(): void;
+}
+export declare function createCompositionController<const T extends ComposedApplication>(definition: T, handlers: Readonly<Record<T["actions"][number], ActionHandler>>, customComponents?: readonly string[]): CompositionController<T["actions"][number], keyof T["fields"] & string>;

package/dist/composition.js

@@ -0,0 +1,227 @@
+import { deriveUIField } from "./derive-input-fields.js";
+import { validateRichCapabilityInput, validateRichInputSchema, validateRichInputValue } from "./input-schema.js";
+import { assertBoundedData, assertSafeKey, copyData } from "./validation-safety.js";
+const builtins = new Set(["Stack", "Form", "Field", "Submit", "Text", "Status"]);
+const identifier = /^[A-Za-z][A-Za-z0-9._-]{0,127}$/;
+export function defineComposedApplication(definition) {
+    return definition;
+}
+export function validateComposedApplication(definition, customComponents = []) {
+    assertBoundedData(definition);
+    if (typeof definition.id !== "string" || !identifier.test(definition.id) || typeof definition.title !== "string" || !definition.title.trim())
+        throw new Error("Invalid application identity");
+    if (!definition.fields || typeof definition.fields !== "object" || Array.isArray(definition.fields))
+        throw new Error("Invalid field schema");
+    validateRichInputSchema(definition.fields);
+    for (const [name, field] of Object.entries(definition.fields)) {
+        if (!identifier.test(name) || typeof field.required !== "boolean" || typeof field.description !== "string")
+            throw new Error(`Invalid field contract: ${name}`);
+        if (field.enum !== undefined && (!Array.isArray(field.enum) || field.enum.length === 0 || new Set(field.enum).size !== field.enum.length))
+            throw new Error(`Invalid enum: ${name}`);
+        if (field.format !== undefined && !["date", "date-time", "multiline"].includes(field.format))
+            throw new Error(`Invalid format: ${name}`);
+        if (field.semantic !== undefined && field.semantic !== "currency")
+            throw new Error(`Invalid semantic: ${name}`);
+        if (field.currency !== undefined && (typeof field.currency !== "string" || !/^[A-Z]{3}$/.test(field.currency)))
+            throw new Error(`Invalid currency: ${name}`);
+        for (const key of ["minLength", "maxLength", "minItems", "maxItems"]) {
+            const value = field[key];
+            if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
+                throw new Error(`Invalid ${key}: ${name}`);
+        }
+        for (const key of ["minimum", "maximum"]) {
+            const value = field[key];
+            if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value)))
+                throw new Error(`Invalid ${key}: ${name}`);
+        }
+    }
+    if (!Array.isArray(definition.actions) || new Set(definition.actions).size !== definition.actions.length || definition.actions.some((id) => typeof id !== "string" || !identifier.test(id)))
+        throw new Error("Invalid action list");
+    for (const name of customComponents) {
+        if (!identifier.test(name))
+            throw new Error(`Invalid component name: ${name}`);
+        assertSafeKey(name);
+    }
+    const known = new Set([...builtins, ...customComponents]);
+    if (known.size !== builtins.size + customComponents.length)
+        throw new Error("Component names must be unique and cannot replace built-ins");
+    const fields = new Set();
+    const actions = new Set();
+    function visit(node, insideForm) {
+        if (!node || typeof node !== "object" || !known.has(node.component))
+            throw new Error(`Unknown component: ${String(node?.component)}`);
+        if (node.children !== undefined && !Array.isArray(node.children))
+            throw new Error("Component children must be an array");
+        if (node.component === "Form" && insideForm)
+            throw new Error("Nested forms are unsupported");
+        if (node.component === "Field") {
+            if (!insideForm || !node.field || !Object.hasOwn(definition.fields, node.field) || fields.has(node.field))
+                throw new Error(`Invalid or duplicate field: ${node.field}`);
+            const type = definition.fields[node.field]?.type;
+            if (type === "object" || type === "array")
+                throw new Error(`Structured field requires a custom component: ${node.field}`);
+            fields.add(node.field);
+        }
+        else if (node.field !== undefined)
+            throw new Error("Only Field nodes accept a field binding");
+        if (node.component === "Submit") {
+            if (!insideForm || !node.action || !definition.actions.includes(node.action) || actions.has(node.action))
+                throw new Error(`Invalid or duplicate action: ${node.action}`);
+            actions.add(node.action);
+        }
+        else if (node.action !== undefined)
+            throw new Error("Only Submit nodes accept an action");
+        if (node.text !== undefined && (typeof node.text !== "string" || node.text.length > 4096))
+            throw new Error("Invalid component text");
+        if (node.component === "Field" || node.component === "Submit" || node.component === "Text" || node.component === "Status") {
+            if (node.children?.length)
+                throw new Error(`${node.component} cannot contain children`);
+        }
+        for (const child of node.children ?? [])
+            visit(child, insideForm || node.component === "Form");
+    }
+    visit(definition.screen, false);
+    if (fields.size !== Object.keys(definition.fields).length || actions.size !== definition.actions.length)
+        throw new Error("All fields and actions must appear in the screen");
+    if (definition.initialState !== undefined) {
+        if (!definition.initialState || typeof definition.initialState !== "object" || Array.isArray(definition.initialState))
+            throw new Error("Invalid initial state");
+        for (const [key, value] of Object.entries(definition.initialState)) {
+            const field = Object.hasOwn(definition.fields, key) ? definition.fields[key] : undefined;
+            if (!field)
+                throw new Error(`Unknown initial field: ${key}`);
+            validateRichInputValue(value, { ...field, required: false }, key);
+        }
+    }
+}
+export function createCompositionController(definition, handlers, customComponents = []) {
+    validateComposedApplication(definition, customComponents);
+    const source = copyData(definition);
+    for (const action of source.actions)
+        if (!Object.hasOwn(handlers, action) || typeof handlers[action] !== "function")
+            throw new Error(`Missing action handler: ${action}`);
+    const listeners = new Set();
+    const values = Object.fromEntries(Object.keys(source.fields).map((name) => [name, source.initialState && Object.hasOwn(source.initialState, name) ? source.initialState[name] : (source.fields[name]?.type === "boolean" ? false : "")]));
+    let errors = {};
+    let status = "idle";
+    let message = "";
+    let disposed = false;
+    const snapshot = () => copyData({ values, errors, status, message });
+    const assertSnapshot = (nextValues, nextErrors, nextStatus, nextMessage) => {
+        assertBoundedData({ values: nextValues, errors: nextErrors, status: nextStatus, message: nextMessage });
+    };
+    const errorBudget = Object.fromEntries(Object.entries(source.fields).map(([name, field]) => [name, `Check ${deriveUIField(name, field).label}`]));
+    const assertValuesResource = (nextValues) => {
+        assertSnapshot(nextValues, errorBudget, "error", "Unable to save. Please try again.");
+    };
+    assertValuesResource(values);
+    const emit = () => { for (const listener of listeners) {
+        try {
+            listener(snapshot());
+        }
+        catch { /* Host listener failures cannot change the transaction. */ }
+    } };
+    return {
+        get definition() { return copyData(source); },
+        snapshot,
+        field(name) {
+            const field = Object.hasOwn(source.fields, name) ? source.fields[name] : undefined;
+            if (!field)
+                throw new Error(`Unknown field: ${name}`);
+            return deriveUIField(name, field);
+        },
+        setField(name, value) {
+            if (disposed)
+                return;
+            const field = Object.hasOwn(source.fields, name) ? source.fields[name] : undefined;
+            if (!field)
+                throw new Error(`Unknown field: ${name}`);
+            if (status === "submitting")
+                return;
+            assertBoundedData(value);
+            const nextValues = { ...values, [name]: copyData(value) };
+            const next = { ...errors };
+            try {
+                validateRichInputValue(value, field, name);
+                delete next[name];
+            }
+            catch {
+                next[name] = `Check ${deriveUIField(name, field).label}`;
+            }
+            assertValuesResource(nextValues);
+            Object.assign(values, nextValues);
+            errors = next;
+            status = "idle";
+            message = "";
+            emit();
+        },
+        async submit(action) {
+            if (disposed)
+                return false;
+            if (!source.actions.includes(action))
+                throw new Error(`Unknown action: ${action}`);
+            if (status === "submitting")
+                return false;
+            const next = {};
+            for (const [name, field] of Object.entries(source.fields)) {
+                try {
+                    validateRichInputValue(values[name], field, name);
+                }
+                catch {
+                    next[name] = `Check ${deriveUIField(name, field).label}`;
+                }
+            }
+            assertSnapshot(values, next, Object.keys(next).length ? "error" : "submitting", Object.keys(next).length ? "Review the highlighted fields." : "Submitting…");
+            errors = next;
+            if (Object.keys(next).length) {
+                status = "error";
+                message = "Review the highlighted fields.";
+                emit();
+                return false;
+            }
+            const input = copyData(values);
+            validateRichCapabilityInput(source.fields, input);
+            status = "submitting";
+            message = "Submitting…";
+            emit();
+            try {
+                const result = await handlers[action](input);
+                if (disposed)
+                    return false;
+                assertBoundedData(result);
+                if (!result || typeof result !== "object" || Object.keys(result).length !== 1 || (result.ok !== true && result.ok !== false))
+                    throw new Error("Invalid action result");
+                if (!result.ok)
+                    throw new Error("Action failed");
+                assertSnapshot(values, errors, "success", "Saved successfully.");
+                status = "success";
+                message = "Saved successfully.";
+                emit();
+                return true;
+            }
+            catch {
+                if (disposed)
+                    return false;
+                assertSnapshot(values, errors, "error", "Unable to save. Please try again.");
+                status = "error";
+                message = "Unable to save. Please try again.";
+                emit();
+                return false;
+            }
+        },
+        subscribe(listener) {
+            if (disposed)
+                throw new Error("Composition controller is disposed");
+            listeners.add(listener);
+            try {
+                listener(snapshot());
+            }
+            catch (error) {
+                listeners.delete(listener);
+                throw error;
+            }
+            return () => { listeners.delete(listener); };
+        },
+        dispose() { disposed = true; listeners.clear(); },
+    };
+}

package/dist/dom.d.ts

@@ -0,0 +1,31 @@
+import type { ComponentNode, CompositionController } from "./composition.js";
+import { type InterfaceController, type InterfaceDefinition, type InterfaceEvent, type InterfaceNode, type InterfaceSnapshot } from "./interface.js";
+export type DOMComponent = (node: Readonly<ComponentNode>, context: {
+    controller: CompositionController;
+    renderChildren: () => HTMLElement[];
+}) => HTMLElement;
+export type DOMComponentRegistry = Readonly<Record<string, DOMComponent>>;
+/** Mount one composed screen. Caller owns the controller, mount point, and disposal. */
+export declare function mountComposedApplication(target: HTMLElement, controller: CompositionController, components?: DOMComponentRegistry): () => void;
+export interface InterfaceDOMComponentInstance {
+    element: HTMLElement;
+    update?: (node: Readonly<InterfaceNode>, snapshot: InterfaceSnapshot) => void;
+    dispose?: () => void;
+}
+export type InterfaceDOMComponent = (node: Readonly<InterfaceNode>, context: {
+    renderChildren: () => HTMLElement[];
+    snapshot: InterfaceSnapshot;
+    signal: AbortSignal;
+}) => HTMLElement | InterfaceDOMComponentInstance;
+export type InterfaceDOMRegistry = Readonly<Record<string, InterfaceDOMComponent>>;
+/** Own a controller and one DOM mount with a single teardown. Component factories remain trusted host code. */
+export declare function createMountedInterface(target: HTMLElement, definition: InterfaceDefinition, options?: {
+    components?: InterfaceDOMRegistry;
+    allowedActions?: readonly string[];
+    onEvent?: (event: InterfaceEvent) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+}): InterfaceController & {
+    unmount(): void;
+};
+/** Mount a framework-neutral interface. The caller owns and disposes the controller separately. */
+export declare function mountInterface(target: HTMLElement, controller: InterfaceController, components?: InterfaceDOMRegistry, onError?: (error: unknown) => void): () => void;