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.

[bokelley]

@pkras — checking in. This consolidates #2918 / #2919 / #2920 into a single page (docs/sponsored-intelligence/a2ui.mdx) and uses MUST language on four host/brand boundary invariants.

WG decision needed before this moves forward:

1. Accept the four invariants as integration guidance (lands as-is)
2. Promote the substance to specification.mdx with normative section numbers
3. Revise

Legal review of the FTC §255.5 / EU DSA Art. 26 / AVMS framing is gated on WG accept — citations are explicitly flagged for counsel review inline.

Could use your eyes when you have a window.

[pkras]

This is a tricky one, my quick take is that container invariants should be promoted to 3.1 spec and theming and actions should stay as guidance.

Container invariants are worth promoting because they define a fundamental trust boundary that every SI host needs to enforce consistently. Get this wrong and you have a security and disclosure problem across every surface SI runs on, which is much harder to fix retroactively than if you'd committed early.

Theming and action-mapping are a different story. The theming split feels right conceptually but nobody has shipped against it yet, and the action vocabulary question is genuinely unresolved, so locking either into spec before there's implementation feedback is how you end up with a normative section you immediately want to revise. Better to keep those as versioned guidance, name someone to bring them back for 3.2 scoping with real-world evidence, and avoid overcommitting on the parts that are still evolving.

Legal review is needed regardless - particularly on the container invariants given the disclosure requirements (FTC, DSA, AVMS). Happy to share with the WG for further input before this moves forward.

[bokelley]

Triage read: there is useful material here, but I would not merge this PR as-is.

What seems worth salvaging:

• Promote/spec-track: the host/container trust-boundary invariants. The core point is that disclosure/governance chrome is host-owned and outside the brand A2UI container; the renderer must enforce containment, prevent disclosure/chrome impersonation, and stay authoritative over what renders.
• Keep as guidance: brand.json -> A2UI theme resolution, accessibility floors, resolved-theme feedback to the brand agent, and host-controlled substitution.
• Keep as guidance/backlog: user-action measurement mapping, shared event_id, drop telemetry, action-name vocabulary, schema tightening, and dataModel.theme shape.
• Do not land unreviewed: legal/regulatory framing and broad MUST language outside the container boundary. That should go through WG/legal before it becomes normative.

This lines up with @pkras's comment: container invariants are likely 3.1-spec material; theming and action mapping should remain versioned guidance until there is implementation feedback.

Recommended next step: split this. One focused PR for the host/container trust boundary, and a second docs PR for A2UI theming/action guidance with softer language and explicit open questions.

[bokelley]

Aligned with both reads. Two concrete edits to scope this PR to the trust boundary before the split:

1. Remove "Why this matters" — the FTC §255.5 / EU DSA / AVMS citations are the clearest piece of regulatory framing that shouldn't land without WG/legal review. The structural rationale (host-only disclosure means once-per-host legal review) can come back post-sign-off or be dropped entirely.
2. Narrow the Closes scope — change to Closes #2919, Refs #2918, Refs #2920 so the theming and user-action issues remain open as trackers for the guidance PR.

One scoping question worth settling before the branch narrows: @pkras's "container invariants" maps clearly to invariants 1–4. Invariants 5–7 (image impersonation, URL canonicalization, text/HTML injection) read as boundary-enforcement too, so likely belong in the spec-track PR. But 8–14 (theme tokens, WCAG substitution, action naming, LLM fencing, multi-tenant isolation, render budget, catalog validation) are less clear — the security reviewer flagged real vectors there, but they may be guidance-shaped even with MUST language. Worth a quick WG thread to confirm which bucket before the branch narrows.

Once #2918 and #2920 are re-opened, /triage execute on either one will produce the guidance PR with softer language and the open questions surfaced explicitly.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01NWDpGt6R9A25zjfPVr78mR

---

Generated by Claude Code