docs(si): A2UI integration guidance (draft, needs WG review) — closes #2918 #2919 #2920

[bokelley]

Summary

Consolidates three open A2UI integration issues into a single new page at docs/sponsored-intelligence/a2ui.mdx:

• A2UI Rendering Guidance: Document disclosure/chrome separation #2919 — Host/brand boundary. Names the structural invariant: the SI agent's A2UI surface renders inside a host-controlled container; sponsorship/governance/regulatory disclosures live in host chrome outside that container; brand cannot suppress, restyle, or impersonate them. Includes compliant and non-compliant example surfaces.
• A2UI Theming: Plumb brand.json palette into A2UI surface at session init #2918 — Brand theming. Resolution flow from brand.json palette/typography → A2UI theme tokens, with the host as resolver (because the host owns its component catalog and a11y floors). Explicit table mapping brand.json fields to typical theme roles.
• Document A2UI user-action to SI session event mapping #2920 — User-action measurement. A2UI user-action flow (host → SI agent for turn-driving, host → AdCP for engagement counting), proposed mapping table, "who fires what" table.

Why this is a draft

The page is marked **Draft — pending working-group review** at the top. Two pieces specifically need human eyes before this becomes normative:

1. The four invariants in Host/Brand Boundary. They use MUST language and read as protocol-level requirements. If we accept them, the next step is promoting the substance to specification.mdx (with normative section numbers) and possibly adding renderer-side guidance to implementing-si-hosts.mdx. Right now they live as integration guidance, which is the safer landing zone.
2. Regulatory framing (FTC §255.5, EU DSA Art. 26, AVMS). The citations are starting points and explicitly flagged for legal review in an inline <Note>. Counsel should confirm the wording before any of this is read as legal guidance.

The action-name vocabulary question (standardize cross-host vs leave brand-defined) is also flagged inline as an open question on #2920.

What this PR does NOT change

• No schema changes. a2ui/*.json and sponsored-intelligence/*.json are untouched.
• No changes to specification.mdx. If WG accepts the structural invariant, that's a follow-up.
• No changes to host or agent implementation guides. Those should reference this page once the boundary is settled.

Files

• docs/sponsored-intelligence/a2ui.mdx (new)
• docs.json (sidebar registration in two locations — current + versioned 3.0.0 trees)
• .changeset/a2ui-integration-guidance.md (empty changeset; docs-only)

Test plan

• npm run docs:dev renders the page without broken links
• Sidebar registration places the page under "SI Chat Protocol" group
• @pkras review (filed all three issues)
• WG review of the four boundary invariants — accept as guidance, promote to spec, or revise
• Legal review of FTC/EU/AVMS framing before any normative promotion

cc @pkras

🤖 Generated with Claude Code

[bokelley]

Expert review pass — what changed

Ran the draft through ad-tech-protocol-expert, adtech-product-expert, docs-expert, and security-reviewer in parallel. Results below, with a high-confidence revision pushed in 254fbc1.

Protocol expert (sound-with-caveats)

• Structural invariant matches IAB SafeFrame, OMID, TCF precedent. Added two more parallels they suggested: IAB AdChoices (host-rendered icon, advertiser cannot suppress) and Apple ATT (system-owned prompt). ✅ landed
• Flagged loose wording in the four MUSTs (especially "opaque", "contradict", "sanitize"). Tightened all three. ✅ landed
• Schema-level enforcement is weaker than prose — surface.json, component.json, user-action.json all use additionalProperties: true. Filed as a follow-up in the page (schema tightening) rather than blocking this PR. 📋 follow-up
• Confirmed user-action measurement division is right (host fires both); SI agent should never be authoritative about an event firing. ✅ unchanged

Product expert (mixed — adoption gaps)

• Brand attribution vs disclosure is distinct and needed an explicit talk-track for brand managers. Added a "Brand attribution vs. disclosure" subsection naming Google Shopping / Amazon Sponsored Products / Apple Search Ads as the brand-side precedent (templated formats brands accept because they convert). ✅ landed
• Theme substitution needed a deterministic algorithm (not host discretion) so brands can predict outcomes — also need to expose resolved theme back to brand for QA. ✅ landed
• event_id correlation between turn-driving signal (to SI agent) and engagement signal (to AdCP measurement) was missing — without it, attribution reconciliation is guesswork. Added as a MUST in the user-action section. ✅ landed
• Drop telemetry — when host drops a brand component, brand needs to know for debugging. Added a "Drop telemetry" subsection (proposed shape, exact schema in follow-ups). ✅ landed
• Action-name vocabulary needs a small standard set with x- prefix for cross-host portability. 📋 follow-up

Docs expert (close to landing)

• Header disclaimer was too heavy and duplicated a later Note. Trimmed to two short Notes (experimental status + draft/legal-review). ✅ landed
• "Deprecated ui_elements" pre-empted a WG decision and contradicted live specification.mdx. Softened to "alternative to". ✅ landed
• "SI Chat Protocol" sidebar group was wrong — A2UI's reach (theming, measurement) is broader than chat handoffs. Moved under "Concepts". ✅ landed in both versioned + current trees in docs.json
• Added an experimental-status declaration matching overview.mdx and specification.mdx. ✅ landed
• Added a negotiated_capabilities.a2ui response example. ✅ landed
• Cross-link follow-ups (specification.mdx + implementing-si-* should reference this page) — separate PR once boundary settles. 📋 follow-up

Security reviewer (the big one — many real bypass vectors)

The four MUSTs covered the obvious case (text impersonation inside the container) but missed several attack surfaces. Added ten additional invariants organized into four buckets — Container, Content, Theme, Action, Operational. Highlights:

• Image disclosure-impersonation — bitmap with "Sponsored" text, fake close-X, OS notification graphics. Added invariant 5 requiring containment + perceptual-hash detection + alt-text isolation from screen-reader chrome.
• URL-shape attack vectors — bound-value.path is unscoped JSON Pointer over arbitrary dataModel; literal or path-bound URLs both need https-only canonicalization. Added invariant 6 with rel="noopener noreferrer" + rel="sponsored" requirements. Folded IntegrationAction and AppHandoff into a dedicated section with deep-link allowlist + confirmation step.
• HTML-injection via Text components and dataModel round-trip — added invariant 7: Text rendered as text never HTML; round-trips through user-action.context cannot enable script execution.
• LLM prompt injection via action.name and surface text — SI agents are LLM-backed and the next-turn prompt almost certainly includes action.name + context verbatim. Added invariant 10 (action-name syntax ^[a-z][a-z0-9_]{0,63}$) and 11 (fence brand-controlled bytes with delimiters when echoed into LLM contexts).
• Theme tokens unbounded — invariant 8: tokens are typed/atomic/enumerated, never raw CSS, geometric properties never themeable.
• WCAG-substitution suppression vector — invariant 9: substitution algorithm is deterministic on host-controlled tokens only; brand-influenced fallback rejected.
• Multi-tenant isolation — invariant 12: surfaceId/componentId/dataModel are host-namespaced per session per brand.
• Render budget DoS — invariant 13: hosts cap component count, tree depth, dataModel size, render time.
• Host validates against catalog schema before render — invariant 14: host is sole arbiter, agent's claim of conformance is not load-bearing.

All the above landed in 254fbc1.

Ready for @pkras review

@pkras you opened all three issues (#2918, #2919, #2920); review request is on this PR. The structural-invariant section is now substantially expanded — would value your read on whether the 14 MUSTs are at the right altitude for guidance vs. spec, and whether the brand-attribution clarifier reads cleanly to a host implementer.

cc working-group reviewers — flagged needs-wg-review.