@adia-ai/a2ui 0.8.37

package/surface-manifest.js

@@ -0,0 +1,294 @@
+/**
+ * Surface Manifest — Multi-surface relationship document (A008).
+ *
+ * Manages a graph of surfaces and their associations:
+ *   routes-to, feeds, shares-context, depends-on, triggers, contains, slots-into
+ *
+ * The manifest is the design-time document that describes application topology.
+ * The runtime reads it to set up navigation, pre-fetch data, and manage
+ * cross-surface context.
+ */
+
+/**
+ * @typedef {object} SurfaceDescriptor
+ * @property {string} name — Human-readable name
+ * @property {string} [route] — URL pattern with :param placeholders
+ * @property {boolean} [entryPoint] — Can user navigate here directly?
+ * @property {string[]} [requiredParams] — Params needed to render
+ * @property {Record<string, object>} [produces] — Data this surface outputs
+ * @property {Record<string, { keys: string[] }>} [consumes] — Named contexts consumed
+ * @property {string} [status] — generated | manual | template | placeholder
+ * @property {string} [generatedBy] — Execution ID from gen-ui pipeline
+ * @property {string[]} [tags] — Freeform tags
+ */
+
+/**
+ * @typedef {object} Association
+ * @property {string} type — routes-to | feeds | shares-context | depends-on | triggers | contains | slots-into
+ * @property {string} from — Source surface ID
+ * @property {string} to — Target surface ID
+ * @property {string} [trigger] — What activates this association
+ * @property {Record<string, object>} [params] — Data passed from source to target
+ * @property {object} [mapping] — Data flow mapping (for feeds)
+ * @property {string} [context] — Shared context name (for shares-context)
+ * @property {string} [condition] — Dependency condition (for depends-on)
+ * @property {string} [fallback] — Fallback action (for depends-on)
+ * @property {string} [effect] — Side effect (for triggers)
+ * @property {string} [slot] — Composition slot (for contains/slots-into)
+ * @property {number} [position] — Order within slot
+ * @property {object} [meta] — Freeform metadata
+ */
+
+export class SurfaceManifest {
+  #id;
+  #name;
+  #version;
+  /** @type {Map<string, SurfaceDescriptor>} */
+  #surfaces = new Map();
+  /** @type {Association[]} */
+  #associations = [];
+  /** @type {Map<string, object>} */
+  #sharedContexts = new Map();
+
+  /**
+   * @param {object} opts
+   * @param {string} opts.id — Manifest ID
+   * @param {string} opts.name — Human-readable name
+   * @param {string} [opts.version]
+   */
+  constructor({ id, name, version = '1.0.0' }) {
+    this.#id = id;
+    this.#name = name;
+    this.#version = version;
+  }
+
+  // ── Surface CRUD ──
+
+  /**
+   * Add or update a surface descriptor.
+   * @param {string} surfaceId
+   * @param {SurfaceDescriptor} descriptor
+   */
+  addSurface(surfaceId, descriptor) {
+    this.#surfaces.set(surfaceId, { ...descriptor });
+  }
+
+  /**
+   * Remove a surface and all its associations.
+   * @param {string} surfaceId
+   */
+  removeSurface(surfaceId) {
+    this.#surfaces.delete(surfaceId);
+    this.#associations = this.#associations.filter(
+      a => a.from !== surfaceId && a.to !== surfaceId
+    );
+  }
+
+  /**
+   * Get a surface descriptor.
+   * @param {string} surfaceId
+   * @returns {SurfaceDescriptor | null}
+   */
+  getSurface(surfaceId) {
+    return this.#surfaces.get(surfaceId) ?? null;
+  }
+
+  /** @returns {string[]} */
+  get surfaceIds() {
+    return [...this.#surfaces.keys()];
+  }
+
+  // ── Associations ──
+
+  /**
+   * Add an association between surfaces.
+   * @param {Association} association
+   */
+  addAssociation(association) {
+    // Validate surfaces exist
+    if (!this.#surfaces.has(association.from)) {
+      console.warn(`Manifest: surface "${association.from}" not found`);
+      return;
+    }
+    if (!this.#surfaces.has(association.to)) {
+      console.warn(`Manifest: surface "${association.to}" not found`);
+      return;
+    }
+
+    // Deduplicate: same type + from + to replaces existing
+    this.#associations = this.#associations.filter(
+      a => !(a.type === association.type && a.from === association.from && a.to === association.to)
+    );
+    this.#associations.push({ ...association });
+  }
+
+  /**
+   * Get associations for a surface (outgoing).
+   * @param {string} surfaceId
+   * @param {string} [type] — Filter by association type
+   * @returns {Association[]}
+   */
+  getAssociationsFrom(surfaceId, type) {
+    return this.#associations.filter(
+      a => a.from === surfaceId && (!type || a.type === type)
+    );
+  }
+
+  /**
+   * Get associations targeting a surface (incoming).
+   * @param {string} surfaceId
+   * @param {string} [type]
+   * @returns {Association[]}
+   */
+  getAssociationsTo(surfaceId, type) {
+    return this.#associations.filter(
+      a => a.to === surfaceId && (!type || a.type === type)
+    );
+  }
+
+  /**
+   * Get all surfaces sharing a context with the given surface.
+   * @param {string} surfaceId
+   * @returns {{ surfaceId: string, context: string }[]}
+   */
+  getSharedContextPeers(surfaceId) {
+    const peers = [];
+    for (const a of this.#associations) {
+      if (a.type !== 'shares-context') continue;
+      if (a.from === surfaceId) peers.push({ surfaceId: a.to, context: a.context });
+      if (a.to === surfaceId) peers.push({ surfaceId: a.from, context: a.context });
+    }
+    return peers;
+  }
+
+  // ── Shared Contexts ──
+
+  /**
+   * Define a shared context.
+   * @param {string} name
+   * @param {object} config — { shape, source, params }
+   */
+  defineSharedContext(name, config) {
+    this.#sharedContexts.set(name, { ...config });
+  }
+
+  /**
+   * Get a shared context definition.
+   * @param {string} name
+   * @returns {object | null}
+   */
+  getSharedContext(name) {
+    return this.#sharedContexts.get(name) ?? null;
+  }
+
+  // ── Validation ──
+
+  /**
+   * Validate the manifest for common issues.
+   * @returns {{ valid: boolean, issues: { severity: string, message: string }[] }}
+   */
+  validate() {
+    const issues = [];
+
+    // Check for orphan surfaces (no associations)
+    for (const id of this.#surfaces.keys()) {
+      const hasAssoc = this.#associations.some(a => a.from === id || a.to === id);
+      if (!hasAssoc && this.#surfaces.size > 1) {
+        issues.push({ severity: 'warning', message: `Surface "${id}" has no associations` });
+      }
+    }
+
+    // Check for missing entry points
+    const entryPoints = [...this.#surfaces.entries()].filter(([, d]) => d.entryPoint);
+    if (entryPoints.length === 0 && this.#surfaces.size > 0) {
+      issues.push({ severity: 'warning', message: 'No surface marked as entryPoint' });
+    }
+
+    // Check depends-on has fallback
+    for (const a of this.#associations) {
+      if (a.type === 'depends-on' && !a.fallback) {
+        issues.push({ severity: 'warning', message: `depends-on from "${a.from}" to "${a.to}" has no fallback` });
+      }
+    }
+
+    // Check shares-context references defined contexts
+    for (const a of this.#associations) {
+      if (a.type === 'shares-context' && a.context && !this.#sharedContexts.has(a.context)) {
+        issues.push({ severity: 'error', message: `Shared context "${a.context}" referenced but not defined` });
+      }
+    }
+
+    // Check feeds associations have trigger
+    for (const a of this.#associations) {
+      if (a.type === 'feeds' && !a.trigger) {
+        issues.push({ severity: 'warning', message: `feeds from "${a.from}" to "${a.to}" has no trigger` });
+      }
+    }
+
+    // Check routes-to targets have routes
+    for (const a of this.#associations) {
+      if (a.type === 'routes-to') {
+        const target = this.#surfaces.get(a.to);
+        if (target && !target.route) {
+          issues.push({ severity: 'error', message: `routes-to target "${a.to}" has no route defined` });
+        }
+      }
+    }
+
+    return {
+      valid: !issues.some(i => i.severity === 'error'),
+      issues,
+    };
+  }
+
+  // ── Serialization ──
+
+  /**
+   * Export as a JSON-serializable object.
+   * @returns {object}
+   */
+  toJSON() {
+    return {
+      $schema: 'https://a2ui.dev/schema/relationships/v1',
+      id: this.#id,
+      name: this.#name,
+      version: this.#version,
+      surfaces: Object.fromEntries(this.#surfaces),
+      associations: [...this.#associations],
+      sharedContexts: Object.fromEntries(this.#sharedContexts),
+    };
+  }
+
+  /**
+   * Import from a JSON object.
+   * @param {object} json
+   * @returns {SurfaceManifest}
+   */
+  static fromJSON(json) {
+    const manifest = new SurfaceManifest({
+      id: json.id,
+      name: json.name,
+      version: json.version,
+    });
+
+    if (json.surfaces) {
+      for (const [id, desc] of Object.entries(json.surfaces)) {
+        manifest.addSurface(id, desc);
+      }
+    }
+
+    if (json.sharedContexts) {
+      for (const [name, config] of Object.entries(json.sharedContexts)) {
+        manifest.defineSharedContext(name, config);
+      }
+    }
+
+    if (json.associations) {
+      for (const assoc of json.associations) {
+        manifest.addAssociation(assoc);
+      }
+    }
+
+    return manifest;
+  }
+}

package/surface.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+
+import type { Dockable } from './dockables/base.js';
+
+/** The context object passed to every Dockable.dock() call. */
+export interface SurfaceContext {
+  readonly surfaceId: string;
+  getElement(id: string): HTMLElement | null;
+  getRootElement(): HTMLElement;
+  getModel(path?: string): unknown;
+  setModel(path: string, value: unknown): void;
+  getDockable(kind: string, id: string): Dockable | null;
+  listDockables(kind?: string): Dockable[];
+  emit(adiaEvent: AdiaEvent): void;
+  getParam(key: string): unknown;
+  watchModel(path: string, fn: (value: unknown) => void): () => void;
+}
+
+/** Event descriptor passed to Surface.context.emit(). */
+export interface AdiaEvent {
+  event: string;
+  target?: string;
+  [key: string]: unknown;
+}
+
+export declare class Surface {
+  /** The unique surface ID. */
+  readonly surfaceId: string;
+
+  /**
+   * @param surfaceId   - Unique surface identifier.
+   * @param rootElement - The surface's root DOM node.
+   * @param elements    - Map of componentId → DOM element.
+   */
+  constructor(
+    surfaceId: string,
+    rootElement: HTMLElement,
+    elements: Map<string, HTMLElement>,
+  );
+
+  /** The surface context object passed to dockables. */
+  readonly context: SurfaceContext;
+
+  /** Dock a dockable, calling its dock(context) method. */
+  dock(dockable: Dockable): void;
+
+  /** Dock multiple dockables in dependency order (provider → controller → source → action → lifecycle). */
+  dockAll(dockables: Dockable[]): void;
+
+  /** Undock by id, calling cleanup then dockable.undock(). */
+  undock(id: string): void;
+
+  /** Undock everything in reverse dependency order. */
+  undockAll(): void;
+
+  /** Undock specific ids. */
+  undockMany(ids: string[]): void;
+
+  /** Set initial model state (before docking). */
+  setInitialModel(model: Record<string, unknown>): void;
+
+  /** Set resolved params. */
+  setParams(params: Record<string, unknown>): void;
+
+  /** Update the element map (after re-render). */
+  updateElements(elements: Map<string, HTMLElement>): void;
+}

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/types.d.ts

@@ -0,0 +1,26 @@
+// AUTO-GENERATED re-export: runtime/types.d.ts now delegates to the schema codegen.
+// The schema (a2ui.schema.json) is the authoritative source for A2UIMessage shapes.
+// Regenerate with: node scripts/build/a2ui-schema-types.mjs
+
+export type {
+  A2UIMessage,
+  A2UIComponent,
+  CreateSurfaceMessage,
+  UpdateComponentsMessage,
+  UpdateDataModelMessage,
+  WireComponentsMessage,
+  WireAction,
+  WireDataSource,
+  WireState,
+  DeleteSurfaceMessage,
+  MetaMessage,
+} from './a2ui.schema.js';
+
+/** String literal union of all valid A2UI message type discriminators. */
+export type A2UIMessageType =
+  | 'createSurface'
+  | 'updateComponents'
+  | 'updateDataModel'
+  | 'wireComponents'
+  | 'deleteSurface'
+  | 'meta';