fix(dom-overlay): hide by descent from the body, not an ancestor walk

[ivanbanov]

Containment holds a few elements out of the hiding — the topmost modal layer, its backdrop, and the layers stacked above it — and it matched them by ancestry:

for (const element of exclude) {
  if (sibling.contains(element)) return true
}

A sibling that contains a retained element was skipped whole. container on the Portal parts is public API (Dialog.Portal, container?: HTMLElement | null), so a layer can land on an app branch rather than the body — and when that branch also holds page content, the entire branch goes unhidden. The page stays reachable by pointer, keyboard, and screen reader for as long as the layer is open.

Reproduced in jsdom before the fix — a dialog open, a non-modal menu portalled into an app branch that also holds an <article>:

menu portalled to body        -> app inert: true  | menu inert: false
menu portalled inside the app -> app inert: false | page content reachable: true | menu inert: false

The fix

The bottom-up walk from target becomes a descent from document.body. The retained roots are target plus exclude. For each child of a parent:

1. the child is a root -> skip it and its subtree entirely
2. the child retains a root (contains one) -> descend into it rather than skipping the branch
3. otherwise -> the existing skip checks, then hide

Page content beside a retained layer then gets hidden individually while the layer stays reachable.

Two details are load-bearing and shouldn't be simplified back out:

• isRoot is checked before retainsRoot. Node.contains returns true for the node itself, so a root satisfies retainsRoot too; testing retainsRoot first would descend into the target and hide its own children.
• The target.contains(document.body) guard. It covers document.body and document.documentElement. The old walk no-opped there because its loop condition was node !== document.body; the descent would otherwise hide the entire page.

stack.ts needs no change — its exclude array and the isConnected guard both still apply.

Tests

Two new tests in tests/containment.test.ts, both verified to earn their place:

Test	Verification
hides page content sitting beside a layer portalled into an app branch	git checkout HEAD -- src/hide-outside.ts -> only this test fails
hides nothing for a layer at the body — there is no outside	delete the target.contains(document.body) guard -> only this test fails

261 tests pass across the repo (was 259). Every prior test passes unchanged — the rewrite is behaviour-preserving except for the branch case it fixes.

Not in scope

• Initial-focus visibility. getInitialFocus filters [disabled] and [type=hidden] but not visibility, so a field in a collapsed section wins the draw, the focus call silently no-ops, and the fallback catches it without firing the warning. Same question as the focus-trap package — to be answered once for both.
• The containment -> reachability rename. The tree still uses containment throughout. After this round no occurrence of the word means DOM Node.contains any more, so the rename is now uniform if picked up: syncContainment -> syncReachability, the SPEC section heading, the test describes.

🤖 Generated with Claude Code