From cf19f9b8c175743e214719bcbaeb9839e3591cf5 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Thu, 24 Sep 2026 21:43:35 -0500
Subject: [PATCH 1/4] feat(ui): harden shadow boundary foundation

Refs: YPE-5947
---
 .changeset/safe-shadows-fallback.md           |   5 +
 docs/shadow-dom-rollout-policy.md             |   8 +-
 packages/ui/src/lib/shadow-isolation.tsx      |  21 ++
 packages/ui/src/lib/shadow-root-host.test.tsx | 345 +++++++++++++++++-
 packages/ui/src/lib/shadow-root-host.tsx      |  15 +-
 5 files changed, 388 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/safe-shadows-fallback.md

diff --git a/.changeset/safe-shadows-fallback.md b/.changeset/safe-shadows-fallback.md
new file mode 100644
index 00000000..dee4ef12
--- /dev/null
+++ b/.changeset/safe-shadows-fallback.md
@@ -0,0 +1,5 @@
+---
+'@youversion/platform-react-ui': patch
+---
+
+Keep isolated UI content rendered with local styles when constructable stylesheet setup fails.
diff --git a/docs/shadow-dom-rollout-policy.md b/docs/shadow-dom-rollout-policy.md
index e24b2819..807aef1a 100644
--- a/docs/shadow-dom-rollout-policy.md
+++ b/docs/shadow-dom-rollout-policy.md
@@ -97,7 +97,7 @@ supported component contract.
 | Open roots are inspectable and mutable by same-page JavaScript | Accepted | Isolation is not a security boundary. |
 | Opening a peer popover dismisses the current peer across component roots | Accepted | Keep the single-active-peer behavior. Supporting concurrent peer popovers would require a demonstrated product journey and separate design. |
 | Nested-dialog and rapid-reopen final focus restoration | Accepted | Preserve the behavior resolved by YPE-5889/PR 414 as regression coverage rather than duplicating the implementation in rollout tickets. |
-| Stylesheet construction or adoption can throw | Blocker | The foundation ticket must prove recovery to the local `<style>` path without losing component rendering. |
+| Stylesheet construction or adoption can throw | Resolved by YPE-5947 | Construction, replacement, and adoption failures recover to the local `<style>` path without losing component rendering; later roots can still use the per-document constructable sheet. |
 | Playwright WebKit is not actual Safari | Follow-up | Repeat SafariDriver validation before the coordinated release candidate and after changes to the host, stylesheet installation, portal controller, or focus controller. |
 | Real screen-reader behavior is unverified | Follow-up | Keep real assistive-technology validation deferred and do not claim VoiceOver, NVDA, or other assistive-technology validation in release notes. |
 
@@ -135,6 +135,12 @@ exported function. Each ticket links to YPE-5356 and this policy.
    - Land all included groups, complete the package and component gates, update
      consumer documentation, and publish the behavior as one major release.
 
+YPE-5947 adds no public Shadow DOM configuration and does not expand the current
+automatic boundary beyond `YouVersionAuthButton`. Its independently releasable
+runtime effect is a patch-level resilience fix for stylesheet installation; the
+additional automatic component boundaries remain part of the coordinated major
+release.
+
 Excluded components are not hidden work in these groups. `Textarea` needs a
 separately approved form contract, and standalone `VerseActionPopover` needs an
 anchor contract that does not cross tree scopes before either can join a future
diff --git a/packages/ui/src/lib/shadow-isolation.tsx b/packages/ui/src/lib/shadow-isolation.tsx
index 8c1492fb..b1771214 100644
--- a/packages/ui/src/lib/shadow-isolation.tsx
+++ b/packages/ui/src/lib/shadow-isolation.tsx
@@ -1,23 +1,44 @@
 import {
+  createContext,
   createElement,
   forwardRef,
+  useContext,
   type ForwardRefExoticComponent,
   type PropsWithoutRef,
+  type ReactNode,
   type RefAttributes,
 } from 'react';
 import { ShadowRootHost } from './shadow-root-host';
 
+const ShadowBoundaryReuseContext = createContext(false);
+
+/** @internal Marks SDK-owned composition that must reuse an existing automatic boundary. */
+export function ReuseShadowBoundary({ children }: { children: ReactNode }): ReactNode {
+  return (
+    <ShadowBoundaryReuseContext.Provider value>{children}</ShadowBoundaryReuseContext.Provider>
+  );
+}
+
 /** @internal Applies automatic isolation while preserving the component ref. */
 export function withShadowIsolation<P extends object, T>(
   Implementation: ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>>,
   displayName: string,
 ): ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>> {
   const Isolated = forwardRef<T, P>((props, ref) => {
+    const reuseBoundary = useContext(ShadowBoundaryReuseContext);
     const implementationProps: PropsWithoutRef<P> & RefAttributes<T> = {
       ...props,
       ref,
     };
 
+    if (reuseBoundary) {
+      return (
+        <ShadowBoundaryReuseContext.Provider value={false}>
+          {createElement(Implementation, implementationProps)}
+        </ShadowBoundaryReuseContext.Provider>
+      );
+    }
+
     return (
       <ShadowRootHost>{createElement(Implementation, implementationProps)}</ShadowRootHost>
     );
diff --git a/packages/ui/src/lib/shadow-root-host.test.tsx b/packages/ui/src/lib/shadow-root-host.test.tsx
index d53331b6..84172d69 100644
--- a/packages/ui/src/lib/shadow-root-host.test.tsx
+++ b/packages/ui/src/lib/shadow-root-host.test.tsx
@@ -1,9 +1,16 @@
-import { createRef, forwardRef, StrictMode, useLayoutEffect, useState } from 'react';
+import {
+  createRef,
+  forwardRef,
+  StrictMode,
+  useLayoutEffect,
+  useState,
+  type ReactNode,
+} from 'react';
 import { hydrateRoot, type Root } from 'react-dom/client';
 import { renderToString } from 'react-dom/server';
 import { act, render, waitFor } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
-import { withShadowIsolation } from './shadow-isolation';
+import { ReuseShadowBoundary, withShadowIsolation } from './shadow-isolation';
 import { ShadowRootHost, useShadowPortalTarget } from './shadow-root-host';
 
 function PortalRequester(): React.ReactNode {
@@ -25,7 +32,47 @@ const IsolatedRefProbe = withShadowIsolation(
   'IsolatedRefProbe',
 );
 
+interface CompositionProbeProps {
+  children?: ReactNode;
+  label: string;
+}
+
+const IsolatedCompositionProbe = withShadowIsolation(
+  forwardRef<HTMLDivElement, CompositionProbeProps>(({ children, label }, ref) => (
+    <div ref={ref} data-testid={label}>
+      {children}
+    </div>
+  )),
+  'IsolatedCompositionProbe',
+);
+
 describe('ShadowRootHost', () => {
+  it('reuses the owning boundary for SDK composition without flattening consumer-created nesting', async () => {
+    const { container } = render(
+      <IsolatedCompositionProbe label="owner">
+        <ReuseShadowBoundary>
+          <IsolatedCompositionProbe label="sdk-owned child">
+            <IsolatedCompositionProbe label="consumer child" />
+          </IsolatedCompositionProbe>
+        </ReuseShadowBoundary>
+      </IsolatedCompositionProbe>,
+    );
+
+    const outerHost = await waitFor(() => {
+      const host = container.querySelector<HTMLElement>('[data-yv-shadow-host]');
+      if (!host?.shadowRoot) throw new Error('outer shadow root not attached');
+      return host;
+    });
+    const outerRoot = outerHost.shadowRoot!;
+    const sdkOwnedChild = outerRoot.querySelector('[data-testid="sdk-owned child"]');
+    const consumerHost = outerRoot.querySelector<HTMLElement>('[data-yv-shadow-host]');
+
+    expect(container.querySelectorAll('[data-yv-shadow-host]')).toHaveLength(1);
+    expect(sdkOwnedChild?.getRootNode()).toBe(outerRoot);
+    expect(outerRoot.querySelectorAll('[data-yv-shadow-host]')).toHaveLength(1);
+    expect(consumerHost?.shadowRoot?.querySelector('[data-testid="consumer child"]')).not.toBeNull();
+  });
+
   it('reuses the empty server host before making the forwarded ref available after shadow mount', async () => {
     const buttonRef = createRef<HTMLButtonElement>();
     const refsDuringInitialClientRender: Array<HTMLButtonElement | null> = [];
@@ -148,6 +195,300 @@ describe('ShadowRootHost', () => {
     expect(style?.getAttribute('data-precedence')).toBe('yv-sdk');
   });
 
+  it('recovers from stylesheet construction failure without poisoning later roots', async () => {
+    const styleSheetDescriptor = Object.getOwnPropertyDescriptor(window, 'CSSStyleSheet');
+    const adoptedStyleSheetsDescriptor = Object.getOwnPropertyDescriptor(
+      ShadowRoot.prototype,
+      'adoptedStyleSheets',
+    );
+    const adoptedStyleSheets = new WeakMap<ShadowRoot, CSSStyleSheet[]>();
+    let failedView: ReturnType<typeof render> | undefined;
+    let recoveredView: ReturnType<typeof render> | undefined;
+
+    try {
+      Object.defineProperty(ShadowRoot.prototype, 'adoptedStyleSheets', {
+        configurable: true,
+        get(this: ShadowRoot): CSSStyleSheet[] {
+          return adoptedStyleSheets.get(this) ?? [];
+        },
+        set(this: ShadowRoot, sheets: CSSStyleSheet[]) {
+          adoptedStyleSheets.set(this, sheets);
+        },
+      });
+      Object.defineProperty(window, 'CSSStyleSheet', {
+        configurable: true,
+        value: class ThrowingStyleSheet {
+          constructor() {
+            throw new Error('construction failed');
+          }
+
+          replaceSync(): void {}
+        },
+      });
+
+      expect(() => {
+        failedView = render(
+          <ShadowRootHost>
+            <span data-testid="fallback-content">Fallback content</span>
+          </ShadowRootHost>,
+        );
+      }).not.toThrow();
+
+      const failedRoot = await waitFor(() => {
+        const root = failedView?.container.querySelector<HTMLElement>('[data-yv-shadow-host]')
+          ?.shadowRoot;
+        if (!root?.querySelector('[data-testid="fallback-content"]')) {
+          throw new Error('fallback content not rendered');
+        }
+        return root;
+      });
+      expect(failedRoot.querySelector('style[data-href="yv-sdk-shadow-styles"]')).not.toBeNull();
+
+      Object.defineProperty(window, 'CSSStyleSheet', {
+        configurable: true,
+        value: class WorkingStyleSheet {
+          replaceSync(): void {}
+        },
+      });
+      recoveredView = render(
+        <ShadowRootHost>
+          <span data-testid="constructed-content">Constructed content</span>
+        </ShadowRootHost>,
+      );
+
+      const recoveredRoot = await waitFor(() => {
+        const root = recoveredView?.container.querySelector<HTMLElement>('[data-yv-shadow-host]')
+          ?.shadowRoot;
+        if (!root?.querySelector('[data-testid="constructed-content"]')) {
+          throw new Error('constructed content not rendered');
+        }
+        return root;
+      });
+      expect(recoveredRoot.adoptedStyleSheets).toHaveLength(1);
+      expect(recoveredRoot.querySelector('style')).toBeNull();
+    } finally {
+      failedView?.unmount();
+      recoveredView?.unmount();
+      if (styleSheetDescriptor) {
+        Object.defineProperty(window, 'CSSStyleSheet', styleSheetDescriptor);
+      } else {
+        Reflect.deleteProperty(window, 'CSSStyleSheet');
+      }
+      if (adoptedStyleSheetsDescriptor) {
+        Object.defineProperty(
+          ShadowRoot.prototype,
+          'adoptedStyleSheets',
+          adoptedStyleSheetsDescriptor,
+        );
+      } else {
+        Reflect.deleteProperty(ShadowRoot.prototype, 'adoptedStyleSheets');
+      }
+    }
+  });
+
+  it('recovers from stylesheet replacement failure without poisoning later roots', async () => {
+    const iframe = document.createElement('iframe');
+    document.body.append(iframe);
+    const ownerWindow = iframe.contentWindow!;
+    const ownerDocument = iframe.contentDocument!;
+    const ownerShadowRootPrototype = Object.getPrototypeOf(
+      ownerDocument.createElement('div').attachShadow({ mode: 'open' }),
+    );
+    const styleSheetDescriptor = Object.getOwnPropertyDescriptor(ownerWindow, 'CSSStyleSheet');
+    const adoptedStyleSheetsDescriptor = Object.getOwnPropertyDescriptor(
+      ownerShadowRootPrototype,
+      'adoptedStyleSheets',
+    );
+    const adoptedStyleSheets = new WeakMap<ShadowRoot, CSSStyleSheet[]>();
+    const container = ownerDocument.createElement('div');
+    ownerDocument.body.append(container);
+    let unmountFailed: (() => void) | undefined;
+    let unmountRecovered: (() => void) | undefined;
+
+    try {
+      Object.defineProperty(ownerShadowRootPrototype, 'adoptedStyleSheets', {
+        configurable: true,
+        get(this: ShadowRoot): CSSStyleSheet[] {
+          return adoptedStyleSheets.get(this) ?? [];
+        },
+        set(this: ShadowRoot, sheets: CSSStyleSheet[]) {
+          adoptedStyleSheets.set(this, sheets);
+        },
+      });
+      Object.defineProperty(ownerWindow, 'CSSStyleSheet', {
+        configurable: true,
+        value: class ThrowingStyleSheet {
+          replaceSync(): void {
+            throw new Error('replacement failed');
+          }
+        },
+      });
+
+      expect(() => {
+        const view = render(
+          <ShadowRootHost>
+            <span data-testid="fallback-content">Fallback content</span>
+          </ShadowRootHost>,
+          { container },
+        );
+        unmountFailed = view.unmount;
+      }).not.toThrow();
+
+      const failedRoot = await waitFor(() => {
+        const root = container.querySelector<HTMLElement>('[data-yv-shadow-host]')?.shadowRoot;
+        if (!root?.querySelector('[data-testid="fallback-content"]')) {
+          throw new Error('fallback content not rendered');
+        }
+        return root;
+      });
+      expect(failedRoot.querySelector('style[data-href="yv-sdk-shadow-styles"]')).not.toBeNull();
+
+      Object.defineProperty(ownerWindow, 'CSSStyleSheet', {
+        configurable: true,
+        value: class WorkingStyleSheet {
+          replaceSync(): void {}
+        },
+      });
+      const recoveredContainer = ownerDocument.createElement('div');
+      ownerDocument.body.append(recoveredContainer);
+      const recoveredView = render(
+        <ShadowRootHost>
+          <span data-testid="constructed-content">Constructed content</span>
+        </ShadowRootHost>,
+        { container: recoveredContainer },
+      );
+      unmountRecovered = recoveredView.unmount;
+
+      const recoveredRoot = await waitFor(() => {
+        const root = recoveredContainer.querySelector<HTMLElement>('[data-yv-shadow-host]')
+          ?.shadowRoot;
+        if (!root?.querySelector('[data-testid="constructed-content"]')) {
+          throw new Error('constructed content not rendered');
+        }
+        return root;
+      });
+      expect(recoveredRoot.adoptedStyleSheets).toHaveLength(1);
+      expect(recoveredRoot.querySelector('style')).toBeNull();
+    } finally {
+      unmountFailed?.();
+      unmountRecovered?.();
+      if (styleSheetDescriptor) {
+        Object.defineProperty(ownerWindow, 'CSSStyleSheet', styleSheetDescriptor);
+      } else {
+        Reflect.deleteProperty(ownerWindow, 'CSSStyleSheet');
+      }
+      if (adoptedStyleSheetsDescriptor) {
+        Object.defineProperty(
+          ownerShadowRootPrototype,
+          'adoptedStyleSheets',
+          adoptedStyleSheetsDescriptor,
+        );
+      } else {
+        Reflect.deleteProperty(ownerShadowRootPrototype, 'adoptedStyleSheets');
+      }
+      iframe.remove();
+    }
+  });
+
+  it('recovers from stylesheet adoption failure without poisoning later roots', async () => {
+    const iframe = document.createElement('iframe');
+    document.body.append(iframe);
+    const ownerWindow = iframe.contentWindow!;
+    const ownerDocument = iframe.contentDocument!;
+    const ownerShadowRootPrototype = Object.getPrototypeOf(
+      ownerDocument.createElement('div').attachShadow({ mode: 'open' }),
+    );
+    const styleSheetDescriptor = Object.getOwnPropertyDescriptor(ownerWindow, 'CSSStyleSheet');
+    const adoptedStyleSheetsDescriptor = Object.getOwnPropertyDescriptor(
+      ownerShadowRootPrototype,
+      'adoptedStyleSheets',
+    );
+    const adoptedStyleSheets = new WeakMap<ShadowRoot, CSSStyleSheet[]>();
+    const container = ownerDocument.createElement('div');
+    ownerDocument.body.append(container);
+    let rejectAdoption = true;
+    let unmountFailed: (() => void) | undefined;
+    let unmountRecovered: (() => void) | undefined;
+
+    try {
+      Object.defineProperty(ownerShadowRootPrototype, 'adoptedStyleSheets', {
+        configurable: true,
+        get(this: ShadowRoot): CSSStyleSheet[] {
+          return adoptedStyleSheets.get(this) ?? [];
+        },
+        set(this: ShadowRoot, sheets: CSSStyleSheet[]) {
+          if (rejectAdoption) throw new Error('adoption failed');
+          adoptedStyleSheets.set(this, sheets);
+        },
+      });
+      Object.defineProperty(ownerWindow, 'CSSStyleSheet', {
+        configurable: true,
+        value: class WorkingStyleSheet {
+          replaceSync(): void {}
+        },
+      });
+
+      expect(() => {
+        const view = render(
+          <ShadowRootHost>
+            <span data-testid="fallback-content">Fallback content</span>
+          </ShadowRootHost>,
+          { container },
+        );
+        unmountFailed = view.unmount;
+      }).not.toThrow();
+
+      const failedRoot = await waitFor(() => {
+        const root = container.querySelector<HTMLElement>('[data-yv-shadow-host]')?.shadowRoot;
+        if (!root?.querySelector('[data-testid="fallback-content"]')) {
+          throw new Error('fallback content not rendered');
+        }
+        return root;
+      });
+      expect(failedRoot.querySelector('style[data-href="yv-sdk-shadow-styles"]')).not.toBeNull();
+
+      rejectAdoption = false;
+      const recoveredContainer = ownerDocument.createElement('div');
+      ownerDocument.body.append(recoveredContainer);
+      const recoveredView = render(
+        <ShadowRootHost>
+          <span data-testid="constructed-content">Constructed content</span>
+        </ShadowRootHost>,
+        { container: recoveredContainer },
+      );
+      unmountRecovered = recoveredView.unmount;
+
+      const recoveredRoot = await waitFor(() => {
+        const root = recoveredContainer.querySelector<HTMLElement>('[data-yv-shadow-host]')
+          ?.shadowRoot;
+        if (!root?.querySelector('[data-testid="constructed-content"]')) {
+          throw new Error('constructed content not rendered');
+        }
+        return root;
+      });
+      expect(recoveredRoot.adoptedStyleSheets).toHaveLength(1);
+      expect(recoveredRoot.querySelector('style')).toBeNull();
+    } finally {
+      unmountFailed?.();
+      unmountRecovered?.();
+      if (styleSheetDescriptor) {
+        Object.defineProperty(ownerWindow, 'CSSStyleSheet', styleSheetDescriptor);
+      } else {
+        Reflect.deleteProperty(ownerWindow, 'CSSStyleSheet');
+      }
+      if (adoptedStyleSheetsDescriptor) {
+        Object.defineProperty(
+          ownerShadowRootPrototype,
+          'adoptedStyleSheets',
+          adoptedStyleSheetsDescriptor,
+        );
+      } else {
+        Reflect.deleteProperty(ownerShadowRootPrototype, 'adoptedStyleSheets');
+      }
+      iframe.remove();
+    }
+  });
+
   it('creates a local portal lazily only after an overlay requests one', async () => {
     const { container } = render(
       <>
diff --git a/packages/ui/src/lib/shadow-root-host.tsx b/packages/ui/src/lib/shadow-root-host.tsx
index 1571da2c..0354dd72 100644
--- a/packages/ui/src/lib/shadow-root-host.tsx
+++ b/packages/ui/src/lib/shadow-root-host.tsx
@@ -144,6 +144,17 @@ function getOrCreateSdkStyleSheet(root: ShadowRoot): CSSStyleSheet {
   return sheet;
 }
 
+function adoptSdkStyleSheet(root: ShadowRoot): boolean {
+  if (!supportsAdoptedStyleSheets(root)) return false;
+
+  try {
+    root.adoptedStyleSheets = [getOrCreateSdkStyleSheet(root)];
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function resetHost(host: HTMLDivElement): void {
   // The host page can select this light-DOM element, including with !important.
   // Inline author-important declarations establish the smallest stable box.
@@ -363,9 +374,7 @@ export function ShadowRootHost({ children, portalStrategy }: ShadowRootHostProps
     shadowRootRef.current = root;
     if (!existingRoot) {
       resetHost(host);
-      if (supportsAdoptedStyleSheets(root)) {
-        root.adoptedStyleSheets = [getOrCreateSdkStyleSheet(root)];
-      } else {
+      if (!adoptSdkStyleSheet(root)) {
         setNeedsStyleFallback(true);
       }
     }

From 4d60babad8177974d1786f98002cb7047819aa17 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Thu, 24 Sep 2026 21:48:53 -0500
Subject: [PATCH 2/4] test(ui): consolidate shadow stylesheet failures

Refs: YPE-5947
---
 packages/ui/src/lib/shadow-root-host.test.tsx | 379 +++++-------------
 1 file changed, 94 insertions(+), 285 deletions(-)

diff --git a/packages/ui/src/lib/shadow-root-host.test.tsx b/packages/ui/src/lib/shadow-root-host.test.tsx
index 84172d69..b33d3c30 100644
--- a/packages/ui/src/lib/shadow-root-host.test.tsx
+++ b/packages/ui/src/lib/shadow-root-host.test.tsx
@@ -46,6 +46,97 @@ const IsolatedCompositionProbe = withShadowIsolation(
   'IsolatedCompositionProbe',
 );
 
+type StyleSheetFailureStage = 'adoption' | 'construction' | 'replacement';
+
+async function expectStyleSheetFailureRecovery(stage: StyleSheetFailureStage): Promise<void> {
+  const iframe = document.createElement('iframe');
+  document.body.append(iframe);
+  const ownerWindow = iframe.contentWindow!;
+  const ownerDocument = iframe.contentDocument!;
+  const ownerShadowRootPrototype = Object.getPrototypeOf(
+    ownerDocument.createElement('div').attachShadow({ mode: 'open' }),
+  );
+  const adoptedStyleSheets = new WeakMap<ShadowRoot, CSSStyleSheet[]>();
+  const failedContainer = ownerDocument.createElement('div');
+  const recoveredContainer = ownerDocument.createElement('div');
+  ownerDocument.body.append(failedContainer, recoveredContainer);
+  let rejectFailure = true;
+  let unmountFailed: (() => void) | undefined;
+  let unmountRecovered: (() => void) | undefined;
+
+  try {
+    Object.defineProperty(ownerShadowRootPrototype, 'adoptedStyleSheets', {
+      configurable: true,
+      get(this: ShadowRoot): CSSStyleSheet[] {
+        return adoptedStyleSheets.get(this) ?? [];
+      },
+      set(this: ShadowRoot, sheets: CSSStyleSheet[]) {
+        if (stage === 'adoption' && rejectFailure) throw new Error('adoption failed');
+        adoptedStyleSheets.set(this, sheets);
+      },
+    });
+    Object.defineProperty(ownerWindow, 'CSSStyleSheet', {
+      configurable: true,
+      value: class TestStyleSheet {
+        constructor() {
+          if (stage === 'construction' && rejectFailure) {
+            throw new Error('construction failed');
+          }
+        }
+
+        replaceSync(): void {
+          if (stage === 'replacement' && rejectFailure) {
+            throw new Error('replacement failed');
+          }
+        }
+      },
+    });
+
+    expect(() => {
+      const view = render(
+        <ShadowRootHost>
+          <span data-testid="fallback-content">Fallback content</span>
+        </ShadowRootHost>,
+        { container: failedContainer },
+      );
+      unmountFailed = view.unmount;
+    }).not.toThrow();
+
+    const failedRoot = await waitFor(() => {
+      const root = failedContainer.querySelector<HTMLElement>('[data-yv-shadow-host]')?.shadowRoot;
+      if (!root?.querySelector('[data-testid="fallback-content"]')) {
+        throw new Error('fallback content not rendered');
+      }
+      return root;
+    });
+    expect(failedRoot.querySelector('style[data-href="yv-sdk-shadow-styles"]')).not.toBeNull();
+
+    rejectFailure = false;
+    const recoveredView = render(
+      <ShadowRootHost>
+        <span data-testid="constructed-content">Constructed content</span>
+      </ShadowRootHost>,
+      { container: recoveredContainer },
+    );
+    unmountRecovered = recoveredView.unmount;
+
+    const recoveredRoot = await waitFor(() => {
+      const root = recoveredContainer.querySelector<HTMLElement>('[data-yv-shadow-host]')
+        ?.shadowRoot;
+      if (!root?.querySelector('[data-testid="constructed-content"]')) {
+        throw new Error('constructed content not rendered');
+      }
+      return root;
+    });
+    expect(recoveredRoot.adoptedStyleSheets).toHaveLength(1);
+    expect(recoveredRoot.querySelector('style')).toBeNull();
+  } finally {
+    unmountFailed?.();
+    unmountRecovered?.();
+    iframe.remove();
+  }
+}
+
 describe('ShadowRootHost', () => {
   it('reuses the owning boundary for SDK composition without flattening consumer-created nesting', async () => {
     const { container } = render(
@@ -196,297 +287,15 @@ describe('ShadowRootHost', () => {
   });
 
   it('recovers from stylesheet construction failure without poisoning later roots', async () => {
-    const styleSheetDescriptor = Object.getOwnPropertyDescriptor(window, 'CSSStyleSheet');
-    const adoptedStyleSheetsDescriptor = Object.getOwnPropertyDescriptor(
-      ShadowRoot.prototype,
-      'adoptedStyleSheets',
-    );
-    const adoptedStyleSheets = new WeakMap<ShadowRoot, CSSStyleSheet[]>();
-    let failedView: ReturnType<typeof render> | undefined;
-    let recoveredView: ReturnType<typeof render> | undefined;
-
-    try {
-      Object.defineProperty(ShadowRoot.prototype, 'adoptedStyleSheets', {
-        configurable: true,
-        get(this: ShadowRoot): CSSStyleSheet[] {
-          return adoptedStyleSheets.get(this) ?? [];
-        },
-        set(this: ShadowRoot, sheets: CSSStyleSheet[]) {
-          adoptedStyleSheets.set(this, sheets);
-        },
-      });
-      Object.defineProperty(window, 'CSSStyleSheet', {
-        configurable: true,
-        value: class ThrowingStyleSheet {
-          constructor() {
-            throw new Error('construction failed');
-          }
-
-          replaceSync(): void {}
-        },
-      });
-
-      expect(() => {
-        failedView = render(
-          <ShadowRootHost>
-            <span data-testid="fallback-content">Fallback content</span>
-          </ShadowRootHost>,
-        );
-      }).not.toThrow();
-
-      const failedRoot = await waitFor(() => {
-        const root = failedView?.container.querySelector<HTMLElement>('[data-yv-shadow-host]')
-          ?.shadowRoot;
-        if (!root?.querySelector('[data-testid="fallback-content"]')) {
-          throw new Error('fallback content not rendered');
-        }
-        return root;
-      });
-      expect(failedRoot.querySelector('style[data-href="yv-sdk-shadow-styles"]')).not.toBeNull();
-
-      Object.defineProperty(window, 'CSSStyleSheet', {
-        configurable: true,
-        value: class WorkingStyleSheet {
-          replaceSync(): void {}
-        },
-      });
-      recoveredView = render(
-        <ShadowRootHost>
-          <span data-testid="constructed-content">Constructed content</span>
-        </ShadowRootHost>,
-      );
-
-      const recoveredRoot = await waitFor(() => {
-        const root = recoveredView?.container.querySelector<HTMLElement>('[data-yv-shadow-host]')
-          ?.shadowRoot;
-        if (!root?.querySelector('[data-testid="constructed-content"]')) {
-          throw new Error('constructed content not rendered');
-        }
-        return root;
-      });
-      expect(recoveredRoot.adoptedStyleSheets).toHaveLength(1);
-      expect(recoveredRoot.querySelector('style')).toBeNull();
-    } finally {
-      failedView?.unmount();
-      recoveredView?.unmount();
-      if (styleSheetDescriptor) {
-        Object.defineProperty(window, 'CSSStyleSheet', styleSheetDescriptor);
-      } else {
-        Reflect.deleteProperty(window, 'CSSStyleSheet');
-      }
-      if (adoptedStyleSheetsDescriptor) {
-        Object.defineProperty(
-          ShadowRoot.prototype,
-          'adoptedStyleSheets',
-          adoptedStyleSheetsDescriptor,
-        );
-      } else {
-        Reflect.deleteProperty(ShadowRoot.prototype, 'adoptedStyleSheets');
-      }
-    }
+    await expectStyleSheetFailureRecovery('construction');
   });
 
   it('recovers from stylesheet replacement failure without poisoning later roots', async () => {
-    const iframe = document.createElement('iframe');
-    document.body.append(iframe);
-    const ownerWindow = iframe.contentWindow!;
-    const ownerDocument = iframe.contentDocument!;
-    const ownerShadowRootPrototype = Object.getPrototypeOf(
-      ownerDocument.createElement('div').attachShadow({ mode: 'open' }),
-    );
-    const styleSheetDescriptor = Object.getOwnPropertyDescriptor(ownerWindow, 'CSSStyleSheet');
-    const adoptedStyleSheetsDescriptor = Object.getOwnPropertyDescriptor(
-      ownerShadowRootPrototype,
-      'adoptedStyleSheets',
-    );
-    const adoptedStyleSheets = new WeakMap<ShadowRoot, CSSStyleSheet[]>();
-    const container = ownerDocument.createElement('div');
-    ownerDocument.body.append(container);
-    let unmountFailed: (() => void) | undefined;
-    let unmountRecovered: (() => void) | undefined;
-
-    try {
-      Object.defineProperty(ownerShadowRootPrototype, 'adoptedStyleSheets', {
-        configurable: true,
-        get(this: ShadowRoot): CSSStyleSheet[] {
-          return adoptedStyleSheets.get(this) ?? [];
-        },
-        set(this: ShadowRoot, sheets: CSSStyleSheet[]) {
-          adoptedStyleSheets.set(this, sheets);
-        },
-      });
-      Object.defineProperty(ownerWindow, 'CSSStyleSheet', {
-        configurable: true,
-        value: class ThrowingStyleSheet {
-          replaceSync(): void {
-            throw new Error('replacement failed');
-          }
-        },
-      });
-
-      expect(() => {
-        const view = render(
-          <ShadowRootHost>
-            <span data-testid="fallback-content">Fallback content</span>
-          </ShadowRootHost>,
-          { container },
-        );
-        unmountFailed = view.unmount;
-      }).not.toThrow();
-
-      const failedRoot = await waitFor(() => {
-        const root = container.querySelector<HTMLElement>('[data-yv-shadow-host]')?.shadowRoot;
-        if (!root?.querySelector('[data-testid="fallback-content"]')) {
-          throw new Error('fallback content not rendered');
-        }
-        return root;
-      });
-      expect(failedRoot.querySelector('style[data-href="yv-sdk-shadow-styles"]')).not.toBeNull();
-
-      Object.defineProperty(ownerWindow, 'CSSStyleSheet', {
-        configurable: true,
-        value: class WorkingStyleSheet {
-          replaceSync(): void {}
-        },
-      });
-      const recoveredContainer = ownerDocument.createElement('div');
-      ownerDocument.body.append(recoveredContainer);
-      const recoveredView = render(
-        <ShadowRootHost>
-          <span data-testid="constructed-content">Constructed content</span>
-        </ShadowRootHost>,
-        { container: recoveredContainer },
-      );
-      unmountRecovered = recoveredView.unmount;
-
-      const recoveredRoot = await waitFor(() => {
-        const root = recoveredContainer.querySelector<HTMLElement>('[data-yv-shadow-host]')
-          ?.shadowRoot;
-        if (!root?.querySelector('[data-testid="constructed-content"]')) {
-          throw new Error('constructed content not rendered');
-        }
-        return root;
-      });
-      expect(recoveredRoot.adoptedStyleSheets).toHaveLength(1);
-      expect(recoveredRoot.querySelector('style')).toBeNull();
-    } finally {
-      unmountFailed?.();
-      unmountRecovered?.();
-      if (styleSheetDescriptor) {
-        Object.defineProperty(ownerWindow, 'CSSStyleSheet', styleSheetDescriptor);
-      } else {
-        Reflect.deleteProperty(ownerWindow, 'CSSStyleSheet');
-      }
-      if (adoptedStyleSheetsDescriptor) {
-        Object.defineProperty(
-          ownerShadowRootPrototype,
-          'adoptedStyleSheets',
-          adoptedStyleSheetsDescriptor,
-        );
-      } else {
-        Reflect.deleteProperty(ownerShadowRootPrototype, 'adoptedStyleSheets');
-      }
-      iframe.remove();
-    }
+    await expectStyleSheetFailureRecovery('replacement');
   });
 
   it('recovers from stylesheet adoption failure without poisoning later roots', async () => {
-    const iframe = document.createElement('iframe');
-    document.body.append(iframe);
-    const ownerWindow = iframe.contentWindow!;
-    const ownerDocument = iframe.contentDocument!;
-    const ownerShadowRootPrototype = Object.getPrototypeOf(
-      ownerDocument.createElement('div').attachShadow({ mode: 'open' }),
-    );
-    const styleSheetDescriptor = Object.getOwnPropertyDescriptor(ownerWindow, 'CSSStyleSheet');
-    const adoptedStyleSheetsDescriptor = Object.getOwnPropertyDescriptor(
-      ownerShadowRootPrototype,
-      'adoptedStyleSheets',
-    );
-    const adoptedStyleSheets = new WeakMap<ShadowRoot, CSSStyleSheet[]>();
-    const container = ownerDocument.createElement('div');
-    ownerDocument.body.append(container);
-    let rejectAdoption = true;
-    let unmountFailed: (() => void) | undefined;
-    let unmountRecovered: (() => void) | undefined;
-
-    try {
-      Object.defineProperty(ownerShadowRootPrototype, 'adoptedStyleSheets', {
-        configurable: true,
-        get(this: ShadowRoot): CSSStyleSheet[] {
-          return adoptedStyleSheets.get(this) ?? [];
-        },
-        set(this: ShadowRoot, sheets: CSSStyleSheet[]) {
-          if (rejectAdoption) throw new Error('adoption failed');
-          adoptedStyleSheets.set(this, sheets);
-        },
-      });
-      Object.defineProperty(ownerWindow, 'CSSStyleSheet', {
-        configurable: true,
-        value: class WorkingStyleSheet {
-          replaceSync(): void {}
-        },
-      });
-
-      expect(() => {
-        const view = render(
-          <ShadowRootHost>
-            <span data-testid="fallback-content">Fallback content</span>
-          </ShadowRootHost>,
-          { container },
-        );
-        unmountFailed = view.unmount;
-      }).not.toThrow();
-
-      const failedRoot = await waitFor(() => {
-        const root = container.querySelector<HTMLElement>('[data-yv-shadow-host]')?.shadowRoot;
-        if (!root?.querySelector('[data-testid="fallback-content"]')) {
-          throw new Error('fallback content not rendered');
-        }
-        return root;
-      });
-      expect(failedRoot.querySelector('style[data-href="yv-sdk-shadow-styles"]')).not.toBeNull();
-
-      rejectAdoption = false;
-      const recoveredContainer = ownerDocument.createElement('div');
-      ownerDocument.body.append(recoveredContainer);
-      const recoveredView = render(
-        <ShadowRootHost>
-          <span data-testid="constructed-content">Constructed content</span>
-        </ShadowRootHost>,
-        { container: recoveredContainer },
-      );
-      unmountRecovered = recoveredView.unmount;
-
-      const recoveredRoot = await waitFor(() => {
-        const root = recoveredContainer.querySelector<HTMLElement>('[data-yv-shadow-host]')
-          ?.shadowRoot;
-        if (!root?.querySelector('[data-testid="constructed-content"]')) {
-          throw new Error('constructed content not rendered');
-        }
-        return root;
-      });
-      expect(recoveredRoot.adoptedStyleSheets).toHaveLength(1);
-      expect(recoveredRoot.querySelector('style')).toBeNull();
-    } finally {
-      unmountFailed?.();
-      unmountRecovered?.();
-      if (styleSheetDescriptor) {
-        Object.defineProperty(ownerWindow, 'CSSStyleSheet', styleSheetDescriptor);
-      } else {
-        Reflect.deleteProperty(ownerWindow, 'CSSStyleSheet');
-      }
-      if (adoptedStyleSheetsDescriptor) {
-        Object.defineProperty(
-          ownerShadowRootPrototype,
-          'adoptedStyleSheets',
-          adoptedStyleSheetsDescriptor,
-        );
-      } else {
-        Reflect.deleteProperty(ownerShadowRootPrototype, 'adoptedStyleSheets');
-      }
-      iframe.remove();
-    }
+    await expectStyleSheetFailureRecovery('adoption');
   });
 
   it('creates a local portal lazily only after an overlay requests one', async () => {

From 61c5cda976903343354cc7fa201fe128589dfd1f Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Fri, 25 Sep 2026 09:28:47 -0500
Subject: [PATCH 3/4] test(ui): prove shadow recovery across documents

Refs: YPE-5947
---
 packages/ui/src/lib/shadow-root-host.test.tsx | 77 ++++++++++++++++++-
 1 file changed, 73 insertions(+), 4 deletions(-)

diff --git a/packages/ui/src/lib/shadow-root-host.test.tsx b/packages/ui/src/lib/shadow-root-host.test.tsx
index b33d3c30..947e8ec8 100644
--- a/packages/ui/src/lib/shadow-root-host.test.tsx
+++ b/packages/ui/src/lib/shadow-root-host.test.tsx
@@ -48,8 +48,33 @@ const IsolatedCompositionProbe = withShadowIsolation(
 
 type StyleSheetFailureStage = 'adoption' | 'construction' | 'replacement';
 
+function installWorkingConstructableStyleSheets(ownerDocument: Document): void {
+  const ownerWindow = ownerDocument.defaultView!;
+  const shadowRootPrototype = Object.getPrototypeOf(
+    ownerDocument.createElement('div').attachShadow({ mode: 'open' }),
+  );
+  const adoptedStyleSheets = new WeakMap<ShadowRoot, CSSStyleSheet[]>();
+
+  Object.defineProperty(shadowRootPrototype, 'adoptedStyleSheets', {
+    configurable: true,
+    get(this: ShadowRoot): CSSStyleSheet[] {
+      return adoptedStyleSheets.get(this) ?? [];
+    },
+    set(this: ShadowRoot, sheets: CSSStyleSheet[]) {
+      adoptedStyleSheets.set(this, sheets);
+    },
+  });
+  Object.defineProperty(ownerWindow, 'CSSStyleSheet', {
+    configurable: true,
+    value: class TestStyleSheet {
+      replaceSync(): void {}
+    },
+  });
+}
+
 async function expectStyleSheetFailureRecovery(stage: StyleSheetFailureStage): Promise<void> {
   const iframe = document.createElement('iframe');
+  const laterIframe = document.createElement('iframe');
   document.body.append(iframe);
   const ownerWindow = iframe.contentWindow!;
   const ownerDocument = iframe.contentDocument!;
@@ -59,10 +84,13 @@ async function expectStyleSheetFailureRecovery(stage: StyleSheetFailureStage): P
   const adoptedStyleSheets = new WeakMap<ShadowRoot, CSSStyleSheet[]>();
   const failedContainer = ownerDocument.createElement('div');
   const recoveredContainer = ownerDocument.createElement('div');
-  ownerDocument.body.append(failedContainer, recoveredContainer);
+  const sharedContainer = ownerDocument.createElement('div');
+  ownerDocument.body.append(failedContainer, recoveredContainer, sharedContainer);
   let rejectFailure = true;
   let unmountFailed: (() => void) | undefined;
   let unmountRecovered: (() => void) | undefined;
+  let unmountShared: (() => void) | undefined;
+  let unmountLaterDocument: (() => void) | undefined;
 
   try {
     Object.defineProperty(ownerShadowRootPrototype, 'adoptedStyleSheets', {
@@ -130,10 +158,51 @@ async function expectStyleSheetFailureRecovery(stage: StyleSheetFailureStage): P
     });
     expect(recoveredRoot.adoptedStyleSheets).toHaveLength(1);
     expect(recoveredRoot.querySelector('style')).toBeNull();
+
+    const sharedView = render(
+      <ShadowRootHost>
+        <span data-testid="shared-content">Shared content</span>
+      </ShadowRootHost>,
+      { container: sharedContainer },
+    );
+    unmountShared = sharedView.unmount;
+    const sharedRoot = await waitFor(() => {
+      const root = sharedContainer.querySelector<HTMLElement>('[data-yv-shadow-host]')?.shadowRoot;
+      if (!root?.querySelector('[data-testid="shared-content"]')) {
+        throw new Error('shared content not rendered');
+      }
+      return root;
+    });
+    expect(sharedRoot.adoptedStyleSheets[0]).toBe(recoveredRoot.adoptedStyleSheets[0]);
+
+    document.body.append(laterIframe);
+    const laterDocument = laterIframe.contentDocument!;
+    installWorkingConstructableStyleSheets(laterDocument);
+    const laterContainer = laterDocument.createElement('div');
+    laterDocument.body.append(laterContainer);
+    const laterView = render(
+      <ShadowRootHost>
+        <span data-testid="later-document-content">Later document content</span>
+      </ShadowRootHost>,
+      { container: laterContainer },
+    );
+    unmountLaterDocument = laterView.unmount;
+    const laterRoot = await waitFor(() => {
+      const root = laterContainer.querySelector<HTMLElement>('[data-yv-shadow-host]')?.shadowRoot;
+      if (!root?.querySelector('[data-testid="later-document-content"]')) {
+        throw new Error('later document content not rendered');
+      }
+      return root;
+    });
+    expect(laterRoot.adoptedStyleSheets).toHaveLength(1);
+    expect(laterRoot.querySelector('style')).toBeNull();
   } finally {
     unmountFailed?.();
     unmountRecovered?.();
+    unmountShared?.();
+    unmountLaterDocument?.();
     iframe.remove();
+    laterIframe.remove();
   }
 }
 
@@ -286,15 +355,15 @@ describe('ShadowRootHost', () => {
     expect(style?.getAttribute('data-precedence')).toBe('yv-sdk');
   });
 
-  it('recovers from stylesheet construction failure without poisoning later roots', async () => {
+  it('recovers from stylesheet construction failure without poisoning later roots or documents', async () => {
     await expectStyleSheetFailureRecovery('construction');
   });
 
-  it('recovers from stylesheet replacement failure without poisoning later roots', async () => {
+  it('recovers from stylesheet replacement failure without poisoning later roots or documents', async () => {
     await expectStyleSheetFailureRecovery('replacement');
   });
 
-  it('recovers from stylesheet adoption failure without poisoning later roots', async () => {
+  it('recovers from stylesheet adoption failure without poisoning later roots or documents', async () => {
     await expectStyleSheetFailureRecovery('adoption');
   });
 

From b34f08fac5fc2f904aeabf8e77952fe67e342991 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Fri, 25 Sep 2026 12:25:53 -0500
Subject: [PATCH 4/4] test(ui): assert document-scoped shadow stylesheet

---
 packages/ui/src/lib/shadow-root-host.test.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/ui/src/lib/shadow-root-host.test.tsx b/packages/ui/src/lib/shadow-root-host.test.tsx
index 947e8ec8..3d709378 100644
--- a/packages/ui/src/lib/shadow-root-host.test.tsx
+++ b/packages/ui/src/lib/shadow-root-host.test.tsx
@@ -195,6 +195,7 @@ async function expectStyleSheetFailureRecovery(stage: StyleSheetFailureStage): P
       return root;
     });
     expect(laterRoot.adoptedStyleSheets).toHaveLength(1);
+    expect(laterRoot.adoptedStyleSheets[0]).not.toBe(recoveredRoot.adoptedStyleSheets[0]);
     expect(laterRoot.querySelector('style')).toBeNull();
   } finally {
     unmountFailed?.();