ScrollSpy: deterministic active-section detection

[mdo]

Problem

ScrollSpy chose the active section with a scroll-direction flag + a sequential offsetTop tiebreaker that mutated state while walking IntersectionObserver entries. IO delivers entries in no guaranteed order, so when several sections shared the viewport (e.g. the docs right-rail TOC) the highlight was wrong. Coarse defaults also left stale gaps, smooth scroll suppressed the URL hash, focus wasn't managed, and ids with dots/special characters threw.

Change

Detection is now IntersectionObserver-native and deterministic — no scroll-position polling and no per-frame getBoundingClientRect() sweep:

• The observer root is collapsed (via rootMargin) to a strip from the top of the scroll root down to an activation line. A small Set of currently-intersecting sections is maintained from the IO entries, and the active section is the deepest of them. Work happens only when a section crosses the line — a handful of times per page traversal, not every animation frame.
• Content gaps: when nothing crosses the line, the last activated section stays active.
• Top of page: before any section crosses the line, the first section stays active.
• Bottom of page: an invisible, aria-hidden bottom sentinel (its own observer) activates the last section even when its top never reaches the line — replacing the old scrollTop math.
• Target resolution: ids are resolved with decodeURIComponent + getElementById (scoped with contains), so dotted/colon/slash/percent-encoded ids resolve without escaping.
• Smooth-scroll settle: scrollend is now registered as a real native event (added to EventHandler), with a transient scroll-idle fallback. On a smooth-scroll click the settle restores the URL hash via history.replaceState and moves focus to the section (tabindex="-1" + focus({ preventScroll: true })). When the target needs no scroll (already there / reduced motion) it settles immediately instead of stranding the pending navigation.
• Config: new topMargin option (default 12%, accepts % or px, e.g. 96px below a sticky navbar) positions the activation line; rootMargin is an advanced override that takes precedence and is passed straight to the observer. threshold default is now [0]. The long-deprecated offset/method options are removed. A debounced resize rebuild keeps a px activation line accurate.

Issues / PRs

• Fixes SyntaxError: Failed to execute 'querySelector' on 'Element': '#div-2.1' is not a valid selector #37858, Scrollspy creates an invalid query selector #39198, Use bootstrap ScrollSpy with anchor using dots? #39248 — special-character / encoded id resolution (getElementById).
• Fixes Enabling smooth scroll option in Scroll Spy prevents url hash change #36387 — smooth scroll now restores the URL hash.
• Fixes Scrollspy: focus shift bug #40526 — focus is moved to the target section after smooth scroll.
• Supersedes Normalize selector operation in scrollspy #41726 for v6 — id escaping is no longer needed (that PR can still land for v5).
• Supersedes ScrollSpy: improve active feedback #41016 — its ratio-based selection mis-handles tall sections.

Verification

• Full unit suite green (1104), lint clean. Added/updated regression tests: deepest-of-multiple determinism, bottom-sentinel forces last, keep-last across gaps, first-at-top, encoded/malformed id resolution, custom rootMargin passthrough, resize rebuild, immediate settle when already at target, and the settle -> hash/focus behavior.
• Browser-validated against the built bundle: navbar example (top -> First, through to bottom -> Fifth, with nested menu-parent highlighting) and the docs right-rail TOC with data-bs-top-margin="96px" (continuous scroll advances cleanly through every section with nested h2/h3 highlighting); smooth-scroll click restores the hash and moves focus.

The docs right-rail TOC uses Bootstrap ScrollSpy directly, so it's fixed transitively.