From 5983688c484eb3c29bf76b6970630f6d00057a92 Mon Sep 17 00:00:00 2001
From: abharms <aharms@works24.com>
Date: Fri, 7 Aug 2026 07:29:02 -0500
Subject: [PATCH 01/11] feat(ui)!: prototype automatic Shadow DOM isolation

---
 .changeset/prototype-shadow-dom-isolation.md  |   7 ++
 ...05-prototype-shadow-dom-style-isolation.md |  45 +++++++
 ...ionAuthButton.shadow-isolation.stories.tsx | 110 ++++++++++++++++++
 .../YouVersionAuthButton.stories.tsx          |  32 +++--
 .../src/components/YouVersionAuthButton.tsx   |  14 ++-
 packages/ui/src/lib/shadow-isolation.tsx      |  25 ++++
 packages/ui/src/lib/shadow-root-host.test.tsx |  34 ++++++
 packages/ui/src/lib/shadow-root-host.tsx      |  82 +++++++++++++
 8 files changed, 340 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/prototype-shadow-dom-isolation.md
 create mode 100644 docs/adr/0005-prototype-shadow-dom-style-isolation.md
 create mode 100644 packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
 create mode 100644 packages/ui/src/lib/shadow-isolation.tsx
 create mode 100644 packages/ui/src/lib/shadow-root-host.test.tsx
 create mode 100644 packages/ui/src/lib/shadow-root-host.tsx

diff --git a/.changeset/prototype-shadow-dom-isolation.md b/.changeset/prototype-shadow-dom-isolation.md
new file mode 100644
index 00000000..6c11fe80
--- /dev/null
+++ b/.changeset/prototype-shadow-dom-isolation.md
@@ -0,0 +1,7 @@
+---
+'@youversion/platform-core': major
+'@youversion/platform-react-hooks': major
+'@youversion/platform-react-ui': major
+---
+
+Prototype automatic Shadow DOM style isolation on `YouVersionAuthButton` so host-page selectors cannot override its internal styles.
diff --git a/docs/adr/0005-prototype-shadow-dom-style-isolation.md b/docs/adr/0005-prototype-shadow-dom-style-isolation.md
new file mode 100644
index 00000000..7e7661d5
--- /dev/null
+++ b/docs/adr/0005-prototype-shadow-dom-style-isolation.md
@@ -0,0 +1,45 @@
+# ADR 0005: Prototype automatic Shadow DOM style isolation
+
+Status: Proposed proof of concept
+
+## Problem
+
+Host applications can apply unlayered global rules such as `button { ... }` or
+Tailwind v3 preflight to SDK markup. Unlayered author CSS outranks the SDK's
+layered CSS, so selector specificity alone cannot guarantee isolation.
+
+## Prototype
+
+`YouVersionAuthButton` automatically creates an open shadow root and renders its
+existing implementation inside it. The SDK's compiled CSS is installed inside
+that root. Consumers continue to write `<YouVersionAuthButton />`; isolation is
+not an option they must discover or enable.
+
+This PR intentionally applies the architecture to one representative component.
+It asks whether automatic Shadow DOM boundaries are the right foundation before
+the same pattern is rolled out across the UI package.
+
+The constructable stylesheet is cached per owner `Document`, because a sheet
+created in the top-level document cannot be adopted by a shadow root rendered in
+a same-origin iframe. Browsers without constructable stylesheets receive a
+`<style>` element in the root. The light-DOM host gets an inline-important box
+reset; an inner, unreachable wrapper resets inherited standard properties.
+
+## What this proves
+
+- Ordinary and `!important` host selectors cannot select the button internals.
+- The consumer API is unchanged and isolation is automatic.
+- Existing click handlers and forwarded refs can cross the React portal.
+- Strict Mode does not attach the root twice.
+
+## Deliberately deferred
+
+- Rollout to all exported components.
+- Radix popover/dialog portal placement and focus management.
+- Form association when controls live outside their form's tree scope.
+- SSR/hydration and the first client paint.
+- Host `@font-face` rules, which are not scoped by Shadow DOM.
+- A full browser/accessibility matrix and consumer test-query migration guidance.
+
+This prototype should be reviewed as an architectural checkpoint, not as a
+complete solution ready for release.
diff --git a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
new file mode 100644
index 00000000..25b72cb6
--- /dev/null
+++ b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
@@ -0,0 +1,110 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { http, HttpResponse } from 'msw';
+import { createRoot } from 'react-dom/client';
+import { expect, waitFor } from 'storybook/test';
+import { ShadowRootHost } from '../lib/shadow-root-host';
+import { YouVersionAuthButton } from './YouVersionAuthButton';
+
+const HOSTILE_CSS = `
+  button {
+    appearance: none !important;
+    background: rgb(185, 28, 28) !important;
+    border: 10px dashed lime !important;
+    color: yellow !important;
+    font: 32px/1 fantasy !important;
+    padding: 40px !important;
+    text-transform: uppercase !important;
+  }
+`;
+
+const meta = {
+  title: 'Spikes/Automatic Shadow DOM isolation',
+  component: YouVersionAuthButton,
+  parameters: {
+    msw: {
+      handlers: [
+        http.get('*/v1/fonts/1/stylesheet', () =>
+          HttpResponse.text('', { headers: { 'Content-Type': 'text/css' } }),
+        ),
+      ],
+    },
+  },
+} satisfies Meta<typeof YouVersionAuthButton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const HostileGlobalButtonRule: Story = {
+  tags: ['integration'],
+  render: () => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 24 }}>
+      <button type="button" data-testid="host-control">
+        Host control
+      </button>
+      <YouVersionAuthButton data-testid="sdk-button" />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const style = document.createElement('style');
+    style.textContent = HOSTILE_CSS;
+    document.head.append(style);
+
+    try {
+      const control = await waitFor(() => {
+        const element = canvasElement.querySelector<HTMLElement>('[data-testid="host-control"]');
+        if (!element) throw new Error('host control not rendered');
+        return element;
+      });
+      const host = await waitFor(() => {
+        const element = canvasElement.querySelector<HTMLElement>('[data-yv-shadow-host]');
+        if (!element?.shadowRoot) throw new Error('shadow root not attached');
+        return element;
+      });
+      const sdkButton = await waitFor(() => {
+        const element = host.shadowRoot?.querySelector<HTMLElement>('[data-testid="sdk-button"]');
+        if (!element) throw new Error('SDK button not rendered');
+        return element;
+      });
+      await waitFor(() => {
+        void expect(getComputedStyle(control).backgroundColor).toBe('rgb(185, 28, 28)');
+      });
+      void expect(getComputedStyle(sdkButton).backgroundColor).not.toBe('rgb(185, 28, 28)');
+      void expect(getComputedStyle(sdkButton).borderTopWidth).not.toBe('10px');
+      void expect(getComputedStyle(sdkButton).fontSize).not.toBe('32px');
+    } finally {
+      style.remove();
+    }
+  },
+};
+
+export const SameOriginIframeDocument: Story = {
+  tags: ['integration'],
+  parameters: { includeAuth: false },
+  render: () => <iframe data-testid="iframe" title="same-origin isolation target" />,
+  play: async ({ canvasElement }) => {
+    const iframe = canvasElement.querySelector<HTMLIFrameElement>('[data-testid="iframe"]');
+    if (!iframe?.contentDocument) throw new Error('same-origin iframe document not available');
+
+    const container = iframe.contentDocument.createElement('div');
+    iframe.contentDocument.body.append(container);
+    const root = createRoot(container);
+
+    try {
+      root.render(
+        <ShadowRootHost>
+          <span data-testid="iframe-content">Isolated</span>
+        </ShadowRootHost>,
+      );
+
+      await waitFor(() => {
+        const host = iframe.contentDocument?.querySelector<HTMLElement>('[data-yv-shadow-host]');
+        const content = host?.shadowRoot?.querySelector('[data-testid="iframe-content"]');
+        if (!content) throw new Error('iframe shadow content not mounted');
+        void expect(host?.ownerDocument).toBe(iframe.contentDocument);
+      });
+    } finally {
+      root.unmount();
+      container.remove();
+    }
+  },
+};
diff --git a/packages/ui/src/components/YouVersionAuthButton.stories.tsx b/packages/ui/src/components/YouVersionAuthButton.stories.tsx
index ca11c634..1b9b31aa 100644
--- a/packages/ui/src/components/YouVersionAuthButton.stories.tsx
+++ b/packages/ui/src/components/YouVersionAuthButton.stories.tsx
@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { expect, fn, userEvent, within, spyOn } from 'storybook/test';
+import { http, HttpResponse } from 'msw';
+import { expect, fn, userEvent, waitFor, spyOn } from 'storybook/test';
 import { YouVersionAuthButton } from './YouVersionAuthButton';
 
 // Store mock reference for interaction test
@@ -10,6 +11,13 @@ const meta = {
   component: YouVersionAuthButton,
   parameters: {
     layout: 'centered',
+    msw: {
+      handlers: [
+        http.get('*/v1/fonts/1/stylesheet', () =>
+          HttpResponse.text('', { headers: { 'Content-Type': 'text/css' } }),
+        ),
+      ],
+    },
   },
   tags: ['autodocs'],
   async beforeEach() {
@@ -74,6 +82,20 @@ export default meta;
 
 type Story = StoryObj<typeof meta>;
 
+async function findAuthButton(
+  canvasElement: HTMLElement,
+  name: RegExp,
+): Promise<HTMLButtonElement> {
+  return waitFor(() => {
+    const host = canvasElement.querySelector<HTMLElement>('[data-yv-shadow-host]');
+    const button = Array.from(host?.shadowRoot?.querySelectorAll('button') ?? []).find(
+      (candidate) => name.test(candidate.textContent ?? ''),
+    );
+    if (!button) throw new Error(`auth button matching ${name} not found`);
+    return button;
+  });
+}
+
 export const Default: Story = {};
 
 export const LightOutline: Story = {
@@ -271,10 +293,8 @@ export const InteractionTestWithMockedAuth: Story = {
   },
   tags: ['integration'],
   play: async ({ canvasElement }) => {
-    const canvas = within(canvasElement);
-
     // Wait for the auth provider to load and the button to appear
-    const loginButton = await canvas.findByRole('button', { name: /sign in with youversion/i });
+    const loginButton = await findAuthButton(canvasElement, /sign in with youversion/i);
     await userEvent.click(loginButton);
 
     void expect(signInMock).toHaveBeenCalled();
@@ -288,10 +308,8 @@ export const CustomText: Story = {
   },
   tags: ['integration'],
   play: async ({ canvasElement }) => {
-    const canvas = within(canvasElement);
-
     // Wait for the auth provider to load and the button to appear
-    const loginButton = await canvas.findByRole('button', { name: /custom text/i });
+    const loginButton = await findAuthButton(canvasElement, /custom text/i);
     await userEvent.click(loginButton);
 
     void expect(signInMock).toHaveBeenCalled();
diff --git a/packages/ui/src/components/YouVersionAuthButton.tsx b/packages/ui/src/components/YouVersionAuthButton.tsx
index c80a2579..33c9affb 100644
--- a/packages/ui/src/components/YouVersionAuthButton.tsx
+++ b/packages/ui/src/components/YouVersionAuthButton.tsx
@@ -10,6 +10,7 @@ import { useYVAuth, useTheme } from '@youversion/platform-react-hooks';
 import { Button } from '../components/ui/button';
 import { YouVersionLogo } from './icons/youversion-logo';
 import { cn } from '../lib/utils';
+import { withShadowIsolation } from '../lib/shadow-isolation';
 
 interface SignInAuthProps {
   /**
@@ -109,7 +110,7 @@ export interface YouVersionAuthButtonProps
  * <YouVersionAuthButton scopes={['profile']}/>
  *
  */
-export const YouVersionAuthButton = React.forwardRef<HTMLButtonElement, YouVersionAuthButtonProps>(
+const YouVersionAuthButtonImpl = React.forwardRef<HTMLButtonElement, YouVersionAuthButtonProps>(
   (
     {
       background,
@@ -266,4 +267,13 @@ export const YouVersionAuthButton = React.forwardRef<HTMLButtonElement, YouVersi
   },
 );
 
-YouVersionAuthButton.displayName = 'YouVersionAuthButton';
+YouVersionAuthButtonImpl.displayName = 'YouVersionAuthButtonImpl';
+
+/**
+ * Automatically rendered in a Shadow DOM so host-page selectors cannot style
+ * the button's internal DOM. No consumer wrapper or opt-in flag is required.
+ */
+export const YouVersionAuthButton = withShadowIsolation(
+  YouVersionAuthButtonImpl,
+  'YouVersionAuthButton',
+);
diff --git a/packages/ui/src/lib/shadow-isolation.tsx b/packages/ui/src/lib/shadow-isolation.tsx
new file mode 100644
index 00000000..7ca16cc7
--- /dev/null
+++ b/packages/ui/src/lib/shadow-isolation.tsx
@@ -0,0 +1,25 @@
+import {
+  createElement,
+  forwardRef,
+  type ForwardRefExoticComponent,
+  type PropsWithoutRef,
+  type RefAttributes,
+} from 'react';
+import { ShadowRootHost } from './shadow-root-host';
+
+/** @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) => (
+    <ShadowRootHost>
+      {createElement(Implementation, {
+        ...(props as P),
+        ref,
+      } as unknown as PropsWithoutRef<P> & RefAttributes<T>)}
+    </ShadowRootHost>
+  ));
+  Isolated.displayName = displayName;
+  return Isolated;
+}
diff --git a/packages/ui/src/lib/shadow-root-host.test.tsx b/packages/ui/src/lib/shadow-root-host.test.tsx
new file mode 100644
index 00000000..e0276974
--- /dev/null
+++ b/packages/ui/src/lib/shadow-root-host.test.tsx
@@ -0,0 +1,34 @@
+import { StrictMode } from 'react';
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { ShadowRootHost } from './shadow-root-host';
+
+describe('ShadowRootHost', () => {
+  it('attaches one shadow root under StrictMode', () => {
+    expect(() =>
+      render(
+        <StrictMode>
+          <ShadowRootHost>
+            <span>content</span>
+          </ShadowRootHost>
+        </StrictMode>,
+      ),
+    ).not.toThrow();
+
+    const host = document.querySelector<HTMLElement>('[data-yv-shadow-host]');
+    expect(host?.shadowRoot?.textContent).toContain('content');
+  });
+
+  it('locks the host box against host-page important rules', () => {
+    render(
+      <ShadowRootHost>
+        <span>content</span>
+      </ShadowRootHost>,
+    );
+
+    const host = document.querySelector<HTMLElement>('[data-yv-shadow-host]');
+    expect(host?.style.getPropertyValue('all')).toBe('initial');
+    expect(host?.style.getPropertyValue('display')).toBe('contents');
+    expect(host?.style.getPropertyPriority('display')).toBe('important');
+  });
+});
diff --git a/packages/ui/src/lib/shadow-root-host.tsx b/packages/ui/src/lib/shadow-root-host.tsx
new file mode 100644
index 00000000..b0185cfe
--- /dev/null
+++ b/packages/ui/src/lib/shadow-root-host.tsx
@@ -0,0 +1,82 @@
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+
+declare const __YV_STYLES__: string;
+
+const sdkStyleSheets = new WeakMap<Document, CSSStyleSheet>();
+
+function getStyleSheetConstructor(root: ShadowRoot): typeof CSSStyleSheet | undefined {
+  return root.ownerDocument.defaultView?.CSSStyleSheet;
+}
+
+function supportsAdoptedStyleSheets(root: ShadowRoot): boolean {
+  const StyleSheet = getStyleSheetConstructor(root);
+  return (
+    StyleSheet !== undefined &&
+    typeof StyleSheet.prototype.replaceSync === 'function' &&
+    'adoptedStyleSheets' in root
+  );
+}
+
+function getOrCreateSdkStyleSheet(root: ShadowRoot): CSSStyleSheet {
+  const ownerDocument = root.ownerDocument;
+  const existing = sdkStyleSheets.get(ownerDocument);
+  if (existing) return existing;
+
+  const StyleSheet = getStyleSheetConstructor(root)!;
+  const sheet = new StyleSheet();
+  sheet.replaceSync(__YV_STYLES__);
+  sdkStyleSheets.set(ownerDocument, sheet);
+  return sheet;
+}
+
+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.
+  host.style.setProperty('all', 'initial', 'important');
+  host.style.setProperty('display', 'contents', 'important');
+  host.style.setProperty('writing-mode', 'inherit', 'important');
+  host.style.setProperty('text-orientation', 'inherit', 'important');
+}
+
+interface ShadowRootHostProps {
+  children: ReactNode;
+}
+
+/** @internal Proof-of-concept primitive; not part of the public API. */
+export function ShadowRootHost({ children }: ShadowRootHostProps): React.ReactNode {
+  const hostRef = useRef<HTMLDivElement | null>(null);
+  const [shadowRoot, setShadowRoot] = useState<ShadowRoot | null>(null);
+  const [needsStyleFallback, setNeedsStyleFallback] = useState(false);
+
+  useEffect(() => {
+    const host = hostRef.current;
+    // React StrictMode replays effects against the same DOM node. Inspect the
+    // live node instead of captured state so attachShadow is called only once.
+    if (!host || host.shadowRoot) return;
+
+    resetHost(host);
+    const root = host.attachShadow({ mode: 'open' });
+    if (supportsAdoptedStyleSheets(root)) {
+      root.adoptedStyleSheets = [getOrCreateSdkStyleSheet(root)];
+    } else {
+      setNeedsStyleFallback(true);
+    }
+    setShadowRoot(root);
+  }, []);
+
+  return (
+    <div ref={hostRef} data-yv-shadow-host>
+      {shadowRoot
+        ? createPortal(
+            <>
+              {needsStyleFallback ? <style>{__YV_STYLES__}</style> : null}
+              {/* Host selectors cannot reach this reset boundary. */}
+              <div style={{ all: 'initial', display: 'contents' }}>{children}</div>
+            </>,
+            shadowRoot,
+          )
+        : null}
+    </div>
+  );
+}

From 7108e77a7e66da782e477691a9f65cf56bf0ed0c Mon Sep 17 00:00:00 2001
From: abharms <aharms@works24.com>
Date: Fri, 7 Aug 2026 10:00:44 -0500
Subject: [PATCH 02/11] docs(examples): add hostile CSS POC demo

---
 examples/vite-react/src/App.tsx               |   4 +-
 examples/vite-react/src/components/navbar.tsx |   1 +
 .../vite-react/src/pages/HostileCssPage.tsx   | 161 ++++++++++++++++++
 .../src/components/YouVersionAuthButton.tsx   |   4 +-
 4 files changed, 167 insertions(+), 3 deletions(-)
 create mode 100644 examples/vite-react/src/pages/HostileCssPage.tsx

diff --git a/examples/vite-react/src/App.tsx b/examples/vite-react/src/App.tsx
index 7aa7d508..ed33c609 100644
--- a/examples/vite-react/src/App.tsx
+++ b/examples/vite-react/src/App.tsx
@@ -3,8 +3,9 @@ import { Navbar } from '@/components/navbar';
 import { BibleReaderPage } from '@/pages/BibleReaderPage';
 import { VotdPage } from '@/pages/VotdPage';
 import { BibleCardPage } from '@/pages/BibleCardPage';
+import { HostileCssPage } from '@/pages/HostileCssPage';
 
-export type Page = 'bible-reader' | 'votd' | 'bible-card';
+export type Page = 'bible-reader' | 'votd' | 'bible-card' | 'hostile-css';
 
 function App() {
   const [currentPage, setCurrentPage] = useState<Page>('bible-reader');
@@ -16,6 +17,7 @@ function App() {
         {currentPage === 'bible-reader' && <BibleReaderPage />}
         {currentPage === 'votd' && <VotdPage />}
         {currentPage === 'bible-card' && <BibleCardPage />}
+        {currentPage === 'hostile-css' && <HostileCssPage />}
       </main>
     </div>
   );
diff --git a/examples/vite-react/src/components/navbar.tsx b/examples/vite-react/src/components/navbar.tsx
index a9c9ecb6..9d6ee951 100644
--- a/examples/vite-react/src/components/navbar.tsx
+++ b/examples/vite-react/src/components/navbar.tsx
@@ -10,6 +10,7 @@ const navItems: { label: string; page: Page }[] = [
   { label: 'Bible Reader', page: 'bible-reader' },
   { label: 'Verse of the Day', page: 'votd' },
   { label: 'Bible Card', page: 'bible-card' },
+  { label: 'Hostile CSS', page: 'hostile-css' },
 ];
 
 interface NavbarProps {
diff --git a/examples/vite-react/src/pages/HostileCssPage.tsx b/examples/vite-react/src/pages/HostileCssPage.tsx
new file mode 100644
index 00000000..35003890
--- /dev/null
+++ b/examples/vite-react/src/pages/HostileCssPage.tsx
@@ -0,0 +1,161 @@
+import { useState } from 'react';
+import { YouVersionAuthButton } from '@youversion/platform-react-ui';
+
+interface HostileVector {
+  key: string;
+  label: string;
+  expectation: string;
+  css: string;
+}
+
+const HOSTILE_VECTORS: HostileVector[] = [
+  {
+    key: 'type-selectors',
+    label: 'Type selectors',
+    expectation: 'The plain button changes; the SDK button should not.',
+    css: `
+.hostile-zone button,
+.hostile-zone [role='button'] {
+  appearance: none !important;
+  background: #b91c1c !important;
+  border: 8px dashed #84cc16 !important;
+  border-radius: 0 !important;
+  color: #fff !important;
+  font: 28px/1 fantasy !important;
+  padding: 28px !important;
+  text-transform: uppercase !important;
+}`,
+  },
+  {
+    key: 'inherited',
+    label: 'Inherited properties',
+    expectation: 'Host text changes; the SDK button should retain its typography.',
+    css: `
+.hostile-zone {
+  color: #d600d6 !important;
+  cursor: crosshair !important;
+  font-family: 'Comic Sans MS', fantasy !important;
+  font-size: 24px !important;
+  font-style: italic !important;
+  letter-spacing: 0.25em !important;
+  line-height: 2.4 !important;
+  text-transform: uppercase !important;
+}`,
+  },
+  {
+    key: 'universal-important',
+    label: 'Universal selector with !important',
+    expectation: 'Every reachable host element changes; shadow internals should not.',
+    css: `
+.hostile-zone * {
+  color: #d600d6 !important;
+  font-family: 'Comic Sans MS', fantasy !important;
+  letter-spacing: 0.2em !important;
+  text-transform: uppercase !important;
+}`,
+  },
+  {
+    key: 'shadow-host',
+    label: 'Shadow-host box attack',
+    expectation: 'The witness disappears; the SDK host should remain usable.',
+    css: `
+.hostile-zone [data-yv-shadow-host],
+.hostile-zone [data-host-box-witness] {
+  display: none !important;
+  opacity: 0 !important;
+  pointer-events: none !important;
+  transform: scale(0.5) !important;
+}`,
+  },
+  {
+    key: 'font-face',
+    label: '@font-face family collision (known limitation)',
+    expectation:
+      'Registers a document-level Inter collision that can reach the shadow tree; the visible result depends on locally installed fonts.',
+    css: `
+@font-face {
+  font-family: 'Inter';
+  src: local('Comic Sans MS'), local('Chalkboard SE');
+}
+@font-face {
+  font-family: 'Untitled Serif';
+  src: local('Comic Sans MS'), local('Chalkboard SE');
+}`,
+  },
+];
+
+export function HostileCssPage() {
+  const [enabled, setEnabled] = useState<Record<string, boolean>>({
+    'type-selectors': true,
+    inherited: false,
+    'universal-important': false,
+    'shadow-host': false,
+    'font-face': false,
+  });
+
+  const toggle = (key: string) => {
+    setEnabled((current) => ({ ...current, [key]: !current[key] }));
+  };
+
+  return (
+    <div className="flex flex-col gap-8 p-6 md:p-12">
+      {HOSTILE_VECTORS.filter((vector) => enabled[vector.key]).map((vector) => (
+        <style key={vector.key}>{vector.css}</style>
+      ))}
+
+      <section className="rounded-lg border p-5">
+        <h1 className="text-xl font-semibold">Automatic Shadow DOM isolation POC</h1>
+        <p className="mt-2 max-w-3xl text-sm text-muted-foreground">
+          This branch automatically isolates only <code>YouVersionAuthButton</code>. The plain host
+          controls are positive witnesses: they should look broken when an attack is active, while
+          the SDK button should remain stable. The font-face option demonstrates a known Shadow DOM
+          limitation.
+        </p>
+
+        <fieldset className="mt-5 flex flex-col gap-3">
+          <legend className="mb-2 font-medium">Hostile stylesheet vectors</legend>
+          {HOSTILE_VECTORS.map((vector) => (
+            <label key={vector.key} className="flex items-start gap-3 text-sm">
+              <input
+                className="mt-1"
+                type="checkbox"
+                checked={enabled[vector.key] ?? false}
+                onChange={() => toggle(vector.key)}
+              />
+              <span>
+                <span className="font-medium">{vector.label}</span>
+                <span className="block text-muted-foreground">{vector.expectation}</span>
+              </span>
+            </label>
+          ))}
+        </fieldset>
+      </section>
+
+      <div className="hostile-zone grid gap-8 md:grid-cols-2">
+        <section className="flex flex-col gap-5 rounded-lg border border-dashed p-5">
+          <h2 className="text-sm font-semibold">LIGHT DOM — SHOULD BE AFFECTED</h2>
+          <button type="button">Plain host-app button</button>
+          <p>Plain host text for inherited-property attacks.</p>
+          <div data-host-box-witness className="rounded border p-3">
+            Host-box witness — this should disappear during the host attack.
+          </div>
+          <p style={{ fontFamily: 'Inter, sans-serif' }}>
+            Host text requesting Inter for the font-face collision.
+          </p>
+        </section>
+
+        <section className="flex flex-col gap-5 rounded-lg border p-5">
+          <h2 className="text-sm font-semibold">SDK POC — SHOULD RESIST</h2>
+          <YouVersionAuthButton
+            size="short"
+            onAuthError={(error) => console.error('Auth error:', error)}
+          />
+          <p className="text-sm text-muted-foreground">
+            Other SDK components are intentionally absent: automatic isolation has not been rolled
+            out to them on this POC branch.
+          </p>
+        </section>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/ui/src/components/YouVersionAuthButton.tsx b/packages/ui/src/components/YouVersionAuthButton.tsx
index 33c9affb..cf5de8df 100644
--- a/packages/ui/src/components/YouVersionAuthButton.tsx
+++ b/packages/ui/src/components/YouVersionAuthButton.tsx
@@ -198,7 +198,7 @@ const YouVersionAuthButtonImpl = React.forwardRef<HTMLButtonElement, YouVersionA
           data-yv-sdk
           data-yv-theme={theme}
           className={cn(
-            'yv:shadow-none yv:p-3 yv:h-auto yv:w-fit',
+            'yv:font-sans yv:shadow-none yv:p-3 yv:h-auto yv:w-fit',
             // The YV brand button is a neutral surface (white in light, dark in
             // dark) with its own text/logo color set below — pin the background
             // explicitly so it doesn't inherit the `default` variant's
@@ -236,7 +236,7 @@ const YouVersionAuthButtonImpl = React.forwardRef<HTMLButtonElement, YouVersionA
         data-yv-sdk
         data-yv-theme={theme}
         className={cn(
-          'yv:relative yv:shadow-none yv:w-fit',
+          'yv:font-sans yv:relative yv:shadow-none yv:w-fit',
           // Pin the neutral brand surface so the button doesn't inherit the
           // `default` variant's `bg-primary` (see the icon branch above).
           'yv:bg-background yv:hover:bg-background/90',

From 94c371831c6a4594ad46b8328b63a5663fcc7696 Mon Sep 17 00:00:00 2001
From: abharms <aharms@works24.com>
Date: Fri, 7 Aug 2026 11:43:33 -0500
Subject: [PATCH 03/11] docs(examples): clarify hostile CSS vectors

---
 .../vite-react/src/pages/HostileCssPage.tsx   | 38 +++++++++++++------
 1 file changed, 26 insertions(+), 12 deletions(-)

diff --git a/examples/vite-react/src/pages/HostileCssPage.tsx b/examples/vite-react/src/pages/HostileCssPage.tsx
index 35003890..4be4b364 100644
--- a/examples/vite-react/src/pages/HostileCssPage.tsx
+++ b/examples/vite-react/src/pages/HostileCssPage.tsx
@@ -5,6 +5,7 @@ interface HostileVector {
   key: string;
   label: string;
   expectation: string;
+  example: string;
   css: string;
 }
 
@@ -13,6 +14,7 @@ const HOSTILE_VECTORS: HostileVector[] = [
     key: 'type-selectors',
     label: 'Type selectors',
     expectation: 'The plain button changes; the SDK button should not.',
+    example: 'button { … }',
     css: `
 .hostile-zone button,
 .hostile-zone [role='button'] {
@@ -30,6 +32,7 @@ const HOSTILE_VECTORS: HostileVector[] = [
     key: 'inherited',
     label: 'Inherited properties',
     expectation: 'Host text changes; the SDK button should retain its typography.',
+    example: '.hostile-zone { font-family: … }',
     css: `
 .hostile-zone {
   color: #d600d6 !important;
@@ -46,6 +49,7 @@ const HOSTILE_VECTORS: HostileVector[] = [
     key: 'universal-important',
     label: 'Universal selector with !important',
     expectation: 'Every reachable host element changes; shadow internals should not.',
+    example: '* { … !important }',
     css: `
 .hostile-zone * {
   color: #d600d6 !important;
@@ -58,6 +62,7 @@ const HOSTILE_VECTORS: HostileVector[] = [
     key: 'shadow-host',
     label: 'Shadow-host box attack',
     expectation: 'The witness disappears; the SDK host should remain usable.',
+    example: '[data-yv-shadow-host] { display: none !important }',
     css: `
 .hostile-zone [data-yv-shadow-host],
 .hostile-zone [data-host-box-witness] {
@@ -72,6 +77,7 @@ const HOSTILE_VECTORS: HostileVector[] = [
     label: '@font-face family collision (known limitation)',
     expectation:
       'Registers a document-level Inter collision that can reach the shadow tree; the visible result depends on locally installed fonts.',
+    example: "@font-face { font-family: 'Inter'; … }",
     css: `
 @font-face {
   font-family: 'Inter';
@@ -115,18 +121,26 @@ export function HostileCssPage() {
         <fieldset className="mt-5 flex flex-col gap-3">
           <legend className="mb-2 font-medium">Hostile stylesheet vectors</legend>
           {HOSTILE_VECTORS.map((vector) => (
-            <label key={vector.key} className="flex items-start gap-3 text-sm">
-              <input
-                className="mt-1"
-                type="checkbox"
-                checked={enabled[vector.key] ?? false}
-                onChange={() => toggle(vector.key)}
-              />
-              <span>
-                <span className="font-medium">{vector.label}</span>
-                <span className="block text-muted-foreground">{vector.expectation}</span>
-              </span>
-            </label>
+            <div
+              key={vector.key}
+              className="flex flex-col gap-2 rounded-md border p-3 sm:flex-row sm:items-center sm:justify-between"
+            >
+              <label className="flex items-start gap-3 text-sm">
+                <input
+                  className="mt-1"
+                  type="checkbox"
+                  checked={enabled[vector.key] ?? false}
+                  onChange={() => toggle(vector.key)}
+                />
+                <span>
+                  <span className="font-medium">{vector.label}</span>
+                  <span className="block text-muted-foreground">{vector.expectation}</span>
+                </span>
+              </label>
+              <code className="w-fit max-w-full overflow-x-auto whitespace-nowrap rounded bg-muted px-2 py-1 text-xs">
+                {vector.example}
+              </code>
+            </div>
           ))}
         </fieldset>
       </section>

From 66a5774fe59dbbf4d78d9eb81d300df7c4b1c9ba Mon Sep 17 00:00:00 2001
From: abharms <aharms@works24.com>
Date: Fri, 7 Aug 2026 11:46:29 -0500
Subject: [PATCH 04/11] docs(ui): align shadow DOM prototype ADR

---
 ...05-prototype-shadow-dom-style-isolation.md | 46 ++++++++++++++++---
 1 file changed, 40 insertions(+), 6 deletions(-)

diff --git a/docs/adr/0005-prototype-shadow-dom-style-isolation.md b/docs/adr/0005-prototype-shadow-dom-style-isolation.md
index 7e7661d5..a4ec882d 100644
--- a/docs/adr/0005-prototype-shadow-dom-style-isolation.md
+++ b/docs/adr/0005-prototype-shadow-dom-style-isolation.md
@@ -11,9 +11,11 @@ layered CSS, so selector specificity alone cannot guarantee isolation.
 ## Prototype
 
 `YouVersionAuthButton` automatically creates an open shadow root and renders its
-existing implementation inside it. The SDK's compiled CSS is installed inside
-that root. Consumers continue to write `<YouVersionAuthButton />`; isolation is
-not an option they must discover or enable.
+existing implementation inside it through a React portal. The SDK's compiled
+Tailwind CSS—generated from `src/styles/global.css` and embedded as
+`__YV_STYLES__`—is installed inside that root. Consumers continue to write
+`<YouVersionAuthButton />`; isolation is not an option they must discover or
+enable.
 
 This PR intentionally applies the architecture to one representative component.
 It asks whether automatic Shadow DOM boundaries are the right foundation before
@@ -24,13 +26,36 @@ created in the top-level document cannot be adopted by a shadow root rendered in
 a same-origin iframe. Browsers without constructable stylesheets receive a
 `<style>` element in the root. The light-DOM host gets an inline-important box
 reset; an inner, unreachable wrapper resets inherited standard properties.
+Because that reset removes the light-DOM font inheritance the button previously
+relied on, the implementation now applies its intended `font-sans` utility
+explicitly.
+
+The Vite example includes a Hostile CSS page with a light-DOM positive control
+beside the isolated SDK button. It demonstrates type selectors, inherited
+properties, universal `!important` rules, direct shadow-host attacks, and a known
+document-wide `@font-face` limitation.
 
 ## What this proves
 
 - Ordinary and `!important` host selectors cannot select the button internals.
-- The consumer API is unchanged and isolation is automatic.
-- Existing click handlers and forwarded refs can cross the React portal.
+- Isolation is automatic without changing the component's React props API.
+- Existing click behavior continues to work through the React portal.
 - Strict Mode does not attach the root twice.
+- Constructed stylesheets are created per owner document, so mounting the shadow
+  host in a same-origin iframe does not cause a cross-document adoption error.
+
+The focused Chromium tests verify a global hostile `button` selector, iframe
+mounting, and existing interactions. The unit tests verify Strict Mode and the
+light-DOM host reset. The remaining hostile vectors are available for manual
+inspection on the demo page.
+
+## Compatibility impact
+
+Although the React props API is unchanged, the rendered DOM structure is not.
+Consumers that query or style internal light-DOM markup must instead account for
+the shadow root. The client-effect mount also changes first-paint and server
+rendering behavior. This is therefore represented as a breaking change rather
+than an implementation detail.
 
 ## Deliberately deferred
 
@@ -38,8 +63,17 @@ reset; an inner, unreachable wrapper resets inherited standard properties.
 - Radix popover/dialog portal placement and focus management.
 - Form association when controls live outside their form's tree scope.
 - SSR/hydration and the first client paint.
+- A package-wide custom-property audit. `all: initial` does not reset custom
+  properties; the larger investigation branch tested redeclaring Tailwind v4's
+  generated theme tokens on the protected internal wrapper.
 - Host `@font-face` rules, which are not scoped by Shadow DOM.
-- A full browser/accessibility matrix and consumer test-query migration guidance.
+- Ancestor layout constraints, which Shadow DOM cannot isolate.
+- Event retargeting, nested-root behavior, and a supported consumer customization
+  model.
+- Stylesheet construction/adoption failure recovery beyond feature fallback.
+- A full browser and assistive-technology matrix; current browser verification is
+  Chromium-focused.
+- Consumer test-query migration guidance and a component-by-component rollout.
 
 This prototype should be reviewed as an architectural checkpoint, not as a
 complete solution ready for release.

From c2ff2426c2c11d60c3668da70636f5179c57272f Mon Sep 17 00:00:00 2001
From: abharms <aharms@works24.com>
Date: Fri, 7 Aug 2026 11:59:24 -0500
Subject: [PATCH 05/11] test(ui): strengthen shadow isolation proof

---
 ...ionAuthButton.shadow-isolation.stories.tsx | 82 ++++++++++++++-----
 1 file changed, 61 insertions(+), 21 deletions(-)

diff --git a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
index 25b72cb6..ebec153c 100644
--- a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
@@ -5,6 +5,13 @@ import { expect, waitFor } from 'storybook/test';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { YouVersionAuthButton } from './YouVersionAuthButton';
 
+/**
+ * Focused architectural POC coverage. These stories answer two questions:
+ * whether a literal global `button {}` rule can change an automatically
+ * isolated SDK button, and whether the document-bound constructed stylesheet
+ * works when a shadow host mounts in a same-origin iframe. Package-wide hostile
+ * vectors and component-specific behavior are deliberately deferred.
+ */
 const HOSTILE_CSS = `
   button {
     appearance: none !important;
@@ -34,6 +41,24 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+function buttonStyleSnapshot(button: HTMLButtonElement) {
+  const styles = getComputedStyle(button);
+  return {
+    appearance: styles.appearance,
+    backgroundColor: styles.backgroundColor,
+    borderTopColor: styles.borderTopColor,
+    borderTopStyle: styles.borderTopStyle,
+    borderTopWidth: styles.borderTopWidth,
+    color: styles.color,
+    display: styles.display,
+    fontFamily: styles.fontFamily,
+    fontSize: styles.fontSize,
+    lineHeight: styles.lineHeight,
+    padding: styles.padding,
+    textTransform: styles.textTransform,
+  };
+}
+
 export const HostileGlobalButtonRule: Story = {
   tags: ['integration'],
   render: () => (
@@ -45,32 +70,45 @@ export const HostileGlobalButtonRule: Story = {
     </div>
   ),
   play: async ({ canvasElement }) => {
+    const control = await waitFor(() => {
+      const element = canvasElement.querySelector<HTMLButtonElement>(
+        '[data-testid="host-control"]',
+      );
+      if (!element) throw new Error('host control not rendered');
+      return element;
+    });
+    const host = await waitFor(() => {
+      const element = canvasElement.querySelector<HTMLElement>('[data-yv-shadow-host]');
+      if (!element?.shadowRoot) throw new Error('shadow root not attached');
+      return element;
+    });
+    const sdkButton = await waitFor(() => {
+      const element = host.shadowRoot?.querySelector<HTMLButtonElement>(
+        '[data-testid="sdk-button"]',
+      );
+      if (!element) throw new Error('SDK button not rendered');
+      return element;
+    });
+
+    const sdkBaseline = buttonStyleSnapshot(sdkButton);
+    // Guard against a false positive where an unstyled browser-default button
+    // also happens not to equal the hostile values below.
+    void expect(sdkBaseline.display).toBe('flex');
+    void expect(sdkBaseline.fontFamily).toContain('Inter');
+
     const style = document.createElement('style');
     style.textContent = HOSTILE_CSS;
-    document.head.append(style);
 
     try {
-      const control = await waitFor(() => {
-        const element = canvasElement.querySelector<HTMLElement>('[data-testid="host-control"]');
-        if (!element) throw new Error('host control not rendered');
-        return element;
-      });
-      const host = await waitFor(() => {
-        const element = canvasElement.querySelector<HTMLElement>('[data-yv-shadow-host]');
-        if (!element?.shadowRoot) throw new Error('shadow root not attached');
-        return element;
-      });
-      const sdkButton = await waitFor(() => {
-        const element = host.shadowRoot?.querySelector<HTMLElement>('[data-testid="sdk-button"]');
-        if (!element) throw new Error('SDK button not rendered');
-        return element;
-      });
+      document.head.append(style);
+
       await waitFor(() => {
         void expect(getComputedStyle(control).backgroundColor).toBe('rgb(185, 28, 28)');
       });
-      void expect(getComputedStyle(sdkButton).backgroundColor).not.toBe('rgb(185, 28, 28)');
-      void expect(getComputedStyle(sdkButton).borderTopWidth).not.toBe('10px');
-      void expect(getComputedStyle(sdkButton).fontSize).not.toBe('32px');
+
+      // The complete relevant style snapshot—not merely a few negative values—
+      // must remain identical to the pre-attack SDK baseline.
+      void expect(buttonStyleSnapshot(sdkButton)).toEqual(sdkBaseline);
     } finally {
       style.remove();
     }
@@ -97,10 +135,12 @@ export const SameOriginIframeDocument: Story = {
       );
 
       await waitFor(() => {
-        const host = iframe.contentDocument?.querySelector<HTMLElement>('[data-yv-shadow-host]');
-        const content = host?.shadowRoot?.querySelector('[data-testid="iframe-content"]');
+        const host = iframe.contentDocument?.querySelector<HTMLDivElement>('[data-yv-shadow-host]');
+        const shadowRoot = host?.shadowRoot;
+        const content = shadowRoot?.querySelector('[data-testid="iframe-content"]');
         if (!content) throw new Error('iframe shadow content not mounted');
         void expect(host?.ownerDocument).toBe(iframe.contentDocument);
+        void expect(shadowRoot?.adoptedStyleSheets).toHaveLength(1);
       });
     } finally {
       root.unmount();

From 8ec370039e6d8fa5ecde94f3bb13f6b5717b6d15 Mon Sep 17 00:00:00 2001
From: abharms <aharms@works24.com>
Date: Fri, 7 Aug 2026 12:25:06 -0500
Subject: [PATCH 06/11] refactor(ui): remove shadow isolation type assertions

---
 packages/ui/src/lib/shadow-isolation.tsx | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/packages/ui/src/lib/shadow-isolation.tsx b/packages/ui/src/lib/shadow-isolation.tsx
index 7ca16cc7..8c1492fb 100644
--- a/packages/ui/src/lib/shadow-isolation.tsx
+++ b/packages/ui/src/lib/shadow-isolation.tsx
@@ -12,14 +12,16 @@ 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) => (
-    <ShadowRootHost>
-      {createElement(Implementation, {
-        ...(props as P),
-        ref,
-      } as unknown as PropsWithoutRef<P> & RefAttributes<T>)}
-    </ShadowRootHost>
-  ));
+  const Isolated = forwardRef<T, P>((props, ref) => {
+    const implementationProps: PropsWithoutRef<P> & RefAttributes<T> = {
+      ...props,
+      ref,
+    };
+
+    return (
+      <ShadowRootHost>{createElement(Implementation, implementationProps)}</ShadowRootHost>
+    );
+  });
   Isolated.displayName = displayName;
   return Isolated;
 }

From d8b80edcbda6df0e9310cd8b47398ac63bc19721 Mon Sep 17 00:00:00 2001
From: abharms <aharms@works24.com>
Date: Fri, 7 Aug 2026 13:23:23 -0500
Subject: [PATCH 07/11] fix(ui): block hostile shadow host pseudo-elements

---
 ...05-prototype-shadow-dom-style-isolation.md |  8 ++++--
 ...ionAuthButton.shadow-isolation.stories.tsx | 16 ++++++++++-
 packages/ui/src/lib/shadow-root-host.test.tsx | 27 +++++++++++++------
 packages/ui/src/styles/global.css             | 10 +++++++
 4 files changed, 50 insertions(+), 11 deletions(-)

diff --git a/docs/adr/0005-prototype-shadow-dom-style-isolation.md b/docs/adr/0005-prototype-shadow-dom-style-isolation.md
index a4ec882d..a301a4ac 100644
--- a/docs/adr/0005-prototype-shadow-dom-style-isolation.md
+++ b/docs/adr/0005-prototype-shadow-dom-style-isolation.md
@@ -26,6 +26,9 @@ created in the top-level document cannot be adopted by a shadow root rendered in
 a same-origin iframe. Browsers without constructable stylesheets receive a
 `<style>` element in the root. The light-DOM host gets an inline-important box
 reset; an inner, unreachable wrapper resets inherited standard properties.
+The shadow stylesheet also suppresses `::before` and `::after` on the
+light-DOM host with shadow-context important declarations, preventing host-page
+CSS from injecting generated content around the isolated component.
 Because that reset removes the light-DOM font inheritance the button previously
 relied on, the implementation now applies its intended `font-sans` utility
 explicitly.
@@ -44,8 +47,9 @@ document-wide `@font-face` limitation.
 - Constructed stylesheets are created per owner document, so mounting the shadow
   host in a same-origin iframe does not cause a cross-document adoption error.
 
-The focused Chromium tests verify a global hostile `button` selector, iframe
-mounting, and existing interactions. The unit tests verify Strict Mode and the
+The focused Chromium tests verify a global hostile `button` selector, hostile
+generated content on the light-DOM host, iframe mounting, and existing
+interactions. The unit tests verify Strict Mode and the
 light-DOM host reset. The remaining hostile vectors are available for manual
 inspection on the demo page.
 
diff --git a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
index ebec153c..24d70688 100644
--- a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
@@ -22,6 +22,14 @@ const HOSTILE_CSS = `
     padding: 40px !important;
     text-transform: uppercase !important;
   }
+
+  [data-yv-shadow-host]::before,
+  [data-yv-shadow-host]::after,
+  [data-host-pseudo-control]::before {
+    content: "HOSTILE" !important;
+    display: block !important;
+    background: red !important;
+  }
 `;
 
 const meta = {
@@ -63,7 +71,7 @@ export const HostileGlobalButtonRule: Story = {
   tags: ['integration'],
   render: () => (
     <div style={{ display: 'flex', alignItems: 'center', gap: 24 }}>
-      <button type="button" data-testid="host-control">
+      <button type="button" data-testid="host-control" data-host-pseudo-control>
         Host control
       </button>
       <YouVersionAuthButton data-testid="sdk-button" />
@@ -104,8 +112,14 @@ export const HostileGlobalButtonRule: Story = {
 
       await waitFor(() => {
         void expect(getComputedStyle(control).backgroundColor).toBe('rgb(185, 28, 28)');
+        void expect(getComputedStyle(control, '::before').content).toBe('"HOSTILE"');
       });
 
+      void expect(getComputedStyle(host, '::before').content).toBe('none');
+      void expect(getComputedStyle(host, '::before').display).toBe('none');
+      void expect(getComputedStyle(host, '::after').content).toBe('none');
+      void expect(getComputedStyle(host, '::after').display).toBe('none');
+
       // The complete relevant style snapshot—not merely a few negative values—
       // must remain identical to the pre-attack SDK baseline.
       void expect(buttonStyleSnapshot(sdkButton)).toEqual(sdkBaseline);
diff --git a/packages/ui/src/lib/shadow-root-host.test.tsx b/packages/ui/src/lib/shadow-root-host.test.tsx
index e0276974..afde0335 100644
--- a/packages/ui/src/lib/shadow-root-host.test.tsx
+++ b/packages/ui/src/lib/shadow-root-host.test.tsx
@@ -5,30 +5,41 @@ import { ShadowRootHost } from './shadow-root-host';
 
 describe('ShadowRootHost', () => {
   it('attaches one shadow root under StrictMode', () => {
-    expect(() =>
-      render(
+    let container!: HTMLElement;
+    expect(() => {
+      ({ container } = render(
         <StrictMode>
           <ShadowRootHost>
             <span>content</span>
           </ShadowRootHost>
         </StrictMode>,
-      ),
-    ).not.toThrow();
+      ));
+    }).not.toThrow();
 
-    const host = document.querySelector<HTMLElement>('[data-yv-shadow-host]');
+    const host = container.querySelector<HTMLElement>('[data-yv-shadow-host]');
+    expect(host).not.toBeNull();
+    expect(host?.shadowRoot).not.toBeNull();
     expect(host?.shadowRoot?.textContent).toContain('content');
   });
 
-  it('locks the host box against host-page important rules', () => {
-    render(
+  it('applies important inline declarations to stabilize the host box', () => {
+    const { container } = render(
       <ShadowRootHost>
         <span>content</span>
       </ShadowRootHost>,
     );
 
-    const host = document.querySelector<HTMLElement>('[data-yv-shadow-host]');
+    const host = container.querySelector<HTMLElement>('[data-yv-shadow-host]');
+    expect(host).not.toBeNull();
     expect(host?.style.getPropertyValue('all')).toBe('initial');
     expect(host?.style.getPropertyValue('display')).toBe('contents');
+    expect(host?.style.getPropertyValue('writing-mode')).toBe('inherit');
+    expect(host?.style.getPropertyValue('text-orientation')).toBe('inherit');
+
+    // jsdom's cssstyle backing does not track priority for `all`,
+    // `writing-mode`, or `text-orientation` (real browsers do), so only
+    // `display` can assert getPropertyPriority here. The value-only checks
+    // above still prove the other properties were set.
     expect(host?.style.getPropertyPriority('display')).toBe('important');
   });
 });
diff --git a/packages/ui/src/styles/global.css b/packages/ui/src/styles/global.css
index 01568998..5134c60d 100644
--- a/packages/ui/src/styles/global.css
+++ b/packages/ui/src/styles/global.css
@@ -45,6 +45,16 @@ layer(yv-sdk-fonts);
 @import '@youversion/platform-core/browser/styles/bible-reader.css' layer(yv-sdk-bible-reader);
 @import 'tw-animate-css';
 
+/* The light-DOM shadow host remains selectable by the consumer page. Prevent
+   hostile host-page rules from generating content around the isolated SDK UI.
+   For !important declarations on a shadow host, the shadow-tree declaration
+   outranks an outer author declaration by design. */
+:host::before,
+:host::after {
+  content: none !important;
+  display: none !important;
+}
+
 /* Untitled Serif has no @font-face here on purpose. Its stylesheet URL needs the
    consumer's app key, which this file cannot know — it is frozen into __YV_STYLES__ at
    build time. It is loaded instead by <YvFonts /> (src/lib/yv-fonts.tsx), rendered from

From b3761bd6dbad85bd5b93c7099ff2df6e0102c346 Mon Sep 17 00:00:00 2001
From: abharms <aharms@works24.com>
Date: Fri, 7 Aug 2026 13:32:12 -0500
Subject: [PATCH 08/11] docs(ui): clarify shadow isolation trade-offs

---
 ...05-prototype-shadow-dom-style-isolation.md | 26 +++++++++++++------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/docs/adr/0005-prototype-shadow-dom-style-isolation.md b/docs/adr/0005-prototype-shadow-dom-style-isolation.md
index a301a4ac..6baa48b2 100644
--- a/docs/adr/0005-prototype-shadow-dom-style-isolation.md
+++ b/docs/adr/0005-prototype-shadow-dom-style-isolation.md
@@ -8,6 +8,12 @@ Host applications can apply unlayered global rules such as `button { ... }` or
 Tailwind v3 preflight to SDK markup. Unlayered author CSS outranks the SDK's
 layered CSS, so selector specificity alone cannot guarantee isolation.
 
+Resets, stronger selectors, `!important`, cascade layers, and `@scope` all
+continue participating in the host document's cascade. They can reduce
+accidental conflicts but cannot prevent an outside selector from matching SDK
+internals. Shadow DOM was selected because it creates a browser-enforced
+selector boundary.
+
 ## Prototype
 
 `YouVersionAuthButton` automatically creates an open shadow root and renders its
@@ -47,19 +53,20 @@ document-wide `@font-face` limitation.
 - Constructed stylesheets are created per owner document, so mounting the shadow
   host in a same-origin iframe does not cause a cross-document adoption error.
 
-The focused Chromium tests verify a global hostile `button` selector, hostile
-generated content on the light-DOM host, iframe mounting, and existing
-interactions. The unit tests verify Strict Mode and the
-light-DOM host reset. The remaining hostile vectors are available for manual
-inspection on the demo page.
+Focused Chromium stories verify hostile button rules, host-generated
+pseudo-content, existing interactions, and mounting in a same-origin iframe.
+Unit tests verify Strict Mode behavior and the inline-important host reset. The
+remaining hostile vectors are available for manual inspection on the demo page.
 
 ## Compatibility impact
 
 Although the React props API is unchanged, the rendered DOM structure is not.
 Consumers that query or style internal light-DOM markup must instead account for
-the shadow root. The client-effect mount also changes first-paint and server
-rendering behavior. This is therefore represented as a breaking change rather
-than an implementation detail.
+the shadow root. Because the prototype attaches the shadow root in `useEffect`,
+server output contains an empty host. The button appears after hydration, and
+its forwarded ref becomes available later than it did previously. This is
+therefore represented as a breaking change rather than an implementation
+detail.
 
 ## Deliberately deferred
 
@@ -70,6 +77,9 @@ than an implementation detail.
 - A package-wide custom-property audit. `all: initial` does not reset custom
   properties; the larger investigation branch tested redeclaring Tailwind v4's
   generated theme tokens on the protected internal wrapper.
+- A deliberate inheritance policy for writing direction and future custom
+  properties. Some host values may be intentional localization inputs, while
+  SDK-owned visual tokens need shadow-local defaults.
 - Host `@font-face` rules, which are not scoped by Shadow DOM.
 - Ancestor layout constraints, which Shadow DOM cannot isolate.
 - Event retargeting, nested-root behavior, and a supported consumer customization

From 8ae31a56c52970d0a8c009195a5d2451e40787e1 Mon Sep 17 00:00:00 2001
From: abharms <aharms@works24.com>
Date: Fri, 7 Aug 2026 13:40:38 -0500
Subject: [PATCH 09/11] test(ui): align shadow isolation demo conventions

---
 .../vite-react/src/pages/HostileCssPage.tsx   | 20 ++++++++++++++++
 ...ionAuthButton.shadow-isolation.stories.tsx | 24 ++++++++++++-------
 packages/ui/src/lib/shadow-root-host.tsx      |  2 +-
 3 files changed, 36 insertions(+), 10 deletions(-)

diff --git a/examples/vite-react/src/pages/HostileCssPage.tsx b/examples/vite-react/src/pages/HostileCssPage.tsx
index 4be4b364..0172ab43 100644
--- a/examples/vite-react/src/pages/HostileCssPage.tsx
+++ b/examples/vite-react/src/pages/HostileCssPage.tsx
@@ -70,6 +70,22 @@ const HOSTILE_VECTORS: HostileVector[] = [
   opacity: 0 !important;
   pointer-events: none !important;
   transform: scale(0.5) !important;
+}`,
+  },
+  {
+    key: 'host-pseudo-elements',
+    label: 'Shadow-host pseudo-elements',
+    expectation: 'The witness gains generated content; the SDK host should not.',
+    example: '[data-yv-shadow-host]::before { content: … !important }',
+    css: `
+.hostile-zone [data-yv-shadow-host]::before,
+.hostile-zone [data-yv-shadow-host]::after,
+.hostile-zone [data-host-pseudo-witness]::before {
+  content: 'HOSTILE' !important;
+  display: block !important;
+  background: #b91c1c !important;
+  color: #fff !important;
+  padding: 8px !important;
 }`,
   },
   {
@@ -96,6 +112,7 @@ export function HostileCssPage() {
     inherited: false,
     'universal-important': false,
     'shadow-host': false,
+    'host-pseudo-elements': false,
     'font-face': false,
   });
 
@@ -153,6 +170,9 @@ export function HostileCssPage() {
           <div data-host-box-witness className="rounded border p-3">
             Host-box witness — this should disappear during the host attack.
           </div>
+          <div data-host-pseudo-witness className="rounded border p-3">
+            Pseudo-element witness — generated content should appear above this text.
+          </div>
           <p style={{ fontFamily: 'Inter, sans-serif' }}>
             Host text requesting Inter for the font-face collision.
           </p>
diff --git a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
index 24d70688..95fb05bd 100644
--- a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
@@ -50,7 +50,9 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 function buttonStyleSnapshot(button: HTMLButtonElement) {
-  const styles = getComputedStyle(button);
+  const ownerWindow = button.ownerDocument.defaultView;
+  if (!ownerWindow) throw new Error('button owner window not available');
+  const styles = ownerWindow.getComputedStyle(button);
   return {
     appearance: styles.appearance,
     backgroundColor: styles.backgroundColor,
@@ -78,6 +80,10 @@ export const HostileGlobalButtonRule: Story = {
     </div>
   ),
   play: async ({ canvasElement }) => {
+    const ownerDocument = canvasElement.ownerDocument;
+    const ownerWindow = ownerDocument.defaultView;
+    if (!ownerWindow) throw new Error('story owner window not available');
+
     const control = await waitFor(() => {
       const element = canvasElement.querySelector<HTMLButtonElement>(
         '[data-testid="host-control"]',
@@ -104,21 +110,21 @@ export const HostileGlobalButtonRule: Story = {
     void expect(sdkBaseline.display).toBe('flex');
     void expect(sdkBaseline.fontFamily).toContain('Inter');
 
-    const style = document.createElement('style');
+    const style = ownerDocument.createElement('style');
     style.textContent = HOSTILE_CSS;
 
     try {
-      document.head.append(style);
+      ownerDocument.head.append(style);
 
       await waitFor(() => {
-        void expect(getComputedStyle(control).backgroundColor).toBe('rgb(185, 28, 28)');
-        void expect(getComputedStyle(control, '::before').content).toBe('"HOSTILE"');
+        void expect(ownerWindow.getComputedStyle(control).backgroundColor).toBe('rgb(185, 28, 28)');
+        void expect(ownerWindow.getComputedStyle(control, '::before').content).toBe('"HOSTILE"');
       });
 
-      void expect(getComputedStyle(host, '::before').content).toBe('none');
-      void expect(getComputedStyle(host, '::before').display).toBe('none');
-      void expect(getComputedStyle(host, '::after').content).toBe('none');
-      void expect(getComputedStyle(host, '::after').display).toBe('none');
+      void expect(ownerWindow.getComputedStyle(host, '::before').content).toBe('none');
+      void expect(ownerWindow.getComputedStyle(host, '::before').display).toBe('none');
+      void expect(ownerWindow.getComputedStyle(host, '::after').content).toBe('none');
+      void expect(ownerWindow.getComputedStyle(host, '::after').display).toBe('none');
 
       // The complete relevant style snapshot—not merely a few negative values—
       // must remain identical to the pre-attack SDK baseline.
diff --git a/packages/ui/src/lib/shadow-root-host.tsx b/packages/ui/src/lib/shadow-root-host.tsx
index b0185cfe..07763a4a 100644
--- a/packages/ui/src/lib/shadow-root-host.tsx
+++ b/packages/ui/src/lib/shadow-root-host.tsx
@@ -44,7 +44,7 @@ interface ShadowRootHostProps {
 }
 
 /** @internal Proof-of-concept primitive; not part of the public API. */
-export function ShadowRootHost({ children }: ShadowRootHostProps): React.ReactNode {
+export function ShadowRootHost({ children }: ShadowRootHostProps): ReactNode {
   const hostRef = useRef<HTMLDivElement | null>(null);
   const [shadowRoot, setShadowRoot] = useState<ShadowRoot | null>(null);
   const [needsStyleFallback, setNeedsStyleFallback] = useState(false);

From 7a311b313524fdc9a787fdc70a262531513f1848 Mon Sep 17 00:00:00 2001
From: abharms <aharms@works24.com>
Date: Fri, 7 Aug 2026 15:28:14 -0500
Subject: [PATCH 10/11] docs(examples): keep hostile demo labels readable

---
 .../vite-react/src/pages/HostileCssPage.tsx   | 34 +++++++++++--------
 1 file changed, 19 insertions(+), 15 deletions(-)

diff --git a/examples/vite-react/src/pages/HostileCssPage.tsx b/examples/vite-react/src/pages/HostileCssPage.tsx
index 0172ab43..bc8e150f 100644
--- a/examples/vite-react/src/pages/HostileCssPage.tsx
+++ b/examples/vite-react/src/pages/HostileCssPage.tsx
@@ -162,28 +162,32 @@ export function HostileCssPage() {
         </fieldset>
       </section>
 
-      <div className="hostile-zone grid gap-8 md:grid-cols-2">
+      <div className="grid gap-8 md:grid-cols-2">
         <section className="flex flex-col gap-5 rounded-lg border border-dashed p-5">
           <h2 className="text-sm font-semibold">LIGHT DOM — SHOULD BE AFFECTED</h2>
-          <button type="button">Plain host-app button</button>
-          <p>Plain host text for inherited-property attacks.</p>
-          <div data-host-box-witness className="rounded border p-3">
-            Host-box witness — this should disappear during the host attack.
-          </div>
-          <div data-host-pseudo-witness className="rounded border p-3">
-            Pseudo-element witness — generated content should appear above this text.
+          <div className="hostile-zone flex flex-col gap-5">
+            <button type="button">Plain host-app button</button>
+            <p>Plain host text for inherited-property attacks.</p>
+            <div data-host-box-witness className="rounded border p-3">
+              Host-box witness — this should disappear during the host attack.
+            </div>
+            <div data-host-pseudo-witness className="rounded border p-3">
+              Pseudo-element witness — generated content should appear above this text.
+            </div>
+            <p style={{ fontFamily: 'Inter, sans-serif' }}>
+              Host text requesting Inter for the font-face collision.
+            </p>
           </div>
-          <p style={{ fontFamily: 'Inter, sans-serif' }}>
-            Host text requesting Inter for the font-face collision.
-          </p>
         </section>
 
         <section className="flex flex-col gap-5 rounded-lg border p-5">
           <h2 className="text-sm font-semibold">SDK POC — SHOULD RESIST</h2>
-          <YouVersionAuthButton
-            size="short"
-            onAuthError={(error) => console.error('Auth error:', error)}
-          />
+          <div className="hostile-zone">
+            <YouVersionAuthButton
+              size="short"
+              onAuthError={(error) => console.error('Auth error:', error)}
+            />
+          </div>
           <p className="text-sm text-muted-foreground">
             Other SDK components are intentionally absent: automatic isolation has not been rolled
             out to them on this POC branch.

From f735fcb10f93f444050854f6b32c3520a9fcdede Mon Sep 17 00:00:00 2001
From: abharms <aharms@works24.com>
Date: Mon, 17 Aug 2026 20:42:32 -0500
Subject: [PATCH 11/11] fix(ui): use style precedence for shadow fallback
 stylesheet

Addresses PR review feedback: the non-adoptedStyleSheets fallback
rendered a bare <style> tag inside the shadow-root portal. Use
React 19's <style href precedence> resource form instead so React
hoists and de-duplicates the stylesheet within the shadow root
rather than risking duplicate insertion.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 packages/ui/src/lib/shadow-root-host.test.tsx | 18 ++++++++++++++++++
 packages/ui/src/lib/shadow-root-host.tsx      |  8 +++++++-
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/packages/ui/src/lib/shadow-root-host.test.tsx b/packages/ui/src/lib/shadow-root-host.test.tsx
index afde0335..514234e2 100644
--- a/packages/ui/src/lib/shadow-root-host.test.tsx
+++ b/packages/ui/src/lib/shadow-root-host.test.tsx
@@ -42,4 +42,22 @@ describe('ShadowRootHost', () => {
     // above still prove the other properties were set.
     expect(host?.style.getPropertyPriority('display')).toBe('important');
   });
+
+  it('gives the fallback stylesheet a stable React resource identity', () => {
+    const { container } = render(
+      <ShadowRootHost>
+        <span>content</span>
+      </ShadowRootHost>,
+    );
+
+    const style = container
+      .querySelector<HTMLElement>('[data-yv-shadow-host]')
+      ?.shadowRoot?.querySelector('style');
+
+    // jsdom does not implement constructable stylesheets, so this exercises
+    // the fallback path. React uses href + precedence to hoist and de-duplicate
+    // stylesheet resources within the shadow root.
+    expect(style?.getAttribute('data-href')).toBe('yv-sdk-shadow-styles');
+    expect(style?.getAttribute('data-precedence')).toBe('yv-sdk');
+  });
 });
diff --git a/packages/ui/src/lib/shadow-root-host.tsx b/packages/ui/src/lib/shadow-root-host.tsx
index 07763a4a..fd4b4061 100644
--- a/packages/ui/src/lib/shadow-root-host.tsx
+++ b/packages/ui/src/lib/shadow-root-host.tsx
@@ -4,6 +4,8 @@ import { createPortal } from 'react-dom';
 declare const __YV_STYLES__: string;
 
 const sdkStyleSheets = new WeakMap<Document, CSSStyleSheet>();
+const SDK_SHADOW_STYLE_HREF = 'yv-sdk-shadow-styles';
+const SDK_SHADOW_STYLE_PRECEDENCE = 'yv-sdk';
 
 function getStyleSheetConstructor(root: ShadowRoot): typeof CSSStyleSheet | undefined {
   return root.ownerDocument.defaultView?.CSSStyleSheet;
@@ -70,7 +72,11 @@ export function ShadowRootHost({ children }: ShadowRootHostProps): ReactNode {
       {shadowRoot
         ? createPortal(
             <>
-              {needsStyleFallback ? <style>{__YV_STYLES__}</style> : null}
+              {needsStyleFallback ? (
+                <style href={SDK_SHADOW_STYLE_HREF} precedence={SDK_SHADOW_STYLE_PRECEDENCE}>
+                  {__YV_STYLES__}
+                </style>
+              ) : null}
               {/* Host selectors cannot reach this reset boundary. */}
               <div style={{ all: 'initial', display: 'contents' }}>{children}</div>
             </>,