@adia-ai/a2ui 0.8.37

package/renderer.js

@@ -0,0 +1,715 @@
+/**
+ * A2UI Renderer — processes A2UI messages and renders AdiaUI components.
+ *
+ * Usage:
+ *   import { A2UIRenderer } from './renderer.js';
+ *   const renderer = new A2UIRenderer(container);
+ *   renderer.process(message);
+ */
+
+import { resolveTag, registry } from './registry.js';
+import { applyResolvedProp, toAttr } from './prop-apply.js';
+
+export class A2UIRenderer {
+  #container;
+  #registry;
+  #surfaces = new Map();
+  #elements = new Map();
+  #prevProps = new Map();
+  #queue = [];
+  #rafId = null;
+  #batching = false;
+
+  constructor(container, reg = registry, { batch = false } = {}) {
+    this.#container = container;
+    this.#registry = reg;
+    this.#batching = batch;
+  }
+
+  process(message) {
+    if (!message) return;
+    if (this.#batching) {
+      this.#queue.push(message);
+      if (this.#rafId === null) {
+        this.#rafId = requestAnimationFrame(() => this.#flush());
+      }
+    } else {
+      this.#processOne(message);
+    }
+  }
+
+  #flush() {
+    this.#rafId = null;
+    const batch = this.#queue.splice(0);
+    for (const msg of batch) this.#processOne(msg);
+  }
+
+  #processOne(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);
+    }
+  }
+
+  // ── wireComponents (lazy-loaded) ──
+
+  #wiringEngine = null;
+
+  async #wireComponents(message) {
+    if (!this.#wiringEngine) {
+      const { WiringEngine } = await import('./wiring-engine.js');
+      this.#wiringEngine = new WiringEngine({
+        updateDataModel: (surfaceId, path, data) => {
+          this.#updateDataModel({ surfaceId, path, value: data });
+        },
+        getElement: (surfaceId, componentId) => {
+          const surface = this.#surfaces.get(surfaceId);
+          return surface?.elements.get(componentId) || null;
+        },
+      });
+    }
+    await this.#wiringEngine.process(message);
+  }
+
+  async processStream(stream) {
+    for await (const message of stream) this.process(message);
+  }
+
+  // ── createSurface ──
+
+  #createSurface({ surfaceId, catalogId, root: rootId }) {
+    if (this.#surfaces.has(surfaceId)) return;
+
+    const root = document.createElement('div');
+    root.setAttribute('data-a2ui-surface', surfaceId);
+    if (catalogId) root.setAttribute('data-catalog', catalogId);
+    this.#container.appendChild(root);
+
+    this.#surfaces.set(surfaceId, {
+      root,
+      // `rootId` = the id of the component to attach as the surface's
+      // rendered root. Honors the A2UI protocol's `createSurface.root`
+      // field when present; falls back to the legacy `'root'` convention
+      // that earlier docs baked in. See #updateComponents attach step.
+      rootId: typeof rootId === 'string' && rootId ? rootId : 'root',
+      elements: new Map(),
+      dataModel: {},
+      bindings: new Map(),
+      // CSS channel (Phase 1): styleId -> { sheet, ruleCount, appliedAt }.
+      // Populated by #updateStyles; cleared by #removeStyles / #deleteSurface.
+      // See .claude/docs/specs/genui-css-channel.md §5.4.
+      adoptedSheets: new Map(),
+    });
+  }
+
+  // ── updateComponents ──
+
+  #updateComponents({ surfaceId, components }) {
+    let surface = this.#surfaces.get(surfaceId);
+
+    if (!surface) {
+      surface = {
+        root: this.#container,
+        // Synthetic surfaces (updateComponents without a prior
+        // createSurface) default to the legacy 'root' convention.
+        rootId: 'root',
+        elements: new Map(),
+        dataModel: {},
+        bindings: new Map(),
+        // CSS channel parity with #createSurface (see spec §5.4).
+        adoptedSheets: new Map(),
+      };
+      this.#surfaces.set(surfaceId, surface);
+      // CSS channel: tag the container so the @scope wrapper has an anchor
+      // to match. Without this, synthetic surfaces (those created lazily by
+      // updateComponents) silently fail to receive their styles — the
+      // @scope wrapper is valid CSS but matches no element. The setAttribute
+      // is idempotent if the container already carries the attribute from a
+      // prior createSurface.
+      if (this.#container && typeof this.#container.setAttribute === 'function') {
+        this.#container.setAttribute('data-a2ui-surface', surfaceId);
+      }
+    }
+
+    // First pass: create/update elements
+    for (const comp of components) {
+      if (!comp.id && comp.id !== 0) continue;
+      if (comp.component === 'ContextBindings') {
+        surface.contextBindings = comp;
+        continue;
+      }
+
+      try {
+        let el = surface.elements.get(comp.id);
+        const tagName = comp.component === 'Text'
+          ? this.#resolveTextTag(comp.variant, comp)
+          : resolveTag(comp.component, this.#registry);
+
+        if (!tagName) {
+          if (!el) {
+            el = document.createElement('div');
+            el.setAttribute('data-a2ui-id', comp.id);
+            el.id = comp.id;
+            el.setAttribute('data-a2ui-unknown', comp.component);
+            el.textContent = `[unknown: ${comp.component}]`;
+            surface.elements.set(comp.id, el);
+            this.#elements.set(comp.id, el);
+          }
+          continue;
+        }
+
+        if (!el) {
+          el = document.createElement(tagName);
+          el.setAttribute('data-a2ui-id', comp.id);
+          el.id = comp.id;
+          surface.elements.set(comp.id, el);
+          this.#elements.set(comp.id, el);
+        } else if (el.localName !== tagName) {
+          const newEl = document.createElement(tagName);
+          newEl.setAttribute('data-a2ui-id', comp.id);
+          newEl.id = comp.id;
+          el.replaceWith(newEl);
+          el = newEl;
+          surface.elements.set(comp.id, el);
+          this.#elements.set(comp.id, el);
+        }
+
+        comp._surfaceId = surfaceId;
+
+        const hasBindings = Object.values(comp).some(v => v && typeof v === 'object' && v.path);
+        if (hasBindings) surface.bindings.set(comp.id, comp);
+
+        this.#applyProps(el, comp);
+      } catch (err) {
+        console.warn(`A2UI: component "${comp.id}" (${comp.component}) failed:`, err.message);
+      }
+    }
+
+    // Structural validation: warn when Card/Drawer body content skips
+    // the canonical <Section> wrap. Mirrors scripts/audit/audit-card-structure.mjs
+    // (which scans authored HTML) — this hook catches runtime-built trees
+    // where the audit can't see. See feedback_card_drawer_body_section_wrap
+    // memory + packages/web-components/components/{card,drawer}/yaml.
+    this.#validateContainerStructure(components);
+
+    // Build parent map for cycle detection
+    const parentMap = new Map();
+    for (const comp of components) {
+      for (const childId of (Array.isArray(comp.children) ? comp.children : [])) {
+        parentMap.set(childId, comp.id);
+      }
+      if (comp.child) parentMap.set(comp.child, comp.id);
+    }
+
+    const wouldCycle = (parentId, childId) => {
+      const visited = new Set();
+      let cursor = parentId;
+      while (cursor != null) {
+        if (cursor === childId) return true;
+        if (visited.has(cursor)) return true;
+        visited.add(cursor);
+        cursor = parentMap.get(cursor);
+      }
+      return false;
+    };
+
+    // Second pass: build tree
+    for (const comp of components) {
+      const el = surface.elements.get(comp.id);
+      if (!el) continue;
+
+      try {
+        const childIds = Array.isArray(comp.children) ? comp.children : [];
+        for (const childId of childIds) {
+          if (childId === comp.id || wouldCycle(comp.id, childId)) continue;
+          const childEl = surface.elements.get(childId);
+          if (childEl && childEl.parentElement !== el) el.appendChild(childEl);
+        }
+
+        if (comp.child && comp.child !== comp.id && !wouldCycle(comp.id, comp.child)) {
+          const childEl = surface.elements.get(comp.child);
+          if (childEl && childEl.parentElement !== el) el.appendChild(childEl);
+        }
+      } catch (err) {
+        console.warn(`A2UI: tree build failed for "${comp.id}":`, err.message);
+      }
+    }
+
+    // Attach root — use the surface's declared rootId (from
+    // createSurface.root) if present, else fall back to the legacy
+    // 'root' convention. Both surface.rootId and the fallback are
+    // looked up in the same elements Map.
+    const attachId = surface.rootId ?? 'root';
+    const rootComp = components.find(c => c.id === attachId);
+    if (rootComp) {
+      const rootEl = surface.elements.get(attachId);
+      if (rootEl && rootEl.parentElement !== surface.root) {
+        surface.root.appendChild(rootEl);
+      }
+    }
+  }
+
+  // ── Structural validation (Card / Drawer body contract) ──
+
+  static #CARD_CANONICAL_CHILDREN = new Set([
+    'Header', 'Section', 'Footer',
+    // Media-first siblings (mirrors audit-card-structure.mjs whitelist):
+    // void/media elements may sit as siblings of header/section/footer.
+    'Img', 'Image', 'Video', 'Picture', 'Iframe',
+    // Layout siblings:
+    //   Aside    — "card with side nav" pattern per aside.yaml.
+    //   Divider  — visual rule between sibling content blocks (pricing-tier
+    //              pattern in eval-025).
+    'Aside', 'Divider',
+  ]);
+
+  static #DRAWER_CANONICAL_CHILDREN = new Set([
+    'Header', 'Section', 'Footer',
+  ]);
+
+  // Slot values that opt a child into a canonical body slot
+  // (drawer-ui supports explicit [slot="header|body|footer"]; card-ui
+  // accepts header/section/footer children for the same slots).
+  static #CANONICAL_SLOT_VALUES = new Set(['header', 'body', 'footer']);
+
+  #warnedStructure = new Set();
+
+  #validateContainerStructure(components) {
+    const componentsById = new Map();
+    for (const comp of components) {
+      if (comp.id != null) componentsById.set(comp.id, comp);
+    }
+
+    for (const comp of components) {
+      const isCard = comp.component === 'Card' || comp.component === 'ErrorContainer';
+      const isDrawer = comp.component === 'Drawer';
+      if (!isCard && !isDrawer) continue;
+
+      const allowed = isDrawer
+        ? A2UIRenderer.#DRAWER_CANONICAL_CHILDREN
+        : A2UIRenderer.#CARD_CANONICAL_CHILDREN;
+      const containerLabel = isDrawer ? '<drawer-ui>' : '<card-ui>';
+
+      const childIds = Array.isArray(comp.children) ? comp.children : [];
+      for (const childId of childIds) {
+        const child = componentsById.get(childId);
+        if (!child) continue;
+        // Allow if child has slot attribute matching canonical body slots
+        if (typeof child.slot === 'string'
+            && A2UIRenderer.#CANONICAL_SLOT_VALUES.has(child.slot)) continue;
+        if (allowed.has(child.component)) continue;
+
+        const key = `${comp.id}::${childId}::${child.component}`;
+        if (this.#warnedStructure.has(key)) continue;
+        this.#warnedStructure.add(key);
+        console.warn(
+          `A2UI: ${containerLabel} (id="${comp.id}") body must wrap "${child.component}" ` +
+          `(id="${childId}") in <Section>. Direct flow children bypass the canonical body ` +
+          `slot and lose --card-inset margin. Canonical children: ${[...allowed].join(', ')}` +
+          (isDrawer ? `, or slot="header|body|footer".` : `.`)
+        );
+      }
+    }
+  }
+
+  // ── Apply props ──
+
+  // Semantic HTML variants — these render as native tags (h1, p, small)
+  // Everything else renders as <text-ui> which is now display:inline
+  static #TEXT_TAG_MAP = {
+    h1: 'h1', h2: 'h2', h3: 'h3', h4: 'h4', h5: 'h5', h6: 'h6',
+    body: 'p', caption: 'small',
+  };
+
+  #resolveTextTag(variant, comp) {
+    // Semantic HTML variants get native tags (accessibility)
+    if (!comp?.slot && A2UIRenderer.#TEXT_TAG_MAP[variant]) {
+      return A2UIRenderer.#TEXT_TAG_MAP[variant];
+    }
+    // Everything else → text-ui (inline, supports truncate/lines/variant)
+    return 'text-ui';
+  }
+
+  #applyProps(el, comp) {
+    const skip = new Set(['id', 'component', 'children', 'child', '_surfaceId']);
+    // Skip variant attr when the tag IS the variant (h1 for h1, p for body, small for caption)
+    if (comp.component === 'Text' && comp.variant && !comp.slot && A2UIRenderer.#TEXT_TAG_MAP[comp.variant]) {
+      skip.add('variant');
+    }
+
+    const prev = this.#prevProps.get(comp.id);
+    const next = {};
+
+    for (const [key, value] of Object.entries(comp)) {
+      if (skip.has(key)) continue;
+
+      const isBinding = value && typeof value === 'object' && value.path;
+      const resolved = this.#resolveValue(value, comp._surfaceId);
+      next[key] = resolved;
+
+      if (prev && Object.is(prev[key], resolved)) continue;
+
+      if (resolved == null && !isBinding) continue; // no value, no binding to clear either
+
+      applyResolvedProp(el, key, resolved);
+    }
+
+    if (prev) {
+      for (const key of Object.keys(prev)) {
+        if (!(key in next) && !skip.has(key)) el.removeAttribute(toAttr(key));
+      }
+    }
+
+    this.#prevProps.set(comp.id, next);
+  }
+
+  #resolveValue(value, surfaceId) {
+    if (value == null) return null;
+    if (typeof value !== 'object') return value;
+    if (value.path) {
+      const surface = surfaceId ? this.#surfaces.get(surfaceId) : null;
+      return surface ? this.#getByPath(surface.dataModel, value.path) : value.path;
+    }
+    return value;
+  }
+
+  #getByPath(obj, path) {
+    if (!path || path === '/') return obj;
+    return path.split('/').filter(Boolean).reduce((o, k) => o?.[k], obj);
+  }
+
+  // ── updateDataModel ──
+
+  #updateDataModel({ surfaceId, path, value }) {
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface) return;
+
+    if (!path || path === '/') {
+      surface.dataModel = value ?? {};
+    } else {
+      const parts = path.split('/').filter(Boolean);
+      let cur = surface.dataModel;
+      for (let i = 0; i < parts.length - 1; i++) {
+        if (cur[parts[i]] == null) cur[parts[i]] = {};
+        cur = cur[parts[i]];
+      }
+      cur[parts[parts.length - 1]] = value;
+    }
+
+    for (const [compId, comp] of surface.bindings) {
+      const el = surface.elements.get(compId);
+      if (el) this.#applyProps(el, comp);
+    }
+  }
+
+  // ── deleteSurface ──
+
+  #deleteSurface({ surfaceId }) {
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface) return;
+    this.#wiringEngine?.teardown(surfaceId);
+    for (const [id] of surface.elements) this.#elements.delete(id);
+    // CSS channel: splice any adopted stylesheets out of the document.
+    if (surface.adoptedSheets && surface.adoptedSheets.size > 0) {
+      const toRemove = new Set();
+      for (const entry of surface.adoptedSheets.values()) toRemove.add(entry.sheet);
+      document.adoptedStyleSheets = document.adoptedStyleSheets
+        .filter(s => !toRemove.has(s));
+      surface.adoptedSheets.clear();
+    }
+    surface.root.remove();
+    this.#surfaces.delete(surfaceId);
+  }
+
+  // ── CSS channel (updateStyles / removeStyles) ──
+  // Spec: .claude/docs/specs/genui-css-channel.md
+  // Implements Phase 1 of the gen-ui parallel-channels initiative.
+
+  // Forbidden top-level selector tokens — these would pollute document scope
+  // even after @scope wrapping (CSS @scope does not constrain @-rules like
+  // @charset; :root / html / body matches OUTSIDE the scope root would still
+  // be authored as document-targeting intent and are rejected up front).
+  static #CSS_FORBIDDEN_TOP_SELECTORS = new Set(['root', 'html', 'body']);
+
+  #updateStyles({ surfaceId, styleId, css }) {
+    if (typeof styleId !== 'string' || styleId.length === 0) {
+      this.#dispatchStylesEvent(null, 'styles-rejected',
+        { surfaceId, styleId, reason: 'invalid-payload: styleId must be a non-empty string' });
+      return;
+    }
+    if (typeof css !== 'string') {
+      this.#dispatchStylesEvent(null, 'styles-rejected',
+        { surfaceId, styleId, reason: 'invalid-payload: css must be a string' });
+      return;
+    }
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface) {
+      this.#dispatchStylesEvent(null, 'styles-rejected',
+        { surfaceId, styleId, reason: 'no-such-surface' });
+      return;
+    }
+
+    const result = this.#validateAndPrepareStyles(css, surfaceId);
+    if (result.rejected) {
+      // Prior valid sheet (if any) is preserved on rejection — see spec §4.7.
+      this.#dispatchStylesEvent(surface.root, 'styles-rejected',
+        { surfaceId, styleId, reason: result.reason });
+      return;
+    }
+
+    // Replace any existing sheet with this styleId
+    const prior = surface.adoptedSheets.get(styleId);
+    if (prior) {
+      document.adoptedStyleSheets = document.adoptedStyleSheets
+        .filter(s => s !== prior.sheet);
+    }
+
+    document.adoptedStyleSheets = [...document.adoptedStyleSheets, result.sheet];
+    surface.adoptedSheets.set(styleId, {
+      sheet: result.sheet,
+      ruleCount: result.sheet.cssRules.length,
+      appliedAt: typeof performance !== 'undefined' ? performance.now() : Date.now(),
+    });
+
+    this.#dispatchStylesEvent(surface.root, 'styles-applied', {
+      surfaceId,
+      styleId,
+      ruleCount: result.sheet.cssRules.length,
+      validationWarnings: result.warnings,
+    });
+  }
+
+  #removeStyles({ surfaceId, styleId }) {
+    const surface = this.#surfaces.get(surfaceId);
+    if (!surface) return;
+    const entry = surface.adoptedSheets.get(styleId);
+    if (!entry) return; // idempotent — no event, no error
+    document.adoptedStyleSheets = document.adoptedStyleSheets
+      .filter(s => s !== entry.sheet);
+    surface.adoptedSheets.delete(styleId);
+    this.#dispatchStylesEvent(surface.root, 'styles-removed', { surfaceId, styleId });
+  }
+
+  // Validate + prepare a stylesheet for adoption. Returns
+  //   { rejected: true, reason }  on failure
+  //   { rejected: false, sheet, warnings }  on success
+  // Spec: §4 (validator rules) + §6.3 (scope wrapping).
+  #validateAndPrepareStyles(css, surfaceId) {
+    const warnings = [];
+
+    // §4.2 — source-text checks for @-rules that some parsers strip
+    // before they appear as CSSRule objects (notably @import and @charset).
+    // Done FIRST so the reason is reported in priority order. Multiline
+    // mode handles css that contains the @-rule mid-source after whitespace.
+    if (/^\s*@import\b/im.test(css))  return { rejected: true, reason: 'forbidden-import' };
+    if (/^\s*@charset\b/im.test(css)) return { rejected: true, reason: 'forbidden-charset' };
+
+    // §4.1 — parse validation (initial probe)
+    const probe = new CSSStyleSheet();
+    try {
+      probe.replaceSync(css);
+    } catch (err) {
+      return { rejected: true, reason: 'parse-error: ' + (err?.message || String(err)) };
+    }
+
+    // §4.2 — forbidden constructs (scan top-level rules)
+    for (const rule of probe.cssRules) {
+      const forbidden = this.#scanForbiddenRule(rule);
+      if (forbidden) return { rejected: true, reason: forbidden };
+    }
+
+    // §4.2 — external URL scan (text-level — covers url() inside declarations)
+    if (/url\s*\(\s*["']?\s*(?:https?:|\/\/)/i.test(css)) {
+      return { rejected: true, reason: 'external-url' };
+    }
+
+    // §4.4 — @property warnings
+    for (const rule of probe.cssRules) {
+      if (rule.constructor?.name === 'CSSPropertyRule' || rule.cssText?.startsWith('@property')) {
+        const m = rule.cssText.match(/@property\s+(--[\w-]+)/);
+        if (m) warnings.push({ kind: 'property-registered-globally', name: m[1] });
+      }
+    }
+
+    // §4.5 — animation-name rewriting (mutates `probe`)
+    const renamedAnimations = this.#rewriteAnimationNames(probe, surfaceId);
+
+    // §6.3 — scope wrapping
+    const wrappedCss = this.#wrapInScope(probe, surfaceId);
+
+    // Final adoption sheet
+    const sheet = new CSSStyleSheet();
+    try {
+      sheet.replaceSync(wrappedCss);
+    } catch (err) {
+      return { rejected: true, reason: 'scope-wrap-failed: ' + (err?.message || String(err)) };
+    }
+    if (renamedAnimations.length > 0) {
+      warnings.push({ kind: 'animations-namespaced', count: renamedAnimations.length });
+    }
+    return { rejected: false, sheet, warnings };
+  }
+
+  // Scan a single top-level CSSRule for forbidden constructs. Returns the
+  // rejection reason string or null if the rule is clean.
+  #scanForbiddenRule(rule) {
+    const text = rule.cssText || '';
+    // @import, @charset, @scope (user-side) — keyed off cssText prefix
+    if (/^@import\b/i.test(text))  return 'forbidden-import';
+    if (/^@charset\b/i.test(text)) return 'forbidden-charset';
+    if (/^@scope\b/i.test(text))   return 'forbidden-scope-directive';
+    // Style rules (CSSStyleRule) — inspect selectorText for document-level targets
+    if (rule.selectorText) {
+      // Split selector list on commas, ignoring commas inside parens.
+      const selectors = this.#splitSelectors(rule.selectorText);
+      for (const sel of selectors) {
+        const trimmed = sel.trim().replace(/^:scope\s*/, ''); // :scope-prefixed is allowed
+        // ':root' parses as a pseudo-class — check FIRST (it doesn't match the
+        // tag-name regex below, but it's the single most common forbidden form).
+        if (trimmed.startsWith(':root')) return 'forbidden-root-selector';
+        // Match bare 'root', 'html', 'body' tokens as the leading simple selector
+        const lead = trimmed.match(/^([a-zA-Z*][\w-]*)/);
+        if (!lead) continue;
+        const tag = lead[1].toLowerCase();
+        if (A2UIRenderer.#CSS_FORBIDDEN_TOP_SELECTORS.has(tag)) return `forbidden-${tag}-selector`;
+      }
+    }
+    return null;
+  }
+
+  // Split a selector list on top-level commas (respects parens for :is(), :where(), :has()).
+  #splitSelectors(selectorText) {
+    const out = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < selectorText.length; i++) {
+      const ch = selectorText[i];
+      if (ch === '(') depth++;
+      else if (ch === ')') depth--;
+      else if (ch === ',' && depth === 0) {
+        out.push(selectorText.slice(start, i));
+        start = i + 1;
+      }
+    }
+    out.push(selectorText.slice(start));
+    return out;
+  }
+
+  // Rewrite @keyframes names with a <surfaceId>_ prefix and update any
+  // matching animation / animation-name declarations in the same sheet.
+  // Mutates `probe` in place via insertRule/deleteRule. Returns the list of
+  // renamed (original -> new) keyframes for the warnings payload.
+  #rewriteAnimationNames(probe, surfaceId) {
+    const renamed = [];
+    const safePrefix = String(surfaceId).replace(/[^a-zA-Z0-9_-]/g, '_');
+
+    // First pass — find @keyframes rules
+    for (let i = 0; i < probe.cssRules.length; i++) {
+      const rule = probe.cssRules[i];
+      if (rule.constructor?.name === 'CSSKeyframesRule' || rule.cssText?.startsWith('@keyframes')) {
+        const oldName = rule.name;
+        if (!oldName) continue;
+        const newName = `${safePrefix}_${oldName}`;
+        // CSSKeyframesRule has a writable .name in modern browsers
+        try {
+          rule.name = newName;
+        } catch {
+          // Fallback: rewrite via deleteRule + insertRule
+          const newText = rule.cssText.replace(/@keyframes\s+[\w-]+/, `@keyframes ${newName}`);
+          probe.deleteRule(i);
+          probe.insertRule(newText, i);
+        }
+        renamed.push({ from: oldName, to: newName });
+      }
+    }
+
+    if (renamed.length === 0) return renamed;
+
+    // Second pass — rewrite animation / animation-name declarations
+    const renameMap = new Map(renamed.map(r => [r.from, r.to]));
+    for (const rule of probe.cssRules) {
+      if (!rule.style) continue;
+      for (const prop of ['animation', 'animation-name']) {
+        const val = rule.style.getPropertyValue(prop);
+        if (!val) continue;
+        // Tokenize on whitespace / commas; substitute matching names
+        const rewritten = val.replace(/\b([\w-]+)\b/g, (match) =>
+          renameMap.has(match) ? renameMap.get(match) : match
+        );
+        if (rewritten !== val) rule.style.setProperty(prop, rewritten);
+      }
+    }
+    return renamed;
+  }
+
+  // Wrap the probe's rules in @scope ([data-a2ui-surface="<id>"]) { ... }.
+  // Returns the new CSS source as a string (re-parsed into a fresh sheet
+  // by the caller).
+  #wrapInScope(probe, surfaceId) {
+    const inner = [];
+    for (const rule of probe.cssRules) inner.push(rule.cssText);
+    const safeId = String(surfaceId).replace(/"/g, '\\"');
+    return `@scope ([data-a2ui-surface="${safeId}"]) {\n${inner.join('\n')}\n}`;
+  }
+
+  // Dispatch a CustomEvent for the CSS channel lifecycle. Bubbles from the
+  // surface root when present; falls back to the renderer #container when
+  // no surface root exists (e.g. updateStyles for unknown surfaceId).
+  #dispatchStylesEvent(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); }
+  getElement(id) { return this.#elements.get(id); }
+  get surfaces() { return [...this.#surfaces.keys()]; }
+
+  // CSS channel — read-only accessor for adopted stylesheets per surface.
+  // Returns a Map<styleId, { sheet, ruleCount, appliedAt }> or an empty Map.
+  getStylesheets(surfaceId) {
+    const surface = this.#surfaces.get(surfaceId);
+    return surface?.adoptedSheets ?? new Map();
+  }
+
+  reset() {
+    if (this.#rafId !== null) { cancelAnimationFrame(this.#rafId); this.#rafId = null; }
+    this.#queue.length = 0;
+    // CSS channel — splice every surface's adopted stylesheets before tear-down
+    const allAdopted = new Set();
+    for (const [, s] of this.#surfaces) {
+      if (s.adoptedSheets) for (const entry of s.adoptedSheets.values()) allAdopted.add(entry.sheet);
+    }
+    if (allAdopted.size > 0) {
+      document.adoptedStyleSheets = document.adoptedStyleSheets
+        .filter(s => !allAdopted.has(s));
+    }
+    for (const [, s] of this.#surfaces) {
+      if (s.root === this.#container) s.root.innerHTML = '';
+      else s.root.remove();
+    }
+    this.#surfaces.clear();
+    this.#elements.clear();
+    this.#prevProps.clear();
+  }
+
+  set batching(v) { this.#batching = !!v; }
+  get batching() { return this.#batching; }
+}