@adia-ai/a2ui-runtime 0.3.0

package/dockables/action.js

@@ -0,0 +1,152 @@
+/**
+ * ActionDock — Binds a UIEvent on a component to a handler.
+ *
+ * The UIEvent is a typed object: { event, target?, debounce?, throttle?, condition? }
+ * When the DOM event fires, the handler runs with the surface context.
+ * onSuccess/onError chains run follow-up handlers based on the outcome.
+ */
+import { Dockable } from './base.js';
+
+/**
+ * UIEvent type → DOM event name.
+ * AdiaUI components emit semantic events; these map to the actual DOM event to listen on.
+ */
+const A2UI_EVENT_TO_DOM = {
+  press:    'click',
+  submit:   'submit',
+  input:    'input',
+  change:   'change',
+  select:   'select',
+  toggle:   'change',
+  dismiss:  'close',
+  navigate: 'click',
+  mount:    'connectedCallback',
+  unmount:  'disconnectedCallback',
+  focus:    'focusin',
+  blur:     'focusout',
+  drag:     'dragstart',
+  drop:     'drop',
+};
+
+export { A2UI_EVENT_TO_DOM };
+
+export class ActionDock extends Dockable {
+  kind = 'action';
+
+  /** @type {string} */
+  id;
+
+  /** @type {{ event: string, target?: string, debounce?: number, throttle?: number, condition?: object }} */
+  event;
+
+  /** @type {string} handler name */
+  handler;
+
+  /** @type {object} handler config */
+  config;
+
+  /** @type {Array|null} follow-up actions on success */
+  onSuccess;
+
+  /** @type {Array|null} follow-up actions on error */
+  onError;
+
+  /** @type {Function} (handlerName) => handlerFn */
+  #resolveHandler;
+
+  /**
+   * @param {object} decl — { event, handler, config?, onSuccess?, onError? }
+   * @param {Function} resolveHandler — (name) => async (config, ctx) => result
+   */
+  constructor(decl, resolveHandler) {
+    super();
+    this.event = decl.event;
+    this.handler = decl.handler;
+    this.config = decl.config || {};
+    this.onSuccess = decl.onSuccess || null;
+    this.onError = decl.onError || null;
+    this.#resolveHandler = resolveHandler;
+
+    // Auto-generate id from event + target
+    this.id = `action:${this.event.event}:${this.event.target || 'root'}:${this.handler}`;
+  }
+
+  dock(ctx) {
+    const target = this.event.target
+      ? ctx.getElement(this.event.target)
+      : ctx.getRootElement();
+
+    if (!target) {
+      console.warn(`ActionDock: target "${this.event.target}" not found`);
+      return;
+    }
+
+    const domEventName = A2UI_EVENT_TO_DOM[this.event.event] || this.event.event;
+    const handlerFn = this.#resolveHandler(this.handler);
+
+    if (!handlerFn) {
+      console.warn(`ActionDock: unknown handler "${this.handler}"`);
+      return;
+    }
+
+    let listener = async (domEvent) => {
+      // Condition guard
+      if (this.event.condition) {
+        const val = ctx.getModel(this.event.condition.path);
+        if ('equals' in this.event.condition && val !== this.event.condition.equals) return;
+        if ('notEquals' in this.event.condition && val === this.event.condition.notEquals) return;
+        if ('exists' in this.event.condition && this.event.condition.exists && val == null) return;
+      }
+
+      try {
+        const result = await handlerFn(this.config, ctx, domEvent);
+
+        // Run onSuccess chain
+        if (this.onSuccess) {
+          for (const follow of this.onSuccess) {
+            const followFn = this.#resolveHandler(follow.handler);
+            if (followFn) await followFn(follow.config || {}, ctx, result);
+          }
+        }
+      } catch (err) {
+        // Run onError chain
+        if (this.onError) {
+          for (const follow of this.onError) {
+            const followFn = this.#resolveHandler(follow.handler);
+            if (followFn) await followFn(follow.config || {}, ctx, err);
+          }
+        } else {
+          console.error(`ActionDock: handler "${this.handler}" failed`, err);
+        }
+      }
+    };
+
+    // Debounce
+    if (this.event.debounce > 0) {
+      const origListener = listener;
+      let timer;
+      listener = (...args) => {
+        clearTimeout(timer);
+        timer = setTimeout(() => origListener(...args), this.event.debounce);
+      };
+    }
+
+    // Throttle
+    if (this.event.throttle > 0) {
+      const origListener = listener;
+      let last = 0;
+      listener = (...args) => {
+        const now = Date.now();
+        if (now - last >= this.event.throttle) {
+          last = now;
+          origListener(...args);
+        }
+      };
+    }
+
+    target.addEventListener(domEventName, listener);
+    return () => target.removeEventListener(domEventName, listener);
+  }
+
+  undock() {}
+}

package/dockables/base.js

@@ -0,0 +1,30 @@
+/**
+ * Dockable — Base class for objects that attach to a Surface.
+ *
+ * Every dockable has:
+ *   kind — which port type it uses (controller, source, action, provider, lifecycle)
+ *   id   — unique identity within the surface
+ *   dock(context)  — attach and return cleanup function
+ *   undock()       — teardown
+ */
+export class Dockable {
+  /** @type {'controller'|'source'|'action'|'provider'|'lifecycle'} */
+  get kind() { throw new Error('Dockable subclass must define kind'); }
+
+  /** @type {string} */
+  get id() { throw new Error('Dockable subclass must define id'); }
+
+  /**
+   * Attach to a surface. Receives the surface context.
+   * Return a cleanup function, or void.
+   * @param {import('../surface.js').SurfaceContext} ctx
+   * @returns {(() => void)|void}
+   */
+  dock(ctx) { throw new Error('Dockable subclass must implement dock()'); }
+
+  /**
+   * Detach from the surface. Cleanup fn from dock() is called
+   * automatically before this.
+   */
+  undock() {}
+}

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.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.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.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.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.js

@@ -0,0 +1,45 @@
+/**
+ * @adia-ai/a2ui-runtime — A2UI runtime surface.
+ *
+ * Framework-agnostic leaf: no runtime dep on @adia-ai/web-components.
+ * Pairs with any A2UI-conformant custom-element catalog.
+ *
+ * Tier 1 — Render: resolve A2UI protocol → custom-element tags, run the
+ * renderer, consume transports.
+ *
+ * Tier 2 — Wire: surface-manifest + wiring-engine + dockable primitives
+ * for cross-surface data flow and lifecycle.
+ */
+
+// ── Tier 1: Render ─────────────────────────────────────────────────
+export { registry, resolveTag, registerType } from './registry.js';
+export { A2UIRenderer } from './renderer.js';
+export { sseStream, wsStream, mockStream, mcpStream, jsonlStream } from './stream.js';
+
+// ── Tier 2: Wire ───────────────────────────────────────────────────
+export { SurfaceManifest } from './surface-manifest.js';
+export { Surface } from './surface.js';
+
+// Wiring primitives
+export { createDockables } from './wire-factory.js';
+export { WiringEngine } from './wiring-engine.js';
+export {
+  wiringRegistry,
+  registerController,
+  registerHandler,
+  registerResolver,
+  resolveController,
+  resolveHandler,
+  resolveData,
+} from './wiring-registry.js';
+
+// Dockable base + implementations
+export {
+  Dockable,
+  ControllerDock,
+  DataSourceDock,
+  ActionDock,
+  A2UI_EVENT_TO_DOM,
+  ProviderDock,
+  LifecycleDock,
+} from './dockables/index.js';

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@adia-ai/a2ui-runtime",
+  "version": "0.3.0",
+  "description": "A2UI runtime \u2014 renderer, registry, streams, surface manifest, and wiring primitives for the A2UI (Agent-to-UI) protocol. Framework-agnostic; pairs with any A2UI-conformant component set.",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./registry": "./registry.js",
+    "./renderer": "./renderer.js",
+    "./streams": "./stream.js",
+    "./surface": "./surface.js",
+    "./wiring": "./wiring-engine.js",
+    "./dockables": "./dockables/index.js"
+  },
+  "files": [
+    "*.js",
+    "dockables/",
+    "controllers/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adiahealth/gen-ui-kit.git",
+    "directory": "packages/a2ui/runtime"
+  }
+}