feat(ui): prototype automatic Shadow DOM style isolation

[cameronapak]

Same-repo copy of #322 so CI can read YVP_API_HOST / YVP_APP_KEY. The fork PR cannot see those secrets.

Code Implementor, sent on behalf of Cam. I am AI.

Note

This is an architectural proof of concept on one representative component, not a package-wide rollout. YPE-4113 is intentionally partial.

Summary

Host applications can apply global CSS to React SDK component internals. This PR prototypes automatic Shadow DOM isolation on YouVersionAuthButton. Consumers keep rendering the component normally, with no wrapper or opt-in.

See #322 for Austin's original write-up, ADR 0005, and the Hostile CSS demo.

HEAD: f735fcb (same as #322).

Greptile Summary

This proof of concept automatically renders YouVersionAuthButton within a Shadow DOM boundary while preserving its existing component API.

• Adds a reusable shadow host and higher-order isolation wrapper with per-document constructable stylesheet caching and a <style> fallback.
• Updates the auth button’s typography and stories for the new shadow-tree structure.
• Adds Strict Mode, hostile-CSS, pseudo-element, and same-origin iframe coverage.
• Adds an interactive hostile-CSS demonstration and an ADR documenting compatibility impacts and deferred work.

Confidence Score: 5/5

The proof of concept appears safe to merge with its intentionally limited scope and documented compatibility tradeoffs.

No concrete, unacknowledged blocking failure remains after accounting for the provider’s existing document-level font loading and the ADR’s explicit treatment of form association, SSR, hydration, and delayed refs.

Important Files Changed

Filename	Overview
packages/ui/src/lib/shadow-root-host.tsx	Introduces effect-driven shadow-root creation, per-document stylesheet adoption, fallback style injection, and portal rendering.
packages/ui/src/lib/shadow-isolation.tsx	Adds a typed forward-ref wrapper that transparently places a component inside ShadowRootHost.
packages/ui/src/components/YouVersionAuthButton.tsx	Wraps the public auth button with automatic shadow isolation and explicitly applies its sans-serif utility.
packages/ui/src/styles/global.css	Adds shadow-context rules that suppress host pseudo-elements around isolated components.
packages/ui/src/lib/shadow-root-host.test.tsx	Covers Strict Mode attachment, the host reset, and fallback stylesheet resource identity.
packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx	Adds browser-level hostile-CSS and same-origin iframe coverage for the prototype.
docs/adr/0005-prototype-shadow-dom-style-isolation.md	Documents the architecture, breaking DOM and lifecycle effects, current evidence, and intentionally deferred limitations.

Flowchart

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

Loading

_{Reviews (1): Last reviewed commit: "fix(ui): use style precedence for shadow..." | Re-trigger Greptile}

Context used:

• Knowledge Base — packages/ui

[changeset-bot]

🦋 Changeset detected

Latest commit: f735fcb

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