Summary

• Adds lib/selector-token-index.ts: a reverse index keyed on id/class tokens that maps each token to the rules whose selectors contain it, plus a complex-fallback bucket for attribute/combinator/pseudo selectors. uBO, Brave, and Ghostery all converge on this independently.
• Refactors lib/selector-hide-rule.ts to register with the index instead of building its own MutationObserver. The token index owns a single shared createSubtreeWatcher subscription; on each added subtree it computes the triggered rule set in one walk and fans out scans only to matching rules.
• scan(root) now matches root itself (via Element.matches) in addition to its descendants. The old "rescan from document.body" workaround for top-level container insertions (HubSpot, OneTrust, Cookiebot) is no longer needed — and the comment at the former selector-hide-rule.ts:158 is gone with it.

What changes for callers

• No public API change. Each rule built via createSelectorHideRule continues to expose apply / optional teardown. The watcher-vs-no-watcher distinction is preserved.
• For watchSubtrees: true rules, the per-rule MutationObserver subscription is replaced by a single shared dispatcher. Throttle / route-change / visibility behavior all flow through the existing shared router unchanged.

Mechanics

• parseSelector strictly recognizes bare `#ident` and `.ident`. Anything else (`div`, `.a.b`, `[role="dialog"]`, `#x .y`, pseudos) lands in complex-fallback.
• findTriggeredRules(root) walks `root` + descendants once, looking up each `element.id` and `element.classList` in the indexes and union-ing `complexFallback`. Constant-time per element rather than full-doc QSA per rule.
• Document.body sweeps (router's route-change rAF) short-circuit token lookup and trigger every registered rule — walking the full body to compute triggers would defeat the purpose.
• siteRule selectors are indexed alongside `alwaysOnSelectors`. URL gating stays inside the rule's own `scan` via the existing per-URL memo; over-triggering an off-URL rule costs one no-op `scan` call against the added root.

Behavioral risk under DOM mutations

The shared MutationObserver is configured { childList: true, subtree: true } (unchanged from before this PR). What changes is what we do with each batch's added roots.

The one real regression: attribute mutations on already-inserted elements were incidentally caught by the old code because every batch's scan ran against document.body. The new dispatch path only walks added subtrees, so post-insertion id/class changes are silently missed until something underneath the renamed element is also added or removed (which would re-walk it as part of that batch).

Practical impact:

• React, Vue, Svelte, HTMX, Alpine: build nodes with full attribute state, then mount. The renamed-after-insert pattern doesn't occur. Safe.
• jQuery / vanilla JS that does $('#foo').addClass('cookie-banner') after the page renders: this is the risky pattern. At risk.
• CMP vendors (OneTrust, Cookiebot, Sourcepoint, Quantcast, Osano, Didomi) inject with the id already present. Safe.
• Chat-widget vendors (HubSpot, Intercom, Drift, Zendesk): same — id is set at insertion. Safe.

Mitigation path (follow-up, not in this PR): extend the shared MO config to { childList: true, subtree: true, attributes: true, attributeFilter: ['id', 'class'] }, and in fanOut dispatch attribute-mutation targets through the dispatcher the same way as added subtrees. AdGuard ExtendedCss takes exactly this approach. The follow-up is mechanical; flagging it here so the reviewer can decide whether it ships in this PR or the next.

Selectors that depend on ancestor combinators (e.g., .parent > .child or body > .x) behave identically: Element.matches evaluates against the live DOM context, and Element.querySelectorAll resolves the selector against the document while constraining results to the scope. None of the rules in the catalog currently use ancestor-combinator selectors, so this is theoretical, but worth noting.

Test plan

• bun run test — 1244 / 1244 pass (29 new example tests + 7 property tests for the token index)
• bun run typecheck
• bun run check (biome + eslint)
• bun run knip
• selector-token-index.test.ts covers parseSelector cases, registerRule bucket population, unregister, findTriggeredRules across token / no-token / fallback shapes, and end-to-end dispatch through the shared watcher.
• selector-token-index.property.test.ts fuzzes subtree monotonicity (`triggered(parent) ⊇ triggered(child)`), token soundness iff (rule fires iff the matching id/class is present somewhere in the subtree), and complex-fallback always-on.
• selector-hide-rule.test.ts gains coverage for scan-from-inserted-root, root-itself matching, outermost dedupe when both root and descendant qualify, dispatcher integration (token hit / miss / teardown), and siteRule registration.

🤖 Generated with Claude Code