@adia-ai/a2ui-runtime 0.6.33 → 0.6.34

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog — @adia-ai/a2ui-runtime
 
+## [0.6.34] — 2026-05-23
+
+### Added — Phase 1 CSS channel: `updateStyles` + `removeStyles`
+
+- **CSS channel — Phase 1** (commit `d664bee22`): runtime gains `updateStyles(id, patch)` + `removeStyles(id, keys)` APIs for parallel-channel CSS-token updates from a2ui messages. Lets agents send token-only updates (`{"--button-bg": "var(--a-accent-strong)"}`) without re-emitting the full component tree. Companion smoke + tests + visual eval fixture in evals/. Sibling spec example + visual eval fixture also updated in commits `f7f8430b2` and `ff62fe305`. Spec: `docs/specs/genui-css-channel.md`.
+
 ## [0.6.33] — 2026-05-23
 
 ### Fixed — card-ui body-slot drift closed across runtime + fixtures

package/css-channel.test.js

@@ -0,0 +1,506 @@
+/**
+ * A2UI CSS channel — unit fixtures.
+ *
+ * Spec: docs/specs/genui-css-channel.md §8.1
+ * Covers the 11 named fixtures asserting the renderer's updateStyles +
+ * removeStyles surface. happy-dom supports constructable stylesheets +
+ * adoptedStyleSheets natively; @scope semantics are not enforced by the
+ * DOM (the assertions check the wrapping behavior + adoption lifecycle,
+ * not the cascade-time effect of @scope itself — that's the smoke
+ * probe's job in §8.2).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { A2UIRenderer } from './renderer.js';
+
+let host;
+let renderer;
+const SURF = 'test-surface-1';
+
+beforeEach(() => {
+  host = document.createElement('div');
+  document.body.appendChild(host);
+  renderer = new A2UIRenderer(host);
+  renderer.process({ type: 'createSurface', surfaceId: SURF, root: 'root' });
+});
+
+afterEach(() => {
+  // Tear down — clears adoptedSheets from document
+  renderer.reset();
+  host.remove();
+  // Defensive — happy-dom shares adoptedStyleSheets across tests
+  document.adoptedStyleSheets = [];
+});
+
+// Helper — count this renderer's adopted sheets on the document
+function adoptedCount(rendererInstance, surfaceId) {
+  return rendererInstance.getStylesheets(surfaceId).size;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Fixture 1: applies-then-removes
+// ─────────────────────────────────────────────────────────────────────
+
+describe('CSS channel — applies-then-removes', () => {
+  it('updateStyles adds a sheet; removeStyles splices it', () => {
+    const before = document.adoptedStyleSheets.length;
+    renderer.process({
+      type: 'updateStyles',
+      surfaceId: SURF,
+      styleId: 's1',
+      css: `:scope { --a-accent: oklch(0.7 0.2 240); }`,
+    });
+    expect(adoptedCount(renderer, SURF)).toBe(1);
+    expect(document.adoptedStyleSheets.length).toBe(before + 1);
+
+    renderer.process({
+      type: 'removeStyles',
+      surfaceId: SURF,
+      styleId: 's1',
+    });
+    expect(adoptedCount(renderer, SURF)).toBe(0);
+    expect(document.adoptedStyleSheets.length).toBe(before);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Fixture 2: replaces-existing-styleid
+// ─────────────────────────────────────────────────────────────────────
+
+describe('CSS channel — replaces-existing-styleid', () => {
+  it('two updateStyles with same styleId keep only one sheet adopted', () => {
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'theme',
+      css: `:scope { --a-accent: red; }`,
+    });
+    const firstSheet = renderer.getStylesheets(SURF).get('theme').sheet;
+
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'theme',
+      css: `:scope { --a-accent: blue; }`,
+    });
+    const secondSheet = renderer.getStylesheets(SURF).get('theme').sheet;
+
+    expect(adoptedCount(renderer, SURF)).toBe(1);
+    expect(firstSheet).not.toBe(secondSheet);
+    expect(document.adoptedStyleSheets.includes(firstSheet)).toBe(false);
+    expect(document.adoptedStyleSheets.includes(secondSheet)).toBe(true);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Fixture 3: scoped-via-attribute
+// ─────────────────────────────────────────────────────────────────────
+
+describe('CSS channel — scoped-via-attribute', () => {
+  it('emitted CSS contains @scope wrapper anchored to the surface id', () => {
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'theme',
+      css: `card-ui { background: red; }`,
+    });
+    const entry = renderer.getStylesheets(SURF).get('theme');
+    const sheetText = Array.from(entry.sheet.cssRules).map(r => r.cssText).join('\n');
+    expect(sheetText).toMatch(/@scope\s*\(\[data-a2ui-surface\s*=\s*"test-surface-1"\]\)/);
+  });
+
+  it('sibling surfaces produce independent scope anchors', () => {
+    const SURF2 = 'test-surface-2';
+    renderer.process({ type: 'createSurface', surfaceId: SURF2, root: 'root' });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF,  styleId: 's', css: `.x { color: red; }`,
+    });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF2, styleId: 's', css: `.x { color: blue; }`,
+    });
+    const a = renderer.getStylesheets(SURF).get('s').sheet;
+    const b = renderer.getStylesheets(SURF2).get('s').sheet;
+    expect(a).not.toBe(b);
+    const aText = Array.from(a.cssRules).map(r => r.cssText).join('\n');
+    const bText = Array.from(b.cssRules).map(r => r.cssText).join('\n');
+    expect(aText).toContain('test-surface-1');
+    expect(aText).not.toContain('test-surface-2');
+    expect(bText).toContain('test-surface-2');
+    expect(bText).not.toContain('test-surface-1');
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Fixture 4: rejects-import
+// ─────────────────────────────────────────────────────────────────────
+
+describe('CSS channel — rejects forbidden constructs', () => {
+  it('rejects @import', () => {
+    let rejection = null;
+    host.addEventListener('styles-rejected', (e) => { rejection = e.detail; });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'bad',
+      css: `@import url('//example.com/x.css'); .x { color: red; }`,
+    });
+    expect(rejection).not.toBeNull();
+    expect(rejection.reason).toBe('forbidden-import');
+    expect(adoptedCount(renderer, SURF)).toBe(0);
+  });
+
+  it('rejects :root selectors', () => {
+    let rejection = null;
+    host.addEventListener('styles-rejected', (e) => { rejection = e.detail; });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'bad',
+      css: `:root { --a-accent: red; }`,
+    });
+    expect(rejection?.reason).toBe('forbidden-root-selector');
+    expect(adoptedCount(renderer, SURF)).toBe(0);
+  });
+
+  it('rejects bare body / html selectors', () => {
+    const detected = [];
+    host.addEventListener('styles-rejected', (e) => { detected.push(e.detail); });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'b1',
+      css: `body { background: black; }`,
+    });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'b2',
+      css: `html { font-size: 18px; }`,
+    });
+    expect(detected.length).toBe(2);
+    expect(detected[0].reason).toBe('forbidden-body-selector');
+    expect(detected[1].reason).toBe('forbidden-html-selector');
+  });
+
+  it('rejects @charset', () => {
+    let rejection = null;
+    host.addEventListener('styles-rejected', (e) => { rejection = e.detail; });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'bad',
+      css: `@charset "UTF-8"; .x { color: red; }`,
+    });
+    // @charset must be the first rule in CSS — if happy-dom strips it,
+    // the test may not see the rejection. Allow either: explicit reject
+    // OR sheet adopted with the @charset stripped (parser behavior).
+    if (rejection) {
+      expect(rejection.reason).toBe('forbidden-charset');
+    } else {
+      // happy-dom may quietly drop @charset; verify no @charset survives
+      const entry = renderer.getStylesheets(SURF).get('bad');
+      if (entry) {
+        const text = Array.from(entry.sheet.cssRules).map(r => r.cssText).join('');
+        expect(text).not.toMatch(/@charset/i);
+      }
+    }
+  });
+
+  it('rejects user-side @scope directives', () => {
+    let rejection = null;
+    host.addEventListener('styles-rejected', (e) => { rejection = e.detail; });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'bad',
+      css: `@scope (.x) { .y { color: red; } }`,
+    });
+    // happy-dom may not parse @scope; in that case the rule is dropped
+    // and the test should not assert rejection. Skip if no rejection
+    // emitted AND no rule reached the sheet.
+    if (rejection) {
+      expect(rejection.reason).toBe('forbidden-scope-directive');
+    }
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Fixture 5: rejects-external-url
+// ─────────────────────────────────────────────────────────────────────
+
+describe('CSS channel — external URL handling', () => {
+  it('rejects http: url() references', () => {
+    let rejection = null;
+    host.addEventListener('styles-rejected', (e) => { rejection = e.detail; });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'bad',
+      css: `.x { background-image: url(http://example.com/x.png); }`,
+    });
+    expect(rejection?.reason).toBe('external-url');
+  });
+
+  it('rejects https: url() references', () => {
+    let rejection = null;
+    host.addEventListener('styles-rejected', (e) => { rejection = e.detail; });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'bad',
+      css: `.x { background-image: url('https://example.com/x.png'); }`,
+    });
+    expect(rejection?.reason).toBe('external-url');
+  });
+
+  it('rejects protocol-relative // url() references', () => {
+    let rejection = null;
+    host.addEventListener('styles-rejected', (e) => { rejection = e.detail; });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'bad',
+      css: `.x { background-image: url(//cdn.example.com/x.png); }`,
+    });
+    expect(rejection?.reason).toBe('external-url');
+  });
+
+  it('allows data: url() references', () => {
+    let applied = null;
+    host.addEventListener('styles-applied', (e) => { applied = e.detail; });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'ok',
+      css: `.x { background-image: url(data:image/svg+xml;base64,PHN2Zy8+); }`,
+    });
+    expect(applied).not.toBeNull();
+    expect(applied.styleId).toBe('ok');
+    expect(adoptedCount(renderer, SURF)).toBe(1);
+  });
+
+  it('allows blob: url() references', () => {
+    let applied = null;
+    host.addEventListener('styles-applied', (e) => { applied = e.detail; });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'ok',
+      css: `.x { background-image: url(blob:abc-123); }`,
+    });
+    expect(applied).not.toBeNull();
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Fixture 6: rewrites-keyframes
+// ─────────────────────────────────────────────────────────────────────
+
+describe('CSS channel — animation-name rewriting', () => {
+  it('@keyframes pulse is namespaced with surface id prefix', () => {
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'anim',
+      css: `
+        @keyframes pulse { from { opacity: 1; } to { opacity: 0.5; } }
+        .x { animation: pulse 2s infinite; }
+      `,
+    });
+    const entry = renderer.getStylesheets(SURF).get('anim');
+    if (!entry) {
+      // happy-dom may not parse @keyframes — skip soft
+      return;
+    }
+    const sheetText = Array.from(entry.sheet.cssRules).map(r => r.cssText).join('\n');
+    // Surface id `test-surface-1` is sanitized to `test-surface-1` (no replacement needed)
+    expect(sheetText).toMatch(/@keyframes\s+test-surface-1_pulse/);
+    expect(sheetText).not.toMatch(/@keyframes\s+pulse\b/);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Fixture 7: cleanup-on-delete-surface
+// ─────────────────────────────────────────────────────────────────────
+
+describe('CSS channel — cleanup on deleteSurface', () => {
+  it('deleteSurface removes all adopted stylesheets for that surface', () => {
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 's1',
+      css: `:scope { --a-accent: red; }`,
+    });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 's2',
+      css: `:scope { --a-radius-md: 12px; }`,
+    });
+    const before = document.adoptedStyleSheets.length;
+    expect(adoptedCount(renderer, SURF)).toBe(2);
+
+    renderer.process({ type: 'deleteSurface', surfaceId: SURF });
+    expect(document.adoptedStyleSheets.length).toBe(before - 2);
+    // Surface itself is gone — getStylesheets returns an empty Map
+    expect(renderer.getStylesheets(SURF).size).toBe(0);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Fixture 8: parse-error-reported
+// ─────────────────────────────────────────────────────────────────────
+
+describe('CSS channel — parse-error reported', () => {
+  it('happy-dom is permissive — verify the channel does not adopt invalid trees', () => {
+    // happy-dom's CSS parser is forgiving and will accept many shapes.
+    // Behavior we DO guarantee: even when happy-dom accepts garbage CSS,
+    // the resulting sheet doesn't blow up the renderer.
+    const before = document.adoptedStyleSheets.length;
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'malformed',
+      css: `}}}{{ not real css at all`,
+    });
+    // Either rejected OR adopted-as-empty; both are acceptable.
+    // The hard requirement is no exception thrown + surface still healthy.
+    expect(renderer.getStylesheets(SURF).size).toBeLessThanOrEqual(1);
+    // Surface still works
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'recover',
+      css: `:scope { --a-accent: red; }`,
+    });
+    expect(renderer.getStylesheets(SURF).has('recover')).toBe(true);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Fixture 9: idempotent-remove
+// ─────────────────────────────────────────────────────────────────────
+
+describe('CSS channel — idempotent removeStyles', () => {
+  it('removeStyles for absent styleId is a silent no-op', () => {
+    const removed = [];
+    host.addEventListener('styles-removed', (e) => { removed.push(e.detail); });
+    renderer.process({
+      type: 'removeStyles', surfaceId: SURF, styleId: 'nonexistent',
+    });
+    expect(removed.length).toBe(0);
+  });
+
+  it('removeStyles for unknown surfaceId is a silent no-op', () => {
+    const removed = [];
+    host.addEventListener('styles-removed', (e) => { removed.push(e.detail); });
+    renderer.process({
+      type: 'removeStyles', surfaceId: 'no-such-surface', styleId: 'anything',
+    });
+    expect(removed.length).toBe(0);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Fixture 10: events-fire
+// ─────────────────────────────────────────────────────────────────────
+
+describe('CSS channel — lifecycle events fire with correct detail', () => {
+  it('styles-applied carries { surfaceId, styleId, ruleCount, validationWarnings }', () => {
+    let detail = null;
+    host.addEventListener('styles-applied', (e) => { detail = e.detail; });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'ok',
+      css: `.x { color: red; } .y { color: blue; }`,
+    });
+    expect(detail).not.toBeNull();
+    expect(detail.surfaceId).toBe(SURF);
+    expect(detail.styleId).toBe('ok');
+    expect(typeof detail.ruleCount).toBe('number');
+    expect(detail.ruleCount).toBeGreaterThan(0);
+    expect(Array.isArray(detail.validationWarnings)).toBe(true);
+  });
+
+  it('styles-removed carries { surfaceId, styleId }', () => {
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'r',
+      css: `.x { color: red; }`,
+    });
+    let detail = null;
+    host.addEventListener('styles-removed', (e) => { detail = e.detail; });
+    renderer.process({
+      type: 'removeStyles', surfaceId: SURF, styleId: 'r',
+    });
+    expect(detail).toEqual({ surfaceId: SURF, styleId: 'r' });
+  });
+
+  it('styles-rejected carries { surfaceId, styleId, reason }', () => {
+    let detail = null;
+    host.addEventListener('styles-rejected', (e) => { detail = e.detail; });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'bad',
+      css: `:root { color: red; }`,
+    });
+    expect(detail).not.toBeNull();
+    expect(detail.surfaceId).toBe(SURF);
+    expect(detail.styleId).toBe('bad');
+    expect(detail.reason).toBe('forbidden-root-selector');
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Fixture 11: surface preconditions (§4.7)
+// ─────────────────────────────────────────────────────────────────────
+
+describe('CSS channel — surface preconditions', () => {
+  it('updateStyles for unknown surfaceId is rejected with no-such-surface', () => {
+    let rejection = null;
+    // Listen on the renderer container (where the event is dispatched when
+    // no surface exists)
+    host.addEventListener('styles-rejected', (e) => { rejection = e.detail; });
+    renderer.process({
+      type: 'updateStyles',
+      surfaceId: 'no-such-surface',
+      styleId: 'x',
+      css: `.x { color: red; }`,
+    });
+    expect(rejection?.reason).toBe('no-such-surface');
+  });
+
+  it('updateStyles with non-string css is rejected with invalid-payload', () => {
+    let rejection = null;
+    host.addEventListener('styles-rejected', (e) => { rejection = e.detail; });
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'x',
+      css: { not: 'a string' },
+    });
+    expect(rejection?.reason).toMatch(/invalid-payload/);
+  });
+
+  it('prior valid sheet is preserved when a new sheet with the same styleId is rejected', () => {
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'theme',
+      css: `:scope { --a-accent: red; }`,
+    });
+    const valid = renderer.getStylesheets(SURF).get('theme').sheet;
+    expect(document.adoptedStyleSheets.includes(valid)).toBe(true);
+
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'theme',
+      css: `:root { color: red; }`, // forbidden
+    });
+
+    // Prior valid sheet still adopted
+    expect(renderer.getStylesheets(SURF).get('theme').sheet).toBe(valid);
+    expect(document.adoptedStyleSheets.includes(valid)).toBe(true);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Programmatic surface — getStylesheets accessor
+// ─────────────────────────────────────────────────────────────────────
+
+describe('CSS channel — getStylesheets accessor', () => {
+  it('returns empty Map for unknown surfaceId', () => {
+    const result = renderer.getStylesheets('no-such-surface');
+    expect(result).toBeInstanceOf(Map);
+    expect(result.size).toBe(0);
+  });
+
+  it('returns the surface adoptedSheets Map after updateStyles', () => {
+    renderer.process({
+      type: 'updateStyles', surfaceId: SURF, styleId: 'x',
+      css: `:scope { --a-accent: red; }`,
+    });
+    const m = renderer.getStylesheets(SURF);
+    expect(m.size).toBe(1);
+    expect(m.has('x')).toBe(true);
+    const entry = m.get('x');
+    expect(entry).toHaveProperty('sheet');
+    expect(entry).toHaveProperty('ruleCount');
+    expect(entry).toHaveProperty('appliedAt');
+    expect(typeof entry.appliedAt).toBe('number');
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Renderer reset() — should clean up adopted sheets across surfaces
+// ─────────────────────────────────────────────────────────────────────
+
+describe('CSS channel — renderer.reset() cleans up adopted sheets', () => {
+  it('reset removes adopted sheets from every surface', () => {
+    const SURF2 = 'surf-2';
+    renderer.process({ type: 'createSurface', surfaceId: SURF2, root: 'root' });
+    renderer.process({ type: 'updateStyles', surfaceId: SURF,  styleId: 'a', css: `.x { color: red; }` });
+    renderer.process({ type: 'updateStyles', surfaceId: SURF2, styleId: 'b', css: `.y { color: blue; }` });
+    const before = document.adoptedStyleSheets.length;
+    expect(before).toBeGreaterThanOrEqual(2);
+
+    renderer.reset();
+    expect(document.adoptedStyleSheets.length).toBe(before - 2);
+    expect(renderer.getStylesheets(SURF).size).toBe(0);
+    expect(renderer.getStylesheets(SURF2).size).toBe(0);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-runtime",
-  "version": "0.6.33",
+  "version": "0.6.34",
   "description": "A2UI runtime \u2014 renderer, registry, streams, surface manifest, and wiring primitives for the A2UI (Agent-to-UI) protocol. Framework-agnostic; pairs with any A2UI-conformant component set.",
   "type": "module",
   "exports": {

package/renderer.js

@@ -50,6 +50,8 @@ export class A2UIRenderer {
       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);
     }
@@ -99,6 +101,10 @@ export class A2UIRenderer {
       elements: new Map(),
       dataModel: {},
       bindings: new Map(),
+      // CSS channel (Phase 1): styleId -> { sheet, ruleCount, appliedAt }.
+      // Populated by #updateStyles; cleared by #removeStyles / #deleteSurface.
+      // See docs/specs/genui-css-channel.md §5.4.
+      adoptedSheets: new Map(),
     });
   }
 
@@ -116,8 +122,19 @@ export class A2UIRenderer {
         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
@@ -484,19 +501,291 @@ export class A2UIRenderer {
     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: 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();