@adia-ai/a2ui 0.8.37

package/README.md

@@ -0,0 +1,99 @@
+# @adia-ai/a2ui
+
+> Formerly `@adia-ai/a2ui-runtime`; renamed at ADR-0048 P3, which folded the
+> runtime into this package root and added protocol-side validation at
+> [`./validate`](./validate/). Runtime subpath exports are unchanged.
+
+The A2UI protocol — renderer, registry, streams, surface manifest, and wiring
+primitives for A2UI (Agent-to-UI), plus protocol-side validation.
+Framework-agnostic and **dependency-free**; pairs with any A2UI-conformant
+component set.
+
+## Install
+
+```bash
+npm install @adia-ai/a2ui
+```
+
+Typically paired with `@adia-ai/web-components` (which provides the
+custom-element catalog the renderer resolves against):
+
+```bash
+npm install @adia-ai/a2ui @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';
+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/renderer';
+import { resolveTag }      from '@adia-ai/a2ui/registry';
+import { sseStream }       from '@adia-ai/a2ui/streams';
+import { SurfaceManifest } from '@adia-ai/a2ui/surface';
+import { WiringEngine }    from '@adia-ai/a2ui/wiring';
+import { ActionDock }      from '@adia-ai/a2ui/dockables';
+import { validateSchema } from '@adia-ai/a2ui/validate';
+```
+
+`./validate` is the protocol-side validator — structural + wiring/registry
+coherence checks against the A2UI protocol, no catalog and no LLM, so it
+keeps this package dependency-free. Catalog-aware validation and the LLM
+semantic judge live in `@adia-ai/gen-ui` (`./validate/catalog`,
+`./validate/semantic`) per ADR-0048.
+
+## 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/a2ui.schema.d.ts

@@ -0,0 +1,192 @@
+// AUTO-GENERATED FROM packages/a2ui/a2ui.schema.json. DO NOT EDIT.
+// Regenerate with: node scripts/build/a2ui-schema-types.mjs
+// Verify drift with: node scripts/build/a2ui-schema-types.mjs --verify
+
+/**
+ * Any valid A2UI protocol message. Discriminated on `type`.
+ */
+export type A2UIMessage =
+  | CreateSurfaceMessage
+  | UpdateComponentsMessage
+  | UpdateDataModelMessage
+  | WireComponentsMessage
+  | DeleteSurfaceMessage
+  | UpdateStylesMessage
+  | RemoveStylesMessage
+  | MetaMessage;
+
+/**
+ * Initialises a new rendering surface.
+ */
+export interface CreateSurfaceMessage {
+  type: 'createSurface';
+  /**
+   * Unique surface identifier.
+   */
+  surfaceId: string;
+  /**
+   * Optional catalog URL override for this surface.
+   */
+  catalogId?: string;
+  /**
+   * Component ID to use as the surface root (defaults to 'root').
+   */
+  root?: string;
+}
+/**
+ * Upserts component nodes on a surface. The renderer reconciles against existing nodes.
+ */
+export interface UpdateComponentsMessage {
+  type: 'updateComponents';
+  /**
+   * Legacy alias for type; renderer accepts both.
+   */
+  messageType?: string;
+  surfaceId: string;
+  /**
+   * @minItems 1
+   */
+  components: [A2UIComponent, ...A2UIComponent[]];
+}
+/**
+ * A single component node in the A2UI component tree.
+ */
+export interface A2UIComponent {
+  /**
+   * Unique identifier within the surface.
+   */
+  id: string;
+  /**
+   * A2UI type name — resolved via the registry to a custom-element tag name.
+   */
+  component: string;
+  /**
+   * Ordered list of child component IDs.
+   */
+  children?: string[];
+  /**
+   * Single child component ID (shorthand when there is exactly one child).
+   */
+  child?: string;
+  /**
+   * Per-child slot address (gh#653): names WHICH region of the PARENT this component occupies — e.g. a Button with slot "trigger" under a Popover, a Text with slot "description" under a ListItem. The legal names are the parent type's own declared anatomy slots (catalog `x-adiaui.slots`); an unknown name is inert, never fatal. Renderers map it to the light-DOM `slot=` attribute, which the component's CSS/JS already consumes — positioning stays CSS by tag + ancestor + DOM order (AGENTS.md), so this is addressing metadata, not a shadow-DOM projection instruction. Optional: children with no `slot` keep pure document order.
+   */
+  slot?: string;
+  [k: string]: unknown;
+}
+/**
+ * Updates the surface data model at a JSON Pointer path.
+ */
+export interface UpdateDataModelMessage {
+  type: 'updateDataModel';
+  surfaceId: string;
+  /**
+   * JSON Pointer path within the data model (e.g. '/user/name'). '/' or '' = replace root.
+   */
+  path: string;
+  value: unknown;
+}
+/**
+ * Attaches interactive behaviour (actions, data sources, controllers) to a surface.
+ */
+export interface WireComponentsMessage {
+  type: 'wireComponents';
+  surfaceId: string;
+  /**
+   * Event → handler bindings.
+   */
+  actions?: WireAction[];
+  /**
+   * Data-source dockables.
+   */
+  data?: WireDataSource[];
+  /**
+   * Controller dockables.
+   */
+  state?: WireState[];
+  /**
+   * Lifecycle hook dockables.
+   */
+  lifecycle?: {
+    [k: string]: unknown;
+  }[];
+}
+/**
+ * An event → handler binding for interactive wiring.
+ */
+export interface WireAction {
+  /**
+   * The UIEvent that triggers this action.
+   */
+  event:
+    | string
+    | {
+        event: string;
+        /**
+         * Component ID that emits the event.
+         */
+        target?: string;
+        debounce?: number;
+      };
+  /**
+   * Handler name registered in the wiring registry.
+   */
+  handler: string;
+  /**
+   * Handler-specific configuration.
+   */
+  config?: {
+    [k: string]: unknown;
+  };
+}
+/**
+ * A data-source dockable: connects a model path to a component property.
+ */
+export interface WireDataSource {
+  source: string;
+  target: string;
+  transform?: string;
+  [k: string]: unknown;
+}
+/**
+ * A controller dockable: attaches a stateful controller to a component.
+ */
+export interface WireState {
+  controller: string;
+  target: string;
+  config?: {
+    [k: string]: unknown;
+  };
+  [k: string]: unknown;
+}
+/**
+ * Removes a surface and all its elements from the DOM.
+ */
+export interface DeleteSurfaceMessage {
+  type: 'deleteSurface';
+  surfaceId: string;
+}
+/**
+ * CSS channel: adopts a surface-scoped stylesheet (wrapped in @scope([data-a2ui-surface=<id>]) by the renderer). See specs/genui-css-channel.md.
+ */
+export interface UpdateStylesMessage {
+  type: 'updateStyles';
+  surfaceId: string;
+  styleId: string;
+  css: string;
+}
+/**
+ * CSS channel: removes a previously adopted surface-scoped stylesheet by styleId.
+ */
+export interface RemoveStylesMessage {
+  type: 'removeStyles';
+  surfaceId: string;
+  styleId: string;
+}
+/**
+ * LLM self-critique or metadata. Not rendered; passed through for logging.
+ */
+export interface MetaMessage {
+  type: 'meta';
+  [k: string]: unknown;
+}

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`);
+  }
+}

package/controllers/data-stream.js

@@ -0,0 +1,281 @@
+import { BaseController } from './base.js';
+
+/**
+ * DataStreamController — pushes live data to chart components.
+ *
+ * Accepts: SSE URL, WebSocket URL, async iterable, polling function, or manual push.
+ * Accumulates data points in a buffer with configurable max size.
+ * Each new point triggers notify() → chart re-renders.
+ *
+ * Usage:
+ *   const ctrl = new DataStreamController({ max: 20 });
+ *   chart.controller = ctrl;
+ *
+ *   // Manual push
+ *   ctrl.commands.push({ month: 'Jan', revenue: 4200 });
+ *
+ *   // SSE
+ *   ctrl.commands.connect('sse', '/api/metrics');
+ *
+ *   // WebSocket
+ *   ctrl.commands.connect('ws', 'wss://api.example.com/stream');
+ *
+ *   // Polling
+ *   ctrl.commands.poll('/api/latest', 2000);
+ *
+ *   // Async iterable
+ *   ctrl.commands.consume(asyncIterable);
+ *
+ *   // Stop
+ *   ctrl.commands.stop();
+ */
+export class DataStreamController extends BaseController {
+  static schema = Object.freeze({
+    name: 'data-stream',
+    state: { data: 'array', status: 'string', error: 'string' },
+    commands: ['push', 'pushMany', 'connect', 'poll', 'consume', 'stop', 'clear'],
+    attributes: ['data-stream-status'],
+  });
+
+  #data = [];
+  #max;
+  #status = 'idle';  // idle | connecting | streaming | error | stopped
+  #error = null;
+  #abort = null;
+  #throttle = 0;      // ms — min interval between notify() calls. 0 = every push.
+  #sample = 1;        // keep every Nth point. 1 = keep all.
+  #pendingNotify = null;
+  #pushCount = 0;     // total pushes since connect (for sampling)
+
+  /**
+   * @param {Object} opts
+   * @param {number} [opts.max=100]      — Maximum data points to retain (FIFO)
+   * @param {number} [opts.throttle=0]   — Min ms between render notifications. 0 = every push.
+   * @param {number} [opts.sample=1]     — Keep every Nth point. 1 = keep all.
+   * @param {Array}  [opts.initial]      — Initial data
+   */
+  constructor({ max = 100, throttle = 0, sample = 1, initial = [] } = {}) {
+    super();
+    this.#max = max;
+    this.#throttle = throttle;
+    this.#sample = Math.max(1, Math.round(sample));
+    this.#data = initial.slice(-max);
+  }
+
+  getState() {
+    return {
+      data: this.#data,
+      status: this.#status,
+      error: this.#error,
+    };
+  }
+
+  reflect() {
+    if (!this.host) return;
+    this.host.setAttribute('data-stream-status', this.#status);
+  }
+
+  onDisconnect() {
+    this.commands.stop();
+  }
+
+  #append(point) {
+    // Sampling: skip points when sample > 1
+    this.#pushCount++;
+    if (this.#sample > 1 && this.#pushCount % this.#sample !== 0) return;
+
+    this.#data.push(point);
+    if (this.#data.length > this.#max) {
+      this.#data = this.#data.slice(-this.#max);
+    }
+    this.#scheduleNotify();
+  }
+
+  #appendMany(points) {
+    // Sampling: filter points when sample > 1
+    if (this.#sample > 1) {
+      const sampled = [];
+      for (const p of points) {
+        this.#pushCount++;
+        if (this.#pushCount % this.#sample === 0) sampled.push(p);
+      }
+      this.#data.push(...sampled);
+    } else {
+      this.#data.push(...points);
+    }
+    if (this.#data.length > this.#max) {
+      this.#data = this.#data.slice(-this.#max);
+    }
+    this.#scheduleNotify();
+  }
+
+  #scheduleNotify() {
+    // No throttle: immediate
+    if (this.#throttle <= 0) {
+      this.notify();
+      return;
+    }
+    // Throttled: batch into one notify per interval
+    if (this.#pendingNotify !== null) return;
+    this.#pendingNotify = setTimeout(() => {
+      this.#pendingNotify = null;
+      this.notify();
+    }, this.#throttle);
+  }
+
+  #setStatus(status, error = null) {
+    this.#status = status;
+    this.#error = error;
+    this.notify();
+  }
+
+  commands = {
+    /** Push a single data point */
+    push: (point) => {
+      this.#append(point);
+    },
+
+    /** Push multiple data points at once */
+    pushMany: (points) => {
+      this.#appendMany(points);
+    },
+
+    /** Connect to SSE or WebSocket stream */
+    connect: (type, url) => {
+      this.commands.stop();
+      this.#abort = new AbortController();
+
+      if (type === 'sse') {
+        this.#connectSSE(url);
+      } else if (type === 'ws') {
+        this.#connectWS(url);
+      } else {
+        this.#setStatus('error', `Unknown stream type: ${type}`);
+      }
+    },
+
+    /** Poll a URL at an interval (ms) */
+    poll: (url, interval = 2000) => {
+      this.commands.stop();
+      this.#abort = new AbortController();
+      this.#startPolling(url, interval);
+    },
+
+    /** Consume an async iterable */
+    consume: (iterable) => {
+      this.commands.stop();
+      this.#abort = new AbortController();
+      this.#consumeIterable(iterable);
+    },
+
+    /** Stop all active streams */
+    stop: () => {
+      if (this.#abort) {
+        this.#abort.abort();
+        this.#abort = null;
+      }
+      if (this.#pendingNotify !== null) {
+        clearTimeout(this.#pendingNotify);
+        this.#pendingNotify = null;
+      }
+      if (this.#status === 'streaming' || this.#status === 'connecting') {
+        this.#setStatus('stopped');
+      }
+    },
+
+    /** Clear all data */
+    clear: () => {
+      this.#data = [];
+      this.notify();
+    },
+  };
+
+  #connectSSE(url) {
+    this.#setStatus('connecting');
+    const es = new EventSource(url);
+    const signal = this.#abort.signal;
+
+    signal.addEventListener('abort', () => es.close());
+
+    es.onopen = () => this.#setStatus('streaming');
+
+    es.onmessage = (e) => {
+      try {
+        const point = JSON.parse(e.data);
+        this.#append(point);
+      } catch { /* skip malformed */ }
+    };
+
+    es.onerror = () => {
+      if (!signal.aborted) {
+        this.#setStatus('error', 'SSE connection lost');
+        es.close();
+      }
+    };
+  }
+
+  #connectWS(url) {
+    this.#setStatus('connecting');
+    const ws = new WebSocket(url);
+    const signal = this.#abort.signal;
+
+    signal.addEventListener('abort', () => ws.close());
+
+    ws.onopen = () => this.#setStatus('streaming');
+
+    ws.onmessage = (e) => {
+      try {
+        const msg = JSON.parse(e.data);
+        if (Array.isArray(msg)) this.#appendMany(msg);
+        else this.#append(msg);
+      } catch { /* skip malformed */ }
+    };
+
+    ws.onerror = () => {
+      if (!signal.aborted) {
+        this.#setStatus('error', 'WebSocket error');
+      }
+    };
+
+    ws.onclose = () => {
+      if (!signal.aborted) {
+        this.#setStatus('stopped');
+      }
+    };
+  }
+
+  async #startPolling(url, interval) {
+    this.#setStatus('streaming');
+    const signal = this.#abort.signal;
+
+    while (!signal.aborted) {
+      try {
+        const res = await fetch(url, { signal });
+        const json = await res.json();
+        if (Array.isArray(json)) this.#appendMany(json);
+        else this.#append(json);
+      } catch (e) {
+        if (signal.aborted) break;
+        this.#setStatus('error', e.message);
+        break;
+      }
+      await new Promise(r => setTimeout(r, interval));
+    }
+  }
+
+  async #consumeIterable(iterable) {
+    this.#setStatus('streaming');
+    const signal = this.#abort.signal;
+
+    try {
+      for await (const point of iterable) {
+        if (signal.aborted) break;
+        if (Array.isArray(point)) this.#appendMany(point);
+        else this.#append(point);
+      }
+      if (!signal.aborted) this.#setStatus('idle');
+    } catch (e) {
+      if (!signal.aborted) this.#setStatus('error', e.message);
+    }
+  }
+}