docs(ui): reconcile shadow dom release contract

[abharms]

Summary

• reconcile Shadow DOM changesets into one coherent major-release narrative while preserving accurate independent fixes
• keep the established commitlint ADR at 0007 and adopt the automatic Shadow DOM decision as ADR 0010
• align the consumer README, compatibility contract, rollout policy, and validation plan with the supported launch contract, and remove the redundant Hostile CSS demo in favor of focused Storybook browser coverage
• keep the existing verse-selection demo's scripture, anchor, and standalone popover in one internal shadow root without adding public API or duplicate coverage

Requirement evidence

Requirement	Evidence
Release metadata describes one launch	The unreleased prototype changeset is deleted, retained collision-height behavior moves to the coordinated changeset, and stale prototype/intermediate wording is removed from release-bearing summaries.
The fixed package group still releases together	pnpm changeset status --verbose reports core, hooks, and UI at 3.0.0; no prototype summary is assigned to core or hooks.
Consumer guidance is accurate and owned once	The UI README keeps migration-critical guidance, the compatibility contract keeps detailed consequences, the rollout policy keeps decisions, and the isolation plan remains the evidence source linked by the coordinated changeset.
ADR numbering and status are correct	Commitlint remains ADR 0007; Shadow DOM is 0010-automatic-shadow-dom-style-isolation.md, titled # 10. Automatic Shadow DOM style isolation, with status Accepted; all in-repo references resolve.
Standalone verse actions stay with their anchor	The existing VerseSelection story uses the internal ShadowRootHost/ReuseShadowBoundary seam and locates the action popover from the scripture root before exercising highlight and copy.
Claims remain evidence-bounded	The unreproduced pointerdown-specific failure is not documented; the existing real-browser picker journey showed onChange is inconsistent, so the implementation retains onInput with neutral comments.

Review scope

Required outcomes

• Present one final-release changeset narrative without prototype or test-only consumer history.
• Preserve accurate independent focus and verse changesets.
• Correct ADR identity, title, status, index, and every Shadow DOM reference.
• Document the agreed Popover API, same-tree anchor, moved-child/query, and ancestor-reset consequences in their owning documents.
• Correct the stable-package claim and remove the redundant hostile-CSS Vite demo while preserving focused Storybook browser coverage.
• Preserve the existing verse-selection journey while proving same-tree composition.

Permitted support work

• Rewrite inaccurate release summaries and documentation within their established ownership.
• Use the existing internal shadow host and reuse context in the existing Storybook fixture.
• Replace unsupported picker-cause comments with evidence-bounded neutral wording.

Non-goals

• Additional event deduplication or host-reset behavior changes.
• A Popover API fallback, SDK error boundary, or cross-tree standalone popover support.
• New public Shadow DOM configuration.
• New standalone browser stories or redundant regression suites.
• Final Safari, performance, tested-SHA, or evidence-dependent claims owned by YPE-6214.

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
• pnpm build — passed
• pnpm test — passed; all 6 tasks, including UI 52 files / 590 tests
• affected Chromium Storybook journeys — 27/27 passed across verse and picker stories
• final focused verse Storybook run — 8/8 passed after review simplification
• pnpm changeset status --verbose — core, hooks, and UI resolve to 3.0.0; no prototype prose is assigned to core or hooks
• relevant relative documentation links and ADR references — resolved
• git diff --check — passed

Compatibility notes

• No public exports, component props, or production runtime behavior change.
• The only runtime-adjacent change is an existing Storybook fixture using supported internal same-tree composition.
• Accurate focus and verse fixes remain independently represented in release metadata.
• ADR 0007 keeps its established commitlint path; the branch-only Shadow DOM ADR moves to the next available number.

Review audits

• Clean-context simplification audit found no worthwhile reductions.
• The first Standards audit identified two redundant root assertions; they were removed while retaining the root-scoped, falsifiable lookup.
• Final follow-up review reconciled the remaining release-note ownership, picker-comment, and changeset-history findings; targeted verification stayed green.
• An earlier Spec pass suggested relabeling historical YPE-5952 release-gate evidence; that was rejected because YPE-5952 remains the parent coordinated-release gate while YPE-6214 owns the upcoming rerun and new evidence.

Jira

YPE-6215

Confidence Score: 5/5

This PR appears safe to merge.

Summary

This PR brings Shadow DOM release notes and consumer guidance into agreement.

• Release notes describe one coordinated Shadow DOM major release.
• Consumer guidance spells out how isolated components fit into a page.
• The Shadow DOM decision now has an accepted ADR numbered 0010.
• The verse-selection story keeps scripture and actions in one shadow root.
• The Vite example no longer shows its Hostile CSS page.
• Picker search comments now describe the native input event.

No actionable new issues or repository-rule violations were found. No previous review threads were supplied.

_{Reviews (7) · Last reviewed commit: "docs(ui): address shadow dom review feed..." · Reviewed by Greptile}

[changeset-bot]

🦋 Changeset detected

Latest commit: 1d85e9a

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

This PR includes changesets to release 4 packages

Name	Type
@youversion/platform-core	Major
@youversion/platform-react-hooks	Major
@youversion/platform-react-ui	Major
vite-react	Patch

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

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

[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-19T16:38:25.365743Z	1d85e9a	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.

[abharms]

@greptileai review

[abharms]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Delightful!

Reviewed commit: 16591b2983

ℹ️ 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".

[camrun91]

looks good. the release story, the adr move and the demo removal all check out, and i didn't see any runtime change. two non-blocking notes inline, both about release notes and docs. nothing here should hold the merge.

.changeset/coordinated-shadow-dom-rollout.md

non-blocking: with the prototype changeset gone, only ui has major-release prose. the fixed group still takes core and hooks to 3.0.0, but hooks' changelog will just say "updated dependencies", and core's will only show the fuzzy-lions-attribute minor note under a major heading. could we add a one-line major changeset for core and hooks, something like "version aligned with ui 3.0.0; no api changes in this package", so consumers aren't left wondering what broke?

[github-actions]

🚨 Breaking change detected — signoff required for v3.0.0

This PR adds a changeset declaring a major bump, which would ship all three packages as v3.0.0 (they are a fixed group in .changeset/config.json, so they version together). Merging is blocked until a repo collaborator with write access comments on this PR with all four (4) of the following:

1. The verbatim acknowledgment phrase below,
2. The precise next version (v3.0.0 or 3.0.0),
3. The release token being approved (db3d8946f275a315), and
4. A 🚀 (:rocket:) emoji.

I confirm that this is an intentional breaking change, and I have read the release procedures. I understand and have documented its impact upon release.

Copy-paste-ready reply:

I confirm that this is an intentional breaking change, and I have read the release procedures. I understand and have documented its impact upon release.

v3.0.0 db3d8946f275a315 🚀

The check re-runs automatically when a qualifying comment is posted or edited. The token covers this release's changesets and version, so ordinary pushes (review fixes, lint, docs) leave this signoff standing; adding or editing a changeset, or a change to the version, needs a fresh one.

[camrun91]

I confirm that this is an intentional breaking change, and I have read the release procedures. I understand and have documented its impact upon release.

v3.0.0 db3d8946f275a315 🚀