feat(ui): Guarantee consuming-app global CSS can't distort Bible components - Shadow DOM

[cameronapak]

This PR is in progress and will continue to be defined. This PR was created as a feature branch for https://lifechurch.atlassian.net/browse/YPE-4113.

Greptile Summary

The PR prototypes automatic Shadow DOM style isolation for YouVersionAuthButton and documents the resulting compatibility boundaries.

• Adds a reusable shadow-root host with constructable-stylesheet and fallback style delivery.
• Wraps the authentication button while preserving its public React props and forwarded ref.
• Adds hostile-CSS demonstrations, browser stories, lifecycle tests, an ADR, and a coordinated major changeset.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains within the eligible follow-up-review scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/ui/src/lib/shadow-root-host.tsx	Adds the shadow-root lifecycle, per-document constructed stylesheet cache, fallback style resource, host reset, and React portal.
packages/ui/src/lib/shadow-isolation.tsx	Adds a typed higher-order wrapper that preserves component props and forwarded refs while introducing the isolation host.
packages/ui/src/components/YouVersionAuthButton.tsx	Moves the existing authentication-button implementation behind automatic Shadow DOM isolation and pins its intended font utility.
packages/ui/src/styles/global.css	Adds shadow-host pseudo-element suppression to the generated SDK stylesheet.
packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx	Adds browser coverage for hostile global selectors, host pseudo-elements, and same-origin iframe stylesheet adoption.
packages/ui/src/lib/shadow-root-host.test.tsx	Adds focused unit coverage for Strict Mode attachment, host resets, and fallback stylesheet identity.
docs/adr/0005-prototype-shadow-dom-style-isolation.md	Documents the prototype architecture, compatibility impact, verified behavior, and deliberately deferred concerns.
.changeset/prototype-shadow-dom-isolation.md	Records the prototype as a coordinated major release across the fixed-version SDK packages.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Consumer[Consumer application] --> Host[Light-DOM shadow host]
  Host --> Root[Open shadow root]
  Styles[Embedded SDK stylesheet] --> Root
  Root --> Portal[React portal]
  Portal --> Button[YouVersionAuthButton implementation]
  HostCSS[Consumer global CSS] -. selector boundary .-> Host

Loading

_{Reviews (3): Last reviewed commit: "Merge branch 'main' into journey-to-the-..." | Re-trigger Greptile}

Context used (3)

• Knowledge Base — UI provider and styling system
• Knowledge Base — Package delivery workflows
• Knowledge Base — Vite React integration example

[changeset-bot]

🦋 Changeset detected

Latest commit: 0222ae9

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-core	Major
@youversion/platform-react-hooks	Major
@youversion/platform-react-ui	Major
vite-react	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