@maxhealth.tech/prefab 0.3.9 → 0.3.10

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.3.10] — 2026-08-24
+
+### Added
+
+- **A2UI is now a first-class output target: `PrefabApp.toA2UI()` emits the same component tree as [A2UI](https://a2ui.org) v1.0.** A2UI is the Google-backed declarative agent-to-UI protocol, and it overlaps prefab's category exactly: the agent sends a component tree plus a data model, and the host's own renderer draws native widgets from it. It reaches renderers prefab has none of (React, Angular, Lit, Flutter, Swift, Jetpack Compose) with no iframe involved, and its agent-side SDK is Python-only, so a TypeScript authoring layer had no equivalent. Two structural gaps had to be bridged: A2UI keeps components in a flat adjacency list rather than a nested tree, and it binds dynamic values through JSON Pointers rather than interpolating `{{ }}` templates. `src/a2ui/` handles both, allocating ids deterministically so the same tree always emits byte-identical output.
+- **`display_a2ui()` and `registerA2uiResource()` serve A2UI over MCP**, under the `application/a2ui+json` MIME type as an embedded resource in a tool result or as a standalone `a2ui://` resource, per the [A2UI over MCP](https://a2ui.org/guides/a2ui_over_mcp/) guide. They sit alongside the existing `ui://` MCP Apps helpers rather than replacing them, so one server can offer both and let the host choose. A `ui://` viewer is a pure function of the package version and stays shared-cacheable; an `a2ui://` surface is rebuilt on every read and defaults to no caching, so `resolveCache` is now exported from `resource.ts` and takes the defaults as a parameter instead of hard-coding the viewer's.
+- **Multi Round-Trip input requests (protocol revision 2026-07-28).** The revision made the protocol core stateless and removed server-initiated `elicitation/create`; a handler now returns an `input_required` result and the client retries the call with the answers. That left `display_form()` reachable only on hosts that render UI. The same `AutoFormField[]` now also derives the restricted elicitation schema, so `display_form(fields, tool, { elicit: true })` asks for exactly what the rendered form asks for. `formSchema`, `formInputRequest`, `acceptedFormInput` and `inputResponse` are exported for handlers that compose the rounds themselves. `acceptedFormInput` validates the untrusted client response against the same field list: unknown keys, wrong types, out-of-bound numbers and unoffered enum values are dropped, and a missing required field fails the answer.
+- **The playground has an A2UI tab.** The preview pane now switches between the rendered UI and the same payload translated to A2UI, with the message and component counts, a pill per diagnostic kind, and every diagnostic listed underneath. A `Stream` toggle splits the output into the three-message form. Being able to see what a payload costs in translation, on the twenty shipped examples, says more than the mapping table does.
+- **`dist/a2ui.min.js`, the emitter as a standalone browser bundle.** The playground needs the emitter and does not need it inside `renderer.min.js`: almost no page that renders `$prefab` also emits A2UI, so folding it in would tax every consumer for a feature they do not use. It exposes `PrefabA2UI.emit()` and `PrefabA2UI.envelope()`, takes wire JSON rather than a component tree, and comes to 17 KB against the renderer's 108 KB. Attached to GitHub releases alongside the renderer bundles.
+- `AutoFormField` gained `options`, `multiple`, `description`, `min`, `max` and `default`. A field with `options` renders as a `Select` instead of a bare `Input` on the UI path, and as an enum on the elicitation path.
+- `McpDisplayResult<S>` pins `structuredContent` as present. Every display helper populates it, and the optional field on `McpToolResult` was forcing callers into a null check on something that is never absent.
+
+### Changed
+
+- **README, docs landing page and package description now lead with "TypeScript authoring for A2UI and MCP Apps".** The previous framing put "a superset of PrefectHQ's Python prefab-ui" in the second line, which tied the package's story to a project moving slowly and described an implementation detail rather than what the package is for. The superset relationship is still stated, one bullet down, where it belongs.
+
+### Fixed
+
+- **The A2UI emitter produced an invalid surface for most icons.** A2UI's `Icon.name` is a closed enum of 59 Material names, so an unrecognised value does not degrade to a fallback glyph — it fails schema validation and takes the component with it. prefab's `Icon(name)` accepts any string and follows Lucide, so every icon outside that enum emitted an invalid payload. The hand-written test view happened to use `Icon('mail')`, which is in the enum, so nothing caught it. `src/a2ui/icons.ts` now normalises the name, matches it against the enum case- and separator-insensitively, translates the Lucide names prefab itself ships (`AlertCircle` → `error`, `CheckCircle` → `check`), and drops the icon with a diagnostic when nothing means the same thing. The enum is duplicated as a literal because the package has no runtime dependencies and cannot read the catalog at emit time; a test asserts it matches the vendored catalog exactly, so a spec revision cannot let it drift.
+- **`test/component-types.test.ts` depended on which test file the runner reached first.** It compared the generated `src/core/component-types.ts` against the whole renderer registry, which is a process-wide singleton any module can add to. `test/renderer-destroy.test.ts` and `test/pipe-wire.test.ts` register a dozen widgets inside their test bodies, so once the runner reached either of them first, all twelve became "renderable but absent from the generated list" and thirteen assertions failed. It passed locally and failed on CI purely on file-discovery order, and adding the A2UI test files was enough to flip it. `registerAllComponents()` now records the delta it contributes as the built-in set, and both the generator and the sync check read that instead of the full registry. The generated list is unchanged at 119 types.
+
+### Internal
+
+- **Registry-wide A2UI invariants, rather than one hand-written view per mapper family.** The per-family views check that the mappings are right; they cannot check that they are safe, because a mapper is only covered if someone remembered to write a view for it, and the branches that matter most are the guards deciding "this cannot be expressed, drop it and say why". Coverage of `catalog.ts` sat at 72% of functions with nearly every uncovered line being one of those guards. `test/a2ui-registry.test.ts` now asserts two properties across all 81 registry entries, so a mapper added later is covered the moment it is registered: nothing a mapper emits is ever invalid, given generous props or none at all; and nothing is dropped without a diagnostic. The furnished pass additionally requires an actual component, since "emits nothing" would otherwise satisfy the first property trivially. This is what surfaced the `Icon` enum bug. `catalog.ts` is now at 100% of functions and 97% of lines.
+- Removed `hasTemplate` and `isTemplatedList`, both exported with no caller anywhere.
+- Emitted A2UI payloads are validated in CI against the official v1.0 JSON Schemas, vendored under `test/fixtures/a2ui/v1_0/` (Apache-2.0, with a `NOTICE.md` recording the upstream commit) and refreshable with `bun scripts/sync-a2ui-schemas.ts`. They are checked in rather than fetched so the suite runs offline. The upstream YAML conformance suites were considered and rejected: they exercise SDK internals (streaming parser, catalog pruning, validator behaviour) that a producer does not implement, whereas the schemas define exactly what a producer must emit. Two structural rules the schemas cannot express — every child reference resolves, and every component is reachable from `root` — are asserted separately, taken from `conformance/core/validator.yaml`.
+
 ## [0.3.9] — 2026-08-07
 
 ### Added

package/README.md

@@ -1,30 +1,39 @@
 # prefab
 
 [![CI](https://github.com/Max-Health-Inc/prefab/actions/workflows/ci.yml/badge.svg)](https://github.com/Max-Health-Inc/prefab/actions/workflows/ci.yml)
-[![tests](https://img.shields.io/badge/tests-1077%20passing%20(100%25)-brightgreen)](https://github.com/Max-Health-Inc/prefab/actions/workflows/ci.yml)
+[![tests](https://img.shields.io/badge/tests-2009%20passing%20(100%25)-brightgreen)](https://github.com/Max-Health-Inc/prefab/actions/workflows/ci.yml)
 [![@maxhealth.tech/prefab](https://img.shields.io/npm/v/@maxhealth.tech/prefab?label=%40maxhealth.tech%2Fprefab)](https://www.npmjs.com/package/@maxhealth.tech/prefab)
 [![prefab-protocol](https://img.shields.io/badge/prefab--protocol-v0.3-brightgreen)](https://maxhealth.tech/prefab/reference/wire-format.html)
+[![A2UI](https://img.shields.io/badge/A2UI-v1.0-4285F4)](https://maxhealth.tech/prefab/guide/a2ui.html)
 [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-The TypeScript full-stack framework for MCP app UIs: author server-side, ship JSON, render anywhere.
+TypeScript authoring for **A2UI** and **MCP Apps**: build the UI server-side, emit either wire format, render anywhere.
 
-A superset of PrefectHQ's Python [prefab-ui](https://github.com/PrefectHQ/prefab), on the **`$prefab` v0.3 wire protocol** (still renders legacy `0.2` payloads).
+**[Live Demo](https://maxhealth.tech/prefab/demo/)** · **[Playground](https://maxhealth.tech/prefab/playground/)** · **[Docs](https://maxhealth.tech/prefab/)**
 
-**[Live Demo](https://maxhealth.tech/prefab/demo/)** · **[Playground](https://maxhealth.tech/prefab/playground/)**
+Agent UIs have settled on two shapes. [MCP Apps](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp) ships HTML that the host renders in a sandboxed iframe. [A2UI](https://a2ui.org) ships a declarative component tree that the host's own renderer draws as native widgets. Writing a UI twice to reach both is the problem this package removes.
 
-Write MCP servers in **TypeScript/Bun** and generate the same wire format that Python servers produce. Render the output in **any web app** with the included vanilla DOM renderer. Full circle: server-side DSL → JSON → browser UI.
+You describe the interface once with a typed component API, and prefab emits whichever wire format the host wants:
+
+```ts
+const app = new PrefabApp({ view: Column({ children: [H1('Users'), autoTable(rows)] }) })
+
+app.toJSON()   // $prefab  — rendered by prefab's renderer, in an MCP Apps iframe or any web app
+app.toA2UI()   // A2UI v1.0 — rendered natively by React, Angular, Lit, Flutter, Swift, Compose
+```
 
 - **115+ components** — layout, form, data, charts, media, interactive, control flow
+- **Auto-renderers** — `autoTable()`, `autoChart()`, `autoForm()`, `autoMetrics()` and more
+- **Two wire formats** — `$prefab` v0.3 (superset of PrefectHQ's Python [prefab-ui](https://github.com/PrefectHQ/prefab), still renders legacy `0.2`) and [A2UI v1.0](https://a2ui.org), schema-validated against the official specification
+- **MCP-native** — `display()`, `display_a2ui()`, `ui://` and `a2ui://` resource helpers, `input_required` for the 2026-07-28 revision
 - **Reactive state** — `rx()` expressions, `SetState`/`ToggleState`/`AppendState` actions
-- **MCP-native** — `display()`, `display_form()`, `CallTool`, `SendMessage` built in
 - **Browser renderer** — zero dependencies, vanilla DOM (optional separate import)
 - **PostMessage bridge** — `app()` factory with dual-protocol handshake, host theme, lifecycle hooks
-- **Auto-renderers** — `autoTable()`, `autoChart()`, `autoForm()`, `autoMetrics()` and more
 
 ## Works Everywhere
 
-The renderer is **vanilla DOM** — no framework dependency. Drop it into any web app:
+On the `$prefab` path the renderer is **vanilla DOM** — no framework dependency. Drop it into any web app:
 
 - **React** — mount into a `ref` div
 - **Vue / Svelte / Angular** — same, it's just DOM
@@ -32,7 +41,7 @@ The renderer is **vanilla DOM** — no framework dependency. Drop it into any we
 - **Electron / Tauri** — desktop apps with web views
 - **Any iframe** — MCP Apps, embedded widgets, sandboxed UIs
 
-Any app that connects to MCP servers can render `$prefab` tool output as rich interactive UI — tables, charts, forms, badges — with zero custom code.
+On the A2UI path there is no prefab renderer at all: the host draws the components itself, so the same tree reaches the A2UI renderers for React, Angular, Lit, Flutter, Swift and Jetpack Compose. See the [A2UI guide](https://maxhealth.tech/prefab/guide/a2ui) for the mapping table and what degrades.
 
 ## Install
 
@@ -361,6 +370,62 @@ return display_error('User not found', `No user with id ${id}.`, {
 })
 ```
 
+### Asking for input (MCP 2026-07-28)
+
+The revision removed server-initiated elicitation: a handler asks for input by
+returning an `input_required` result, and the client retries the call with the
+answers. The same field list drives both paths, so a host with no UI surface
+still gets the form:
+
+```ts
+const FIELDS = [
+  { name: 'email', label: 'Email', type: 'email', required: true },
+  { name: 'plan', label: 'Plan', options: [{ value: 'pro' }, { value: 'team' }] },
+]
+
+// Rendered as prefab UI, submitting to the `signup` tool:
+display_form(FIELDS, 'signup', { title: 'Create your account' })
+
+// Or asked natively by the client, which then retries the call:
+display_form(FIELDS, 'signup', { title: 'Create your account', elicit: true })
+```
+
+Read the answer back with `acceptedFormInput`, which checks the untrusted client
+response against the same fields. Full walkthrough in
+[Asking for Input](https://maxhealth.tech/prefab/guide/input-required).
+
+## A2UI
+
+Emit the same tree as [A2UI](https://a2ui.org) and let the host render it natively:
+
+```ts
+const { messages, diagnostics } = app.toA2UI()
+```
+
+Serve it over MCP under the `application/a2ui+json` MIME type:
+
+```ts
+// Per-call, as an embedded resource in a tool result
+server.registerTool('list-users', schema, async () => display_a2ui(autoTable(await db.users())))
+
+// Or as a static a2ui:// resource the host can cache
+registerA2uiResource(server, () => Column({ children: [H1('Settings')] }))
+```
+
+Or translate a payload in the browser, from a bundle separate to the renderer:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@maxhealth.tech/prefab/dist/a2ui.min.js"></script>
+<script>const { messages, diagnostics } = PrefabA2UI.emit(wireJson)</script>
+```
+
+prefab has 115+ components and the A2UI Basic catalog has 18, so parts of the
+tree change shape on the way across. `diagnostics` reports every one — nothing
+degrades silently. Payloads are validated against the official A2UI v1.0 JSON
+Schemas in CI. The [playground](https://maxhealth.tech/prefab/playground/) has an
+A2UI tab that shows the translation and its diagnostics live. See the
+[A2UI guide](https://maxhealth.tech/prefab/guide/a2ui).
+
 ### `rendererHtml()` — Viewer HTML Shell
 
 Generate the complete HTML page for an MCP Apps viewer resource. Loads `prefab.css` + `renderer.auto.min.js` from the CDN automatically — no manual script wiring needed:
@@ -498,6 +563,7 @@ import { ... } from '@maxhealth.tech/prefab/rx'         // Rx expressions only
 import { ... } from '@maxhealth.tech/prefab/charts'     // Chart components only
 import { ... } from '@maxhealth.tech/prefab/auto'       // Auto-renderers
 import { ... } from '@maxhealth.tech/prefab/mcp'        // MCP display helpers
+import { ... } from '@maxhealth.tech/prefab/a2ui'      // A2UI emitter
 import { ... } from '@maxhealth.tech/prefab/renderer'   // Browser renderer
 import '@maxhealth.tech/prefab/prefab.css'              // Default stylesheet
 ```
@@ -506,7 +572,7 @@ import '@maxhealth.tech/prefab/prefab.css'              // Default stylesheet
 
 ```bash
 bun install          # Install dependencies
-bun test             # Run tests (996 passing)
+bun test             # Run tests
 bun run build        # TypeScript compile + IIFE bundle
 bun run lint         # ESLint
 bun run typecheck    # Type check without emitting

package/dist/a2ui/browser.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Browser entry for the A2UI emitter — `dist/a2ui.min.js`.
+ *
+ * Bundled separately from `renderer.min.js` on purpose. The renderer is what
+ * every `$prefab` page loads, and emitting A2UI is something almost none of
+ * them do, so folding the emitter in would tax every consumer for a feature
+ * they do not use. Keeping it apart also means the two can be loaded
+ * independently: a tool that only translates payloads needs no renderer at all.
+ *
+ * The emitter takes wire JSON and returns wire JSON, so nothing here needs the
+ * component API. That is what keeps the bundle small.
+ *
+ * ```html
+ * <script src="https://cdn.jsdelivr.net/npm/@maxhealth.tech/prefab/dist/a2ui.min.js"></script>
+ * <script>
+ *   const { messages, diagnostics } = PrefabA2UI.emit(wireJson)
+ * </script>
+ * ```
+ */
+import { type A2uiEmitOptions, type A2uiEmitResult } from './emit.js';
+import { mappedTypes } from './catalog.js';
+import { type A2uiMessage, type A2uiMessageList } from './types.js';
+/**
+ * Emit A2UI from a `$prefab` payload.
+ *
+ * Accepts `unknown` because the caller is usually handing over parsed editor
+ * text or a tool result, neither of which is typed. A payload without a `view`
+ * is rejected here rather than producing an empty surface further downstream.
+ */
+declare function emit(wire: unknown, options?: A2uiEmitOptions): A2uiEmitResult;
+/** Wrap messages in the list envelope, for transports needing a JSON object. */
+declare function envelope(messages: A2uiMessage[]): A2uiMessageList;
+declare const PrefabA2UI: {
+    emit: typeof emit;
+    envelope: typeof envelope;
+    /** Every prefab component type with a first-class A2UI mapping. */
+    mappedTypes: typeof mappedTypes;
+    VERSION: string;
+    A2UI_VERSION: string;
+    A2UI_BASIC_CATALOG: string;
+    A2UI_MIME: string;
+    A2UI_SCHEME: string;
+};
+export default PrefabA2UI;
+export { emit, envelope };
+//# sourceMappingURL=browser.d.ts.map

package/dist/a2ui/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/a2ui/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAY,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAG1C,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,YAAY,CAAA;AAEnB;;;;;;GAMG;AACH,iBAAS,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,cAAc,CAKtE;AAED,gFAAgF;AAChF,iBAAS,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,eAAe,CAE1D;AAED,QAAA,MAAM,UAAU;;;IAGd,mEAAmE;;;;;;;CAOpE,CAAA;AAED,eAAe,UAAU,CAAA;AACzB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA"}

package/dist/a2ui/browser.js

@@ -0,0 +1,58 @@
+/**
+ * Browser entry for the A2UI emitter — `dist/a2ui.min.js`.
+ *
+ * Bundled separately from `renderer.min.js` on purpose. The renderer is what
+ * every `$prefab` page loads, and emitting A2UI is something almost none of
+ * them do, so folding the emitter in would tax every consumer for a feature
+ * they do not use. Keeping it apart also means the two can be loaded
+ * independently: a tool that only translates payloads needs no renderer at all.
+ *
+ * The emitter takes wire JSON and returns wire JSON, so nothing here needs the
+ * component API. That is what keeps the bundle small.
+ *
+ * ```html
+ * <script src="https://cdn.jsdelivr.net/npm/@maxhealth.tech/prefab/dist/a2ui.min.js"></script>
+ * <script>
+ *   const { messages, diagnostics } = PrefabA2UI.emit(wireJson)
+ * </script>
+ * ```
+ */
+import { emitA2UI } from './emit.js';
+import { mappedTypes } from './catalog.js';
+import { VERSION } from '../core/version.js';
+import { A2UI_BASIC_CATALOG, A2UI_MIME, A2UI_SCHEME, A2UI_VERSION, } from './types.js';
+/**
+ * Emit A2UI from a `$prefab` payload.
+ *
+ * Accepts `unknown` because the caller is usually handing over parsed editor
+ * text or a tool result, neither of which is typed. A payload without a `view`
+ * is rejected here rather than producing an empty surface further downstream.
+ */
+function emit(wire, options) {
+    if (wire == null || typeof wire !== 'object' || !('view' in wire)) {
+        throw new TypeError('PrefabA2UI.emit: expected a $prefab payload with a "view"');
+    }
+    return emitA2UI(wire, options);
+}
+/** Wrap messages in the list envelope, for transports needing a JSON object. */
+function envelope(messages) {
+    return { messages };
+}
+const PrefabA2UI = {
+    emit,
+    envelope,
+    /** Every prefab component type with a first-class A2UI mapping. */
+    mappedTypes,
+    VERSION,
+    A2UI_VERSION,
+    A2UI_BASIC_CATALOG,
+    A2UI_MIME,
+    A2UI_SCHEME,
+};
+export default PrefabA2UI;
+export { emit, envelope };
+if (typeof window !== 'undefined') {
+    ;
+    window.PrefabA2UI = PrefabA2UI;
+}
+//# sourceMappingURL=browser.js.map

package/dist/a2ui/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/a2ui/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,QAAQ,EAA6C,MAAM,WAAW,CAAA;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AAE5C,OAAO,EACL,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,YAAY,GAGb,MAAM,YAAY,CAAA;AAEnB;;;;;;GAMG;AACH,SAAS,IAAI,CAAC,IAAa,EAAE,OAAyB;IACpD,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,SAAS,CAAC,2DAA2D,CAAC,CAAA;IAClF,CAAC;IACD,OAAO,QAAQ,CAAC,IAAwB,EAAE,OAAO,CAAC,CAAA;AACpD,CAAC;AAED,gFAAgF;AAChF,SAAS,QAAQ,CAAC,QAAuB;IACvC,OAAO,EAAE,QAAQ,EAAE,CAAA;AACrB,CAAC;AAED,MAAM,UAAU,GAAG;IACjB,IAAI;IACJ,QAAQ;IACR,mEAAmE;IACnE,WAAW;IACX,OAAO;IACP,YAAY;IACZ,kBAAkB;IAClB,SAAS;IACT,WAAW;CACZ,CAAA;AAED,eAAe,UAAU,CAAA;AACzB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;AAEzB,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;IAClC,CAAC;IAAC,MAA6C,CAAC,UAAU,GAAG,UAAU,CAAA;AACzE,CAAC"}

package/dist/a2ui/catalog.d.ts

@@ -0,0 +1,51 @@
+/**
+ * prefab component type → A2UI Basic catalog mapper registry.
+ *
+ * prefab ships 115+ components; the A2UI Basic catalog defines 18. The gap is
+ * closed by degradation rather than by refusing to emit: a `Badge` becomes
+ * `Text`, an `Alert` becomes a `Card` wrapping its body, an `H2` becomes `Text`
+ * carrying a Markdown `##` prefix (which the Basic catalog's `Text` explicitly
+ * supports). Every degradation is recorded as a diagnostic, so what changed is
+ * visible at emit time instead of in someone else's renderer.
+ *
+ * A mapper returns the A2UI properties for one node without its `id`; the
+ * emitter allocates ids and owns the adjacency list. Mappers that expand one
+ * prefab node into several A2UI components (`Metric`, the table family in
+ * `./table.ts`) push the extras through `ctx.push` and return the root of the
+ * expansion.
+ */
+import type { ComponentJSON } from '../core/component.js';
+import type { A2uiComponentProps, A2uiAction, A2uiDiagnosticKind } from './types.js';
+/** A2UI properties for one component, before the emitter assigns its id. */
+export type A2uiProps = A2uiComponentProps;
+/** Services the emitter lends to a mapper. */
+export interface EmitContext {
+    /** Emit one child subtree, returning its id, or `undefined` if it was dropped. */
+    child(node: ComponentJSON): string | undefined;
+    /** Emit several child subtrees, returning the ids that survived. */
+    children(nodes: unknown): string[];
+    /** Emit `nodes` as a single child, wrapping them in a Column when there are several. */
+    single(nodes: unknown): string | undefined;
+    /** Add a component the mapper synthesized, returning its id. */
+    push(props: A2uiProps): string;
+    /** Record a translation loss. */
+    note(kind: A2uiDiagnosticKind, subject: string, detail: string): void;
+    /** Convert a serialized prefab action into an A2UI action. */
+    action(value: unknown, subject: string): A2uiAction | undefined;
+    /** Seed a literal value into the surface data model, returning its JSON Pointer. */
+    bindData(key: string, value: unknown): string;
+}
+export type Mapper = (node: ComponentJSON, ctx: EmitContext) => A2uiProps | undefined;
+export declare function mapperFor(type: string): Mapper | undefined;
+export declare function isConsumedByParent(type: string): boolean;
+/** Every prefab type with a first-class mapping, for docs and tests. */
+export declare function mappedTypes(): string[];
+/**
+ * Last-resort mapping for a type the registry does not name.
+ *
+ * A node with children becomes a Column, a node with text becomes a Text, and
+ * anything else is dropped. This is what keeps a tree built from unmapped
+ * components emitting something coherent instead of failing outright.
+ */
+export declare function fallbackMapper(node: ComponentJSON, ctx: EmitContext): A2uiProps | undefined;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/a2ui/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/a2ui/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAKpF,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG,kBAAkB,CAAA;AAE1C,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,kFAAkF;IAClF,KAAK,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAAA;IAC9C,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAAA;IAClC,wFAAwF;IACxF,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAA;IAC1C,gEAAgE;IAChE,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAAA;IAC9B,iCAAiC;IACjC,IAAI,CAAC,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrE,8DAA8D;IAC9D,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;IAC/D,oFAAoF;IACpF,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAAA;CAC9C;AAED,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,WAAW,KAAK,SAAS,GAAG,SAAS,CAAA;AAybrF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1D;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wEAAwE;AACxE,wBAAgB,WAAW,IAAI,MAAM,EAAE,CAEtC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAsB3F"}