test(ui): validate Shadow DOM consumer compatibility (YPE-5436)

[abharms]

Summary

• add three self-explaining Chromium Storybook integration journeys for consumer behavior across SDK shadow boundaries
• document the supported, constrained, and unsupported contracts for forms, labels, ARIA references, events, refs, automation, and nested roots
• feed the validated contract and limitations into the Shadow DOM rollout plan for YPE-5356
• keep overlay ownership under YPE-5355 and make no production runtime changes

Requirement evidence

Jira acceptance area	Evidence
Form association and serialization	The form story proves the isolated textarea has no owner form and is absent from form.elements and FormData
External label behavior	The form story proves label.control is null and clicking the external label does not focus the internal textarea
Cross-root ARIA references	The form story preserves the attributes while Chromium reports empty reflected aria-labelledby and aria-describedby relationships
Event behavior	The event story proves native host retargeting, the composed path, and exact React target/currentTarget identities
Forwarded refs	The event story proves the ref is null through the consumer's first layout effect and later resolves to the exact internal button
Query and automation behavior	The stories distinguish outer queries from open-root traversal and separately await root attachment and internal rendering
Nested roots	The nested story proves recursive traversal and retargeting at both boundaries
Contract and limitations	docs/shadow-dom-consumer-compatibility.md classifies every scenario and records browser, accessibility, timing, and rollout constraints

Review scope

Required scope:

• executable browser evidence for the YPE-5436 consumer-compatibility matrix
• accurate documentation of supported, constrained, and unsupported patterns
• actionable rollout input for YPE-5356

Supporting scope:

• the Shadow DOM isolation-plan links and evidence-status updates
• an intentional empty changeset for the test/docs-only change

Non-goals:

• production component fixes or public API changes
• nested/concurrent overlay behavior owned by YPE-5355
• package-wide guarantees beyond the representative components and Chromium evidence named in the contract

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.

Validation

• pnpm --filter @youversion/platform-react-ui exec vitest run --project storybook src/components/consumer-compatibility.shadow-isolation.stories.tsx — 3/3 passed in Chromium
• pnpm --filter @youversion/platform-react-ui typecheck — passed
• pnpm lint — passed
• pnpm turbo build --force — passed (4/4 tasks)
• git diff --check — passed
• pnpm test — core 432/432 and hooks 318/318 passed; the final UI run passed 538/539 and hit the existing 5-second timeout in bible-reader-controlled.test.tsx. That unchanged test passed in the earlier full-suite retry, where UI was 539/539.
• final independent Standards, Spec, and Compatibility audits at 9d4c1b6 — 0 required findings; one non-blocking helper-consistency suggestion

Compatibility and limitations

• no production module, public barrel, package entry point, JS bundle, or declaration surface changes
• DOM selector APIs do not cross shadow boundaries and need traversal after attachment and rendering; Playwright locators pierce open roots by default, except for XPath locators
• external form ownership, label resolution, and ID-based ARIA relationships do not cross the tested boundary
• browser evidence is Chromium-specific and does not replace assistive-technology validation
• overlay stacking, inertness, dismissal, and restoration remain owned by YPE-5355

Jira

YPE-5436

Greptile Summary

This test-and-documentation-only PR records Chromium evidence for consumer behavior across SDK Shadow DOM boundaries and feeds the resulting constraints into the rollout plan.

• Adds three Storybook integration journeys covering forms and external relationships, event/ref/query behavior, and nested roots.
• Documents supported, constrained, and unsupported consumer patterns.
• Updates the isolation plan with compatibility evidence and rollout gates.
• Adds an intentionally empty changeset without changing production runtime behavior.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx	Adds representative Chromium journeys whose assertions align with the documented Shadow DOM boundaries and component behavior.
docs/shadow-dom-consumer-compatibility.md	Clearly scopes the compatibility contract to representative components and Chromium evidence while recording rollout limitations.
docs/shadow-dom-isolation-plan.md	Integrates the new consumer evidence into the research handoff, audit checklist, and rollout sequence.
.changeset/flat-shadows-report.md	Adds the intentional empty changeset appropriate for a test-and-documentation-only change.

_{Reviews (5): Last reviewed commit: "test(ui): remove instructional copy asse..." | Re-trigger Greptile}

[changeset-bot]

🦋 Changeset detected

Latest commit: 3b8563e

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-09-03T16:23:34.206688Z	3b8563e	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: 9d4c1b6c6c

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

Jira ticket: YPE-5436

Summary

Standards: 1 must-fix. Worst: the play functions check scenario titles, not the shadow contract.

Spec: 0 must-fix on this SHA. Worst: none.

CI: pass.

For Agents: pin and CI

• Pin HEAD: 2730e57b7ca12c3892e6ad3b39f073edcc194e6f
• Base: main
• Event: REQUEST_CHANGES. Walks back APPROVE 5097118767. Standards must-fix landed after that approve.
• Review bot: Greptile 5/5 (last reviewed 2730e57). Codex P2 automation locators resolved (2eef188). Do not reopen.
• CI: Build, Bundle Size, Integration Tests, Lint, Lint Commit Messages, Lint PR Title, Locale Ownership, Test, Type Check, i18n Check, Require Changeset pass. Publish coverage badges skipped. Greptile Review pass.
• Same h2 copy asserts also at lines 310 and 363 in packages/ui/src/components/consumer-compatibility.shadow-isolation.stories.tsx. One inline covers all three.

By Code Reviewer bot, sent on behalf of Cam.

[cameronapak]

issue: The play functions check the scenario titles. The test standard says to check behavior, not instructional copy. Remove these three title checks. Keep the form, label, ARIA, event, ref, and query checks.

For Agents: h2 copy asserts

docs/testing.md: Assert behavior / stable contracts / roles — not i18n prose or instructional copy.

packages/ui/AGENTS.md: Assert roles/behavior, not localized copy blobs.

void expect(
  await waitForElement<HTMLHeadingElement>(canvasElement, 'h2', 'scenario title not rendered'),
).toHaveTextContent('Forms, labels, and descriptions');

Same pattern at lines 310 (Events, refs, and test queries) and 363 (Nested shadow roots). Sibling YouVersionAuthButton.shadow-isolation.stories.tsx does not assert instructional copy.

By Code Reviewer bot, sent on behalf of Cam.