@adia-ai/a2ui 0.8.39 → 0.8.41

package/renderer.js

@@ -41,23 +41,85 @@ export class A2UIRenderer {
   #flush() {
     this.#rafId = null;
     const batch = this.#queue.splice(0);
-    for (const msg of batch) this.#processOne(msg);
+    // Per-message error isolation (gh#1364 review finding): #flush runs
+    // inside a requestAnimationFrame callback with no caller to propagate
+    // to — a hard protocol error from ONE message (e.g. REQ-002's
+    // DUPLICATE_SURFACE_ID throw) must not silently drop every remaining
+    // message in the batch, nor escape uncaught where nothing can observe
+    // it. Non-batching `process()` keeps throwing straight to its caller
+    // (a real call site that can catch it) — this isolation is specific
+    // to the queued/rAF path, which <a2ui-root> reaches whenever `batch`
+    // is set.
+    for (const msg of batch) {
+      try {
+        this.#processOne(msg);
+      } catch (err) {
+        console.error('A2UI: message failed during batch flush', err);
+        this.#dispatchDiagnostic(null, 'a2ui-message-error', {
+          error: err, messageType: msg?.type || msg?.messageType,
+        });
+      }
+    }
   }
 
+  // Message kinds that buffer inside an open beginSurfaceUpdate bracket
+  // (spec-a2ui-surface-lifecycle.md). `deleteSurface` is deliberately
+  // absent — it "never buffers... tears down immediately, cancelling any
+  // pending generation" (spec, state-machine section); `createSurface`
+  // targeting an id already in the map always hits the REQ-002 hard-error
+  // branch instead, pending or not.
+  static #BUFFERABLE_KINDS = new Set([
+    'updateComponents', 'updateDataModel', 'wireComponents', 'updateStyles', 'removeStyles',
+  ]);
+
   #processOne(message) {
+    const kind = message.type || message.messageType;
+    const surfaceId = message.surfaceId;
+    if (surfaceId && A2UIRenderer.#BUFFERABLE_KINDS.has(kind)) {
+      const surface = this.#surfaces.get(surfaceId);
+      if (surface && !surface.synthetic && this.#isSurfacePending(surface)) {
+        surface.lifecycle.buffer.push(message);
+        return;
+      }
+    }
+    this.#dispatchMessage(message);
+  }
+
+  // The raw switch — no lifecycle/buffering guard. Called directly by
+  // #processOne for an immediate apply, and by #commitSurfaceUpdate to
+  // replay a bracket's buffer (which must bypass the pending check above,
+  // since the surface is still `pending-*` while its own buffer replays).
+  //
+  // Deliberately NOT declared `async`: a hard synchronous throw here (e.g.
+  // REQ-002's DUPLICATE_SURFACE_ID) must propagate to the caller as a real
+  // synchronous exception — #flush's per-message try/catch (gh#1364 review
+  // finding) and process()'s own direct-throw contract both depend on
+  // that. `async` would silently convert that throw into a rejected
+  // Promise instead. The `wireComponents` branch RETURNS `#wireComponents`'s
+  // own promise (that method is itself `async`) without awaiting it here —
+  // #processOne's call site drops it (fire-and-forget, same as `process()`
+  // always did for wireComponents); #commitSurfaceUpdate's buffer replay
+  // is the one caller that DOES await this return value, so a bracket's
+  // wiring finishes docking (and #wiringEngine is guaranteed initialized)
+  // before #sweepSurvivors runs.
+  #dispatchMessage(message) {
     switch (message.type || message.messageType) {
-      case 'createSurface':    this.#createSurface(message); break;
-      case 'updateComponents': this.#updateComponents(message); break;
-      case 'updateDataModel':  this.#updateDataModel(message); break;
-      case 'wireComponents':   this.#wireComponents(message); break;
-      case 'deleteSurface':    this.#deleteSurface(message); break;
-      case 'updateStyles':     this.#updateStyles(message); break;
-      case 'removeStyles':     this.#removeStyles(message); break;
-      case 'meta':             break; // LLM self-critique — not renderable
-      default: console.warn('A2UI: unknown message type', message.type);
+      case 'createSurface':    this.#createSurface(message); return undefined;
+      case 'updateComponents': this.#updateComponents(message); return undefined;
+      case 'updateDataModel':  this.#updateDataModel(message); return undefined;
+      case 'wireComponents':   return this.#wireComponents(message);
+      case 'deleteSurface':    this.#deleteSurface(message); return undefined;
+      case 'updateStyles':     this.#updateStyles(message); return undefined;
+      case 'removeStyles':     this.#removeStyles(message); return undefined;
+      case 'meta':             return undefined; // LLM self-critique — not renderable
+      default: console.warn('A2UI: unknown message type', message.type); return undefined;
     }
   }
 
+  #isSurfacePending(surface) {
+    return surface.lifecycle.state === 'pending-first' || surface.lifecycle.state === 'pending-stale';
+  }
+
   // ── wireComponents (lazy-loaded) ──
 
   #wiringEngine = null;
@@ -85,7 +147,28 @@ export class A2UIRenderer {
   // ── createSurface ──
 
   #createSurface({ surfaceId, catalogId, root: rootId }) {
-    if (this.#surfaces.has(surfaceId)) return;
+    if (this.#surfaces.has(surfaceId)) {
+      // REQ-002 (spec-a2ui-v1-conformance.md): v1.0 Candidate makes a
+      // duplicate surfaceId a HARD error. Promoted from the P0
+      // diagnostic-only no-op (gh#1350) now that the surface lifecycle API
+      // ships below (gh#1364, ADR-0061's interlock): hosts have a
+      // sanctioned regeneration path — beginSurfaceUpdate → applyTo →
+      // commitSurfaceUpdate (spec-a2ui-surface-lifecycle.md) — so a second
+      // createSurface for an existing id is no longer anyone's only route.
+      // The diagnostic event still fires first (observability parity with
+      // the P0 shape) before the throw.
+      const existing = this.#surfaces.get(surfaceId);
+      this.#dispatchDiagnostic(existing.root, 'a2ui-duplicate-surface-id', { surfaceId });
+      const err = new Error(
+        `A2UI: duplicate createSurface for surfaceId "${surfaceId}" — REQ-002 ` +
+        `(spec-a2ui-v1-conformance.md) makes this a hard error. Regenerate an ` +
+        `existing surface with renderer.beginSurfaceUpdate(surfaceId) → applyTo ` +
+        `→ commitSurfaceUpdate instead (spec-a2ui-surface-lifecycle.md).`
+      );
+      err.code = 'DUPLICATE_SURFACE_ID';
+      err.surfaceId = surfaceId;
+      throw err;
+    }
 
     const root = document.createElement('div');
     root.setAttribute('data-a2ui-surface', surfaceId);
@@ -106,6 +189,19 @@ export class A2UIRenderer {
       // Populated by #updateStyles; cleared by #removeStyles / #deleteSurface.
       // See .claude/docs/specs/genui-css-channel.md §5.4.
       adoptedSheets: new Map(),
+      // Surface lifecycle (spec-a2ui-surface-lifecycle.md, ADR-0061,
+      // gh#1364): pending/stale/healing state machine, one per real
+      // (createSurface'd) surface. `synthetic: false` marks that the
+      // lifecycle contract applies — see #beginSurfaceUpdate below.
+      synthetic: false,
+      lifecycle: {
+        state: 'empty',
+        generationId: null,
+        buffer: null,
+        mode: 'replace',
+        reason: null,
+        hadError: false,
+      },
     });
   }
 
@@ -125,6 +221,14 @@ export class A2UIRenderer {
         bindings: new Map(),
         // CSS channel parity with #createSurface (see spec §5.4).
         adoptedSheets: new Map(),
+        // Surface lifecycle (gh#1364): synthetic surfaces share the
+        // renderer's #container as their root — there is no per-surface
+        // element to carry per-surface lifecycle state, so they are
+        // outside the lifecycle contract by ruling
+        // (spec-a2ui-surface-lifecycle.md's state-machine section).
+        // #beginSurfaceUpdate no-ops with a console warn for these.
+        synthetic: true,
+        lifecycle: null,
       };
       this.#surfaces.set(surfaceId, surface);
       // CSS channel: tag the container so the @scope wrapper has an anchor
@@ -414,6 +518,11 @@ export class A2UIRenderer {
   #deleteSurface({ surfaceId }) {
     const surface = this.#surfaces.get(surfaceId);
     if (!surface) return;
+    // Surface lifecycle (gh#1364): deleteSurface is not a BUFFERABLE_KIND
+    // (see #processOne) — it always runs immediately, per spec: "never
+    // buffers... tears down immediately, cancelling any pending
+    // generation." The whole record (lifecycle included) is deleted below,
+    // so any in-flight bracket is simply gone — no separate cancel step.
     this.#wiringEngine?.teardown(surfaceId);
     for (const [id] of surface.elements) this.#elements.delete(id);
     // CSS channel: splice any adopted stylesheets out of the document.
@@ -428,6 +537,288 @@ export class A2UIRenderer {
     this.#surfaces.delete(surfaceId);
   }
 
+  // ── Surface lifecycle (spec-a2ui-surface-lifecycle.md, ADR-0061, gh#1364) ──
+  //
+  // Per-surface pending/stale/healing state machine, driven by a public
+  // host API: beginSurfaceUpdate → applyTo (buffers) → commitSurfaceUpdate
+  // (or abortSurfaceUpdate). Strictly additive (REQ-011): a surface whose
+  // begin is never called stays in `empty` forever and every existing
+  // call path (process/processStream/applyTo-while-live) behaves exactly
+  // as before.
+
+  #genCounter = 0;
+
+  #mintGenerationId() {
+    this.#genCounter += 1;
+    return `g${this.#genCounter}-${Date.now().toString(36)}`;
+  }
+
+  #setLifecycleAttr(surface, state) {
+    surface.root?.setAttribute?.('data-a2ui-lifecycle', state);
+  }
+
+  // Dispatch a bubbling CustomEvent for a surface lifecycle transition
+  // (REQ-010) — surface-pending / surface-committed / surface-aborted.
+  // Same fail-silent shape as #dispatchStylesEvent / #dispatchDiagnostic.
+  #dispatchLifecycleEvent(target, eventName, detail) {
+    const node = target || this.#container;
+    if (!node || typeof CustomEvent === 'undefined') return;
+    try {
+      node.dispatchEvent(new CustomEvent(eventName, { detail, bubbles: true, composed: false }));
+    } catch {
+      // Hard fail-silent — event dispatch should never break the renderer.
+    }
+  }
+
+  /**
+   * Begin a regeneration bracket for `surfaceId` (REQ-002/006/008).
+   * `empty`/`error-empty` → `pending-first`; `live`/`error-stale` →
+   * `pending-stale`. A begin on an already-pending surface supersedes the
+   * older generation (REQ-008) — its buffer is discarded. No-op (console
+   * warn) for a missing or synthetic surface (state-machine ruling).
+   *
+   * @param {string} surfaceId
+   * @param {{generationId?: string, reason?: 'refine'|'revalidate'|'regenerate', mode?: 'replace'|'patch'}} [opts]
+   * @returns {string|null} the minted/echoed generationId, or null on no-op
+   */
+  beginSurfaceUpdate(surfaceId, { generationId, reason = null, mode = 'replace' } = {}) {
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface) {
+      console.warn(`A2UI: beginSurfaceUpdate — no such surface "${surfaceId}"`);
+      return null;
+    }
+    if (surface.synthetic) {
+      console.warn(
+        `A2UI: beginSurfaceUpdate — surfaceId "${surfaceId}" is synthetic ` +
+        `(no prior createSurface); lifecycle is a no-op here. Send createSurface first.`
+      );
+      return null;
+    }
+
+    const lc = surface.lifecycle;
+    const wasError = lc.state === 'error-empty' || lc.state === 'error-stale';
+    const hadContent = lc.state === 'live' || lc.state === 'error-stale';
+    const nextState = hadContent ? 'pending-stale' : 'pending-first';
+
+    lc.state = nextState;
+    lc.generationId = typeof generationId === 'string' && generationId ? generationId : this.#mintGenerationId();
+    lc.buffer = [];
+    lc.mode = mode === 'patch' ? 'patch' : 'replace';
+    lc.reason = reason;
+    lc.hadError = wasError;
+
+    this.#setLifecycleAttr(surface, nextState);
+    this.#dispatchLifecycleEvent(surface.root, 'surface-pending', {
+      surfaceId, generationId: lc.generationId, reason, firstRender: nextState === 'pending-first',
+    });
+    return lc.generationId;
+  }
+
+  /**
+   * Apply messages targeting `surfaceId`. While the surface is pending
+   * (inside a beginSurfaceUpdate bracket), messages buffer and apply
+   * atomically at commitSurfaceUpdate (REQ-003). Outside a bracket,
+   * applies immediately — identical to calling process() for that
+   * message, so legacy callers that never touch the lifecycle API see no
+   * difference (REQ-011).
+   *
+   * @param {string} surfaceId
+   * @param {object|object[]} messages
+   */
+  applyTo(surfaceId, messages) {
+    const list = Array.isArray(messages) ? messages : [messages];
+    for (const msg of list) this.#processOne({ ...msg, surfaceId });
+  }
+
+  /**
+   * Commit the in-flight generation for `surfaceId`: applies the buffered
+   * bracket atomically (REQ-003). `replace` mode (default) sweeps
+   * components the new answer no longer declares — the survivor set is
+   * the union of component ids across every buffered updateComponents
+   * batch (REQ-004); buffered `updateStyles` replace the surface's
+   * `adoptedSheets` set the same way (any styleId not re-declared this
+   * bracket is dropped). `patch` mode applies with today's upsert-only
+   * semantics for both. A commit whose `generationId` doesn't match the
+   * current in-flight generation is ignored as stale (REQ-008).
+   *
+   * `async` (gh#1364 review finding): the buffer replay AWAITS each
+   * dispatched message — specifically so a buffered `wireComponents`
+   * finishes docking (and `#wiringEngine` is guaranteed initialized)
+   * before the sweep runs; every other message kind resolves its await
+   * immediately (`#dispatchMessage` returns a bare value for them, not a
+   * promise it made you wait on).
+   *
+   * @param {string} surfaceId
+   * @param {string} [generationId] — when passed, must match the surface's
+   *   current in-flight generation.
+   * @returns {Promise<boolean>} true if the commit applied
+   */
+  async commitSurfaceUpdate(surfaceId, generationId) {
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface || surface.synthetic) {
+      console.warn(`A2UI: commitSurfaceUpdate — no such lifecycle surface "${surfaceId}"`);
+      return false;
+    }
+    const lc = surface.lifecycle;
+    if (!this.#isSurfacePending(surface)) {
+      console.warn(`A2UI: commitSurfaceUpdate — surface "${surfaceId}" has no in-flight generation to commit`);
+      return false;
+    }
+    if (generationId != null && generationId !== lc.generationId) {
+      return false; // REQ-008 — a superseded generationId is ignored, not an error.
+    }
+
+    const buffer = lc.buffer || [];
+    const committedGenerationId = lc.generationId;
+    const healed = lc.hadError;
+
+    let swept = [];
+    let stylesSwept = [];
+    if (lc.mode === 'replace') {
+      const survivors = new Set();
+      let sawComponents = false;
+      const survivorStyleIds = new Set();
+      let sawStyles = false;
+      for (const msg of buffer) {
+        const kind = msg.type || msg.messageType;
+        if (kind === 'updateComponents') {
+          sawComponents = true;
+          for (const comp of msg.components || []) {
+            if (comp.id != null) survivors.add(comp.id);
+          }
+        } else if (kind === 'updateStyles') {
+          sawStyles = true;
+          if (typeof msg.styleId === 'string') survivorStyleIds.add(msg.styleId);
+        }
+      }
+      for (const msg of buffer) await this.#dispatchMessage(msg);
+      // Only sweep when this bracket actually declared a component/style
+      // set — a bracket carrying only e.g. updateDataModel sweeps
+      // neither, since it never named a survivor set at all.
+      if (sawComponents) swept = this.#sweepSurvivors(surfaceId, survivors);
+      if (sawStyles) stylesSwept = this.#sweepStyles(surfaceId, survivorStyleIds);
+    } else {
+      for (const msg of buffer) await this.#dispatchMessage(msg);
+    }
+
+    lc.state = 'live';
+    lc.buffer = null;
+    lc.generationId = null;
+    lc.reason = null;
+    lc.hadError = false;
+
+    this.#setLifecycleAttr(surface, 'live');
+    this.#dispatchLifecycleEvent(surface.root, 'surface-committed', {
+      surfaceId, generationId: committedGenerationId, healed, swept, stylesSwept,
+    });
+    return true;
+  }
+
+  // Remove every adoptedSheets entry in `surfaceId` outside
+  // `survivorStyleIds` — buffered `updateStyles` replace the surface's
+  // style set the same way replace-mode replaces its component set
+  // (REQ-004's style-sweep half). Same removal path as #removeStyles,
+  // including its `styles-removed` event per dropped styleId.
+  #sweepStyles(surfaceId, survivorStyleIds) {
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface || !surface.adoptedSheets || surface.adoptedSheets.size === 0) return [];
+    const swept = [];
+    for (const styleId of [...surface.adoptedSheets.keys()]) {
+      if (survivorStyleIds.has(styleId)) continue;
+      const entry = surface.adoptedSheets.get(styleId);
+      document.adoptedStyleSheets = document.adoptedStyleSheets.filter(s => s !== entry.sheet);
+      surface.adoptedSheets.delete(styleId);
+      this.#dispatchStylesEvent(surface.root, 'styles-removed', { surfaceId, styleId });
+      swept.push(styleId);
+    }
+    return swept;
+  }
+
+  // Remove every element id in `surfaceId`'s element map outside
+  // `survivors` — DOM, elements, bindings, #prevProps, and any docked
+  // wiring for those ids (existing per-id undock path, surface.js:107-113,
+  // reached via WiringEngine#undockIds). REQ-004.
+  #sweepSurvivors(surfaceId, survivors) {
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface) return [];
+    const swept = [];
+    for (const id of [...surface.elements.keys()]) {
+      if (survivors.has(id)) continue;
+      const el = surface.elements.get(id);
+      el?.remove();
+      surface.elements.delete(id);
+      this.#elements.delete(id);
+      surface.bindings.delete(id);
+      this.#prevProps.delete(id);
+      swept.push(id);
+    }
+    if (swept.length > 0) this.#wiringEngine?.undockIds(surfaceId, swept);
+    return swept;
+  }
+
+  /**
+   * Abort the in-flight generation for `surfaceId` — the old answer (if
+   * any) stays visible (REQ-007). `pending-first` → `error-empty`;
+   * `pending-stale` → `error-stale`. A superseded `generationId` is
+   * ignored (REQ-008), same as commit.
+   *
+   * @param {string} surfaceId
+   * @param {string} [generationId]
+   * @param {object} [error]
+   * @returns {boolean} true if the abort applied
+   */
+  abortSurfaceUpdate(surfaceId, generationId, error) {
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface || surface.synthetic) {
+      console.warn(`A2UI: abortSurfaceUpdate — no such lifecycle surface "${surfaceId}"`);
+      return false;
+    }
+    const lc = surface.lifecycle;
+    if (!this.#isSurfacePending(surface)) {
+      console.warn(`A2UI: abortSurfaceUpdate — surface "${surfaceId}" has no in-flight generation to abort`);
+      return false;
+    }
+    if (generationId != null && generationId !== lc.generationId) {
+      return false; // REQ-008 — stale abort ignored
+    }
+
+    const abortedGenerationId = lc.generationId;
+    const nextState = lc.state === 'pending-first' ? 'error-empty' : 'error-stale';
+
+    lc.state = nextState;
+    lc.buffer = null;
+    lc.generationId = null;
+    lc.reason = null;
+    lc.hadError = true;
+
+    this.#setLifecycleAttr(surface, nextState);
+    this.#dispatchLifecycleEvent(surface.root, 'surface-aborted', {
+      surfaceId, generationId: abortedGenerationId, error: error ?? null,
+    });
+    return true;
+  }
+
+  /** Read-only lifecycle snapshot for `surfaceId`, or null (missing/synthetic). */
+  getLifecycle(surfaceId) {
+    const surface = this.#surfaces.get(surfaceId);
+    return surface && !surface.synthetic ? surface.lifecycle : null;
+  }
+
+  /** True while `surfaceId` has an in-flight generation (pending-first/pending-stale). */
+  isPending(surfaceId) {
+    const lc = this.getLifecycle(surfaceId);
+    return lc?.state === 'pending-first' || lc?.state === 'pending-stale';
+  }
+
+  /** IDs of every surface currently pending — hosts reflect this as one boolean (a2ui-root's `pending`). */
+  get pendingSurfaces() {
+    const out = [];
+    for (const [id, s] of this.#surfaces) {
+      if (!s.synthetic && this.#isSurfacePending(s)) out.push(id);
+    }
+    return out;
+  }
+
   // ── CSS channel (updateStyles / removeStyles) ──
   // Spec: .claude/docs/specs/genui-css-channel.md
   // Implements Phase 1 of the gen-ui parallel-channels initiative.
@@ -676,6 +1067,24 @@ export class A2UIRenderer {
     }
   }
 
+  // Dispatch a bubbling CustomEvent for a non-fatal protocol diagnostic
+  // (REQ-002's duplicate-surfaceId case today). Same fail-silent shape as
+  // #dispatchStylesEvent but a distinct, generically-named method — this
+  // has nothing to do with the CSS channel.
+  #dispatchDiagnostic(target, eventName, detail) {
+    const node = target || this.#container;
+    if (!node || typeof CustomEvent === 'undefined') return;
+    try {
+      node.dispatchEvent(new CustomEvent(eventName, {
+        detail,
+        bubbles: true,
+        composed: false,
+      }));
+    } catch {
+      // Hard fail-silent — event dispatch should never break the renderer.
+    }
+  }
+
   // ── Public ──
 
   getSurface(id) { return this.#surfaces.get(id); }

package/stream.js

@@ -145,12 +145,20 @@ export function mcpStream(url, options = {}) {
 
 /**
  * Helper: extract A2UI messages from a JSON-RPC `result.content` array
- * and push them into a queue/resolver pair.
+ * and push them into a queue/resolver pair. Exported (underscore-prefixed,
+ * still internal) so stream.test.js can exercise the MIME-flip logic
+ * directly without standing up a fake MCP transport.
  */
-function _extractA2UIFromRpc(rpc, push) {
+export function _extractA2UIFromRpc(rpc, push) {
   if (rpc.result?.content) {
     for (const block of rpc.result.content) {
-      if (block.type === 'resource' && block.resource?.mimeType === 'application/json+a2ui') {
+      if (
+        block.type === 'resource' &&
+        // v1.0 Candidate MIME (REQ-001); the pre-Candidate form is still
+        // accepted on read for the transition (spec-a2ui-v1-conformance).
+        (block.resource?.mimeType === 'application/a2ui+json' ||
+          block.resource?.mimeType === 'application/json+a2ui')
+      ) {
         try {
           const messages = JSON.parse(block.resource.text);
           for (const msg of (Array.isArray(messages) ? messages : [messages])) push(msg);

package/wiring-engine.d.ts

@@ -44,6 +44,13 @@ export declare class WiringEngine {
    */
   teardown(surfaceId: string): void;
 
+  /**
+   * Undock specific dockable ids for a surface without tearing down the
+   * whole surface (called by the renderer's replace-mode lifecycle commit
+   * sweep — spec-a2ui-surface-lifecycle.md REQ-004, gh#1364).
+   */
+  undockIds(surfaceId: string, ids: string[]): void;
+
   /**
    * Tear down all wired surfaces.
    */

package/wiring-engine.js

@@ -93,6 +93,21 @@ export class WiringEngine {
     this.#surfaces.delete(surfaceId);
   }
 
+  /**
+   * Undock specific dockable ids for a surface without tearing down the
+   * whole surface — used by the renderer's replace-mode commit sweep
+   * (spec-a2ui-surface-lifecycle.md REQ-004, gh#1364): swept component ids
+   * lose their wiring too, but the surface itself (and its other docked
+   * dockables) survive the commit.
+   * @param {string} surfaceId
+   * @param {string[]} ids
+   */
+  undockIds(surfaceId, ids) {
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface) return;
+    surface.undockMany(ids);
+  }
+
   /**
    * Tear down everything.
    */