@adia-ai/a2ui 0.8.37

package/dockables/controller.js

@@ -0,0 +1,97 @@
+/**
+ * ControllerDock — Wraps a AdiaUI controller as a dockable.
+ *
+ * Instantiates the controller, connects it to its host element,
+ * and sets up two-way binding between controller state and model paths.
+ */
+import { Dockable } from './base.js';
+
+export class ControllerDock extends Dockable {
+  kind = 'controller';
+
+  /** @type {string} */
+  id;
+
+  /** @type {string} controller type name, e.g., 'FormController' */
+  type;
+
+  /** @type {string} component id to attach to */
+  hostId;
+
+  /** @type {object} controller config */
+  config;
+
+  /** @type {object|null} model path bindings { stateKey: '/model/path' } */
+  bind;
+
+  /** @type {import('../controllers/base.js').BaseController|null} */
+  controller = null;
+
+  /** @type {Function|null} resolve controller class */
+  #resolveClass;
+
+  /**
+   * @param {object} decl — { id, type, host, config?, bind? }
+   * @param {Function} resolveClass — async (type) => ControllerClass
+   */
+  constructor(decl, resolveClass) {
+    super();
+    this.id = decl.id;
+    this.type = decl.type;
+    this.hostId = decl.host;
+    this.config = decl.config || {};
+    this.bind = decl.bind || null;
+    this.#resolveClass = resolveClass;
+  }
+
+  async dock(ctx) {
+    const host = ctx.getElement(this.hostId);
+    if (!host) {
+      console.warn(`ControllerDock: host element "${this.hostId}" not found`);
+      return;
+    }
+
+    const ControllerClass = await this.#resolveClass(this.type);
+    if (!ControllerClass) {
+      console.warn(`ControllerDock: unknown controller type "${this.type}"`);
+      return;
+    }
+
+    this.controller = new ControllerClass(this.config);
+    this.controller.connect(host);
+
+    // Two-way bind: controller state ↔ model paths
+    const unbinders = [];
+    if (this.bind) {
+      for (const [stateKey, modelPath] of Object.entries(this.bind)) {
+        // Controller → model
+        if (this.controller.subscribe) {
+          const unsub = this.controller.subscribe(stateKey, (value) => {
+            ctx.setModel(modelPath, value);
+          });
+          if (unsub) unbinders.push(unsub);
+        }
+
+        // Model → controller (initial sync)
+        const initial = ctx.getModel(modelPath);
+        if (initial !== undefined && this.controller.setState) {
+          this.controller.setState(stateKey, initial);
+        }
+      }
+    }
+
+    host.controller = this.controller;
+
+    return () => {
+      host.controller = null;
+      unbinders.forEach(u => u());
+    };
+  }
+
+  undock() {
+    if (this.controller) {
+      this.controller.disconnect?.();
+      this.controller = null;
+    }
+  }
+}

package/dockables/data-source.d.ts

@@ -0,0 +1,35 @@
+/**
+ * DataSourceDock — Fetches data and pushes it into the surface model.
+ */
+
+import type { Dockable } from './base.js';
+import type { SurfaceContext } from '../surface.js';
+
+export interface DataSourceDecl {
+  id: string;
+  /** URI template, e.g., "resource://users/{userId}" */
+  uri: string;
+  /** Model path to write fetched data to. */
+  path: string;
+  /** Refresh strategy: 'once' | 'on-focus' | 'interval:<ms>' | 'stream'. Default: 'once'. */
+  refresh?: string;
+}
+
+export declare class DataSourceDock extends Dockable {
+  readonly kind: 'source';
+  readonly id: string;
+  readonly uri: string;
+  readonly path: string;
+  readonly refresh: string;
+
+  constructor(
+    decl: DataSourceDecl,
+    resolveData: (uri: string, ctx: unknown) => Promise<unknown>,
+  );
+
+  dock(ctx: SurfaceContext): (() => void) | void;
+  undock(): void;
+
+  /** Manually re-fetch the data source. */
+  refetch(): void;
+}

package/dockables/data-source.js

@@ -0,0 +1,103 @@
+/**
+ * DataSourceDock — Fetches data and pushes it into the surface model.
+ *
+ * Supports refresh strategies: once, on-focus, interval:{ms}, stream.
+ * Re-fetch on demand via refetch() (used by refresh-source handler).
+ */
+import { Dockable } from './base.js';
+
+export class DataSourceDock extends Dockable {
+  kind = 'source';
+
+  /** @type {string} */
+  id;
+
+  /** @type {string} URI template, e.g., "resource://users/{userId}" */
+  uri;
+
+  /** @type {string} model path to write to */
+  path;
+
+  /** @type {string} refresh strategy */
+  refresh;
+
+  /** @type {Function} (uri, params) => data */
+  #resolveData;
+
+  /** @type {import('../surface.js').SurfaceContext|null} */
+  #ctx = null;
+
+  /**
+   * @param {object} decl — { id, uri, path, refresh? }
+   * @param {Function} resolveData — async (uri, params) => data
+   */
+  constructor(decl, resolveData) {
+    super();
+    this.id = decl.id;
+    this.uri = decl.uri;
+    this.path = decl.path;
+    this.refresh = decl.refresh || 'once';
+    this.#resolveData = resolveData;
+  }
+
+  dock(ctx) {
+    this.#ctx = ctx;
+
+    // Initial fetch
+    this.#fetch(ctx);
+
+    // Refresh strategy
+    if (this.refresh === 'on-focus') {
+      const handler = () => this.#fetch(ctx);
+      window.addEventListener('focus', handler);
+      return () => window.removeEventListener('focus', handler);
+    }
+
+    if (this.refresh.startsWith('interval:')) {
+      const ms = parseInt(this.refresh.split(':')[1], 10);
+      if (ms > 0) {
+        const id = setInterval(() => this.#fetch(ctx), ms);
+        return () => clearInterval(id);
+      }
+    }
+
+    if (this.refresh === 'stream') {
+      const resolvedUri = this.#resolveUri(ctx);
+      try {
+        const source = new EventSource(resolvedUri);
+        source.onmessage = (e) => {
+          try { ctx.setModel(this.path, JSON.parse(e.data)); }
+          catch { /* malformed data */ }
+        };
+        return () => source.close();
+      } catch {
+        console.warn(`DataSourceDock: stream failed for ${resolvedUri}`);
+      }
+    }
+  }
+
+  undock() {
+    this.#ctx = null;
+  }
+
+  /** Re-fetch on demand (called by refresh-source handler). */
+  refetch() {
+    if (this.#ctx) this.#fetch(this.#ctx);
+  }
+
+  async #fetch(ctx) {
+    const resolvedUri = this.#resolveUri(ctx);
+    try {
+      const data = await this.#resolveData(resolvedUri, ctx);
+      if (data !== undefined) ctx.setModel(this.path, data);
+    } catch (err) {
+      console.warn(`DataSourceDock: fetch failed for ${resolvedUri}`, err);
+    }
+  }
+
+  #resolveUri(ctx) {
+    return this.uri.replace(/\{(\w+)\}/g, (_, key) => {
+      return ctx.getParam(key) ?? ctx.getModel('/' + key) ?? '';
+    });
+  }
+}

package/dockables/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Dockables barrel — re-exports all dockable classes and the event mapping.
+ */
+
+export { Dockable } from './base.js';
+export type { DockableKind } from './base.js';
+
+export { ControllerDock } from './controller.js';
+export type { ControllerDecl } from './controller.js';
+
+export { DataSourceDock } from './data-source.js';
+export type { DataSourceDecl } from './data-source.js';
+
+export { ActionDock, A2UI_EVENT_TO_DOM } from './action.js';
+export type { ActionDecl, UIEventDecl } from './action.js';
+
+export { ProviderDock } from './provider.js';
+export type { ProviderDecl } from './provider.js';
+
+export { LifecycleDock } from './lifecycle.js';
+export type { LifecycleDecl, LifecycleAction, ModelChangeWatcher } from './lifecycle.js';

package/dockables/index.js

@@ -0,0 +1,6 @@
+export { Dockable } from './base.js';
+export { ControllerDock } from './controller.js';
+export { DataSourceDock } from './data-source.js';
+export { ActionDock, A2UI_EVENT_TO_DOM } from './action.js';
+export { ProviderDock } from './provider.js';
+export { LifecycleDock } from './lifecycle.js';

package/dockables/lifecycle.d.ts

@@ -0,0 +1,38 @@
+/**
+ * LifecycleDock — Runs actions on mount, unmount, and model changes.
+ */
+
+import type { Dockable } from './base.js';
+import type { SurfaceContext } from '../surface.js';
+
+export interface LifecycleAction {
+  handler: string;
+  config?: Record<string, unknown>;
+}
+
+export interface ModelChangeWatcher extends LifecycleAction {
+  path: string;
+  debounce?: number;
+}
+
+export interface LifecycleDecl {
+  onMount?: LifecycleAction[];
+  onUnmount?: LifecycleAction[];
+  onModelChange?: ModelChangeWatcher[];
+}
+
+export declare class LifecycleDock extends Dockable {
+  readonly kind: 'lifecycle';
+  readonly id: 'lifecycle';
+  readonly onMount: LifecycleAction[];
+  readonly onUnmount: LifecycleAction[];
+  readonly onModelChange: ModelChangeWatcher[];
+
+  constructor(
+    decl: LifecycleDecl,
+    resolveHandler: (name: string) => ((config: unknown, ctx: SurfaceContext) => Promise<unknown>) | null,
+  );
+
+  dock(ctx: SurfaceContext): (() => void) | void;
+  undock(): void;
+}

package/dockables/lifecycle.js

@@ -0,0 +1,84 @@
+/**
+ * LifecycleDock — Runs actions on mount, unmount, and model changes.
+ *
+ * One per surface. Fires onMount actions immediately on dock,
+ * watches model paths for changes, and runs onUnmount on undock.
+ */
+import { Dockable } from './base.js';
+
+export class LifecycleDock extends Dockable {
+  kind = 'lifecycle';
+  id = 'lifecycle';
+
+  /** @type {Array} actions to run on mount */
+  onMount;
+
+  /** @type {Array} actions to run on unmount */
+  onUnmount;
+
+  /** @type {Array} model path watchers */
+  onModelChange;
+
+  /** @type {Function} (handlerName) => handlerFn */
+  #resolveHandler;
+
+  /** @type {import('../surface.js').SurfaceContext|null} */
+  #ctx = null;
+
+  /**
+   * @param {object} decl — { onMount?, onUnmount?, onModelChange? }
+   * @param {Function} resolveHandler — (name) => async (config, ctx) => result
+   */
+  constructor(decl, resolveHandler) {
+    super();
+    this.onMount = decl.onMount || [];
+    this.onUnmount = decl.onUnmount || [];
+    this.onModelChange = decl.onModelChange || [];
+    this.#resolveHandler = resolveHandler;
+  }
+
+  dock(ctx) {
+    this.#ctx = ctx;
+
+    // Run onMount actions
+    for (const action of this.onMount) {
+      this.#run(action, ctx);
+    }
+
+    // Set up model watchers
+    const unwatchers = this.onModelChange.map((watcher) => {
+      let handler = () => this.#run(watcher, ctx);
+
+      // Debounce if specified
+      if (watcher.debounce > 0) {
+        const origHandler = handler;
+        let timer;
+        handler = () => {
+          clearTimeout(timer);
+          timer = setTimeout(origHandler, watcher.debounce);
+        };
+      }
+
+      return ctx.watchModel(watcher.path, handler);
+    });
+
+    return () => unwatchers.forEach(u => u());
+  }
+
+  undock() {
+    if (this.#ctx) {
+      for (const action of this.onUnmount) {
+        this.#run(action, this.#ctx);
+      }
+      this.#ctx = null;
+    }
+  }
+
+  async #run(action, ctx) {
+    const fn = this.#resolveHandler(action.handler);
+    if (fn) {
+      try { await fn(action.config || {}, ctx); }
+      catch (err) { console.warn(`LifecycleDock: ${action.handler} failed`, err); }
+    }
+  }
+}

package/dockables/provider.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ProviderDock — Injects shared context into a component subtree.
+ */
+
+import type { Dockable } from './base.js';
+import type { SurfaceContext } from '../surface.js';
+
+export interface ProviderDecl {
+  /** Context name, e.g. "auth". The dock id is set to "provider:<name>". */
+  name: string;
+  /** Component ID to wrap. Defaults to the surface root. */
+  host?: string;
+  /** Initial context value. */
+  value?: unknown;
+}
+
+export declare class ProviderDock extends Dockable {
+  readonly kind: 'provider';
+  /** "provider:<name>" */
+  readonly id: string;
+  readonly hostId: string | null;
+  readonly value: unknown;
+
+  constructor(decl: ProviderDecl);
+
+  dock(ctx: SurfaceContext): (() => void) | void;
+  undock(): void;
+}

package/dockables/provider.js

@@ -0,0 +1,59 @@
+/**
+ * ProviderDock — Injects shared context into a component subtree.
+ *
+ * Creates an <a2ui-provider> wrapper around the host element.
+ * Children can consume the context by name.
+ */
+import { Dockable } from './base.js';
+
+export class ProviderDock extends Dockable {
+  kind = 'provider';
+
+  /** @type {string} context name, e.g., "auth" */
+  id;
+
+  /** @type {string|null} component id to wrap (null = root) */
+  hostId;
+
+  /** @type {*} initial context value */
+  value;
+
+  /**
+   * @param {object} decl — { name, host?, value? }
+   */
+  constructor(decl) {
+    super();
+    this.id = `provider:${decl.name}`;
+    this.hostId = decl.host || null;
+    this.value = decl.value ?? null;
+  }
+
+  dock(ctx) {
+    const host = this.hostId
+      ? ctx.getElement(this.hostId)
+      : ctx.getRootElement();
+
+    if (!host) {
+      console.warn(`ProviderDock: host "${this.hostId}" not found`);
+      return;
+    }
+
+    const provider = document.createElement('a2ui-provider');
+    provider.setAttribute('name', this.id.replace('provider:', ''));
+    provider.value = this.value;
+
+    // Wrap: insert provider before host, move host inside
+    host.parentNode?.insertBefore(provider, host);
+    provider.appendChild(host);
+
+    return () => {
+      // Unwrap: move host back out, remove provider
+      if (provider.parentNode) {
+        provider.parentNode.insertBefore(host, provider);
+        provider.remove();
+      }
+    };
+  }
+
+  undock() {}
+}

package/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @adia-ai/a2ui — A2UI runtime surface barrel.
+ *
+ * Re-exports all public symbols from Tier 1 (Render) and Tier 2 (Wire).
+ */
+
+// ── Types ───────────────────────────────────────────────────────────────────
+export type { A2UIMessageType, A2UIComponent, A2UIMessage } from './types.js';
+
+// ── Tier 1: Render ──────────────────────────────────────────────────────────
+export { registry, resolveTag, registerType } from './registry.js';
+export { A2UIRenderer } from './renderer.js';
+export type { A2UIRendererOptions, SurfaceState } from './renderer.js';
+export { applyResolvedProp, toAttr } from './prop-apply.js';
+export { sseStream, wsStream, mockStream, mcpStream, jsonlStream } from './stream.js';
+export type { StreamOptions, McpStreamOptions } from './stream.js';
+
+// ── Tier 2: Wire ────────────────────────────────────────────────────────────
+export { SurfaceManifest } from './surface-manifest.js';
+export type {
+  SurfaceDescriptor,
+  Association,
+  AssociationType,
+  ManifestValidationResult,
+} from './surface-manifest.js';
+
+export { Surface } from './surface.js';
+export type { SurfaceContext, AdiaEvent } from './surface.js';
+
+export { createDockables } from './wire-factory.js';
+export type { CreateDockablesResult } from './wire-factory.js';
+
+export { WiringEngine } from './wiring-engine.js';
+export type { WiringEngineOptions, SurfaceWireState } from './wiring-engine.js';
+
+export {
+  wiringRegistry,
+  registerController,
+  registerHandler,
+  registerResolver,
+  resolveController,
+  resolveHandler,
+  resolveData,
+} from './wiring-registry.js';
+export type { WiringRegistry, HandlerContext } from './wiring-registry.js';
+
+// ── Dockable base + implementations ─────────────────────────────────────────
+export { Dockable } from './dockables/base.js';
+export type { DockableKind } from './dockables/base.js';
+
+export { ControllerDock } from './dockables/controller.js';
+export type { ControllerDecl } from './dockables/controller.js';
+
+export { DataSourceDock } from './dockables/data-source.js';
+export type { DataSourceDecl } from './dockables/data-source.js';
+
+export { ActionDock, A2UI_EVENT_TO_DOM } from './dockables/action.js';
+export type { ActionDecl, UIEventDecl } from './dockables/action.js';
+
+export { ProviderDock } from './dockables/provider.js';
+export type { ProviderDecl } from './dockables/provider.js';
+
+export { LifecycleDock } from './dockables/lifecycle.js';
+export type { LifecycleDecl, LifecycleAction, ModelChangeWatcher } from './dockables/lifecycle.js';

package/index.js

@@ -0,0 +1,54 @@
+import { registry, resolveTag, registerType } from "./registry.js";
+import { A2UIRenderer } from "./renderer.js";
+import { applyResolvedProp, toAttr } from "./prop-apply.js";
+import { sseStream, wsStream, mockStream, mcpStream, jsonlStream } from "./stream.js";
+import { SurfaceManifest } from "./surface-manifest.js";
+import { Surface } from "./surface.js";
+import { createDockables } from "./wire-factory.js";
+import { WiringEngine } from "./wiring-engine.js";
+import {
+  wiringRegistry,
+  registerController,
+  registerHandler,
+  registerResolver,
+  resolveController,
+  resolveHandler,
+  resolveData
+} from "./wiring-registry.js";
+import { Dockable } from "./dockables/base.js";
+import { ControllerDock } from "./dockables/controller.js";
+import { DataSourceDock } from "./dockables/data-source.js";
+import { ActionDock, A2UI_EVENT_TO_DOM } from "./dockables/action.js";
+import { ProviderDock } from "./dockables/provider.js";
+import { LifecycleDock } from "./dockables/lifecycle.js";
+export {
+  A2UIRenderer,
+  A2UI_EVENT_TO_DOM,
+  ActionDock,
+  ControllerDock,
+  DataSourceDock,
+  Dockable,
+  LifecycleDock,
+  ProviderDock,
+  Surface,
+  SurfaceManifest,
+  WiringEngine,
+  applyResolvedProp,
+  createDockables,
+  jsonlStream,
+  mcpStream,
+  mockStream,
+  registerController,
+  registerHandler,
+  registerResolver,
+  registerType,
+  registry,
+  resolveController,
+  resolveData,
+  resolveHandler,
+  resolveTag,
+  sseStream,
+  toAttr,
+  wiringRegistry,
+  wsStream
+};

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@adia-ai/a2ui",
+  "version": "0.8.37",
+  "description": "The A2UI protocol — runtime (renderer, registry, streams, surface manifest, wiring primitives, dockable base classes) plus protocol-side validation. Framework-agnostic and dependency-free; pairs with any A2UI-conformant component set. Folded from @adia-ai/a2ui-runtime + the protocol half of @adia-ai/a2ui-validator (ADR-0048).",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./registry": {
+      "types": "./registry.d.ts",
+      "import": "./registry.js",
+      "default": "./registry.js"
+    },
+    "./renderer": {
+      "types": "./renderer.d.ts",
+      "import": "./renderer.js",
+      "default": "./renderer.js"
+    },
+    "./prop-apply": {
+      "types": "./prop-apply.d.ts",
+      "import": "./prop-apply.js",
+      "default": "./prop-apply.js"
+    },
+    "./streams": {
+      "types": "./stream.d.ts",
+      "import": "./stream.js",
+      "default": "./stream.js"
+    },
+    "./surface": {
+      "types": "./surface.d.ts",
+      "import": "./surface.js",
+      "default": "./surface.js"
+    },
+    "./wiring": {
+      "types": "./wiring-engine.d.ts",
+      "import": "./wiring-engine.js",
+      "default": "./wiring-engine.js"
+    },
+    "./dockables": {
+      "types": "./dockables/index.d.ts",
+      "import": "./dockables/index.js",
+      "default": "./dockables/index.js"
+    },
+    "./schema": {
+      "types": "./a2ui.schema.d.ts",
+      "default": "./a2ui.schema.d.ts"
+    },
+    "./types": {
+      "types": "./types.d.ts",
+      "default": "./types.d.ts"
+    },
+    "./validate": {
+      "types": "./validate/index.d.ts",
+      "import": "./validate/index.js",
+      "default": "./validate/index.js"
+    }
+  },
+  "files": [
+    "*.js",
+    "dockables/",
+    "controllers/",
+    "validate/index.js",
+    "validate/validator.js",
+    "validate/README.md",
+    "validate/CHANGELOG.md",
+    "README.md",
+    "CHANGELOG.md",
+    "a2ui.schema.d.ts",
+    "types.d.ts",
+    "**/*.d.ts",
+    "!**/*.test.js"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adiahealth/gen-ui-kit.git",
+    "directory": "packages/a2ui"
+  },
+  "devDependencies": {
+    "@adia-ai/gen-ui": "^0.8.0"
+  }
+}