feat(ui): harden Shadow DOM rollout foundation (YPE-5947)

[abharms]

Summary

Targets ype-5356-shadow-dom-rollout-plan, the branch from PR #423 that establishes the rollout policy this foundation implements.

• add an internal one-shot boundary ownership seam so SDK-owned composition reuses its parent shadow root while consumer-created nesting still creates an intentional nested root
• recover from constructable stylesheet creation, replacement, and adoption failures by falling back to a local <style> without losing rendered content
• prove a failed root does not poison later roots or documents, while recovered roots in the same document continue sharing one stylesheet
• document the patch-level resilience impact without expanding the current auth-only automatic-isolation rollout

Requirement evidence

Jira acceptance area	Evidence
Shared internal boundary foundation	ReuseShadowBoundary marks one SDK-owned child boundary for reuse and resets ownership before rendering consumer descendants.
SDK composition and consumer nesting	Focused unit coverage proves one owning boundary for SDK composition and a distinct nested root for consumer-created nesting.
Failure recovery	Focused tests independently force CSSStyleSheet construction, replaceSync, and adoptedStyleSheets assignment failures; content remains rendered and local fallback CSS is installed without throwing.
Cache and document recovery	Tests prove later roots recover, recovered roots in one document share the same sheet, and a later document adopts its own constructable sheet.
Existing contracts	The focused suite retains hydration, Strict Mode, refs, events, intentional nesting, lifecycle, fallback, and custom-property coverage; the full monorepo suite passes.
Browser behavior	Actual Safari validation passed 22/22 focused stories in fresh isolated sessions. Chromium, Firefox, and Playwright WebKit remain required PR CI evidence.
Release and rollout	The rollout policy records patch-level resilience only, and the UI package includes a patch changeset.

Review scope

Required outcomes:

• provide a shared internal boundary foundation without adding public configuration or automatically isolating more components
• ensure SDK-owned composition has one owning shadow boundary while consumer-created nesting remains intentional
• safely fall back when constructable stylesheet creation, replacement, or adoption throws
• ensure failures do not poison later roots or document-scoped stylesheet caching
• preserve the existing Shadow DOM contracts and rollout gates

Permitted support work:

• a narrowly scoped internal boundary-ownership seam
• focused unit regressions for composition, failure stages, recovery, and document scoping
• directly corresponding rollout-policy wording
• the required UI patch changeset

Non-goals:

• automatically moving additional components into Shadow DOM
• a public escape hatch, configuration API, registry, or rollout flag
• new component styling or unrelated refactors
• assistive-technology validation or claims
• changing the coordinated-major-release plan for component 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 --filter @youversion/platform-react-ui exec vitest run packages/ui/src/lib/shadow-root-host.test.tsx — 10/10 passed
• pnpm --filter @youversion/platform-react-ui typecheck — passed
• pnpm lint — passed
• pnpm build — passed
• pnpm test — passed: core 476 passed / 2 skipped, hooks 315 passed, UI 572 passed
• actual Safari smoke validation — 22/22 focused stories passed in fresh SafariDriver sessions
• git diff --check ype-5356-shadow-dom-rollout-plan...HEAD — passed

The local Vitest Storybook browser runner reached Storybook's uniform “No Preview” infrastructure state for all 24 stories, including untouched controls. The PR's authenticated Chromium, Firefox, and Playwright WebKit jobs are the authoritative browser matrix.

Compatibility and release notes

• Auth remains the only component currently receiving automatic Shadow DOM isolation.
• Public exports, component props, and configuration remain unchanged.
• This PR carries a UI patch changeset for resilience; rolling additional components into Shadow DOM remains a coordinated major-release change.
• This PR is stacked on docs(ui): define Shadow DOM rollout policy #423. After docs(ui): define Shadow DOM rollout policy #423 merges, this branch can be rebased and the PR retargeted without changing the YPE-5947 scope.

Jira

• YPE-5947

Confidence Score: 5/5

The PR appears safe to merge based on this review; no new issue was introduced since the previous review.

Summary

The PR adds an internal boundary-reuse seam and falls back to a local <style> when constructable stylesheet setup fails. It adds regression coverage for failure recovery, sheet sharing, and document isolation, plus rollout-policy wording and a patch changeset. There have been no changes since the previous review.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[New shadow root] --> B{Construct and adopt stylesheet}
  B -->|Succeeds| C[Use document-scoped sheet]
  B -->|Fails or unsupported| D[Render with local style fallback]

Loading

_{Reviews (3) · Last reviewed commit: "test(ui): assert document-scoped shadow ..."}

[changeset-bot]

🦋 Changeset detected

Latest commit: b34f08f

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

This PR includes changesets to release 4 packages

Name	Type
@youversion/platform-react-ui	Patch
vite-react	Patch
@youversion/platform-core	Patch
@youversion/platform-react-hooks	Patch

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-25T19:14:13.975795Z	b34f08f	New commits

ℹ️ 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.