@adia-ai/a2ui-compose 0.0.1

package/engine/context-store.js

@@ -0,0 +1,218 @@
+/**
+ * Context Store — Cross-surface shared state (A008 §8).
+ *
+ * Manages named contexts that multiple surfaces can read from and write to.
+ * When the first participating surface mounts, the context is populated.
+ * When the last participating surface unmounts, the context is eligible
+ * for garbage collection.
+ *
+ * This is the horizontal equivalent of A007's provider (vertical, parent→child).
+ * Contexts live outside any single surface's lifecycle.
+ */
+
+/**
+ * @typedef {object} ContextEntry
+ * @property {string} name
+ * @property {object} shape — Schema of the context data
+ * @property {object} data — Current data
+ * @property {Set<string>} participants — Surface IDs consuming this context
+ * @property {object} source — How to populate { uri, refresh, params }
+ * @property {boolean} populated — Whether data has been fetched
+ * @property {Set<(data: object) => void>} listeners — Change listeners
+ */
+
+export class ContextStore {
+  /** @type {Map<string, ContextEntry>} */
+  #contexts = new Map();
+
+  /**
+   * Define a shared context (usually from a surface manifest).
+   *
+   * @param {string} name — Context name
+   * @param {object} config
+   * @param {object} config.shape — Data shape schema
+   * @param {object} [config.source] — { uri, refresh, params }
+   */
+  define(name, config) {
+    if (this.#contexts.has(name)) return; // Already defined
+
+    this.#contexts.set(name, {
+      name,
+      shape: config.shape || {},
+      data: {},
+      participants: new Set(),
+      source: config.source || null,
+      populated: false,
+      listeners: new Set(),
+    });
+  }
+
+  /**
+   * Register a surface as a participant in a context.
+   * If this is the first participant and a source is defined, triggers population.
+   *
+   * @param {string} contextName
+   * @param {string} surfaceId
+   * @param {(uri: string, params: Record<string, string>) => Promise<unknown>} [fetcher] — Data fetcher
+   * @param {Record<string, string>} [params]
+   */
+  async join(contextName, surfaceId, fetcher, params = {}) {
+    let ctx = this.#contexts.get(contextName);
+    if (!ctx) {
+      // Auto-define if not pre-defined
+      ctx = { name: contextName, shape: {}, data: {}, participants: new Set(), source: null, populated: false, listeners: new Set() };
+      this.#contexts.set(contextName, ctx);
+    }
+
+    ctx.participants.add(surfaceId);
+
+    // Populate on first join (if source exists and not already populated)
+    if (!ctx.populated && ctx.source && fetcher) {
+      try {
+        let uri = ctx.source.uri;
+        const resolvedParams = { ...ctx.source.params, ...params };
+        for (const [key, spec] of Object.entries(resolvedParams)) {
+          const value = typeof spec === 'string' ? spec : spec.value || '';
+          uri = uri.replace(`{${key}}`, encodeURIComponent(value));
+        }
+        ctx.data = await fetcher(uri, resolvedParams);
+        ctx.populated = true;
+        this.#notify(contextName);
+      } catch (err) {
+        console.warn(`ContextStore: failed to populate "${contextName}":`, err.message);
+      }
+    }
+
+    return ctx.data;
+  }
+
+  /**
+   * Unregister a surface from a context.
+   * If no participants remain, mark for potential cleanup.
+   *
+   * @param {string} contextName
+   * @param {string} surfaceId
+   */
+  leave(contextName, surfaceId) {
+    const ctx = this.#contexts.get(contextName);
+    if (!ctx) return;
+
+    ctx.participants.delete(surfaceId);
+
+    // Eligible for GC when no participants
+    if (ctx.participants.size === 0) {
+      ctx.populated = false;
+      ctx.data = {};
+    }
+  }
+
+  /**
+   * Get the current data for a context.
+   *
+   * @param {string} contextName
+   * @returns {object | null}
+   */
+  get(contextName) {
+    return this.#contexts.get(contextName)?.data ?? null;
+  }
+
+  /**
+   * Read a specific key from a context.
+   *
+   * @param {string} contextName
+   * @param {string} key — Dot-separated path (e.g., "patient.name")
+   * @returns {unknown}
+   */
+  read(contextName, key) {
+    const data = this.get(contextName);
+    if (!data || !key) return data;
+
+    const segments = key.split('.');
+    let current = data;
+    for (const seg of segments) {
+      if (current == null || typeof current !== 'object') return undefined;
+      current = current[seg];
+    }
+    return current;
+  }
+
+  /**
+   * Update data in a context. Notifies all listeners.
+   *
+   * @param {string} contextName
+   * @param {object} data — Partial or full data update (merged)
+   */
+  update(contextName, data) {
+    const ctx = this.#contexts.get(contextName);
+    if (!ctx) return;
+
+    ctx.data = { ...ctx.data, ...data };
+    ctx.populated = true;
+    this.#notify(contextName);
+  }
+
+  /**
+   * Subscribe to context changes.
+   *
+   * @param {string} contextName
+   * @param {(data: object) => void} listener
+   * @returns {() => void} — Unsubscribe function
+   */
+  subscribe(contextName, listener) {
+    const ctx = this.#contexts.get(contextName);
+    if (!ctx) return () => {};
+
+    ctx.listeners.add(listener);
+    return () => ctx.listeners.delete(listener);
+  }
+
+  /**
+   * Check if a context is populated with data.
+   * @param {string} contextName
+   * @returns {boolean}
+   */
+  isPopulated(contextName) {
+    return this.#contexts.get(contextName)?.populated ?? false;
+  }
+
+  /**
+   * Get all defined context names.
+   * @returns {string[]}
+   */
+  get contextNames() {
+    return [...this.#contexts.keys()];
+  }
+
+  /**
+   * Get diagnostic info for a context.
+   * @param {string} contextName
+   */
+  inspect(contextName) {
+    const ctx = this.#contexts.get(contextName);
+    if (!ctx) return null;
+    return {
+      name: ctx.name,
+      populated: ctx.populated,
+      participantCount: ctx.participants.size,
+      participants: [...ctx.participants],
+      listenerCount: ctx.listeners.size,
+      dataKeys: Object.keys(ctx.data),
+    };
+  }
+
+  /** Clear all contexts. */
+  clear() {
+    this.#contexts.clear();
+  }
+
+  #notify(contextName) {
+    const ctx = this.#contexts.get(contextName);
+    if (!ctx) return;
+    for (const listener of ctx.listeners) {
+      try { listener(ctx.data); } catch { /* listener error */ }
+    }
+  }
+}
+
+/** Singleton shared context store for the application. */
+export const sharedContextStore = new ContextStore();