feat(ui): isolate Bible reader (YPE-5951)

[abharms]

Summary

• give BibleReader.Root one automatic open, client-only Shadow DOM boundary
• keep reader-owned content, toolbar, search, scripture, pickers, settings, avatar, verse actions, and auth dialogs in that root without accidental nested automatic roots
• preserve intentional consumer-created nested roots while documenting that arbitrary reader children now lose page-CSS and document-query access
• adapt the full reader/search Storybook suites to traverse the public root, add focused SSR/hydration, hostile-CSS, ownership, overlay, and cross-browser evidence, and retain detailed behavior tests at the existing reuse seam
• record the YPE-5952 release handoff and add an empty changeset so this ticket cannot release independently

Jira: YPE-5951

Builds on merged #431 (YPE-5950).

Requirement evidence

Requirement	Evidence
One open client-only reader root	Focused SSR/hydration coverage asserts one exact empty server host, exact-host reuse, an accessible open root, no light-DOM content, and no recoverable hydration errors.
Reader-owned composition avoids nested roots	Structural coverage checks scripture, toolbar pickers, open settings, direct search, and the signed-in avatar; focused stories assert verse-action, sign-in, and permission dialogs belong to the reader root.
Consumer composition contract	A consumer child relocates into the root and disappears from document-rooted queries; hostile page CSS cannot style it. An intentionally isolated consumer child retains its nested root.
Existing behavior remains intact	Existing detailed unit suites continue at the reuse seam. All 23 integration-tagged reader and 8 integration-tagged search stories now traverse the real public root and cover scrolling, selection, footnotes, settings, auth menu, controlled navigation, loading/error states, and search journeys.
Search	SearchAndReturn covers toolbar open, result navigation, dismissal, reopening, and focus restoration. Focused unit assertions cover direct composition and host-owned callback mode.
Reader overlays	Reader-specific verse-action and both highlight-auth branches remain shadow-local and preserve Escape dismissal, teardown, and focus restoration without repeating shared-host permutations.
Layout and first paint	Hostile CSS, constrained geometry, theme, interface/scripture direction, and 18px typography are asserted. The accepted empty-host first paint, Vite page shell/scroller review, and qualitative performance review are recorded.
Cross-browser	The five focused reader/search journeys pass Chromium, Firefox, and Playwright WebKit.
Coordinated release	Consumer-breaking DOM/CSS/query impacts are assigned to YPE-5952; YPE-6040 remains a release blocker; the changeset is intentionally empty.

Review scope

Required outcomes

• make BibleReader.Root the sole automatic reader boundary
• keep all reader-owned composition and overlays in that boundary without accidental nested roots
• preserve reader/search behavior and the existing public interface
• document arbitrary-child DOM/CSS/query changes for YPE-5952
• provide focused SSR/hydration, Chromium, Firefox, and Playwright WebKit evidence
• avoid an independent partial release

Permitted support work

• existing private boundary/reuse plumbing
• shadow-aware test and Storybook query helpers
• the shadow-local search autofocus correction exposed by the new boundary
• focused regression/browser evidence, compatibility docs, and an empty changeset

Non-goals

• new public props, callbacks, refs, exports, or Shadow DOM configuration
• reader/search/picker/settings/overlay redesign
• repeating exhaustive shared-host or component behavior permutations
• YPE-6040 event deduplication
• a benchmark framework, native Safari claim, or real assistive-technology claim
• the YPE-5952 coordinated release itself

Please treat a finding as blocking only when it identifies an unmet in-scope requirement, a documented repository-standard violation in added or modified code, or a concrete regression or defect caused or worsened by this diff. Label other valid improvements as non-blocking follow-ups.

Verification

• pnpm lint — passed
• pnpm typecheck — passed (6/6 workspaces)
• pnpm --filter @youversion/platform-react-ui build — passed, including entries, exports, styles, and declarations
• pnpm --filter vite-react build — passed
• complete UI unit suite — 632/632 passed
• reader Storybook integration set — 23/23 passed in Chromium
• search Storybook integration set — 8/8 passed in Chromium
• focused ticket matrix — 5/5 passed independently in Chromium, Firefox, and Playwright WebKit
• bounded combined UI gate — 733/733 passed with four workers and a 10-second timeout
• exact package integration script rerun — all 31 integration-tagged reader/search stories passed; one unchanged search unit timed out under combined contention and immediately passed 1/1 in isolation (4.377s)
• Prettier and git diff --check — passed
• clean-context simplification audit — implementation and evidence judged appropriately minimal; stale wording and redundant assertions removed
• final independent audits — Spec: no missing requirements/scope creep/incorrect implementation; Compatibility: no regression; Standards: implementation clean, with only pre-existing legacy-story style observations outside this ticket's behavioral changes

Existing Radix accessibility development warnings, MSW fixture warnings, and the Vite chunk-size advisory remain non-failing.

Compatibility and release notes

• BibleReader.Root server output is now an empty host; reader content mounts in its open root after the client effect.
• Arbitrary Root children move into that root, so document selectors and global CSS no longer reach them. React context and callbacks remain in the same React tree.
• Reader-owned isolated components reuse the reader root; a consumer deliberately inserting another isolated public component may still create a nested root.
• Open-root traversal, native event retargeting, cross-tree form/ARIA limits, and the known YPE-6040 ancestor React-event duplication follow the package rollout contract.
• This branch must not publish independently. YPE-5952 owns coordinated consumer documentation/release, and YPE-6040 must land before that release.

Confidence Score: 5/5

The PR appears safe to merge into its feature branch; the coordinated release remains separate.

Summary

BibleReader.Root gains one open, client-only Shadow DOM boundary. Reader-owned controls and dialogs reuse it, while deliberately isolated consumer children can keep their own roots.

• Changes since the previous review only clarify documentation and organize evidence references.
• Previous focus-restoration, private-API, search-navigation, and search-lifecycle concerns remain addressed. All supplied threads are unnumbered, so they receive no numbered classifications.
• abharms documents the empty-host first paint as accepted. The known ancestor React-event duplication is deferred to YPE-6040 and remains a coordinated-release blocker, not new work for this PR.
• The empty changeset preserves the coordinated release boundary.

Greptile automatically discovered a related ticket that helped explain the purpose of this PR: isolate the reader without adding public configuration or publishing a partial rollout.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  App[Consumer app] --> Host[BibleReader.Root empty server host]
  Host --> Root[Open shadow root after client mount]
  Root --> Content[Scripture and verse actions]
  Root --> Toolbar[Toolbar and reader-owned pickers]
  Root --> Dialogs[Search, settings, and auth dialogs]
  Root --> Children[Consumer children]
  Children --> Nested[Deliberately isolated child may keep its own root]

Loading

_{Reviews (18) · Last reviewed commit: "docs: align reader isolation evidence (Y..." · Reviewed by Greptile}

[changeset-bot]

🦋 Changeset detected

Latest commit: 740875b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-07T14:24:56.995129Z	740875b	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ddb92e2227

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d645b58265

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d3576d9afe

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 83f0aa9318

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 45d3d256f6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 23389a83f1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cameronapak]

Review

YPE-5951

Summary

Standards: 0 must-fix. Spec: 0 must-fix. Primary concern: none.

Review evidence

• Scope: reviewed pinned revision 740875b, Jira requirements, full merge-base diff, surrounding implementation, tests, stories, documentation, and resolved review threads.
• Method: independent Standards, Spec, and Correctness passes; traced SSR/hydration, reader-owned composition, intentional nesting, search navigation, overlay ownership, focus restoration, public API, and coordinated-release boundaries.

Behavior or check	Method / command	Result	Evidence source
Reader root and hydration	Source trace plus focused test inspection	Exact empty SSR host, host reuse, no light-DOM content, and no accidental owned roots are asserted	Coordinator review
Search and overlay behavior	Source and browser-story trace	Opening, navigation, dismissal, teardown, and focus restoration are covered through the public root	Coordinator review
Build and tests	GitHub checks at pinned HEAD	Test, Type Check, Build, Integration Tests, Firefox, and WebKit passed	CI

• Limits: local reruns did not execute because the detached checkout lacked built workspace-package links and the orb lacked the matching Playwright browser binary. Native Safari and real assistive-technology validation are explicitly outside this ticket; YPE-6040 remains a coordinated-release blocker.
• CI and bot review: all required checks passed; all existing review threads are resolved.
• Event: APPROVE.

Written by Code Reviewer bot on behalf of Cam.

[cameronapak]

praise: Asserting the exact empty server markup, host identity after hydration, and absence of nested reader-owned hosts makes the new boundary contract unusually hard to regress.

For Agents: focused boundary evidence

This test checks the observable SSR and hydration contract rather than only verifying that content eventually renders. It also distinguishes accidental SDK-owned nesting from intentional consumer-created nesting in the adjacent case.

Written by Code Reviewer bot on behalf of Cam.