@adia-ai/a2ui-runtime 0.3.0

package/stream.js

@@ -0,0 +1,243 @@
+/**
+ * A2UI Stream Adapters — connect to various transports and yield A2UI messages.
+ *
+ * Each adapter returns an AsyncIterable<A2UIMessage>.
+ *
+ * Usage:
+ *   const stream = sseStream('/api/agent');
+ *   for await (const message of stream) { renderer.process(message); }
+ */
+
+/**
+ * SSE (Server-Sent Events) stream adapter.
+ */
+export function sseStream(url, options = {}) {
+  let finalUrl = url;
+  if (options.catalog) {
+    const types = options.catalog instanceof Map ? [...options.catalog.keys()] : Object.keys(options.catalog);
+    const sep = url.includes('?') ? '&' : '?';
+    finalUrl = `${url}${sep}a2ui_catalog=${encodeURIComponent(types.join(','))}`;
+  }
+
+  return {
+    [Symbol.asyncIterator]() {
+      const eventSource = new EventSource(finalUrl);
+      const queue = [];
+      let resolve = null;
+      let done = false;
+
+      eventSource.onmessage = (e) => {
+        try {
+          const message = JSON.parse(e.data);
+          if (resolve) { const r = resolve; resolve = null; r({ value: message, done: false }); }
+          else queue.push(message);
+        } catch { console.warn('A2UI SSE: invalid JSON', e.data); }
+      };
+
+      eventSource.onerror = () => {
+        done = true;
+        eventSource.close();
+        if (resolve) { const r = resolve; resolve = null; r({ value: undefined, done: true }); }
+      };
+
+      if (options.signal) {
+        options.signal.addEventListener('abort', () => {
+          done = true;
+          eventSource.close();
+          if (resolve) { const r = resolve; resolve = null; r({ value: undefined, done: true }); }
+        });
+      }
+
+      return {
+        next() {
+          if (queue.length > 0) return Promise.resolve({ value: queue.shift(), done: false });
+          if (done) return Promise.resolve({ value: undefined, done: true });
+          return new Promise(r => { resolve = r; });
+        },
+        return() {
+          done = true;
+          eventSource.close();
+          return Promise.resolve({ value: undefined, done: true });
+        },
+      };
+    },
+  };
+}
+
+/**
+ * WebSocket stream adapter.
+ */
+export function wsStream(url, options = {}) {
+  return {
+    [Symbol.asyncIterator]() {
+      const ws = new WebSocket(url);
+      const queue = [];
+      let resolve = null;
+      let done = false;
+
+      ws.onopen = () => {
+        if (options.catalog) {
+          const types = options.catalog instanceof Map ? [...options.catalog.keys()] : Object.keys(options.catalog);
+          ws.send(JSON.stringify({ type: 'a2ui:catalog', supportedTypes: types }));
+        }
+      };
+
+      ws.onmessage = (e) => {
+        try {
+          const message = JSON.parse(e.data);
+          if (resolve) { const r = resolve; resolve = null; r({ value: message, done: false }); }
+          else queue.push(message);
+        } catch { console.warn('A2UI WS: invalid JSON', e.data); }
+      };
+
+      ws.onclose = () => {
+        done = true;
+        if (resolve) { const r = resolve; resolve = null; r({ value: undefined, done: true }); }
+      };
+
+      ws.onerror = () => { done = true; ws.close(); };
+
+      return {
+        next() {
+          if (queue.length > 0) return Promise.resolve({ value: queue.shift(), done: false });
+          if (done) return Promise.resolve({ value: undefined, done: true });
+          return new Promise(r => { resolve = r; });
+        },
+        return() { done = true; ws.close(); return Promise.resolve({ value: undefined, done: true }); },
+      };
+    },
+  };
+}
+
+/**
+ * Array/mock stream adapter — for testing.
+ */
+export function mockStream(messages, delay = 0) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (const msg of messages) {
+        if (delay > 0) await new Promise(r => setTimeout(r, delay));
+        yield msg;
+      }
+    },
+  };
+}
+
+/**
+ * MCP stream adapter — connects to MCP server, yields A2UI messages.
+ */
+export function mcpStream(url, options = {}) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      const { signal, catalog, onAction } = options;
+
+      const ws = new WebSocket(url);
+      await new Promise((resolve, reject) => {
+        ws.onopen = resolve;
+        ws.onerror = reject;
+        if (signal) signal.addEventListener('abort', () => {
+          ws.close();
+          reject(new DOMException('Aborted', 'AbortError'));
+        }, { once: true });
+      });
+
+      if (catalog) {
+        const types = catalog instanceof Map ? [...catalog.keys()] : Object.keys(catalog);
+        ws.send(JSON.stringify({
+          jsonrpc: '2.0',
+          method: 'a2ui/catalog',
+          params: { supportedTypes: types },
+        }));
+      }
+
+      const queue = [];
+      let resolve = null;
+      let done = false;
+
+      ws.onmessage = (e) => {
+        try {
+          const rpc = JSON.parse(e.data);
+
+          if (rpc.result?.content) {
+            for (const block of rpc.result.content) {
+              if (block.type === 'resource' && block.resource?.mimeType === 'application/json+a2ui') {
+                const messages = JSON.parse(block.resource.text);
+                for (const msg of (Array.isArray(messages) ? messages : [messages])) {
+                  if (resolve) { const r = resolve; resolve = null; r({ value: msg, done: false }); }
+                  else queue.push(msg);
+                }
+              } else if (block.type === 'text') {
+                try {
+                  const msg = JSON.parse(block.text);
+                  if (msg.type && (msg.type.startsWith('create') || msg.type.startsWith('update') || msg.type.startsWith('delete'))) {
+                    if (resolve) { const r = resolve; resolve = null; r({ value: msg, done: false }); }
+                    else queue.push(msg);
+                  }
+                } catch { /* not A2UI */ }
+              }
+            }
+          }
+
+          if (rpc.method === 'a2ui/action' && onAction) {
+            onAction(rpc.params?.name, rpc.params?.arguments).then(result => {
+              ws.send(JSON.stringify({ jsonrpc: '2.0', id: rpc.id, result }));
+            }).catch(err => {
+              ws.send(JSON.stringify({ jsonrpc: '2.0', id: rpc.id, error: { code: -1, message: err.message } }));
+            });
+          }
+        } catch { console.warn('A2UI MCP: invalid message', e.data); }
+      };
+
+      ws.onclose = () => { done = true; if (resolve) { const r = resolve; resolve = null; r({ value: undefined, done: true }); } };
+      ws.onerror = () => { done = true; ws.close(); };
+      if (signal) signal.addEventListener('abort', () => { done = true; ws.close(); if (resolve) { const r = resolve; resolve = null; r({ value: undefined, done: true }); } });
+
+      while (!done || queue.length > 0) {
+        if (queue.length > 0) { yield queue.shift(); }
+        else if (done) { break; }
+        else {
+          const v = await new Promise(r => { resolve = r; });
+          if (v.done) break;
+          yield v.value;
+        }
+      }
+    },
+  };
+}
+
+/**
+ * JSONL (newline-delimited JSON) stream adapter via fetch.
+ */
+export function jsonlStream(url, options = {}) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      const headers = {};
+      if (options.catalog) {
+        const types = options.catalog instanceof Map ? [...options.catalog.keys()] : Object.keys(options.catalog);
+        headers['X-A2UI-Catalog'] = types.join(',');
+      }
+      const response = await fetch(url, { signal: options.signal, headers });
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop();
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          try { yield JSON.parse(trimmed); }
+          catch { console.warn('A2UI JSONL: invalid JSON', trimmed); }
+        }
+      }
+      if (buffer.trim()) {
+        try { yield JSON.parse(buffer.trim()); }
+        catch { /* ignore */ }
+      }
+    },
+  };
+}

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