@adia-ai/a2ui-runtime 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,215 @@
+# Changelog — @adia-ai/a2ui-runtime
+
+Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+[Semantic Versioning](https://semver.org/).
+
+> **Renamed from `@adia-ai/a2ui-utils` in v0.3.0.** All releases
+> through v0.2.5 published as `@adia-ai/a2ui-utils`. The package's own
+> description has always called it the "A2UI runtime"; v0.3.0 aligns
+> the package name with its purpose. See v0.3.0 entry for migration
+> notes.
+
+## [Unreleased]
+
+_No pending changes._
+
+## [0.3.0] - 2026-05-05
+
+**9-package lockstep cut + package rename + LLM extraction.** All 9 published `@adia-ai/*` packages bump 0.2.5 → 0.3.0 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` dep ranges bump `^0.2.0` → `^0.3.0`.
+
+This is a **minor cut on top of v0.2.5 with two BREAKING changes for npm consumers** (acceptable under pre-1.0 semver):
+1. **Package renamed** — `@adia-ai/a2ui-utils` → `@adia-ai/a2ui-runtime` (this package).
+2. New 9th lockstep package `@adia-ai/llm` extracted from `@adia-ai/a2ui-compose/llm` (sibling concern).
+
+Lockstep policy expanded from 8 to 9 packages. The CI gate `lockstep-versioning` now enforces all 9 share one version.
+
+### Changed
+
+- **Package name: `@adia-ai/a2ui-utils` → `@adia-ai/a2ui-runtime`.** Pure rename. No API change. Source path moved from `packages/a2ui/utils/` → `packages/a2ui/runtime/` to match the new name. The `name` field in package.json is the only consumer-visible change; all subpath exports (`./registry`, `./renderer`, `./streams`, `./surface`, `./wiring`, `./dockables`) preserved verbatim.
+- `version`: `0.2.5` → `0.3.0`.
+
+### Migration
+
+Update `package.json`:
+
+```diff
+- "@adia-ai/a2ui-utils": "^0.2.0"
++ "@adia-ai/a2ui-runtime": "^0.3.0"
+```
+
+Update imports across the codebase:
+
+```diff
+- import { A2UIRenderer } from '@adia-ai/a2ui-utils/renderer';
++ import { A2UIRenderer } from '@adia-ai/a2ui-runtime/renderer';
+
+- import { registry } from '@adia-ai/a2ui-utils/registry';
++ import { registry } from '@adia-ai/a2ui-runtime/registry';
+```
+
+The `@adia-ai/a2ui-utils@0.2.5` and earlier remain on npm and continue to work; the rename only affects new installs and explicit upgrades. There is no deprecated stub on the old name — consumers who don't upgrade keep their existing `@adia-ai/a2ui-utils@0.2.5` installation.
+
+### Why
+
+"utils" undersold what this package is and collided visually with `web-modules/runtime/` (which holds `<a2ui-root>`, the surface element). The package's own description has always called it "A2UI runtime — renderer, registry, streams"; the name now matches.
+
+## [0.2.5] - 2026-05-04
+
+**8-package lockstep cut.** All 8 published `@adia-ai/*` packages bump 0.2.4 → 0.2.5 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` dep ranges remain at `^0.2.0` (covers 0.2.5 under semver — patch-cut asymmetry).
+
+This is a **patch cut on top of v0.2.4, no BREAKING changes.** Substantive content lives in `web-components` (new `<fields-ui>` form-grid primitive + `draggable-list-item` last-item drop-zone fix, both surfaced by the Tasks UI Playground at `docs/projects/tasks-playground/`); `a2ui-corpus` ships a catalog regen for the new `<fields-ui>` yaml. `a2ui-utils` rides along at version bump only — no source change.
+
+### Changed
+
+- `version`: `0.2.4` → `0.2.5`.
+- Internal `@adia-ai/*` dep ranges: unchanged at `^0.2.0` (covers `0.2.5` under semver — patch-cut asymmetry).
+
+## [0.2.4] - 2026-05-04
+
+**8-package lockstep cut.** All 8 published `@adia-ai/*` packages bump 0.2.3 → 0.2.4 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` dep ranges remain at `^0.2.0` (covers 0.2.4 under semver — patch-cut asymmetry).
+
+This is a **patch cut on top of v0.2.3, no BREAKING changes.** Substantive content lives in `web-components` (Tier 4 trait library lift, 11 new traits + 2 architectural rewrites, plus accumulated bug fixes); `a2ui-corpus` ships a catalog regen for the new `<demo-toggle-ui>` primitive. Six packages ride along at version + dep-range bump.
+
+### Changed
+
+- `version`: `0.2.3` → `0.2.4`.
+- `dependencies["@adia-ai/a2ui-utils"]`: `^0.2.0` (covers `0.2.4`).
+
+This package's source tree is byte-identical to 0.2.3. The cut bumps version + the internal dep range only, per the lockstep policy.
+
+_Nothing yet._
+
+---
+
+---
+
+## [0.2.3] - 2026-05-04
+
+**Lockstep cut.** All 8 published `@adia-ai/*` packages bump
+0.2.2 → 0.2.3 per
+[`docs/specs/package-architecture.md` § 15](../../../../docs/specs/package-architecture.md#15-versioning-policy).
+Patch cut — no breaking changes.
+
+### Changed
+
+- `version`: `0.2.2` → `0.2.3`.
+
+### No source changes
+
+`@adia-ai/a2ui-utils` source is byte-identical to `0.2.2`. The cut bumps version only.
+
+## [0.2.2] — 2026-05-02
+
+**Lockstep cut.** All 8 published `@adia-ai/*` packages bump 0.2.1 → 0.2.2 per [`docs/specs/package-architecture.md` § 15](../../../../docs/specs/package-architecture.md#15-versioning-policy). Patch cut — no breaking changes.
+
+### Changed
+
+- `version`: `0.2.1` → `0.2.2`.
+
+### No source changes
+
+`a2ui-utils` source is byte-identical to `0.2.1`. The cut bumps version only.
+
+---
+
+## [0.2.1] — 2026-05-02
+
+**Lockstep cut + A2UI registry mappings (`Field`/`Rating`/`ListItem`/`NavItem`/`NavGroup`).** All 8 published `@adia-ai/*` packages bump 0.2.0 → 0.2.1 per [`docs/specs/package-architecture.md` § 15](../../../../docs/specs/package-architecture.md#15-versioning-policy). Patch cut — no breaking changes.
+
+### Changed
+
+- `version`: `0.2.0` → `0.2.1`.
+
+### Added — A2UI registry mappings (2026-05-02)
+
+Five new A2UI type → AdiaUI tag mappings in `registry.js`:
+
+- `Field` → `field-ui`
+- `Rating` → `rating-ui`
+- `ListItem` → `list-item-ui`
+- `NavItem` → `nav-item-ui`
+- `NavGroup` → `nav-group-ui`
+
+All 5 components existed in `@adia-ai/web-components`; the registry hadn't been kept in sync. Closing this gap fixes 28/113 hand-authored patterns that previously rendered as `[unknown: X]` placeholders when imported into `/site/playground/a2ui-editor`, plus the render-preview's `streamed-list` example. The `NavItem` and `NavGroup` additions also align with [ADR-0015](../../../.brain/adrs/0015-three-tier-naming-convention.md)'s nav consolidation (the retired `SectionNav`/`SectionNavItem` types are migrated in `@adia-ai/a2ui-corpus`).
+
+Smoke side-effect: zettel score 91 → 92; `smoke:engines` flipped from `valid=false score=98/91` to `valid=true score=100/92` because the unregistered types were tripping validation. Per-finding triage in [`docs/reports/playground-examples-review-2026-05-02.md`](../../../docs/reports/playground-examples-review-2026-05-02.md).
+
+---
+
+## [0.2.0] — 2026-05-02
+
+**Lockstep cut.** All 8 published `@adia-ai/*` packages now share one
+version, governed by [`docs/specs/package-architecture.md` § 15
+(Versioning Policy)](../../../../docs/specs/package-architecture.md#15-versioning-policy).
+
+### Changed
+
+- `version`: `0.0.2` → `0.2.0`.
+
+### No source changes
+
+A2UI runtime source (renderer, registry, streams, surface manifest,
+wiring primitives, controllers, dockables) is byte-identical to 0.0.2.
+The cut bumps the version only — utils has no internal `@adia-ai/*`
+dependencies. Five sibling packages depend on this package via
+`^0.0.2` (now `^0.2.0`), which under npm pre-1.0 semver locks them to
+the exact version; the lockstep cut switches them to a working range.
+
+---
+
+## [0.0.2] — 2026-04-22
+
+Controllers-move fix. `0.0.1` published but was broken for any
+surface that declared a controller: `wiring-registry.js` held lazy
+`await import('../controllers/*.js')` calls that resolved to
+`packages/a2ui/controllers/` (nonexistent) because the controllers
+subdir still lived under `packages/web-components/` at the time of
+the initial split. `0.0.2` moves `controllers/` into this package
+alongside the wiring code that uses them and retargets the dynamic
+imports to `./controllers/`. **Consumers on `0.0.1` should upgrade
+to `0.0.2`; `0.0.1` is broken for any surface that declares a
+controller.**
+
+### Included
+
+- **Controllers** — `controllers/` subdir with `FormController`,
+  `DataStreamController`, `SelectionController`, `ToggleController`,
+  `AccordionController`, `StateMachineController`, plus the shared
+  `BaseController`. Lazy-loaded via dynamic imports from
+  `wiringRegistry`. Pure JS — no web-component dependency; only
+  extend `BaseController` (host management + subscription + notify).
+  Moved in from `packages/web-components/controllers/` after the
+  initial carve-out surfaced that `wiring-registry.js` lazy-imports
+  these at runtime and the imports couldn't resolve — the six types
+  are registered in `wiringRegistry` for lazy resolution so a
+  surface only loads what it declares.
+- **`A2UIRenderer`** — processes A2UI protocol messages (`createSurface`,
+  `updateComponents`, `wireComponents`, `updateDataModel`, `destroySurface`)
+  and writes custom elements into a container. Batched via
+  `requestAnimationFrame`.
+- **Registry** — `registry`, `resolveTag`, `registerType`. A2UI protocol
+  component name → custom-element tag map, extensible at runtime.
+- **Transports** — `sseStream`, `wsStream`, `mockStream`, `mcpStream`,
+  `jsonlStream`. Normalize inbound A2UI messages from the respective
+  transports into a consistent async iterable.
+- **`SurfaceManifest`** — design-time manifest model for multi-surface
+  apps.
+- **`Surface`** — runtime surface lifecycle primitive.
+- **Wiring layer** — `WiringEngine`, `wiringRegistry`, `createDockables`,
+  and the dockable base classes (`Dockable`, `ControllerDock`,
+  `DataSourceDock`, `ActionDock`, `ProviderDock`, `LifecycleDock`).
+
+### Notes on the carve-out
+
+- Dead exports from the old `web-components/a2ui/index.js`
+  (`ContextStore`, `ManifestRuntime`, `A2UIValidator`, `A2UIGenerator`,
+  `savePattern`, `importPattern`, `buildPatternJSON`, `retrieval/*`,
+  `feedbackStore`) were not carried forward — the referenced source
+  files did not exist in this repo. The new `index.js` exports only
+  live symbols.
+- `manifest-runtime.js` was deleted during the move — it referenced
+  `./context-store.js` which had never been authored. Will return if
+  and when a context-store surface is designed.
+- The `ActionDock` constant that mapped A2UI event names to DOM event
+  names was renamed to `A2UI_EVENT_TO_DOM` for clarity. Its shape is
+  unchanged.

package/README.md

@@ -0,0 +1,87 @@
+# @adia-ai/a2ui-runtime
+
+A2UI runtime — renderer, registry, streams, surface manifest, and wiring
+primitives for the A2UI (Agent-to-UI) protocol. Framework-agnostic;
+pairs with any A2UI-conformant component set.
+
+## Install
+
+```bash
+npm install @adia-ai/a2ui-runtime
+```
+
+Typically paired with `@adia-ai/web-components` (which provides the
+custom-element catalog the renderer resolves against):
+
+```bash
+npm install @adia-ai/a2ui-runtime @adia-ai/web-components
+```
+
+## What's in the box
+
+- **`A2UIRenderer`** — processes A2UI protocol messages and writes
+  custom elements to a container.
+- **`registry`** / **`resolveTag`** / **`registerType`** — A2UI protocol
+  component name → custom-element tag map. Extensible via
+  `registerType`.
+- **Transports** — `sseStream`, `wsStream`, `mockStream`, `mcpStream`,
+  `jsonlStream`. Normalize inbound A2UI messages from SSE, WebSocket,
+  mock fixtures, MCP tool calls, or JSONL logs.
+- **`SurfaceManifest`** / **`Surface`** — design-time surface shape +
+  runtime lifecycle for cross-surface data flow.
+- **Wiring primitives** — `WiringEngine`, `wiringRegistry`,
+  `createDockables`, plus the dockable base classes
+  (`ControllerDock`, `DataSourceDock`, `ActionDock`, `ProviderDock`,
+  `LifecycleDock`).
+- **Controllers** — lazy-loaded runtime state managers at
+  `controllers/`: `FormController`, `DataStreamController`,
+  `SelectionController`, `ToggleController`, `AccordionController`,
+  `StateMachineController`, plus `BaseController`. Registered in the
+  wiring registry for lazy resolution; surface only imports what it
+  declares.
+
+## Minimal usage
+
+```js
+import { A2UIRenderer, jsonlStream } from '@adia-ai/a2ui-runtime';
+import '@adia-ai/web-components';   // register the custom elements
+
+const container = document.querySelector('#app');
+const renderer = new A2UIRenderer(container);
+
+for await (const msg of jsonlStream(fetch('/api/ui-trace.jsonl').then(r => r.body))) {
+  renderer.process(msg);
+}
+```
+
+For declarative embedding in HTML, use the `<a2ui-root>` element from
+`@adia-ai/web-modules/runtime` — it wraps `A2UIRenderer` + stream
+wiring in a custom element. (Was `@adia-ai/web-components/patterns/`
+prior to the package split per ADR-0012.)
+
+## Public entry points
+
+The default export bundles the common surface. Granular subpath
+imports are available if you want to tree-shake:
+
+```js
+import { A2UIRenderer }    from '@adia-ai/a2ui-runtime/renderer';
+import { resolveTag }      from '@adia-ai/a2ui-runtime/registry';
+import { sseStream }       from '@adia-ai/a2ui-runtime/streams';
+import { SurfaceManifest } from '@adia-ai/a2ui-runtime/surface';
+import { WiringEngine }    from '@adia-ai/a2ui-runtime/wiring';
+import { ActionDock }      from '@adia-ai/a2ui-runtime/dockables';
+```
+
+## Relationship to other packages
+
+- **`@adia-ai/web-components`** — the custom-element catalog the
+  renderer resolves tags against. Depends on this package at runtime
+  (as of web-components v0.0.4).
+- **`@adia-ai/web-modules/runtime/a2ui-root`** — the declarative
+  `<a2ui-root>` custom element; wraps this package's renderer + stream.
+  Extracted from `@adia-ai/web-components/patterns/` per ADR-0012.
+
+## License
+
+(See repository root.)

package/controllers/accordion.js

@@ -0,0 +1,73 @@
+import { BaseController } from './base.js';
+
+/**
+ * Accordion controller — manages expandable section state.
+ * Sets [data-accordion-expanded] on expanded sections.
+ */
+export class AccordionController extends BaseController {
+  static schema = Object.freeze({
+    name: 'accordion',
+    state: { expanded: 'Set', multiple: 'boolean' },
+    commands: ['toggle', 'expand', 'collapse', 'collapseAll', 'expandAll'],
+    attributes: ['data-accordion-expanded'],
+  });
+
+  #expanded = new Set();
+  #multiple = false;
+
+  constructor({ multiple = false, initial = [] } = {}) {
+    super();
+    this.#multiple = multiple;
+    for (const key of initial) this.#expanded.add(String(key));
+  }
+
+  onDisconnect(host) {
+    const sections = host.querySelectorAll('[data-accordion-expanded]');
+    for (const s of sections) s.removeAttribute('data-accordion-expanded');
+  }
+
+  getState() {
+    return { expanded: new Set(this.#expanded), multiple: this.#multiple };
+  }
+
+  reflect() {
+    if (!this.host) return;
+    const sections = this.host.querySelectorAll('[data-accordion-key]');
+    for (const section of sections) {
+      const key = section.getAttribute('data-accordion-key');
+      if (this.#expanded.has(key)) section.setAttribute('data-accordion-expanded', '');
+      else section.removeAttribute('data-accordion-expanded');
+    }
+  }
+
+  commands = {
+    toggle: (key) => {
+      key = String(key);
+      if (this.#expanded.has(key)) this.#expanded.delete(key);
+      else {
+        if (!this.#multiple) this.#expanded.clear();
+        this.#expanded.add(key);
+      }
+      this.notify();
+    },
+    expand: (key) => {
+      key = String(key);
+      if (!this.#multiple) this.#expanded.clear();
+      this.#expanded.add(key);
+      this.notify();
+    },
+    collapse: (key) => {
+      this.#expanded.delete(String(key));
+      this.notify();
+    },
+    collapseAll: () => {
+      this.#expanded.clear();
+      this.notify();
+    },
+    expandAll: (keys) => {
+      if (!this.#multiple) return;
+      for (const k of keys) this.#expanded.add(String(k));
+      this.notify();
+    },
+  };
+}

package/controllers/base.js

@@ -0,0 +1,68 @@
+/**
+ * BaseController — base class for all controllers.
+ *
+ * Provides: host management, subscription, notification, reflection.
+ * Subclass implements: onConnect, onDisconnect, getState, reflect, commands.
+ *
+ * Usage:
+ *   class ToggleController extends BaseController {
+ *     static schema = { name: 'toggle', state: { on: 'boolean' }, commands: ['toggle', 'set'], attributes: ['data-toggle-on'] };
+ *     #on = false;
+ *     getState() { return { on: this.#on }; }
+ *     reflect() { ... }
+ *     commands = { toggle: () => { ... this.notify(); } };
+ *   }
+ */
+
+const validated = new WeakSet();
+
+export class BaseController {
+  #host = null;
+  #subs = new Set();
+
+  get host() { return this.#host; }
+
+  connect(host) {
+    const ctor = this.constructor;
+    if (!validated.has(ctor) && ctor !== BaseController) {
+      validated.add(ctor);
+      if (!ctor.schema) {
+        console.warn(`AdiaUI: ${ctor.name} extends BaseController without static schema`);
+      }
+      if (this.getState === BaseController.prototype.getState) {
+        console.error(`AdiaUI: ${ctor.schema?.name ?? ctor.name} must implement getState()`);
+      }
+    }
+    if (this.#host && this.#host !== host) {
+      console.warn(`AdiaUI: ${ctor.schema?.name ?? ctor.name} already connected to a different host`);
+    }
+    this.#host = host;
+    this.onConnect(host);
+    this.reflect();
+  }
+
+  disconnect(host) {
+    const h = host ?? this.#host;
+    if (!h) return;
+    this.onDisconnect(h);
+    this.#host = null;
+  }
+
+  subscribe(fn) {
+    this.#subs.add(fn);
+    return () => this.#subs.delete(fn);
+  }
+
+  notify() {
+    this.reflect();
+    for (const fn of this.#subs) fn();
+  }
+
+  onConnect(host) {}
+  onDisconnect(host) {}
+  reflect() {}
+
+  getState() {
+    throw new Error(`${this.constructor.schema?.name ?? this.constructor.name}: getState() not implemented`);
+  }
+}