@adia-ai/a2ui-runtime 0.3.0

package/surface.js

@@ -0,0 +1,222 @@
+/**
+ * Surface — A dock host where typed objects connect and disconnect cleanly.
+ *
+ * A Surface is the runtime representation of a rendered UI region.
+ * It holds a data model, resolved params, and a registry of docked objects
+ * (controllers, data sources, actions, providers, lifecycle hooks).
+ *
+ * Dockables attach via dock(surface) and clean up via undock().
+ * The Surface doesn't know what dockables do internally — it just manages
+ * their lifecycle and provides a shared context.
+ */
+
+// ── Dock order (lowest docks first, undocks last) ──
+const DOCK_ORDER = { provider: 0, controller: 1, source: 2, action: 3, lifecycle: 4 };
+
+/**
+ * @typedef {object} DockEntry
+ * @property {import('./dockables/base.js').Dockable} dockable
+ * @property {Function|null} cleanup — returned from dock()
+ */
+
+export class Surface {
+  /** @type {string} */
+  surfaceId;
+
+  /** @type {Map<string, DockEntry>} keyed by dockable.id */
+  #docked = new Map();
+
+  /** @type {object} reactive-ish data model */
+  #model = {};
+
+  /** @type {object} resolved params (route, store, literal) */
+  #params = {};
+
+  /** @type {Map<string, Set<Function>>} model watchers keyed by path */
+  #watchers = new Map();
+
+  /** @type {HTMLElement} surface root element */
+  #rootElement;
+
+  /** @type {Map<string, HTMLElement>} componentId → DOM element */
+  #elements;
+
+  /**
+   * @param {string} surfaceId
+   * @param {HTMLElement} rootElement — the surface's root DOM node
+   * @param {Map<string, HTMLElement>} elements — componentId → element map
+   */
+  constructor(surfaceId, rootElement, elements) {
+    this.surfaceId = surfaceId;
+    this.#rootElement = rootElement;
+    this.#elements = elements;
+  }
+
+  // ── Context (passed to dockables) ─────────────────────────
+
+  /** @returns {SurfaceContext} */
+  get context() {
+    return {
+      surfaceId: this.surfaceId,
+      getElement: (id) => this.#elements.get(id) || null,
+      getRootElement: () => this.#rootElement,
+      getModel: (path) => path ? getPath(this.#model, path) : this.#model,
+      setModel: (path, value) => this.#setModel(path, value),
+      getDockable: (kind, id) => this.#getDockable(kind, id),
+      listDockables: (kind) => this.#listDockables(kind),
+      emit: (adiaEvent) => this.#emit(adiaEvent),
+      getParam: (key) => this.#params[key],
+      watchModel: (path, fn) => this.#watchModel(path, fn),
+    };
+  }
+
+  // ── Dock Protocol ─────────────────────────────────────────
+
+  /**
+   * Dock a new object. Calls dockable.dock(context).
+   * @param {import('./dockables/base.js').Dockable} dockable
+   */
+  dock(dockable) {
+    // If same id already docked, redock (hot-swap)
+    if (this.#docked.has(dockable.id)) {
+      this.undock(dockable.id);
+    }
+
+    const cleanup = dockable.dock(this.context);
+    this.#docked.set(dockable.id, {
+      dockable,
+      cleanup: typeof cleanup === 'function' ? cleanup : null,
+    });
+  }
+
+  /**
+   * Dock multiple objects in dependency order.
+   * @param {import('./dockables/base.js').Dockable[]} dockables
+   */
+  dockAll(dockables) {
+    const sorted = [...dockables].sort(
+      (a, b) => (DOCK_ORDER[a.kind] ?? 9) - (DOCK_ORDER[b.kind] ?? 9)
+    );
+    for (const d of sorted) this.dock(d);
+  }
+
+  /**
+   * Undock by id. Calls cleanup then dockable.undock().
+   * @param {string} id
+   */
+  undock(id) {
+    const entry = this.#docked.get(id);
+    if (!entry) return;
+    entry.cleanup?.();
+    entry.dockable.undock();
+    this.#docked.delete(id);
+  }
+
+  /**
+   * Undock everything in reverse dependency order.
+   */
+  undockAll() {
+    const entries = [...this.#docked.entries()].sort(
+      (a, b) => (DOCK_ORDER[b[1].dockable.kind] ?? 9) - (DOCK_ORDER[a[1].dockable.kind] ?? 9)
+    );
+    for (const [id] of entries) this.undock(id);
+  }
+
+  /**
+   * Undock specific ids.
+   * @param {string[]} ids
+   */
+  undockMany(ids) {
+    for (const id of ids) this.undock(id);
+  }
+
+  // ── Model ─────────────────────────────────────────────────
+
+  /** Set initial model state (before docking). */
+  setInitialModel(model) {
+    Object.assign(this.#model, model);
+  }
+
+  /** Set resolved params. */
+  setParams(params) {
+    Object.assign(this.#params, params);
+  }
+
+  /** Update element map (after re-render). */
+  updateElements(elements) {
+    this.#elements = elements;
+  }
+
+  // ── Private ───────────────────────────────────────────────
+
+  #setModel(path, value) {
+    setPath(this.#model, path, value);
+    // Notify watchers for this path and any parent paths
+    for (const [watchPath, fns] of this.#watchers) {
+      if (path === watchPath || path.startsWith(watchPath + '/')) {
+        for (const fn of fns) fn(getPath(this.#model, watchPath));
+      }
+    }
+  }
+
+  #watchModel(path, fn) {
+    if (!this.#watchers.has(path)) this.#watchers.set(path, new Set());
+    this.#watchers.get(path).add(fn);
+    return () => {
+      const set = this.#watchers.get(path);
+      set?.delete(fn);
+      if (set?.size === 0) this.#watchers.delete(path);
+    };
+  }
+
+  #getDockable(kind, id) {
+    const entry = this.#docked.get(id);
+    if (entry && entry.dockable.kind === kind) return entry.dockable;
+    return null;
+  }
+
+  #listDockables(kind) {
+    const result = [];
+    for (const { dockable } of this.#docked.values()) {
+      if (!kind || dockable.kind === kind) result.push(dockable);
+    }
+    return result;
+  }
+
+  #emit(adiaEvent) {
+    const target = adiaEvent.target
+      ? this.#elements.get(adiaEvent.target)
+      : this.#rootElement;
+    if (!target) return;
+
+    target.dispatchEvent(new CustomEvent(adiaEvent.event, {
+      bubbles: true,
+      detail: adiaEvent,
+    }));
+  }
+}
+
+// ── JSON Pointer helpers (simplified, "/" delimited) ────────
+
+function getPath(obj, path) {
+  if (!path || path === '/') return obj;
+  const keys = path.replace(/^\//, '').split('/');
+  let current = obj;
+  for (const key of keys) {
+    if (current == null) return undefined;
+    current = current[key];
+  }
+  return current;
+}
+
+function setPath(obj, path, value) {
+  if (!path || path === '/') return;
+  const keys = path.replace(/^\//, '').split('/');
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (current[key] == null) current[key] = {};
+    current = current[key];
+  }
+  current[keys[keys.length - 1]] = value;
+}

package/wire-factory.js

@@ -0,0 +1,134 @@
+/**
+ * Wire Factory — Translates wireComponents messages into typed Dockable objects.
+ *
+ * This is the bridge between the LLM's declarative JSON and the runtime dock system.
+ * Each section of the wireComponents message maps to a Dockable type:
+ *
+ *   data.sources      → DataSourceDock[]
+ *   state.controllers → ControllerDock[]
+ *   actions           → ActionDock[]
+ *   provides          → ProviderDock
+ *   lifecycle         → LifecycleDock
+ *   state.model       → set directly on Surface
+ */
+import { ControllerDock } from './dockables/controller.js';
+import { DataSourceDock } from './dockables/data-source.js';
+import { ActionDock } from './dockables/action.js';
+import { ProviderDock } from './dockables/provider.js';
+import { LifecycleDock } from './dockables/lifecycle.js';
+import { resolveController, resolveData, resolveHandler } from './wiring-registry.js';
+
+/**
+ * Adapt a registry handler (old ctx shape) to the dock signature (config, surfaceCtx, domEvent).
+ * The old handlers read from ctx.action.*, ctx.event, ctx.source, ctx.dataModel, ctx.updateModel, etc.
+ * The new signature passes (config, surfaceCtx, domEventOrResult).
+ */
+function adaptHandler(handlerFn) {
+  return async (config, surfaceCtx, domEventOrResult) => {
+    // Build a backward-compatible HandlerContext from the new args
+    const ctx = {
+      // Config props spread as "action" (old handlers read ctx.action.path, ctx.action.uri, etc.)
+      action: config,
+      // DOM event if present
+      event: domEventOrResult instanceof Event ? domEventOrResult : null,
+      source: domEventOrResult instanceof Event ? domEventOrResult.target : null,
+      // Model access
+      dataModel: surfaceCtx.getModel(),
+      updateModel: (path, value) => surfaceCtx.setModel(path, value),
+      // Controllers lookup
+      controllers: Object.fromEntries(
+        surfaceCtx.listDockables('controller').map(d => [d.id, d.controller])
+      ),
+      // Params
+      params: {},
+      // Data resolver
+      resolveData,
+    };
+    return handlerFn(ctx);
+  };
+}
+
+/**
+ * Create a handler resolver function that looks up from the registry
+ * and wraps with the adapter.
+ * @returns {(name: string) => Function|null}
+ */
+function createHandlerResolver() {
+  const cache = new Map();
+  return (name) => {
+    if (cache.has(name)) return cache.get(name);
+    const raw = resolveHandler(name);
+    if (!raw) return null;
+    const adapted = adaptHandler(raw);
+    cache.set(name, adapted);
+    return adapted;
+  };
+}
+
+/**
+ * Create a controller class resolver (async, lazy-loaded).
+ * @returns {(type: string) => Promise<Function|null>}
+ */
+function createControllerResolver() {
+  return async (type) => resolveController(type);
+}
+
+/**
+ * Create a data resolver that uses the wiring registry.
+ * @returns {(uri: string, ctx: object) => Promise<*>}
+ */
+function createDataResolver() {
+  return async (uri, ctx) => resolveData(uri, {});
+}
+
+/**
+ * Translate a wireComponents message into an array of Dockable objects.
+ *
+ * @param {object} msg — wireComponents message
+ * @returns {{ dockables: import('./dockables/base.js').Dockable[], initialModel: object|null }}
+ */
+export function createDockables(msg) {
+  const dockables = [];
+  const handlerResolver = createHandlerResolver();
+  const controllerResolver = createControllerResolver();
+  const dataResolver = createDataResolver();
+
+  // Data sources
+  if (msg.data?.sources) {
+    for (const source of msg.data.sources) {
+      dockables.push(new DataSourceDock(source, dataResolver));
+    }
+  }
+
+  // Controllers
+  if (msg.state?.controllers) {
+    for (const ctrl of msg.state.controllers) {
+      dockables.push(new ControllerDock(ctrl, controllerResolver));
+    }
+  }
+
+  // Actions
+  if (msg.actions) {
+    for (const action of msg.actions) {
+      dockables.push(new ActionDock(action, handlerResolver));
+    }
+  }
+
+  // Provides
+  if (msg.provides) {
+    const provides = Array.isArray(msg.provides) ? msg.provides : [msg.provides];
+    for (const p of provides) {
+      dockables.push(new ProviderDock(p));
+    }
+  }
+
+  // Lifecycle
+  if (msg.lifecycle) {
+    dockables.push(new LifecycleDock(msg.lifecycle, handlerResolver));
+  }
+
+  // Initial model (not a dockable — set directly on Surface)
+  const initialModel = msg.state?.model || null;
+
+  return { dockables, initialModel };
+}

package/wiring-engine.js

@@ -0,0 +1,209 @@
+/**
+ * Wiring Engine — Processes wireComponents messages via the Surface dock system.
+ *
+ * This is the bridge between the renderer (which receives raw messages)
+ * and the Surface (which manages dockable objects). It:
+ *
+ *   1. Creates/retrieves a Surface for the surfaceId
+ *   2. Resolves params from the message
+ *   3. Translates the message sections into typed Dockables via wire-factory
+ *   4. Docks them in dependency order on the Surface
+ *
+ * The external API is unchanged: process(msg), teardown(surfaceId), teardownAll().
+ */
+
+import { Surface } from './surface.js';
+import { createDockables } from './wire-factory.js';
+
+export class WiringEngine {
+  /** @type {Map<string, Surface>} */
+  #surfaces = new Map();
+
+  /** @type {(surfaceId: string, path: string, data: unknown) => void} */
+  #updateDataModel;
+
+  /** @type {(surfaceId: string, componentId: string) => HTMLElement | null} */
+  #getElement;
+
+  /**
+   * @param {object} opts
+   * @param {(surfaceId: string, path: string, data: unknown) => void} opts.updateDataModel
+   * @param {(surfaceId: string, componentId: string) => HTMLElement | null} opts.getElement
+   */
+  constructor({ updateDataModel, getElement }) {
+    this.#updateDataModel = updateDataModel;
+    this.#getElement = getElement;
+  }
+
+  /**
+   * Process a wireComponents message.
+   * Multiple calls for the same surfaceId are additive (new dockables added,
+   * same-id dockables hot-swapped).
+   *
+   * @param {object} message
+   */
+  async process(message) {
+    const { surfaceId } = message;
+    if (!surfaceId) return;
+
+    let surface = this.#surfaces.get(surfaceId);
+    if (!surface) {
+      surface = this.#createSurface(surfaceId);
+      this.#surfaces.set(surfaceId, surface);
+    }
+
+    try {
+      // Resolve params (before creating dockables, they may need params)
+      if (message.data?.params) {
+        surface.setParams(this.#resolveParams(message.data.params));
+      }
+
+      // Translate message → dockables
+      const { dockables, initialModel } = createDockables(message);
+
+      // Set initial model state before docking
+      if (initialModel) {
+        surface.setInitialModel(initialModel);
+      }
+
+      // Handle explicit undocking
+      if (message.undock) {
+        surface.undockMany(message.undock);
+      }
+
+      // Dock all in dependency order
+      // Some dockables have async dock() (controllers), so we dock sequentially
+      // by kind to maintain order guarantees
+      for (const dockable of dockables) {
+        await surface.dock(dockable);
+      }
+    } catch (err) {
+      console.warn(`Wiring: error processing wireComponents for "${surfaceId}":`, err.message);
+    }
+  }
+
+  /**
+   * Tear down all wiring for a surface.
+   * @param {string} surfaceId
+   */
+  teardown(surfaceId) {
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface) return;
+    surface.undockAll();
+    this.#surfaces.delete(surfaceId);
+  }
+
+  /**
+   * Tear down everything.
+   */
+  teardownAll() {
+    for (const surfaceId of this.#surfaces.keys()) this.teardown(surfaceId);
+  }
+
+  /**
+   * Get a surface for inspection/testing.
+   * @param {string} surfaceId
+   * @returns {Surface|null}
+   */
+  getSurface(surfaceId) {
+    return this.#surfaces.get(surfaceId) || null;
+  }
+
+  /**
+   * Get a wired surface's state (for debugging/inspection).
+   * @param {string} surfaceId
+   */
+  getSurfaceState(surfaceId) {
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface) return null;
+    const dockables = surface.context.listDockables();
+    return {
+      surfaceId,
+      controllerCount: dockables.filter(d => d.kind === 'controller').length,
+      sourceCount: dockables.filter(d => d.kind === 'source').length,
+      actionCount: dockables.filter(d => d.kind === 'action').length,
+      providerCount: dockables.filter(d => d.kind === 'provider').length,
+      hasLifecycle: dockables.some(d => d.kind === 'lifecycle'),
+      totalDocked: dockables.length,
+    };
+  }
+
+  // ── Private ────────────────────────────────────────────────
+
+  /**
+   * Create a Surface wired to the renderer's element map.
+   */
+  #createSurface(surfaceId) {
+    // Create an element proxy that delegates to the renderer's getElement
+    const elementsProxy = {
+      get: (componentId) => this.#getElement(surfaceId, componentId),
+      has: (componentId) => !!this.#getElement(surfaceId, componentId),
+    };
+
+    // The root element is the surface container in the renderer
+    const rootElement = this.#getElement(surfaceId, 'root') || document.createElement('div');
+
+    // Build a Map-like wrapper so Surface can use elements.get()
+    const elements = new Proxy(new Map(), {
+      get(target, prop) {
+        if (prop === 'get') return (id) => elementsProxy.get(id);
+        if (prop === 'has') return (id) => elementsProxy.has(id);
+        return target[prop];
+      },
+    });
+
+    // Wrap updateDataModel so dockables that call ctx.setModel
+    // also flow through to the renderer's data binding system
+    const surface = new Surface(surfaceId, rootElement, elements);
+
+    // Monkey-patch setModel on context to also notify the renderer
+    const originalContext = surface.context;
+    const origSetModel = originalContext.setModel;
+    const updateDataModel = this.#updateDataModel;
+    Object.defineProperty(surface, 'context', {
+      get() {
+        const ctx = originalContext;
+        return {
+          ...ctx,
+          setModel(path, value) {
+            origSetModel(path, value);
+            updateDataModel(surfaceId, path, value);
+          },
+        };
+      },
+    });
+
+    return surface;
+  }
+
+  /**
+   * Resolve parameter declarations to values.
+   * @param {Record<string, { from: string, key: string }>} params
+   * @returns {Record<string, string>}
+   */
+  #resolveParams(params) {
+    const resolved = {};
+    for (const [name, spec] of Object.entries(params)) {
+      switch (spec.from) {
+        case 'route': {
+          const hash = location.hash.slice(1);
+          const match = hash.match(new RegExp(`${spec.key}/([^/]+)`));
+          if (match) resolved[name] = match[1];
+          break;
+        }
+        case 'query': {
+          const url = new URL(location.href);
+          const val = url.searchParams.get(spec.key);
+          if (val) resolved[name] = val;
+          break;
+        }
+        case 'literal':
+          resolved[name] = spec.value;
+          break;
+        default:
+          if (typeof spec === 'string') resolved[name] = spec;
+      }
+    }
+    return resolved;
+  }
+}