From 6cd3a16d11085c2c157c2c946366997af89bbe66 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Mon, 21 Sep 2026 07:40:47 -0500
Subject: [PATCH 01/21] test(ui): add cross-browser shadow DOM coverage

---
 .changeset/calm-browsers-test.md              |  2 +
 .github/workflows/storybook.yml               | 32 +++++++++++
 docs/shadow-dom-consumer-compatibility.md     | 27 +++++----
 docs/shadow-dom-isolation-plan.md             | 37 ++++++------
 packages/ui/package.json                      |  3 +-
 ...ionAuthButton.shadow-isolation.stories.tsx |  3 +-
 ...ersion-picker.shadow-isolation.stories.tsx | 57 +++++++++++++------
 ...compatibility.shadow-isolation.stories.tsx |  8 +--
 ...oduction-seam.shadow-isolation.stories.tsx |  8 +--
 ...adow-root-host-realistic-usage.stories.tsx |  2 +-
 ...ign-in-dialog.shadow-isolation.stories.tsx | 13 +++--
 ...ction-popover.shadow-isolation.stories.tsx |  4 +-
 packages/ui/vitest.config.ts                  | 10 +++-
 13 files changed, 138 insertions(+), 68 deletions(-)
 create mode 100644 .changeset/calm-browsers-test.md

diff --git a/.changeset/calm-browsers-test.md b/.changeset/calm-browsers-test.md
new file mode 100644
index 00000000..a845151c
--- /dev/null
+++ b/.changeset/calm-browsers-test.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/.github/workflows/storybook.yml b/.github/workflows/storybook.yml
index 56e947c3..9aa45f7f 100644
--- a/.github/workflows/storybook.yml
+++ b/.github/workflows/storybook.yml
@@ -39,3 +39,35 @@ jobs:
           YVP_APP_KEY: ${{ secrets.YVP_APP_KEY }}
           STORYBOOK_YOUVERSION_API_HOST: ${{ secrets.YVP_API_HOST }}
           STORYBOOK_YOUVERSION_APP_KEY: ${{ secrets.STORYBOOK_YOUVERSION_APP_KEY }}
+
+  shadow-browser-tests:
+    name: Shadow DOM (${{ matrix.browser }})
+    runs-on: ubuntu-latest
+    container:
+      image: mcr.microsoft.com/playwright:v1.56.1-noble
+    strategy:
+      fail-fast: false
+      matrix:
+        browser: [firefox, webkit]
+    env:
+      VITEST_BROWSER: ${{ matrix.browser }}
+      STORYBOOK_YOUVERSION_APP_KEY: ${{ secrets.STORYBOOK_YOUVERSION_APP_KEY }}
+      STORYBOOK_AUTH_REDIRECT_URL: ${{ secrets.STORYBOOK_AUTH_REDIRECT_URL }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build packages
+        run: pnpm build
+
+      - name: Run Shadow DOM browser tests
+        run: cd packages/ui && pnpm run test:shadow-browser
diff --git a/docs/shadow-dom-consumer-compatibility.md b/docs/shadow-dom-consumer-compatibility.md
index 7f356783..8c51d152 100644
--- a/docs/shadow-dom-consumer-compatibility.md
+++ b/docs/shadow-dom-consumer-compatibility.md
@@ -2,9 +2,9 @@
 
 ## Purpose
 
-This contract records the Chromium evidence for consumer-facing behavior at the
-SDK's Shadow DOM boundary. It is input to YPE-5356's production rollout policy,
-not approval for automatic isolation beyond `YouVersionAuthButton`.
+This contract records cross-browser evidence for consumer-facing behavior at
+the SDK's Shadow DOM boundary. It is input to YPE-5356's production rollout
+policy, not approval for automatic isolation beyond `YouVersionAuthButton`.
 
 The executable evidence lives in
 `consumer-compatibility.shadow-isolation.stories.tsx`. The existing
@@ -30,7 +30,7 @@ exercise. They do not establish compatibility for every SDK component.
 | --- | --- | --- |
 | A light-DOM form natively owns or serializes a control inside an SDK shadow root | Unsupported | `FormsAndExternalRelationshipsStopAtTheTreeScope` verifies that the isolated textarea has no owner form, is absent from `form.elements`, and is absent from `FormData`. A rollout target that needs form participation requires an explicit component API or separately designed form-associated host contract. |
 | A light-DOM `<label for>` labels or focuses a control inside an SDK shadow root | Unsupported | The same story verifies that `label.control` is `null` and clicking the label does not focus the isolated textarea. Put the label and control in the same tree scope or expose an explicit component labeling API. |
-| An internal control resolves light-DOM `aria-labelledby` or `aria-describedby` ID references | Unsupported | The attributes remain present, but Chromium's reflected element arrays are empty across the boundary. Keep referenced nodes in the same tree scope. This DOM evidence is not a substitute for assistive-technology testing. |
+| An internal control resolves light-DOM `aria-labelledby` or `aria-describedby` ID references | Unsupported | The attributes remain present, but reflected element arrays are empty across the boundary in Chromium, Firefox, and Playwright WebKit. Keep referenced nodes in the same tree scope. This DOM evidence is not a substitute for assistive-technology testing. |
 | A native composed event crosses one shadow boundary | Supported with native retargeting | `EventsRefsAndDomQueriesExposeDifferentConsumerViews` clicks an internal label element and verifies that a light-DOM listener receives the shadow host as `event.target`; `composedPath()` begins with the label and includes the internal button and host. Consumers must not assume an external native listener's target is the internal control. |
 | A React handler passed to `YouVersionAuthButton` receives its button event | Supported for this public component | The same story verifies that the consumer `onClick` handler receives the internal originating label as `target` and the internal button as `currentTarget`. Consumers may rely on the button current target, not on every event originating at the button itself. This is component-specific evidence, not a package-wide promise for every event prop. |
 | A forwarded `YouVersionAuthButton` ref exposes the internal button | Supported after mount | The ref resolves to the exact internal `HTMLButtonElement`. It remains `null` through the consumer's first layout effect because the shadow root attaches in a passive effect; consumers must handle callback-ref updates or read object refs after a later commit. |
@@ -38,7 +38,7 @@ exercise. They do not establish compatibility for every SDK component.
 | A consumer traverses an open root and queries after attachment | Supported with timing and access constraints | Wait for the host's open `shadowRoot`, then query within it. The contract depends on the prototype's open-root policy and does not make internals a stable semantic API; prefer public refs, roles, and component callbacks where available. |
 | An automatically isolated component is nested inside another open SDK shadow root | Supported for basic rendering, traversal, and composed events | `NestedRootsRequireTraversalAndRetargetAtEveryBoundary` verifies recursive root traversal and target retargeting to the inner host in the outer scope and to the outer host in the document scope. Consumers must traverse every root explicitly. |
 | Nested or concurrent overlays inside shadow roots | Unsupported by this contract | YPE-5355 owns stacking, focus, inertness, dismissal, and restoration. Basic nested-root evidence here does not change that overlay boundary. |
-| Shadow-local ID relationships inside `BibleVersionPicker` | Supported in current Chromium evidence | `TopLayerEscapesClippingAndPreservesSemantics` verifies that the trigger and controlled panel remain in one root and Chromium resolves their `aria-controls` relationship. This does not make cross-scope ID references supported. |
+| Shadow-local ID relationships inside `BibleVersionPicker` | Supported in current browser evidence | `TopLayerEscapesClippingAndPreservesSemantics` verifies that the trigger and controlled panel remain in one root and Chromium, Firefox, and Playwright WebKit resolve their `aria-controls` relationship. This does not make cross-scope ID references supported. |
 
 ## Consumer risks
 
@@ -52,9 +52,11 @@ An open root permits inspection and mutation by same-page JavaScript, so it is
 an automation and styling boundary rather than a security boundary. Selectors
 that depend on internal markup remain fragile even when they traverse the root.
 
-The executable suite currently runs only in Chromium. Firefox, WebKit, and real
-assistive technologies remain unverified. Chromium's reflected ARIA element
-properties demonstrate DOM relationship resolution, not announcements or other
+The focused Shadow DOM suite runs in Chromium, Firefox, and Playwright WebKit.
+All 21 automated interactions also passed a local Safari 26.6.2 run through
+SafariDriver; actual Safari is not part of continuous integration. Real
+assistive technologies remain unverified. Reflected ARIA element properties
+demonstrate DOM relationship resolution, not announcements or other
 assistive-technology behavior.
 
 ## Input for YPE-5356
@@ -73,8 +75,9 @@ must:
   default](https://playwright.dev/docs/locators#locate-in-shadow-dom), while DOM
   selector APIs need explicit traversal after root attachment and internal
   rendering;
-- define required Firefox, WebKit, and assistive-technology evidence rather than
-  treating the Chromium results as universal; and
+- preserve Firefox and WebKit coverage, define when to repeat actual-Safari
+  validation, and define required assistive-technology evidence rather than
+  treating browser DOM results as universal; and
 - preserve YPE-5355's separate ownership of nested and concurrent overlay
   behavior.
 
@@ -84,7 +87,7 @@ No production defect is fixed by this validation ticket. If a selected rollout
 component must participate in an outer native form or consume external labeling
 relationships, create a component-specific implementation ticket for an
 explicit public contract rather than relying on cross-scope browser behavior.
-Cross-browser and assistive-technology validation, consumer-facing rollout
-documentation, and any production implementation belong to YPE-5356 or
+Recurring actual-Safari and assistive-technology validation, consumer-facing
+rollout documentation, and any production implementation belong to YPE-5356 or
 separately authorized follow-up tickets. No new Jira issue is created by this
 document.
diff --git a/docs/shadow-dom-isolation-plan.md b/docs/shadow-dom-isolation-plan.md
index d7409a6b..4937025b 100644
--- a/docs/shadow-dom-isolation-plan.md
+++ b/docs/shadow-dom-isolation-plan.md
@@ -39,29 +39,30 @@ This is a working plan, not approval for package-wide rollout.
 Separate `ShadowRootHost` instances use different portal containers and tear
 those containers down independently. This provides lifecycle isolation, not
 interactive concurrency: pointer interaction in another root dismisses the
-existing peer overlay. Firefox, WebKit, and assistive-technology checks remain
-open.
+existing peer overlay. Automated Firefox and Playwright WebKit coverage now
+exercises these journeys, and all 21 automated interactions passed locally in
+Safari 26.6.2 through SafariDriver. Assistive-technology checks remain open.
 
 ## Validation matrix
 
 | Area | Evidence today | Status | Remaining work |
 | --- | --- | --- | --- |
-| Host CSS isolation | Hostile-CSS demo and focused Chromium coverage exercise element selectors, direction inheritance, vertical writing and typography resets, hostile custom properties, universal `!important` rules, host attacks, and generated pseudo-content. | Validated for the prototype | Repeat against each component selected for rollout. |
+| Host CSS isolation | Hostile-CSS demos and focused browser coverage exercise element selectors, direction inheritance, vertical writing and typography resets, hostile custom properties, universal `!important` rules, host attacks, and generated pseudo-content. | Validated in Chromium, Firefox, Playwright WebKit, and local Safari 26.6.2 | Repeat against each component selected for rollout. |
 | SSR and hydration | Focused React coverage verifies reuse of the exact empty server host, matching hydration without recoverable errors or duplicate content, and a null forwarded ref before the passive-effect mount. | Validated for the client-only prototype | Decide per rollout component whether a possibly empty first paint, layout shift, and no-JavaScript absence are acceptable. |
 | Component behavior | Auth button interaction works through the React portal; Strict Mode does not attach the root twice. | Validated for the prototype | Audit component-specific refs, events, and consumer integrations during rollout. |
-| Owner-document handling | Focused coverage mounts into a same-origin iframe and verifies document-compatible stylesheet construction. | Validated for the prototype | Verify stylesheet failure recovery. |
+| Owner-document handling | Focused coverage mounts into a same-origin iframe and verifies document-compatible stylesheet construction. | Validated in Chromium, Firefox, Playwright WebKit, and local Safari 26.6.2 | Verify stylesheet failure recovery. |
 | Inline floating content | The picker negative control preserves tree-scope relationships but demonstrates clipping beyond a constrained ancestor. | Validated as a negative control | None; clipping is why inline placement is not the selected escaping strategy. |
-| Native top-layer floating content | Picker stories verify clipping escape, hit testing, collision handling, hostile-CSS isolation, and resolved `aria-controls` relationships. | Validated in Chromium | Expand browser and assistive-technology coverage. |
+| Native top-layer floating content | Picker stories verify clipping escape, hit testing, collision handling, hostile-CSS isolation, and resolved `aria-controls` relationships. | Validated in Chromium, Firefox, Playwright WebKit, and local Safari 26.6.2 | Verify assistive-technology behavior and repeat actual-Safari checks for significant platform changes. |
 | Portal lifecycle | Unit and browser coverage exercise lazy creation, exit-animation retention, cleanup, immediate reopen behavior, and the direct-Radix `VerseActionPopover` consumer. | Validated for shared primitives and the known bypass | Repeat the consumer audit when adding another direct overlay primitive. |
-| Dialog relationships | Chromium resolves title and description relationships inside the component tree. | Validated in Chromium | Verify announcements with real assistive technology. |
-| Dialog keyboard containment | Browser coverage exercises initial focus, programmatic escape redirection, forward and reverse traversal, radio-group collapsing, negative `tabindex`, and wraparound. | Validated in Chromium | Expand the browser and assistive-technology matrix. |
-| Dialog modal lifetime | Coverage verifies inert background content while open and through staggered Content and Overlay exit animations. YPE-5355 also exercises both unmount orders for overlapping popover and dialog exits. | Validated for order-independent teardown | YPE-5356 owns peer concurrency across component roots and final focus-restoration gaps. Expand browser and assistive-technology coverage. |
-| Dialog dismissal and restoration | Coverage exercises Escape, backdrop click, full-viewport hit testing, overlay-only focus, and restoration after both modal nodes unmount. | Validated in Chromium | Verify real screen-reader and cross-browser behavior. |
-| Consumer form participation | Chromium coverage verifies that a light-DOM form does not own or serialize a native control inside an SDK shadow root. | Unsupported across tree scopes | Use an explicit component contract if a rollout target requires outer-form participation. |
-| Consumer labels and ARIA ID references | Chromium coverage verifies that external native labels, `aria-labelledby`, and `aria-describedby` relationships do not resolve to controls inside the root. | Unsupported across tree scopes | Keep relationships in one tree scope; verify real assistive technology separately. |
+| Dialog relationships | Browser coverage resolves title and description relationships inside the component tree. | Validated in Chromium, Firefox, Playwright WebKit, and local Safari 26.6.2 | Verify announcements with real assistive technology. |
+| Dialog keyboard containment | Browser coverage exercises initial focus, programmatic escape redirection, forward and reverse traversal, radio-group collapsing, negative `tabindex`, and wraparound. | Validated in Chromium, Firefox, Playwright WebKit, and local Safari 26.6.2 | Verify assistive-technology behavior and repeat actual-Safari checks for significant platform changes. |
+| Dialog modal lifetime | Coverage verifies inert background content while open and through staggered Content and Overlay exit animations. YPE-5355 also exercises both unmount orders for overlapping popover and dialog exits. | Validated for order-independent teardown | YPE-5356 owns peer concurrency across component roots and final focus-restoration gaps. Verify assistive-technology behavior and repeat actual-Safari checks for significant platform changes. |
+| Dialog dismissal and restoration | Coverage exercises Escape, backdrop click, full-viewport hit testing, overlay-only focus, and restoration after both modal nodes unmount. | Validated in Chromium, Firefox, Playwright WebKit, and local Safari 26.6.2 | Verify real screen-reader behavior and repeat actual-Safari checks for significant platform changes. |
+| Consumer form participation | Browser coverage verifies that a light-DOM form does not own or serialize a native control inside an SDK shadow root. | Unsupported across tree scopes | Use an explicit component contract if a rollout target requires outer-form participation. |
+| Consumer labels and ARIA ID references | Browser coverage verifies that external native labels, `aria-labelledby`, and `aria-describedby` relationships do not resolve to controls inside the root. | Unsupported across tree scopes | Keep relationships in one tree scope; verify real assistive technology separately. |
 | Consumer events, refs, and automation | Coverage verifies native retargeting, the auth button's React handler and forwarded ref, open-root queries, and effect-driven attachment timing. | Supported with documented constraints | Repeat for each public component selected for rollout. |
 | Nested shadow roots | Coverage verifies basic rendering, recursive queries, and event retargeting at each boundary. | Supported for the validated basics | Nested and concurrent overlay ownership remains with YPE-5355. |
-| Realistic same-page usage | YPE-5437 mounts, removes, and re-adds a 12-component mix in Normal and Strict Mode. Chromium coverage verifies exact host counts, rendered scripture content, and one shared stylesheet object across roots and remounts. A production-build comparison found a small warm-run mount-cost difference on one machine. | No shared-host blocker found | Repeat user-visible performance and compatibility checks for each component selected for rollout. |
+| Realistic same-page usage | YPE-5437 mounts, removes, and re-adds a 12-component mix in Normal and Strict Mode. Chromium, Firefox, Playwright WebKit, and local Safari 26.6.2 coverage verifies exact host counts, rendered scripture content, and one shared stylesheet object across roots and remounts. A production-build comparison found a small warm-run mount-cost difference on one machine. | No shared-host blocker found | Repeat user-visible performance and compatibility checks for each component selected for rollout. |
 
 ## Direct overlay inventory
 
@@ -89,7 +90,7 @@ decision. YPE-5356 owns whether and how to implement that coordination.
   shipping nested and concurrent overlays (YPE-5356). The decision must consider
   trigger-time peer dismissal as well as overlay order and restore targets;
   ADR 0007 records the gaps but does not select a coordination design.
-  Cross-browser and assistive-technology coverage still remain.
+  Recurring actual-Safari and assistive-technology coverage still remain.
 - Keep the YPE-5400 custom-property contract and compiled-stylesheet prevention
   guard green as component styles change. The audit below closes the known
   ambient dependency; `all: initial` still does not reset custom properties.
@@ -148,7 +149,8 @@ separately in YPE-5749.
 - Apply the [Shadow DOM consumer compatibility contract](shadow-dom-consumer-compatibility.md)
   to every proposed rollout component. Native outer-form participation and
   external `label`, `aria-labelledby`, and `aria-describedby` relationships are
-  unsupported across tree scopes in the current Chromium evidence.
+  unsupported across tree scopes in current Chromium, Firefox, and Playwright
+  WebKit evidence.
 - Preserve `direction` as the only intentional inherited CSS property. Vertical
   writing modes, text orientation, inherited host typography, and undeclared
   host custom properties are not supported customization inputs. The prototype
@@ -179,9 +181,10 @@ separately in YPE-5749.
   constraining the component host or its ancestors.
 - Open shadow roots prevent CSS selector crossover; they do not prevent
   same-page JavaScript from inspecting or mutating the root.
-- Browser automation currently focuses on Chromium. Firefox and WebKit remain
-  to be evaluated.
-- Chromium DOM relationship reflection is not a substitute for VoiceOver, NVDA,
+- The focused Shadow DOM browser suite runs in Chromium, Firefox, and Playwright
+  WebKit. Playwright WebKit is not a substitute for testing actual Safari; all
+  21 automated interactions also passed a local Safari 26.6.2 SafariDriver run.
+- Browser DOM relationship reflection is not a substitute for VoiceOver, NVDA,
   or other real assistive-technology verification.
 
 ## Research handoff and completion gate
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 170e4ac4..1e0a941e 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -48,7 +48,8 @@
     "prepublishOnly": "YVP_PUBLISH_BUILD=true pnpm --filter @youversion/platform-core build && pnpm build && node ../../scripts/check-sdk-version-stamp.mjs core",
     "storybook": "pnpm build:css && pnpm build:storybook-css && concurrently \"node scripts/generate-i18n-resources.mjs --watch\" \"tailwindcss -i src/styles/chrome.css -o dist/chrome.css --watch\" \"tailwindcss -i src/styles/global.css -o dist/tailwind.css --watch\" \"tailwindcss -i src/styles/reader.css -o dist/bible-reader.css --watch\" \"node scripts/write-public-styles.js --watch\" \"storybook dev -p 6006\"",
     "build-storybook": "pnpm generate:i18n && pnpm build:css && pnpm build:storybook-css && storybook build",
-    "test:integration": "vitest run"
+    "test:integration": "vitest run",
+    "test:shadow-browser": "VITEST_STORY_TAG=shadow-dom vitest run --project storybook"
   },
   "dependencies": {
     "@radix-ui/react-accordion": "1.2.12",
diff --git a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
index 2a3c5fd1..4bbf145c 100644
--- a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
@@ -35,6 +35,7 @@ const HOSTILE_CSS = `
 const meta = {
   title: 'Spikes/Automatic Shadow DOM isolation',
   component: YouVersionAuthButton,
+  tags: ['integration', 'shadow-dom'],
   parameters: {
     msw: {
       handlers: [
@@ -70,7 +71,6 @@ function buttonStyleSnapshot(button: HTMLButtonElement) {
 }
 
 export const HostileGlobalButtonRule: Story = {
-  tags: ['integration'],
   render: () => (
     <div style={{ display: 'flex', alignItems: 'center', gap: 24 }}>
       <button type="button" data-testid="host-control" data-host-pseudo-control>
@@ -136,7 +136,6 @@ export const HostileGlobalButtonRule: Story = {
 };
 
 export const SameOriginIframeDocument: Story = {
-  tags: ['integration'],
   parameters: { includeAuth: false },
   render: () => <iframe data-testid="iframe" title="same-origin isolation target" />,
   play: async ({ canvasElement }) => {
diff --git a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
index d44153a7..f94d4dd8 100644
--- a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
@@ -1,7 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { YouVersionProvider as HooksYouVersionProvider } from '@youversion/platform-react-hooks';
 import { http, HttpResponse } from 'msw';
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { expect, userEvent, waitFor, within } from 'storybook/test';
 import { ShadowRootHost } from '../lib/shadow-root-host';
@@ -53,14 +53,14 @@ function TwoPickersInOneIsland(): React.ReactNode {
 }
 
 function SameOriginIframeHarness(): React.ReactNode {
-  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const [iframeDocument, setIframeDocument] = useState<Document | null>(null);
   const [container, setContainer] = useState<HTMLElement | null>(null);
 
   useEffect(() => {
-    const iframeDocument = iframeRef.current?.contentDocument;
     if (!iframeDocument) return;
 
     const portalContainer = iframeDocument.createElement('div');
+    portalContainer.setAttribute('data-testid', 'iframe-portal-container');
     portalContainer.style.setProperty('display', 'grid');
     portalContainer.style.setProperty('min-block-size', '100vh');
     portalContainer.style.setProperty('place-items', 'center');
@@ -68,15 +68,16 @@ function SameOriginIframeHarness(): React.ReactNode {
     setContainer(portalContainer);
 
     return () => portalContainer.remove();
-  }, []);
+  }, [iframeDocument]);
 
   return (
     <>
       <iframe
-        ref={iframeRef}
         data-testid="iframe"
+        srcDoc="<!doctype html><html><head></head><body></body></html>"
         title="same-origin picker target"
         style={{ inlineSize: 800, blockSize: 600 }}
+        onLoad={(event) => setIframeDocument(event.currentTarget.contentDocument)}
       />
       {container
         ? createPortal(
@@ -93,7 +94,7 @@ function SameOriginIframeHarness(): React.ReactNode {
 const meta = {
   title: 'Spikes/BibleVersionPicker Shadow DOM isolation',
   component: IsolatedBibleVersionPicker,
-  tags: ['integration'],
+  tags: ['integration', 'shadow-dom'],
   parameters: {
     layout: 'centered',
     msw: {
@@ -220,11 +221,11 @@ export const TopLayerEscapesClippingAndPreservesSemantics: Story = {
     const hit = root.elementFromPoint(sampleX, sampleY);
     void expect(hit === panel || (hit !== null && panel.contains(hit))).toBe(true);
 
-    // SAFETY: Chromium exposes this reflected-ARIA draft property; the guard below verifies it.
+    // SAFETY: The reflected-ARIA property is still a draft; verify browser support before use.
     const reflectedControls = (
       trigger as HTMLElement & { ariaControlsElements?: readonly Element[] }
     ).ariaControlsElements;
-    if (!reflectedControls) throw new Error('Chromium did not expose ariaControlsElements');
+    if (!reflectedControls) throw new Error('browser did not expose ariaControlsElements');
     void expect(trigger.getAttribute('aria-controls')).toBe(panel.id);
     void expect(reflectedControls).toEqual([panel]);
   },
@@ -312,15 +313,23 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
     </div>
   ),
   play: async ({ canvasElement }) => {
-    const outsideControl = canvasElement.querySelector<HTMLButtonElement>(
+    const outsideControl = await waitForElement<HTMLButtonElement>(
+      canvasElement,
       '[data-testid="outside-control"]',
+      'outside control not rendered',
     );
-    if (!outsideControl) throw new Error('outside control not rendered');
     const { root, trigger, topLayer, panel } = await openPicker(canvasElement);
     await waitFor(() => {
       const focused = root.activeElement;
       void expect(focused !== null && panel.contains(focused)).toBe(true);
     });
+    const exitAnimationStyle = canvasElement.ownerDocument.createElement('style');
+    exitAnimationStyle.textContent = `
+      [data-slot='popover-content'][data-state='closed'] {
+        animation-duration: 400ms !important;
+      }
+    `;
+    root.append(exitAnimationStyle);
 
     const baseline = styleSnapshot(panel);
     const hostileStyle = canvasElement.ownerDocument.createElement('style');
@@ -387,11 +396,12 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
   },
 };
 
-export const DirectionOnlyInheritanceRejectsHostVisualValues: Story = {
+export const ProviderDirectionRejectsHostVisualValues: Story = {
+  globals: { interfaceDirection: 'rtl' },
   render: () => (
     <div
       data-testid="hostile-inheritance-container"
-      dir="rtl"
+      dir="ltr"
       style={{ display: 'flex', alignItems: 'center', gap: 24 }}
     >
       <span data-testid="hostile-inheritance-control">Host control</span>
@@ -409,6 +419,7 @@ export const DirectionOnlyInheritanceRejectsHostVisualValues: Story = {
     if (!hostControl) throw new Error('hostile inheritance control not rendered');
 
     const { root, trigger, panel } = await openPicker(canvasElement);
+    await waitFor(() => void expect(trigger).toHaveTextContent('NIV'));
     const wrapper = root.querySelector<HTMLElement>('[data-yv-shadow-content-wrapper]');
     const heading = panel.querySelector<HTMLElement>('h2');
     const inputGroup = panel.querySelector<HTMLElement>('[data-slot="input-group"]');
@@ -420,9 +431,9 @@ export const DirectionOnlyInheritanceRejectsHostVisualValues: Story = {
     const headingTypography = typographySnapshot(heading, ownerWindow);
     void expect(headingTypography.fontFamily).toContain('Inter');
     void expect(ownerWindow.getComputedStyle(trigger).direction).toBe('rtl');
-    void expect(ownerWindow.getComputedStyle(wrapper).direction).toBe('rtl');
+    void expect(ownerWindow.getComputedStyle(wrapper).direction).toBe('ltr');
 
-    await userEvent.click(within(panel).getByRole('button', { name: /select language/i }));
+    await userEvent.click(within(panel).getByRole('button', { name: /select a language/i }));
     const languageTabs = await waitForElement<HTMLElement>(
       panel,
       '[data-slot="tabs-list"]',
@@ -481,7 +492,7 @@ export const DirectionOnlyInheritanceRejectsHostVisualValues: Story = {
       const wrapperStyle = ownerWindow.getComputedStyle(wrapper);
       const headingStyle = ownerWindow.getComputedStyle(heading);
       const panelStyle = ownerWindow.getComputedStyle(panel);
-      void expect(wrapperStyle.direction).toBe('rtl');
+      void expect(wrapperStyle.direction).toBe('ltr');
       void expect(wrapperStyle.writingMode).toBe('horizontal-tb');
       void expect(wrapperStyle.textOrientation).toBe('mixed');
       void expect(headingStyle.direction).toBe('rtl');
@@ -695,9 +706,19 @@ export const PanelTracksAncestorScrollAndVersionListScrollsInternally: Story = {
 export const SameOriginIframeTopLayerRemainsInteractive: Story = {
   render: () => <SameOriginIframeHarness />,
   play: async ({ canvasElement }) => {
-    const iframe = canvasElement.querySelector<HTMLIFrameElement>('[data-testid="iframe"]');
-    if (!iframe?.contentDocument) throw new Error('same-origin iframe document not available');
-    const componentRoot = await getComponentRoot(iframe.contentDocument);
+    const { iframe, iframeDocument } = await waitFor(() => {
+      const currentIframe =
+        canvasElement.querySelector<HTMLIFrameElement>('[data-testid="iframe"]');
+      const currentDocument = currentIframe?.contentDocument;
+      if (!currentIframe || !currentDocument) {
+        throw new Error('same-origin iframe document not available');
+      }
+      if (!currentDocument.querySelector('[data-testid="iframe-portal-container"]')) {
+        throw new Error('same-origin iframe portal container not mounted');
+      }
+      return { iframe: currentIframe, iframeDocument: currentDocument };
+    });
+    const componentRoot = await getComponentRoot(iframeDocument);
     const trigger = await getTrigger(componentRoot);
     await userEvent.click(trigger);
     const topLayer = await waitForElement<HTMLElement>(
diff --git a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
index 2c6a6b95..0c476bf0 100644
--- a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
@@ -9,7 +9,7 @@ import { YouVersionAuthButton } from './YouVersionAuthButton';
 
 const meta = {
   title: 'Spikes/Shadow DOM consumer compatibility',
-  tags: ['integration'],
+  tags: ['integration', 'shadow-dom'],
   parameters: {
     layout: 'padded',
     msw: {
@@ -204,13 +204,13 @@ export const FormsAndExternalRelationshipsStopAtTheTreeScope: Story = {
       ariaLabelledByElements?: readonly Element[];
       ariaDescribedByElements?: readonly Element[];
     };
-    // SAFETY: The optional extension models Chromium properties, and the guards below verify them.
+    // SAFETY: The optional extension models draft reflected-ARIA properties; verify before use.
     const reflectedTextarea = textarea as ReflectedAriaElement;
     if (!reflectedTextarea.ariaLabelledByElements) {
-      throw new Error('Chromium did not expose ariaLabelledByElements');
+      throw new Error('browser did not expose ariaLabelledByElements');
     }
     if (!reflectedTextarea.ariaDescribedByElements) {
-      throw new Error('Chromium did not expose ariaDescribedByElements');
+      throw new Error('browser did not expose ariaDescribedByElements');
     }
 
     void expect(textarea.getAttribute('aria-labelledby')).toBe('external-name');
diff --git a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
index 446a955b..9470361a 100644
--- a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
@@ -387,7 +387,7 @@ export const RapidCloseReopenDuringExit = manualWorkflow(
 
 /** YPE-5355 stable regression evidence; unsupported observations remain in the decision docs. */
 export const PopoverOpensDialogEvidence: Story = {
-  tags: ['!dev'],
+  tags: ['!dev', 'shadow-dom'],
   play: async ({ canvasElement, step }) => {
     const { contentWrapper, root } = await getPrimaryHarness(canvasElement);
     const priorControl = await waitForElement<HTMLButtonElement>(
@@ -531,7 +531,7 @@ export const PopoverOpensDialogEvidence: Story = {
 };
 
 export const DialogContainsPopoverEvidence: Story = {
-  tags: ['!dev'],
+  tags: ['!dev', 'shadow-dom'],
   play: async ({ canvasElement, step }) => {
     const { contentWrapper, root } = await getPrimaryHarness(canvasElement);
     const openNotes = await waitForElement<HTMLButtonElement>(
@@ -611,7 +611,7 @@ export const DialogContainsPopoverEvidence: Story = {
 
 /** YPE-5355 stable regression evidence; peer-dismissal observations remain in the docs. */
 export const TwoIndependentOverlaysEvidence: Story = {
-  tags: ['!dev'],
+  tags: ['!dev', 'shadow-dom'],
   play: async ({ canvasElement, step }) => {
     const { contentWrapper, primaryIsland, root } = await getPrimaryHarness(canvasElement);
     const verse = await waitForElement<HTMLElement>(
@@ -703,7 +703,7 @@ export const TwoIndependentOverlaysEvidence: Story = {
 
 /** YPE-5355 stable regression evidence; final-focus observations remain in the docs. */
 export const RapidCloseReopenDuringExitEvidence: Story = {
-  tags: ['!dev'],
+  tags: ['!dev', 'shadow-dom'],
   args: { enableRapidReopen: true },
   play: async ({ canvasElement, step }) => {
     const { contentWrapper, root } = await getPrimaryHarness(canvasElement);
diff --git a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
index ed4914d6..8090a903 100644
--- a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
+++ b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
@@ -29,7 +29,7 @@ const EXPECTED_COMPONENT_IDS = [
 
 const meta = {
   title: 'Spikes/Shadow DOM realistic usage',
-  tags: ['integration'],
+  tags: ['integration', 'shadow-dom'],
   parameters: {
     includeAuth: false,
     layout: 'fullscreen',
diff --git a/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx b/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
index 2a3353ba..802ece52 100644
--- a/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
@@ -38,7 +38,7 @@ function SignInDialogHarness(): React.ReactNode {
 const meta = {
   title: 'Spikes/SignInDialog Shadow DOM isolation',
   component: SignInDialogHarness,
-  tags: ['integration'],
+  tags: ['integration', 'shadow-dom'],
   parameters: {
     layout: 'centered',
     msw: {
@@ -99,8 +99,11 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
       [data-slot='dialog-overlay'][data-state='closed'] { animation-duration: 800ms !important; }
     `;
     root.append(exitAnimationStyle);
-    const insideControl = root.querySelector<HTMLButtonElement>('[data-testid="inside-control"]');
-    if (!insideControl) throw new Error('inside-island control not rendered');
+    const insideControl = await waitFor(() => {
+      const element = root.querySelector<HTMLButtonElement>('[data-testid="inside-control"]');
+      if (!element) throw new Error('inside-island control not rendered');
+      return element;
+    });
     void expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
     insideControl.focus();
     await userEvent.click(insideControl);
@@ -126,13 +129,13 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     const description = root.getElementById(descriptionId!);
     void expect(title).not.toBeNull();
     void expect(description).not.toBeNull();
-    // SAFETY: This Chromium-only story checks that both reflected properties exist before use.
+    // SAFETY: These reflected-ARIA properties are still a draft; verify support before use.
     const reflectedDialog = dialog as HTMLElement & {
       ariaLabelledByElements?: readonly Element[];
       ariaDescribedByElements?: readonly Element[];
     };
     if (!reflectedDialog.ariaLabelledByElements || !reflectedDialog.ariaDescribedByElements) {
-      throw new Error('Chromium did not expose the dialog ARIA element relationships');
+      throw new Error('browser did not expose the dialog ARIA element relationships');
     }
     void expect(reflectedDialog.ariaLabelledByElements).toEqual([title]);
     void expect(reflectedDialog.ariaDescribedByElements).toEqual([description]);
diff --git a/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx b/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
index fedc9146..b99a7edd 100644
--- a/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
@@ -126,7 +126,7 @@ function IsolatedVerseActionPopover(): React.ReactNode {
 const meta = {
   title: 'Spikes/VerseActionPopover Shadow DOM isolation',
   component: IsolatedVerseActionPopover,
-  tags: ['integration'],
+  tags: ['integration', 'shadow-dom'],
   parameters: {
     layout: 'centered',
     msw: {
@@ -250,7 +250,7 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
     readerScrollRoot.scrollTop = 0;
     await waitFor(() => {
       const returnedRect = dialog.getBoundingClientRect();
-      void expect(Math.abs(returnedRect.left - firstDialogRect.left)).toBeLessThan(8);
+      void expect(Math.abs(returnedRect.left - firstDialogRect.left)).toBeLessThan(12);
       void expect(Math.abs(returnedRect.top - firstDialogRect.top)).toBeLessThan(12);
     });
 
diff --git a/packages/ui/vitest.config.ts b/packages/ui/vitest.config.ts
index 55302887..06f50e23 100644
--- a/packages/ui/vitest.config.ts
+++ b/packages/ui/vitest.config.ts
@@ -7,6 +7,12 @@ import { fileURLToPath } from 'node:url';
 
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 
+const browserName = process.env.VITEST_BROWSER ?? 'chromium';
+if (!['chromium', 'firefox', 'webkit'].includes(browserName)) {
+  throw new Error(`Unsupported VITEST_BROWSER: ${browserName}`);
+}
+const storyTag = process.env.VITEST_STORY_TAG ?? 'integration';
+
 export default defineConfig({
   plugins: [react()],
   test: {
@@ -51,7 +57,7 @@ export default defineConfig({
             // This should match your package.json script to run Storybook
             // The --ci flag will skip prompts and not open a browser
             storybookScript: 'pnpm storybook --no-open',
-            tags: { include: ['integration'] },
+            tags: { include: [storyTag] },
           }),
         ],
         test: {
@@ -65,7 +71,7 @@ export default defineConfig({
             // Make sure to install Playwright
             provider: playwright(),
             headless: true,
-            instances: [{ browser: 'chromium' }],
+            instances: [{ browser: browserName as 'chromium' | 'firefox' | 'webkit' }],
           },
           setupFiles: ['./.storybook/vitest.setup.ts'],
         },

From 846872d4bb9287f3179b53a85d9e2b1372e9c564 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 08:28:49 -0500
Subject: [PATCH 02/21] test(ui): stabilize Firefox story readiness

---
 ...umer-compatibility.shadow-isolation.stories.tsx | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
index 0c476bf0..cd699932 100644
--- a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
@@ -172,12 +172,14 @@ export const FormsAndExternalRelationshipsStopAtTheTreeScope: Story = {
   name: 'External relationships stop at the shadow boundary',
   render: () => <FormRelationshipsHarness />,
   play: async ({ canvasElement }) => {
-    const form = await waitFor(() =>
-      requireElement<HTMLFormElement>(
-        canvasElement,
-        '[data-testid="consumer-form"]',
-        'consumer form not rendered',
-      ),
+    const form = await waitFor(
+      () =>
+        requireElement<HTMLFormElement>(
+          canvasElement,
+          '[data-testid="consumer-form"]',
+          'consumer form not rendered',
+        ),
+      { timeout: 5_000 },
     );
     const label = requireElement<HTMLLabelElement>(
       canvasElement,

From cae444479dd64db1042d05883c94e38de365f4c7 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 10:01:54 -0500
Subject: [PATCH 03/21] fix(ci): stabilize shadow browser jobs

---
 .github/workflows/storybook.yml                             | 2 ++
 ...dow-overlay-production-seam.shadow-isolation.stories.tsx | 6 +++---
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/storybook.yml b/.github/workflows/storybook.yml
index 9aa45f7f..3f1b5a71 100644
--- a/.github/workflows/storybook.yml
+++ b/.github/workflows/storybook.yml
@@ -71,3 +71,5 @@ jobs:
 
       - name: Run Shadow DOM browser tests
         run: cd packages/ui && pnpm run test:shadow-browser
+        env:
+          HOME: /root
diff --git a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
index 6c6b80f9..de989e87 100644
--- a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
@@ -429,7 +429,7 @@ export const PopoverOpensDialogEvidence: Story = {
         await waitFor(() => {
           const focused = root.activeElement;
           void expect(focused !== null && permissionDialog.contains(focused)).toBe(true);
-        });
+        }, productionWaitOptions);
         void expect(contentWrapper.inert).toBe(true);
         void expect(opened.versePopover).toHaveAttribute('data-state', 'open');
       });
@@ -442,13 +442,13 @@ export const PopoverOpensDialogEvidence: Story = {
           void expect(contentWrapper.inert).toBe(false);
           const focused = root.activeElement;
           void expect(focused !== null && versePopover.contains(focused)).toBe(true);
-        });
+        }, productionWaitOptions);
         await userEvent.keyboard('{Escape}');
         await waitFor(() => {
           void expect(topLayer.querySelector('[data-slot="verse-action-popover"]')).toBeNull();
           void expect(topLayer.matches(':popover-open')).toBe(false);
           void expect(root.activeElement).toBe(priorControl);
-        });
+        }, productionWaitOptions);
       });
 
       await step('Keep modal ownership when the popover exits first', async () => {

From 201d13474e3f013f103acb6b9811d90dcc492aeb Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 10:13:04 -0500
Subject: [PATCH 04/21] test(ui): make overlay exit ordering deterministic

---
 ...oduction-seam.shadow-isolation.stories.tsx | 108 +++++++++++-------
 1 file changed, 64 insertions(+), 44 deletions(-)

diff --git a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
index de989e87..e4ada187 100644
--- a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
@@ -290,6 +290,10 @@ function installUnequalExitDurations(
   return style;
 }
 
+function finishAnimations(element: HTMLElement): void {
+  for (const animation of element.getAnimations()) animation.finish();
+}
+
 interface PrimaryHarness {
   contentWrapper: HTMLElement;
   primaryIsland: HTMLElement;
@@ -454,33 +458,41 @@ export const PopoverOpensDialogEvidence: Story = {
       await step('Keep modal ownership when the popover exits first', async () => {
         exitAnimationStyles.push(
           installUnequalExitDurations(root, {
-            dialog: 400,
-            overlay: 800,
-            popover: 180,
+            dialog: 40_000,
+            overlay: 50_000,
+            popover: 30_000,
           }),
         );
         const opened = await openVerseActionPopover(root, verse);
-        await openPermissionDialogFromVerseAction(opened.topLayer, opened.versePopover);
-        closeAllOverlays.click();
-        closeAllOverlays.click();
-        await waitFor(
-          () => {
-            void expect(
-              opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
-            ).toBeNull();
-            void expect(getPermissionDialog(opened.topLayer)).not.toBeNull();
-            void expect(contentWrapper.inert).toBe(true);
-          },
-          { timeout: 2_000 },
+        const permissionDialog = await openPermissionDialogFromVerseAction(
+          opened.topLayer,
+          opened.versePopover,
         );
-        await waitFor(
-          () => {
-            void expect(getPermissionDialog(opened.topLayer)).toBeNull();
-            void expect(contentWrapper.inert).toBe(false);
-            void expect(opened.topLayer.matches(':popover-open')).toBe(false);
-          },
-          { timeout: 2_000 },
+        const dialogOverlay = opened.topLayer.querySelector<HTMLElement>(
+          '[data-slot="dialog-overlay"]',
         );
+        if (!dialogOverlay) throw new Error('dialog overlay not rendered');
+        closeAllOverlays.click();
+        closeAllOverlays.click();
+        await waitFor(() => {
+          void expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
+          void expect(permissionDialog).toHaveAttribute('data-state', 'closed');
+        }, productionWaitOptions);
+        finishAnimations(opened.versePopover);
+        await waitFor(() => {
+          void expect(
+            opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
+          ).toBeNull();
+          void expect(getPermissionDialog(opened.topLayer)).toBe(permissionDialog);
+          void expect(contentWrapper.inert).toBe(true);
+        }, productionWaitOptions);
+        finishAnimations(permissionDialog);
+        finishAnimations(dialogOverlay);
+        await waitFor(() => {
+          void expect(getPermissionDialog(opened.topLayer)).toBeNull();
+          void expect(contentWrapper.inert).toBe(false);
+          void expect(opened.topLayer.matches(':popover-open')).toBe(false);
+        }, productionWaitOptions);
         void expect(closeAllRequests.getAttribute('data-count')).toBe('2');
       });
 
@@ -488,33 +500,41 @@ export const PopoverOpensDialogEvidence: Story = {
         exitAnimationStyles.at(-1)?.remove();
         exitAnimationStyles.push(
           installUnequalExitDurations(root, {
-            dialog: 120,
-            overlay: 160,
-            popover: 800,
+            dialog: 30_000,
+            overlay: 40_000,
+            popover: 50_000,
           }),
         );
         const opened = await openVerseActionPopover(root, verse);
-        await openPermissionDialogFromVerseAction(opened.topLayer, opened.versePopover);
-        closeAllOverlays.click();
-        await waitFor(
-          () => {
-            void expect(getPermissionDialog(opened.topLayer)).toBeNull();
-            void expect(
-              opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
-            ).not.toBeNull();
-          },
-          { timeout: 2_000 },
+        const permissionDialog = await openPermissionDialogFromVerseAction(
+          opened.topLayer,
+          opened.versePopover,
         );
-        await waitFor(
-          () => {
-            void expect(
-              opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
-            ).toBeNull();
-            void expect(contentWrapper.inert).toBe(false);
-            void expect(opened.topLayer.matches(':popover-open')).toBe(false);
-          },
-          { timeout: 2_000 },
+        const dialogOverlay = opened.topLayer.querySelector<HTMLElement>(
+          '[data-slot="dialog-overlay"]',
         );
+        if (!dialogOverlay) throw new Error('dialog overlay not rendered');
+        closeAllOverlays.click();
+        await waitFor(() => {
+          void expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
+          void expect(permissionDialog).toHaveAttribute('data-state', 'closed');
+        }, productionWaitOptions);
+        finishAnimations(permissionDialog);
+        finishAnimations(dialogOverlay);
+        await waitFor(() => {
+          void expect(getPermissionDialog(opened.topLayer)).toBeNull();
+          void expect(
+            opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
+          ).not.toBeNull();
+        }, productionWaitOptions);
+        finishAnimations(opened.versePopover);
+        await waitFor(() => {
+          void expect(
+            opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
+          ).toBeNull();
+          void expect(contentWrapper.inert).toBe(false);
+          void expect(opened.topLayer.matches(':popover-open')).toBe(false);
+        }, productionWaitOptions);
         void expect(closeAllRequests.getAttribute('data-count')).toBe('3');
       });
     } finally {

From 648102be437cb423a0616ced80fb0c43d89dee8b Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 10:50:01 -0500
Subject: [PATCH 05/21] test(ui): await Storybook assertions

---
 ...ionAuthButton.shadow-isolation.stories.tsx |  46 +--
 ...ersion-picker.shadow-isolation.stories.tsx | 204 ++++++-------
 ...compatibility.shadow-isolation.stories.tsx |  60 ++--
 ...oduction-seam.shadow-isolation.stories.tsx | 278 +++++++++---------
 ...adow-root-host-realistic-usage.stories.tsx |  56 ++--
 ...ign-in-dialog.shadow-isolation.stories.tsx | 146 ++++-----
 ...ction-popover.shadow-isolation.stories.tsx |  80 ++---
 7 files changed, 443 insertions(+), 427 deletions(-)

diff --git a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
index b8f815d3..d32704c3 100644
--- a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
@@ -99,7 +99,7 @@ export const HostileGlobalButtonRule: Story = {
       'shadow host not rendered',
       browserWaitOptions,
     );
-    const shadowRoot = await waitFor(() => {
+    const shadowRoot = await waitFor(async () => {
       if (!host.shadowRoot) throw new Error('shadow root not attached');
       return host.shadowRoot;
     }, browserWaitOptions);
@@ -113,8 +113,8 @@ export const HostileGlobalButtonRule: Story = {
     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');
+    await expect(sdkBaseline.display).toBe('flex');
+    await expect(sdkBaseline.fontFamily).toContain('Inter');
 
     const style = ownerDocument.createElement('style');
     style.textContent = HOSTILE_CSS;
@@ -122,19 +122,21 @@ export const HostileGlobalButtonRule: Story = {
     try {
       ownerDocument.head.append(style);
 
-      await waitFor(() => {
-        void expect(ownerWindow.getComputedStyle(control).backgroundColor).toBe('rgb(185, 28, 28)');
-        void expect(ownerWindow.getComputedStyle(control, '::before').content).toBe('"HOSTILE"');
+      await waitFor(async () => {
+        await expect(ownerWindow.getComputedStyle(control).backgroundColor).toBe(
+          'rgb(185, 28, 28)',
+        );
+        await expect(ownerWindow.getComputedStyle(control, '::before').content).toBe('"HOSTILE"');
       });
 
-      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');
+      await expect(ownerWindow.getComputedStyle(host, '::before').content).toBe('none');
+      await expect(ownerWindow.getComputedStyle(host, '::before').display).toBe('none');
+      await expect(ownerWindow.getComputedStyle(host, '::after').content).toBe('none');
+      await 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.
-      void expect(buttonStyleSnapshot(sdkButton)).toEqual(sdkBaseline);
+      await expect(buttonStyleSnapshot(sdkButton)).toEqual(sdkBaseline);
     } finally {
       style.remove();
     }
@@ -151,7 +153,7 @@ export const SameOriginIframeDocument: Story = {
       'same-origin iframe not rendered',
       browserWaitOptions,
     );
-    const { iframeDocument, iframeWindow } = await waitFor(() => {
+    const { iframeDocument, iframeWindow } = await waitFor(async () => {
       const currentDocument = iframe.contentDocument;
       const currentWindow = currentDocument?.defaultView;
       if (!currentDocument?.body || !currentWindow) {
@@ -175,15 +177,15 @@ export const SameOriginIframeDocument: Story = {
         </ShadowRootHost>,
       );
 
-      await waitFor(() => {
+      await waitFor(async () => {
         const host = container.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(iframeDocument);
-        void expect(shadowRoot?.adoptedStyleSheets).toHaveLength(1);
-        void expect(shadowRoot?.adoptedStyleSheets[0]).toBeInstanceOf(iframeWindow.CSSStyleSheet);
-        void expect(iframeWindow.getComputedStyle(content).display).toBe('flex');
+        await expect(host?.ownerDocument).toBe(iframeDocument);
+        await expect(shadowRoot?.adoptedStyleSheets).toHaveLength(1);
+        await expect(shadowRoot?.adoptedStyleSheets[0]).toBeInstanceOf(iframeWindow.CSSStyleSheet);
+        await expect(iframeWindow.getComputedStyle(content).display).toBe('flex');
       }, browserWaitOptions);
 
       const styleSheetPrototype = iframeWindow.CSSStyleSheet.prototype;
@@ -208,17 +210,17 @@ export const SameOriginIframeDocument: Story = {
           </ShadowRootHost>,
         );
 
-        await waitFor(() => {
+        await waitFor(async () => {
           const fallbackHost =
             fallbackContainer?.querySelector<HTMLDivElement>('[data-yv-shadow-host]');
           const shadowRoot = fallbackHost?.shadowRoot;
           const content = shadowRoot?.querySelector('[data-testid="iframe-fallback-content"]');
           const style = shadowRoot?.querySelector('style');
           if (!content || !style) throw new Error('iframe fallback content not mounted');
-          void expect(shadowRoot?.adoptedStyleSheets).toHaveLength(0);
-          void expect(style.getAttribute('data-href')).toBe('yv-sdk-shadow-styles');
-          void expect(style.getAttribute('data-precedence')).toBe('yv-sdk');
-          void expect(iframeWindow.getComputedStyle(content).display).toBe('flex');
+          await expect(shadowRoot?.adoptedStyleSheets).toHaveLength(0);
+          await expect(style.getAttribute('data-href')).toBe('yv-sdk-shadow-styles');
+          await expect(style.getAttribute('data-precedence')).toBe('yv-sdk');
+          await expect(iframeWindow.getComputedStyle(content).display).toBe('flex');
         }, browserWaitOptions);
       } finally {
         fallbackRoot?.unmount();
diff --git a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
index 71beaef6..dad198f0 100644
--- a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
@@ -118,7 +118,7 @@ async function getTrigger(root: ShadowRoot): Promise<HTMLElement> {
 async function openPicker(container: ParentNode) {
   const root = await waitForShadowRoot(container);
   const trigger = await getTrigger(root);
-  void expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+  await expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
   await userEvent.click(trigger);
   const topLayer = await waitForElement<HTMLElement>(
     root,
@@ -130,7 +130,7 @@ async function openPicker(container: ParentNode) {
     '[data-slot="popover-content"]',
     'picker panel not rendered in local top layer',
   );
-  await waitFor(() => void expect(topLayer.matches(':popover-open')).toBe(true));
+  await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(true));
   return { root, trigger, topLayer, panel };
 }
 
@@ -183,35 +183,35 @@ export const TopLayerEscapesClippingAndPreservesSemantics: Story = {
     );
     const { root, trigger, topLayer, panel } = await openPicker(clippingContainer);
 
-    void expect(topLayer.getRootNode()).toBe(root);
-    void expect(panel.getRootNode()).toBe(root);
-    void expect(
+    await expect(topLayer.getRootNode()).toBe(root);
+    await expect(panel.getRootNode()).toBe(root);
+    await expect(
       canvasElement.ownerDocument.body.querySelector('[data-yv-shadow-overlay-host]'),
     ).toBeNull();
 
     const clippingRect = clippingContainer.getBoundingClientRect();
     const panelRect = panel.getBoundingClientRect();
-    void expect(panelRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
+    await expect(panelRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
     const viewport = canvasElement.ownerDocument.defaultView;
     if (!viewport) throw new Error('story window not available');
-    void expect(panelRect.top).toBeGreaterThanOrEqual(16);
-    void expect(panelRect.left).toBeGreaterThanOrEqual(16);
-    void expect(panelRect.bottom).toBeLessThanOrEqual(viewport.innerHeight - 16);
-    void expect(panelRect.right).toBeLessThanOrEqual(viewport.innerWidth - 16);
+    await expect(panelRect.top).toBeGreaterThanOrEqual(16);
+    await expect(panelRect.left).toBeGreaterThanOrEqual(16);
+    await expect(panelRect.bottom).toBeLessThanOrEqual(viewport.innerHeight - 16);
+    await expect(panelRect.right).toBeLessThanOrEqual(viewport.innerWidth - 16);
 
     const sampleX = panelRect.left + panelRect.width / 2;
     const sampleY = Math.max(panelRect.top + 2, clippingRect.bottom + 2);
     if (sampleY >= panelRect.bottom) throw new Error('panel did not extend beyond its ancestor');
     const hit = root.elementFromPoint(sampleX, sampleY);
-    void expect(hit === panel || (hit !== null && panel.contains(hit))).toBe(true);
+    await expect(hit === panel || (hit !== null && panel.contains(hit))).toBe(true);
 
     // SAFETY: The reflected-ARIA property is still a draft; verify browser support before use.
     const reflectedControls = (
       trigger as HTMLElement & { ariaControlsElements?: readonly Element[] }
     ).ariaControlsElements;
     if (!reflectedControls) throw new Error('browser did not expose ariaControlsElements');
-    void expect(trigger.getAttribute('aria-controls')).toBe(panel.id);
-    void expect(reflectedControls).toEqual([panel]);
+    await expect(trigger.getAttribute('aria-controls')).toBe(panel.id);
+    await expect(reflectedControls).toEqual([panel]);
   },
 };
 
@@ -250,7 +250,7 @@ export const InlineControlIsClippedByItsAncestor: Story = {
       'clipping container not rendered',
     );
     const root = await waitForShadowRoot(clippingContainer);
-    void expect(root.querySelector('[data-yv-shadow-inline-overlay]')).toBeNull();
+    await expect(root.querySelector('[data-yv-shadow-inline-overlay]')).toBeNull();
     await userEvent.click(await getTrigger(root));
     const inlineContainer = await waitForElement<HTMLElement>(
       root,
@@ -265,14 +265,14 @@ export const InlineControlIsClippedByItsAncestor: Story = {
 
     const clippingRect = clippingContainer.getBoundingClientRect();
     const panelRect = panel.getBoundingClientRect();
-    void expect(panelRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
+    await expect(panelRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
     const sampleX = panelRect.left + panelRect.width / 2;
     const visibleSampleY = Math.max(panelRect.top + 2, clippingRect.top + 2);
     if (visibleSampleY >= clippingRect.bottom) {
       throw new Error('panel has no visible area inside its clipping ancestor');
     }
     const visibleHit = root.elementFromPoint(sampleX, visibleSampleY);
-    void expect(visibleHit === panel || (visibleHit !== null && panel.contains(visibleHit))).toBe(
+    await expect(visibleHit === panel || (visibleHit !== null && panel.contains(visibleHit))).toBe(
       true,
     );
 
@@ -281,7 +281,7 @@ export const InlineControlIsClippedByItsAncestor: Story = {
       throw new Error('panel did not extend beyond its clipping ancestor');
     }
     const clippedHit = root.elementFromPoint(sampleX, clippedSampleY);
-    void expect(clippedHit === panel || (clippedHit !== null && panel.contains(clippedHit))).toBe(
+    await expect(clippedHit === panel || (clippedHit !== null && panel.contains(clippedHit))).toBe(
       false,
     );
   },
@@ -303,9 +303,9 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
       'outside control not rendered',
     );
     const { root, trigger, topLayer, panel } = await openPicker(canvasElement);
-    await waitFor(() => {
+    await waitFor(async () => {
       const focused = root.activeElement;
-      void expect(focused !== null && panel.contains(focused)).toBe(true);
+      await expect(focused !== null && panel.contains(focused)).toBe(true);
     });
     const exitAnimationStyle = canvasElement.ownerDocument.createElement('style');
     exitAnimationStyle.textContent = `
@@ -330,23 +330,23 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
     try {
       canvasElement.ownerDocument.head.append(hostileStyle);
       await waitFor(
-        () =>
-          void expect(getComputedStyle(outsideControl).backgroundColor).toBe('rgb(185, 28, 28)'),
+        async () =>
+          await expect(getComputedStyle(outsideControl).backgroundColor).toBe('rgb(185, 28, 28)'),
       );
-      void expect(styleSnapshot(panel)).toEqual(baseline);
+      await expect(styleSnapshot(panel)).toEqual(baseline);
     } finally {
       hostileStyle.remove();
     }
 
     await userEvent.click(outsideControl);
-    await waitFor(() => {
-      void expect(panel).toHaveAttribute('data-state', 'closed');
-      void expect(topLayer).toContainElement(panel);
-      void expect(topLayer.matches(':popover-open')).toBe(true);
+    await waitFor(async () => {
+      await expect(panel).toHaveAttribute('data-state', 'closed');
+      await expect(topLayer).toContainElement(panel);
+      await expect(topLayer.matches(':popover-open')).toBe(true);
     });
-    await waitFor(() => {
-      void expect(topLayer.querySelector('[data-slot="popover-content"]')).toBeNull();
-      void expect(topLayer.matches(':popover-open')).toBe(false);
+    await waitFor(async () => {
+      await expect(topLayer.querySelector('[data-slot="popover-content"]')).toBeNull();
+      await expect(topLayer.matches(':popover-open')).toBe(false);
     });
 
     await userEvent.click(trigger);
@@ -355,9 +355,9 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
       '[data-slot="popover-content"]',
       'picker panel did not reopen',
     );
-    await waitFor(() => {
+    await waitFor(async () => {
       const activeElement = root.activeElement;
-      void expect(activeElement !== null && reopenedPanel.contains(activeElement)).toBe(true);
+      await expect(activeElement !== null && reopenedPanel.contains(activeElement)).toBe(true);
     });
 
     const focused = root.activeElement;
@@ -366,16 +366,16 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
       new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, composed: true }),
     );
     trigger.click();
-    await waitFor(() => {
-      void expect(topLayer.matches(':popover-open')).toBe(true);
-      void expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
+    await waitFor(async () => {
+      await expect(topLayer.matches(':popover-open')).toBe(true);
+      await expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
     });
 
     await userEvent.keyboard('{Escape}');
-    await waitFor(() => {
-      void expect(topLayer.querySelector('[data-slot="popover-content"]')).toBeNull();
-      void expect(topLayer.matches(':popover-open')).toBe(false);
-      void expect(root.activeElement).toBe(trigger);
+    await waitFor(async () => {
+      await expect(topLayer.querySelector('[data-slot="popover-content"]')).toBeNull();
+      await expect(topLayer.matches(':popover-open')).toBe(false);
+      await expect(root.activeElement).toBe(trigger);
     });
   },
 };
@@ -403,7 +403,7 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
     if (!hostControl) throw new Error('hostile inheritance control not rendered');
 
     const { root, trigger, panel } = await openPicker(canvasElement);
-    await waitFor(() => void expect(trigger).toHaveTextContent('NIV'));
+    await waitFor(async () => await expect(trigger).toHaveTextContent('NIV'));
     const wrapper = root.querySelector<HTMLElement>('[data-yv-shadow-content-wrapper]');
     const heading = panel.querySelector<HTMLElement>('h2');
     const inputGroup = panel.querySelector<HTMLElement>('[data-slot="input-group"]');
@@ -413,9 +413,9 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
     const panelGeometry = geometrySnapshot(panel);
     const inputGeometry = geometrySnapshot(inputGroup);
     const headingTypography = typographySnapshot(heading, ownerWindow);
-    void expect(headingTypography.fontFamily).toContain('Inter');
-    void expect(ownerWindow.getComputedStyle(trigger).direction).toBe('rtl');
-    void expect(ownerWindow.getComputedStyle(wrapper).direction).toBe('ltr');
+    await expect(headingTypography.fontFamily).toContain('Inter');
+    await expect(ownerWindow.getComputedStyle(trigger).direction).toBe('rtl');
+    await expect(ownerWindow.getComputedStyle(wrapper).direction).toBe('ltr');
 
     await userEvent.click(within(panel).getByRole('button', { name: /select a language/i }));
     const languageTabs = await waitForElement<HTMLElement>(
@@ -433,8 +433,8 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
     }
     const languageTabsInlineSize = languageTabs.offsetWidth;
     const languageInputRadius = ownerWindow.getComputedStyle(languageInputGroup).borderRadius;
-    void expect(languageTabsInlineSize).toBe(languageTabsContainer.clientWidth - 32);
-    void expect(languageInputRadius).toBe('30px');
+    await expect(languageTabsInlineSize).toBe(languageTabsContainer.clientWidth - 32);
+    await expect(languageInputRadius).toBe('30px');
 
     const hostileStyle = ownerDocument.createElement('style');
     hostileStyle.textContent = `
@@ -460,39 +460,39 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
 
     try {
       ownerDocument.head.append(hostileStyle);
-      await waitFor(() => {
+      await waitFor(async () => {
         const controlStyle = ownerWindow.getComputedStyle(hostControl);
-        void expect(controlStyle.writingMode).toBe('vertical-rl');
-        void expect(controlStyle.textOrientation).toBe('upright');
-        void expect(controlStyle.color).toBe('rgb(185, 28, 28)');
-        void expect(controlStyle.fontFamily).toContain('fantasy');
-        void expect(controlStyle.fontSize).toBe('32px');
-        void expect(controlStyle.letterSpacing).toBe('16px');
-        void expect(controlStyle.lineHeight).toBe('96px');
-        void expect(controlStyle.wordSpacing).toBe('32px');
-        void expect(controlStyle.borderRadius).toBe('0px');
+        await expect(controlStyle.writingMode).toBe('vertical-rl');
+        await expect(controlStyle.textOrientation).toBe('upright');
+        await expect(controlStyle.color).toBe('rgb(185, 28, 28)');
+        await expect(controlStyle.fontFamily).toContain('fantasy');
+        await expect(controlStyle.fontSize).toBe('32px');
+        await expect(controlStyle.letterSpacing).toBe('16px');
+        await expect(controlStyle.lineHeight).toBe('96px');
+        await expect(controlStyle.wordSpacing).toBe('32px');
+        await expect(controlStyle.borderRadius).toBe('0px');
       });
 
       const wrapperStyle = ownerWindow.getComputedStyle(wrapper);
       const headingStyle = ownerWindow.getComputedStyle(heading);
       const panelStyle = ownerWindow.getComputedStyle(panel);
-      void expect(wrapperStyle.direction).toBe('ltr');
-      void expect(wrapperStyle.writingMode).toBe('horizontal-tb');
-      void expect(wrapperStyle.textOrientation).toBe('mixed');
-      void expect(headingStyle.direction).toBe('rtl');
-      void expect(headingStyle.writingMode).toBe('horizontal-tb');
-      void expect(headingStyle.textOrientation).toBe('mixed');
-      void expect(typographySnapshot(heading, ownerWindow)).toEqual(headingTypography);
-      void expect(panelStyle.getPropertyValue('--yv-spacing').trim()).toBe('.25rem');
-      void expect(panelStyle.getPropertyValue('--spacing').trim()).toBe('.25rem');
-      void expect(panelStyle.getPropertyValue('--yv-radius').trim()).toBe('2rem');
-      void expect(languageTabs.offsetWidth).toBe(languageTabsInlineSize);
-      void expect(ownerWindow.getComputedStyle(languageInputGroup).borderRadius).toBe(
+      await expect(wrapperStyle.direction).toBe('ltr');
+      await expect(wrapperStyle.writingMode).toBe('horizontal-tb');
+      await expect(wrapperStyle.textOrientation).toBe('mixed');
+      await expect(headingStyle.direction).toBe('rtl');
+      await expect(headingStyle.writingMode).toBe('horizontal-tb');
+      await expect(headingStyle.textOrientation).toBe('mixed');
+      await expect(typographySnapshot(heading, ownerWindow)).toEqual(headingTypography);
+      await expect(panelStyle.getPropertyValue('--yv-spacing').trim()).toBe('.25rem');
+      await expect(panelStyle.getPropertyValue('--spacing').trim()).toBe('.25rem');
+      await expect(panelStyle.getPropertyValue('--yv-radius').trim()).toBe('2rem');
+      await expect(languageTabs.offsetWidth).toBe(languageTabsInlineSize);
+      await expect(ownerWindow.getComputedStyle(languageInputGroup).borderRadius).toBe(
         languageInputRadius,
       );
-      void expect(geometrySnapshot(trigger)).toEqual(triggerGeometry);
-      void expect(geometrySnapshot(panel)).toEqual(panelGeometry);
-      void expect(geometrySnapshot(inputGroup)).toEqual(inputGeometry);
+      await expect(geometrySnapshot(trigger)).toEqual(triggerGeometry);
+      await expect(geometrySnapshot(panel)).toEqual(panelGeometry);
+      await expect(geometrySnapshot(inputGroup)).toEqual(inputGeometry);
     } finally {
       hostileStyle.remove();
     }
@@ -516,8 +516,8 @@ export const MultiplePickersCreateIndependentLazyContainers: Story = {
     if (!first || !second) throw new Error('picker harness not rendered');
     const firstRoot = await waitForShadowRoot(first);
     const secondRoot = await waitForShadowRoot(second);
-    void expect(firstRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
-    void expect(secondRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    await expect(firstRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    await expect(secondRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
 
     const firstTrigger = await getTrigger(firstRoot);
     const secondTrigger = await getTrigger(secondRoot);
@@ -527,7 +527,7 @@ export const MultiplePickersCreateIndependentLazyContainers: Story = {
       '[data-yv-shadow-local-overlay]',
       'first local container not created',
     );
-    void expect(secondRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    await expect(secondRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
 
     await userEvent.click(secondTrigger);
     const secondTopLayer = await waitForElement<HTMLElement>(
@@ -535,10 +535,12 @@ export const MultiplePickersCreateIndependentLazyContainers: Story = {
       '[data-yv-shadow-local-overlay]',
       'second local container not created',
     );
-    await waitFor(() => {
-      void expect(firstTopLayer.matches(':popover-open')).toBe(false);
-      void expect(secondTopLayer.matches(':popover-open')).toBe(true);
-      void expect(secondTopLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
+    await waitFor(async () => {
+      await expect(firstTopLayer.matches(':popover-open')).toBe(false);
+      await expect(secondTopLayer.matches(':popover-open')).toBe(true);
+      await expect(secondTopLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(
+        1,
+      );
     });
   },
 };
@@ -550,10 +552,10 @@ export const MultiplePopoversShareOneIslandContainer: Story = {
     const triggers = Array.from(
       root.querySelectorAll<HTMLElement>('[data-slot="popover-trigger"]'),
     );
-    void expect(triggers).toHaveLength(2);
+    await expect(triggers).toHaveLength(2);
     const [firstTrigger, secondTrigger] = triggers;
     if (!firstTrigger || !secondTrigger) throw new Error('picker triggers not rendered');
-    void expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    await expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
 
     await userEvent.click(firstTrigger);
     const topLayer = await waitForElement<HTMLElement>(
@@ -561,18 +563,18 @@ export const MultiplePopoversShareOneIslandContainer: Story = {
       '[data-yv-shadow-local-overlay]',
       'shared island container not created',
     );
-    await waitFor(() => {
-      void expect(firstTrigger).toHaveAttribute('aria-expanded', 'true');
-      void expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
+    await waitFor(async () => {
+      await expect(firstTrigger).toHaveAttribute('aria-expanded', 'true');
+      await expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
     });
 
     await userEvent.click(secondTrigger);
-    await waitFor(() => {
-      void expect(firstTrigger).toHaveAttribute('aria-expanded', 'false');
-      void expect(secondTrigger).toHaveAttribute('aria-expanded', 'true');
-      void expect(topLayer.matches(':popover-open')).toBe(true);
-      void expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
-      void expect(root.querySelectorAll('[data-yv-shadow-local-overlay]')).toHaveLength(1);
+    await waitFor(async () => {
+      await expect(firstTrigger).toHaveAttribute('aria-expanded', 'false');
+      await expect(secondTrigger).toHaveAttribute('aria-expanded', 'true');
+      await expect(topLayer.matches(':popover-open')).toBe(true);
+      await expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
+      await expect(root.querySelectorAll('[data-yv-shadow-local-overlay]')).toHaveLength(1);
     });
 
     const panel = topLayer.querySelector<HTMLElement>('[data-slot="popover-content"]');
@@ -580,8 +582,8 @@ export const MultiplePopoversShareOneIslandContainer: Story = {
     const panelRect = panel.getBoundingClientRect();
     const viewport = canvasElement.ownerDocument.defaultView;
     if (!viewport) throw new Error('story window not available');
-    void expect(panelRect.top).toBeGreaterThanOrEqual(16);
-    void expect(panelRect.bottom).toBeLessThanOrEqual(viewport.innerHeight - 16);
+    await expect(panelRect.top).toBeGreaterThanOrEqual(16);
+    await expect(panelRect.bottom).toBeLessThanOrEqual(viewport.innerHeight - 16);
   },
 };
 
@@ -634,16 +636,16 @@ export const PanelTracksAncestorScrollAndVersionListScrollsInternally: Story = {
     scrollAncestor.scrollTop += scrollDelta;
     scrollAncestor.dispatchEvent(new Event('scroll', { bubbles: true }));
 
-    await waitFor(() => {
+    await waitFor(async () => {
       const triggerRectAfter = trigger.getBoundingClientRect();
-      void expect(
+      await expect(
         Math.abs(triggerRectAfter.top - (triggerRectBefore.top - scrollDelta)),
       ).toBeLessThan(2);
     });
     const triggerRectAfter = trigger.getBoundingClientRect();
     const panelRectAfter = panel.getBoundingClientRect();
     const offsetAfter = panelRectAfter.top - triggerRectAfter.bottom;
-    void expect(Math.abs(offsetAfter - offsetBefore)).toBeLessThanOrEqual(8);
+    await expect(Math.abs(offsetAfter - offsetBefore)).toBeLessThanOrEqual(8);
 
     // Part 2: the version list scrolls internally within the panel. Locate
     // the scroll region via the unconditional "All Versions" marker's
@@ -674,8 +676,8 @@ export const PanelTracksAncestorScrollAndVersionListScrollsInternally: Story = {
     scrollRegion.scrollTop = scrollRegion.scrollHeight;
     scrollRegion.dispatchEvent(new Event('scroll', { bubbles: true }));
 
-    await waitFor(() => {
-      void expect(scrollRegion.scrollTop).toBeGreaterThan(initialScrollTop);
+    await waitFor(async () => {
+      await expect(scrollRegion.scrollTop).toBeGreaterThan(initialScrollTop);
     });
 
     const lastItemRect = lastItem.getBoundingClientRect();
@@ -683,14 +685,14 @@ export const PanelTracksAncestorScrollAndVersionListScrollsInternally: Story = {
       lastItemRect.left + lastItemRect.width / 2,
       lastItemRect.top + lastItemRect.height / 2,
     );
-    void expect(hit === lastItem || (hit !== null && lastItem.contains(hit))).toBe(true);
+    await expect(hit === lastItem || (hit !== null && lastItem.contains(hit))).toBe(true);
   },
 };
 
 export const SameOriginIframeTopLayerRemainsInteractive: Story = {
   render: () => <SameOriginIframeHarness />,
   play: async ({ canvasElement }) => {
-    const { iframe, iframeDocument } = await waitFor(() => {
+    const { iframe, iframeDocument } = await waitFor(async () => {
       const currentIframe =
         canvasElement.querySelector<HTMLIFrameElement>('[data-testid="iframe"]');
       const currentDocument = currentIframe?.contentDocument;
@@ -710,7 +712,7 @@ export const SameOriginIframeTopLayerRemainsInteractive: Story = {
       '[data-yv-shadow-local-overlay]',
       'iframe top-layer container not created',
     );
-    const portalWrapper = await waitFor(() => {
+    const portalWrapper = await waitFor(async () => {
       const element = topLayer.firstElementChild;
       // SAFETY: A same-origin iframe exposes its realm's HTMLElement constructor on its Window.
       const frameWindow = iframe.contentWindow as
@@ -723,7 +725,7 @@ export const SameOriginIframeTopLayerRemainsInteractive: Story = {
     });
     const portalWindow = portalWrapper.ownerDocument.defaultView;
     if (!portalWindow) throw new Error('iframe portal window not available');
-    void expect(portalWindow.getComputedStyle(portalWrapper).pointerEvents).toBe('auto');
+    await expect(portalWindow.getComputedStyle(portalWrapper).pointerEvents).toBe('auto');
 
     const input = await waitForElement<HTMLInputElement>(
       topLayer,
@@ -731,14 +733,14 @@ export const SameOriginIframeTopLayerRemainsInteractive: Story = {
       'iframe picker input not rendered',
     );
     await userEvent.click(input);
-    void expect(componentRoot.activeElement).toBe(input);
+    await expect(componentRoot.activeElement).toBe(input);
 
     const panel = topLayer.querySelector<HTMLElement>('[data-slot="popover-content"]');
     if (!panel) throw new Error('iframe picker panel not rendered');
     const panelRect = panel.getBoundingClientRect();
     const frameWindow = iframe.contentWindow;
     if (!frameWindow) throw new Error('iframe window not available');
-    void expect(panelRect.top).toBeGreaterThanOrEqual(16);
-    void expect(panelRect.bottom).toBeLessThanOrEqual(frameWindow.innerHeight - 16);
+    await expect(panelRect.top).toBeGreaterThanOrEqual(16);
+    await expect(panelRect.bottom).toBeLessThanOrEqual(frameWindow.innerHeight - 16);
   },
 };
diff --git a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
index b6112698..c2351473 100644
--- a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
@@ -37,7 +37,7 @@ function requireElement<ElementType extends Element>(
 }
 
 async function requireShadowHost(container: ParentNode): Promise<HTMLElement> {
-  return waitFor(() => {
+  return waitFor(async () => {
     const host = requireElement<HTMLElement>(
       container,
       '[data-yv-shadow-host]',
@@ -187,13 +187,13 @@ export const FormsAndExternalRelationshipsStopAtTheTreeScope: Story = {
       'isolated textarea not rendered',
     );
 
-    void expect(textarea.form).toBeNull();
-    void expect(form.elements.namedItem('notes')).toBeNull();
-    void expect(new FormData(form).has('notes')).toBe(false);
+    await expect(textarea.form).toBeNull();
+    await expect(form.elements.namedItem('notes')).toBeNull();
+    await expect(new FormData(form).has('notes')).toBe(false);
 
-    void expect(label.control).toBeNull();
+    await expect(label.control).toBeNull();
     await userEvent.click(label);
-    void expect(root.activeElement).not.toBe(textarea);
+    await expect(root.activeElement).not.toBe(textarea);
 
     type ReflectedAriaElement = HTMLElement & {
       ariaLabelledByElements?: readonly Element[];
@@ -208,10 +208,10 @@ export const FormsAndExternalRelationshipsStopAtTheTreeScope: Story = {
       throw new Error('browser did not expose ariaDescribedByElements');
     }
 
-    void expect(textarea.getAttribute('aria-labelledby')).toBe('external-name');
-    void expect(textarea.getAttribute('aria-describedby')).toBe('external-description');
-    void expect(reflectedTextarea.ariaLabelledByElements).toEqual([]);
-    void expect(reflectedTextarea.ariaDescribedByElements).toEqual([]);
+    await expect(textarea.getAttribute('aria-labelledby')).toBe('external-name');
+    await expect(textarea.getAttribute('aria-describedby')).toBe('external-description');
+    await expect(reflectedTextarea.ariaLabelledByElements).toEqual([]);
+    await expect(reflectedTextarea.ariaDescribedByElements).toEqual([]);
   },
 };
 
@@ -278,7 +278,7 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
   name: 'Events, refs, and DOM queries expose different views',
   render: () => <AutomaticButtonHarness />,
   play: async ({ canvasElement }) => {
-    const observer = await waitFor(() =>
+    const observer = await waitFor(async () =>
       requireElement<HTMLElement>(
         canvasElement,
         '[data-testid="consumer-observer"]',
@@ -293,8 +293,8 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
       'isolated auth button not rendered',
     );
 
-    void expect(canvasElement.querySelector('[data-testid="isolated-auth-button"]')).toBeNull();
-    void expect(root.querySelector('[data-testid="isolated-auth-button"]')).toBe(button);
+    await expect(canvasElement.querySelector('[data-testid="isolated-auth-button"]')).toBeNull();
+    await expect(root.querySelector('[data-testid="isolated-auth-button"]')).toBe(button);
     const firstLayoutEvidence = requireElement<HTMLOutputElement>(
       canvasElement,
       '[data-testid="first-layout-ref-state"]',
@@ -316,9 +316,9 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
       'consumer current target evidence not rendered',
     );
 
-    void expect(firstLayoutEvidence).toHaveTextContent('null');
-    void expect(firstLayoutEvidence).toHaveAttribute('hidden');
-    await waitFor(() => void expect(forwardedRefEvidence.observedNode).toBe(button));
+    await expect(firstLayoutEvidence).toHaveTextContent('null');
+    await expect(firstLayoutEvidence).toHaveAttribute('hidden');
+    await waitFor(async () => await expect(forwardedRefEvidence.observedNode).toBe(button));
 
     const clickTarget = requireElement<HTMLDivElement>(
       button,
@@ -338,12 +338,12 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
 
     await userEvent.click(clickTarget);
 
-    void expect(outsideTarget).toBe(host);
-    void expect(outsidePath[0]).toBe(clickTarget);
-    void expect(outsidePath).toContain(button);
-    void expect(outsidePath).toContain(host);
-    void expect(consumerTargetEvidence.observedNode).toBe(clickTarget);
-    void expect(consumerCurrentTargetEvidence.observedNode).toBe(button);
+    await expect(outsideTarget).toBe(host);
+    await expect(outsidePath[0]).toBe(clickTarget);
+    await expect(outsidePath).toContain(button);
+    await expect(outsidePath).toContain(host);
+    await expect(consumerTargetEvidence.observedNode).toBe(clickTarget);
+    await expect(consumerCurrentTargetEvidence.observedNode).toBe(button);
   },
 };
 
@@ -383,9 +383,9 @@ export const NestedRootsRequireTraversalAndRetargetAtEveryBoundary: Story = {
       'nested auth button not rendered',
     );
 
-    void expect(canvasElement.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
-    void expect(outerRoot.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
-    void expect(innerRoot.querySelector('[data-testid="nested-auth-button"]')).toBe(button);
+    await expect(canvasElement.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
+    await expect(outerRoot.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
+    await expect(innerRoot.querySelector('[data-testid="nested-auth-button"]')).toBe(button);
 
     let outerScopeTarget: EventTarget | null = null;
     let documentScopeTarget: EventTarget | null = null;
@@ -408,10 +408,10 @@ export const NestedRootsRequireTraversalAndRetargetAtEveryBoundary: Story = {
 
     await userEvent.click(button);
 
-    void expect(outerScopeTarget).toBe(innerHost);
-    void expect(documentScopeTarget).toBe(outerHost);
-    void expect(composedPath[0]).toBe(button);
-    void expect(composedPath).toContain(innerHost);
-    void expect(composedPath).toContain(outerHost);
+    await expect(outerScopeTarget).toBe(innerHost);
+    await expect(documentScopeTarget).toBe(outerHost);
+    await expect(composedPath[0]).toBe(button);
+    await expect(composedPath).toContain(innerHost);
+    await expect(composedPath).toContain(outerHost);
   },
 };
diff --git a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
index e4ada187..43e469dd 100644
--- a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
@@ -217,11 +217,11 @@ function getPermissionDialog(topLayer: HTMLElement): HTMLElement | null {
   );
 }
 
-function expectOverlayAboveAtOverlap(
+async function expectOverlayAboveAtOverlap(
   root: ShadowRoot,
   expectedTop: HTMLElement,
   underneath: HTMLElement,
-): void {
+): Promise<void> {
   const topRect = expectedTop.getBoundingClientRect();
   const underneathRect = underneath.getBoundingClientRect();
   const overlapLeft = Math.max(topRect.left, underneathRect.left);
@@ -229,14 +229,14 @@ function expectOverlayAboveAtOverlap(
   const overlapTop = Math.max(topRect.top, underneathRect.top);
   const overlapBottom = Math.min(topRect.bottom, underneathRect.bottom);
 
-  void expect(overlapRight).toBeGreaterThan(overlapLeft);
-  void expect(overlapBottom).toBeGreaterThan(overlapTop);
+  await expect(overlapRight).toBeGreaterThan(overlapLeft);
+  await expect(overlapBottom).toBeGreaterThan(overlapTop);
 
   const hit = root.elementFromPoint(
     overlapLeft + (overlapRight - overlapLeft) / 2,
     overlapTop + (overlapBottom - overlapTop) / 2,
   );
-  void expect(hit === expectedTop || (hit !== null && expectedTop.contains(hit))).toBe(true);
+  await expect(hit === expectedTop || (hit !== null && expectedTop.contains(hit))).toBe(true);
 }
 
 function placeOverlayCenterUnderneath(
@@ -310,7 +310,7 @@ async function getPrimaryHarness(canvasElement: HTMLElement): Promise<PrimaryHar
   const root = await waitForShadowRoot(primaryIsland);
   const contentWrapper = root.querySelector<HTMLElement>('[data-yv-shadow-content-wrapper]');
   if (!contentWrapper) throw new Error('shadow content wrapper not rendered');
-  void expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+  await expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
   return { contentWrapper, primaryIsland, root };
 }
 
@@ -331,7 +331,7 @@ async function openVerseActionPopover(
     'verse action popover not rendered',
     productionWaitOptions,
   );
-  await waitFor(() => void expect(topLayer.matches(':popover-open')).toBe(true));
+  await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(true));
   return { topLayer, versePopover };
 }
 
@@ -342,7 +342,7 @@ async function openPermissionDialogFromVerseAction(
   const swatch = versePopover.querySelector<HTMLButtonElement>('[role="group"] button');
   if (!swatch) throw new Error('highlight swatch not rendered');
   await userEvent.click(swatch);
-  return waitFor(() => {
+  return waitFor(async () => {
     const dialog = getPermissionDialog(topLayer);
     if (!dialog) throw new Error('highlight permission dialog not rendered');
     return dialog;
@@ -422,36 +422,36 @@ export const PopoverOpensDialogEvidence: Story = {
           opened.topLayer,
           opened.versePopover,
         );
-        void expect(opened.versePopover.getRootNode()).toBe(root);
-        void expect(permissionDialog.getRootNode()).toBe(root);
+        await expect(opened.versePopover.getRootNode()).toBe(root);
+        await expect(permissionDialog.getRootNode()).toBe(root);
         const restorePosition = placeOverlayCenterUnderneath(opened.versePopover, permissionDialog);
         try {
-          expectOverlayAboveAtOverlap(root, permissionDialog, opened.versePopover);
+          await expectOverlayAboveAtOverlap(root, permissionDialog, opened.versePopover);
         } finally {
           restorePosition();
         }
-        await waitFor(() => {
+        await waitFor(async () => {
           const focused = root.activeElement;
-          void expect(focused !== null && permissionDialog.contains(focused)).toBe(true);
+          await expect(focused !== null && permissionDialog.contains(focused)).toBe(true);
         }, productionWaitOptions);
-        void expect(contentWrapper.inert).toBe(true);
-        void expect(opened.versePopover).toHaveAttribute('data-state', 'open');
+        await expect(contentWrapper.inert).toBe(true);
+        await expect(opened.versePopover).toHaveAttribute('data-state', 'open');
       });
 
       await step('Escape dismisses one nested overlay at a time', async () => {
         await userEvent.keyboard('{Escape}');
-        await waitFor(() => {
-          void expect(getPermissionDialog(topLayer)).toBeNull();
-          void expect(topLayer.querySelector('[data-slot="verse-action-popover"]')).not.toBeNull();
-          void expect(contentWrapper.inert).toBe(false);
+        await waitFor(async () => {
+          await expect(getPermissionDialog(topLayer)).toBeNull();
+          await expect(topLayer.querySelector('[data-slot="verse-action-popover"]')).not.toBeNull();
+          await expect(contentWrapper.inert).toBe(false);
           const focused = root.activeElement;
-          void expect(focused !== null && versePopover.contains(focused)).toBe(true);
+          await expect(focused !== null && versePopover.contains(focused)).toBe(true);
         }, productionWaitOptions);
         await userEvent.keyboard('{Escape}');
-        await waitFor(() => {
-          void expect(topLayer.querySelector('[data-slot="verse-action-popover"]')).toBeNull();
-          void expect(topLayer.matches(':popover-open')).toBe(false);
-          void expect(root.activeElement).toBe(priorControl);
+        await waitFor(async () => {
+          await expect(topLayer.querySelector('[data-slot="verse-action-popover"]')).toBeNull();
+          await expect(topLayer.matches(':popover-open')).toBe(false);
+          await expect(root.activeElement).toBe(priorControl);
         }, productionWaitOptions);
       });
 
@@ -474,26 +474,26 @@ export const PopoverOpensDialogEvidence: Story = {
         if (!dialogOverlay) throw new Error('dialog overlay not rendered');
         closeAllOverlays.click();
         closeAllOverlays.click();
-        await waitFor(() => {
-          void expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
-          void expect(permissionDialog).toHaveAttribute('data-state', 'closed');
+        await waitFor(async () => {
+          await expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
+          await expect(permissionDialog).toHaveAttribute('data-state', 'closed');
         }, productionWaitOptions);
         finishAnimations(opened.versePopover);
-        await waitFor(() => {
-          void expect(
+        await waitFor(async () => {
+          await expect(
             opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
           ).toBeNull();
-          void expect(getPermissionDialog(opened.topLayer)).toBe(permissionDialog);
-          void expect(contentWrapper.inert).toBe(true);
+          await expect(getPermissionDialog(opened.topLayer)).toBe(permissionDialog);
+          await expect(contentWrapper.inert).toBe(true);
         }, productionWaitOptions);
         finishAnimations(permissionDialog);
         finishAnimations(dialogOverlay);
-        await waitFor(() => {
-          void expect(getPermissionDialog(opened.topLayer)).toBeNull();
-          void expect(contentWrapper.inert).toBe(false);
-          void expect(opened.topLayer.matches(':popover-open')).toBe(false);
+        await waitFor(async () => {
+          await expect(getPermissionDialog(opened.topLayer)).toBeNull();
+          await expect(contentWrapper.inert).toBe(false);
+          await expect(opened.topLayer.matches(':popover-open')).toBe(false);
         }, productionWaitOptions);
-        void expect(closeAllRequests.getAttribute('data-count')).toBe('2');
+        await expect(closeAllRequests.getAttribute('data-count')).toBe('2');
       });
 
       await step('Finish teardown when the dialog exits first', async () => {
@@ -515,27 +515,27 @@ export const PopoverOpensDialogEvidence: Story = {
         );
         if (!dialogOverlay) throw new Error('dialog overlay not rendered');
         closeAllOverlays.click();
-        await waitFor(() => {
-          void expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
-          void expect(permissionDialog).toHaveAttribute('data-state', 'closed');
+        await waitFor(async () => {
+          await expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
+          await expect(permissionDialog).toHaveAttribute('data-state', 'closed');
         }, productionWaitOptions);
         finishAnimations(permissionDialog);
         finishAnimations(dialogOverlay);
-        await waitFor(() => {
-          void expect(getPermissionDialog(opened.topLayer)).toBeNull();
-          void expect(
+        await waitFor(async () => {
+          await expect(getPermissionDialog(opened.topLayer)).toBeNull();
+          await expect(
             opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
           ).not.toBeNull();
         }, productionWaitOptions);
         finishAnimations(opened.versePopover);
-        await waitFor(() => {
-          void expect(
+        await waitFor(async () => {
+          await expect(
             opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
           ).toBeNull();
-          void expect(contentWrapper.inert).toBe(false);
-          void expect(opened.topLayer.matches(':popover-open')).toBe(false);
+          await expect(contentWrapper.inert).toBe(false);
+          await expect(opened.topLayer.matches(':popover-open')).toBe(false);
         }, productionWaitOptions);
-        void expect(closeAllRequests.getAttribute('data-count')).toBe('3');
+        await expect(closeAllRequests.getAttribute('data-count')).toBe('3');
       });
     } finally {
       for (const style of exitAnimationStyles) style.remove();
@@ -593,7 +593,7 @@ export const DialogContainsPopoverEvidence: Story = {
       );
       const restorePosition = placeOverlayCenterUnderneath(notesDialog, notesPopover);
       try {
-        expectOverlayAboveAtOverlap(root, notesPopover, notesDialog);
+        await expectOverlayAboveAtOverlap(root, notesPopover, notesDialog);
       } finally {
         restorePosition();
       }
@@ -604,27 +604,27 @@ export const DialogContainsPopoverEvidence: Story = {
         productionWaitOptions,
       );
       await userEvent.click(notesAction);
-      await waitFor(() => void expect(noteActionCount.getAttribute('data-count')).toBe('1'));
-      await waitFor(() => {
+      await waitFor(async () => await expect(noteActionCount.getAttribute('data-count')).toBe('1'));
+      await waitFor(async () => {
         const focused = root.activeElement;
-        void expect(focused !== null && notesPopover.contains(focused)).toBe(true);
+        await expect(focused !== null && notesPopover.contains(focused)).toBe(true);
       });
     });
 
     await step('Escape closes only the popover and restores its trigger', async () => {
       await userEvent.keyboard('{Escape}');
-      await waitFor(() => void expect(notesPopover.isConnected).toBe(false));
-      void expect(topLayer).toContainElement(notesDialog);
-      void expect(root.activeElement).toBe(notesTrigger);
-      void expect(contentWrapper.inert).toBe(true);
+      await waitFor(async () => await expect(notesPopover.isConnected).toBe(false));
+      await expect(topLayer).toContainElement(notesDialog);
+      await expect(root.activeElement).toBe(notesTrigger);
+      await expect(contentWrapper.inert).toBe(true);
     });
 
     await step('The next Escape closes the dialog and restores its opener', async () => {
       await userEvent.keyboard('{Escape}');
-      await waitFor(() => void expect(notesDialog.isConnected).toBe(false));
-      await waitFor(() => void expect(contentWrapper.inert).toBe(false));
-      await waitFor(() => void expect(topLayer.matches(':popover-open')).toBe(false));
-      void expect(root.activeElement).toBe(openNotes);
+      await waitFor(async () => await expect(notesDialog.isConnected).toBe(false));
+      await waitFor(async () => await expect(contentWrapper.inert).toBe(false));
+      await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(false));
+      await expect(root.activeElement).toBe(openNotes);
     });
   },
 };
@@ -662,16 +662,16 @@ export const TwoIndependentOverlaysEvidence: Story = {
         'independent popover not rendered',
         productionWaitOptions,
       );
-      await waitFor(() => {
+      await waitFor(async () => {
         const focused = root.activeElement;
-        void expect(focused !== null && independentPopover.contains(focused)).toBe(true);
+        await expect(focused !== null && independentPopover.contains(focused)).toBe(true);
       });
-      void expect(contentWrapper.inert).toBe(false);
+      await expect(contentWrapper.inert).toBe(false);
       await userEvent.keyboard('{Escape}');
-      await waitFor(() => void expect(independentPopover.isConnected).toBe(false));
-      void expect(root.activeElement).toBe(independentTrigger);
+      await waitFor(async () => await expect(independentPopover.isConnected).toBe(false));
+      await expect(root.activeElement).toBe(independentTrigger);
       closeAllOverlays.click();
-      await waitFor(() => void expect(topLayer.matches(':popover-open')).toBe(false));
+      await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(false));
     });
 
     await step('Keep the secondary root usable through primary teardown', async () => {
@@ -703,7 +703,7 @@ export const TwoIndependentOverlaysEvidence: Story = {
       );
 
       const opened = await openVerseActionPopover(root, verse);
-      void expect(opened.topLayer).not.toBe(secondaryTopLayer);
+      await expect(opened.topLayer).not.toBe(secondaryTopLayer);
       await openPermissionDialogFromVerseAction(opened.topLayer, opened.versePopover);
       const unmountPrimary = await waitForElement<HTMLButtonElement>(
         canvasElement,
@@ -712,11 +712,13 @@ export const TwoIndependentOverlaysEvidence: Story = {
         productionWaitOptions,
       );
       unmountPrimary.click();
-      await waitFor(() => void expect(primaryIsland.isConnected).toBe(false));
+      await waitFor(async () => await expect(primaryIsland.isConnected).toBe(false));
       closeAllOverlays.click();
-      await waitFor(() => void expect(secondaryPopover.isConnected).toBe(false));
-      await waitFor(() => void expect(secondaryTopLayer.matches(':popover-open')).toBe(false));
-      void expect(secondaryIsland.isConnected).toBe(true);
+      await waitFor(async () => await expect(secondaryPopover.isConnected).toBe(false));
+      await waitFor(
+        async () => await expect(secondaryTopLayer.matches(':popover-open')).toBe(false),
+      );
+      await expect(secondaryIsland.isConnected).toBe(true);
 
       await userEvent.click(secondaryTrigger);
       const reopenedSecondaryPopover = await waitForElement<HTMLElement>(
@@ -725,8 +727,8 @@ export const TwoIndependentOverlaysEvidence: Story = {
         'secondary popover did not reopen after primary teardown',
         productionWaitOptions,
       );
-      void expect(reopenedSecondaryPopover).toHaveAttribute('data-state', 'open');
-      void expect(secondaryTopLayer.matches(':popover-open')).toBe(true);
+      await expect(reopenedSecondaryPopover).toHaveAttribute('data-state', 'open');
+      await expect(secondaryTopLayer.matches(':popover-open')).toBe(true);
     });
   },
 };
@@ -760,7 +762,7 @@ export const RapidCloseReopenDuringExitEvidence: Story = {
           'shadow-local top layer not created',
           productionWaitOptions,
         );
-        firstDialog = await waitFor(() => {
+        firstDialog = await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog) throw new Error('permission dialog did not open');
           return dialog;
@@ -768,52 +770,54 @@ export const RapidCloseReopenDuringExitEvidence: Story = {
       });
 
       await step('Retain modal ownership while the dialog starts exiting', async () => {
-        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
-        void expect(firstDialog.isConnected).toBe(true);
-        void expect(topLayer).toContainElement(firstDialog);
-        void expect(contentWrapper.inert).toBe(true);
+        await waitFor(
+          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
+        );
+        await expect(firstDialog.isConnected).toBe(true);
+        await expect(topLayer).toContainElement(firstDialog);
+        await expect(contentWrapper.inert).toBe(true);
       });
 
       await step('Preserve modal focus after the first dialog unmounts', async () => {
-        await waitFor(() => {
-          void expect(firstDialog.isConnected).toBe(false);
+        await waitFor(async () => {
+          await expect(firstDialog.isConnected).toBe(false);
           const overlay = topLayer.querySelector<HTMLElement>('[data-slot="dialog-overlay"]');
           if (!overlay) throw new Error('dialog overlay did not remain during content exit');
           const currentDialog = getPermissionDialog(topLayer);
           const focused = root.activeElement;
-          void expect(
+          await expect(
             focused === overlay ||
               (focused !== null && currentDialog !== null && currentDialog.contains(focused)),
           ).toBe(true);
-          void expect(contentWrapper.inert).toBe(true);
-          void expect(topLayer.matches(':popover-open')).toBe(true);
+          await expect(contentWrapper.inert).toBe(true);
+          await expect(topLayer.matches(':popover-open')).toBe(true);
         });
       });
 
       await step('Reopen from overlay-only retained presence', async () => {
-        const reopenedDialog = await waitFor(() => {
+        const reopenedDialog = await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not reopen during exit');
           }
           return dialog;
         });
-        void expect(reopenedDialog).not.toBe(firstDialog);
-        await waitFor(() => {
+        await expect(reopenedDialog).not.toBe(firstDialog);
+        await waitFor(async () => {
           const focused = root.activeElement;
-          void expect(focused !== null && reopenedDialog.contains(focused)).toBe(true);
-          void expect(contentWrapper.inert).toBe(true);
-          void expect(topLayer.matches(':popover-open')).toBe(true);
+          await expect(focused !== null && reopenedDialog.contains(focused)).toBe(true);
+          await expect(contentWrapper.inert).toBe(true);
+          await expect(topLayer.matches(':popover-open')).toBe(true);
         });
       });
 
       await step('Release modal ownership after the final close', async () => {
         await userEvent.keyboard('{Escape}');
-        await waitFor(() => {
-          void expect(getPermissionDialog(topLayer)).toBeNull();
-          void expect(contentWrapper.inert).toBe(false);
-          void expect(topLayer.matches(':popover-open')).toBe(false);
-          void expect(root.activeElement).toBe(runRapidCloseReopen);
+        await waitFor(async () => {
+          await expect(getPermissionDialog(topLayer)).toBeNull();
+          await expect(contentWrapper.inert).toBe(false);
+          await expect(topLayer.matches(':popover-open')).toBe(false);
+          await expect(root.activeElement).toBe(runRapidCloseReopen);
         });
       });
     } finally {
@@ -853,44 +857,48 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
           '[data-yv-shadow-local-overlay]',
           'shadow-local top layer not created',
         );
-        const firstDialog = await waitFor(() => {
+        const firstDialog = await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog) throw new Error('permission dialog did not open');
           return dialog;
         });
-        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
-        await waitFor(() => {
+        await waitFor(
+          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
+        );
+        await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not reopen during exit');
           }
-          void expect(contentWrapper.inert).toBe(true);
+          await expect(contentWrapper.inert).toBe(true);
         });
       });
 
       await step('Ignore the opener after it moves to another shadow root', async () => {
         secondaryRoot.append(runRapidCloseReopen);
-        void expect(runRapidCloseReopen.getRootNode()).toBe(secondaryRoot);
+        await expect(runRapidCloseReopen.getRootNode()).toBe(secondaryRoot);
 
         await userEvent.keyboard('{Escape}');
-        await waitFor(() => {
-          void expect(getPermissionDialog(topLayer)).toBeNull();
-          void expect(contentWrapper.inert).toBe(false);
-          void expect(topLayer.matches(':popover-open')).toBe(false);
+        await waitFor(async () => {
+          await expect(getPermissionDialog(topLayer)).toBeNull();
+          await expect(contentWrapper.inert).toBe(false);
+          await expect(topLayer.matches(':popover-open')).toBe(false);
         });
-        void expect(secondaryRoot.activeElement).not.toBe(runRapidCloseReopen);
+        await expect(secondaryRoot.activeElement).not.toBe(runRapidCloseReopen);
       });
 
       await step('Ignore the opener after it moves into the light DOM', async () => {
         contentWrapper.append(runRapidCloseReopen);
         await userEvent.click(runRapidCloseReopen);
-        const firstDialog = await waitFor(() => {
+        const firstDialog = await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog) throw new Error('permission dialog did not reopen for light-DOM target');
           return dialog;
         });
-        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
-        await waitFor(() => {
+        await waitFor(
+          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
+        );
+        await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not rapidly reopen for light-DOM target');
@@ -900,15 +908,15 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
         const focus = spyOn(runRapidCloseReopen, 'focus');
         try {
           canvasElement.ownerDocument.body.append(runRapidCloseReopen);
-          void expect(runRapidCloseReopen.getRootNode()).toBe(canvasElement.ownerDocument);
+          await expect(runRapidCloseReopen.getRootNode()).toBe(canvasElement.ownerDocument);
           await userEvent.keyboard('{Escape}');
-          await waitFor(() => {
-            void expect(getPermissionDialog(topLayer)).toBeNull();
-            void expect(contentWrapper.inert).toBe(false);
-            void expect(topLayer.matches(':popover-open')).toBe(false);
+          await waitFor(async () => {
+            await expect(getPermissionDialog(topLayer)).toBeNull();
+            await expect(contentWrapper.inert).toBe(false);
+            await expect(topLayer.matches(':popover-open')).toBe(false);
           });
-          void expect(focus).not.toHaveBeenCalled();
-          void expect(canvasElement.ownerDocument.activeElement).not.toBe(runRapidCloseReopen);
+          await expect(focus).not.toHaveBeenCalled();
+          await expect(canvasElement.ownerDocument.activeElement).not.toBe(runRapidCloseReopen);
         } finally {
           focus.mockRestore();
         }
@@ -917,13 +925,15 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
       await step('Ignore the opener after it disconnects', async () => {
         contentWrapper.append(runRapidCloseReopen);
         await userEvent.click(runRapidCloseReopen);
-        const firstDialog = await waitFor(() => {
+        const firstDialog = await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog) throw new Error('permission dialog did not reopen for disconnected target');
           return dialog;
         });
-        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
-        await waitFor(() => {
+        await waitFor(
+          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
+        );
+        await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not rapidly reopen for disconnected target');
@@ -933,15 +943,15 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
         const focus = spyOn(runRapidCloseReopen, 'focus');
         try {
           runRapidCloseReopen.remove();
-          void expect(runRapidCloseReopen.isConnected).toBe(false);
+          await expect(runRapidCloseReopen.isConnected).toBe(false);
           await userEvent.keyboard('{Escape}');
-          await waitFor(() => {
-            void expect(getPermissionDialog(topLayer)).toBeNull();
-            void expect(contentWrapper.inert).toBe(false);
-            void expect(topLayer.matches(':popover-open')).toBe(false);
+          await waitFor(async () => {
+            await expect(getPermissionDialog(topLayer)).toBeNull();
+            await expect(contentWrapper.inert).toBe(false);
+            await expect(topLayer.matches(':popover-open')).toBe(false);
           });
-          void expect(focus).not.toHaveBeenCalled();
-          void expect(root.activeElement).not.toBe(runRapidCloseReopen);
+          await expect(focus).not.toHaveBeenCalled();
+          await expect(root.activeElement).not.toBe(runRapidCloseReopen);
         } finally {
           focus.mockRestore();
         }
@@ -950,14 +960,16 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
       await step('Ignore the opener after it moves to another document', async () => {
         contentWrapper.append(runRapidCloseReopen);
         await userEvent.click(runRapidCloseReopen);
-        const firstDialog = await waitFor(() => {
+        const firstDialog = await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog)
             throw new Error('permission dialog did not reopen for cross-document target');
           return dialog;
         });
-        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
-        await waitFor(() => {
+        await waitFor(
+          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
+        );
+        await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not rapidly reopen for cross-document target');
@@ -968,15 +980,15 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
         const focus = spyOn(runRapidCloseReopen, 'focus');
         try {
           secondaryDocument.body.append(runRapidCloseReopen);
-          void expect(runRapidCloseReopen.isConnected).toBe(true);
-          void expect(runRapidCloseReopen.ownerDocument).toBe(secondaryDocument);
+          await expect(runRapidCloseReopen.isConnected).toBe(true);
+          await expect(runRapidCloseReopen.ownerDocument).toBe(secondaryDocument);
           await userEvent.keyboard('{Escape}');
-          await waitFor(() => {
-            void expect(getPermissionDialog(topLayer)).toBeNull();
-            void expect(contentWrapper.inert).toBe(false);
-            void expect(topLayer.matches(':popover-open')).toBe(false);
+          await waitFor(async () => {
+            await expect(getPermissionDialog(topLayer)).toBeNull();
+            await expect(contentWrapper.inert).toBe(false);
+            await expect(topLayer.matches(':popover-open')).toBe(false);
           });
-          void expect(focus).not.toHaveBeenCalled();
+          await expect(focus).not.toHaveBeenCalled();
         } finally {
           focus.mockRestore();
         }
diff --git a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
index 8090a903..c7a9a1d6 100644
--- a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
+++ b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
@@ -221,11 +221,11 @@ interface MountedFixture {
   sheet: CSSStyleSheet;
 }
 
-function requireMountedFixture(canvasElement: HTMLElement): MountedFixture {
+async function requireMountedFixture(canvasElement: HTMLElement): Promise<MountedFixture> {
   const hosts = Array.from(
     canvasElement.ownerDocument.querySelectorAll<HTMLElement>('[data-yv-shadow-host]'),
   );
-  void expect(hosts).toHaveLength(EXPECTED_COMPONENT_IDS.length);
+  await expect(hosts).toHaveLength(EXPECTED_COMPONENT_IDS.length);
 
   const roots = hosts.map((host) => {
     if (!host.shadowRoot) throw new Error('shadow root not attached');
@@ -235,7 +235,7 @@ function requireMountedFixture(canvasElement: HTMLElement): MountedFixture {
     (root) =>
       root.querySelector<HTMLElement>('[data-realistic-component]')?.dataset.realisticComponent,
   );
-  void expect(componentIds).toEqual(EXPECTED_COMPONENT_IDS);
+  await expect(componentIds).toEqual(EXPECTED_COMPONENT_IDS);
 
   const components = new Map(
     roots.map((root, index) => [
@@ -251,35 +251,35 @@ function requireMountedFixture(canvasElement: HTMLElement): MountedFixture {
     ['votd-large', 'JHN.3.16'],
   ]);
   for (const [id, usfm] of expectedPassages) {
-    void expect(components.get(id)).toHaveTextContent(`Fixture scripture content for ${usfm}.`);
+    await expect(components.get(id)).toHaveTextContent(`Fixture scripture content for ${usfm}.`);
   }
-  void expect(
+  await expect(
     components.get('avatar-primary')?.querySelector('[aria-label="SDK Reader"]'),
   ).not.toBeNull();
-  void expect(
+  await expect(
     components.get('avatar-secondary')?.querySelector('[aria-label="Bible Partner"]'),
   ).not.toBeNull();
-  void expect(components.get('notes-primary')?.querySelector('textarea')).toHaveValue(
+  await expect(components.get('notes-primary')?.querySelector('textarea')).toHaveValue(
     'Primary notes',
   );
-  void expect(components.get('notes-secondary')?.querySelector('textarea')).toHaveValue(
+  await expect(components.get('notes-secondary')?.querySelector('textarea')).toHaveValue(
     'Secondary notes',
   );
-  void expect(components.get('notes-tertiary')?.querySelector('textarea')).toHaveValue(
+  await expect(components.get('notes-tertiary')?.querySelector('textarea')).toHaveValue(
     'Tertiary notes',
   );
-  void expect(
+  await expect(
     components.get('separator-primary')?.querySelector('[role="separator"]'),
   ).not.toBeNull();
-  void expect(
+  await expect(
     components.get('separator-secondary')?.querySelector('[role="separator"]'),
   ).not.toBeNull();
 
   const sheet = roots[0]?.adoptedStyleSheets[0];
   if (!sheet) throw new Error('shared SDK stylesheet not adopted');
   for (const root of roots) {
-    void expect(root.adoptedStyleSheets).toHaveLength(1);
-    void expect(root.adoptedStyleSheets[0]).toBe(sheet);
+    await expect(root.adoptedStyleSheets).toHaveLength(1);
+    await expect(root.adoptedStyleSheets[0]).toBe(sheet);
   }
 
   return { hosts, sheet };
@@ -305,13 +305,13 @@ const STRICT_EFFECT_COUNTS: ExpectedEffectCounts = import.meta.env.DEV
     }
   : NORMAL_EFFECT_COUNTS;
 
-function requireEffectCounts(
+async function requireEffectCounts(
   canvasElement: HTMLElement,
   [setup, cleanup]: [setup: number, cleanup: number],
-): void {
+): Promise<void> {
   const counts = canvasElement.querySelector('[data-testid="effect-lifecycle-counts"]');
-  void expect(counts).toHaveAttribute('data-effect-setup', String(setup));
-  void expect(counts).toHaveAttribute('data-effect-cleanup', String(cleanup));
+  await expect(counts).toHaveAttribute('data-effect-setup', String(setup));
+  await expect(counts).toHaveAttribute('data-effect-cleanup', String(cleanup));
 }
 
 async function exerciseLifecycle(
@@ -324,27 +324,27 @@ async function exerciseLifecycle(
 
   try {
     await userEvent.click(toggle);
-    const firstMount = await waitFor(() => {
-      const fixture = requireMountedFixture(canvasElement);
-      requireEffectCounts(canvasElement, expectedEffectCounts.firstMount);
+    const firstMount = await waitFor(async () => {
+      const fixture = await requireMountedFixture(canvasElement);
+      await requireEffectCounts(canvasElement, expectedEffectCounts.firstMount);
       return fixture;
     });
 
     await userEvent.click(toggle);
-    void expect(canvasElement.querySelectorAll('[data-yv-shadow-host]')).toHaveLength(0);
-    void expect(canvasElement.querySelector('[data-testid="realistic-component-mix"]')).toBeNull();
-    requireEffectCounts(canvasElement, expectedEffectCounts.removal);
+    await expect(canvasElement.querySelectorAll('[data-yv-shadow-host]')).toHaveLength(0);
+    await expect(canvasElement.querySelector('[data-testid="realistic-component-mix"]')).toBeNull();
+    await requireEffectCounts(canvasElement, expectedEffectCounts.removal);
 
     await userEvent.click(toggle);
-    const secondMount = await waitFor(() => {
-      const fixture = requireMountedFixture(canvasElement);
-      requireEffectCounts(canvasElement, expectedEffectCounts.secondMount);
+    const secondMount = await waitFor(async () => {
+      const fixture = await requireMountedFixture(canvasElement);
+      await requireEffectCounts(canvasElement, expectedEffectCounts.secondMount);
       return fixture;
     });
     for (const host of secondMount.hosts) {
-      void expect(host.shadowRoot?.adoptedStyleSheets[0]).toBe(firstMount.sheet);
+      await expect(host.shadowRoot?.adoptedStyleSheets[0]).toBe(firstMount.sheet);
     }
-    void expect(consoleError).not.toHaveBeenCalled();
+    await expect(consoleError).not.toHaveBeenCalled();
   } finally {
     consoleError.mockRestore();
   }
diff --git a/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx b/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
index 0e21f954..2fd50725 100644
--- a/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
@@ -72,16 +72,16 @@ async function expectOutsideFocusRedirectedInto(
   dialog: HTMLElement,
 ): Promise<void> {
   outsideControl.focus();
-  await waitFor(() => {
+  await waitFor(async () => {
     const focused = root.activeElement;
-    void expect(focused !== null && dialog.contains(focused)).toBe(true);
+    await expect(focused !== null && dialog.contains(focused)).toBe(true);
   });
-  void expect(outsideControl.ownerDocument.activeElement).not.toBe(outsideControl);
+  await expect(outsideControl.ownerDocument.activeElement).not.toBe(outsideControl);
 }
 
 export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
   play: async ({ canvasElement }) => {
-    const { outsideControl, clippingContainer } = await waitFor(() => {
+    const { outsideControl, clippingContainer } = await waitFor(async () => {
       const outside = canvasElement.querySelector<HTMLButtonElement>(
         '[data-testid="outside-control"]',
       );
@@ -99,15 +99,15 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
       [data-slot='dialog-overlay'][data-state='closed'] { animation-duration: 800ms !important; }
     `;
     root.append(exitAnimationStyle);
-    const insideControl = await waitFor(() => {
+    const insideControl = await waitFor(async () => {
       const element = root.querySelector<HTMLButtonElement>('[data-testid="inside-control"]');
       if (!element) throw new Error('inside-island control not rendered');
       return element;
     });
-    void expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    await expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
     insideControl.focus();
     await userEvent.click(insideControl);
-    const dialog = await waitFor(() => {
+    const dialog = await waitFor(async () => {
       const element = root.querySelector<HTMLElement>('[role="dialog"]');
       if (!element) throw new Error('sign-in dialog not rendered in the component shadow root');
       return element;
@@ -116,19 +116,19 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     const contentWrapper = root.querySelector<HTMLElement>('[data-yv-shadow-content-wrapper]');
     if (!topLayer || !contentWrapper) throw new Error('shadow modal coordination not rendered');
 
-    void expect(dialog.getRootNode()).toBe(root);
-    void expect(topLayer.getRootNode()).toBe(root);
-    void expect(canvasElement.ownerDocument.body.querySelector('[role="dialog"]')).toBeNull();
-    await waitFor(() => void expect(topLayer.matches(':popover-open')).toBe(true));
+    await expect(dialog.getRootNode()).toBe(root);
+    await expect(topLayer.getRootNode()).toBe(root);
+    await expect(canvasElement.ownerDocument.body.querySelector('[role="dialog"]')).toBeNull();
+    await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(true));
 
     const titleId = dialog.getAttribute('aria-labelledby');
     const descriptionId = dialog.getAttribute('aria-describedby');
-    void expect(titleId).toBeTruthy();
-    void expect(descriptionId).toBeTruthy();
+    await expect(titleId).toBeTruthy();
+    await expect(descriptionId).toBeTruthy();
     const title = root.getElementById(titleId!);
     const description = root.getElementById(descriptionId!);
-    void expect(title).not.toBeNull();
-    void expect(description).not.toBeNull();
+    await expect(title).not.toBeNull();
+    await expect(description).not.toBeNull();
     // SAFETY: These reflected-ARIA properties are still a draft; verify support before use.
     const reflectedDialog = dialog as HTMLElement & {
       ariaLabelledByElements?: readonly Element[];
@@ -137,12 +137,12 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     if (!reflectedDialog.ariaLabelledByElements || !reflectedDialog.ariaDescribedByElements) {
       throw new Error('browser did not expose the dialog ARIA element relationships');
     }
-    void expect(reflectedDialog.ariaLabelledByElements).toEqual([title]);
-    void expect(reflectedDialog.ariaDescribedByElements).toEqual([description]);
+    await expect(reflectedDialog.ariaLabelledByElements).toEqual([title]);
+    await expect(reflectedDialog.ariaDescribedByElements).toEqual([description]);
 
-    await waitFor(() => {
+    await waitFor(async () => {
       const focused = root.activeElement;
-      void expect(focused !== null && dialog.contains(focused)).toBe(true);
+      await expect(focused !== null && dialog.contains(focused)).toBe(true);
     });
 
     const hiddenWrapper = canvasElement.ownerDocument.createElement('div');
@@ -155,7 +155,7 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     const dialogButtons = Array.from(
       dialog.querySelectorAll<HTMLButtonElement>('button[data-slot="button"]'),
     );
-    void expect(dialogButtons).toHaveLength(2);
+    await expect(dialogButtons).toHaveLength(2);
     const [confirmButton, declineButton] = dialogButtons;
     if (!confirmButton || !declineButton) throw new Error('sign-in dialog actions not rendered');
 
@@ -175,24 +175,24 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
 
     confirmButton.focus();
     await userEvent.tab();
-    void expect(root.activeElement).toBe(firstRadio);
+    await expect(root.activeElement).toBe(firstRadio);
     await userEvent.tab();
-    void expect(root.activeElement).toBe(declineButton);
+    await expect(root.activeElement).toBe(declineButton);
     await userEvent.tab();
-    await waitFor(() => void expect(root.activeElement).toBe(confirmButton));
+    await waitFor(async () => await expect(root.activeElement).toBe(confirmButton));
     await userEvent.tab({ shift: true });
-    await waitFor(() => void expect(root.activeElement).toBe(declineButton));
-    void expect(root.activeElement).not.toBe(negativeTabIndexButton);
-    void expect(root.activeElement).not.toBe(secondRadio);
+    await waitFor(async () => await expect(root.activeElement).toBe(declineButton));
+    await expect(root.activeElement).not.toBe(negativeTabIndexButton);
+    await expect(root.activeElement).not.toBe(secondRadio);
 
-    void expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
+    await expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
 
     await expectOutsideFocusRedirectedInto(root, outsideControl, dialog);
 
-    void expect(insideControl.closest('[inert]')).not.toBeNull();
+    await expect(insideControl.closest('[inert]')).not.toBeNull();
 
     insideControl.focus();
-    void expect(root.activeElement).not.toBe(insideControl);
+    await expect(root.activeElement).not.toBe(insideControl);
 
     const overlay = dialog.previousElementSibling;
     if (!(overlay instanceof HTMLElement)) throw new Error('dialog overlay not rendered');
@@ -201,23 +201,23 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     const clippingRect = clippingContainer.getBoundingClientRect();
     const viewport = canvasElement.ownerDocument.defaultView;
     if (!viewport) throw new Error('story window not available');
-    void expect(overlayRect.width).toBeGreaterThanOrEqual(viewport.innerWidth - 1);
-    void expect(overlayRect.height).toBeGreaterThanOrEqual(viewport.innerHeight - 1);
+    await expect(overlayRect.width).toBeGreaterThanOrEqual(viewport.innerWidth - 1);
+    await expect(overlayRect.height).toBeGreaterThanOrEqual(viewport.innerHeight - 1);
     const sampleX =
       clippingRect.right + 4 < viewport.innerWidth ? clippingRect.right + 4 : clippingRect.left - 4;
     const sampleY = Math.min(viewport.innerHeight - 4, Math.max(4, clippingRect.top + 4));
     const escapedHit = root.elementFromPoint(sampleX, sampleY);
-    void expect(
+    await expect(
       escapedHit === overlay || (escapedHit !== null && overlay.contains(escapedHit)),
     ).toBe(true);
-    void expect(dialogRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
+    await expect(dialogRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
     const dialogSampleX = dialogRect.left + dialogRect.width / 2;
     const dialogSampleY = Math.max(dialogRect.top + 2, clippingRect.bottom + 2);
     if (dialogSampleY >= dialogRect.bottom) {
       throw new Error('dialog did not extend beyond its clipping ancestor');
     }
     const dialogHit = root.elementFromPoint(dialogSampleX, dialogSampleY);
-    void expect(dialogHit === dialog || (dialogHit !== null && dialog.contains(dialogHit))).toBe(
+    await expect(dialogHit === dialog || (dialogHit !== null && dialog.contains(dialogHit))).toBe(
       true,
     );
 
@@ -238,39 +238,39 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     try {
       canvasElement.ownerDocument.head.append(hostileStyle);
       await waitFor(
-        () =>
-          void expect(getComputedStyle(outsideControl).backgroundColor).toBe('rgb(185, 28, 28)'),
+        async () =>
+          await expect(getComputedStyle(outsideControl).backgroundColor).toBe('rgb(185, 28, 28)'),
       );
-      void expect(styleSnapshot(dialog)).toEqual(dialogStyles);
-      void expect(styleSnapshot(overlay)).toEqual(overlayStyles);
+      await expect(styleSnapshot(dialog)).toEqual(dialogStyles);
+      await expect(styleSnapshot(overlay)).toEqual(overlayStyles);
     } finally {
       hostileStyle.remove();
     }
 
     await userEvent.keyboard('{Escape}');
-    await waitFor(() => {
-      void expect(dialog).toHaveAttribute('data-state', 'closed');
-      void expect(topLayer).toContainElement(dialog);
-      void expect(contentWrapper.inert).toBe(true);
-      void expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
-      void expect(topLayer.matches(':popover-open')).toBe(true);
+    await waitFor(async () => {
+      await expect(dialog).toHaveAttribute('data-state', 'closed');
+      await expect(topLayer).toContainElement(dialog);
+      await expect(contentWrapper.inert).toBe(true);
+      await expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
+      await expect(topLayer.matches(':popover-open')).toBe(true);
     });
     await expectOutsideFocusRedirectedInto(root, outsideControl, dialog);
-    await waitFor(() => {
-      void expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
-      void expect(topLayer.querySelector('[data-slot="dialog-overlay"]')).not.toBeNull();
-      void expect(contentWrapper.inert).toBe(true);
-      void expect(root.activeElement).toBe(overlay);
+    await waitFor(async () => {
+      await expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
+      await expect(topLayer.querySelector('[data-slot="dialog-overlay"]')).not.toBeNull();
+      await expect(contentWrapper.inert).toBe(true);
+      await expect(root.activeElement).toBe(overlay);
     });
-    await waitFor(() => {
-      void expect(topLayer.childElementCount).toBe(0);
-      void expect(topLayer.matches(':popover-open')).toBe(false);
-      void expect(contentWrapper.inert).toBe(false);
-      void expect(root.activeElement).toBe(insideControl);
+    await waitFor(async () => {
+      await expect(topLayer.childElementCount).toBe(0);
+      await expect(topLayer.matches(':popover-open')).toBe(false);
+      await expect(contentWrapper.inert).toBe(false);
+      await expect(root.activeElement).toBe(insideControl);
     });
 
     await userEvent.click(outsideControl);
-    const reopenedDialog = await waitFor(() => {
+    const reopenedDialog = await waitFor(async () => {
       const element = root.querySelector<HTMLElement>('[role="dialog"]');
       if (!element) throw new Error('dialog did not reopen');
       return element;
@@ -280,29 +280,29 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
       throw new Error('reopened dialog overlay not rendered');
     }
     await userEvent.click(reopenedOverlay);
-    await waitFor(() => {
-      void expect(reopenedDialog).toHaveAttribute('data-state', 'closed');
-      void expect(contentWrapper.inert).toBe(true);
-      void expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
-      void expect(topLayer.matches(':popover-open')).toBe(true);
+    await waitFor(async () => {
+      await expect(reopenedDialog).toHaveAttribute('data-state', 'closed');
+      await expect(contentWrapper.inert).toBe(true);
+      await expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
+      await expect(topLayer.matches(':popover-open')).toBe(true);
     });
     await expectOutsideFocusRedirectedInto(root, outsideControl, reopenedDialog);
-    await waitFor(() => {
-      void expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
-      void expect(topLayer.querySelector('[data-slot="dialog-overlay"]')).not.toBeNull();
-      void expect(contentWrapper.inert).toBe(true);
-      void expect(root.activeElement).toBe(reopenedOverlay);
+    await waitFor(async () => {
+      await expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
+      await expect(topLayer.querySelector('[data-slot="dialog-overlay"]')).not.toBeNull();
+      await expect(contentWrapper.inert).toBe(true);
+      await expect(root.activeElement).toBe(reopenedOverlay);
     });
     outsideControl.focus();
-    await waitFor(() => {
-      void expect(canvasElement.ownerDocument.activeElement).not.toBe(outsideControl);
-      void expect(root.activeElement).toBe(reopenedOverlay);
+    await waitFor(async () => {
+      await expect(canvasElement.ownerDocument.activeElement).not.toBe(outsideControl);
+      await expect(root.activeElement).toBe(reopenedOverlay);
     });
-    await waitFor(() => {
-      void expect(topLayer.childElementCount).toBe(0);
-      void expect(topLayer.matches(':popover-open')).toBe(false);
-      void expect(contentWrapper.inert).toBe(false);
-      void expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
+    await waitFor(async () => {
+      await expect(topLayer.childElementCount).toBe(0);
+      await expect(topLayer.matches(':popover-open')).toBe(false);
+      await expect(contentWrapper.inert).toBe(false);
+      await expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
     });
     exitAnimationStyle.remove();
   },
diff --git a/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx b/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
index ed985430..f49afa4c 100644
--- a/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
@@ -143,9 +143,9 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 async function waitForClosed(topLayer: HTMLElement): Promise<void> {
-  await waitFor(() => {
-    void expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
-    void expect(topLayer.matches(':popover-open')).toBe(false);
+  await waitFor(async () => {
+    await expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
+    await expect(topLayer.matches(':popover-open')).toBe(false);
   });
 }
 
@@ -204,19 +204,19 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
       'verse action popover not rendered',
     );
 
-    await waitFor(() => void expect(topLayer.matches(':popover-open')).toBe(true));
-    void expect(topLayer.getRootNode()).toBe(shadowRoot);
-    void expect(dialog.getRootNode()).toBe(shadowRoot);
-    void expect(canvasElement.ownerDocument.body.querySelector('[role="dialog"]')).toBeNull();
-    void expect(dialog).toHaveAccessibleName(/.+/);
-    void expect(dialog.querySelector('[role="group"]')).toHaveAccessibleName(/.+/);
-    await waitFor(() => void expect(shadowRoot.activeElement).toBe(dialog));
+    await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(true));
+    await expect(topLayer.getRootNode()).toBe(shadowRoot);
+    await expect(dialog.getRootNode()).toBe(shadowRoot);
+    await expect(canvasElement.ownerDocument.body.querySelector('[role="dialog"]')).toBeNull();
+    await expect(dialog).toHaveAccessibleName(/.+/);
+    await expect(dialog.querySelector('[role="group"]')).toHaveAccessibleName(/.+/);
+    await waitFor(async () => await expect(shadowRoot.activeElement).toBe(dialog));
 
     const clippingRect = clippingContainer.getBoundingClientRect();
     const firstDialogRect = dialog.getBoundingClientRect();
     const escapesAbove = firstDialogRect.top < clippingRect.top - 1;
     const escapesBelow = firstDialogRect.bottom > clippingRect.bottom + 1;
-    void expect(escapesAbove || escapesBelow).toBe(true);
+    await expect(escapesAbove || escapesBelow).toBe(true);
     const sampleX = firstDialogRect.left + firstDialogRect.width / 2;
     const sampleY = escapesBelow
       ? Math.max(firstDialogRect.top + 2, clippingRect.bottom + 2)
@@ -224,44 +224,44 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
     if (sampleY <= firstDialogRect.top || sampleY >= firstDialogRect.bottom)
       throw new Error('popover did not escape clipping bounds');
     const hit = shadowRoot.elementFromPoint(sampleX, sampleY);
-    void expect(hit === dialog || (hit !== null && dialog.contains(hit))).toBe(true);
+    await expect(hit === dialog || (hit !== null && dialog.contains(hit))).toBe(true);
 
     readerScrollRoot.scrollTop = readerScrollRoot.scrollHeight;
-    await waitFor(() => {
+    await waitFor(async () => {
       const readerRect = readerScrollRoot.getBoundingClientRect();
       const dockedRect = dialog.getBoundingClientRect();
-      void expect(Math.abs(dockedRect.top - (readerRect.top + 24))).toBeLessThan(12);
-      void expect(
+      await expect(Math.abs(dockedRect.top - (readerRect.top + 24))).toBeLessThan(12);
+      await expect(
         Math.abs(dockedRect.left + dockedRect.width / 2 - (readerRect.left + readerRect.width / 2)),
       ).toBeLessThan(2);
     });
     readerScrollRoot.scrollTop = 0;
-    await waitFor(() => {
+    await waitFor(async () => {
       const returnedRect = dialog.getBoundingClientRect();
-      void expect(Math.abs(returnedRect.left - firstDialogRect.left)).toBeLessThan(12);
-      void expect(Math.abs(returnedRect.top - firstDialogRect.top)).toBeLessThan(12);
+      await expect(Math.abs(returnedRect.left - firstDialogRect.left)).toBeLessThan(12);
+      await expect(Math.abs(returnedRect.top - firstDialogRect.top)).toBeLessThan(12);
     });
 
     await userEvent.click(secondVerse);
-    await waitFor(() => {
+    await waitFor(async () => {
       const nextRect = dialog.getBoundingClientRect();
-      void expect(nextRect.left).toBeGreaterThan(firstDialogRect.left + 20);
+      await expect(nextRect.left).toBeGreaterThan(firstDialogRect.left + 20);
     });
-    void expect(
+    await expect(
       shadowRoot.querySelector('[data-testid="close-requests"]')?.getAttribute('data-count'),
     ).toBe('0');
-    void expect(topLayer).toContainElement(dialog);
+    await expect(topLayer).toContainElement(dialog);
 
     await userEvent.keyboard('{Escape}');
     await waitForClosed(topLayer);
-    void expect(shadowRoot.activeElement).toBe(priorControl);
+    await expect(shadowRoot.activeElement).toBe(priorControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
     dialog = await waitForElement(topLayer, '[role="dialog"]', 'popover did not reopen');
     await userEvent.click(getCopyButton(dialog));
     await waitForClosed(topLayer);
-    void expect(shadowRoot.activeElement).toBe(priorControl);
+    await expect(shadowRoot.activeElement).toBe(priorControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
@@ -277,30 +277,30 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
     const closeRequestsBeforeRejection = Number(closeRequestOutput.getAttribute('data-count'));
     await userEvent.click(rejectedOutsideControl);
     await waitFor(
-      () =>
-        void expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
+      async () =>
+        await expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
           closeRequestsBeforeRejection + 1,
         ),
     );
-    void expect(topLayer).toContainElement(dialog);
-    void expect(canvasElement.ownerDocument.activeElement).toBe(rejectedOutsideControl);
+    await expect(topLayer).toContainElement(dialog);
+    await expect(canvasElement.ownerDocument.activeElement).toBe(rejectedOutsideControl);
     await userEvent.click(getCopyButton(dialog));
     await waitForClosed(topLayer);
-    void expect(shadowRoot.activeElement).toBe(priorControl);
+    await expect(shadowRoot.activeElement).toBe(priorControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
     await waitForElement(topLayer, '[role="dialog"]', 'popover did not reopen for delayed close');
     await userEvent.click(delayedOutsideControl);
     await waitForClosed(topLayer);
-    void expect(canvasElement.ownerDocument.activeElement).toBe(delayedOutsideControl);
+    await expect(canvasElement.ownerDocument.activeElement).toBe(delayedOutsideControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
     await waitForElement(topLayer, '[role="dialog"]', 'popover did not reopen for outside click');
     await userEvent.click(outsideControl);
     await waitForClosed(topLayer);
-    void expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
+    await expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
 
     const closeRequestsBeforeTouch = Number(closeRequestOutput.getAttribute('data-count'));
     const touchUser = userEvent.setup({ document: canvasElement.ownerDocument });
@@ -308,22 +308,22 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
     dialog = await waitForElement(topLayer, '[role="dialog"]', 'popover did not open for touch');
     const touchDialogRect = dialog.getBoundingClientRect();
     await touchUser.pointer({ keys: '[TouchA]', target: secondVerse });
-    void expect(firstVerse).toHaveClass('yv-v-selected');
-    void expect(secondVerse).toHaveClass('yv-v-selected');
-    void expect(dialog).toHaveAttribute('data-state', 'open');
-    void expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
+    await expect(firstVerse).toHaveClass('yv-v-selected');
+    await expect(secondVerse).toHaveClass('yv-v-selected');
+    await expect(dialog).toHaveAttribute('data-state', 'open');
+    await expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
       closeRequestsBeforeTouch,
     );
-    await waitFor(() => {
-      void expect(dialog.getBoundingClientRect().left).toBeGreaterThan(touchDialogRect.left + 20);
+    await waitFor(async () => {
+      await expect(dialog.getBoundingClientRect().left).toBeGreaterThan(touchDialogRect.left + 20);
     });
     await touchUser.pointer({ keys: '[TouchA>]', target: outsideControl });
-    void expect(dialog).toHaveAttribute('data-state', 'open');
+    await expect(dialog).toHaveAttribute('data-state', 'open');
     await touchUser.pointer({ keys: '[/TouchA]', target: outsideControl });
     await waitForClosed(topLayer);
-    void expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
+    await expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
       closeRequestsBeforeTouch + 1,
     );
-    void expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
+    await expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
   },
 };

From a632b7d755ae7518c70b6528975f80789c215b10 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 14:00:55 -0500
Subject: [PATCH 06/21] fix(ci): avoid Firefox matcher teardown rejections

---
 ...ionAuthButton.shadow-isolation.stories.tsx |  49 ++-
 ...ersion-picker.shadow-isolation.stories.tsx | 216 +++++++------
 ...compatibility.shadow-isolation.stories.tsx |  63 ++--
 ...oduction-seam.shadow-isolation.stories.tsx | 285 +++++++++---------
 ...adow-root-host-realistic-usage.stories.tsx |  63 ++--
 ...ign-in-dialog.shadow-isolation.stories.tsx | 156 +++++-----
 ...ction-popover.shadow-isolation.stories.tsx |  90 +++---
 7 files changed, 447 insertions(+), 475 deletions(-)

diff --git a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
index d32704c3..fc6cc43d 100644
--- a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
@@ -1,7 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { http, HttpResponse } from 'msw';
 import { createRoot, type Root } from 'react-dom/client';
-import { expect, waitFor } from 'storybook/test';
+import { waitFor } from 'storybook/test';
+import { expect } from 'vitest';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { waitForElement } from '../test/storybook-dom';
 import { YouVersionAuthButton } from './YouVersionAuthButton';
@@ -99,7 +100,7 @@ export const HostileGlobalButtonRule: Story = {
       'shadow host not rendered',
       browserWaitOptions,
     );
-    const shadowRoot = await waitFor(async () => {
+    const shadowRoot = await waitFor(() => {
       if (!host.shadowRoot) throw new Error('shadow root not attached');
       return host.shadowRoot;
     }, browserWaitOptions);
@@ -113,8 +114,8 @@ export const HostileGlobalButtonRule: Story = {
     const sdkBaseline = buttonStyleSnapshot(sdkButton);
     // Guard against a false positive where an unstyled browser-default button
     // also happens not to equal the hostile values below.
-    await expect(sdkBaseline.display).toBe('flex');
-    await expect(sdkBaseline.fontFamily).toContain('Inter');
+    expect(sdkBaseline.display).toBe('flex');
+    expect(sdkBaseline.fontFamily).toContain('Inter');
 
     const style = ownerDocument.createElement('style');
     style.textContent = HOSTILE_CSS;
@@ -122,21 +123,19 @@ export const HostileGlobalButtonRule: Story = {
     try {
       ownerDocument.head.append(style);
 
-      await waitFor(async () => {
-        await expect(ownerWindow.getComputedStyle(control).backgroundColor).toBe(
-          'rgb(185, 28, 28)',
-        );
-        await expect(ownerWindow.getComputedStyle(control, '::before').content).toBe('"HOSTILE"');
+      await waitFor(() => {
+        expect(ownerWindow.getComputedStyle(control).backgroundColor).toBe('rgb(185, 28, 28)');
+        expect(ownerWindow.getComputedStyle(control, '::before').content).toBe('"HOSTILE"');
       });
 
-      await expect(ownerWindow.getComputedStyle(host, '::before').content).toBe('none');
-      await expect(ownerWindow.getComputedStyle(host, '::before').display).toBe('none');
-      await expect(ownerWindow.getComputedStyle(host, '::after').content).toBe('none');
-      await expect(ownerWindow.getComputedStyle(host, '::after').display).toBe('none');
+      expect(ownerWindow.getComputedStyle(host, '::before').content).toBe('none');
+      expect(ownerWindow.getComputedStyle(host, '::before').display).toBe('none');
+      expect(ownerWindow.getComputedStyle(host, '::after').content).toBe('none');
+      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.
-      await expect(buttonStyleSnapshot(sdkButton)).toEqual(sdkBaseline);
+      expect(buttonStyleSnapshot(sdkButton)).toEqual(sdkBaseline);
     } finally {
       style.remove();
     }
@@ -153,7 +152,7 @@ export const SameOriginIframeDocument: Story = {
       'same-origin iframe not rendered',
       browserWaitOptions,
     );
-    const { iframeDocument, iframeWindow } = await waitFor(async () => {
+    const { iframeDocument, iframeWindow } = await waitFor(() => {
       const currentDocument = iframe.contentDocument;
       const currentWindow = currentDocument?.defaultView;
       if (!currentDocument?.body || !currentWindow) {
@@ -177,15 +176,15 @@ export const SameOriginIframeDocument: Story = {
         </ShadowRootHost>,
       );
 
-      await waitFor(async () => {
+      await waitFor(() => {
         const host = container.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');
-        await expect(host?.ownerDocument).toBe(iframeDocument);
-        await expect(shadowRoot?.adoptedStyleSheets).toHaveLength(1);
-        await expect(shadowRoot?.adoptedStyleSheets[0]).toBeInstanceOf(iframeWindow.CSSStyleSheet);
-        await expect(iframeWindow.getComputedStyle(content).display).toBe('flex');
+        expect(host?.ownerDocument).toBe(iframeDocument);
+        expect(shadowRoot?.adoptedStyleSheets).toHaveLength(1);
+        expect(shadowRoot?.adoptedStyleSheets[0]).toBeInstanceOf(iframeWindow.CSSStyleSheet);
+        expect(iframeWindow.getComputedStyle(content).display).toBe('flex');
       }, browserWaitOptions);
 
       const styleSheetPrototype = iframeWindow.CSSStyleSheet.prototype;
@@ -210,17 +209,17 @@ export const SameOriginIframeDocument: Story = {
           </ShadowRootHost>,
         );
 
-        await waitFor(async () => {
+        await waitFor(() => {
           const fallbackHost =
             fallbackContainer?.querySelector<HTMLDivElement>('[data-yv-shadow-host]');
           const shadowRoot = fallbackHost?.shadowRoot;
           const content = shadowRoot?.querySelector('[data-testid="iframe-fallback-content"]');
           const style = shadowRoot?.querySelector('style');
           if (!content || !style) throw new Error('iframe fallback content not mounted');
-          await expect(shadowRoot?.adoptedStyleSheets).toHaveLength(0);
-          await expect(style.getAttribute('data-href')).toBe('yv-sdk-shadow-styles');
-          await expect(style.getAttribute('data-precedence')).toBe('yv-sdk');
-          await expect(iframeWindow.getComputedStyle(content).display).toBe('flex');
+          expect(shadowRoot?.adoptedStyleSheets).toHaveLength(0);
+          expect(style.getAttribute('data-href')).toBe('yv-sdk-shadow-styles');
+          expect(style.getAttribute('data-precedence')).toBe('yv-sdk');
+          expect(iframeWindow.getComputedStyle(content).display).toBe('flex');
         }, browserWaitOptions);
       } finally {
         fallbackRoot?.unmount();
diff --git a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
index dad198f0..2b7e64d7 100644
--- a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
@@ -3,7 +3,8 @@ import { YouVersionProvider as HooksYouVersionProvider } from '@youversion/platf
 import { http, HttpResponse } from 'msw';
 import { useEffect, useState } from 'react';
 import { createPortal } from 'react-dom';
-import { expect, userEvent, waitFor, within } from 'storybook/test';
+import { userEvent, waitFor, within } from 'storybook/test';
+import { expect } from 'vitest';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { globalHandlers } from '../test/mocks/handlers';
 import { waitForElement, waitForShadowRoot } from '../test/storybook-dom';
@@ -118,7 +119,7 @@ async function getTrigger(root: ShadowRoot): Promise<HTMLElement> {
 async function openPicker(container: ParentNode) {
   const root = await waitForShadowRoot(container);
   const trigger = await getTrigger(root);
-  await expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+  expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
   await userEvent.click(trigger);
   const topLayer = await waitForElement<HTMLElement>(
     root,
@@ -130,7 +131,7 @@ async function openPicker(container: ParentNode) {
     '[data-slot="popover-content"]',
     'picker panel not rendered in local top layer',
   );
-  await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(true));
+  await waitFor(() => expect(topLayer.matches(':popover-open')).toBe(true));
   return { root, trigger, topLayer, panel };
 }
 
@@ -183,35 +184,35 @@ export const TopLayerEscapesClippingAndPreservesSemantics: Story = {
     );
     const { root, trigger, topLayer, panel } = await openPicker(clippingContainer);
 
-    await expect(topLayer.getRootNode()).toBe(root);
-    await expect(panel.getRootNode()).toBe(root);
-    await expect(
+    expect(topLayer.getRootNode()).toBe(root);
+    expect(panel.getRootNode()).toBe(root);
+    expect(
       canvasElement.ownerDocument.body.querySelector('[data-yv-shadow-overlay-host]'),
     ).toBeNull();
 
     const clippingRect = clippingContainer.getBoundingClientRect();
     const panelRect = panel.getBoundingClientRect();
-    await expect(panelRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
+    expect(panelRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
     const viewport = canvasElement.ownerDocument.defaultView;
     if (!viewport) throw new Error('story window not available');
-    await expect(panelRect.top).toBeGreaterThanOrEqual(16);
-    await expect(panelRect.left).toBeGreaterThanOrEqual(16);
-    await expect(panelRect.bottom).toBeLessThanOrEqual(viewport.innerHeight - 16);
-    await expect(panelRect.right).toBeLessThanOrEqual(viewport.innerWidth - 16);
+    expect(panelRect.top).toBeGreaterThanOrEqual(16);
+    expect(panelRect.left).toBeGreaterThanOrEqual(16);
+    expect(panelRect.bottom).toBeLessThanOrEqual(viewport.innerHeight - 16);
+    expect(panelRect.right).toBeLessThanOrEqual(viewport.innerWidth - 16);
 
     const sampleX = panelRect.left + panelRect.width / 2;
     const sampleY = Math.max(panelRect.top + 2, clippingRect.bottom + 2);
     if (sampleY >= panelRect.bottom) throw new Error('panel did not extend beyond its ancestor');
     const hit = root.elementFromPoint(sampleX, sampleY);
-    await expect(hit === panel || (hit !== null && panel.contains(hit))).toBe(true);
+    expect(hit === panel || (hit !== null && panel.contains(hit))).toBe(true);
 
     // SAFETY: The reflected-ARIA property is still a draft; verify browser support before use.
     const reflectedControls = (
       trigger as HTMLElement & { ariaControlsElements?: readonly Element[] }
     ).ariaControlsElements;
     if (!reflectedControls) throw new Error('browser did not expose ariaControlsElements');
-    await expect(trigger.getAttribute('aria-controls')).toBe(panel.id);
-    await expect(reflectedControls).toEqual([panel]);
+    expect(trigger.getAttribute('aria-controls')).toBe(panel.id);
+    expect(reflectedControls).toEqual([panel]);
   },
 };
 
@@ -250,7 +251,7 @@ export const InlineControlIsClippedByItsAncestor: Story = {
       'clipping container not rendered',
     );
     const root = await waitForShadowRoot(clippingContainer);
-    await expect(root.querySelector('[data-yv-shadow-inline-overlay]')).toBeNull();
+    expect(root.querySelector('[data-yv-shadow-inline-overlay]')).toBeNull();
     await userEvent.click(await getTrigger(root));
     const inlineContainer = await waitForElement<HTMLElement>(
       root,
@@ -265,25 +266,21 @@ export const InlineControlIsClippedByItsAncestor: Story = {
 
     const clippingRect = clippingContainer.getBoundingClientRect();
     const panelRect = panel.getBoundingClientRect();
-    await expect(panelRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
+    expect(panelRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
     const sampleX = panelRect.left + panelRect.width / 2;
     const visibleSampleY = Math.max(panelRect.top + 2, clippingRect.top + 2);
     if (visibleSampleY >= clippingRect.bottom) {
       throw new Error('panel has no visible area inside its clipping ancestor');
     }
     const visibleHit = root.elementFromPoint(sampleX, visibleSampleY);
-    await expect(visibleHit === panel || (visibleHit !== null && panel.contains(visibleHit))).toBe(
-      true,
-    );
+    expect(visibleHit === panel || (visibleHit !== null && panel.contains(visibleHit))).toBe(true);
 
     const clippedSampleY = Math.max(panelRect.top + 2, clippingRect.bottom + 2);
     if (clippedSampleY >= panelRect.bottom) {
       throw new Error('panel did not extend beyond its clipping ancestor');
     }
     const clippedHit = root.elementFromPoint(sampleX, clippedSampleY);
-    await expect(clippedHit === panel || (clippedHit !== null && panel.contains(clippedHit))).toBe(
-      false,
-    );
+    expect(clippedHit === panel || (clippedHit !== null && panel.contains(clippedHit))).toBe(false);
   },
 };
 
@@ -303,9 +300,9 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
       'outside control not rendered',
     );
     const { root, trigger, topLayer, panel } = await openPicker(canvasElement);
-    await waitFor(async () => {
+    await waitFor(() => {
       const focused = root.activeElement;
-      await expect(focused !== null && panel.contains(focused)).toBe(true);
+      expect(focused !== null && panel.contains(focused)).toBe(true);
     });
     const exitAnimationStyle = canvasElement.ownerDocument.createElement('style');
     exitAnimationStyle.textContent = `
@@ -329,24 +326,23 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
     `;
     try {
       canvasElement.ownerDocument.head.append(hostileStyle);
-      await waitFor(
-        async () =>
-          await expect(getComputedStyle(outsideControl).backgroundColor).toBe('rgb(185, 28, 28)'),
+      await waitFor(() =>
+        expect(getComputedStyle(outsideControl).backgroundColor).toBe('rgb(185, 28, 28)'),
       );
-      await expect(styleSnapshot(panel)).toEqual(baseline);
+      expect(styleSnapshot(panel)).toEqual(baseline);
     } finally {
       hostileStyle.remove();
     }
 
     await userEvent.click(outsideControl);
-    await waitFor(async () => {
-      await expect(panel).toHaveAttribute('data-state', 'closed');
-      await expect(topLayer).toContainElement(panel);
-      await expect(topLayer.matches(':popover-open')).toBe(true);
+    await waitFor(() => {
+      void expect(panel).toHaveAttribute('data-state', 'closed');
+      void expect(topLayer).toContainElement(panel);
+      expect(topLayer.matches(':popover-open')).toBe(true);
     });
-    await waitFor(async () => {
-      await expect(topLayer.querySelector('[data-slot="popover-content"]')).toBeNull();
-      await expect(topLayer.matches(':popover-open')).toBe(false);
+    await waitFor(() => {
+      expect(topLayer.querySelector('[data-slot="popover-content"]')).toBeNull();
+      expect(topLayer.matches(':popover-open')).toBe(false);
     });
 
     await userEvent.click(trigger);
@@ -355,9 +351,9 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
       '[data-slot="popover-content"]',
       'picker panel did not reopen',
     );
-    await waitFor(async () => {
+    await waitFor(() => {
       const activeElement = root.activeElement;
-      await expect(activeElement !== null && reopenedPanel.contains(activeElement)).toBe(true);
+      expect(activeElement !== null && reopenedPanel.contains(activeElement)).toBe(true);
     });
 
     const focused = root.activeElement;
@@ -366,16 +362,16 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
       new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, composed: true }),
     );
     trigger.click();
-    await waitFor(async () => {
-      await expect(topLayer.matches(':popover-open')).toBe(true);
-      await expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
+    await waitFor(() => {
+      expect(topLayer.matches(':popover-open')).toBe(true);
+      expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
     });
 
     await userEvent.keyboard('{Escape}');
-    await waitFor(async () => {
-      await expect(topLayer.querySelector('[data-slot="popover-content"]')).toBeNull();
-      await expect(topLayer.matches(':popover-open')).toBe(false);
-      await expect(root.activeElement).toBe(trigger);
+    await waitFor(() => {
+      expect(topLayer.querySelector('[data-slot="popover-content"]')).toBeNull();
+      expect(topLayer.matches(':popover-open')).toBe(false);
+      expect(root.activeElement).toBe(trigger);
     });
   },
 };
@@ -403,7 +399,7 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
     if (!hostControl) throw new Error('hostile inheritance control not rendered');
 
     const { root, trigger, panel } = await openPicker(canvasElement);
-    await waitFor(async () => await expect(trigger).toHaveTextContent('NIV'));
+    await waitFor(() => void expect(trigger).toHaveTextContent('NIV'));
     const wrapper = root.querySelector<HTMLElement>('[data-yv-shadow-content-wrapper]');
     const heading = panel.querySelector<HTMLElement>('h2');
     const inputGroup = panel.querySelector<HTMLElement>('[data-slot="input-group"]');
@@ -413,9 +409,9 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
     const panelGeometry = geometrySnapshot(panel);
     const inputGeometry = geometrySnapshot(inputGroup);
     const headingTypography = typographySnapshot(heading, ownerWindow);
-    await expect(headingTypography.fontFamily).toContain('Inter');
-    await expect(ownerWindow.getComputedStyle(trigger).direction).toBe('rtl');
-    await expect(ownerWindow.getComputedStyle(wrapper).direction).toBe('ltr');
+    expect(headingTypography.fontFamily).toContain('Inter');
+    expect(ownerWindow.getComputedStyle(trigger).direction).toBe('rtl');
+    expect(ownerWindow.getComputedStyle(wrapper).direction).toBe('ltr');
 
     await userEvent.click(within(panel).getByRole('button', { name: /select a language/i }));
     const languageTabs = await waitForElement<HTMLElement>(
@@ -433,8 +429,8 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
     }
     const languageTabsInlineSize = languageTabs.offsetWidth;
     const languageInputRadius = ownerWindow.getComputedStyle(languageInputGroup).borderRadius;
-    await expect(languageTabsInlineSize).toBe(languageTabsContainer.clientWidth - 32);
-    await expect(languageInputRadius).toBe('30px');
+    expect(languageTabsInlineSize).toBe(languageTabsContainer.clientWidth - 32);
+    expect(languageInputRadius).toBe('30px');
 
     const hostileStyle = ownerDocument.createElement('style');
     hostileStyle.textContent = `
@@ -460,39 +456,39 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
 
     try {
       ownerDocument.head.append(hostileStyle);
-      await waitFor(async () => {
+      await waitFor(() => {
         const controlStyle = ownerWindow.getComputedStyle(hostControl);
-        await expect(controlStyle.writingMode).toBe('vertical-rl');
-        await expect(controlStyle.textOrientation).toBe('upright');
-        await expect(controlStyle.color).toBe('rgb(185, 28, 28)');
-        await expect(controlStyle.fontFamily).toContain('fantasy');
-        await expect(controlStyle.fontSize).toBe('32px');
-        await expect(controlStyle.letterSpacing).toBe('16px');
-        await expect(controlStyle.lineHeight).toBe('96px');
-        await expect(controlStyle.wordSpacing).toBe('32px');
-        await expect(controlStyle.borderRadius).toBe('0px');
+        expect(controlStyle.writingMode).toBe('vertical-rl');
+        expect(controlStyle.textOrientation).toBe('upright');
+        expect(controlStyle.color).toBe('rgb(185, 28, 28)');
+        expect(controlStyle.fontFamily).toContain('fantasy');
+        expect(controlStyle.fontSize).toBe('32px');
+        expect(controlStyle.letterSpacing).toBe('16px');
+        expect(controlStyle.lineHeight).toBe('96px');
+        expect(controlStyle.wordSpacing).toBe('32px');
+        expect(controlStyle.borderRadius).toBe('0px');
       });
 
       const wrapperStyle = ownerWindow.getComputedStyle(wrapper);
       const headingStyle = ownerWindow.getComputedStyle(heading);
       const panelStyle = ownerWindow.getComputedStyle(panel);
-      await expect(wrapperStyle.direction).toBe('ltr');
-      await expect(wrapperStyle.writingMode).toBe('horizontal-tb');
-      await expect(wrapperStyle.textOrientation).toBe('mixed');
-      await expect(headingStyle.direction).toBe('rtl');
-      await expect(headingStyle.writingMode).toBe('horizontal-tb');
-      await expect(headingStyle.textOrientation).toBe('mixed');
-      await expect(typographySnapshot(heading, ownerWindow)).toEqual(headingTypography);
-      await expect(panelStyle.getPropertyValue('--yv-spacing').trim()).toBe('.25rem');
-      await expect(panelStyle.getPropertyValue('--spacing').trim()).toBe('.25rem');
-      await expect(panelStyle.getPropertyValue('--yv-radius').trim()).toBe('2rem');
-      await expect(languageTabs.offsetWidth).toBe(languageTabsInlineSize);
-      await expect(ownerWindow.getComputedStyle(languageInputGroup).borderRadius).toBe(
+      expect(wrapperStyle.direction).toBe('ltr');
+      expect(wrapperStyle.writingMode).toBe('horizontal-tb');
+      expect(wrapperStyle.textOrientation).toBe('mixed');
+      expect(headingStyle.direction).toBe('rtl');
+      expect(headingStyle.writingMode).toBe('horizontal-tb');
+      expect(headingStyle.textOrientation).toBe('mixed');
+      expect(typographySnapshot(heading, ownerWindow)).toEqual(headingTypography);
+      expect(panelStyle.getPropertyValue('--yv-spacing').trim()).toBe('.25rem');
+      expect(panelStyle.getPropertyValue('--spacing').trim()).toBe('.25rem');
+      expect(panelStyle.getPropertyValue('--yv-radius').trim()).toBe('2rem');
+      expect(languageTabs.offsetWidth).toBe(languageTabsInlineSize);
+      expect(ownerWindow.getComputedStyle(languageInputGroup).borderRadius).toBe(
         languageInputRadius,
       );
-      await expect(geometrySnapshot(trigger)).toEqual(triggerGeometry);
-      await expect(geometrySnapshot(panel)).toEqual(panelGeometry);
-      await expect(geometrySnapshot(inputGroup)).toEqual(inputGeometry);
+      expect(geometrySnapshot(trigger)).toEqual(triggerGeometry);
+      expect(geometrySnapshot(panel)).toEqual(panelGeometry);
+      expect(geometrySnapshot(inputGroup)).toEqual(inputGeometry);
     } finally {
       hostileStyle.remove();
     }
@@ -516,8 +512,8 @@ export const MultiplePickersCreateIndependentLazyContainers: Story = {
     if (!first || !second) throw new Error('picker harness not rendered');
     const firstRoot = await waitForShadowRoot(first);
     const secondRoot = await waitForShadowRoot(second);
-    await expect(firstRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
-    await expect(secondRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    expect(firstRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    expect(secondRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
 
     const firstTrigger = await getTrigger(firstRoot);
     const secondTrigger = await getTrigger(secondRoot);
@@ -527,7 +523,7 @@ export const MultiplePickersCreateIndependentLazyContainers: Story = {
       '[data-yv-shadow-local-overlay]',
       'first local container not created',
     );
-    await expect(secondRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    expect(secondRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
 
     await userEvent.click(secondTrigger);
     const secondTopLayer = await waitForElement<HTMLElement>(
@@ -535,12 +531,10 @@ export const MultiplePickersCreateIndependentLazyContainers: Story = {
       '[data-yv-shadow-local-overlay]',
       'second local container not created',
     );
-    await waitFor(async () => {
-      await expect(firstTopLayer.matches(':popover-open')).toBe(false);
-      await expect(secondTopLayer.matches(':popover-open')).toBe(true);
-      await expect(secondTopLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(
-        1,
-      );
+    await waitFor(() => {
+      expect(firstTopLayer.matches(':popover-open')).toBe(false);
+      expect(secondTopLayer.matches(':popover-open')).toBe(true);
+      expect(secondTopLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
     });
   },
 };
@@ -552,10 +546,10 @@ export const MultiplePopoversShareOneIslandContainer: Story = {
     const triggers = Array.from(
       root.querySelectorAll<HTMLElement>('[data-slot="popover-trigger"]'),
     );
-    await expect(triggers).toHaveLength(2);
+    expect(triggers).toHaveLength(2);
     const [firstTrigger, secondTrigger] = triggers;
     if (!firstTrigger || !secondTrigger) throw new Error('picker triggers not rendered');
-    await expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
 
     await userEvent.click(firstTrigger);
     const topLayer = await waitForElement<HTMLElement>(
@@ -563,18 +557,18 @@ export const MultiplePopoversShareOneIslandContainer: Story = {
       '[data-yv-shadow-local-overlay]',
       'shared island container not created',
     );
-    await waitFor(async () => {
-      await expect(firstTrigger).toHaveAttribute('aria-expanded', 'true');
-      await expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
+    await waitFor(() => {
+      void expect(firstTrigger).toHaveAttribute('aria-expanded', 'true');
+      expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
     });
 
     await userEvent.click(secondTrigger);
-    await waitFor(async () => {
-      await expect(firstTrigger).toHaveAttribute('aria-expanded', 'false');
-      await expect(secondTrigger).toHaveAttribute('aria-expanded', 'true');
-      await expect(topLayer.matches(':popover-open')).toBe(true);
-      await expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
-      await expect(root.querySelectorAll('[data-yv-shadow-local-overlay]')).toHaveLength(1);
+    await waitFor(() => {
+      void expect(firstTrigger).toHaveAttribute('aria-expanded', 'false');
+      void expect(secondTrigger).toHaveAttribute('aria-expanded', 'true');
+      expect(topLayer.matches(':popover-open')).toBe(true);
+      expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
+      expect(root.querySelectorAll('[data-yv-shadow-local-overlay]')).toHaveLength(1);
     });
 
     const panel = topLayer.querySelector<HTMLElement>('[data-slot="popover-content"]');
@@ -582,8 +576,8 @@ export const MultiplePopoversShareOneIslandContainer: Story = {
     const panelRect = panel.getBoundingClientRect();
     const viewport = canvasElement.ownerDocument.defaultView;
     if (!viewport) throw new Error('story window not available');
-    await expect(panelRect.top).toBeGreaterThanOrEqual(16);
-    await expect(panelRect.bottom).toBeLessThanOrEqual(viewport.innerHeight - 16);
+    expect(panelRect.top).toBeGreaterThanOrEqual(16);
+    expect(panelRect.bottom).toBeLessThanOrEqual(viewport.innerHeight - 16);
   },
 };
 
@@ -636,16 +630,16 @@ export const PanelTracksAncestorScrollAndVersionListScrollsInternally: Story = {
     scrollAncestor.scrollTop += scrollDelta;
     scrollAncestor.dispatchEvent(new Event('scroll', { bubbles: true }));
 
-    await waitFor(async () => {
+    await waitFor(() => {
       const triggerRectAfter = trigger.getBoundingClientRect();
-      await expect(
-        Math.abs(triggerRectAfter.top - (triggerRectBefore.top - scrollDelta)),
-      ).toBeLessThan(2);
+      expect(Math.abs(triggerRectAfter.top - (triggerRectBefore.top - scrollDelta))).toBeLessThan(
+        2,
+      );
     });
     const triggerRectAfter = trigger.getBoundingClientRect();
     const panelRectAfter = panel.getBoundingClientRect();
     const offsetAfter = panelRectAfter.top - triggerRectAfter.bottom;
-    await expect(Math.abs(offsetAfter - offsetBefore)).toBeLessThanOrEqual(8);
+    expect(Math.abs(offsetAfter - offsetBefore)).toBeLessThanOrEqual(8);
 
     // Part 2: the version list scrolls internally within the panel. Locate
     // the scroll region via the unconditional "All Versions" marker's
@@ -676,8 +670,8 @@ export const PanelTracksAncestorScrollAndVersionListScrollsInternally: Story = {
     scrollRegion.scrollTop = scrollRegion.scrollHeight;
     scrollRegion.dispatchEvent(new Event('scroll', { bubbles: true }));
 
-    await waitFor(async () => {
-      await expect(scrollRegion.scrollTop).toBeGreaterThan(initialScrollTop);
+    await waitFor(() => {
+      expect(scrollRegion.scrollTop).toBeGreaterThan(initialScrollTop);
     });
 
     const lastItemRect = lastItem.getBoundingClientRect();
@@ -685,14 +679,14 @@ export const PanelTracksAncestorScrollAndVersionListScrollsInternally: Story = {
       lastItemRect.left + lastItemRect.width / 2,
       lastItemRect.top + lastItemRect.height / 2,
     );
-    await expect(hit === lastItem || (hit !== null && lastItem.contains(hit))).toBe(true);
+    expect(hit === lastItem || (hit !== null && lastItem.contains(hit))).toBe(true);
   },
 };
 
 export const SameOriginIframeTopLayerRemainsInteractive: Story = {
   render: () => <SameOriginIframeHarness />,
   play: async ({ canvasElement }) => {
-    const { iframe, iframeDocument } = await waitFor(async () => {
+    const { iframe, iframeDocument } = await waitFor(() => {
       const currentIframe =
         canvasElement.querySelector<HTMLIFrameElement>('[data-testid="iframe"]');
       const currentDocument = currentIframe?.contentDocument;
@@ -712,7 +706,7 @@ export const SameOriginIframeTopLayerRemainsInteractive: Story = {
       '[data-yv-shadow-local-overlay]',
       'iframe top-layer container not created',
     );
-    const portalWrapper = await waitFor(async () => {
+    const portalWrapper = await waitFor(() => {
       const element = topLayer.firstElementChild;
       // SAFETY: A same-origin iframe exposes its realm's HTMLElement constructor on its Window.
       const frameWindow = iframe.contentWindow as
@@ -725,7 +719,7 @@ export const SameOriginIframeTopLayerRemainsInteractive: Story = {
     });
     const portalWindow = portalWrapper.ownerDocument.defaultView;
     if (!portalWindow) throw new Error('iframe portal window not available');
-    await expect(portalWindow.getComputedStyle(portalWrapper).pointerEvents).toBe('auto');
+    expect(portalWindow.getComputedStyle(portalWrapper).pointerEvents).toBe('auto');
 
     const input = await waitForElement<HTMLInputElement>(
       topLayer,
@@ -733,14 +727,14 @@ export const SameOriginIframeTopLayerRemainsInteractive: Story = {
       'iframe picker input not rendered',
     );
     await userEvent.click(input);
-    await expect(componentRoot.activeElement).toBe(input);
+    expect(componentRoot.activeElement).toBe(input);
 
     const panel = topLayer.querySelector<HTMLElement>('[data-slot="popover-content"]');
     if (!panel) throw new Error('iframe picker panel not rendered');
     const panelRect = panel.getBoundingClientRect();
     const frameWindow = iframe.contentWindow;
     if (!frameWindow) throw new Error('iframe window not available');
-    await expect(panelRect.top).toBeGreaterThanOrEqual(16);
-    await expect(panelRect.bottom).toBeLessThanOrEqual(frameWindow.innerHeight - 16);
+    expect(panelRect.top).toBeGreaterThanOrEqual(16);
+    expect(panelRect.bottom).toBeLessThanOrEqual(frameWindow.innerHeight - 16);
   },
 };
diff --git a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
index c2351473..3a00fc1b 100644
--- a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
@@ -2,7 +2,8 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useTheme } from '@youversion/platform-react-hooks';
 import { http, HttpResponse } from 'msw';
 import { useCallback, useLayoutEffect, useRef, useState } from 'react';
-import { expect, userEvent, waitFor } from 'storybook/test';
+import { userEvent, waitFor } from 'storybook/test';
+import { expect } from 'vitest';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { waitForElement } from '../test/storybook-dom';
 import { Textarea } from './ui/textarea';
@@ -37,7 +38,7 @@ function requireElement<ElementType extends Element>(
 }
 
 async function requireShadowHost(container: ParentNode): Promise<HTMLElement> {
-  return waitFor(async () => {
+  return waitFor(() => {
     const host = requireElement<HTMLElement>(
       container,
       '[data-yv-shadow-host]',
@@ -187,13 +188,13 @@ export const FormsAndExternalRelationshipsStopAtTheTreeScope: Story = {
       'isolated textarea not rendered',
     );
 
-    await expect(textarea.form).toBeNull();
-    await expect(form.elements.namedItem('notes')).toBeNull();
-    await expect(new FormData(form).has('notes')).toBe(false);
+    expect(textarea.form).toBeNull();
+    expect(form.elements.namedItem('notes')).toBeNull();
+    expect(new FormData(form).has('notes')).toBe(false);
 
-    await expect(label.control).toBeNull();
+    expect(label.control).toBeNull();
     await userEvent.click(label);
-    await expect(root.activeElement).not.toBe(textarea);
+    expect(root.activeElement).not.toBe(textarea);
 
     type ReflectedAriaElement = HTMLElement & {
       ariaLabelledByElements?: readonly Element[];
@@ -208,10 +209,10 @@ export const FormsAndExternalRelationshipsStopAtTheTreeScope: Story = {
       throw new Error('browser did not expose ariaDescribedByElements');
     }
 
-    await expect(textarea.getAttribute('aria-labelledby')).toBe('external-name');
-    await expect(textarea.getAttribute('aria-describedby')).toBe('external-description');
-    await expect(reflectedTextarea.ariaLabelledByElements).toEqual([]);
-    await expect(reflectedTextarea.ariaDescribedByElements).toEqual([]);
+    expect(textarea.getAttribute('aria-labelledby')).toBe('external-name');
+    expect(textarea.getAttribute('aria-describedby')).toBe('external-description');
+    expect(reflectedTextarea.ariaLabelledByElements).toEqual([]);
+    expect(reflectedTextarea.ariaDescribedByElements).toEqual([]);
   },
 };
 
@@ -278,7 +279,7 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
   name: 'Events, refs, and DOM queries expose different views',
   render: () => <AutomaticButtonHarness />,
   play: async ({ canvasElement }) => {
-    const observer = await waitFor(async () =>
+    const observer = await waitFor(() =>
       requireElement<HTMLElement>(
         canvasElement,
         '[data-testid="consumer-observer"]',
@@ -293,8 +294,8 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
       'isolated auth button not rendered',
     );
 
-    await expect(canvasElement.querySelector('[data-testid="isolated-auth-button"]')).toBeNull();
-    await expect(root.querySelector('[data-testid="isolated-auth-button"]')).toBe(button);
+    expect(canvasElement.querySelector('[data-testid="isolated-auth-button"]')).toBeNull();
+    expect(root.querySelector('[data-testid="isolated-auth-button"]')).toBe(button);
     const firstLayoutEvidence = requireElement<HTMLOutputElement>(
       canvasElement,
       '[data-testid="first-layout-ref-state"]',
@@ -316,9 +317,9 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
       'consumer current target evidence not rendered',
     );
 
-    await expect(firstLayoutEvidence).toHaveTextContent('null');
-    await expect(firstLayoutEvidence).toHaveAttribute('hidden');
-    await waitFor(async () => await expect(forwardedRefEvidence.observedNode).toBe(button));
+    void expect(firstLayoutEvidence).toHaveTextContent('null');
+    void expect(firstLayoutEvidence).toHaveAttribute('hidden');
+    await waitFor(() => expect(forwardedRefEvidence.observedNode).toBe(button));
 
     const clickTarget = requireElement<HTMLDivElement>(
       button,
@@ -338,12 +339,12 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
 
     await userEvent.click(clickTarget);
 
-    await expect(outsideTarget).toBe(host);
-    await expect(outsidePath[0]).toBe(clickTarget);
-    await expect(outsidePath).toContain(button);
-    await expect(outsidePath).toContain(host);
-    await expect(consumerTargetEvidence.observedNode).toBe(clickTarget);
-    await expect(consumerCurrentTargetEvidence.observedNode).toBe(button);
+    expect(outsideTarget).toBe(host);
+    expect(outsidePath[0]).toBe(clickTarget);
+    expect(outsidePath).toContain(button);
+    expect(outsidePath).toContain(host);
+    expect(consumerTargetEvidence.observedNode).toBe(clickTarget);
+    expect(consumerCurrentTargetEvidence.observedNode).toBe(button);
   },
 };
 
@@ -383,9 +384,9 @@ export const NestedRootsRequireTraversalAndRetargetAtEveryBoundary: Story = {
       'nested auth button not rendered',
     );
 
-    await expect(canvasElement.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
-    await expect(outerRoot.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
-    await expect(innerRoot.querySelector('[data-testid="nested-auth-button"]')).toBe(button);
+    expect(canvasElement.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
+    expect(outerRoot.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
+    expect(innerRoot.querySelector('[data-testid="nested-auth-button"]')).toBe(button);
 
     let outerScopeTarget: EventTarget | null = null;
     let documentScopeTarget: EventTarget | null = null;
@@ -408,10 +409,10 @@ export const NestedRootsRequireTraversalAndRetargetAtEveryBoundary: Story = {
 
     await userEvent.click(button);
 
-    await expect(outerScopeTarget).toBe(innerHost);
-    await expect(documentScopeTarget).toBe(outerHost);
-    await expect(composedPath[0]).toBe(button);
-    await expect(composedPath).toContain(innerHost);
-    await expect(composedPath).toContain(outerHost);
+    expect(outerScopeTarget).toBe(innerHost);
+    expect(documentScopeTarget).toBe(outerHost);
+    expect(composedPath[0]).toBe(button);
+    expect(composedPath).toContain(innerHost);
+    expect(composedPath).toContain(outerHost);
   },
 };
diff --git a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
index 43e469dd..d6c2d119 100644
--- a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
@@ -1,7 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { http, HttpResponse } from 'msw';
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { expect, spyOn, userEvent, waitFor } from 'storybook/test';
+import { spyOn, userEvent, waitFor } from 'storybook/test';
+import { expect } from 'vitest';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { waitForElement, waitForShadowRoot } from '../test/storybook-dom';
 import { HighlightPermissionDialog } from './highlight-permission-dialog';
@@ -217,11 +218,11 @@ function getPermissionDialog(topLayer: HTMLElement): HTMLElement | null {
   );
 }
 
-async function expectOverlayAboveAtOverlap(
+function expectOverlayAboveAtOverlap(
   root: ShadowRoot,
   expectedTop: HTMLElement,
   underneath: HTMLElement,
-): Promise<void> {
+): void {
   const topRect = expectedTop.getBoundingClientRect();
   const underneathRect = underneath.getBoundingClientRect();
   const overlapLeft = Math.max(topRect.left, underneathRect.left);
@@ -229,14 +230,14 @@ async function expectOverlayAboveAtOverlap(
   const overlapTop = Math.max(topRect.top, underneathRect.top);
   const overlapBottom = Math.min(topRect.bottom, underneathRect.bottom);
 
-  await expect(overlapRight).toBeGreaterThan(overlapLeft);
-  await expect(overlapBottom).toBeGreaterThan(overlapTop);
+  expect(overlapRight).toBeGreaterThan(overlapLeft);
+  expect(overlapBottom).toBeGreaterThan(overlapTop);
 
   const hit = root.elementFromPoint(
     overlapLeft + (overlapRight - overlapLeft) / 2,
     overlapTop + (overlapBottom - overlapTop) / 2,
   );
-  await expect(hit === expectedTop || (hit !== null && expectedTop.contains(hit))).toBe(true);
+  expect(hit === expectedTop || (hit !== null && expectedTop.contains(hit))).toBe(true);
 }
 
 function placeOverlayCenterUnderneath(
@@ -310,7 +311,7 @@ async function getPrimaryHarness(canvasElement: HTMLElement): Promise<PrimaryHar
   const root = await waitForShadowRoot(primaryIsland);
   const contentWrapper = root.querySelector<HTMLElement>('[data-yv-shadow-content-wrapper]');
   if (!contentWrapper) throw new Error('shadow content wrapper not rendered');
-  await expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+  expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
   return { contentWrapper, primaryIsland, root };
 }
 
@@ -331,7 +332,7 @@ async function openVerseActionPopover(
     'verse action popover not rendered',
     productionWaitOptions,
   );
-  await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(true));
+  await waitFor(() => expect(topLayer.matches(':popover-open')).toBe(true));
   return { topLayer, versePopover };
 }
 
@@ -342,7 +343,7 @@ async function openPermissionDialogFromVerseAction(
   const swatch = versePopover.querySelector<HTMLButtonElement>('[role="group"] button');
   if (!swatch) throw new Error('highlight swatch not rendered');
   await userEvent.click(swatch);
-  return waitFor(async () => {
+  return waitFor(() => {
     const dialog = getPermissionDialog(topLayer);
     if (!dialog) throw new Error('highlight permission dialog not rendered');
     return dialog;
@@ -422,36 +423,36 @@ export const PopoverOpensDialogEvidence: Story = {
           opened.topLayer,
           opened.versePopover,
         );
-        await expect(opened.versePopover.getRootNode()).toBe(root);
-        await expect(permissionDialog.getRootNode()).toBe(root);
+        expect(opened.versePopover.getRootNode()).toBe(root);
+        expect(permissionDialog.getRootNode()).toBe(root);
         const restorePosition = placeOverlayCenterUnderneath(opened.versePopover, permissionDialog);
         try {
-          await expectOverlayAboveAtOverlap(root, permissionDialog, opened.versePopover);
+          expectOverlayAboveAtOverlap(root, permissionDialog, opened.versePopover);
         } finally {
           restorePosition();
         }
-        await waitFor(async () => {
+        await waitFor(() => {
           const focused = root.activeElement;
-          await expect(focused !== null && permissionDialog.contains(focused)).toBe(true);
+          expect(focused !== null && permissionDialog.contains(focused)).toBe(true);
         }, productionWaitOptions);
-        await expect(contentWrapper.inert).toBe(true);
-        await expect(opened.versePopover).toHaveAttribute('data-state', 'open');
+        expect(contentWrapper.inert).toBe(true);
+        void expect(opened.versePopover).toHaveAttribute('data-state', 'open');
       });
 
       await step('Escape dismisses one nested overlay at a time', async () => {
         await userEvent.keyboard('{Escape}');
-        await waitFor(async () => {
-          await expect(getPermissionDialog(topLayer)).toBeNull();
-          await expect(topLayer.querySelector('[data-slot="verse-action-popover"]')).not.toBeNull();
-          await expect(contentWrapper.inert).toBe(false);
+        await waitFor(() => {
+          expect(getPermissionDialog(topLayer)).toBeNull();
+          expect(topLayer.querySelector('[data-slot="verse-action-popover"]')).not.toBeNull();
+          expect(contentWrapper.inert).toBe(false);
           const focused = root.activeElement;
-          await expect(focused !== null && versePopover.contains(focused)).toBe(true);
+          expect(focused !== null && versePopover.contains(focused)).toBe(true);
         }, productionWaitOptions);
         await userEvent.keyboard('{Escape}');
-        await waitFor(async () => {
-          await expect(topLayer.querySelector('[data-slot="verse-action-popover"]')).toBeNull();
-          await expect(topLayer.matches(':popover-open')).toBe(false);
-          await expect(root.activeElement).toBe(priorControl);
+        await waitFor(() => {
+          expect(topLayer.querySelector('[data-slot="verse-action-popover"]')).toBeNull();
+          expect(topLayer.matches(':popover-open')).toBe(false);
+          expect(root.activeElement).toBe(priorControl);
         }, productionWaitOptions);
       });
 
@@ -474,26 +475,24 @@ export const PopoverOpensDialogEvidence: Story = {
         if (!dialogOverlay) throw new Error('dialog overlay not rendered');
         closeAllOverlays.click();
         closeAllOverlays.click();
-        await waitFor(async () => {
-          await expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
-          await expect(permissionDialog).toHaveAttribute('data-state', 'closed');
+        await waitFor(() => {
+          void expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
+          void expect(permissionDialog).toHaveAttribute('data-state', 'closed');
         }, productionWaitOptions);
         finishAnimations(opened.versePopover);
-        await waitFor(async () => {
-          await expect(
-            opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
-          ).toBeNull();
-          await expect(getPermissionDialog(opened.topLayer)).toBe(permissionDialog);
-          await expect(contentWrapper.inert).toBe(true);
+        await waitFor(() => {
+          expect(opened.topLayer.querySelector('[data-slot="verse-action-popover"]')).toBeNull();
+          expect(getPermissionDialog(opened.topLayer)).toBe(permissionDialog);
+          expect(contentWrapper.inert).toBe(true);
         }, productionWaitOptions);
         finishAnimations(permissionDialog);
         finishAnimations(dialogOverlay);
-        await waitFor(async () => {
-          await expect(getPermissionDialog(opened.topLayer)).toBeNull();
-          await expect(contentWrapper.inert).toBe(false);
-          await expect(opened.topLayer.matches(':popover-open')).toBe(false);
+        await waitFor(() => {
+          expect(getPermissionDialog(opened.topLayer)).toBeNull();
+          expect(contentWrapper.inert).toBe(false);
+          expect(opened.topLayer.matches(':popover-open')).toBe(false);
         }, productionWaitOptions);
-        await expect(closeAllRequests.getAttribute('data-count')).toBe('2');
+        expect(closeAllRequests.getAttribute('data-count')).toBe('2');
       });
 
       await step('Finish teardown when the dialog exits first', async () => {
@@ -515,27 +514,25 @@ export const PopoverOpensDialogEvidence: Story = {
         );
         if (!dialogOverlay) throw new Error('dialog overlay not rendered');
         closeAllOverlays.click();
-        await waitFor(async () => {
-          await expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
-          await expect(permissionDialog).toHaveAttribute('data-state', 'closed');
+        await waitFor(() => {
+          void expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
+          void expect(permissionDialog).toHaveAttribute('data-state', 'closed');
         }, productionWaitOptions);
         finishAnimations(permissionDialog);
         finishAnimations(dialogOverlay);
-        await waitFor(async () => {
-          await expect(getPermissionDialog(opened.topLayer)).toBeNull();
-          await expect(
+        await waitFor(() => {
+          expect(getPermissionDialog(opened.topLayer)).toBeNull();
+          expect(
             opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
           ).not.toBeNull();
         }, productionWaitOptions);
         finishAnimations(opened.versePopover);
-        await waitFor(async () => {
-          await expect(
-            opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
-          ).toBeNull();
-          await expect(contentWrapper.inert).toBe(false);
-          await expect(opened.topLayer.matches(':popover-open')).toBe(false);
+        await waitFor(() => {
+          expect(opened.topLayer.querySelector('[data-slot="verse-action-popover"]')).toBeNull();
+          expect(contentWrapper.inert).toBe(false);
+          expect(opened.topLayer.matches(':popover-open')).toBe(false);
         }, productionWaitOptions);
-        await expect(closeAllRequests.getAttribute('data-count')).toBe('3');
+        expect(closeAllRequests.getAttribute('data-count')).toBe('3');
       });
     } finally {
       for (const style of exitAnimationStyles) style.remove();
@@ -593,7 +590,7 @@ export const DialogContainsPopoverEvidence: Story = {
       );
       const restorePosition = placeOverlayCenterUnderneath(notesDialog, notesPopover);
       try {
-        await expectOverlayAboveAtOverlap(root, notesPopover, notesDialog);
+        expectOverlayAboveAtOverlap(root, notesPopover, notesDialog);
       } finally {
         restorePosition();
       }
@@ -604,27 +601,27 @@ export const DialogContainsPopoverEvidence: Story = {
         productionWaitOptions,
       );
       await userEvent.click(notesAction);
-      await waitFor(async () => await expect(noteActionCount.getAttribute('data-count')).toBe('1'));
-      await waitFor(async () => {
+      await waitFor(() => expect(noteActionCount.getAttribute('data-count')).toBe('1'));
+      await waitFor(() => {
         const focused = root.activeElement;
-        await expect(focused !== null && notesPopover.contains(focused)).toBe(true);
+        expect(focused !== null && notesPopover.contains(focused)).toBe(true);
       });
     });
 
     await step('Escape closes only the popover and restores its trigger', async () => {
       await userEvent.keyboard('{Escape}');
-      await waitFor(async () => await expect(notesPopover.isConnected).toBe(false));
-      await expect(topLayer).toContainElement(notesDialog);
-      await expect(root.activeElement).toBe(notesTrigger);
-      await expect(contentWrapper.inert).toBe(true);
+      await waitFor(() => expect(notesPopover.isConnected).toBe(false));
+      void expect(topLayer).toContainElement(notesDialog);
+      expect(root.activeElement).toBe(notesTrigger);
+      expect(contentWrapper.inert).toBe(true);
     });
 
     await step('The next Escape closes the dialog and restores its opener', async () => {
       await userEvent.keyboard('{Escape}');
-      await waitFor(async () => await expect(notesDialog.isConnected).toBe(false));
-      await waitFor(async () => await expect(contentWrapper.inert).toBe(false));
-      await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(false));
-      await expect(root.activeElement).toBe(openNotes);
+      await waitFor(() => expect(notesDialog.isConnected).toBe(false));
+      await waitFor(() => expect(contentWrapper.inert).toBe(false));
+      await waitFor(() => expect(topLayer.matches(':popover-open')).toBe(false));
+      expect(root.activeElement).toBe(openNotes);
     });
   },
 };
@@ -662,16 +659,16 @@ export const TwoIndependentOverlaysEvidence: Story = {
         'independent popover not rendered',
         productionWaitOptions,
       );
-      await waitFor(async () => {
+      await waitFor(() => {
         const focused = root.activeElement;
-        await expect(focused !== null && independentPopover.contains(focused)).toBe(true);
+        expect(focused !== null && independentPopover.contains(focused)).toBe(true);
       });
-      await expect(contentWrapper.inert).toBe(false);
+      expect(contentWrapper.inert).toBe(false);
       await userEvent.keyboard('{Escape}');
-      await waitFor(async () => await expect(independentPopover.isConnected).toBe(false));
-      await expect(root.activeElement).toBe(independentTrigger);
+      await waitFor(() => expect(independentPopover.isConnected).toBe(false));
+      expect(root.activeElement).toBe(independentTrigger);
       closeAllOverlays.click();
-      await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(false));
+      await waitFor(() => expect(topLayer.matches(':popover-open')).toBe(false));
     });
 
     await step('Keep the secondary root usable through primary teardown', async () => {
@@ -703,7 +700,7 @@ export const TwoIndependentOverlaysEvidence: Story = {
       );
 
       const opened = await openVerseActionPopover(root, verse);
-      await expect(opened.topLayer).not.toBe(secondaryTopLayer);
+      expect(opened.topLayer).not.toBe(secondaryTopLayer);
       await openPermissionDialogFromVerseAction(opened.topLayer, opened.versePopover);
       const unmountPrimary = await waitForElement<HTMLButtonElement>(
         canvasElement,
@@ -712,13 +709,11 @@ export const TwoIndependentOverlaysEvidence: Story = {
         productionWaitOptions,
       );
       unmountPrimary.click();
-      await waitFor(async () => await expect(primaryIsland.isConnected).toBe(false));
+      await waitFor(() => expect(primaryIsland.isConnected).toBe(false));
       closeAllOverlays.click();
-      await waitFor(async () => await expect(secondaryPopover.isConnected).toBe(false));
-      await waitFor(
-        async () => await expect(secondaryTopLayer.matches(':popover-open')).toBe(false),
-      );
-      await expect(secondaryIsland.isConnected).toBe(true);
+      await waitFor(() => expect(secondaryPopover.isConnected).toBe(false));
+      await waitFor(() => expect(secondaryTopLayer.matches(':popover-open')).toBe(false));
+      expect(secondaryIsland.isConnected).toBe(true);
 
       await userEvent.click(secondaryTrigger);
       const reopenedSecondaryPopover = await waitForElement<HTMLElement>(
@@ -727,8 +722,8 @@ export const TwoIndependentOverlaysEvidence: Story = {
         'secondary popover did not reopen after primary teardown',
         productionWaitOptions,
       );
-      await expect(reopenedSecondaryPopover).toHaveAttribute('data-state', 'open');
-      await expect(secondaryTopLayer.matches(':popover-open')).toBe(true);
+      void expect(reopenedSecondaryPopover).toHaveAttribute('data-state', 'open');
+      expect(secondaryTopLayer.matches(':popover-open')).toBe(true);
     });
   },
 };
@@ -762,7 +757,7 @@ export const RapidCloseReopenDuringExitEvidence: Story = {
           'shadow-local top layer not created',
           productionWaitOptions,
         );
-        firstDialog = await waitFor(async () => {
+        firstDialog = await waitFor(() => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog) throw new Error('permission dialog did not open');
           return dialog;
@@ -770,54 +765,52 @@ export const RapidCloseReopenDuringExitEvidence: Story = {
       });
 
       await step('Retain modal ownership while the dialog starts exiting', async () => {
-        await waitFor(
-          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
-        );
-        await expect(firstDialog.isConnected).toBe(true);
-        await expect(topLayer).toContainElement(firstDialog);
-        await expect(contentWrapper.inert).toBe(true);
+        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
+        expect(firstDialog.isConnected).toBe(true);
+        void expect(topLayer).toContainElement(firstDialog);
+        expect(contentWrapper.inert).toBe(true);
       });
 
       await step('Preserve modal focus after the first dialog unmounts', async () => {
-        await waitFor(async () => {
-          await expect(firstDialog.isConnected).toBe(false);
+        await waitFor(() => {
+          expect(firstDialog.isConnected).toBe(false);
           const overlay = topLayer.querySelector<HTMLElement>('[data-slot="dialog-overlay"]');
           if (!overlay) throw new Error('dialog overlay did not remain during content exit');
           const currentDialog = getPermissionDialog(topLayer);
           const focused = root.activeElement;
-          await expect(
+          expect(
             focused === overlay ||
               (focused !== null && currentDialog !== null && currentDialog.contains(focused)),
           ).toBe(true);
-          await expect(contentWrapper.inert).toBe(true);
-          await expect(topLayer.matches(':popover-open')).toBe(true);
+          expect(contentWrapper.inert).toBe(true);
+          expect(topLayer.matches(':popover-open')).toBe(true);
         });
       });
 
       await step('Reopen from overlay-only retained presence', async () => {
-        const reopenedDialog = await waitFor(async () => {
+        const reopenedDialog = await waitFor(() => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not reopen during exit');
           }
           return dialog;
         });
-        await expect(reopenedDialog).not.toBe(firstDialog);
-        await waitFor(async () => {
+        expect(reopenedDialog).not.toBe(firstDialog);
+        await waitFor(() => {
           const focused = root.activeElement;
-          await expect(focused !== null && reopenedDialog.contains(focused)).toBe(true);
-          await expect(contentWrapper.inert).toBe(true);
-          await expect(topLayer.matches(':popover-open')).toBe(true);
+          expect(focused !== null && reopenedDialog.contains(focused)).toBe(true);
+          expect(contentWrapper.inert).toBe(true);
+          expect(topLayer.matches(':popover-open')).toBe(true);
         });
       });
 
       await step('Release modal ownership after the final close', async () => {
         await userEvent.keyboard('{Escape}');
-        await waitFor(async () => {
-          await expect(getPermissionDialog(topLayer)).toBeNull();
-          await expect(contentWrapper.inert).toBe(false);
-          await expect(topLayer.matches(':popover-open')).toBe(false);
-          await expect(root.activeElement).toBe(runRapidCloseReopen);
+        await waitFor(() => {
+          expect(getPermissionDialog(topLayer)).toBeNull();
+          expect(contentWrapper.inert).toBe(false);
+          expect(topLayer.matches(':popover-open')).toBe(false);
+          expect(root.activeElement).toBe(runRapidCloseReopen);
         });
       });
     } finally {
@@ -857,48 +850,44 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
           '[data-yv-shadow-local-overlay]',
           'shadow-local top layer not created',
         );
-        const firstDialog = await waitFor(async () => {
+        const firstDialog = await waitFor(() => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog) throw new Error('permission dialog did not open');
           return dialog;
         });
-        await waitFor(
-          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
-        );
-        await waitFor(async () => {
+        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
+        await waitFor(() => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not reopen during exit');
           }
-          await expect(contentWrapper.inert).toBe(true);
+          expect(contentWrapper.inert).toBe(true);
         });
       });
 
       await step('Ignore the opener after it moves to another shadow root', async () => {
         secondaryRoot.append(runRapidCloseReopen);
-        await expect(runRapidCloseReopen.getRootNode()).toBe(secondaryRoot);
+        expect(runRapidCloseReopen.getRootNode()).toBe(secondaryRoot);
 
         await userEvent.keyboard('{Escape}');
-        await waitFor(async () => {
-          await expect(getPermissionDialog(topLayer)).toBeNull();
-          await expect(contentWrapper.inert).toBe(false);
-          await expect(topLayer.matches(':popover-open')).toBe(false);
+        await waitFor(() => {
+          expect(getPermissionDialog(topLayer)).toBeNull();
+          expect(contentWrapper.inert).toBe(false);
+          expect(topLayer.matches(':popover-open')).toBe(false);
         });
-        await expect(secondaryRoot.activeElement).not.toBe(runRapidCloseReopen);
+        expect(secondaryRoot.activeElement).not.toBe(runRapidCloseReopen);
       });
 
       await step('Ignore the opener after it moves into the light DOM', async () => {
         contentWrapper.append(runRapidCloseReopen);
         await userEvent.click(runRapidCloseReopen);
-        const firstDialog = await waitFor(async () => {
+        const firstDialog = await waitFor(() => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog) throw new Error('permission dialog did not reopen for light-DOM target');
           return dialog;
         });
-        await waitFor(
-          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
-        );
-        await waitFor(async () => {
+        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
+        await waitFor(() => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not rapidly reopen for light-DOM target');
@@ -908,15 +897,15 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
         const focus = spyOn(runRapidCloseReopen, 'focus');
         try {
           canvasElement.ownerDocument.body.append(runRapidCloseReopen);
-          await expect(runRapidCloseReopen.getRootNode()).toBe(canvasElement.ownerDocument);
+          expect(runRapidCloseReopen.getRootNode()).toBe(canvasElement.ownerDocument);
           await userEvent.keyboard('{Escape}');
-          await waitFor(async () => {
-            await expect(getPermissionDialog(topLayer)).toBeNull();
-            await expect(contentWrapper.inert).toBe(false);
-            await expect(topLayer.matches(':popover-open')).toBe(false);
+          await waitFor(() => {
+            expect(getPermissionDialog(topLayer)).toBeNull();
+            expect(contentWrapper.inert).toBe(false);
+            expect(topLayer.matches(':popover-open')).toBe(false);
           });
-          await expect(focus).not.toHaveBeenCalled();
-          await expect(canvasElement.ownerDocument.activeElement).not.toBe(runRapidCloseReopen);
+          expect(focus).not.toHaveBeenCalled();
+          expect(canvasElement.ownerDocument.activeElement).not.toBe(runRapidCloseReopen);
         } finally {
           focus.mockRestore();
         }
@@ -925,15 +914,13 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
       await step('Ignore the opener after it disconnects', async () => {
         contentWrapper.append(runRapidCloseReopen);
         await userEvent.click(runRapidCloseReopen);
-        const firstDialog = await waitFor(async () => {
+        const firstDialog = await waitFor(() => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog) throw new Error('permission dialog did not reopen for disconnected target');
           return dialog;
         });
-        await waitFor(
-          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
-        );
-        await waitFor(async () => {
+        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
+        await waitFor(() => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not rapidly reopen for disconnected target');
@@ -943,15 +930,15 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
         const focus = spyOn(runRapidCloseReopen, 'focus');
         try {
           runRapidCloseReopen.remove();
-          await expect(runRapidCloseReopen.isConnected).toBe(false);
+          expect(runRapidCloseReopen.isConnected).toBe(false);
           await userEvent.keyboard('{Escape}');
-          await waitFor(async () => {
-            await expect(getPermissionDialog(topLayer)).toBeNull();
-            await expect(contentWrapper.inert).toBe(false);
-            await expect(topLayer.matches(':popover-open')).toBe(false);
+          await waitFor(() => {
+            expect(getPermissionDialog(topLayer)).toBeNull();
+            expect(contentWrapper.inert).toBe(false);
+            expect(topLayer.matches(':popover-open')).toBe(false);
           });
-          await expect(focus).not.toHaveBeenCalled();
-          await expect(root.activeElement).not.toBe(runRapidCloseReopen);
+          expect(focus).not.toHaveBeenCalled();
+          expect(root.activeElement).not.toBe(runRapidCloseReopen);
         } finally {
           focus.mockRestore();
         }
@@ -960,16 +947,14 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
       await step('Ignore the opener after it moves to another document', async () => {
         contentWrapper.append(runRapidCloseReopen);
         await userEvent.click(runRapidCloseReopen);
-        const firstDialog = await waitFor(async () => {
+        const firstDialog = await waitFor(() => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog)
             throw new Error('permission dialog did not reopen for cross-document target');
           return dialog;
         });
-        await waitFor(
-          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
-        );
-        await waitFor(async () => {
+        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
+        await waitFor(() => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not rapidly reopen for cross-document target');
@@ -980,15 +965,15 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
         const focus = spyOn(runRapidCloseReopen, 'focus');
         try {
           secondaryDocument.body.append(runRapidCloseReopen);
-          await expect(runRapidCloseReopen.isConnected).toBe(true);
-          await expect(runRapidCloseReopen.ownerDocument).toBe(secondaryDocument);
+          expect(runRapidCloseReopen.isConnected).toBe(true);
+          expect(runRapidCloseReopen.ownerDocument).toBe(secondaryDocument);
           await userEvent.keyboard('{Escape}');
-          await waitFor(async () => {
-            await expect(getPermissionDialog(topLayer)).toBeNull();
-            await expect(contentWrapper.inert).toBe(false);
-            await expect(topLayer.matches(':popover-open')).toBe(false);
+          await waitFor(() => {
+            expect(getPermissionDialog(topLayer)).toBeNull();
+            expect(contentWrapper.inert).toBe(false);
+            expect(topLayer.matches(':popover-open')).toBe(false);
           });
-          await expect(focus).not.toHaveBeenCalled();
+          expect(focus).not.toHaveBeenCalled();
         } finally {
           focus.mockRestore();
         }
diff --git a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
index c7a9a1d6..65e883ed 100644
--- a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
+++ b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
@@ -3,7 +3,8 @@ import type { BibleBook, BibleVersion } from '@youversion/platform-core';
 import { YouVersionContext, type HookOverrides } from '@youversion/platform-react-hooks';
 import { http, HttpResponse } from 'msw';
 import { StrictMode, useCallback, useContext, useEffect, useState, type ReactNode } from 'react';
-import { expect, spyOn, userEvent, waitFor } from 'storybook/test';
+import { spyOn, userEvent, waitFor } from 'storybook/test';
+import { expect } from 'vitest';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { BibleCard } from './bible-card';
 import { BibleReader } from './bible-reader';
@@ -221,11 +222,11 @@ interface MountedFixture {
   sheet: CSSStyleSheet;
 }
 
-async function requireMountedFixture(canvasElement: HTMLElement): Promise<MountedFixture> {
+function requireMountedFixture(canvasElement: HTMLElement): MountedFixture {
   const hosts = Array.from(
     canvasElement.ownerDocument.querySelectorAll<HTMLElement>('[data-yv-shadow-host]'),
   );
-  await expect(hosts).toHaveLength(EXPECTED_COMPONENT_IDS.length);
+  expect(hosts).toHaveLength(EXPECTED_COMPONENT_IDS.length);
 
   const roots = hosts.map((host) => {
     if (!host.shadowRoot) throw new Error('shadow root not attached');
@@ -235,7 +236,7 @@ async function requireMountedFixture(canvasElement: HTMLElement): Promise<Mounte
     (root) =>
       root.querySelector<HTMLElement>('[data-realistic-component]')?.dataset.realisticComponent,
   );
-  await expect(componentIds).toEqual(EXPECTED_COMPONENT_IDS);
+  expect(componentIds).toEqual(EXPECTED_COMPONENT_IDS);
 
   const components = new Map(
     roots.map((root, index) => [
@@ -251,35 +252,31 @@ async function requireMountedFixture(canvasElement: HTMLElement): Promise<Mounte
     ['votd-large', 'JHN.3.16'],
   ]);
   for (const [id, usfm] of expectedPassages) {
-    await expect(components.get(id)).toHaveTextContent(`Fixture scripture content for ${usfm}.`);
+    void expect(components.get(id)).toHaveTextContent(`Fixture scripture content for ${usfm}.`);
   }
-  await expect(
+  expect(
     components.get('avatar-primary')?.querySelector('[aria-label="SDK Reader"]'),
   ).not.toBeNull();
-  await expect(
+  expect(
     components.get('avatar-secondary')?.querySelector('[aria-label="Bible Partner"]'),
   ).not.toBeNull();
-  await expect(components.get('notes-primary')?.querySelector('textarea')).toHaveValue(
+  void expect(components.get('notes-primary')?.querySelector('textarea')).toHaveValue(
     'Primary notes',
   );
-  await expect(components.get('notes-secondary')?.querySelector('textarea')).toHaveValue(
+  void expect(components.get('notes-secondary')?.querySelector('textarea')).toHaveValue(
     'Secondary notes',
   );
-  await expect(components.get('notes-tertiary')?.querySelector('textarea')).toHaveValue(
+  void expect(components.get('notes-tertiary')?.querySelector('textarea')).toHaveValue(
     'Tertiary notes',
   );
-  await expect(
-    components.get('separator-primary')?.querySelector('[role="separator"]'),
-  ).not.toBeNull();
-  await expect(
-    components.get('separator-secondary')?.querySelector('[role="separator"]'),
-  ).not.toBeNull();
+  expect(components.get('separator-primary')?.querySelector('[role="separator"]')).not.toBeNull();
+  expect(components.get('separator-secondary')?.querySelector('[role="separator"]')).not.toBeNull();
 
   const sheet = roots[0]?.adoptedStyleSheets[0];
   if (!sheet) throw new Error('shared SDK stylesheet not adopted');
   for (const root of roots) {
-    await expect(root.adoptedStyleSheets).toHaveLength(1);
-    await expect(root.adoptedStyleSheets[0]).toBe(sheet);
+    expect(root.adoptedStyleSheets).toHaveLength(1);
+    expect(root.adoptedStyleSheets[0]).toBe(sheet);
   }
 
   return { hosts, sheet };
@@ -305,13 +302,13 @@ const STRICT_EFFECT_COUNTS: ExpectedEffectCounts = import.meta.env.DEV
     }
   : NORMAL_EFFECT_COUNTS;
 
-async function requireEffectCounts(
+function requireEffectCounts(
   canvasElement: HTMLElement,
   [setup, cleanup]: [setup: number, cleanup: number],
-): Promise<void> {
+): void {
   const counts = canvasElement.querySelector('[data-testid="effect-lifecycle-counts"]');
-  await expect(counts).toHaveAttribute('data-effect-setup', String(setup));
-  await expect(counts).toHaveAttribute('data-effect-cleanup', String(cleanup));
+  void expect(counts).toHaveAttribute('data-effect-setup', String(setup));
+  void expect(counts).toHaveAttribute('data-effect-cleanup', String(cleanup));
 }
 
 async function exerciseLifecycle(
@@ -324,27 +321,27 @@ async function exerciseLifecycle(
 
   try {
     await userEvent.click(toggle);
-    const firstMount = await waitFor(async () => {
-      const fixture = await requireMountedFixture(canvasElement);
-      await requireEffectCounts(canvasElement, expectedEffectCounts.firstMount);
+    const firstMount = await waitFor(() => {
+      const fixture = requireMountedFixture(canvasElement);
+      requireEffectCounts(canvasElement, expectedEffectCounts.firstMount);
       return fixture;
     });
 
     await userEvent.click(toggle);
-    await expect(canvasElement.querySelectorAll('[data-yv-shadow-host]')).toHaveLength(0);
-    await expect(canvasElement.querySelector('[data-testid="realistic-component-mix"]')).toBeNull();
-    await requireEffectCounts(canvasElement, expectedEffectCounts.removal);
+    expect(canvasElement.querySelectorAll('[data-yv-shadow-host]')).toHaveLength(0);
+    expect(canvasElement.querySelector('[data-testid="realistic-component-mix"]')).toBeNull();
+    requireEffectCounts(canvasElement, expectedEffectCounts.removal);
 
     await userEvent.click(toggle);
-    const secondMount = await waitFor(async () => {
-      const fixture = await requireMountedFixture(canvasElement);
-      await requireEffectCounts(canvasElement, expectedEffectCounts.secondMount);
+    const secondMount = await waitFor(() => {
+      const fixture = requireMountedFixture(canvasElement);
+      requireEffectCounts(canvasElement, expectedEffectCounts.secondMount);
       return fixture;
     });
     for (const host of secondMount.hosts) {
-      await expect(host.shadowRoot?.adoptedStyleSheets[0]).toBe(firstMount.sheet);
+      expect(host.shadowRoot?.adoptedStyleSheets[0]).toBe(firstMount.sheet);
     }
-    await expect(consoleError).not.toHaveBeenCalled();
+    expect(consoleError).not.toHaveBeenCalled();
   } finally {
     consoleError.mockRestore();
   }
diff --git a/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx b/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
index 2fd50725..83b1b185 100644
--- a/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
@@ -1,7 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { http, HttpResponse } from 'msw';
 import { useState } from 'react';
-import { expect, userEvent, waitFor } from 'storybook/test';
+import { userEvent, waitFor } from 'storybook/test';
+import { expect } from 'vitest';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { waitForShadowRoot } from '../test/storybook-dom';
 import { SignInDialog } from './sign-in-dialog';
@@ -72,16 +73,16 @@ async function expectOutsideFocusRedirectedInto(
   dialog: HTMLElement,
 ): Promise<void> {
   outsideControl.focus();
-  await waitFor(async () => {
+  await waitFor(() => {
     const focused = root.activeElement;
-    await expect(focused !== null && dialog.contains(focused)).toBe(true);
+    expect(focused !== null && dialog.contains(focused)).toBe(true);
   });
-  await expect(outsideControl.ownerDocument.activeElement).not.toBe(outsideControl);
+  expect(outsideControl.ownerDocument.activeElement).not.toBe(outsideControl);
 }
 
 export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
   play: async ({ canvasElement }) => {
-    const { outsideControl, clippingContainer } = await waitFor(async () => {
+    const { outsideControl, clippingContainer } = await waitFor(() => {
       const outside = canvasElement.querySelector<HTMLButtonElement>(
         '[data-testid="outside-control"]',
       );
@@ -99,15 +100,15 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
       [data-slot='dialog-overlay'][data-state='closed'] { animation-duration: 800ms !important; }
     `;
     root.append(exitAnimationStyle);
-    const insideControl = await waitFor(async () => {
+    const insideControl = await waitFor(() => {
       const element = root.querySelector<HTMLButtonElement>('[data-testid="inside-control"]');
       if (!element) throw new Error('inside-island control not rendered');
       return element;
     });
-    await expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
     insideControl.focus();
     await userEvent.click(insideControl);
-    const dialog = await waitFor(async () => {
+    const dialog = await waitFor(() => {
       const element = root.querySelector<HTMLElement>('[role="dialog"]');
       if (!element) throw new Error('sign-in dialog not rendered in the component shadow root');
       return element;
@@ -116,19 +117,19 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     const contentWrapper = root.querySelector<HTMLElement>('[data-yv-shadow-content-wrapper]');
     if (!topLayer || !contentWrapper) throw new Error('shadow modal coordination not rendered');
 
-    await expect(dialog.getRootNode()).toBe(root);
-    await expect(topLayer.getRootNode()).toBe(root);
-    await expect(canvasElement.ownerDocument.body.querySelector('[role="dialog"]')).toBeNull();
-    await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(true));
+    expect(dialog.getRootNode()).toBe(root);
+    expect(topLayer.getRootNode()).toBe(root);
+    expect(canvasElement.ownerDocument.body.querySelector('[role="dialog"]')).toBeNull();
+    await waitFor(() => expect(topLayer.matches(':popover-open')).toBe(true));
 
     const titleId = dialog.getAttribute('aria-labelledby');
     const descriptionId = dialog.getAttribute('aria-describedby');
-    await expect(titleId).toBeTruthy();
-    await expect(descriptionId).toBeTruthy();
+    expect(titleId).toBeTruthy();
+    expect(descriptionId).toBeTruthy();
     const title = root.getElementById(titleId!);
     const description = root.getElementById(descriptionId!);
-    await expect(title).not.toBeNull();
-    await expect(description).not.toBeNull();
+    expect(title).not.toBeNull();
+    expect(description).not.toBeNull();
     // SAFETY: These reflected-ARIA properties are still a draft; verify support before use.
     const reflectedDialog = dialog as HTMLElement & {
       ariaLabelledByElements?: readonly Element[];
@@ -137,12 +138,12 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     if (!reflectedDialog.ariaLabelledByElements || !reflectedDialog.ariaDescribedByElements) {
       throw new Error('browser did not expose the dialog ARIA element relationships');
     }
-    await expect(reflectedDialog.ariaLabelledByElements).toEqual([title]);
-    await expect(reflectedDialog.ariaDescribedByElements).toEqual([description]);
+    expect(reflectedDialog.ariaLabelledByElements).toEqual([title]);
+    expect(reflectedDialog.ariaDescribedByElements).toEqual([description]);
 
-    await waitFor(async () => {
+    await waitFor(() => {
       const focused = root.activeElement;
-      await expect(focused !== null && dialog.contains(focused)).toBe(true);
+      expect(focused !== null && dialog.contains(focused)).toBe(true);
     });
 
     const hiddenWrapper = canvasElement.ownerDocument.createElement('div');
@@ -155,7 +156,7 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     const dialogButtons = Array.from(
       dialog.querySelectorAll<HTMLButtonElement>('button[data-slot="button"]'),
     );
-    await expect(dialogButtons).toHaveLength(2);
+    expect(dialogButtons).toHaveLength(2);
     const [confirmButton, declineButton] = dialogButtons;
     if (!confirmButton || !declineButton) throw new Error('sign-in dialog actions not rendered');
 
@@ -175,24 +176,24 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
 
     confirmButton.focus();
     await userEvent.tab();
-    await expect(root.activeElement).toBe(firstRadio);
+    expect(root.activeElement).toBe(firstRadio);
     await userEvent.tab();
-    await expect(root.activeElement).toBe(declineButton);
+    expect(root.activeElement).toBe(declineButton);
     await userEvent.tab();
-    await waitFor(async () => await expect(root.activeElement).toBe(confirmButton));
+    await waitFor(() => expect(root.activeElement).toBe(confirmButton));
     await userEvent.tab({ shift: true });
-    await waitFor(async () => await expect(root.activeElement).toBe(declineButton));
-    await expect(root.activeElement).not.toBe(negativeTabIndexButton);
-    await expect(root.activeElement).not.toBe(secondRadio);
+    await waitFor(() => expect(root.activeElement).toBe(declineButton));
+    expect(root.activeElement).not.toBe(negativeTabIndexButton);
+    expect(root.activeElement).not.toBe(secondRadio);
 
-    await expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
+    expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
 
     await expectOutsideFocusRedirectedInto(root, outsideControl, dialog);
 
-    await expect(insideControl.closest('[inert]')).not.toBeNull();
+    expect(insideControl.closest('[inert]')).not.toBeNull();
 
     insideControl.focus();
-    await expect(root.activeElement).not.toBe(insideControl);
+    expect(root.activeElement).not.toBe(insideControl);
 
     const overlay = dialog.previousElementSibling;
     if (!(overlay instanceof HTMLElement)) throw new Error('dialog overlay not rendered');
@@ -201,25 +202,23 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     const clippingRect = clippingContainer.getBoundingClientRect();
     const viewport = canvasElement.ownerDocument.defaultView;
     if (!viewport) throw new Error('story window not available');
-    await expect(overlayRect.width).toBeGreaterThanOrEqual(viewport.innerWidth - 1);
-    await expect(overlayRect.height).toBeGreaterThanOrEqual(viewport.innerHeight - 1);
+    expect(overlayRect.width).toBeGreaterThanOrEqual(viewport.innerWidth - 1);
+    expect(overlayRect.height).toBeGreaterThanOrEqual(viewport.innerHeight - 1);
     const sampleX =
       clippingRect.right + 4 < viewport.innerWidth ? clippingRect.right + 4 : clippingRect.left - 4;
     const sampleY = Math.min(viewport.innerHeight - 4, Math.max(4, clippingRect.top + 4));
     const escapedHit = root.elementFromPoint(sampleX, sampleY);
-    await expect(
-      escapedHit === overlay || (escapedHit !== null && overlay.contains(escapedHit)),
-    ).toBe(true);
-    await expect(dialogRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
+    expect(escapedHit === overlay || (escapedHit !== null && overlay.contains(escapedHit))).toBe(
+      true,
+    );
+    expect(dialogRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
     const dialogSampleX = dialogRect.left + dialogRect.width / 2;
     const dialogSampleY = Math.max(dialogRect.top + 2, clippingRect.bottom + 2);
     if (dialogSampleY >= dialogRect.bottom) {
       throw new Error('dialog did not extend beyond its clipping ancestor');
     }
     const dialogHit = root.elementFromPoint(dialogSampleX, dialogSampleY);
-    await expect(dialogHit === dialog || (dialogHit !== null && dialog.contains(dialogHit))).toBe(
-      true,
-    );
+    expect(dialogHit === dialog || (dialogHit !== null && dialog.contains(dialogHit))).toBe(true);
 
     const dialogStyles = styleSnapshot(dialog);
     const overlayStyles = styleSnapshot(overlay);
@@ -237,40 +236,39 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     `;
     try {
       canvasElement.ownerDocument.head.append(hostileStyle);
-      await waitFor(
-        async () =>
-          await expect(getComputedStyle(outsideControl).backgroundColor).toBe('rgb(185, 28, 28)'),
+      await waitFor(() =>
+        expect(getComputedStyle(outsideControl).backgroundColor).toBe('rgb(185, 28, 28)'),
       );
-      await expect(styleSnapshot(dialog)).toEqual(dialogStyles);
-      await expect(styleSnapshot(overlay)).toEqual(overlayStyles);
+      expect(styleSnapshot(dialog)).toEqual(dialogStyles);
+      expect(styleSnapshot(overlay)).toEqual(overlayStyles);
     } finally {
       hostileStyle.remove();
     }
 
     await userEvent.keyboard('{Escape}');
-    await waitFor(async () => {
-      await expect(dialog).toHaveAttribute('data-state', 'closed');
-      await expect(topLayer).toContainElement(dialog);
-      await expect(contentWrapper.inert).toBe(true);
-      await expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
-      await expect(topLayer.matches(':popover-open')).toBe(true);
+    await waitFor(() => {
+      void expect(dialog).toHaveAttribute('data-state', 'closed');
+      void expect(topLayer).toContainElement(dialog);
+      expect(contentWrapper.inert).toBe(true);
+      expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
+      expect(topLayer.matches(':popover-open')).toBe(true);
     });
     await expectOutsideFocusRedirectedInto(root, outsideControl, dialog);
-    await waitFor(async () => {
-      await expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
-      await expect(topLayer.querySelector('[data-slot="dialog-overlay"]')).not.toBeNull();
-      await expect(contentWrapper.inert).toBe(true);
-      await expect(root.activeElement).toBe(overlay);
+    await waitFor(() => {
+      expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
+      expect(topLayer.querySelector('[data-slot="dialog-overlay"]')).not.toBeNull();
+      expect(contentWrapper.inert).toBe(true);
+      expect(root.activeElement).toBe(overlay);
     });
-    await waitFor(async () => {
-      await expect(topLayer.childElementCount).toBe(0);
-      await expect(topLayer.matches(':popover-open')).toBe(false);
-      await expect(contentWrapper.inert).toBe(false);
-      await expect(root.activeElement).toBe(insideControl);
+    await waitFor(() => {
+      expect(topLayer.childElementCount).toBe(0);
+      expect(topLayer.matches(':popover-open')).toBe(false);
+      expect(contentWrapper.inert).toBe(false);
+      expect(root.activeElement).toBe(insideControl);
     });
 
     await userEvent.click(outsideControl);
-    const reopenedDialog = await waitFor(async () => {
+    const reopenedDialog = await waitFor(() => {
       const element = root.querySelector<HTMLElement>('[role="dialog"]');
       if (!element) throw new Error('dialog did not reopen');
       return element;
@@ -280,29 +278,29 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
       throw new Error('reopened dialog overlay not rendered');
     }
     await userEvent.click(reopenedOverlay);
-    await waitFor(async () => {
-      await expect(reopenedDialog).toHaveAttribute('data-state', 'closed');
-      await expect(contentWrapper.inert).toBe(true);
-      await expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
-      await expect(topLayer.matches(':popover-open')).toBe(true);
+    await waitFor(() => {
+      void expect(reopenedDialog).toHaveAttribute('data-state', 'closed');
+      expect(contentWrapper.inert).toBe(true);
+      expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
+      expect(topLayer.matches(':popover-open')).toBe(true);
     });
     await expectOutsideFocusRedirectedInto(root, outsideControl, reopenedDialog);
-    await waitFor(async () => {
-      await expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
-      await expect(topLayer.querySelector('[data-slot="dialog-overlay"]')).not.toBeNull();
-      await expect(contentWrapper.inert).toBe(true);
-      await expect(root.activeElement).toBe(reopenedOverlay);
+    await waitFor(() => {
+      expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
+      expect(topLayer.querySelector('[data-slot="dialog-overlay"]')).not.toBeNull();
+      expect(contentWrapper.inert).toBe(true);
+      expect(root.activeElement).toBe(reopenedOverlay);
     });
     outsideControl.focus();
-    await waitFor(async () => {
-      await expect(canvasElement.ownerDocument.activeElement).not.toBe(outsideControl);
-      await expect(root.activeElement).toBe(reopenedOverlay);
+    await waitFor(() => {
+      expect(canvasElement.ownerDocument.activeElement).not.toBe(outsideControl);
+      expect(root.activeElement).toBe(reopenedOverlay);
     });
-    await waitFor(async () => {
-      await expect(topLayer.childElementCount).toBe(0);
-      await expect(topLayer.matches(':popover-open')).toBe(false);
-      await expect(contentWrapper.inert).toBe(false);
-      await expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
+    await waitFor(() => {
+      expect(topLayer.childElementCount).toBe(0);
+      expect(topLayer.matches(':popover-open')).toBe(false);
+      expect(contentWrapper.inert).toBe(false);
+      expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
     });
     exitAnimationStyle.remove();
   },
diff --git a/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx b/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
index f49afa4c..a4bcee9b 100644
--- a/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
@@ -1,7 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { http, HttpResponse } from 'msw';
 import { useRef, useState } from 'react';
-import { expect, userEvent, waitFor, within } from 'storybook/test';
+import { userEvent, waitFor, within } from 'storybook/test';
+import { expect } from 'vitest';
 import i18n from '../i18n';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { waitForElement, waitForShadowRoot } from '../test/storybook-dom';
@@ -143,9 +144,9 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 async function waitForClosed(topLayer: HTMLElement): Promise<void> {
-  await waitFor(async () => {
-    await expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
-    await expect(topLayer.matches(':popover-open')).toBe(false);
+  await waitFor(() => {
+    expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
+    expect(topLayer.matches(':popover-open')).toBe(false);
   });
 }
 
@@ -204,19 +205,19 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
       'verse action popover not rendered',
     );
 
-    await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(true));
-    await expect(topLayer.getRootNode()).toBe(shadowRoot);
-    await expect(dialog.getRootNode()).toBe(shadowRoot);
-    await expect(canvasElement.ownerDocument.body.querySelector('[role="dialog"]')).toBeNull();
-    await expect(dialog).toHaveAccessibleName(/.+/);
-    await expect(dialog.querySelector('[role="group"]')).toHaveAccessibleName(/.+/);
-    await waitFor(async () => await expect(shadowRoot.activeElement).toBe(dialog));
+    await waitFor(() => expect(topLayer.matches(':popover-open')).toBe(true));
+    expect(topLayer.getRootNode()).toBe(shadowRoot);
+    expect(dialog.getRootNode()).toBe(shadowRoot);
+    expect(canvasElement.ownerDocument.body.querySelector('[role="dialog"]')).toBeNull();
+    void expect(dialog).toHaveAccessibleName(/.+/);
+    void expect(dialog.querySelector('[role="group"]')).toHaveAccessibleName(/.+/);
+    await waitFor(() => expect(shadowRoot.activeElement).toBe(dialog));
 
     const clippingRect = clippingContainer.getBoundingClientRect();
     const firstDialogRect = dialog.getBoundingClientRect();
     const escapesAbove = firstDialogRect.top < clippingRect.top - 1;
     const escapesBelow = firstDialogRect.bottom > clippingRect.bottom + 1;
-    await expect(escapesAbove || escapesBelow).toBe(true);
+    expect(escapesAbove || escapesBelow).toBe(true);
     const sampleX = firstDialogRect.left + firstDialogRect.width / 2;
     const sampleY = escapesBelow
       ? Math.max(firstDialogRect.top + 2, clippingRect.bottom + 2)
@@ -224,44 +225,44 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
     if (sampleY <= firstDialogRect.top || sampleY >= firstDialogRect.bottom)
       throw new Error('popover did not escape clipping bounds');
     const hit = shadowRoot.elementFromPoint(sampleX, sampleY);
-    await expect(hit === dialog || (hit !== null && dialog.contains(hit))).toBe(true);
+    expect(hit === dialog || (hit !== null && dialog.contains(hit))).toBe(true);
 
     readerScrollRoot.scrollTop = readerScrollRoot.scrollHeight;
-    await waitFor(async () => {
+    await waitFor(() => {
       const readerRect = readerScrollRoot.getBoundingClientRect();
       const dockedRect = dialog.getBoundingClientRect();
-      await expect(Math.abs(dockedRect.top - (readerRect.top + 24))).toBeLessThan(12);
-      await expect(
+      expect(Math.abs(dockedRect.top - (readerRect.top + 24))).toBeLessThan(12);
+      expect(
         Math.abs(dockedRect.left + dockedRect.width / 2 - (readerRect.left + readerRect.width / 2)),
       ).toBeLessThan(2);
     });
     readerScrollRoot.scrollTop = 0;
-    await waitFor(async () => {
+    await waitFor(() => {
       const returnedRect = dialog.getBoundingClientRect();
-      await expect(Math.abs(returnedRect.left - firstDialogRect.left)).toBeLessThan(12);
-      await expect(Math.abs(returnedRect.top - firstDialogRect.top)).toBeLessThan(12);
+      expect(Math.abs(returnedRect.left - firstDialogRect.left)).toBeLessThan(12);
+      expect(Math.abs(returnedRect.top - firstDialogRect.top)).toBeLessThan(12);
     });
 
     await userEvent.click(secondVerse);
-    await waitFor(async () => {
+    await waitFor(() => {
       const nextRect = dialog.getBoundingClientRect();
-      await expect(nextRect.left).toBeGreaterThan(firstDialogRect.left + 20);
+      expect(nextRect.left).toBeGreaterThan(firstDialogRect.left + 20);
     });
-    await expect(
+    expect(
       shadowRoot.querySelector('[data-testid="close-requests"]')?.getAttribute('data-count'),
     ).toBe('0');
-    await expect(topLayer).toContainElement(dialog);
+    void expect(topLayer).toContainElement(dialog);
 
     await userEvent.keyboard('{Escape}');
     await waitForClosed(topLayer);
-    await expect(shadowRoot.activeElement).toBe(priorControl);
+    expect(shadowRoot.activeElement).toBe(priorControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
     dialog = await waitForElement(topLayer, '[role="dialog"]', 'popover did not reopen');
     await userEvent.click(getCopyButton(dialog));
     await waitForClosed(topLayer);
-    await expect(shadowRoot.activeElement).toBe(priorControl);
+    expect(shadowRoot.activeElement).toBe(priorControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
@@ -276,31 +277,30 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
     if (!closeRequestOutput) throw new Error('close request output missing');
     const closeRequestsBeforeRejection = Number(closeRequestOutput.getAttribute('data-count'));
     await userEvent.click(rejectedOutsideControl);
-    await waitFor(
-      async () =>
-        await expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
-          closeRequestsBeforeRejection + 1,
-        ),
+    await waitFor(() =>
+      expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
+        closeRequestsBeforeRejection + 1,
+      ),
     );
-    await expect(topLayer).toContainElement(dialog);
-    await expect(canvasElement.ownerDocument.activeElement).toBe(rejectedOutsideControl);
+    void expect(topLayer).toContainElement(dialog);
+    expect(canvasElement.ownerDocument.activeElement).toBe(rejectedOutsideControl);
     await userEvent.click(getCopyButton(dialog));
     await waitForClosed(topLayer);
-    await expect(shadowRoot.activeElement).toBe(priorControl);
+    expect(shadowRoot.activeElement).toBe(priorControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
     await waitForElement(topLayer, '[role="dialog"]', 'popover did not reopen for delayed close');
     await userEvent.click(delayedOutsideControl);
     await waitForClosed(topLayer);
-    await expect(canvasElement.ownerDocument.activeElement).toBe(delayedOutsideControl);
+    expect(canvasElement.ownerDocument.activeElement).toBe(delayedOutsideControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
     await waitForElement(topLayer, '[role="dialog"]', 'popover did not reopen for outside click');
     await userEvent.click(outsideControl);
     await waitForClosed(topLayer);
-    await expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
+    expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
 
     const closeRequestsBeforeTouch = Number(closeRequestOutput.getAttribute('data-count'));
     const touchUser = userEvent.setup({ document: canvasElement.ownerDocument });
@@ -308,22 +308,20 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
     dialog = await waitForElement(topLayer, '[role="dialog"]', 'popover did not open for touch');
     const touchDialogRect = dialog.getBoundingClientRect();
     await touchUser.pointer({ keys: '[TouchA]', target: secondVerse });
-    await expect(firstVerse).toHaveClass('yv-v-selected');
-    await expect(secondVerse).toHaveClass('yv-v-selected');
-    await expect(dialog).toHaveAttribute('data-state', 'open');
-    await expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
-      closeRequestsBeforeTouch,
-    );
-    await waitFor(async () => {
-      await expect(dialog.getBoundingClientRect().left).toBeGreaterThan(touchDialogRect.left + 20);
+    void expect(firstVerse).toHaveClass('yv-v-selected');
+    void expect(secondVerse).toHaveClass('yv-v-selected');
+    void expect(dialog).toHaveAttribute('data-state', 'open');
+    expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(closeRequestsBeforeTouch);
+    await waitFor(() => {
+      expect(dialog.getBoundingClientRect().left).toBeGreaterThan(touchDialogRect.left + 20);
     });
     await touchUser.pointer({ keys: '[TouchA>]', target: outsideControl });
-    await expect(dialog).toHaveAttribute('data-state', 'open');
+    void expect(dialog).toHaveAttribute('data-state', 'open');
     await touchUser.pointer({ keys: '[/TouchA]', target: outsideControl });
     await waitForClosed(topLayer);
-    await expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
+    expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
       closeRequestsBeforeTouch + 1,
     );
-    await expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
+    expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
   },
 };

From 744bf47459cebeb9c43a7482b5a519c7fbc0cf64 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 14:29:38 -0500
Subject: [PATCH 07/21] test(ui): await shadow browser assertions

---
 ...ionAuthButton.shadow-isolation.stories.tsx |  48 +--
 ...ersion-picker.shadow-isolation.stories.tsx | 217 ++++++-------
 ...compatibility.shadow-isolation.stories.tsx |  64 ++--
 ...oduction-seam.shadow-isolation.stories.tsx | 286 ++++++++++--------
 ...adow-root-host-realistic-usage.stories.tsx |  64 ++--
 ...ign-in-dialog.shadow-isolation.stories.tsx | 157 +++++-----
 ...ction-popover.shadow-isolation.stories.tsx |  91 +++---
 7 files changed, 494 insertions(+), 433 deletions(-)

diff --git a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
index fc6cc43d..e0034e03 100644
--- a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
@@ -1,3 +1,5 @@
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
+
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { http, HttpResponse } from 'msw';
 import { createRoot, type Root } from 'react-dom/client';
@@ -100,7 +102,7 @@ export const HostileGlobalButtonRule: Story = {
       'shadow host not rendered',
       browserWaitOptions,
     );
-    const shadowRoot = await waitFor(() => {
+    const shadowRoot = await waitFor(async () => {
       if (!host.shadowRoot) throw new Error('shadow root not attached');
       return host.shadowRoot;
     }, browserWaitOptions);
@@ -114,8 +116,8 @@ export const HostileGlobalButtonRule: Story = {
     const sdkBaseline = buttonStyleSnapshot(sdkButton);
     // Guard against a false positive where an unstyled browser-default button
     // also happens not to equal the hostile values below.
-    expect(sdkBaseline.display).toBe('flex');
-    expect(sdkBaseline.fontFamily).toContain('Inter');
+    await expect(sdkBaseline.display).toBe('flex');
+    await expect(sdkBaseline.fontFamily).toContain('Inter');
 
     const style = ownerDocument.createElement('style');
     style.textContent = HOSTILE_CSS;
@@ -123,19 +125,21 @@ export const HostileGlobalButtonRule: Story = {
     try {
       ownerDocument.head.append(style);
 
-      await waitFor(() => {
-        expect(ownerWindow.getComputedStyle(control).backgroundColor).toBe('rgb(185, 28, 28)');
-        expect(ownerWindow.getComputedStyle(control, '::before').content).toBe('"HOSTILE"');
+      await waitFor(async () => {
+        await expect(ownerWindow.getComputedStyle(control).backgroundColor).toBe(
+          'rgb(185, 28, 28)',
+        );
+        await expect(ownerWindow.getComputedStyle(control, '::before').content).toBe('"HOSTILE"');
       });
 
-      expect(ownerWindow.getComputedStyle(host, '::before').content).toBe('none');
-      expect(ownerWindow.getComputedStyle(host, '::before').display).toBe('none');
-      expect(ownerWindow.getComputedStyle(host, '::after').content).toBe('none');
-      expect(ownerWindow.getComputedStyle(host, '::after').display).toBe('none');
+      await expect(ownerWindow.getComputedStyle(host, '::before').content).toBe('none');
+      await expect(ownerWindow.getComputedStyle(host, '::before').display).toBe('none');
+      await expect(ownerWindow.getComputedStyle(host, '::after').content).toBe('none');
+      await 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.
-      expect(buttonStyleSnapshot(sdkButton)).toEqual(sdkBaseline);
+      await expect(buttonStyleSnapshot(sdkButton)).toEqual(sdkBaseline);
     } finally {
       style.remove();
     }
@@ -152,7 +156,7 @@ export const SameOriginIframeDocument: Story = {
       'same-origin iframe not rendered',
       browserWaitOptions,
     );
-    const { iframeDocument, iframeWindow } = await waitFor(() => {
+    const { iframeDocument, iframeWindow } = await waitFor(async () => {
       const currentDocument = iframe.contentDocument;
       const currentWindow = currentDocument?.defaultView;
       if (!currentDocument?.body || !currentWindow) {
@@ -176,15 +180,15 @@ export const SameOriginIframeDocument: Story = {
         </ShadowRootHost>,
       );
 
-      await waitFor(() => {
+      await waitFor(async () => {
         const host = container.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');
-        expect(host?.ownerDocument).toBe(iframeDocument);
-        expect(shadowRoot?.adoptedStyleSheets).toHaveLength(1);
-        expect(shadowRoot?.adoptedStyleSheets[0]).toBeInstanceOf(iframeWindow.CSSStyleSheet);
-        expect(iframeWindow.getComputedStyle(content).display).toBe('flex');
+        await expect(host?.ownerDocument).toBe(iframeDocument);
+        await expect(shadowRoot?.adoptedStyleSheets).toHaveLength(1);
+        await expect(shadowRoot?.adoptedStyleSheets[0]).toBeInstanceOf(iframeWindow.CSSStyleSheet);
+        await expect(iframeWindow.getComputedStyle(content).display).toBe('flex');
       }, browserWaitOptions);
 
       const styleSheetPrototype = iframeWindow.CSSStyleSheet.prototype;
@@ -209,17 +213,17 @@ export const SameOriginIframeDocument: Story = {
           </ShadowRootHost>,
         );
 
-        await waitFor(() => {
+        await waitFor(async () => {
           const fallbackHost =
             fallbackContainer?.querySelector<HTMLDivElement>('[data-yv-shadow-host]');
           const shadowRoot = fallbackHost?.shadowRoot;
           const content = shadowRoot?.querySelector('[data-testid="iframe-fallback-content"]');
           const style = shadowRoot?.querySelector('style');
           if (!content || !style) throw new Error('iframe fallback content not mounted');
-          expect(shadowRoot?.adoptedStyleSheets).toHaveLength(0);
-          expect(style.getAttribute('data-href')).toBe('yv-sdk-shadow-styles');
-          expect(style.getAttribute('data-precedence')).toBe('yv-sdk');
-          expect(iframeWindow.getComputedStyle(content).display).toBe('flex');
+          await expect(shadowRoot?.adoptedStyleSheets).toHaveLength(0);
+          await expect(style.getAttribute('data-href')).toBe('yv-sdk-shadow-styles');
+          await expect(style.getAttribute('data-precedence')).toBe('yv-sdk');
+          await expect(iframeWindow.getComputedStyle(content).display).toBe('flex');
         }, browserWaitOptions);
       } finally {
         fallbackRoot?.unmount();
diff --git a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
index 2b7e64d7..6bae9d53 100644
--- a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
@@ -1,4 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
+
 import { YouVersionProvider as HooksYouVersionProvider } from '@youversion/platform-react-hooks';
 import { http, HttpResponse } from 'msw';
 import { useEffect, useState } from 'react';
@@ -119,7 +121,7 @@ async function getTrigger(root: ShadowRoot): Promise<HTMLElement> {
 async function openPicker(container: ParentNode) {
   const root = await waitForShadowRoot(container);
   const trigger = await getTrigger(root);
-  expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+  await expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
   await userEvent.click(trigger);
   const topLayer = await waitForElement<HTMLElement>(
     root,
@@ -131,7 +133,7 @@ async function openPicker(container: ParentNode) {
     '[data-slot="popover-content"]',
     'picker panel not rendered in local top layer',
   );
-  await waitFor(() => expect(topLayer.matches(':popover-open')).toBe(true));
+  await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(true));
   return { root, trigger, topLayer, panel };
 }
 
@@ -184,35 +186,35 @@ export const TopLayerEscapesClippingAndPreservesSemantics: Story = {
     );
     const { root, trigger, topLayer, panel } = await openPicker(clippingContainer);
 
-    expect(topLayer.getRootNode()).toBe(root);
-    expect(panel.getRootNode()).toBe(root);
-    expect(
+    await expect(topLayer.getRootNode()).toBe(root);
+    await expect(panel.getRootNode()).toBe(root);
+    await expect(
       canvasElement.ownerDocument.body.querySelector('[data-yv-shadow-overlay-host]'),
     ).toBeNull();
 
     const clippingRect = clippingContainer.getBoundingClientRect();
     const panelRect = panel.getBoundingClientRect();
-    expect(panelRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
+    await expect(panelRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
     const viewport = canvasElement.ownerDocument.defaultView;
     if (!viewport) throw new Error('story window not available');
-    expect(panelRect.top).toBeGreaterThanOrEqual(16);
-    expect(panelRect.left).toBeGreaterThanOrEqual(16);
-    expect(panelRect.bottom).toBeLessThanOrEqual(viewport.innerHeight - 16);
-    expect(panelRect.right).toBeLessThanOrEqual(viewport.innerWidth - 16);
+    await expect(panelRect.top).toBeGreaterThanOrEqual(16);
+    await expect(panelRect.left).toBeGreaterThanOrEqual(16);
+    await expect(panelRect.bottom).toBeLessThanOrEqual(viewport.innerHeight - 16);
+    await expect(panelRect.right).toBeLessThanOrEqual(viewport.innerWidth - 16);
 
     const sampleX = panelRect.left + panelRect.width / 2;
     const sampleY = Math.max(panelRect.top + 2, clippingRect.bottom + 2);
     if (sampleY >= panelRect.bottom) throw new Error('panel did not extend beyond its ancestor');
     const hit = root.elementFromPoint(sampleX, sampleY);
-    expect(hit === panel || (hit !== null && panel.contains(hit))).toBe(true);
+    await expect(hit === panel || (hit !== null && panel.contains(hit))).toBe(true);
 
     // SAFETY: The reflected-ARIA property is still a draft; verify browser support before use.
     const reflectedControls = (
       trigger as HTMLElement & { ariaControlsElements?: readonly Element[] }
     ).ariaControlsElements;
     if (!reflectedControls) throw new Error('browser did not expose ariaControlsElements');
-    expect(trigger.getAttribute('aria-controls')).toBe(panel.id);
-    expect(reflectedControls).toEqual([panel]);
+    await expect(trigger.getAttribute('aria-controls')).toBe(panel.id);
+    await expect(reflectedControls).toEqual([panel]);
   },
 };
 
@@ -251,7 +253,7 @@ export const InlineControlIsClippedByItsAncestor: Story = {
       'clipping container not rendered',
     );
     const root = await waitForShadowRoot(clippingContainer);
-    expect(root.querySelector('[data-yv-shadow-inline-overlay]')).toBeNull();
+    await expect(root.querySelector('[data-yv-shadow-inline-overlay]')).toBeNull();
     await userEvent.click(await getTrigger(root));
     const inlineContainer = await waitForElement<HTMLElement>(
       root,
@@ -266,21 +268,25 @@ export const InlineControlIsClippedByItsAncestor: Story = {
 
     const clippingRect = clippingContainer.getBoundingClientRect();
     const panelRect = panel.getBoundingClientRect();
-    expect(panelRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
+    await expect(panelRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
     const sampleX = panelRect.left + panelRect.width / 2;
     const visibleSampleY = Math.max(panelRect.top + 2, clippingRect.top + 2);
     if (visibleSampleY >= clippingRect.bottom) {
       throw new Error('panel has no visible area inside its clipping ancestor');
     }
     const visibleHit = root.elementFromPoint(sampleX, visibleSampleY);
-    expect(visibleHit === panel || (visibleHit !== null && panel.contains(visibleHit))).toBe(true);
+    await expect(visibleHit === panel || (visibleHit !== null && panel.contains(visibleHit))).toBe(
+      true,
+    );
 
     const clippedSampleY = Math.max(panelRect.top + 2, clippingRect.bottom + 2);
     if (clippedSampleY >= panelRect.bottom) {
       throw new Error('panel did not extend beyond its clipping ancestor');
     }
     const clippedHit = root.elementFromPoint(sampleX, clippedSampleY);
-    expect(clippedHit === panel || (clippedHit !== null && panel.contains(clippedHit))).toBe(false);
+    await expect(clippedHit === panel || (clippedHit !== null && panel.contains(clippedHit))).toBe(
+      false,
+    );
   },
 };
 
@@ -300,9 +306,9 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
       'outside control not rendered',
     );
     const { root, trigger, topLayer, panel } = await openPicker(canvasElement);
-    await waitFor(() => {
+    await waitFor(async () => {
       const focused = root.activeElement;
-      expect(focused !== null && panel.contains(focused)).toBe(true);
+      await expect(focused !== null && panel.contains(focused)).toBe(true);
     });
     const exitAnimationStyle = canvasElement.ownerDocument.createElement('style');
     exitAnimationStyle.textContent = `
@@ -326,23 +332,24 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
     `;
     try {
       canvasElement.ownerDocument.head.append(hostileStyle);
-      await waitFor(() =>
-        expect(getComputedStyle(outsideControl).backgroundColor).toBe('rgb(185, 28, 28)'),
+      await waitFor(
+        async () =>
+          await expect(getComputedStyle(outsideControl).backgroundColor).toBe('rgb(185, 28, 28)'),
       );
-      expect(styleSnapshot(panel)).toEqual(baseline);
+      await expect(styleSnapshot(panel)).toEqual(baseline);
     } finally {
       hostileStyle.remove();
     }
 
     await userEvent.click(outsideControl);
-    await waitFor(() => {
-      void expect(panel).toHaveAttribute('data-state', 'closed');
-      void expect(topLayer).toContainElement(panel);
-      expect(topLayer.matches(':popover-open')).toBe(true);
+    await waitFor(async () => {
+      await expect(panel).toHaveAttribute('data-state', 'closed');
+      await expect(topLayer).toContainElement(panel);
+      await expect(topLayer.matches(':popover-open')).toBe(true);
     });
-    await waitFor(() => {
-      expect(topLayer.querySelector('[data-slot="popover-content"]')).toBeNull();
-      expect(topLayer.matches(':popover-open')).toBe(false);
+    await waitFor(async () => {
+      await expect(topLayer.querySelector('[data-slot="popover-content"]')).toBeNull();
+      await expect(topLayer.matches(':popover-open')).toBe(false);
     });
 
     await userEvent.click(trigger);
@@ -351,9 +358,9 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
       '[data-slot="popover-content"]',
       'picker panel did not reopen',
     );
-    await waitFor(() => {
+    await waitFor(async () => {
       const activeElement = root.activeElement;
-      expect(activeElement !== null && reopenedPanel.contains(activeElement)).toBe(true);
+      await expect(activeElement !== null && reopenedPanel.contains(activeElement)).toBe(true);
     });
 
     const focused = root.activeElement;
@@ -362,16 +369,16 @@ export const StylingFocusDismissalAndRapidReopen: Story = {
       new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, composed: true }),
     );
     trigger.click();
-    await waitFor(() => {
-      expect(topLayer.matches(':popover-open')).toBe(true);
-      expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
+    await waitFor(async () => {
+      await expect(topLayer.matches(':popover-open')).toBe(true);
+      await expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
     });
 
     await userEvent.keyboard('{Escape}');
-    await waitFor(() => {
-      expect(topLayer.querySelector('[data-slot="popover-content"]')).toBeNull();
-      expect(topLayer.matches(':popover-open')).toBe(false);
-      expect(root.activeElement).toBe(trigger);
+    await waitFor(async () => {
+      await expect(topLayer.querySelector('[data-slot="popover-content"]')).toBeNull();
+      await expect(topLayer.matches(':popover-open')).toBe(false);
+      await expect(root.activeElement).toBe(trigger);
     });
   },
 };
@@ -399,7 +406,7 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
     if (!hostControl) throw new Error('hostile inheritance control not rendered');
 
     const { root, trigger, panel } = await openPicker(canvasElement);
-    await waitFor(() => void expect(trigger).toHaveTextContent('NIV'));
+    await waitFor(async () => await expect(trigger).toHaveTextContent('NIV'));
     const wrapper = root.querySelector<HTMLElement>('[data-yv-shadow-content-wrapper]');
     const heading = panel.querySelector<HTMLElement>('h2');
     const inputGroup = panel.querySelector<HTMLElement>('[data-slot="input-group"]');
@@ -409,9 +416,9 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
     const panelGeometry = geometrySnapshot(panel);
     const inputGeometry = geometrySnapshot(inputGroup);
     const headingTypography = typographySnapshot(heading, ownerWindow);
-    expect(headingTypography.fontFamily).toContain('Inter');
-    expect(ownerWindow.getComputedStyle(trigger).direction).toBe('rtl');
-    expect(ownerWindow.getComputedStyle(wrapper).direction).toBe('ltr');
+    await expect(headingTypography.fontFamily).toContain('Inter');
+    await expect(ownerWindow.getComputedStyle(trigger).direction).toBe('rtl');
+    await expect(ownerWindow.getComputedStyle(wrapper).direction).toBe('ltr');
 
     await userEvent.click(within(panel).getByRole('button', { name: /select a language/i }));
     const languageTabs = await waitForElement<HTMLElement>(
@@ -429,8 +436,8 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
     }
     const languageTabsInlineSize = languageTabs.offsetWidth;
     const languageInputRadius = ownerWindow.getComputedStyle(languageInputGroup).borderRadius;
-    expect(languageTabsInlineSize).toBe(languageTabsContainer.clientWidth - 32);
-    expect(languageInputRadius).toBe('30px');
+    await expect(languageTabsInlineSize).toBe(languageTabsContainer.clientWidth - 32);
+    await expect(languageInputRadius).toBe('30px');
 
     const hostileStyle = ownerDocument.createElement('style');
     hostileStyle.textContent = `
@@ -456,39 +463,39 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
 
     try {
       ownerDocument.head.append(hostileStyle);
-      await waitFor(() => {
+      await waitFor(async () => {
         const controlStyle = ownerWindow.getComputedStyle(hostControl);
-        expect(controlStyle.writingMode).toBe('vertical-rl');
-        expect(controlStyle.textOrientation).toBe('upright');
-        expect(controlStyle.color).toBe('rgb(185, 28, 28)');
-        expect(controlStyle.fontFamily).toContain('fantasy');
-        expect(controlStyle.fontSize).toBe('32px');
-        expect(controlStyle.letterSpacing).toBe('16px');
-        expect(controlStyle.lineHeight).toBe('96px');
-        expect(controlStyle.wordSpacing).toBe('32px');
-        expect(controlStyle.borderRadius).toBe('0px');
+        await expect(controlStyle.writingMode).toBe('vertical-rl');
+        await expect(controlStyle.textOrientation).toBe('upright');
+        await expect(controlStyle.color).toBe('rgb(185, 28, 28)');
+        await expect(controlStyle.fontFamily).toContain('fantasy');
+        await expect(controlStyle.fontSize).toBe('32px');
+        await expect(controlStyle.letterSpacing).toBe('16px');
+        await expect(controlStyle.lineHeight).toBe('96px');
+        await expect(controlStyle.wordSpacing).toBe('32px');
+        await expect(controlStyle.borderRadius).toBe('0px');
       });
 
       const wrapperStyle = ownerWindow.getComputedStyle(wrapper);
       const headingStyle = ownerWindow.getComputedStyle(heading);
       const panelStyle = ownerWindow.getComputedStyle(panel);
-      expect(wrapperStyle.direction).toBe('ltr');
-      expect(wrapperStyle.writingMode).toBe('horizontal-tb');
-      expect(wrapperStyle.textOrientation).toBe('mixed');
-      expect(headingStyle.direction).toBe('rtl');
-      expect(headingStyle.writingMode).toBe('horizontal-tb');
-      expect(headingStyle.textOrientation).toBe('mixed');
-      expect(typographySnapshot(heading, ownerWindow)).toEqual(headingTypography);
-      expect(panelStyle.getPropertyValue('--yv-spacing').trim()).toBe('.25rem');
-      expect(panelStyle.getPropertyValue('--spacing').trim()).toBe('.25rem');
-      expect(panelStyle.getPropertyValue('--yv-radius').trim()).toBe('2rem');
-      expect(languageTabs.offsetWidth).toBe(languageTabsInlineSize);
-      expect(ownerWindow.getComputedStyle(languageInputGroup).borderRadius).toBe(
+      await expect(wrapperStyle.direction).toBe('ltr');
+      await expect(wrapperStyle.writingMode).toBe('horizontal-tb');
+      await expect(wrapperStyle.textOrientation).toBe('mixed');
+      await expect(headingStyle.direction).toBe('rtl');
+      await expect(headingStyle.writingMode).toBe('horizontal-tb');
+      await expect(headingStyle.textOrientation).toBe('mixed');
+      await expect(typographySnapshot(heading, ownerWindow)).toEqual(headingTypography);
+      await expect(panelStyle.getPropertyValue('--yv-spacing').trim()).toBe('.25rem');
+      await expect(panelStyle.getPropertyValue('--spacing').trim()).toBe('.25rem');
+      await expect(panelStyle.getPropertyValue('--yv-radius').trim()).toBe('2rem');
+      await expect(languageTabs.offsetWidth).toBe(languageTabsInlineSize);
+      await expect(ownerWindow.getComputedStyle(languageInputGroup).borderRadius).toBe(
         languageInputRadius,
       );
-      expect(geometrySnapshot(trigger)).toEqual(triggerGeometry);
-      expect(geometrySnapshot(panel)).toEqual(panelGeometry);
-      expect(geometrySnapshot(inputGroup)).toEqual(inputGeometry);
+      await expect(geometrySnapshot(trigger)).toEqual(triggerGeometry);
+      await expect(geometrySnapshot(panel)).toEqual(panelGeometry);
+      await expect(geometrySnapshot(inputGroup)).toEqual(inputGeometry);
     } finally {
       hostileStyle.remove();
     }
@@ -512,8 +519,8 @@ export const MultiplePickersCreateIndependentLazyContainers: Story = {
     if (!first || !second) throw new Error('picker harness not rendered');
     const firstRoot = await waitForShadowRoot(first);
     const secondRoot = await waitForShadowRoot(second);
-    expect(firstRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
-    expect(secondRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    await expect(firstRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    await expect(secondRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
 
     const firstTrigger = await getTrigger(firstRoot);
     const secondTrigger = await getTrigger(secondRoot);
@@ -523,7 +530,7 @@ export const MultiplePickersCreateIndependentLazyContainers: Story = {
       '[data-yv-shadow-local-overlay]',
       'first local container not created',
     );
-    expect(secondRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    await expect(secondRoot.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
 
     await userEvent.click(secondTrigger);
     const secondTopLayer = await waitForElement<HTMLElement>(
@@ -531,10 +538,12 @@ export const MultiplePickersCreateIndependentLazyContainers: Story = {
       '[data-yv-shadow-local-overlay]',
       'second local container not created',
     );
-    await waitFor(() => {
-      expect(firstTopLayer.matches(':popover-open')).toBe(false);
-      expect(secondTopLayer.matches(':popover-open')).toBe(true);
-      expect(secondTopLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
+    await waitFor(async () => {
+      await expect(firstTopLayer.matches(':popover-open')).toBe(false);
+      await expect(secondTopLayer.matches(':popover-open')).toBe(true);
+      await expect(secondTopLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(
+        1,
+      );
     });
   },
 };
@@ -546,10 +555,10 @@ export const MultiplePopoversShareOneIslandContainer: Story = {
     const triggers = Array.from(
       root.querySelectorAll<HTMLElement>('[data-slot="popover-trigger"]'),
     );
-    expect(triggers).toHaveLength(2);
+    await expect(triggers).toHaveLength(2);
     const [firstTrigger, secondTrigger] = triggers;
     if (!firstTrigger || !secondTrigger) throw new Error('picker triggers not rendered');
-    expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    await expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
 
     await userEvent.click(firstTrigger);
     const topLayer = await waitForElement<HTMLElement>(
@@ -557,18 +566,18 @@ export const MultiplePopoversShareOneIslandContainer: Story = {
       '[data-yv-shadow-local-overlay]',
       'shared island container not created',
     );
-    await waitFor(() => {
-      void expect(firstTrigger).toHaveAttribute('aria-expanded', 'true');
-      expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
+    await waitFor(async () => {
+      await expect(firstTrigger).toHaveAttribute('aria-expanded', 'true');
+      await expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
     });
 
     await userEvent.click(secondTrigger);
-    await waitFor(() => {
-      void expect(firstTrigger).toHaveAttribute('aria-expanded', 'false');
-      void expect(secondTrigger).toHaveAttribute('aria-expanded', 'true');
-      expect(topLayer.matches(':popover-open')).toBe(true);
-      expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
-      expect(root.querySelectorAll('[data-yv-shadow-local-overlay]')).toHaveLength(1);
+    await waitFor(async () => {
+      await expect(firstTrigger).toHaveAttribute('aria-expanded', 'false');
+      await expect(secondTrigger).toHaveAttribute('aria-expanded', 'true');
+      await expect(topLayer.matches(':popover-open')).toBe(true);
+      await expect(topLayer.querySelectorAll('[data-slot="popover-content"]')).toHaveLength(1);
+      await expect(root.querySelectorAll('[data-yv-shadow-local-overlay]')).toHaveLength(1);
     });
 
     const panel = topLayer.querySelector<HTMLElement>('[data-slot="popover-content"]');
@@ -576,8 +585,8 @@ export const MultiplePopoversShareOneIslandContainer: Story = {
     const panelRect = panel.getBoundingClientRect();
     const viewport = canvasElement.ownerDocument.defaultView;
     if (!viewport) throw new Error('story window not available');
-    expect(panelRect.top).toBeGreaterThanOrEqual(16);
-    expect(panelRect.bottom).toBeLessThanOrEqual(viewport.innerHeight - 16);
+    await expect(panelRect.top).toBeGreaterThanOrEqual(16);
+    await expect(panelRect.bottom).toBeLessThanOrEqual(viewport.innerHeight - 16);
   },
 };
 
@@ -630,16 +639,16 @@ export const PanelTracksAncestorScrollAndVersionListScrollsInternally: Story = {
     scrollAncestor.scrollTop += scrollDelta;
     scrollAncestor.dispatchEvent(new Event('scroll', { bubbles: true }));
 
-    await waitFor(() => {
+    await waitFor(async () => {
       const triggerRectAfter = trigger.getBoundingClientRect();
-      expect(Math.abs(triggerRectAfter.top - (triggerRectBefore.top - scrollDelta))).toBeLessThan(
-        2,
-      );
+      await expect(
+        Math.abs(triggerRectAfter.top - (triggerRectBefore.top - scrollDelta)),
+      ).toBeLessThan(2);
     });
     const triggerRectAfter = trigger.getBoundingClientRect();
     const panelRectAfter = panel.getBoundingClientRect();
     const offsetAfter = panelRectAfter.top - triggerRectAfter.bottom;
-    expect(Math.abs(offsetAfter - offsetBefore)).toBeLessThanOrEqual(8);
+    await expect(Math.abs(offsetAfter - offsetBefore)).toBeLessThanOrEqual(8);
 
     // Part 2: the version list scrolls internally within the panel. Locate
     // the scroll region via the unconditional "All Versions" marker's
@@ -670,8 +679,8 @@ export const PanelTracksAncestorScrollAndVersionListScrollsInternally: Story = {
     scrollRegion.scrollTop = scrollRegion.scrollHeight;
     scrollRegion.dispatchEvent(new Event('scroll', { bubbles: true }));
 
-    await waitFor(() => {
-      expect(scrollRegion.scrollTop).toBeGreaterThan(initialScrollTop);
+    await waitFor(async () => {
+      await expect(scrollRegion.scrollTop).toBeGreaterThan(initialScrollTop);
     });
 
     const lastItemRect = lastItem.getBoundingClientRect();
@@ -679,14 +688,14 @@ export const PanelTracksAncestorScrollAndVersionListScrollsInternally: Story = {
       lastItemRect.left + lastItemRect.width / 2,
       lastItemRect.top + lastItemRect.height / 2,
     );
-    expect(hit === lastItem || (hit !== null && lastItem.contains(hit))).toBe(true);
+    await expect(hit === lastItem || (hit !== null && lastItem.contains(hit))).toBe(true);
   },
 };
 
 export const SameOriginIframeTopLayerRemainsInteractive: Story = {
   render: () => <SameOriginIframeHarness />,
   play: async ({ canvasElement }) => {
-    const { iframe, iframeDocument } = await waitFor(() => {
+    const { iframe, iframeDocument } = await waitFor(async () => {
       const currentIframe =
         canvasElement.querySelector<HTMLIFrameElement>('[data-testid="iframe"]');
       const currentDocument = currentIframe?.contentDocument;
@@ -706,7 +715,7 @@ export const SameOriginIframeTopLayerRemainsInteractive: Story = {
       '[data-yv-shadow-local-overlay]',
       'iframe top-layer container not created',
     );
-    const portalWrapper = await waitFor(() => {
+    const portalWrapper = await waitFor(async () => {
       const element = topLayer.firstElementChild;
       // SAFETY: A same-origin iframe exposes its realm's HTMLElement constructor on its Window.
       const frameWindow = iframe.contentWindow as
@@ -719,7 +728,7 @@ export const SameOriginIframeTopLayerRemainsInteractive: Story = {
     });
     const portalWindow = portalWrapper.ownerDocument.defaultView;
     if (!portalWindow) throw new Error('iframe portal window not available');
-    expect(portalWindow.getComputedStyle(portalWrapper).pointerEvents).toBe('auto');
+    await expect(portalWindow.getComputedStyle(portalWrapper).pointerEvents).toBe('auto');
 
     const input = await waitForElement<HTMLInputElement>(
       topLayer,
@@ -727,14 +736,16 @@ export const SameOriginIframeTopLayerRemainsInteractive: Story = {
       'iframe picker input not rendered',
     );
     await userEvent.click(input);
-    expect(componentRoot.activeElement).toBe(input);
+    await expect(componentRoot.activeElement).toBe(input);
 
     const panel = topLayer.querySelector<HTMLElement>('[data-slot="popover-content"]');
     if (!panel) throw new Error('iframe picker panel not rendered');
     const panelRect = panel.getBoundingClientRect();
     const frameWindow = iframe.contentWindow;
     if (!frameWindow) throw new Error('iframe window not available');
-    expect(panelRect.top).toBeGreaterThanOrEqual(16);
-    expect(panelRect.bottom).toBeLessThanOrEqual(frameWindow.innerHeight - 16);
+    await expect(panelRect.top).toBeGreaterThanOrEqual(16);
+    await expect(panelRect.bottom).toBeLessThanOrEqual(frameWindow.innerHeight - 16);
   },
 };
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
diff --git a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
index 3a00fc1b..f3eef8eb 100644
--- a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
@@ -1,4 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
+
 import { useTheme } from '@youversion/platform-react-hooks';
 import { http, HttpResponse } from 'msw';
 import { useCallback, useLayoutEffect, useRef, useState } from 'react';
@@ -38,7 +40,7 @@ function requireElement<ElementType extends Element>(
 }
 
 async function requireShadowHost(container: ParentNode): Promise<HTMLElement> {
-  return waitFor(() => {
+  return waitFor(async () => {
     const host = requireElement<HTMLElement>(
       container,
       '[data-yv-shadow-host]',
@@ -188,13 +190,13 @@ export const FormsAndExternalRelationshipsStopAtTheTreeScope: Story = {
       'isolated textarea not rendered',
     );
 
-    expect(textarea.form).toBeNull();
-    expect(form.elements.namedItem('notes')).toBeNull();
-    expect(new FormData(form).has('notes')).toBe(false);
+    await expect(textarea.form).toBeNull();
+    await expect(form.elements.namedItem('notes')).toBeNull();
+    await expect(new FormData(form).has('notes')).toBe(false);
 
-    expect(label.control).toBeNull();
+    await expect(label.control).toBeNull();
     await userEvent.click(label);
-    expect(root.activeElement).not.toBe(textarea);
+    await expect(root.activeElement).not.toBe(textarea);
 
     type ReflectedAriaElement = HTMLElement & {
       ariaLabelledByElements?: readonly Element[];
@@ -209,10 +211,10 @@ export const FormsAndExternalRelationshipsStopAtTheTreeScope: Story = {
       throw new Error('browser did not expose ariaDescribedByElements');
     }
 
-    expect(textarea.getAttribute('aria-labelledby')).toBe('external-name');
-    expect(textarea.getAttribute('aria-describedby')).toBe('external-description');
-    expect(reflectedTextarea.ariaLabelledByElements).toEqual([]);
-    expect(reflectedTextarea.ariaDescribedByElements).toEqual([]);
+    await expect(textarea.getAttribute('aria-labelledby')).toBe('external-name');
+    await expect(textarea.getAttribute('aria-describedby')).toBe('external-description');
+    await expect(reflectedTextarea.ariaLabelledByElements).toEqual([]);
+    await expect(reflectedTextarea.ariaDescribedByElements).toEqual([]);
   },
 };
 
@@ -279,7 +281,7 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
   name: 'Events, refs, and DOM queries expose different views',
   render: () => <AutomaticButtonHarness />,
   play: async ({ canvasElement }) => {
-    const observer = await waitFor(() =>
+    const observer = await waitFor(async () =>
       requireElement<HTMLElement>(
         canvasElement,
         '[data-testid="consumer-observer"]',
@@ -294,8 +296,8 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
       'isolated auth button not rendered',
     );
 
-    expect(canvasElement.querySelector('[data-testid="isolated-auth-button"]')).toBeNull();
-    expect(root.querySelector('[data-testid="isolated-auth-button"]')).toBe(button);
+    await expect(canvasElement.querySelector('[data-testid="isolated-auth-button"]')).toBeNull();
+    await expect(root.querySelector('[data-testid="isolated-auth-button"]')).toBe(button);
     const firstLayoutEvidence = requireElement<HTMLOutputElement>(
       canvasElement,
       '[data-testid="first-layout-ref-state"]',
@@ -317,9 +319,9 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
       'consumer current target evidence not rendered',
     );
 
-    void expect(firstLayoutEvidence).toHaveTextContent('null');
-    void expect(firstLayoutEvidence).toHaveAttribute('hidden');
-    await waitFor(() => expect(forwardedRefEvidence.observedNode).toBe(button));
+    await expect(firstLayoutEvidence).toHaveTextContent('null');
+    await expect(firstLayoutEvidence).toHaveAttribute('hidden');
+    await waitFor(async () => await expect(forwardedRefEvidence.observedNode).toBe(button));
 
     const clickTarget = requireElement<HTMLDivElement>(
       button,
@@ -339,12 +341,12 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
 
     await userEvent.click(clickTarget);
 
-    expect(outsideTarget).toBe(host);
-    expect(outsidePath[0]).toBe(clickTarget);
-    expect(outsidePath).toContain(button);
-    expect(outsidePath).toContain(host);
-    expect(consumerTargetEvidence.observedNode).toBe(clickTarget);
-    expect(consumerCurrentTargetEvidence.observedNode).toBe(button);
+    await expect(outsideTarget).toBe(host);
+    await expect(outsidePath[0]).toBe(clickTarget);
+    await expect(outsidePath).toContain(button);
+    await expect(outsidePath).toContain(host);
+    await expect(consumerTargetEvidence.observedNode).toBe(clickTarget);
+    await expect(consumerCurrentTargetEvidence.observedNode).toBe(button);
   },
 };
 
@@ -384,9 +386,9 @@ export const NestedRootsRequireTraversalAndRetargetAtEveryBoundary: Story = {
       'nested auth button not rendered',
     );
 
-    expect(canvasElement.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
-    expect(outerRoot.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
-    expect(innerRoot.querySelector('[data-testid="nested-auth-button"]')).toBe(button);
+    await expect(canvasElement.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
+    await expect(outerRoot.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
+    await expect(innerRoot.querySelector('[data-testid="nested-auth-button"]')).toBe(button);
 
     let outerScopeTarget: EventTarget | null = null;
     let documentScopeTarget: EventTarget | null = null;
@@ -409,10 +411,12 @@ export const NestedRootsRequireTraversalAndRetargetAtEveryBoundary: Story = {
 
     await userEvent.click(button);
 
-    expect(outerScopeTarget).toBe(innerHost);
-    expect(documentScopeTarget).toBe(outerHost);
-    expect(composedPath[0]).toBe(button);
-    expect(composedPath).toContain(innerHost);
-    expect(composedPath).toContain(outerHost);
+    await expect(outerScopeTarget).toBe(innerHost);
+    await expect(documentScopeTarget).toBe(outerHost);
+    await expect(composedPath[0]).toBe(button);
+    await expect(composedPath).toContain(innerHost);
+    await expect(composedPath).toContain(outerHost);
   },
 };
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
diff --git a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
index d6c2d119..48a4249f 100644
--- a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
@@ -1,4 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
+
 import { http, HttpResponse } from 'msw';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { spyOn, userEvent, waitFor } from 'storybook/test';
@@ -218,11 +220,11 @@ function getPermissionDialog(topLayer: HTMLElement): HTMLElement | null {
   );
 }
 
-function expectOverlayAboveAtOverlap(
+async function expectOverlayAboveAtOverlap(
   root: ShadowRoot,
   expectedTop: HTMLElement,
   underneath: HTMLElement,
-): void {
+): Promise<void> {
   const topRect = expectedTop.getBoundingClientRect();
   const underneathRect = underneath.getBoundingClientRect();
   const overlapLeft = Math.max(topRect.left, underneathRect.left);
@@ -230,14 +232,14 @@ function expectOverlayAboveAtOverlap(
   const overlapTop = Math.max(topRect.top, underneathRect.top);
   const overlapBottom = Math.min(topRect.bottom, underneathRect.bottom);
 
-  expect(overlapRight).toBeGreaterThan(overlapLeft);
-  expect(overlapBottom).toBeGreaterThan(overlapTop);
+  await expect(overlapRight).toBeGreaterThan(overlapLeft);
+  await expect(overlapBottom).toBeGreaterThan(overlapTop);
 
   const hit = root.elementFromPoint(
     overlapLeft + (overlapRight - overlapLeft) / 2,
     overlapTop + (overlapBottom - overlapTop) / 2,
   );
-  expect(hit === expectedTop || (hit !== null && expectedTop.contains(hit))).toBe(true);
+  await expect(hit === expectedTop || (hit !== null && expectedTop.contains(hit))).toBe(true);
 }
 
 function placeOverlayCenterUnderneath(
@@ -311,7 +313,7 @@ async function getPrimaryHarness(canvasElement: HTMLElement): Promise<PrimaryHar
   const root = await waitForShadowRoot(primaryIsland);
   const contentWrapper = root.querySelector<HTMLElement>('[data-yv-shadow-content-wrapper]');
   if (!contentWrapper) throw new Error('shadow content wrapper not rendered');
-  expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+  await expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
   return { contentWrapper, primaryIsland, root };
 }
 
@@ -332,7 +334,7 @@ async function openVerseActionPopover(
     'verse action popover not rendered',
     productionWaitOptions,
   );
-  await waitFor(() => expect(topLayer.matches(':popover-open')).toBe(true));
+  await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(true));
   return { topLayer, versePopover };
 }
 
@@ -343,7 +345,7 @@ async function openPermissionDialogFromVerseAction(
   const swatch = versePopover.querySelector<HTMLButtonElement>('[role="group"] button');
   if (!swatch) throw new Error('highlight swatch not rendered');
   await userEvent.click(swatch);
-  return waitFor(() => {
+  return waitFor(async () => {
     const dialog = getPermissionDialog(topLayer);
     if (!dialog) throw new Error('highlight permission dialog not rendered');
     return dialog;
@@ -423,36 +425,36 @@ export const PopoverOpensDialogEvidence: Story = {
           opened.topLayer,
           opened.versePopover,
         );
-        expect(opened.versePopover.getRootNode()).toBe(root);
-        expect(permissionDialog.getRootNode()).toBe(root);
+        await expect(opened.versePopover.getRootNode()).toBe(root);
+        await expect(permissionDialog.getRootNode()).toBe(root);
         const restorePosition = placeOverlayCenterUnderneath(opened.versePopover, permissionDialog);
         try {
-          expectOverlayAboveAtOverlap(root, permissionDialog, opened.versePopover);
+          await expectOverlayAboveAtOverlap(root, permissionDialog, opened.versePopover);
         } finally {
           restorePosition();
         }
-        await waitFor(() => {
+        await waitFor(async () => {
           const focused = root.activeElement;
-          expect(focused !== null && permissionDialog.contains(focused)).toBe(true);
+          await expect(focused !== null && permissionDialog.contains(focused)).toBe(true);
         }, productionWaitOptions);
-        expect(contentWrapper.inert).toBe(true);
-        void expect(opened.versePopover).toHaveAttribute('data-state', 'open');
+        await expect(contentWrapper.inert).toBe(true);
+        await expect(opened.versePopover).toHaveAttribute('data-state', 'open');
       });
 
       await step('Escape dismisses one nested overlay at a time', async () => {
         await userEvent.keyboard('{Escape}');
-        await waitFor(() => {
-          expect(getPermissionDialog(topLayer)).toBeNull();
-          expect(topLayer.querySelector('[data-slot="verse-action-popover"]')).not.toBeNull();
-          expect(contentWrapper.inert).toBe(false);
+        await waitFor(async () => {
+          await expect(getPermissionDialog(topLayer)).toBeNull();
+          await expect(topLayer.querySelector('[data-slot="verse-action-popover"]')).not.toBeNull();
+          await expect(contentWrapper.inert).toBe(false);
           const focused = root.activeElement;
-          expect(focused !== null && versePopover.contains(focused)).toBe(true);
+          await expect(focused !== null && versePopover.contains(focused)).toBe(true);
         }, productionWaitOptions);
         await userEvent.keyboard('{Escape}');
-        await waitFor(() => {
-          expect(topLayer.querySelector('[data-slot="verse-action-popover"]')).toBeNull();
-          expect(topLayer.matches(':popover-open')).toBe(false);
-          expect(root.activeElement).toBe(priorControl);
+        await waitFor(async () => {
+          await expect(topLayer.querySelector('[data-slot="verse-action-popover"]')).toBeNull();
+          await expect(topLayer.matches(':popover-open')).toBe(false);
+          await expect(root.activeElement).toBe(priorControl);
         }, productionWaitOptions);
       });
 
@@ -475,24 +477,26 @@ export const PopoverOpensDialogEvidence: Story = {
         if (!dialogOverlay) throw new Error('dialog overlay not rendered');
         closeAllOverlays.click();
         closeAllOverlays.click();
-        await waitFor(() => {
-          void expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
-          void expect(permissionDialog).toHaveAttribute('data-state', 'closed');
+        await waitFor(async () => {
+          await expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
+          await expect(permissionDialog).toHaveAttribute('data-state', 'closed');
         }, productionWaitOptions);
         finishAnimations(opened.versePopover);
-        await waitFor(() => {
-          expect(opened.topLayer.querySelector('[data-slot="verse-action-popover"]')).toBeNull();
-          expect(getPermissionDialog(opened.topLayer)).toBe(permissionDialog);
-          expect(contentWrapper.inert).toBe(true);
+        await waitFor(async () => {
+          await expect(
+            opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
+          ).toBeNull();
+          await expect(getPermissionDialog(opened.topLayer)).toBe(permissionDialog);
+          await expect(contentWrapper.inert).toBe(true);
         }, productionWaitOptions);
         finishAnimations(permissionDialog);
         finishAnimations(dialogOverlay);
-        await waitFor(() => {
-          expect(getPermissionDialog(opened.topLayer)).toBeNull();
-          expect(contentWrapper.inert).toBe(false);
-          expect(opened.topLayer.matches(':popover-open')).toBe(false);
+        await waitFor(async () => {
+          await expect(getPermissionDialog(opened.topLayer)).toBeNull();
+          await expect(contentWrapper.inert).toBe(false);
+          await expect(opened.topLayer.matches(':popover-open')).toBe(false);
         }, productionWaitOptions);
-        expect(closeAllRequests.getAttribute('data-count')).toBe('2');
+        await expect(closeAllRequests.getAttribute('data-count')).toBe('2');
       });
 
       await step('Finish teardown when the dialog exits first', async () => {
@@ -514,25 +518,27 @@ export const PopoverOpensDialogEvidence: Story = {
         );
         if (!dialogOverlay) throw new Error('dialog overlay not rendered');
         closeAllOverlays.click();
-        await waitFor(() => {
-          void expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
-          void expect(permissionDialog).toHaveAttribute('data-state', 'closed');
+        await waitFor(async () => {
+          await expect(opened.versePopover).toHaveAttribute('data-state', 'closed');
+          await expect(permissionDialog).toHaveAttribute('data-state', 'closed');
         }, productionWaitOptions);
         finishAnimations(permissionDialog);
         finishAnimations(dialogOverlay);
-        await waitFor(() => {
-          expect(getPermissionDialog(opened.topLayer)).toBeNull();
-          expect(
+        await waitFor(async () => {
+          await expect(getPermissionDialog(opened.topLayer)).toBeNull();
+          await expect(
             opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
           ).not.toBeNull();
         }, productionWaitOptions);
         finishAnimations(opened.versePopover);
-        await waitFor(() => {
-          expect(opened.topLayer.querySelector('[data-slot="verse-action-popover"]')).toBeNull();
-          expect(contentWrapper.inert).toBe(false);
-          expect(opened.topLayer.matches(':popover-open')).toBe(false);
+        await waitFor(async () => {
+          await expect(
+            opened.topLayer.querySelector('[data-slot="verse-action-popover"]'),
+          ).toBeNull();
+          await expect(contentWrapper.inert).toBe(false);
+          await expect(opened.topLayer.matches(':popover-open')).toBe(false);
         }, productionWaitOptions);
-        expect(closeAllRequests.getAttribute('data-count')).toBe('3');
+        await expect(closeAllRequests.getAttribute('data-count')).toBe('3');
       });
     } finally {
       for (const style of exitAnimationStyles) style.remove();
@@ -590,7 +596,7 @@ export const DialogContainsPopoverEvidence: Story = {
       );
       const restorePosition = placeOverlayCenterUnderneath(notesDialog, notesPopover);
       try {
-        expectOverlayAboveAtOverlap(root, notesPopover, notesDialog);
+        await expectOverlayAboveAtOverlap(root, notesPopover, notesDialog);
       } finally {
         restorePosition();
       }
@@ -601,27 +607,27 @@ export const DialogContainsPopoverEvidence: Story = {
         productionWaitOptions,
       );
       await userEvent.click(notesAction);
-      await waitFor(() => expect(noteActionCount.getAttribute('data-count')).toBe('1'));
-      await waitFor(() => {
+      await waitFor(async () => await expect(noteActionCount.getAttribute('data-count')).toBe('1'));
+      await waitFor(async () => {
         const focused = root.activeElement;
-        expect(focused !== null && notesPopover.contains(focused)).toBe(true);
+        await expect(focused !== null && notesPopover.contains(focused)).toBe(true);
       });
     });
 
     await step('Escape closes only the popover and restores its trigger', async () => {
       await userEvent.keyboard('{Escape}');
-      await waitFor(() => expect(notesPopover.isConnected).toBe(false));
-      void expect(topLayer).toContainElement(notesDialog);
-      expect(root.activeElement).toBe(notesTrigger);
-      expect(contentWrapper.inert).toBe(true);
+      await waitFor(async () => await expect(notesPopover.isConnected).toBe(false));
+      await expect(topLayer).toContainElement(notesDialog);
+      await expect(root.activeElement).toBe(notesTrigger);
+      await expect(contentWrapper.inert).toBe(true);
     });
 
     await step('The next Escape closes the dialog and restores its opener', async () => {
       await userEvent.keyboard('{Escape}');
-      await waitFor(() => expect(notesDialog.isConnected).toBe(false));
-      await waitFor(() => expect(contentWrapper.inert).toBe(false));
-      await waitFor(() => expect(topLayer.matches(':popover-open')).toBe(false));
-      expect(root.activeElement).toBe(openNotes);
+      await waitFor(async () => await expect(notesDialog.isConnected).toBe(false));
+      await waitFor(async () => await expect(contentWrapper.inert).toBe(false));
+      await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(false));
+      await expect(root.activeElement).toBe(openNotes);
     });
   },
 };
@@ -659,16 +665,16 @@ export const TwoIndependentOverlaysEvidence: Story = {
         'independent popover not rendered',
         productionWaitOptions,
       );
-      await waitFor(() => {
+      await waitFor(async () => {
         const focused = root.activeElement;
-        expect(focused !== null && independentPopover.contains(focused)).toBe(true);
+        await expect(focused !== null && independentPopover.contains(focused)).toBe(true);
       });
-      expect(contentWrapper.inert).toBe(false);
+      await expect(contentWrapper.inert).toBe(false);
       await userEvent.keyboard('{Escape}');
-      await waitFor(() => expect(independentPopover.isConnected).toBe(false));
-      expect(root.activeElement).toBe(independentTrigger);
+      await waitFor(async () => await expect(independentPopover.isConnected).toBe(false));
+      await expect(root.activeElement).toBe(independentTrigger);
       closeAllOverlays.click();
-      await waitFor(() => expect(topLayer.matches(':popover-open')).toBe(false));
+      await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(false));
     });
 
     await step('Keep the secondary root usable through primary teardown', async () => {
@@ -700,7 +706,7 @@ export const TwoIndependentOverlaysEvidence: Story = {
       );
 
       const opened = await openVerseActionPopover(root, verse);
-      expect(opened.topLayer).not.toBe(secondaryTopLayer);
+      await expect(opened.topLayer).not.toBe(secondaryTopLayer);
       await openPermissionDialogFromVerseAction(opened.topLayer, opened.versePopover);
       const unmountPrimary = await waitForElement<HTMLButtonElement>(
         canvasElement,
@@ -709,11 +715,13 @@ export const TwoIndependentOverlaysEvidence: Story = {
         productionWaitOptions,
       );
       unmountPrimary.click();
-      await waitFor(() => expect(primaryIsland.isConnected).toBe(false));
+      await waitFor(async () => await expect(primaryIsland.isConnected).toBe(false));
       closeAllOverlays.click();
-      await waitFor(() => expect(secondaryPopover.isConnected).toBe(false));
-      await waitFor(() => expect(secondaryTopLayer.matches(':popover-open')).toBe(false));
-      expect(secondaryIsland.isConnected).toBe(true);
+      await waitFor(async () => await expect(secondaryPopover.isConnected).toBe(false));
+      await waitFor(
+        async () => await expect(secondaryTopLayer.matches(':popover-open')).toBe(false),
+      );
+      await expect(secondaryIsland.isConnected).toBe(true);
 
       await userEvent.click(secondaryTrigger);
       const reopenedSecondaryPopover = await waitForElement<HTMLElement>(
@@ -722,8 +730,8 @@ export const TwoIndependentOverlaysEvidence: Story = {
         'secondary popover did not reopen after primary teardown',
         productionWaitOptions,
       );
-      void expect(reopenedSecondaryPopover).toHaveAttribute('data-state', 'open');
-      expect(secondaryTopLayer.matches(':popover-open')).toBe(true);
+      await expect(reopenedSecondaryPopover).toHaveAttribute('data-state', 'open');
+      await expect(secondaryTopLayer.matches(':popover-open')).toBe(true);
     });
   },
 };
@@ -757,7 +765,7 @@ export const RapidCloseReopenDuringExitEvidence: Story = {
           'shadow-local top layer not created',
           productionWaitOptions,
         );
-        firstDialog = await waitFor(() => {
+        firstDialog = await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog) throw new Error('permission dialog did not open');
           return dialog;
@@ -765,52 +773,54 @@ export const RapidCloseReopenDuringExitEvidence: Story = {
       });
 
       await step('Retain modal ownership while the dialog starts exiting', async () => {
-        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
-        expect(firstDialog.isConnected).toBe(true);
-        void expect(topLayer).toContainElement(firstDialog);
-        expect(contentWrapper.inert).toBe(true);
+        await waitFor(
+          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
+        );
+        await expect(firstDialog.isConnected).toBe(true);
+        await expect(topLayer).toContainElement(firstDialog);
+        await expect(contentWrapper.inert).toBe(true);
       });
 
       await step('Preserve modal focus after the first dialog unmounts', async () => {
-        await waitFor(() => {
-          expect(firstDialog.isConnected).toBe(false);
+        await waitFor(async () => {
+          await expect(firstDialog.isConnected).toBe(false);
           const overlay = topLayer.querySelector<HTMLElement>('[data-slot="dialog-overlay"]');
           if (!overlay) throw new Error('dialog overlay did not remain during content exit');
           const currentDialog = getPermissionDialog(topLayer);
           const focused = root.activeElement;
-          expect(
+          await expect(
             focused === overlay ||
               (focused !== null && currentDialog !== null && currentDialog.contains(focused)),
           ).toBe(true);
-          expect(contentWrapper.inert).toBe(true);
-          expect(topLayer.matches(':popover-open')).toBe(true);
+          await expect(contentWrapper.inert).toBe(true);
+          await expect(topLayer.matches(':popover-open')).toBe(true);
         });
       });
 
       await step('Reopen from overlay-only retained presence', async () => {
-        const reopenedDialog = await waitFor(() => {
+        const reopenedDialog = await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not reopen during exit');
           }
           return dialog;
         });
-        expect(reopenedDialog).not.toBe(firstDialog);
-        await waitFor(() => {
+        await expect(reopenedDialog).not.toBe(firstDialog);
+        await waitFor(async () => {
           const focused = root.activeElement;
-          expect(focused !== null && reopenedDialog.contains(focused)).toBe(true);
-          expect(contentWrapper.inert).toBe(true);
-          expect(topLayer.matches(':popover-open')).toBe(true);
+          await expect(focused !== null && reopenedDialog.contains(focused)).toBe(true);
+          await expect(contentWrapper.inert).toBe(true);
+          await expect(topLayer.matches(':popover-open')).toBe(true);
         });
       });
 
       await step('Release modal ownership after the final close', async () => {
         await userEvent.keyboard('{Escape}');
-        await waitFor(() => {
-          expect(getPermissionDialog(topLayer)).toBeNull();
-          expect(contentWrapper.inert).toBe(false);
-          expect(topLayer.matches(':popover-open')).toBe(false);
-          expect(root.activeElement).toBe(runRapidCloseReopen);
+        await waitFor(async () => {
+          await expect(getPermissionDialog(topLayer)).toBeNull();
+          await expect(contentWrapper.inert).toBe(false);
+          await expect(topLayer.matches(':popover-open')).toBe(false);
+          await expect(root.activeElement).toBe(runRapidCloseReopen);
         });
       });
     } finally {
@@ -850,44 +860,48 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
           '[data-yv-shadow-local-overlay]',
           'shadow-local top layer not created',
         );
-        const firstDialog = await waitFor(() => {
+        const firstDialog = await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog) throw new Error('permission dialog did not open');
           return dialog;
         });
-        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
-        await waitFor(() => {
+        await waitFor(
+          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
+        );
+        await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not reopen during exit');
           }
-          expect(contentWrapper.inert).toBe(true);
+          await expect(contentWrapper.inert).toBe(true);
         });
       });
 
       await step('Ignore the opener after it moves to another shadow root', async () => {
         secondaryRoot.append(runRapidCloseReopen);
-        expect(runRapidCloseReopen.getRootNode()).toBe(secondaryRoot);
+        await expect(runRapidCloseReopen.getRootNode()).toBe(secondaryRoot);
 
         await userEvent.keyboard('{Escape}');
-        await waitFor(() => {
-          expect(getPermissionDialog(topLayer)).toBeNull();
-          expect(contentWrapper.inert).toBe(false);
-          expect(topLayer.matches(':popover-open')).toBe(false);
+        await waitFor(async () => {
+          await expect(getPermissionDialog(topLayer)).toBeNull();
+          await expect(contentWrapper.inert).toBe(false);
+          await expect(topLayer.matches(':popover-open')).toBe(false);
         });
-        expect(secondaryRoot.activeElement).not.toBe(runRapidCloseReopen);
+        await expect(secondaryRoot.activeElement).not.toBe(runRapidCloseReopen);
       });
 
       await step('Ignore the opener after it moves into the light DOM', async () => {
         contentWrapper.append(runRapidCloseReopen);
         await userEvent.click(runRapidCloseReopen);
-        const firstDialog = await waitFor(() => {
+        const firstDialog = await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog) throw new Error('permission dialog did not reopen for light-DOM target');
           return dialog;
         });
-        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
-        await waitFor(() => {
+        await waitFor(
+          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
+        );
+        await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not rapidly reopen for light-DOM target');
@@ -897,15 +911,15 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
         const focus = spyOn(runRapidCloseReopen, 'focus');
         try {
           canvasElement.ownerDocument.body.append(runRapidCloseReopen);
-          expect(runRapidCloseReopen.getRootNode()).toBe(canvasElement.ownerDocument);
+          await expect(runRapidCloseReopen.getRootNode()).toBe(canvasElement.ownerDocument);
           await userEvent.keyboard('{Escape}');
-          await waitFor(() => {
-            expect(getPermissionDialog(topLayer)).toBeNull();
-            expect(contentWrapper.inert).toBe(false);
-            expect(topLayer.matches(':popover-open')).toBe(false);
+          await waitFor(async () => {
+            await expect(getPermissionDialog(topLayer)).toBeNull();
+            await expect(contentWrapper.inert).toBe(false);
+            await expect(topLayer.matches(':popover-open')).toBe(false);
           });
-          expect(focus).not.toHaveBeenCalled();
-          expect(canvasElement.ownerDocument.activeElement).not.toBe(runRapidCloseReopen);
+          await expect(focus).not.toHaveBeenCalled();
+          await expect(canvasElement.ownerDocument.activeElement).not.toBe(runRapidCloseReopen);
         } finally {
           focus.mockRestore();
         }
@@ -914,13 +928,15 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
       await step('Ignore the opener after it disconnects', async () => {
         contentWrapper.append(runRapidCloseReopen);
         await userEvent.click(runRapidCloseReopen);
-        const firstDialog = await waitFor(() => {
+        const firstDialog = await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog) throw new Error('permission dialog did not reopen for disconnected target');
           return dialog;
         });
-        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
-        await waitFor(() => {
+        await waitFor(
+          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
+        );
+        await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not rapidly reopen for disconnected target');
@@ -930,15 +946,15 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
         const focus = spyOn(runRapidCloseReopen, 'focus');
         try {
           runRapidCloseReopen.remove();
-          expect(runRapidCloseReopen.isConnected).toBe(false);
+          await expect(runRapidCloseReopen.isConnected).toBe(false);
           await userEvent.keyboard('{Escape}');
-          await waitFor(() => {
-            expect(getPermissionDialog(topLayer)).toBeNull();
-            expect(contentWrapper.inert).toBe(false);
-            expect(topLayer.matches(':popover-open')).toBe(false);
+          await waitFor(async () => {
+            await expect(getPermissionDialog(topLayer)).toBeNull();
+            await expect(contentWrapper.inert).toBe(false);
+            await expect(topLayer.matches(':popover-open')).toBe(false);
           });
-          expect(focus).not.toHaveBeenCalled();
-          expect(root.activeElement).not.toBe(runRapidCloseReopen);
+          await expect(focus).not.toHaveBeenCalled();
+          await expect(root.activeElement).not.toBe(runRapidCloseReopen);
         } finally {
           focus.mockRestore();
         }
@@ -947,14 +963,16 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
       await step('Ignore the opener after it moves to another document', async () => {
         contentWrapper.append(runRapidCloseReopen);
         await userEvent.click(runRapidCloseReopen);
-        const firstDialog = await waitFor(() => {
+        const firstDialog = await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog)
             throw new Error('permission dialog did not reopen for cross-document target');
           return dialog;
         });
-        await waitFor(() => void expect(firstDialog).toHaveAttribute('data-state', 'closed'));
-        await waitFor(() => {
+        await waitFor(
+          async () => await expect(firstDialog).toHaveAttribute('data-state', 'closed'),
+        );
+        await waitFor(async () => {
           const dialog = getPermissionDialog(topLayer);
           if (!dialog || dialog.getAttribute('data-state') === 'closed') {
             throw new Error('permission dialog did not rapidly reopen for cross-document target');
@@ -965,15 +983,15 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
         const focus = spyOn(runRapidCloseReopen, 'focus');
         try {
           secondaryDocument.body.append(runRapidCloseReopen);
-          expect(runRapidCloseReopen.isConnected).toBe(true);
-          expect(runRapidCloseReopen.ownerDocument).toBe(secondaryDocument);
+          await expect(runRapidCloseReopen.isConnected).toBe(true);
+          await expect(runRapidCloseReopen.ownerDocument).toBe(secondaryDocument);
           await userEvent.keyboard('{Escape}');
-          await waitFor(() => {
-            expect(getPermissionDialog(topLayer)).toBeNull();
-            expect(contentWrapper.inert).toBe(false);
-            expect(topLayer.matches(':popover-open')).toBe(false);
+          await waitFor(async () => {
+            await expect(getPermissionDialog(topLayer)).toBeNull();
+            await expect(contentWrapper.inert).toBe(false);
+            await expect(topLayer.matches(':popover-open')).toBe(false);
           });
-          expect(focus).not.toHaveBeenCalled();
+          await expect(focus).not.toHaveBeenCalled();
         } finally {
           focus.mockRestore();
         }
@@ -983,3 +1001,5 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
     }
   },
 };
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
diff --git a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
index 65e883ed..98305e51 100644
--- a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
+++ b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
@@ -1,4 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
+
 import type { BibleBook, BibleVersion } from '@youversion/platform-core';
 import { YouVersionContext, type HookOverrides } from '@youversion/platform-react-hooks';
 import { http, HttpResponse } from 'msw';
@@ -222,11 +224,11 @@ interface MountedFixture {
   sheet: CSSStyleSheet;
 }
 
-function requireMountedFixture(canvasElement: HTMLElement): MountedFixture {
+async function requireMountedFixture(canvasElement: HTMLElement): Promise<MountedFixture> {
   const hosts = Array.from(
     canvasElement.ownerDocument.querySelectorAll<HTMLElement>('[data-yv-shadow-host]'),
   );
-  expect(hosts).toHaveLength(EXPECTED_COMPONENT_IDS.length);
+  await expect(hosts).toHaveLength(EXPECTED_COMPONENT_IDS.length);
 
   const roots = hosts.map((host) => {
     if (!host.shadowRoot) throw new Error('shadow root not attached');
@@ -236,7 +238,7 @@ function requireMountedFixture(canvasElement: HTMLElement): MountedFixture {
     (root) =>
       root.querySelector<HTMLElement>('[data-realistic-component]')?.dataset.realisticComponent,
   );
-  expect(componentIds).toEqual(EXPECTED_COMPONENT_IDS);
+  await expect(componentIds).toEqual(EXPECTED_COMPONENT_IDS);
 
   const components = new Map(
     roots.map((root, index) => [
@@ -252,31 +254,35 @@ function requireMountedFixture(canvasElement: HTMLElement): MountedFixture {
     ['votd-large', 'JHN.3.16'],
   ]);
   for (const [id, usfm] of expectedPassages) {
-    void expect(components.get(id)).toHaveTextContent(`Fixture scripture content for ${usfm}.`);
+    await expect(components.get(id)).toHaveTextContent(`Fixture scripture content for ${usfm}.`);
   }
-  expect(
+  await expect(
     components.get('avatar-primary')?.querySelector('[aria-label="SDK Reader"]'),
   ).not.toBeNull();
-  expect(
+  await expect(
     components.get('avatar-secondary')?.querySelector('[aria-label="Bible Partner"]'),
   ).not.toBeNull();
-  void expect(components.get('notes-primary')?.querySelector('textarea')).toHaveValue(
+  await expect(components.get('notes-primary')?.querySelector('textarea')).toHaveValue(
     'Primary notes',
   );
-  void expect(components.get('notes-secondary')?.querySelector('textarea')).toHaveValue(
+  await expect(components.get('notes-secondary')?.querySelector('textarea')).toHaveValue(
     'Secondary notes',
   );
-  void expect(components.get('notes-tertiary')?.querySelector('textarea')).toHaveValue(
+  await expect(components.get('notes-tertiary')?.querySelector('textarea')).toHaveValue(
     'Tertiary notes',
   );
-  expect(components.get('separator-primary')?.querySelector('[role="separator"]')).not.toBeNull();
-  expect(components.get('separator-secondary')?.querySelector('[role="separator"]')).not.toBeNull();
+  await expect(
+    components.get('separator-primary')?.querySelector('[role="separator"]'),
+  ).not.toBeNull();
+  await expect(
+    components.get('separator-secondary')?.querySelector('[role="separator"]'),
+  ).not.toBeNull();
 
   const sheet = roots[0]?.adoptedStyleSheets[0];
   if (!sheet) throw new Error('shared SDK stylesheet not adopted');
   for (const root of roots) {
-    expect(root.adoptedStyleSheets).toHaveLength(1);
-    expect(root.adoptedStyleSheets[0]).toBe(sheet);
+    await expect(root.adoptedStyleSheets).toHaveLength(1);
+    await expect(root.adoptedStyleSheets[0]).toBe(sheet);
   }
 
   return { hosts, sheet };
@@ -302,13 +308,13 @@ const STRICT_EFFECT_COUNTS: ExpectedEffectCounts = import.meta.env.DEV
     }
   : NORMAL_EFFECT_COUNTS;
 
-function requireEffectCounts(
+async function requireEffectCounts(
   canvasElement: HTMLElement,
   [setup, cleanup]: [setup: number, cleanup: number],
-): void {
+): Promise<void> {
   const counts = canvasElement.querySelector('[data-testid="effect-lifecycle-counts"]');
-  void expect(counts).toHaveAttribute('data-effect-setup', String(setup));
-  void expect(counts).toHaveAttribute('data-effect-cleanup', String(cleanup));
+  await expect(counts).toHaveAttribute('data-effect-setup', String(setup));
+  await expect(counts).toHaveAttribute('data-effect-cleanup', String(cleanup));
 }
 
 async function exerciseLifecycle(
@@ -321,27 +327,27 @@ async function exerciseLifecycle(
 
   try {
     await userEvent.click(toggle);
-    const firstMount = await waitFor(() => {
-      const fixture = requireMountedFixture(canvasElement);
-      requireEffectCounts(canvasElement, expectedEffectCounts.firstMount);
+    const firstMount = await waitFor(async () => {
+      const fixture = await requireMountedFixture(canvasElement);
+      await requireEffectCounts(canvasElement, expectedEffectCounts.firstMount);
       return fixture;
     });
 
     await userEvent.click(toggle);
-    expect(canvasElement.querySelectorAll('[data-yv-shadow-host]')).toHaveLength(0);
-    expect(canvasElement.querySelector('[data-testid="realistic-component-mix"]')).toBeNull();
-    requireEffectCounts(canvasElement, expectedEffectCounts.removal);
+    await expect(canvasElement.querySelectorAll('[data-yv-shadow-host]')).toHaveLength(0);
+    await expect(canvasElement.querySelector('[data-testid="realistic-component-mix"]')).toBeNull();
+    await requireEffectCounts(canvasElement, expectedEffectCounts.removal);
 
     await userEvent.click(toggle);
-    const secondMount = await waitFor(() => {
-      const fixture = requireMountedFixture(canvasElement);
-      requireEffectCounts(canvasElement, expectedEffectCounts.secondMount);
+    const secondMount = await waitFor(async () => {
+      const fixture = await requireMountedFixture(canvasElement);
+      await requireEffectCounts(canvasElement, expectedEffectCounts.secondMount);
       return fixture;
     });
     for (const host of secondMount.hosts) {
-      expect(host.shadowRoot?.adoptedStyleSheets[0]).toBe(firstMount.sheet);
+      await expect(host.shadowRoot?.adoptedStyleSheets[0]).toBe(firstMount.sheet);
     }
-    expect(consoleError).not.toHaveBeenCalled();
+    await expect(consoleError).not.toHaveBeenCalled();
   } finally {
     consoleError.mockRestore();
   }
@@ -368,3 +374,5 @@ export const StrictModeLifecycle: Story = {
     await exerciseLifecycle(canvasElement, STRICT_EFFECT_COUNTS);
   },
 };
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
diff --git a/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx b/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
index 83b1b185..44204318 100644
--- a/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
@@ -1,4 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
+
 import { http, HttpResponse } from 'msw';
 import { useState } from 'react';
 import { userEvent, waitFor } from 'storybook/test';
@@ -73,16 +75,16 @@ async function expectOutsideFocusRedirectedInto(
   dialog: HTMLElement,
 ): Promise<void> {
   outsideControl.focus();
-  await waitFor(() => {
+  await waitFor(async () => {
     const focused = root.activeElement;
-    expect(focused !== null && dialog.contains(focused)).toBe(true);
+    await expect(focused !== null && dialog.contains(focused)).toBe(true);
   });
-  expect(outsideControl.ownerDocument.activeElement).not.toBe(outsideControl);
+  await expect(outsideControl.ownerDocument.activeElement).not.toBe(outsideControl);
 }
 
 export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
   play: async ({ canvasElement }) => {
-    const { outsideControl, clippingContainer } = await waitFor(() => {
+    const { outsideControl, clippingContainer } = await waitFor(async () => {
       const outside = canvasElement.querySelector<HTMLButtonElement>(
         '[data-testid="outside-control"]',
       );
@@ -100,15 +102,15 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
       [data-slot='dialog-overlay'][data-state='closed'] { animation-duration: 800ms !important; }
     `;
     root.append(exitAnimationStyle);
-    const insideControl = await waitFor(() => {
+    const insideControl = await waitFor(async () => {
       const element = root.querySelector<HTMLButtonElement>('[data-testid="inside-control"]');
       if (!element) throw new Error('inside-island control not rendered');
       return element;
     });
-    expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
+    await expect(root.querySelector('[data-yv-shadow-local-overlay]')).toBeNull();
     insideControl.focus();
     await userEvent.click(insideControl);
-    const dialog = await waitFor(() => {
+    const dialog = await waitFor(async () => {
       const element = root.querySelector<HTMLElement>('[role="dialog"]');
       if (!element) throw new Error('sign-in dialog not rendered in the component shadow root');
       return element;
@@ -117,19 +119,19 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     const contentWrapper = root.querySelector<HTMLElement>('[data-yv-shadow-content-wrapper]');
     if (!topLayer || !contentWrapper) throw new Error('shadow modal coordination not rendered');
 
-    expect(dialog.getRootNode()).toBe(root);
-    expect(topLayer.getRootNode()).toBe(root);
-    expect(canvasElement.ownerDocument.body.querySelector('[role="dialog"]')).toBeNull();
-    await waitFor(() => expect(topLayer.matches(':popover-open')).toBe(true));
+    await expect(dialog.getRootNode()).toBe(root);
+    await expect(topLayer.getRootNode()).toBe(root);
+    await expect(canvasElement.ownerDocument.body.querySelector('[role="dialog"]')).toBeNull();
+    await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(true));
 
     const titleId = dialog.getAttribute('aria-labelledby');
     const descriptionId = dialog.getAttribute('aria-describedby');
-    expect(titleId).toBeTruthy();
-    expect(descriptionId).toBeTruthy();
+    await expect(titleId).toBeTruthy();
+    await expect(descriptionId).toBeTruthy();
     const title = root.getElementById(titleId!);
     const description = root.getElementById(descriptionId!);
-    expect(title).not.toBeNull();
-    expect(description).not.toBeNull();
+    await expect(title).not.toBeNull();
+    await expect(description).not.toBeNull();
     // SAFETY: These reflected-ARIA properties are still a draft; verify support before use.
     const reflectedDialog = dialog as HTMLElement & {
       ariaLabelledByElements?: readonly Element[];
@@ -138,12 +140,12 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     if (!reflectedDialog.ariaLabelledByElements || !reflectedDialog.ariaDescribedByElements) {
       throw new Error('browser did not expose the dialog ARIA element relationships');
     }
-    expect(reflectedDialog.ariaLabelledByElements).toEqual([title]);
-    expect(reflectedDialog.ariaDescribedByElements).toEqual([description]);
+    await expect(reflectedDialog.ariaLabelledByElements).toEqual([title]);
+    await expect(reflectedDialog.ariaDescribedByElements).toEqual([description]);
 
-    await waitFor(() => {
+    await waitFor(async () => {
       const focused = root.activeElement;
-      expect(focused !== null && dialog.contains(focused)).toBe(true);
+      await expect(focused !== null && dialog.contains(focused)).toBe(true);
     });
 
     const hiddenWrapper = canvasElement.ownerDocument.createElement('div');
@@ -156,7 +158,7 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     const dialogButtons = Array.from(
       dialog.querySelectorAll<HTMLButtonElement>('button[data-slot="button"]'),
     );
-    expect(dialogButtons).toHaveLength(2);
+    await expect(dialogButtons).toHaveLength(2);
     const [confirmButton, declineButton] = dialogButtons;
     if (!confirmButton || !declineButton) throw new Error('sign-in dialog actions not rendered');
 
@@ -176,24 +178,24 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
 
     confirmButton.focus();
     await userEvent.tab();
-    expect(root.activeElement).toBe(firstRadio);
+    await expect(root.activeElement).toBe(firstRadio);
     await userEvent.tab();
-    expect(root.activeElement).toBe(declineButton);
+    await expect(root.activeElement).toBe(declineButton);
     await userEvent.tab();
-    await waitFor(() => expect(root.activeElement).toBe(confirmButton));
+    await waitFor(async () => await expect(root.activeElement).toBe(confirmButton));
     await userEvent.tab({ shift: true });
-    await waitFor(() => expect(root.activeElement).toBe(declineButton));
-    expect(root.activeElement).not.toBe(negativeTabIndexButton);
-    expect(root.activeElement).not.toBe(secondRadio);
+    await waitFor(async () => await expect(root.activeElement).toBe(declineButton));
+    await expect(root.activeElement).not.toBe(negativeTabIndexButton);
+    await expect(root.activeElement).not.toBe(secondRadio);
 
-    expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
+    await expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
 
     await expectOutsideFocusRedirectedInto(root, outsideControl, dialog);
 
-    expect(insideControl.closest('[inert]')).not.toBeNull();
+    await expect(insideControl.closest('[inert]')).not.toBeNull();
 
     insideControl.focus();
-    expect(root.activeElement).not.toBe(insideControl);
+    await expect(root.activeElement).not.toBe(insideControl);
 
     const overlay = dialog.previousElementSibling;
     if (!(overlay instanceof HTMLElement)) throw new Error('dialog overlay not rendered');
@@ -202,23 +204,25 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     const clippingRect = clippingContainer.getBoundingClientRect();
     const viewport = canvasElement.ownerDocument.defaultView;
     if (!viewport) throw new Error('story window not available');
-    expect(overlayRect.width).toBeGreaterThanOrEqual(viewport.innerWidth - 1);
-    expect(overlayRect.height).toBeGreaterThanOrEqual(viewport.innerHeight - 1);
+    await expect(overlayRect.width).toBeGreaterThanOrEqual(viewport.innerWidth - 1);
+    await expect(overlayRect.height).toBeGreaterThanOrEqual(viewport.innerHeight - 1);
     const sampleX =
       clippingRect.right + 4 < viewport.innerWidth ? clippingRect.right + 4 : clippingRect.left - 4;
     const sampleY = Math.min(viewport.innerHeight - 4, Math.max(4, clippingRect.top + 4));
     const escapedHit = root.elementFromPoint(sampleX, sampleY);
-    expect(escapedHit === overlay || (escapedHit !== null && overlay.contains(escapedHit))).toBe(
-      true,
-    );
-    expect(dialogRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
+    await expect(
+      escapedHit === overlay || (escapedHit !== null && overlay.contains(escapedHit)),
+    ).toBe(true);
+    await expect(dialogRect.bottom).toBeGreaterThan(clippingRect.bottom + 1);
     const dialogSampleX = dialogRect.left + dialogRect.width / 2;
     const dialogSampleY = Math.max(dialogRect.top + 2, clippingRect.bottom + 2);
     if (dialogSampleY >= dialogRect.bottom) {
       throw new Error('dialog did not extend beyond its clipping ancestor');
     }
     const dialogHit = root.elementFromPoint(dialogSampleX, dialogSampleY);
-    expect(dialogHit === dialog || (dialogHit !== null && dialog.contains(dialogHit))).toBe(true);
+    await expect(dialogHit === dialog || (dialogHit !== null && dialog.contains(dialogHit))).toBe(
+      true,
+    );
 
     const dialogStyles = styleSnapshot(dialog);
     const overlayStyles = styleSnapshot(overlay);
@@ -236,39 +240,40 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     `;
     try {
       canvasElement.ownerDocument.head.append(hostileStyle);
-      await waitFor(() =>
-        expect(getComputedStyle(outsideControl).backgroundColor).toBe('rgb(185, 28, 28)'),
+      await waitFor(
+        async () =>
+          await expect(getComputedStyle(outsideControl).backgroundColor).toBe('rgb(185, 28, 28)'),
       );
-      expect(styleSnapshot(dialog)).toEqual(dialogStyles);
-      expect(styleSnapshot(overlay)).toEqual(overlayStyles);
+      await expect(styleSnapshot(dialog)).toEqual(dialogStyles);
+      await expect(styleSnapshot(overlay)).toEqual(overlayStyles);
     } finally {
       hostileStyle.remove();
     }
 
     await userEvent.keyboard('{Escape}');
-    await waitFor(() => {
-      void expect(dialog).toHaveAttribute('data-state', 'closed');
-      void expect(topLayer).toContainElement(dialog);
-      expect(contentWrapper.inert).toBe(true);
-      expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
-      expect(topLayer.matches(':popover-open')).toBe(true);
+    await waitFor(async () => {
+      await expect(dialog).toHaveAttribute('data-state', 'closed');
+      await expect(topLayer).toContainElement(dialog);
+      await expect(contentWrapper.inert).toBe(true);
+      await expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
+      await expect(topLayer.matches(':popover-open')).toBe(true);
     });
     await expectOutsideFocusRedirectedInto(root, outsideControl, dialog);
-    await waitFor(() => {
-      expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
-      expect(topLayer.querySelector('[data-slot="dialog-overlay"]')).not.toBeNull();
-      expect(contentWrapper.inert).toBe(true);
-      expect(root.activeElement).toBe(overlay);
+    await waitFor(async () => {
+      await expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
+      await expect(topLayer.querySelector('[data-slot="dialog-overlay"]')).not.toBeNull();
+      await expect(contentWrapper.inert).toBe(true);
+      await expect(root.activeElement).toBe(overlay);
     });
-    await waitFor(() => {
-      expect(topLayer.childElementCount).toBe(0);
-      expect(topLayer.matches(':popover-open')).toBe(false);
-      expect(contentWrapper.inert).toBe(false);
-      expect(root.activeElement).toBe(insideControl);
+    await waitFor(async () => {
+      await expect(topLayer.childElementCount).toBe(0);
+      await expect(topLayer.matches(':popover-open')).toBe(false);
+      await expect(contentWrapper.inert).toBe(false);
+      await expect(root.activeElement).toBe(insideControl);
     });
 
     await userEvent.click(outsideControl);
-    const reopenedDialog = await waitFor(() => {
+    const reopenedDialog = await waitFor(async () => {
       const element = root.querySelector<HTMLElement>('[role="dialog"]');
       if (!element) throw new Error('dialog did not reopen');
       return element;
@@ -278,30 +283,32 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
       throw new Error('reopened dialog overlay not rendered');
     }
     await userEvent.click(reopenedOverlay);
-    await waitFor(() => {
-      void expect(reopenedDialog).toHaveAttribute('data-state', 'closed');
-      expect(contentWrapper.inert).toBe(true);
-      expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
-      expect(topLayer.matches(':popover-open')).toBe(true);
+    await waitFor(async () => {
+      await expect(reopenedDialog).toHaveAttribute('data-state', 'closed');
+      await expect(contentWrapper.inert).toBe(true);
+      await expect(getComputedStyle(outsideControl).pointerEvents).toBe('none');
+      await expect(topLayer.matches(':popover-open')).toBe(true);
     });
     await expectOutsideFocusRedirectedInto(root, outsideControl, reopenedDialog);
-    await waitFor(() => {
-      expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
-      expect(topLayer.querySelector('[data-slot="dialog-overlay"]')).not.toBeNull();
-      expect(contentWrapper.inert).toBe(true);
-      expect(root.activeElement).toBe(reopenedOverlay);
+    await waitFor(async () => {
+      await expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
+      await expect(topLayer.querySelector('[data-slot="dialog-overlay"]')).not.toBeNull();
+      await expect(contentWrapper.inert).toBe(true);
+      await expect(root.activeElement).toBe(reopenedOverlay);
     });
     outsideControl.focus();
-    await waitFor(() => {
-      expect(canvasElement.ownerDocument.activeElement).not.toBe(outsideControl);
-      expect(root.activeElement).toBe(reopenedOverlay);
+    await waitFor(async () => {
+      await expect(canvasElement.ownerDocument.activeElement).not.toBe(outsideControl);
+      await expect(root.activeElement).toBe(reopenedOverlay);
     });
-    await waitFor(() => {
-      expect(topLayer.childElementCount).toBe(0);
-      expect(topLayer.matches(':popover-open')).toBe(false);
-      expect(contentWrapper.inert).toBe(false);
-      expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
+    await waitFor(async () => {
+      await expect(topLayer.childElementCount).toBe(0);
+      await expect(topLayer.matches(':popover-open')).toBe(false);
+      await expect(contentWrapper.inert).toBe(false);
+      await expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
     });
     exitAnimationStyle.remove();
   },
 };
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
diff --git a/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx b/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
index a4bcee9b..527ffbb1 100644
--- a/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
@@ -1,4 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
+
 import { http, HttpResponse } from 'msw';
 import { useRef, useState } from 'react';
 import { userEvent, waitFor, within } from 'storybook/test';
@@ -144,9 +146,9 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 async function waitForClosed(topLayer: HTMLElement): Promise<void> {
-  await waitFor(() => {
-    expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
-    expect(topLayer.matches(':popover-open')).toBe(false);
+  await waitFor(async () => {
+    await expect(topLayer.querySelector('[role="dialog"]')).toBeNull();
+    await expect(topLayer.matches(':popover-open')).toBe(false);
   });
 }
 
@@ -205,19 +207,19 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
       'verse action popover not rendered',
     );
 
-    await waitFor(() => expect(topLayer.matches(':popover-open')).toBe(true));
-    expect(topLayer.getRootNode()).toBe(shadowRoot);
-    expect(dialog.getRootNode()).toBe(shadowRoot);
-    expect(canvasElement.ownerDocument.body.querySelector('[role="dialog"]')).toBeNull();
-    void expect(dialog).toHaveAccessibleName(/.+/);
-    void expect(dialog.querySelector('[role="group"]')).toHaveAccessibleName(/.+/);
-    await waitFor(() => expect(shadowRoot.activeElement).toBe(dialog));
+    await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(true));
+    await expect(topLayer.getRootNode()).toBe(shadowRoot);
+    await expect(dialog.getRootNode()).toBe(shadowRoot);
+    await expect(canvasElement.ownerDocument.body.querySelector('[role="dialog"]')).toBeNull();
+    await expect(dialog).toHaveAccessibleName(/.+/);
+    await expect(dialog.querySelector('[role="group"]')).toHaveAccessibleName(/.+/);
+    await waitFor(async () => await expect(shadowRoot.activeElement).toBe(dialog));
 
     const clippingRect = clippingContainer.getBoundingClientRect();
     const firstDialogRect = dialog.getBoundingClientRect();
     const escapesAbove = firstDialogRect.top < clippingRect.top - 1;
     const escapesBelow = firstDialogRect.bottom > clippingRect.bottom + 1;
-    expect(escapesAbove || escapesBelow).toBe(true);
+    await expect(escapesAbove || escapesBelow).toBe(true);
     const sampleX = firstDialogRect.left + firstDialogRect.width / 2;
     const sampleY = escapesBelow
       ? Math.max(firstDialogRect.top + 2, clippingRect.bottom + 2)
@@ -225,44 +227,44 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
     if (sampleY <= firstDialogRect.top || sampleY >= firstDialogRect.bottom)
       throw new Error('popover did not escape clipping bounds');
     const hit = shadowRoot.elementFromPoint(sampleX, sampleY);
-    expect(hit === dialog || (hit !== null && dialog.contains(hit))).toBe(true);
+    await expect(hit === dialog || (hit !== null && dialog.contains(hit))).toBe(true);
 
     readerScrollRoot.scrollTop = readerScrollRoot.scrollHeight;
-    await waitFor(() => {
+    await waitFor(async () => {
       const readerRect = readerScrollRoot.getBoundingClientRect();
       const dockedRect = dialog.getBoundingClientRect();
-      expect(Math.abs(dockedRect.top - (readerRect.top + 24))).toBeLessThan(12);
-      expect(
+      await expect(Math.abs(dockedRect.top - (readerRect.top + 24))).toBeLessThan(12);
+      await expect(
         Math.abs(dockedRect.left + dockedRect.width / 2 - (readerRect.left + readerRect.width / 2)),
       ).toBeLessThan(2);
     });
     readerScrollRoot.scrollTop = 0;
-    await waitFor(() => {
+    await waitFor(async () => {
       const returnedRect = dialog.getBoundingClientRect();
-      expect(Math.abs(returnedRect.left - firstDialogRect.left)).toBeLessThan(12);
-      expect(Math.abs(returnedRect.top - firstDialogRect.top)).toBeLessThan(12);
+      await expect(Math.abs(returnedRect.left - firstDialogRect.left)).toBeLessThan(12);
+      await expect(Math.abs(returnedRect.top - firstDialogRect.top)).toBeLessThan(12);
     });
 
     await userEvent.click(secondVerse);
-    await waitFor(() => {
+    await waitFor(async () => {
       const nextRect = dialog.getBoundingClientRect();
-      expect(nextRect.left).toBeGreaterThan(firstDialogRect.left + 20);
+      await expect(nextRect.left).toBeGreaterThan(firstDialogRect.left + 20);
     });
-    expect(
+    await expect(
       shadowRoot.querySelector('[data-testid="close-requests"]')?.getAttribute('data-count'),
     ).toBe('0');
-    void expect(topLayer).toContainElement(dialog);
+    await expect(topLayer).toContainElement(dialog);
 
     await userEvent.keyboard('{Escape}');
     await waitForClosed(topLayer);
-    expect(shadowRoot.activeElement).toBe(priorControl);
+    await expect(shadowRoot.activeElement).toBe(priorControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
     dialog = await waitForElement(topLayer, '[role="dialog"]', 'popover did not reopen');
     await userEvent.click(getCopyButton(dialog));
     await waitForClosed(topLayer);
-    expect(shadowRoot.activeElement).toBe(priorControl);
+    await expect(shadowRoot.activeElement).toBe(priorControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
@@ -277,30 +279,31 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
     if (!closeRequestOutput) throw new Error('close request output missing');
     const closeRequestsBeforeRejection = Number(closeRequestOutput.getAttribute('data-count'));
     await userEvent.click(rejectedOutsideControl);
-    await waitFor(() =>
-      expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
-        closeRequestsBeforeRejection + 1,
-      ),
+    await waitFor(
+      async () =>
+        await expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
+          closeRequestsBeforeRejection + 1,
+        ),
     );
-    void expect(topLayer).toContainElement(dialog);
-    expect(canvasElement.ownerDocument.activeElement).toBe(rejectedOutsideControl);
+    await expect(topLayer).toContainElement(dialog);
+    await expect(canvasElement.ownerDocument.activeElement).toBe(rejectedOutsideControl);
     await userEvent.click(getCopyButton(dialog));
     await waitForClosed(topLayer);
-    expect(shadowRoot.activeElement).toBe(priorControl);
+    await expect(shadowRoot.activeElement).toBe(priorControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
     await waitForElement(topLayer, '[role="dialog"]', 'popover did not reopen for delayed close');
     await userEvent.click(delayedOutsideControl);
     await waitForClosed(topLayer);
-    expect(canvasElement.ownerDocument.activeElement).toBe(delayedOutsideControl);
+    await expect(canvasElement.ownerDocument.activeElement).toBe(delayedOutsideControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
     await waitForElement(topLayer, '[role="dialog"]', 'popover did not reopen for outside click');
     await userEvent.click(outsideControl);
     await waitForClosed(topLayer);
-    expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
+    await expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
 
     const closeRequestsBeforeTouch = Number(closeRequestOutput.getAttribute('data-count'));
     const touchUser = userEvent.setup({ document: canvasElement.ownerDocument });
@@ -308,20 +311,24 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
     dialog = await waitForElement(topLayer, '[role="dialog"]', 'popover did not open for touch');
     const touchDialogRect = dialog.getBoundingClientRect();
     await touchUser.pointer({ keys: '[TouchA]', target: secondVerse });
-    void expect(firstVerse).toHaveClass('yv-v-selected');
-    void expect(secondVerse).toHaveClass('yv-v-selected');
-    void expect(dialog).toHaveAttribute('data-state', 'open');
-    expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(closeRequestsBeforeTouch);
-    await waitFor(() => {
-      expect(dialog.getBoundingClientRect().left).toBeGreaterThan(touchDialogRect.left + 20);
+    await expect(firstVerse).toHaveClass('yv-v-selected');
+    await expect(secondVerse).toHaveClass('yv-v-selected');
+    await expect(dialog).toHaveAttribute('data-state', 'open');
+    await expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
+      closeRequestsBeforeTouch,
+    );
+    await waitFor(async () => {
+      await expect(dialog.getBoundingClientRect().left).toBeGreaterThan(touchDialogRect.left + 20);
     });
     await touchUser.pointer({ keys: '[TouchA>]', target: outsideControl });
-    void expect(dialog).toHaveAttribute('data-state', 'open');
+    await expect(dialog).toHaveAttribute('data-state', 'open');
     await touchUser.pointer({ keys: '[/TouchA]', target: outsideControl });
     await waitForClosed(topLayer);
-    expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
+    await expect(Number(closeRequestOutput.getAttribute('data-count'))).toBe(
       closeRequestsBeforeTouch + 1,
     );
-    expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
+    await expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
   },
 };
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
+/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */

From 2dce28673c0ccd3498667c11d50a4e61f9a49048 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 14:40:50 -0500
Subject: [PATCH 08/21] test(ui): stabilize shadow browser timing

---
 ...ersion-picker.shadow-isolation.stories.tsx |  2 +-
 ...adow-root-host-realistic-usage.stories.tsx | 41 ++++++++++++++-----
 2 files changed, 32 insertions(+), 11 deletions(-)

diff --git a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
index 6bae9d53..42aecbe1 100644
--- a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
@@ -413,7 +413,6 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
     if (!wrapper || !heading || !inputGroup) throw new Error('picker landmarks not rendered');
 
     const triggerGeometry = geometrySnapshot(trigger);
-    const panelGeometry = geometrySnapshot(panel);
     const inputGeometry = geometrySnapshot(inputGroup);
     const headingTypography = typographySnapshot(heading, ownerWindow);
     await expect(headingTypography.fontFamily).toContain('Inter');
@@ -436,6 +435,7 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
     }
     const languageTabsInlineSize = languageTabs.offsetWidth;
     const languageInputRadius = ownerWindow.getComputedStyle(languageInputGroup).borderRadius;
+    const panelGeometry = geometrySnapshot(panel);
     await expect(languageTabsInlineSize).toBe(languageTabsContainer.clientWidth - 32);
     await expect(languageInputRadius).toBe('30px');
 
diff --git a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
index 98305e51..4e8d4598 100644
--- a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
+++ b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
@@ -325,13 +325,36 @@ async function exerciseLifecycle(
   if (!toggle) throw new Error('lifecycle toggle not rendered');
   const consoleError = spyOn(console, 'error').mockImplementation(() => undefined);
 
+  const waitForMountedDom = async (): Promise<MountedFixture> =>
+    waitFor(() => {
+      const hosts = Array.from(
+        canvasElement.ownerDocument.querySelectorAll<HTMLElement>('[data-yv-shadow-host]'),
+      );
+      if (hosts.length !== EXPECTED_COMPONENT_IDS.length) {
+        throw new Error('realistic component mix is still mounting');
+      }
+
+      const roots = hosts.map((host) => host.shadowRoot);
+      if (roots.some((root) => !root)) throw new Error('shadow roots are still mounting');
+      const componentIds = roots.map(
+        (root) =>
+          root?.querySelector<HTMLElement>('[data-realistic-component]')?.dataset
+            .realisticComponent,
+      );
+      if (componentIds.some((id, index) => id !== EXPECTED_COMPONENT_IDS[index])) {
+        throw new Error('realistic component mix is still mounting');
+      }
+
+      const sheet = roots[0]?.adoptedStyleSheets[0];
+      if (!sheet) throw new Error('shared SDK stylesheet is still mounting');
+      return { hosts, sheet };
+    });
+
   try {
     await userEvent.click(toggle);
-    const firstMount = await waitFor(async () => {
-      const fixture = await requireMountedFixture(canvasElement);
-      await requireEffectCounts(canvasElement, expectedEffectCounts.firstMount);
-      return fixture;
-    });
+    const firstMount = await waitForMountedDom();
+    await requireMountedFixture(canvasElement);
+    await requireEffectCounts(canvasElement, expectedEffectCounts.firstMount);
 
     await userEvent.click(toggle);
     await expect(canvasElement.querySelectorAll('[data-yv-shadow-host]')).toHaveLength(0);
@@ -339,11 +362,9 @@ async function exerciseLifecycle(
     await requireEffectCounts(canvasElement, expectedEffectCounts.removal);
 
     await userEvent.click(toggle);
-    const secondMount = await waitFor(async () => {
-      const fixture = await requireMountedFixture(canvasElement);
-      await requireEffectCounts(canvasElement, expectedEffectCounts.secondMount);
-      return fixture;
-    });
+    const secondMount = await waitForMountedDom();
+    await requireMountedFixture(canvasElement);
+    await requireEffectCounts(canvasElement, expectedEffectCounts.secondMount);
     for (const host of secondMount.hosts) {
       await expect(host.shadowRoot?.adoptedStyleSheets[0]).toBe(firstMount.sheet);
     }

From 4cb81b2c86a340a013d29a383c5530d610dce11e Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 14:56:49 -0500
Subject: [PATCH 09/21] test(ui): consume shadow story wait promises

---
 ...ionAuthButton.shadow-isolation.stories.tsx |  3 +--
 ...ersion-picker.shadow-isolation.stories.tsx | 11 +++++-----
 ...compatibility.shadow-isolation.stories.tsx |  4 ++--
 ...oduction-seam.shadow-isolation.stories.tsx |  8 +++----
 ...adow-root-host-realistic-usage.stories.tsx |  3 ++-
 ...ign-in-dialog.shadow-isolation.stories.tsx |  4 ++--
 ...ction-popover.shadow-isolation.stories.tsx | 14 ++++++++-----
 packages/ui/src/test/storybook-dom.ts         | 21 ++++++++++++++++++-
 8 files changed, 45 insertions(+), 23 deletions(-)

diff --git a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
index e0034e03..4390db02 100644
--- a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
@@ -3,10 +3,9 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { http, HttpResponse } from 'msw';
 import { createRoot, type Root } from 'react-dom/client';
-import { waitFor } from 'storybook/test';
 import { expect } from 'vitest';
 import { ShadowRootHost } from '../lib/shadow-root-host';
-import { waitForElement } from '../test/storybook-dom';
+import { waitFor, waitForElement } from '../test/storybook-dom';
 import { YouVersionAuthButton } from './YouVersionAuthButton';
 
 /**
diff --git a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
index 42aecbe1..a55916a2 100644
--- a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
@@ -5,11 +5,11 @@ import { YouVersionProvider as HooksYouVersionProvider } from '@youversion/platf
 import { http, HttpResponse } from 'msw';
 import { useEffect, useState } from 'react';
 import { createPortal } from 'react-dom';
-import { userEvent, waitFor, within } from 'storybook/test';
+import { userEvent, within } from 'storybook/test';
 import { expect } from 'vitest';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { globalHandlers } from '../test/mocks/handlers';
-import { waitForElement, waitForShadowRoot } from '../test/storybook-dom';
+import { waitFor, waitForElement, waitForShadowRoot } from '../test/storybook-dom';
 import { BibleVersionPicker } from './bible-version-picker';
 
 type PortalStrategy = 'local-inline' | 'local-top-layer';
@@ -641,14 +641,13 @@ export const PanelTracksAncestorScrollAndVersionListScrollsInternally: Story = {
 
     await waitFor(async () => {
       const triggerRectAfter = trigger.getBoundingClientRect();
+      const panelRectAfter = panel.getBoundingClientRect();
       await expect(
         Math.abs(triggerRectAfter.top - (triggerRectBefore.top - scrollDelta)),
       ).toBeLessThan(2);
+      const offsetAfter = panelRectAfter.top - triggerRectAfter.bottom;
+      await expect(Math.abs(offsetAfter - offsetBefore)).toBeLessThanOrEqual(8);
     });
-    const triggerRectAfter = trigger.getBoundingClientRect();
-    const panelRectAfter = panel.getBoundingClientRect();
-    const offsetAfter = panelRectAfter.top - triggerRectAfter.bottom;
-    await expect(Math.abs(offsetAfter - offsetBefore)).toBeLessThanOrEqual(8);
 
     // Part 2: the version list scrolls internally within the panel. Locate
     // the scroll region via the unconditional "All Versions" marker's
diff --git a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
index f3eef8eb..6e27630c 100644
--- a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
@@ -4,10 +4,10 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useTheme } from '@youversion/platform-react-hooks';
 import { http, HttpResponse } from 'msw';
 import { useCallback, useLayoutEffect, useRef, useState } from 'react';
-import { userEvent, waitFor } from 'storybook/test';
+import { userEvent } from 'storybook/test';
 import { expect } from 'vitest';
 import { ShadowRootHost } from '../lib/shadow-root-host';
-import { waitForElement } from '../test/storybook-dom';
+import { waitFor, waitForElement } from '../test/storybook-dom';
 import { Textarea } from './ui/textarea';
 import { YouVersionAuthButton } from './YouVersionAuthButton';
 
diff --git a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
index 48a4249f..4fea5c14 100644
--- a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
@@ -3,10 +3,10 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { http, HttpResponse } from 'msw';
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { spyOn, userEvent, waitFor } from 'storybook/test';
+import { spyOn, userEvent } from 'storybook/test';
 import { expect } from 'vitest';
 import { ShadowRootHost } from '../lib/shadow-root-host';
-import { waitForElement, waitForShadowRoot } from '../test/storybook-dom';
+import { waitFor, waitForElement, waitForShadowRoot } from '../test/storybook-dom';
 import { HighlightPermissionDialog } from './highlight-permission-dialog';
 import { Dialog, DialogContent, DialogTitle } from './ui/dialog';
 import { Popover, PopoverContent, PopoverTrigger } from './ui/popover';
@@ -618,7 +618,7 @@ export const DialogContainsPopoverEvidence: Story = {
       await userEvent.keyboard('{Escape}');
       await waitFor(async () => await expect(notesPopover.isConnected).toBe(false));
       await expect(topLayer).toContainElement(notesDialog);
-      await expect(root.activeElement).toBe(notesTrigger);
+      await waitFor(async () => await expect(root.activeElement).toBe(notesTrigger));
       await expect(contentWrapper.inert).toBe(true);
     });
 
@@ -627,7 +627,7 @@ export const DialogContainsPopoverEvidence: Story = {
       await waitFor(async () => await expect(notesDialog.isConnected).toBe(false));
       await waitFor(async () => await expect(contentWrapper.inert).toBe(false));
       await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(false));
-      await expect(root.activeElement).toBe(openNotes);
+      await waitFor(async () => await expect(root.activeElement).toBe(openNotes));
     });
   },
 };
diff --git a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
index 4e8d4598..c697b937 100644
--- a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
+++ b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
@@ -5,7 +5,7 @@ import type { BibleBook, BibleVersion } from '@youversion/platform-core';
 import { YouVersionContext, type HookOverrides } from '@youversion/platform-react-hooks';
 import { http, HttpResponse } from 'msw';
 import { StrictMode, useCallback, useContext, useEffect, useState, type ReactNode } from 'react';
-import { spyOn, userEvent, waitFor } from 'storybook/test';
+import { spyOn, userEvent } from 'storybook/test';
 import { expect } from 'vitest';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { BibleCard } from './bible-card';
@@ -14,6 +14,7 @@ import { ProfileAvatar } from './profile-avatar';
 import { Separator } from './ui/separator';
 import { Textarea } from './ui/textarea';
 import { VerseOfTheDay } from './verse-of-the-day';
+import { waitFor } from '../test/storybook-dom';
 
 const EXPECTED_COMPONENT_IDS = [
   'reader',
diff --git a/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx b/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
index 44204318..69db85dd 100644
--- a/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
@@ -3,10 +3,10 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { http, HttpResponse } from 'msw';
 import { useState } from 'react';
-import { userEvent, waitFor } from 'storybook/test';
+import { userEvent } from 'storybook/test';
 import { expect } from 'vitest';
 import { ShadowRootHost } from '../lib/shadow-root-host';
-import { waitForShadowRoot } from '../test/storybook-dom';
+import { waitFor, waitForShadowRoot } from '../test/storybook-dom';
 import { SignInDialog } from './sign-in-dialog';
 
 function SignInDialogHarness(): React.ReactNode {
diff --git a/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx b/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
index 527ffbb1..04fed00d 100644
--- a/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
@@ -3,11 +3,11 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 
 import { http, HttpResponse } from 'msw';
 import { useRef, useState } from 'react';
-import { userEvent, waitFor, within } from 'storybook/test';
+import { userEvent, within } from 'storybook/test';
 import { expect } from 'vitest';
 import i18n from '../i18n';
 import { ShadowRootHost } from '../lib/shadow-root-host';
-import { waitForElement, waitForShadowRoot } from '../test/storybook-dom';
+import { waitFor, waitForElement, waitForShadowRoot } from '../test/storybook-dom';
 import { VerseActionPopover } from './verse-action-popover';
 
 function IsolatedVerseActionPopover(): React.ReactNode {
@@ -152,6 +152,10 @@ async function waitForClosed(topLayer: HTMLElement): Promise<void> {
   });
 }
 
+async function waitForFocus(shadowRoot: ShadowRoot, element: HTMLElement): Promise<void> {
+  await waitFor(async () => await expect(shadowRoot.activeElement).toBe(element));
+}
+
 function getCopyButton(dialog: HTMLElement): HTMLButtonElement {
   return within(dialog).getByRole('button', { name: i18n.t('copy') });
 }
@@ -257,14 +261,14 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
 
     await userEvent.keyboard('{Escape}');
     await waitForClosed(topLayer);
-    await expect(shadowRoot.activeElement).toBe(priorControl);
+    await waitForFocus(shadowRoot, priorControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
     dialog = await waitForElement(topLayer, '[role="dialog"]', 'popover did not reopen');
     await userEvent.click(getCopyButton(dialog));
     await waitForClosed(topLayer);
-    await expect(shadowRoot.activeElement).toBe(priorControl);
+    await waitForFocus(shadowRoot, priorControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
@@ -289,7 +293,7 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
     await expect(canvasElement.ownerDocument.activeElement).toBe(rejectedOutsideControl);
     await userEvent.click(getCopyButton(dialog));
     await waitForClosed(topLayer);
-    await expect(shadowRoot.activeElement).toBe(priorControl);
+    await waitForFocus(shadowRoot, priorControl);
 
     priorControl.focus();
     await userEvent.click(firstVerse);
diff --git a/packages/ui/src/test/storybook-dom.ts b/packages/ui/src/test/storybook-dom.ts
index 23c32bc2..3c912759 100644
--- a/packages/ui/src/test/storybook-dom.ts
+++ b/packages/ui/src/test/storybook-dom.ts
@@ -1,10 +1,29 @@
-import { waitFor } from 'storybook/test';
 import { requireShadowRoot } from './dom-stubs';
 
 interface StorybookWaitOptions {
   timeout?: number;
 }
 
+export async function waitFor<T>(
+  callback: () => T | Promise<T>,
+  options: StorybookWaitOptions = {},
+): Promise<T> {
+  const timeout = options.timeout ?? 5000;
+  const deadline = Date.now() + timeout;
+  let lastError: unknown;
+
+  while (Date.now() <= deadline) {
+    try {
+      return await callback();
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+
+  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+
 export async function waitForElement<ElementType extends Element>(
   container: ParentNode,
   selector: string,

From 5f574ed1316eca2edbc99cb55f2d80f5045dc44b Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 15:04:51 -0500
Subject: [PATCH 10/21] test(ui): avoid matcher promises in shadow stories

---
 ...compatibility.shadow-isolation.stories.tsx | 56 +++++++++----------
 ...adow-root-host-realistic-usage.stories.tsx | 44 ++++++---------
 2 files changed, 46 insertions(+), 54 deletions(-)

diff --git a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
index 6e27630c..63a9a931 100644
--- a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
@@ -190,13 +190,13 @@ export const FormsAndExternalRelationshipsStopAtTheTreeScope: Story = {
       'isolated textarea not rendered',
     );
 
-    await expect(textarea.form).toBeNull();
-    await expect(form.elements.namedItem('notes')).toBeNull();
-    await expect(new FormData(form).has('notes')).toBe(false);
+    expect(textarea.form).toBeNull();
+    expect(form.elements.namedItem('notes')).toBeNull();
+    expect(new FormData(form).has('notes')).toBe(false);
 
-    await expect(label.control).toBeNull();
+    expect(label.control).toBeNull();
     await userEvent.click(label);
-    await expect(root.activeElement).not.toBe(textarea);
+    expect(root.activeElement).not.toBe(textarea);
 
     type ReflectedAriaElement = HTMLElement & {
       ariaLabelledByElements?: readonly Element[];
@@ -211,10 +211,10 @@ export const FormsAndExternalRelationshipsStopAtTheTreeScope: Story = {
       throw new Error('browser did not expose ariaDescribedByElements');
     }
 
-    await expect(textarea.getAttribute('aria-labelledby')).toBe('external-name');
-    await expect(textarea.getAttribute('aria-describedby')).toBe('external-description');
-    await expect(reflectedTextarea.ariaLabelledByElements).toEqual([]);
-    await expect(reflectedTextarea.ariaDescribedByElements).toEqual([]);
+    expect(textarea.getAttribute('aria-labelledby')).toBe('external-name');
+    expect(textarea.getAttribute('aria-describedby')).toBe('external-description');
+    expect(reflectedTextarea.ariaLabelledByElements).toEqual([]);
+    expect(reflectedTextarea.ariaDescribedByElements).toEqual([]);
   },
 };
 
@@ -296,8 +296,8 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
       'isolated auth button not rendered',
     );
 
-    await expect(canvasElement.querySelector('[data-testid="isolated-auth-button"]')).toBeNull();
-    await expect(root.querySelector('[data-testid="isolated-auth-button"]')).toBe(button);
+    expect(canvasElement.querySelector('[data-testid="isolated-auth-button"]')).toBeNull();
+    expect(root.querySelector('[data-testid="isolated-auth-button"]')).toBe(button);
     const firstLayoutEvidence = requireElement<HTMLOutputElement>(
       canvasElement,
       '[data-testid="first-layout-ref-state"]',
@@ -319,9 +319,9 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
       'consumer current target evidence not rendered',
     );
 
-    await expect(firstLayoutEvidence).toHaveTextContent('null');
-    await expect(firstLayoutEvidence).toHaveAttribute('hidden');
-    await waitFor(async () => await expect(forwardedRefEvidence.observedNode).toBe(button));
+    expect(firstLayoutEvidence).toHaveTextContent('null');
+    expect(firstLayoutEvidence).toHaveAttribute('hidden');
+    await waitFor(() => expect(forwardedRefEvidence.observedNode).toBe(button));
 
     const clickTarget = requireElement<HTMLDivElement>(
       button,
@@ -341,12 +341,12 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
 
     await userEvent.click(clickTarget);
 
-    await expect(outsideTarget).toBe(host);
-    await expect(outsidePath[0]).toBe(clickTarget);
-    await expect(outsidePath).toContain(button);
-    await expect(outsidePath).toContain(host);
-    await expect(consumerTargetEvidence.observedNode).toBe(clickTarget);
-    await expect(consumerCurrentTargetEvidence.observedNode).toBe(button);
+    expect(outsideTarget).toBe(host);
+    expect(outsidePath[0]).toBe(clickTarget);
+    expect(outsidePath).toContain(button);
+    expect(outsidePath).toContain(host);
+    expect(consumerTargetEvidence.observedNode).toBe(clickTarget);
+    expect(consumerCurrentTargetEvidence.observedNode).toBe(button);
   },
 };
 
@@ -386,9 +386,9 @@ export const NestedRootsRequireTraversalAndRetargetAtEveryBoundary: Story = {
       'nested auth button not rendered',
     );
 
-    await expect(canvasElement.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
-    await expect(outerRoot.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
-    await expect(innerRoot.querySelector('[data-testid="nested-auth-button"]')).toBe(button);
+    expect(canvasElement.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
+    expect(outerRoot.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
+    expect(innerRoot.querySelector('[data-testid="nested-auth-button"]')).toBe(button);
 
     let outerScopeTarget: EventTarget | null = null;
     let documentScopeTarget: EventTarget | null = null;
@@ -411,11 +411,11 @@ export const NestedRootsRequireTraversalAndRetargetAtEveryBoundary: Story = {
 
     await userEvent.click(button);
 
-    await expect(outerScopeTarget).toBe(innerHost);
-    await expect(documentScopeTarget).toBe(outerHost);
-    await expect(composedPath[0]).toBe(button);
-    await expect(composedPath).toContain(innerHost);
-    await expect(composedPath).toContain(outerHost);
+    expect(outerScopeTarget).toBe(innerHost);
+    expect(documentScopeTarget).toBe(outerHost);
+    expect(composedPath[0]).toBe(button);
+    expect(composedPath).toContain(innerHost);
+    expect(composedPath).toContain(outerHost);
   },
 };
 /* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
diff --git a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
index c697b937..10d67f17 100644
--- a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
+++ b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
@@ -229,7 +229,7 @@ async function requireMountedFixture(canvasElement: HTMLElement): Promise<Mounte
   const hosts = Array.from(
     canvasElement.ownerDocument.querySelectorAll<HTMLElement>('[data-yv-shadow-host]'),
   );
-  await expect(hosts).toHaveLength(EXPECTED_COMPONENT_IDS.length);
+  expect(hosts).toHaveLength(EXPECTED_COMPONENT_IDS.length);
 
   const roots = hosts.map((host) => {
     if (!host.shadowRoot) throw new Error('shadow root not attached');
@@ -239,7 +239,7 @@ async function requireMountedFixture(canvasElement: HTMLElement): Promise<Mounte
     (root) =>
       root.querySelector<HTMLElement>('[data-realistic-component]')?.dataset.realisticComponent,
   );
-  await expect(componentIds).toEqual(EXPECTED_COMPONENT_IDS);
+  expect(componentIds).toEqual(EXPECTED_COMPONENT_IDS);
 
   const components = new Map(
     roots.map((root, index) => [
@@ -255,35 +255,27 @@ async function requireMountedFixture(canvasElement: HTMLElement): Promise<Mounte
     ['votd-large', 'JHN.3.16'],
   ]);
   for (const [id, usfm] of expectedPassages) {
-    await expect(components.get(id)).toHaveTextContent(`Fixture scripture content for ${usfm}.`);
+    expect(components.get(id)).toHaveTextContent(`Fixture scripture content for ${usfm}.`);
   }
-  await expect(
+  expect(
     components.get('avatar-primary')?.querySelector('[aria-label="SDK Reader"]'),
   ).not.toBeNull();
-  await expect(
+  expect(
     components.get('avatar-secondary')?.querySelector('[aria-label="Bible Partner"]'),
   ).not.toBeNull();
-  await expect(components.get('notes-primary')?.querySelector('textarea')).toHaveValue(
-    'Primary notes',
-  );
-  await expect(components.get('notes-secondary')?.querySelector('textarea')).toHaveValue(
+  expect(components.get('notes-primary')?.querySelector('textarea')).toHaveValue('Primary notes');
+  expect(components.get('notes-secondary')?.querySelector('textarea')).toHaveValue(
     'Secondary notes',
   );
-  await expect(components.get('notes-tertiary')?.querySelector('textarea')).toHaveValue(
-    'Tertiary notes',
-  );
-  await expect(
-    components.get('separator-primary')?.querySelector('[role="separator"]'),
-  ).not.toBeNull();
-  await expect(
-    components.get('separator-secondary')?.querySelector('[role="separator"]'),
-  ).not.toBeNull();
+  expect(components.get('notes-tertiary')?.querySelector('textarea')).toHaveValue('Tertiary notes');
+  expect(components.get('separator-primary')?.querySelector('[role="separator"]')).not.toBeNull();
+  expect(components.get('separator-secondary')?.querySelector('[role="separator"]')).not.toBeNull();
 
   const sheet = roots[0]?.adoptedStyleSheets[0];
   if (!sheet) throw new Error('shared SDK stylesheet not adopted');
   for (const root of roots) {
-    await expect(root.adoptedStyleSheets).toHaveLength(1);
-    await expect(root.adoptedStyleSheets[0]).toBe(sheet);
+    expect(root.adoptedStyleSheets).toHaveLength(1);
+    expect(root.adoptedStyleSheets[0]).toBe(sheet);
   }
 
   return { hosts, sheet };
@@ -314,8 +306,8 @@ async function requireEffectCounts(
   [setup, cleanup]: [setup: number, cleanup: number],
 ): Promise<void> {
   const counts = canvasElement.querySelector('[data-testid="effect-lifecycle-counts"]');
-  await expect(counts).toHaveAttribute('data-effect-setup', String(setup));
-  await expect(counts).toHaveAttribute('data-effect-cleanup', String(cleanup));
+  expect(counts).toHaveAttribute('data-effect-setup', String(setup));
+  expect(counts).toHaveAttribute('data-effect-cleanup', String(cleanup));
 }
 
 async function exerciseLifecycle(
@@ -358,8 +350,8 @@ async function exerciseLifecycle(
     await requireEffectCounts(canvasElement, expectedEffectCounts.firstMount);
 
     await userEvent.click(toggle);
-    await expect(canvasElement.querySelectorAll('[data-yv-shadow-host]')).toHaveLength(0);
-    await expect(canvasElement.querySelector('[data-testid="realistic-component-mix"]')).toBeNull();
+    expect(canvasElement.querySelectorAll('[data-yv-shadow-host]')).toHaveLength(0);
+    expect(canvasElement.querySelector('[data-testid="realistic-component-mix"]')).toBeNull();
     await requireEffectCounts(canvasElement, expectedEffectCounts.removal);
 
     await userEvent.click(toggle);
@@ -367,9 +359,9 @@ async function exerciseLifecycle(
     await requireMountedFixture(canvasElement);
     await requireEffectCounts(canvasElement, expectedEffectCounts.secondMount);
     for (const host of secondMount.hosts) {
-      await expect(host.shadowRoot?.adoptedStyleSheets[0]).toBe(firstMount.sheet);
+      expect(host.shadowRoot?.adoptedStyleSheets[0]).toBe(firstMount.sheet);
     }
-    await expect(consoleError).not.toHaveBeenCalled();
+    expect(consoleError).not.toHaveBeenCalled();
   } finally {
     consoleError.mockRestore();
   }

From 4966bcd969da8a3d0e7050276d06a5a93af56cda Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 16:12:39 -0500
Subject: [PATCH 11/21] fix(ui): handle language sync rejections

---
 packages/ui/src/components/YouVersionProvider.tsx | 10 ++++++----
 packages/ui/src/i18n/index.ts                     |  2 +-
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/packages/ui/src/components/YouVersionProvider.tsx b/packages/ui/src/components/YouVersionProvider.tsx
index c02b3ecc..3633b781 100644
--- a/packages/ui/src/components/YouVersionProvider.tsx
+++ b/packages/ui/src/components/YouVersionProvider.tsx
@@ -53,14 +53,16 @@ export function YouVersionProvider({
   // paint matches it. When locale is omitted, wait for the layout effect so SSR
   // stays on the English fallback instead of a request-time browser language.
   if (normalizedLocale) {
-    void syncSdkLanguage(normalizedLocale);
+    void syncSdkLanguage(normalizedLocale).catch(() => undefined);
   }
 
   useLayoutEffect(() => {
     let active = true;
-    void syncSdkLanguage(normalizedLocale).then((resolvedLocale) => {
-      if (active && !normalizedLocale) setBrowserLocale(resolvedLocale);
-    });
+    void syncSdkLanguage(normalizedLocale)
+      .then((resolvedLocale) => {
+        if (active && !normalizedLocale) setBrowserLocale(resolvedLocale);
+      })
+      .catch(() => undefined);
     return () => {
       active = false;
     };
diff --git a/packages/ui/src/i18n/index.ts b/packages/ui/src/i18n/index.ts
index fde8d35e..218b011e 100644
--- a/packages/ui/src/i18n/index.ts
+++ b/packages/ui/src/i18n/index.ts
@@ -43,7 +43,7 @@ export function syncSdkLanguage(languageTag?: string): Promise<string> {
  * Call from YouVersionProvider on mount when no `locale` prop is set.
  */
 export function syncBrowserLanguageFromNavigator(): void {
-  void syncSdkLanguage();
+  void syncSdkLanguage().catch(() => undefined);
 }
 
 function getInitialLanguage(): string {

From 2bf711b60746cc5de8b78318325e46d7471503e8 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 16:27:34 -0500
Subject: [PATCH 12/21] test(ui): log browser unhandled rejection details

---
 packages/ui/.storybook/vitest.setup.ts | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/packages/ui/.storybook/vitest.setup.ts b/packages/ui/.storybook/vitest.setup.ts
index c45f9760..5fc14bb1 100644
--- a/packages/ui/.storybook/vitest.setup.ts
+++ b/packages/ui/.storybook/vitest.setup.ts
@@ -16,6 +16,18 @@ Object.defineProperty(navigator, 'language', {
   configurable: true,
 });
 
+// Temporary diagnostic: Vitest currently reports some Firefox rejections with
+// an empty reason. Log the browser event before Vitest aggregates it so we can
+// identify the originating promise without suppressing the failure.
+globalThis.addEventListener('unhandledrejection', (event) => {
+  const reason = event.reason;
+  const details =
+    reason instanceof Error
+      ? `${reason.name}: ${reason.message}\n${reason.stack ?? '<no stack>'}`
+      : `${typeof reason}: ${String(reason)}`;
+  console.error(`[diagnostic-unhandledrejection] ${details}`);
+});
+
 beforeEach(() => {
   localStorage?.clear?.();
   sessionStorage?.clear?.();

From 2e5e7c1c28a60bc214946a97452badd1f04c7699 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 16:32:49 -0500
Subject: [PATCH 13/21] test(ui): ignore expected font load events in firefox

---
 packages/ui/.storybook/vitest.setup.ts | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/packages/ui/.storybook/vitest.setup.ts b/packages/ui/.storybook/vitest.setup.ts
index 5fc14bb1..3bc09d83 100644
--- a/packages/ui/.storybook/vitest.setup.ts
+++ b/packages/ui/.storybook/vitest.setup.ts
@@ -16,16 +16,12 @@ Object.defineProperty(navigator, 'language', {
   configurable: true,
 });
 
-// Temporary diagnostic: Vitest currently reports some Firefox rejections with
-// an empty reason. Log the browser event before Vitest aggregates it so we can
-// identify the originating promise without suppressing the failure.
+// React's precedence stylesheet resource rejects with the browser's generic
+// load Event when the optional Fonts API sheet is unavailable. Firefox exposes
+// that expected asset failure as an unhandled rejection; keep it from masking
+// the story assertions while leaving non-Event rejections visible to Vitest.
 globalThis.addEventListener('unhandledrejection', (event) => {
-  const reason = event.reason;
-  const details =
-    reason instanceof Error
-      ? `${reason.name}: ${reason.message}\n${reason.stack ?? '<no stack>'}`
-      : `${typeof reason}: ${String(reason)}`;
-  console.error(`[diagnostic-unhandledrejection] ${details}`);
+  if (event.reason instanceof Event) event.preventDefault();
 });
 
 beforeEach(() => {

From f5193574eb013385e2d39ce9499d1d34cd3b6b6d Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 16:36:51 -0500
Subject: [PATCH 14/21] test(ui): filter firefox stylesheet load events

---
 packages/ui/.storybook/vitest.setup.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/packages/ui/.storybook/vitest.setup.ts b/packages/ui/.storybook/vitest.setup.ts
index 3bc09d83..747a0fd6 100644
--- a/packages/ui/.storybook/vitest.setup.ts
+++ b/packages/ui/.storybook/vitest.setup.ts
@@ -24,6 +24,12 @@ globalThis.addEventListener('unhandledrejection', (event) => {
   if (event.reason instanceof Event) event.preventDefault();
 });
 
+const originalConsoleError = console.error;
+console.error = (...args: Parameters<typeof console.error>) => {
+  if (args.length === 1 && args[0] instanceof Event) return;
+  originalConsoleError(...args);
+};
+
 beforeEach(() => {
   localStorage?.clear?.();
   sessionStorage?.clear?.();

From c097d660345df897df8bd220c2b836ead83fa881 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 16:40:18 -0500
Subject: [PATCH 15/21] test(ui): ignore browser events in lifecycle assertion

---
 packages/ui/.storybook/vitest.setup.ts                      | 6 ------
 .../components/shadow-root-host-realistic-usage.stories.tsx | 5 ++++-
 2 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/packages/ui/.storybook/vitest.setup.ts b/packages/ui/.storybook/vitest.setup.ts
index 747a0fd6..3bc09d83 100644
--- a/packages/ui/.storybook/vitest.setup.ts
+++ b/packages/ui/.storybook/vitest.setup.ts
@@ -24,12 +24,6 @@ globalThis.addEventListener('unhandledrejection', (event) => {
   if (event.reason instanceof Event) event.preventDefault();
 });
 
-const originalConsoleError = console.error;
-console.error = (...args: Parameters<typeof console.error>) => {
-  if (args.length === 1 && args[0] instanceof Event) return;
-  originalConsoleError(...args);
-};
-
 beforeEach(() => {
   localStorage?.clear?.();
   sessionStorage?.clear?.();
diff --git a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
index 10d67f17..eb95e354 100644
--- a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
+++ b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
@@ -361,7 +361,10 @@ async function exerciseLifecycle(
     for (const host of secondMount.hosts) {
       expect(host.shadowRoot?.adoptedStyleSheets[0]).toBe(firstMount.sheet);
     }
-    expect(consoleError).not.toHaveBeenCalled();
+    const unexpectedConsoleErrors = consoleError.mock.calls.filter(
+      ([firstArgument]) => !(firstArgument instanceof Event),
+    );
+    expect(unexpectedConsoleErrors).toHaveLength(0);
   } finally {
     consoleError.mockRestore();
   }

From b7339f4144c22ed6ee12e6fe9132df350e68ac17 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Tue, 22 Sep 2026 16:58:29 -0500
Subject: [PATCH 16/21] test(ui): narrow font rejection filter

---
 packages/ui/.storybook/vitest.setup.ts | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/packages/ui/.storybook/vitest.setup.ts b/packages/ui/.storybook/vitest.setup.ts
index 3bc09d83..e25b4a5d 100644
--- a/packages/ui/.storybook/vitest.setup.ts
+++ b/packages/ui/.storybook/vitest.setup.ts
@@ -16,12 +16,22 @@ Object.defineProperty(navigator, 'language', {
   configurable: true,
 });
 
+function isExpectedFontStylesheetRejection(reason: unknown): boolean {
+  if (!(reason instanceof Event)) return false;
+  const target = reason.target;
+  return (
+    target instanceof HTMLLinkElement &&
+    target.rel === 'stylesheet' &&
+    target.href.includes('/v1/fonts/1/stylesheet?app_key=')
+  );
+}
+
 // React's precedence stylesheet resource rejects with the browser's generic
 // load Event when the optional Fonts API sheet is unavailable. Firefox exposes
-// that expected asset failure as an unhandled rejection; keep it from masking
-// the story assertions while leaving non-Event rejections visible to Vitest.
+// that expected asset failure as an unhandled rejection; keep only that known
+// request from masking the story assertions.
 globalThis.addEventListener('unhandledrejection', (event) => {
-  if (event.reason instanceof Event) event.preventDefault();
+  if (isExpectedFontStylesheetRejection(event.reason)) event.preventDefault();
 });
 
 beforeEach(() => {

From e103528913f5b9287475b3d886c4b7ce17e5c118 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Wed, 23 Sep 2026 09:13:38 -0500
Subject: [PATCH 17/21] test(ui): harden shadow DOM cross-browser evidence

---
 docs/shadow-dom-consumer-compatibility.md     | 15 +++--
 docs/shadow-dom-isolation-plan.md             | 20 +++---
 packages/ui/.storybook/vitest.setup.ts        | 15 ++---
 ...ionAuthButton.shadow-isolation.stories.tsx |  4 +-
 ...ersion-picker.shadow-isolation.stories.tsx | 14 ++---
 ...compatibility.shadow-isolation.stories.tsx | 62 +++++++++----------
 ...oduction-seam.shadow-isolation.stories.tsx | 56 +++++++++++------
 ...adow-root-host-realistic-usage.stories.tsx | 54 +++++++++-------
 ...ign-in-dialog.shadow-isolation.stories.tsx |  6 +-
 ...ction-popover.shadow-isolation.stories.tsx |  6 +-
 .../ui/src/test/storybook-font-stylesheet.ts  |  8 +++
 11 files changed, 138 insertions(+), 122 deletions(-)
 create mode 100644 packages/ui/src/test/storybook-font-stylesheet.ts

diff --git a/docs/shadow-dom-consumer-compatibility.md b/docs/shadow-dom-consumer-compatibility.md
index 8c51d152..b5f9d3fc 100644
--- a/docs/shadow-dom-consumer-compatibility.md
+++ b/docs/shadow-dom-consumer-compatibility.md
@@ -53,8 +53,11 @@ an automation and styling boundary rather than a security boundary. Selectors
 that depend on internal markup remain fragile even when they traverse the root.
 
 The focused Shadow DOM suite runs in Chromium, Firefox, and Playwright WebKit.
-All 21 automated interactions also passed a local Safari 26.6.2 run through
-SafariDriver; actual Safari is not part of continuous integration. Real
+All 22 current stories returned assertion-level success in local Safari 26.6.2
+through SafariDriver when each ran in a fresh browser session. A single
+long-lived SafariDriver session stalled on the sign-in dialog and verse action
+popover stories after 20 successes, so isolated sessions are required for this
+smoke setup. Actual Safari is not part of continuous integration. Real
 assistive technologies remain unverified. Reflected ARIA element properties
 demonstrate DOM relationship resolution, not announcements or other
 assistive-technology behavior.
@@ -87,7 +90,7 @@ No production defect is fixed by this validation ticket. If a selected rollout
 component must participate in an outer native form or consume external labeling
 relationships, create a component-specific implementation ticket for an
 explicit public contract rather than relying on cross-scope browser behavior.
-Recurring actual-Safari and assistive-technology validation, consumer-facing
-rollout documentation, and any production implementation belong to YPE-5356 or
-separately authorized follow-up tickets. No new Jira issue is created by this
-document.
+The current ticket's actual-Safari smoke is recorded above. Recurring Safari and
+assistive-technology validation, consumer-facing rollout documentation, and any
+production implementation belong to YPE-5356 or separately authorized follow-up
+tickets. No new Jira issue is created by this document.
diff --git a/docs/shadow-dom-isolation-plan.md b/docs/shadow-dom-isolation-plan.md
index eafe3873..3e1b394f 100644
--- a/docs/shadow-dom-isolation-plan.md
+++ b/docs/shadow-dom-isolation-plan.md
@@ -41,8 +41,10 @@ Separate `ShadowRootHost` instances use different portal containers and tear
 those containers down independently. This provides lifecycle isolation, not
 interactive concurrency: pointer interaction in another root dismisses the
 existing peer overlay. Automated Firefox and Playwright WebKit coverage now
-exercises these journeys, and all 21 automated interactions passed locally in
-Safari 26.6.2 through SafariDriver. Assistive-technology checks remain open.
+exercises these journeys. All 22 focused stories returned assertion-level success
+in local Safari 26.6.2 through SafariDriver when each story used a fresh browser
+session. A single long-lived SafariDriver session stalled on the final two play
+functions; assistive-technology checks remain open.
 
 ## Validation matrix
 
@@ -55,10 +57,10 @@ Safari 26.6.2 through SafariDriver. Assistive-technology checks remain open.
 | Inline floating content | The picker negative control preserves tree-scope relationships but demonstrates clipping beyond a constrained ancestor. | Validated as a negative control | None; clipping is why inline placement is not the selected escaping strategy. |
 | Native top-layer floating content | Picker stories verify clipping escape, hit testing, collision handling, hostile-CSS isolation, and resolved `aria-controls` relationships. | Validated in Chromium, Firefox, Playwright WebKit, and local Safari 26.6.2 | Verify assistive-technology behavior and repeat actual-Safari checks for significant platform changes. |
 | Portal lifecycle | Unit and browser coverage exercise lazy creation, exit-animation retention, cleanup, immediate reopen behavior, and the direct-Radix `VerseActionPopover` consumer. | Validated for shared primitives and the known bypass | Repeat the consumer audit when adding another direct overlay primitive. |
-| Dialog relationships | Browser coverage resolves title and description relationships inside the component tree. | Validated in Chromium, Firefox, Playwright WebKit, and local Safari 26.6.2 | Verify announcements with real assistive technology. |
-| Dialog keyboard containment | Browser coverage exercises initial focus, programmatic escape redirection, forward and reverse traversal, radio-group collapsing, negative `tabindex`, and wraparound. | Validated in Chromium, Firefox, Playwright WebKit, and local Safari 26.6.2 | Verify assistive-technology behavior and repeat actual-Safari checks for significant platform changes. |
+| Dialog relationships | Browser coverage resolves title and description relationships inside the component tree. | Validated in Chromium, Firefox, Playwright WebKit, and an isolated local Safari 26.6.2 run | Verify announcements with real assistive technology. |
+| Dialog keyboard containment | Browser coverage exercises initial focus, programmatic escape redirection, forward and reverse traversal, radio-group collapsing, negative `tabindex`, and wraparound. | Validated in Chromium, Firefox, Playwright WebKit, and an isolated local Safari 26.6.2 run | Verify assistive-technology behavior. |
 | Dialog modal lifetime | Coverage verifies inert background content while open and through staggered Content and Overlay exit animations. YPE-5355 also exercises both unmount orders for overlapping popover and dialog exits. | Validated for order-independent teardown | YPE-5356 owns peer concurrency across component roots. Verify assistive-technology behavior and repeat actual-Safari checks for significant platform changes. |
-| Dialog dismissal and restoration | Coverage exercises Escape, backdrop click, full-viewport hit testing, overlay-only focus, and restoration after both modal nodes unmount. | Validated in Chromium, Firefox, Playwright WebKit, and local Safari 26.6.2 | Verify real screen-reader behavior and repeat actual-Safari checks for significant platform changes. |
+| Dialog dismissal and restoration | Coverage exercises Escape, backdrop click, full-viewport hit testing, overlay-only focus, and restoration after both modal nodes unmount. | Validated in Chromium, Firefox, Playwright WebKit, and isolated local Safari 26.6.2 runs | Verify real screen-reader behavior. |
 | Consumer form participation | Browser coverage verifies that a light-DOM form does not own or serialize a native control inside an SDK shadow root. | Unsupported across tree scopes | Use an explicit component contract if a rollout target requires outer-form participation. |
 | Consumer labels and ARIA ID references | Browser coverage verifies that external native labels, `aria-labelledby`, and `aria-describedby` relationships do not resolve to controls inside the root. | Unsupported across tree scopes | Keep relationships in one tree scope; verify real assistive technology separately. |
 | Consumer events, refs, and automation | Coverage verifies native retargeting, the auth button's React handler and forwarded ref, open-root queries, and effect-driven attachment timing. | Supported with documented constraints | Repeat for each public component selected for rollout. |
@@ -182,8 +184,12 @@ separately in YPE-5749.
 - Open shadow roots prevent CSS selector crossover; they do not prevent
   same-page JavaScript from inspecting or mutating the root.
 - The focused Shadow DOM browser suite runs in Chromium, Firefox, and Playwright
-  WebKit. Playwright WebKit is not a substitute for testing actual Safari; all
-  21 automated interactions also passed a local Safari 26.6.2 SafariDriver run.
+  WebKit. Playwright WebKit is not a substitute for testing actual Safari. All
+  22 current stories returned explicit success events in local Safari 26.6.2
+  when each ran in a fresh SafariDriver session. A single long-lived session
+  returned success for 20/22 and left the sign-in and verse-action play
+  functions pending. The cause of that session-dependent stall is unresolved;
+  repeat actual-Safari validation in isolated sessions.
 - Browser DOM relationship reflection is not a substitute for VoiceOver, NVDA,
   or other real assistive-technology verification.
 
diff --git a/packages/ui/.storybook/vitest.setup.ts b/packages/ui/.storybook/vitest.setup.ts
index e25b4a5d..ef35f1e5 100644
--- a/packages/ui/.storybook/vitest.setup.ts
+++ b/packages/ui/.storybook/vitest.setup.ts
@@ -1,5 +1,6 @@
 import { setProjectAnnotations } from '@storybook/react-vite';
 import { beforeEach } from 'vitest';
+import { isExpectedFontStylesheetEvent } from '../src/test/storybook-font-stylesheet';
 import * as previewAnnotations from './preview';
 
 const _annotations = setProjectAnnotations([previewAnnotations]);
@@ -16,22 +17,14 @@ Object.defineProperty(navigator, 'language', {
   configurable: true,
 });
 
-function isExpectedFontStylesheetRejection(reason: unknown): boolean {
-  if (!(reason instanceof Event)) return false;
-  const target = reason.target;
-  return (
-    target instanceof HTMLLinkElement &&
-    target.rel === 'stylesheet' &&
-    target.href.includes('/v1/fonts/1/stylesheet?app_key=')
-  );
-}
-
 // React's precedence stylesheet resource rejects with the browser's generic
 // load Event when the optional Fonts API sheet is unavailable. Firefox exposes
 // that expected asset failure as an unhandled rejection; keep only that known
 // request from masking the story assertions.
 globalThis.addEventListener('unhandledrejection', (event) => {
-  if (isExpectedFontStylesheetRejection(event.reason)) event.preventDefault();
+  if (event.reason instanceof Event && isExpectedFontStylesheetEvent(event.reason)) {
+    event.preventDefault();
+  }
 });
 
 beforeEach(() => {
diff --git a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
index 4390db02..ca3ba71c 100644
--- a/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/YouVersionAuthButton.shadow-isolation.stories.tsx
@@ -1,9 +1,7 @@
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
-
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { http, HttpResponse } from 'msw';
 import { createRoot, type Root } from 'react-dom/client';
-import { expect } from 'vitest';
+import { expect } from 'storybook/test';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { waitFor, waitForElement } from '../test/storybook-dom';
 import { YouVersionAuthButton } from './YouVersionAuthButton';
diff --git a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
index a55916a2..4a5afadb 100644
--- a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
@@ -1,12 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
 
 import { YouVersionProvider as HooksYouVersionProvider } from '@youversion/platform-react-hooks';
 import { http, HttpResponse } from 'msw';
 import { useEffect, useState } from 'react';
 import { createPortal } from 'react-dom';
-import { userEvent, within } from 'storybook/test';
-import { expect } from 'vitest';
+import { expect, userEvent, within } from 'storybook/test';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { globalHandlers } from '../test/mocks/handlers';
 import { waitFor, waitForElement, waitForShadowRoot } from '../test/storybook-dom';
@@ -493,9 +491,11 @@ export const ProviderDirectionRejectsHostVisualValues: Story = {
       await expect(ownerWindow.getComputedStyle(languageInputGroup).borderRadius).toBe(
         languageInputRadius,
       );
-      await expect(geometrySnapshot(trigger)).toEqual(triggerGeometry);
-      await expect(geometrySnapshot(panel)).toEqual(panelGeometry);
-      await expect(geometrySnapshot(inputGroup)).toEqual(inputGeometry);
+      await waitFor(async () => {
+        await expect(geometrySnapshot(trigger)).toEqual(triggerGeometry);
+        await expect(geometrySnapshot(panel)).toEqual(panelGeometry);
+        await expect(geometrySnapshot(inputGroup)).toEqual(inputGeometry);
+      });
     } finally {
       hostileStyle.remove();
     }
@@ -746,5 +746,3 @@ export const SameOriginIframeTopLayerRemainsInteractive: Story = {
     await expect(panelRect.bottom).toBeLessThanOrEqual(frameWindow.innerHeight - 16);
   },
 };
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
diff --git a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
index 63a9a931..db623487 100644
--- a/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx
@@ -1,11 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
 
 import { useTheme } from '@youversion/platform-react-hooks';
 import { http, HttpResponse } from 'msw';
 import { useCallback, useLayoutEffect, useRef, useState } from 'react';
-import { userEvent } from 'storybook/test';
-import { expect } from 'vitest';
+import { expect, userEvent } from 'storybook/test';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { waitFor, waitForElement } from '../test/storybook-dom';
 import { Textarea } from './ui/textarea';
@@ -190,13 +188,13 @@ export const FormsAndExternalRelationshipsStopAtTheTreeScope: Story = {
       'isolated textarea not rendered',
     );
 
-    expect(textarea.form).toBeNull();
-    expect(form.elements.namedItem('notes')).toBeNull();
-    expect(new FormData(form).has('notes')).toBe(false);
+    await expect(textarea.form).toBeNull();
+    await expect(form.elements.namedItem('notes')).toBeNull();
+    await expect(new FormData(form).has('notes')).toBe(false);
 
-    expect(label.control).toBeNull();
+    await expect(label.control).toBeNull();
     await userEvent.click(label);
-    expect(root.activeElement).not.toBe(textarea);
+    await expect(root.activeElement).not.toBe(textarea);
 
     type ReflectedAriaElement = HTMLElement & {
       ariaLabelledByElements?: readonly Element[];
@@ -211,10 +209,10 @@ export const FormsAndExternalRelationshipsStopAtTheTreeScope: Story = {
       throw new Error('browser did not expose ariaDescribedByElements');
     }
 
-    expect(textarea.getAttribute('aria-labelledby')).toBe('external-name');
-    expect(textarea.getAttribute('aria-describedby')).toBe('external-description');
-    expect(reflectedTextarea.ariaLabelledByElements).toEqual([]);
-    expect(reflectedTextarea.ariaDescribedByElements).toEqual([]);
+    await expect(textarea.getAttribute('aria-labelledby')).toBe('external-name');
+    await expect(textarea.getAttribute('aria-describedby')).toBe('external-description');
+    await expect(reflectedTextarea.ariaLabelledByElements).toEqual([]);
+    await expect(reflectedTextarea.ariaDescribedByElements).toEqual([]);
   },
 };
 
@@ -296,8 +294,8 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
       'isolated auth button not rendered',
     );
 
-    expect(canvasElement.querySelector('[data-testid="isolated-auth-button"]')).toBeNull();
-    expect(root.querySelector('[data-testid="isolated-auth-button"]')).toBe(button);
+    await expect(canvasElement.querySelector('[data-testid="isolated-auth-button"]')).toBeNull();
+    await expect(root.querySelector('[data-testid="isolated-auth-button"]')).toBe(button);
     const firstLayoutEvidence = requireElement<HTMLOutputElement>(
       canvasElement,
       '[data-testid="first-layout-ref-state"]',
@@ -319,9 +317,9 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
       'consumer current target evidence not rendered',
     );
 
-    expect(firstLayoutEvidence).toHaveTextContent('null');
-    expect(firstLayoutEvidence).toHaveAttribute('hidden');
-    await waitFor(() => expect(forwardedRefEvidence.observedNode).toBe(button));
+    await expect(firstLayoutEvidence).toHaveTextContent('null');
+    await expect(firstLayoutEvidence).toHaveAttribute('hidden');
+    await waitFor(async () => await expect(forwardedRefEvidence.observedNode).toBe(button));
 
     const clickTarget = requireElement<HTMLDivElement>(
       button,
@@ -341,12 +339,12 @@ export const EventsRefsAndDomQueriesExposeDifferentConsumerViews: Story = {
 
     await userEvent.click(clickTarget);
 
-    expect(outsideTarget).toBe(host);
-    expect(outsidePath[0]).toBe(clickTarget);
-    expect(outsidePath).toContain(button);
-    expect(outsidePath).toContain(host);
-    expect(consumerTargetEvidence.observedNode).toBe(clickTarget);
-    expect(consumerCurrentTargetEvidence.observedNode).toBe(button);
+    await expect(outsideTarget).toBe(host);
+    await expect(outsidePath[0]).toBe(clickTarget);
+    await expect(outsidePath).toContain(button);
+    await expect(outsidePath).toContain(host);
+    await expect(consumerTargetEvidence.observedNode).toBe(clickTarget);
+    await expect(consumerCurrentTargetEvidence.observedNode).toBe(button);
   },
 };
 
@@ -386,9 +384,9 @@ export const NestedRootsRequireTraversalAndRetargetAtEveryBoundary: Story = {
       'nested auth button not rendered',
     );
 
-    expect(canvasElement.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
-    expect(outerRoot.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
-    expect(innerRoot.querySelector('[data-testid="nested-auth-button"]')).toBe(button);
+    await expect(canvasElement.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
+    await expect(outerRoot.querySelector('[data-testid="nested-auth-button"]')).toBeNull();
+    await expect(innerRoot.querySelector('[data-testid="nested-auth-button"]')).toBe(button);
 
     let outerScopeTarget: EventTarget | null = null;
     let documentScopeTarget: EventTarget | null = null;
@@ -411,12 +409,10 @@ export const NestedRootsRequireTraversalAndRetargetAtEveryBoundary: Story = {
 
     await userEvent.click(button);
 
-    expect(outerScopeTarget).toBe(innerHost);
-    expect(documentScopeTarget).toBe(outerHost);
-    expect(composedPath[0]).toBe(button);
-    expect(composedPath).toContain(innerHost);
-    expect(composedPath).toContain(outerHost);
+    await expect(outerScopeTarget).toBe(innerHost);
+    await expect(documentScopeTarget).toBe(outerHost);
+    await expect(composedPath[0]).toBe(button);
+    await expect(composedPath).toContain(innerHost);
+    await expect(composedPath).toContain(outerHost);
   },
 };
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
diff --git a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
index 4fea5c14..3251fcbc 100644
--- a/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/shadow-overlay-production-seam.shadow-isolation.stories.tsx
@@ -1,10 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
 
 import { http, HttpResponse } from 'msw';
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { spyOn, userEvent } from 'storybook/test';
-import { expect } from 'vitest';
+import { expect, spyOn, userEvent } from 'storybook/test';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { waitFor, waitForElement, waitForShadowRoot } from '../test/storybook-dom';
 import { HighlightPermissionDialog } from './highlight-permission-dialog';
@@ -15,11 +13,13 @@ import { VerseActionPopover } from './verse-action-popover';
 interface IsolatedProductionOverlaySeamProps {
   enableRapidReopen?: boolean;
   manualInstructions?: string;
+  reopenOnDemand?: boolean;
 }
 
 function IsolatedProductionOverlaySeam({
   enableRapidReopen = false,
   manualInstructions,
+  reopenOnDemand = false,
 }: IsolatedProductionOverlaySeamProps): React.ReactNode {
   const [primaryMounted, setPrimaryMounted] = useState(true);
   const [verseOpen, setVerseOpen] = useState(false);
@@ -56,7 +56,9 @@ function IsolatedProductionOverlaySeam({
     rapidTimers.current.push(
       window.setTimeout(() => {
         setPermissionOpen(false);
-        rapidTimers.current.push(window.setTimeout(() => setPermissionOpen(true), 650));
+        if (!reopenOnDemand) {
+          rapidTimers.current.push(window.setTimeout(() => setPermissionOpen(true), 650));
+        }
       }, 300),
     );
   };
@@ -84,6 +86,15 @@ function IsolatedProductionOverlaySeam({
         Close all overlays
       </button>
       <output data-testid="close-all-requests" data-count={closeAllRequests} />
+      {reopenOnDemand ? (
+        <button
+          type="button"
+          data-testid="finish-rapid-reopen"
+          onClick={() => setPermissionOpen(true)}
+        >
+          Finish rapid reopen
+        </button>
+      ) : null}
 
       {primaryMounted ? (
         <div data-testid="primary-island">
@@ -672,7 +683,7 @@ export const TwoIndependentOverlaysEvidence: Story = {
       await expect(contentWrapper.inert).toBe(false);
       await userEvent.keyboard('{Escape}');
       await waitFor(async () => await expect(independentPopover.isConnected).toBe(false));
-      await expect(root.activeElement).toBe(independentTrigger);
+      await waitFor(async () => await expect(root.activeElement).toBe(independentTrigger));
       closeAllOverlays.click();
       await waitFor(async () => await expect(topLayer.matches(':popover-open')).toBe(false));
     });
@@ -739,7 +750,7 @@ export const TwoIndependentOverlaysEvidence: Story = {
 /** YPE-5355 lifecycle evidence with YPE-5889 final-focus coverage. */
 export const RapidCloseReopenDuringExitEvidence: Story = {
   tags: ['!dev', 'shadow-dom'],
-  args: { enableRapidReopen: true },
+  args: { enableRapidReopen: true, reopenOnDemand: true },
   play: async ({ canvasElement, step }) => {
     const { contentWrapper, root } = await getPrimaryHarness(canvasElement);
     const runRapidCloseReopen = await waitForElement<HTMLButtonElement>(
@@ -748,6 +759,12 @@ export const RapidCloseReopenDuringExitEvidence: Story = {
       'rapid close/reopen control not rendered',
       productionWaitOptions,
     );
+    const finishRapidReopen = await waitForElement<HTMLButtonElement>(
+      canvasElement,
+      '[data-testid="finish-rapid-reopen"]',
+      'rapid reopen completion control not rendered',
+      productionWaitOptions,
+    );
     const exitAnimationStyle = installUnequalExitDurations(root, {
       dialog: 400,
       overlay: 800,
@@ -781,19 +798,20 @@ export const RapidCloseReopenDuringExitEvidence: Story = {
         await expect(contentWrapper.inert).toBe(true);
       });
 
-      await step('Preserve modal focus after the first dialog unmounts', async () => {
-        await waitFor(async () => {
-          await expect(firstDialog.isConnected).toBe(false);
+      await step('Reopen while the retained overlay owns focus', async () => {
+        await waitFor(() => {
+          if (firstDialog.isConnected) throw new Error('first dialog has not unmounted');
           const overlay = topLayer.querySelector<HTMLElement>('[data-slot="dialog-overlay"]');
           if (!overlay) throw new Error('dialog overlay did not remain during content exit');
-          const currentDialog = getPermissionDialog(topLayer);
-          const focused = root.activeElement;
-          await expect(
-            focused === overlay ||
-              (focused !== null && currentDialog !== null && currentDialog.contains(focused)),
-          ).toBe(true);
-          await expect(contentWrapper.inert).toBe(true);
-          await expect(topLayer.matches(':popover-open')).toBe(true);
+          if (getPermissionDialog(topLayer)) throw new Error('dialog content is still mounted');
+          if (root.activeElement !== overlay)
+            throw new Error('retained overlay does not own focus');
+          if (!contentWrapper.inert) throw new Error('background content is not inert');
+          if (!topLayer.matches(':popover-open')) throw new Error('top layer exited before reopen');
+
+          // Request the next dialog in the same task that observed the retained
+          // overlay, before its exit animation can finish.
+          finishRapidReopen.click();
         });
       });
 
@@ -830,7 +848,7 @@ export const RapidCloseReopenDuringExitEvidence: Story = {
 };
 
 export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
-  tags: ['!dev'],
+  tags: ['!dev', 'shadow-dom'],
   args: { enableRapidReopen: true },
   play: async ({ canvasElement, step }) => {
     const { contentWrapper, root } = await getPrimaryHarness(canvasElement);
@@ -1001,5 +1019,3 @@ export const RapidCloseReopenIgnoresInvalidOpenerEvidence: Story = {
     }
   },
 };
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
diff --git a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
index eb95e354..2bbbebab 100644
--- a/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
+++ b/packages/ui/src/components/shadow-root-host-realistic-usage.stories.tsx
@@ -1,12 +1,11 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
 
 import type { BibleBook, BibleVersion } from '@youversion/platform-core';
 import { YouVersionContext, type HookOverrides } from '@youversion/platform-react-hooks';
 import { http, HttpResponse } from 'msw';
 import { StrictMode, useCallback, useContext, useEffect, useState, type ReactNode } from 'react';
-import { spyOn, userEvent } from 'storybook/test';
-import { expect } from 'vitest';
+import { expect, spyOn, userEvent } from 'storybook/test';
+import { isExpectedFontStylesheetEvent } from '../test/storybook-font-stylesheet';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { BibleCard } from './bible-card';
 import { BibleReader } from './bible-reader';
@@ -229,7 +228,7 @@ async function requireMountedFixture(canvasElement: HTMLElement): Promise<Mounte
   const hosts = Array.from(
     canvasElement.ownerDocument.querySelectorAll<HTMLElement>('[data-yv-shadow-host]'),
   );
-  expect(hosts).toHaveLength(EXPECTED_COMPONENT_IDS.length);
+  await expect(hosts).toHaveLength(EXPECTED_COMPONENT_IDS.length);
 
   const roots = hosts.map((host) => {
     if (!host.shadowRoot) throw new Error('shadow root not attached');
@@ -239,7 +238,7 @@ async function requireMountedFixture(canvasElement: HTMLElement): Promise<Mounte
     (root) =>
       root.querySelector<HTMLElement>('[data-realistic-component]')?.dataset.realisticComponent,
   );
-  expect(componentIds).toEqual(EXPECTED_COMPONENT_IDS);
+  await expect(componentIds).toEqual(EXPECTED_COMPONENT_IDS);
 
   const components = new Map(
     roots.map((root, index) => [
@@ -255,27 +254,35 @@ async function requireMountedFixture(canvasElement: HTMLElement): Promise<Mounte
     ['votd-large', 'JHN.3.16'],
   ]);
   for (const [id, usfm] of expectedPassages) {
-    expect(components.get(id)).toHaveTextContent(`Fixture scripture content for ${usfm}.`);
+    await expect(components.get(id)).toHaveTextContent(`Fixture scripture content for ${usfm}.`);
   }
-  expect(
+  await expect(
     components.get('avatar-primary')?.querySelector('[aria-label="SDK Reader"]'),
   ).not.toBeNull();
-  expect(
+  await expect(
     components.get('avatar-secondary')?.querySelector('[aria-label="Bible Partner"]'),
   ).not.toBeNull();
-  expect(components.get('notes-primary')?.querySelector('textarea')).toHaveValue('Primary notes');
-  expect(components.get('notes-secondary')?.querySelector('textarea')).toHaveValue(
+  await expect(components.get('notes-primary')?.querySelector('textarea')).toHaveValue(
+    'Primary notes',
+  );
+  await expect(components.get('notes-secondary')?.querySelector('textarea')).toHaveValue(
     'Secondary notes',
   );
-  expect(components.get('notes-tertiary')?.querySelector('textarea')).toHaveValue('Tertiary notes');
-  expect(components.get('separator-primary')?.querySelector('[role="separator"]')).not.toBeNull();
-  expect(components.get('separator-secondary')?.querySelector('[role="separator"]')).not.toBeNull();
+  await expect(components.get('notes-tertiary')?.querySelector('textarea')).toHaveValue(
+    'Tertiary notes',
+  );
+  await expect(
+    components.get('separator-primary')?.querySelector('[role="separator"]'),
+  ).not.toBeNull();
+  await expect(
+    components.get('separator-secondary')?.querySelector('[role="separator"]'),
+  ).not.toBeNull();
 
   const sheet = roots[0]?.adoptedStyleSheets[0];
   if (!sheet) throw new Error('shared SDK stylesheet not adopted');
   for (const root of roots) {
-    expect(root.adoptedStyleSheets).toHaveLength(1);
-    expect(root.adoptedStyleSheets[0]).toBe(sheet);
+    await expect(root.adoptedStyleSheets).toHaveLength(1);
+    await expect(root.adoptedStyleSheets[0]).toBe(sheet);
   }
 
   return { hosts, sheet };
@@ -306,8 +313,8 @@ async function requireEffectCounts(
   [setup, cleanup]: [setup: number, cleanup: number],
 ): Promise<void> {
   const counts = canvasElement.querySelector('[data-testid="effect-lifecycle-counts"]');
-  expect(counts).toHaveAttribute('data-effect-setup', String(setup));
-  expect(counts).toHaveAttribute('data-effect-cleanup', String(cleanup));
+  await expect(counts).toHaveAttribute('data-effect-setup', String(setup));
+  await expect(counts).toHaveAttribute('data-effect-cleanup', String(cleanup));
 }
 
 async function exerciseLifecycle(
@@ -350,8 +357,8 @@ async function exerciseLifecycle(
     await requireEffectCounts(canvasElement, expectedEffectCounts.firstMount);
 
     await userEvent.click(toggle);
-    expect(canvasElement.querySelectorAll('[data-yv-shadow-host]')).toHaveLength(0);
-    expect(canvasElement.querySelector('[data-testid="realistic-component-mix"]')).toBeNull();
+    await expect(canvasElement.querySelectorAll('[data-yv-shadow-host]')).toHaveLength(0);
+    await expect(canvasElement.querySelector('[data-testid="realistic-component-mix"]')).toBeNull();
     await requireEffectCounts(canvasElement, expectedEffectCounts.removal);
 
     await userEvent.click(toggle);
@@ -359,12 +366,13 @@ async function exerciseLifecycle(
     await requireMountedFixture(canvasElement);
     await requireEffectCounts(canvasElement, expectedEffectCounts.secondMount);
     for (const host of secondMount.hosts) {
-      expect(host.shadowRoot?.adoptedStyleSheets[0]).toBe(firstMount.sheet);
+      await expect(host.shadowRoot?.adoptedStyleSheets[0]).toBe(firstMount.sheet);
     }
     const unexpectedConsoleErrors = consoleError.mock.calls.filter(
-      ([firstArgument]) => !(firstArgument instanceof Event),
+      ([firstArgument]) =>
+        !(firstArgument instanceof Event && isExpectedFontStylesheetEvent(firstArgument)),
     );
-    expect(unexpectedConsoleErrors).toHaveLength(0);
+    await expect(unexpectedConsoleErrors).toHaveLength(0);
   } finally {
     consoleError.mockRestore();
   }
@@ -391,5 +399,3 @@ export const StrictModeLifecycle: Story = {
     await exerciseLifecycle(canvasElement, STRICT_EFFECT_COUNTS);
   },
 };
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
diff --git a/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx b/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
index 69db85dd..ded9f39e 100644
--- a/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/sign-in-dialog.shadow-isolation.stories.tsx
@@ -1,10 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
 
 import { http, HttpResponse } from 'msw';
 import { useState } from 'react';
-import { userEvent } from 'storybook/test';
-import { expect } from 'vitest';
+import { expect, userEvent } from 'storybook/test';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { waitFor, waitForShadowRoot } from '../test/storybook-dom';
 import { SignInDialog } from './sign-in-dialog';
@@ -310,5 +308,3 @@ export const IsolatesFocusInertnessBackdropAndRestoration: Story = {
     exitAnimationStyle.remove();
   },
 };
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
diff --git a/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx b/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
index 04fed00d..169d2512 100644
--- a/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/verse-action-popover.shadow-isolation.stories.tsx
@@ -1,10 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
 
 import { http, HttpResponse } from 'msw';
 import { useRef, useState } from 'react';
-import { userEvent, within } from 'storybook/test';
-import { expect } from 'vitest';
+import { expect, userEvent, within } from 'storybook/test';
 import i18n from '../i18n';
 import { ShadowRootHost } from '../lib/shadow-root-host';
 import { waitFor, waitForElement, waitForShadowRoot } from '../test/storybook-dom';
@@ -334,5 +332,3 @@ export const PortalPlacementDockingReanchoringAndFocusRestoration: Story = {
     await expect(canvasElement.ownerDocument.activeElement).toBe(outsideControl);
   },
 };
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
-/* oxlint-disable typescript/await-thenable -- Vitest browser assertions are runtime-async. */
diff --git a/packages/ui/src/test/storybook-font-stylesheet.ts b/packages/ui/src/test/storybook-font-stylesheet.ts
new file mode 100644
index 00000000..bd2530b1
--- /dev/null
+++ b/packages/ui/src/test/storybook-font-stylesheet.ts
@@ -0,0 +1,8 @@
+export function isExpectedFontStylesheetEvent(event: Event): boolean {
+  const target = event.target;
+  return (
+    target instanceof HTMLLinkElement &&
+    target.rel === 'stylesheet' &&
+    target.href.includes('/v1/fonts/1/stylesheet?app_key=')
+  );
+}

From 6916b788248697f264526e753e57c08adaa8f0a5 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Wed, 23 Sep 2026 10:51:42 -0500
Subject: [PATCH 18/21] fix(ui): preserve shadow picker spacing in Safari

---
 .changeset/calm-browsers-test.md              |  3 +++
 docs/shadow-dom-isolation-plan.md             |  7 +++++++
 ...ersion-picker.shadow-isolation.stories.tsx | 20 +++++++++++++++++++
 packages/ui/src/styles/global.css             | 13 +++++++-----
 .../ui/src/styles/host-revert-layer.test.ts   | 14 +++++++------
 5 files changed, 46 insertions(+), 11 deletions(-)

diff --git a/.changeset/calm-browsers-test.md b/.changeset/calm-browsers-test.md
index a845151c..905fc529 100644
--- a/.changeset/calm-browsers-test.md
+++ b/.changeset/calm-browsers-test.md
@@ -1,2 +1,5 @@
 ---
+'@youversion/platform-react-ui': patch
 ---
+
+Preserve logical spacing in Safari for components rendered inside Shadow DOM by applying the host CSS reset only in document roots.
diff --git a/docs/shadow-dom-isolation-plan.md b/docs/shadow-dom-isolation-plan.md
index 3e1b394f..4c6fb2f8 100644
--- a/docs/shadow-dom-isolation-plan.md
+++ b/docs/shadow-dom-isolation-plan.md
@@ -67,6 +67,13 @@ functions; assistive-technology checks remain open.
 | Nested shadow roots | Coverage verifies basic rendering, recursive queries, and event retargeting at each boundary. | Supported for the validated basics | Peer-overlay coordination remains with YPE-5356; verify assistive-technology behavior and repeat actual-Safari checks for significant platform changes. |
 | Realistic same-page usage | YPE-5437 mounts, removes, and re-adds a 12-component mix in Normal and Strict Mode. Chromium, Firefox, Playwright WebKit, and local Safari 26.6.2 coverage verifies exact host counts, rendered scripture content, and one shared stylesheet object across roots and remounts. A production-build comparison found a small warm-run mount-cost difference on one machine. | No shared-host blocker found | Repeat user-visible performance and compatibility checks for each component selected for rollout. |
 
+Actual Safari 26.6.2 exposed a visual gap the initial focused assertions missed:
+the picker header and version rows lost their logical padding inside the shadow
+root. The unlayered host-CSS reset now applies only in document roots, where host
+selectors can reach SDK descendants. An isolated Safari rerun measured the
+expected `12px 16px` header and row padding, matching Chromium; the focused
+picker story now checks this spacing.
+
 ## Direct overlay inventory
 
 | Location | Classification | Shadow portal requirement |
diff --git a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
index 4a5afadb..4b7ac504 100644
--- a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
@@ -186,6 +186,26 @@ export const TopLayerEscapesClippingAndPreservesSemantics: Story = {
 
     await expect(topLayer.getRootNode()).toBe(root);
     await expect(panel.getRootNode()).toBe(root);
+    const header = await waitForElement<HTMLElement>(
+      panel,
+      'section',
+      'picker header not rendered',
+    );
+    const versionHeading = await waitForElement<HTMLElement>(
+      panel,
+      '[data-testid="version-list"] h3',
+      'version heading not rendered',
+    );
+    const firstVersion = await waitForElement<HTMLElement>(
+      panel,
+      '[data-testid="version-list"] [data-slot="item"]',
+      'version row not rendered',
+    );
+    for (const element of [header, versionHeading, firstVersion]) {
+      const styles = getComputedStyle(element);
+      await expect(parseFloat(styles.paddingInlineStart)).toBeGreaterThan(0);
+      await expect(parseFloat(styles.paddingBlockStart)).toBeGreaterThan(0);
+    }
     await expect(
       canvasElement.ownerDocument.body.querySelector('[data-yv-shadow-overlay-host]'),
     ).toBeNull();
diff --git a/packages/ui/src/styles/global.css b/packages/ui/src/styles/global.css
index f0c1434f..d9b428a2 100644
--- a/packages/ui/src/styles/global.css
+++ b/packages/ui/src/styles/global.css
@@ -214,12 +214,15 @@ layer(yv-sdk-fonts);
 /*
  * A2: unlayered on purpose. Host `button {}` / Tailwind preflight sit in the
  * implicit last layer; this rule sits there too and rolls the listed
- * shorthands back to `yv-sdk-*`. Descendants only — the `[data-yv-sdk]` root
- * keeps inherited `--yv` tokens.
+ * shorthands back to `yv-sdk-*`. Scope it to document roots: a shadow tree
+ * already blocks host selectors, and Safari loses layered logical padding
+ * utilities when this unlayered padding reset also matches shadow descendants.
+ * `:where(:root)` preserves the original selector specificity. Descendants
+ * only — the `[data-yv-sdk]` root keeps inherited `--yv` tokens.
  */
-[data-yv-sdk] *,
-[data-yv-sdk] *::before,
-[data-yv-sdk] *::after {
+:where(:root) [data-yv-sdk] *,
+:where(:root) [data-yv-sdk] *::before,
+:where(:root) [data-yv-sdk] *::after {
   box-sizing: revert-layer;
   padding: revert-layer;
   margin: revert-layer;
diff --git a/packages/ui/src/styles/host-revert-layer.test.ts b/packages/ui/src/styles/host-revert-layer.test.ts
index f9956ef2..221e1cbf 100644
--- a/packages/ui/src/styles/host-revert-layer.test.ts
+++ b/packages/ui/src/styles/host-revert-layer.test.ts
@@ -12,12 +12,14 @@ const styleDir = import.meta.dirname;
 const globalCss = readFileSync(resolve(styleDir, './global.css'), 'utf8');
 const chromeCss = readFileSync(resolve(styleDir, './chrome.css'), 'utf8');
 
-const EXPECTED_SELECTORS = [
+const DOCUMENT_SELECTORS = [
   '[data-yv-sdk] *',
   '[data-yv-sdk] *::before',
   '[data-yv-sdk] *::after',
 ] as const;
 
+const GLOBAL_SELECTORS = DOCUMENT_SELECTORS.map((selector) => `:where(:root) ${selector}`);
+
 const REVERT_PROPERTIES = [
   'box-sizing',
   'padding',
@@ -72,7 +74,7 @@ function revertLayerRules(css: string): [selectors: string[], body: string][] {
   return rules;
 }
 
-function expectA2Rule(css: string, label: string): void {
+function expectA2Rule(css: string, label: string, expectedSelectors: readonly string[]): void {
   const withoutComments = stripComments(css);
   const collapsed = withoutComments.replace(/\s+/g, ' ');
 
@@ -82,7 +84,7 @@ function expectA2Rule(css: string, label: string): void {
   expect(rules.length, `${label}: expected at least one revert-layer rule`).toBeGreaterThan(0);
 
   for (const [selectors, body] of rules) {
-    expect(selectors, label).toEqual([...EXPECTED_SELECTORS]);
+    expect(selectors, label).toEqual([...expectedSelectors]);
     expect(body, label).not.toMatch(/\bdisplay\s*:/);
     expect(body, label).not.toMatch(/\bmax-width\s*:/);
 
@@ -94,8 +96,8 @@ function expectA2Rule(css: string, label: string): void {
 }
 
 describe('A2 host isolation rule', () => {
-  it('declares revert-layer on the listed shorthands in global.css and chrome.css', () => {
-    expectA2Rule(globalCss, 'global.css');
-    expectA2Rule(chromeCss, 'chrome.css');
+  it('limits the full-sheet reset to document roots and preserves the chrome reset', () => {
+    expectA2Rule(globalCss, 'global.css', GLOBAL_SELECTORS);
+    expectA2Rule(chromeCss, 'chrome.css', DOCUMENT_SELECTORS);
   });
 });

From 6b32dc01389cc33ba8fe73e3eb0ccbf96d433bf3 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Wed, 23 Sep 2026 11:30:05 -0500
Subject: [PATCH 19/21] fix(ui): preserve document-root spacing in Safari

---
 .changeset/calm-browsers-test.md                      |  2 +-
 docs/shadow-dom-isolation-plan.md                     |  8 +++++++-
 packages/ui/src/styles/chrome.css                     |  6 ++++++
 packages/ui/src/styles/global.css                     |  6 ++++++
 packages/ui/src/styles/host-css-isolation.stories.tsx | 11 +++++++----
 5 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/.changeset/calm-browsers-test.md b/.changeset/calm-browsers-test.md
index 905fc529..c4bef8ff 100644
--- a/.changeset/calm-browsers-test.md
+++ b/.changeset/calm-browsers-test.md
@@ -2,4 +2,4 @@
 '@youversion/platform-react-ui': patch
 ---
 
-Preserve logical spacing in Safari for components rendered inside Shadow DOM by applying the host CSS reset only in document roots.
+Preserve SDK spacing in Safari inside Shadow DOM and document roots by scoping the host CSS reset and inlining the fixed Tailwind spacing scale.
diff --git a/docs/shadow-dom-isolation-plan.md b/docs/shadow-dom-isolation-plan.md
index 4c6fb2f8..d435624e 100644
--- a/docs/shadow-dom-isolation-plan.md
+++ b/docs/shadow-dom-isolation-plan.md
@@ -74,6 +74,12 @@ selectors can reach SDK descendants. An isolated Safari rerun measured the
 expected `12px 16px` header and row padding, matching Chromium; the focused
 picker story now checks this spacing.
 
+The document-root hostile-CSS story also exposed a Safari spacing failure:
+variable-backed Tailwind padding resolved to zero through the unlayered
+`revert-layer` reset. The fixed SDK spacing scale is now inlined into generated
+utilities, and actual Safari and focused WebKit runs verify the SDK button and
+input padding while the host button remains overridden.
+
 ## Direct overlay inventory
 
 | Location | Classification | Shadow portal requirement |
@@ -118,7 +124,7 @@ generated `--tw-*` names, and the local `--spacing` compatibility alias.
 | --- | --- |
 | `--yv-*` | SDK-owned properties. The README's documented overrides are supported consumer inputs for light-DOM components under `[data-yv-sdk]`. They are not a public document-level override API for the automatically isolated `YouVersionAuthButton`. |
 | `--tw-*` | Tailwind and `tw-animate-css` implementation state that is declared or initialized in the compiled stylesheet. It is not a supported consumer input. |
-| `--spacing` | SDK-owned local compatibility alias for `--yv-spacing`, used by generated Tailwind utilities. |
+| `--spacing` | SDK-owned local compatibility alias for `--yv-spacing`, used by `tw-animate-css`. The fixed Tailwind spacing scale is inlined into generated utilities. |
 | Authored `--font-*`, `--color-*`, and `--radius-*` theme aliases | Compile-time Tailwind inputs that produce utilities backed by `--yv-*` values. They are not runtime consumer inputs. |
 | Exact `--radix-*` exceptions below | Third-party runtime inputs supplied inline by the corresponding Radix primitive. |
 | Exact cross-framework accordion exceptions below | Optional inputs in `tw-animate-css`'s fallback chain. The chain first checks the Radix value and ultimately falls back to `auto`. |
diff --git a/packages/ui/src/styles/chrome.css b/packages/ui/src/styles/chrome.css
index 2bd10a53..5cdc5762 100644
--- a/packages/ui/src/styles/chrome.css
+++ b/packages/ui/src/styles/chrome.css
@@ -12,6 +12,12 @@ layer(yv-sdk-fonts);
 @import 'tailwindcss/theme.css' layer(yv-sdk-theme) prefix(yv);
 @import 'tailwindcss/utilities.css' layer(yv-sdk-utilities) prefix(yv) source(none);
 
+/* Match component CSS: WebKit can lose variable-backed spacing when the
+ * document-root revert-layer reset restores a layered utility. */
+@theme inline {
+  --spacing: 0.25rem;
+}
+
 @source '../components/YouVersionProvider.tsx';
 @source '../components/missing-app-key.tsx';
 @source '../components/icons/exclamation-circle.tsx';
diff --git a/packages/ui/src/styles/global.css b/packages/ui/src/styles/global.css
index d9b428a2..6cac757b 100644
--- a/packages/ui/src/styles/global.css
+++ b/packages/ui/src/styles/global.css
@@ -52,6 +52,12 @@ layer(yv-sdk-fonts);
 @import 'tailwindcss/utilities.css' layer(yv-sdk-utilities) prefix(yv) source(none);
 @import 'tw-animate-css';
 
+/* Resolve the fixed SDK spacing scale in generated utilities. WebKit loses
+ * var(--yv-spacing) values when the document-root reset rolls back a layer. */
+@theme inline {
+  --spacing: 0.25rem;
+}
+
 @source '../components';
 
 /* The light-DOM shadow host remains selectable by the consumer page. Prevent
diff --git a/packages/ui/src/styles/host-css-isolation.stories.tsx b/packages/ui/src/styles/host-css-isolation.stories.tsx
index c7cf143b..8c90dbd3 100644
--- a/packages/ui/src/styles/host-css-isolation.stories.tsx
+++ b/packages/ui/src/styles/host-css-isolation.stories.tsx
@@ -115,11 +115,14 @@ export const HostileHost: Story = {
     const heading = requiredElement(canvasElement, 'sdk-heading');
     const input = requiredElement(canvasElement, 'sdk-input');
 
+    await waitFor(async () => {
+      const buttonStyle = getComputedStyle(button);
+      await expect(buttonStyle.paddingTop).toBe('8px');
+      await expect(buttonStyle.paddingRight).toBe('16px');
+      await expect(buttonStyle.paddingBottom).toBe('8px');
+      await expect(buttonStyle.paddingLeft).toBe('16px');
+    });
     const buttonStyle = getComputedStyle(button);
-    await expect(buttonStyle.paddingTop).toBe('8px');
-    await expect(buttonStyle.paddingRight).toBe('16px');
-    await expect(buttonStyle.paddingBottom).toBe('8px');
-    await expect(buttonStyle.paddingLeft).toBe('16px');
     await expect(buttonStyle.backgroundColor).toBe('rgb(18, 18, 18)');
     await expect(buttonStyle.color).toBe('rgb(255, 255, 255)');
     await expect(buttonStyle.fontFamily).not.toContain('HostileHostSerif');

From c799eb6565241deed977c33826fcdd28c056f7ea Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Thu, 24 Sep 2026 11:33:38 -0500
Subject: [PATCH 20/21] test(ui): cover spacing fixes cross-browser

---
 packages/ui/package.json                      |  2 +-
 ...ersion-picker.shadow-isolation.stories.tsx | 19 ++++++++++++++-----
 .../components/missing-app-key.stories.tsx    | 15 ++++++++++++---
 .../src/styles/host-css-isolation.stories.tsx |  2 +-
 packages/ui/vitest.config.ts                  |  4 ++--
 5 files changed, 30 insertions(+), 12 deletions(-)

diff --git a/packages/ui/package.json b/packages/ui/package.json
index 1e0a941e..f27a2251 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -49,7 +49,7 @@
     "storybook": "pnpm build:css && pnpm build:storybook-css && concurrently \"node scripts/generate-i18n-resources.mjs --watch\" \"tailwindcss -i src/styles/chrome.css -o dist/chrome.css --watch\" \"tailwindcss -i src/styles/global.css -o dist/tailwind.css --watch\" \"tailwindcss -i src/styles/reader.css -o dist/bible-reader.css --watch\" \"node scripts/write-public-styles.js --watch\" \"storybook dev -p 6006\"",
     "build-storybook": "pnpm generate:i18n && pnpm build:css && pnpm build:storybook-css && storybook build",
     "test:integration": "vitest run",
-    "test:shadow-browser": "VITEST_STORY_TAG=shadow-dom vitest run --project storybook"
+    "test:shadow-browser": "VITEST_STORY_TAG=shadow-dom,cross-browser vitest run --project storybook"
   },
   "dependencies": {
     "@radix-ui/react-accordion": "1.2.12",
diff --git a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
index 4b7ac504..55c6c96e 100644
--- a/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
+++ b/packages/ui/src/components/bible-version-picker.shadow-isolation.stories.tsx
@@ -167,6 +167,17 @@ function typographySnapshot(element: HTMLElement, ownerWindow: Window) {
   };
 }
 
+async function expectLogicalPadding(
+  element: HTMLElement,
+  expected: { block: string; inline: string },
+): Promise<void> {
+  const style = getComputedStyle(element);
+  await expect(style.paddingBlockStart).toBe(expected.block);
+  await expect(style.paddingBlockEnd).toBe(expected.block);
+  await expect(style.paddingInlineStart).toBe(expected.inline);
+  await expect(style.paddingInlineEnd).toBe(expected.inline);
+}
+
 export const TopLayerEscapesClippingAndPreservesSemantics: Story = {
   render: () => (
     <div
@@ -201,11 +212,9 @@ export const TopLayerEscapesClippingAndPreservesSemantics: Story = {
       '[data-testid="version-list"] [data-slot="item"]',
       'version row not rendered',
     );
-    for (const element of [header, versionHeading, firstVersion]) {
-      const styles = getComputedStyle(element);
-      await expect(parseFloat(styles.paddingInlineStart)).toBeGreaterThan(0);
-      await expect(parseFloat(styles.paddingBlockStart)).toBeGreaterThan(0);
-    }
+    await expectLogicalPadding(header, { block: '12px', inline: '16px' });
+    await expectLogicalPadding(versionHeading, { block: '8px', inline: '16px' });
+    await expectLogicalPadding(firstVersion, { block: '12px', inline: '16px' });
     await expect(
       canvasElement.ownerDocument.body.querySelector('[data-yv-shadow-overlay-host]'),
     ).toBeNull();
diff --git a/packages/ui/src/components/missing-app-key.stories.tsx b/packages/ui/src/components/missing-app-key.stories.tsx
index b14d7092..634aafcc 100644
--- a/packages/ui/src/components/missing-app-key.stories.tsx
+++ b/packages/ui/src/components/missing-app-key.stories.tsx
@@ -46,15 +46,24 @@ export const RendersMessage: Story = {
   args: {
     theme: 'light',
   },
-  tags: ['integration'],
+  tags: ['integration', 'cross-browser'],
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
 
-    await waitFor(async () => {
-      await expect(canvas.getByRole('alert')).toBeInTheDocument();
+    const alert = await waitFor(async () => {
+      const element = canvas.getByRole('alert');
+      await expect(element).toBeInTheDocument();
+      return element;
     });
 
     await expect(canvas.getByText('Error')).toBeInTheDocument();
     await expect(canvas.getByText(/app key/)).toBeInTheDocument();
+    await waitFor(async () => {
+      const style = getComputedStyle(alert);
+      await expect(style.paddingBlockStart).toBe('16px');
+      await expect(style.paddingBlockEnd).toBe('16px');
+      await expect(style.paddingInlineStart).toBe('16px');
+      await expect(style.paddingInlineEnd).toBe('16px');
+    });
   },
 };
diff --git a/packages/ui/src/styles/host-css-isolation.stories.tsx b/packages/ui/src/styles/host-css-isolation.stories.tsx
index 8c90dbd3..be997020 100644
--- a/packages/ui/src/styles/host-css-isolation.stories.tsx
+++ b/packages/ui/src/styles/host-css-isolation.stories.tsx
@@ -98,7 +98,7 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const HostileHost: Story = {
-  tags: ['integration'],
+  tags: ['integration', 'cross-browser'],
   play: async ({ canvasElement }) => {
     await waitFor(async () => {
       const hostButton = requiredElement(document, 'host-button');
diff --git a/packages/ui/vitest.config.ts b/packages/ui/vitest.config.ts
index 06f50e23..2e5ba721 100644
--- a/packages/ui/vitest.config.ts
+++ b/packages/ui/vitest.config.ts
@@ -11,7 +11,7 @@ const browserName = process.env.VITEST_BROWSER ?? 'chromium';
 if (!['chromium', 'firefox', 'webkit'].includes(browserName)) {
   throw new Error(`Unsupported VITEST_BROWSER: ${browserName}`);
 }
-const storyTag = process.env.VITEST_STORY_TAG ?? 'integration';
+const storyTags = (process.env.VITEST_STORY_TAG ?? 'integration').split(',');
 
 export default defineConfig({
   plugins: [react()],
@@ -57,7 +57,7 @@ export default defineConfig({
             // This should match your package.json script to run Storybook
             // The --ci flag will skip prompts and not open a browser
             storybookScript: 'pnpm storybook --no-open',
-            tags: { include: [storyTag] },
+            tags: { include: storyTags },
           }),
         ],
         test: {

From 03d766170c30e57359b9038e0ecddc1c259d7931 Mon Sep 17 00:00:00 2001
From: Austin <abharms@gmail.com>
Date: Thu, 24 Sep 2026 15:42:53 -0500
Subject: [PATCH 21/21] test(ui): reuse Storybook wait helper

---
 packages/ui/src/test/storybook-dom.ts | 18 +++---------------
 1 file changed, 3 insertions(+), 15 deletions(-)

diff --git a/packages/ui/src/test/storybook-dom.ts b/packages/ui/src/test/storybook-dom.ts
index 3c912759..cd147107 100644
--- a/packages/ui/src/test/storybook-dom.ts
+++ b/packages/ui/src/test/storybook-dom.ts
@@ -1,27 +1,15 @@
+import { waitFor as storybookWaitFor } from 'storybook/test';
 import { requireShadowRoot } from './dom-stubs';
 
 interface StorybookWaitOptions {
   timeout?: number;
 }
 
-export async function waitFor<T>(
+export function waitFor<T>(
   callback: () => T | Promise<T>,
   options: StorybookWaitOptions = {},
 ): Promise<T> {
-  const timeout = options.timeout ?? 5000;
-  const deadline = Date.now() + timeout;
-  let lastError: unknown;
-
-  while (Date.now() <= deadline) {
-    try {
-      return await callback();
-    } catch (error) {
-      lastError = error;
-    }
-    await new Promise((resolve) => setTimeout(resolve, 50));
-  }
-
-  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+  return storybookWaitFor(callback, { timeout: 5000, ...options });
 }
 
 export async function waitForElement<ElementType extends Element>(