docs(ui): define Shadow DOM rollout policy

[abharms]

Summary

• define the complete public UI boundary for the coordinated Shadow DOM major release
• reconcile the merged research and browser evidence from YPE-5354, YPE-5355, YPE-5400, YPE-5436, YPE-5437, and YPE-5946/PR 420
• sequence YPE-5947 through YPE-5952 with reusable package gates, component-specific validation, and a single coordinated release gate
• distinguish the current integration-branch prototype from planned package-wide behavior and document the consumer-breaking contract

This PR changes planning and compatibility documentation only. It does not expand runtime isolation: YouVersionAuthButton remains the only component automatically isolated on the integration branch.

Requirement evidence

Jira acceptance area	Evidence
Complete public boundary	docs/shadow-dom-rollout-policy.md inventories every public React UI export, identifies included roots and compound members, and gives a concrete reason for each exclusion.
Research reconciliation	The policy and evidence inventory incorporate the findings from YPE-5354, YPE-5355, YPE-5400, YPE-5436, YPE-5437, and the 22-story cross-browser/Safari evidence merged in PR 420.
Limitation decisions	Every known limitation is classified as Accepted, Follow-up, or Blocker; stylesheet fallback recovery is the shared implementation blocker and real assistive-technology validation remains an explicit follow-up.
Implementation order	YPE-5947 establishes the shared host, then YPE-5948 through YPE-5951 validate component groups, and YPE-5952 owns the coordinated major release.
Package and component gates	The policy separates reusable Chromium/Firefox/WebKit/Safari, styling, lifecycle, accessibility, and release evidence from validation that must be repeated for each component group.
Consumer contract	Release guidance covers DOM rendering and queries, refs, events, forms, accessible relationships, automation, styling/customization, and breaking-release framing.
Planned versus implemented	ADR 0007, the evidence inventory, and the policy consistently identify package-wide isolation as planned; no feature flag or phased stable rollout is introduced.

Review scope

Required outcomes:

• satisfy all ten YPE-5356 documentary acceptance criteria
• make the rollout implementation-ready through a dependency-ordered ticket sequence
• preserve PR 420's final evidence: 22 focused stories across Chromium, Firefox, Playwright WebKit, and isolated SafariDriver sessions
• keep the current integration-branch runtime unchanged

Permitted support work:

• reconcile the ADR, consumer compatibility contract, and validation inventory
• clarify the existing YPE-5947 through YPE-5952 follow-up tickets
• add the required empty changeset

Non-goals:

• runtime isolation changes
• feature flags or phased-release infrastructure
• repeating completed research
• claiming real assistive-technology validation
• publishing or merging the coordinated rollout

Please treat a finding as blocking only when it identifies an unmet in-scope requirement, a documented repository-standard violation in added or modified code, or a concrete regression or defect caused or worsened by this diff. Label other valid improvements as non-blocking follow-ups.

Verification

• pnpm lint — passed
• pnpm typecheck — passed, including UI build, public-entry/export checks, and style verification
• pnpm test — passed: core 476 passed / 2 skipped, hooks 315 passed, UI 568 passed
• pnpm exec prettier --check <changed Markdown files> — passed
• git diff --check — passed
• independent Standards, Spec, and Compatibility review of the final pinned snapshot — no findings

Compatibility and release notes

• The rollout is intentionally one coordinated major release, not a partial stable rollout.
• Single-active-peer popover dismissal is accepted; simultaneous peer popovers are not promised.
• Native outer-form participation and cross-tree label/ARIA ID references remain unsupported; Textarea is excluded from automatic isolation.
• Playwright WebKit remains the recurring CI browser. SafariDriver validation repeats before the release candidate and after relevant shared-infrastructure changes.
• VoiceOver, NVDA, and other real assistive-technology results must not be claimed until separately validated.

Jira

YPE-5356 — Prepare the package-wide Shadow DOM rollout

Confidence Score: 5/5

The documentation-only PR appears safe to merge, with no unmet acceptance criterion, repository-rule violation, or concrete regression identified.

Summary

The PR defines the documentation-only policy for a coordinated major-version Shadow DOM rollout while preserving the current YouVersionAuthButton-only runtime behavior.

• Inventories the complete public UI boundary with reasons for included, transitive, and excluded exports.
• Reconciles browser, SSR, styling, overlay, accessibility, and consumer-compatibility evidence.
• Establishes dependency-ordered implementation groups, reusable validation gates, and one coordinated release gate.
• Adds the required empty changeset for this no-release documentation change.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    F[YPE-5947 Shared boundary foundation] --> L[YPE-5948 Leaf and standalone components]
    F --> P[YPE-5949 Compound pickers]
    P --> S[YPE-5950 Scripture presentation]
    L --> R[YPE-5951 Bible reader]
    P --> R
    S --> R
    R --> G[YPE-5952 Coordinated major release]
    G --> D[Consumer documentation and release notes]

Loading

_{Reviews (1) · Last reviewed commit: "docs(ui): correct rollout compatibility ..."}

[changeset-bot]

🦋 Changeset detected

Latest commit: f531cbb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-25T01:57:07.798776Z	f531cbb	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.