WIP: feat!: YPE-4113

[cameronapak]

This is for demo purposes at this time.

YPE-4113 | Artifacts | Task | PR Walkthrough (alpha)

Breaking change. Consumer CSS can no longer override SDK declarations.
The migration path is in the changeset and repeated at the bottom of this
description.

What problems was I solving

A partner puts BibleTextView into their app. Their button { padding: 1rem }
reshapes our version picker trigger. Their body { font-family: Comic Sans }
rewrites our verse text. The partner sees a broken Bible experience and has no
supported way to correct it.

The cause was our own design, not an accident. SDK CSS sat in yv-sdk-* cascade
layers. CSS Cascade 5 §6.1
compares layer order before specificity, and unlayered CSS joins an implicit
final layer. A consumer button {} rule at 0,0,1 thus overrode every yv:
utility at any specificity. Raising specificity inside the layer could never
help. That choice protected the consumer from us, and it guaranteed the leak in
the other direction.

There were two leak channels, not one:

Channel	Example	Why it won
Direct match	button { padding: 1rem } matches our button	Unlayered CSS beats layered CSS at any specificity
Inheritance	body { color: green } flows into our text	The SDK declared no color, so the value was inherited

After this PR:

• A host reset, a bare element rule, Tailwind Preflight, and inherited body
  typography all leave SDK components unchanged. Measured, not assumed.
• The one remaining hole is a consumer !important rule, and it is documented
  with per-component numbers.
• Shadow DOM is recommended against, on those numbers.

Measured result. Baseline was 124 to 4,041 leaks per component. Four of the
five hostile groups now report 0 on every component. The fifth group,
!important, reports 880 leaks across 155 <button> elements. No element that
is not a <button> leaks anywhere.

What user-facing changes did I ship

• packages/ui/src/styles/global.css — SDK CSS ships in no cascade layer. The nine-layer declaration and every layer() import are gone.
• packages/ui/scripts/scope-selectors.mjs — every compiled selector gains :is([data-yv-sdk], [data-yv-sdk] *). SDK CSS cannot match DOM the SDK did not render, and inside an SDK subtree our rules beat bare element selectors.
• packages/core/src/styles/theme.css — the SDK root declares the inherited properties (font, color, line-height, letter-spacing, text-align, and the rest) plus the box model. A gate on a selector does not stop inheritance.
• profile-avatar.tsx, separator.tsx, textarea.tsx, dialog.tsx — every exported root now stamps data-yv-sdk and data-yv-theme.
• packages/ui/src/components/verse.tsx — bug fix. FootnoteContent named the gate but not a theme, so yv:bg-background stayed light whatever the caller asked for.
• docs/style-isolation-residual-leak.md — the residual-leak report, per group and per component.
• docs/adr/0005-scope-sdk-css-to-data-yv-sdk-subtrees.md — the decision record, with the three prior flips and the rejected alternatives.

How I implemented it

Five phases, in order. Each one had to move the number the phase before it
produced.

1. Measure first

Nothing was fixed here. The point was a baseline the later phases had to beat.

• packages/ui/src/test/hostile-host.ts — five groups of adversarial global CSS: preflight, bareElements, aggressiveReset, inheritedTypography, important.
• packages/ui/src/test/style-diff.ts — reads 32 computed properties on every element of an SDK subtree, once clean and once under attack, and reports the pairs that moved. Longhands only. Elements are identified by DOM path, because any identity based on styling would be circular.
• packages/ui/src/components/style-isolation.stories.tsx — 14 stories: one per exported component, plus a check that consumer token overrides still apply.
• packages/ui/.storybook/preview.tsx — a parameters.hostileHost decorator. A layout effect, so the injected tags always land after the hoisted SDK style tag. That is the source order a real consumer app produces.

2. Stamp data-yv-sdk on every exported root

The gate is worthless on a root that carries no attribute.

• scope-attribute.test.tsx asserts every public export renders a root with both attributes. A new component that forgets the attribute renders unstyled, and this test catches it at the boundary.
• dialog.tsx needed DialogOverlay stamped. It portals to document.body, outside every stamped ancestor.
• bible-version-picker.tsx and bible-reader.tsx had roots outside the ones the plan listed.

3. Declare the inherited properties

theme.css does three things:

1. :where([data-yv-sdk]) becomes [data-yv-sdk]. The old form dropped every rule inside it to 0,0,0, which was correct while SDK CSS was meant to lose.
2. The inherited set is declared on the root. It works at zero specificity for the same reason the leak worked: there is no competing declaration to lose to.
3. color: inherit on every descendant, and the box model repeated on the root itself. Both are explained under Deviations.

theme-inherited-properties.test.ts parses the file and asserts the set, so the block cannot be trimmed by accident.

4. Drop the layers and gate every selector

scope-selectors.mjs rewrites the compiled sheet after Tailwind runs:

.yv\:mt-4  →  :is([data-yv-sdk], [data-yv-sdk] *).yv\:mt-4

It uses Lightning CSS, not a regular expression and not postcss-prefix-selector:

• Its Selector visitor is a typed structural API, so it cannot corrupt an escaped class name such as .yv\:mt-4.
• @keyframes, @font-face and @property produce no Selector nodes, so the script skips them by construction rather than by an exclusion list.
• It flattens CSS nesting. bible-reader.css and @utility touch-hitbox both emit nested & rules, and a prefix on a nested selector corrupts it.
• postcss-prefix-selector@2.1.1 was tested against this repo's real output and rejected. It rewrites :host into [data-yv-sdk] :host, which can never match, and thus drops every theme variable without a warning.

Tailwind v4 has no built-in equivalent. prefix(yv) only renames classes,
@import "tailwindcss" important takes no selector argument, and the v3
important: '#app' option has no v4 replacement.

Three build gates make the guarantee real:

• The script re-parses its own output and throws on any ungated selector.
• verify-styles.js asserts dist/index.js contains the gate string, and does not contain @layer yv-sdk-. The yv-sdk- prefix is deliberate: Tailwind emits its own @layer properties block for the @property fallback, whatever our directives say.
• package.json writes the raw Tailwind output to a gitignored .cache/, so the ungated sheet can never reach dist/ and be published.

5. Record the decision and the residual

• ADR-0005 records five decisions, the three times this decision already flipped, and the rejected alternatives. Only the changelog recorded the last flip. This ADR exists to prevent a fourth flip by accident.
• The residual report names the elements a partner would actually see break, with clean and hostile values for each.

The residual, and the shadow DOM recommendation

Group	Leaks
preflight	0
bareElements	0
aggressiveReset	0
inheritedTypography	0
important	880

Zero means zero on every component, not an average. The 880 leaks come from two
declarations:

button { padding: 2rem !important }        /* reaches 155 buttons */
button { border-radius: 0 !important }     /* reaches 65 of those 155 */

Recommendation: do not adopt shadow DOM. ADR-0005 fixed the condition before
the harness produced a number: recommend shadow DOM only if the residual
includes rules that do not use !important. There is no such residual, and the
result is not close to the threshold.

The shadow DOM costs are large and are enumerated in the ADR. Radix portals
mount outside the shadow root, so FocusScope, aria-hidden and
dismissable-layer break at the boundary. React 19 <style precedence> hoisting
into a shadow root is undocumented. Tailwind Labs state that v4 does not target
shadow DOM, because v4 depends on @property. Theming moves per-root.

If a partner reports a break from a rule that does not use !important, the
harness measures that case. Add their rule to HOSTILE_GROUPS, run the suite,
and read the number.

Deviations from the plan

Compared against
.humanlayer/tasks/.../04-structure-outline-style-isolation.md.

Implemented as planned

• The hostile-host fixture, the computed-style diff harness, the 14 stories, and the Storybook decorator.
• data-yv-sdk and data-yv-theme on profile-avatar, separator, textarea, dialog, plus scope-attribute.test.tsx.
• The inherited-property block on [data-yv-sdk], with direction left out on purpose. bible-reader.css owns RTL, and text-align: start already follows direction.
• @layer removal, the Lightning CSS rewriter (the plan already required Lightning CSS after its own verification), the .d.mts types, and the unit tests.
• :where([data-yv-sdk]) to [data-yv-sdk], with the specificity comment inverted.
• The build split, .cache/ in .gitignore, the rewritten verify-styles.js, ADR-0005, the residual report, README and AGENTS updates, and the major-bump changeset.

Deviations and surprises

• The reset is wider than the plan's diff. The plan added nine inherited properties. The implementation also added color: inherit on descendants and the box model on the root. Eleven of fourteen stories stayed red without both. color on the root alone does not stop a consumer ul { color } rule, which matches an SDK element directly rather than arriving by inheritance. The universal block is [data-yv-sdk] *, which misses the marked element, and a consumer * { box-sizing } does not miss it.
• ui/button.tsx was never stamped, contrary to the phase 2 file list. It is not in src/components/index.ts, and every internal <Button> call site already sits inside a stamped ancestor. Stamping it would need an audit of all 31 call sites for the correct local theme, which is out of scope for a phase whose contract was "no visual change". Two roots the plan did not name were stamped instead: the version picker's language trigger and FootnoteContent.
• tsconfig.build.json now excludes src/test. Not in the plan. The phase 1 harness iterates NodeList, and the declaration build's lib (ES2020, DOM, no DOM.Iterable) cannot compile it. This surfaced only when phase 4 ran a full pnpm build. The directory ships no public type.
• The important assertion changed shape. The plan asserted one global "greater than zero". The real assertion is per story, conditioned on whether the component renders a <button>. BibleCard, FootnoteContent, ProfileAvatar, Separator and Textarea render none, and correctly report zero.

Additions not in the plan

• A final pass rewriting the comments and prose added by this branch to the simple-english rules (commit 89e5807). Comment and prose only. No selector, declaration or code path changed, and the full suite still passes.
• That commit also moved the inherited-properties comment in theme.css down to the block it describes. It had sat above the box-model block, which made it read as documentation for the wrong four declarations.

Items planned but not implemented

None. All five phases have corresponding code in the diff.

How to verify it

git fetch origin
git worktree add ../ype-4113-review ype-4113-spike-react-web-sdk-uidom-guarantee-consuming-app-global-css-cant-distort-bible-components-2
cd ../ype-4113-review
pnpm install

Manual testing

• Run pnpm --filter @youversion/platform-react-ui storybook, open Style Isolation, and look at any story. The component renders correctly under CSS built to break it.
• Open ConsumerTokenOverrideStillApplies. The supported customization path still works after the lockdown.
• Read docs/style-isolation-residual-leak.md and check the numbers against the console output of a story run.
• Break the gate on purpose: delete pnpm build:css:scope from the build script and run pnpm --filter @youversion/platform-react-ui build. The build fails.

Automated tests

# Full UI suite, including the 14 hostile-host browser stories
pnpm --filter @youversion/platform-react-ui build
pnpm --filter @youversion/platform-react-ui test:integration   # 43 files, 523 tests

# Core and hooks. Core needs the env vars its handler tests read.
YVP_API_HOST=api.youversion.com YVP_APP_KEY=test pnpm --filter @youversion/platform-core test    # 382 tests
YVP_API_HOST=api.youversion.com YVP_APP_KEY=test pnpm --filter @youversion/platform-react-hooks test  # 289 tests

pnpm turbo typecheck lint

All of the above pass on 89e5807.

Migration for consumers

Replace each consumer CSS override with a supported path:

1. Set --yv-* design tokens on [data-yv-sdk].
2. Use the theme prop on YouVersionProvider, or the background prop on a component.
3. Open an issue if neither path covers the case.

Rules that use !important still win. That is the one remaining hole, and
docs/style-isolation-residual-leak.md records it.

Description for the changelog

Scope all SDK CSS to data-yv-sdk subtrees, so the global CSS of a host app can no longer change SDK components.

Greptile Summary

This PR introduces a CSS isolation pipeline that scopes and hardens SDK styles, protects consumer-provided slots, and adds regression coverage and migration documentation. The watcher’s startup fix still leaves a race that can miss Tailwind’s initial output.

• Rewrites compiled selectors under data-yv-sdk boundaries and excludes data-yv-slot consumer content.
• Splits declarations by cascade behavior, converts rem lengths to px, and verifies the generated stylesheet.
• Adds component stamps, hostile-host tests, architectural decisions, and consumer migration guidance.

Confidence Score: 4/5

The PR should not merge until the scope watcher cannot miss Tailwind’s initial stylesheet write during concurrent startup.

The missing-directory crash from the previous thread is corrected, but runOnce still executes before watcher registration; an initial Tailwind write in that interval receives no event and no retry, leaving development or Storybook with missing or stale scoped CSS.

Files Needing Attention: packages/ui/scripts/scope-selectors.mjs and packages/ui/package.json

Important Files Changed

Filename	Overview
packages/ui/scripts/scope-selectors.mjs	Adds the CSS transformation and verification pipeline, but watcher registration occurs after the initial rewrite and can miss Tailwind’s first concurrent write.
packages/ui/package.json	Adds the ordered production CSS build and concurrent development watchers; the latter provide no readiness coordination.
packages/core/src/styles/theme.css	Establishes scoped inherited-property and box-model defaults while respecting consumer slot boundaries.
packages/ui/src/lib/consumer-slot.tsx	Introduces the explicit boundary used to prevent SDK selectors from styling consumer-owned content.
packages/ui/src/styles/scope-selectors.test.ts	Thoroughly exercises transformation behavior but does not cover watcher startup ordering.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[dev or storybook] --> B[Tailwind watcher]
  A --> C[Scope watcher]
  C --> D[Initial runOnce]
  D -->|raw CSS missing| E[Return without output]
  E --> F[Register fs.watch]
  B -->|write occurs before F| G[Event missed]
  G --> H[dist/tailwind.css missing or stale]

Loading

Prompt To Fix All With AI

### Issue 1
packages/ui/scripts/scope-selectors.mjs:1442
**Initial stylesheet write is missed**

When Tailwind creates `.cache/tailwind.raw.css` after the initial `runOnce` check but before `fs.watch` is registered, the write produces no observed event and has no retry, leaving `dist/tailwind.css` missing or stale until another Tailwind rebuild occurs.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (4): Last reviewed commit: "docs: record the :where() placement and ..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

Context used:

• Knowledge Base — packages/ui

[changeset-bot]

🦋 Changeset detected

Latest commit: 0117634

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

[cameronapak]

issue: Aggressive lol

[greptile-apps]

Initial stylesheet write is missed

When Tailwind creates .cache/tailwind.raw.css after the initial runOnce check but before fs.watch is registered, the write produces no observed event and has no retry, leaving dist/tailwind.css missing or stale until another Tailwind rebuild occurs.

Knowledge Base Used: packages/ui

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/ui/scripts/scope-selectors.mjs
Line: 1442

Comment:
**Initial stylesheet write is missed**

When Tailwind creates `.cache/tailwind.raw.css` after the initial `runOnce` check but before `fs.watch` is registered, the write produces no observed event and has no retry, leaving `dist/tailwind.css` missing or stale until another Tailwind rebuild occurs.

**Knowledge Base Used:** [packages/ui](https://app.greptile.com/youversion/-/custom-context/knowledge-base/youversion/platform-sdk-react/-/docs/ui-package.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.