❓ Type of change

• 📖 Documentation
• 🐞 Bug fix
• 👌 Enhancement
• ✨ New feature
• 🧹 Chore
• ⚠️ Breaking change

📚 Description

The client DOM head renderer had several correctness bugs once the head re-rendered or the target document changed:

• Leaked event listeners. Handlers were re-added on every patch instead of replaced, so repeated renders stacked duplicate listeners, and they were never removed when a tag (or a bodyAttrs/window handler) was removed.
• Stale state across documents. DOM state was cached on head._dom and reused even when rendering into a different document, carrying stale element references and listeners into the new document.
• Lost mutations. Changes made inside dom:rendered / onRendered hooks were dropped instead of applied, and a re-entrant render triggered from dom:beforeRender could clobber the in-flight pass.

This binds each handler once and tracks it as a disposable side effect keyed by identity, rebuilds DOM state when the document instance changes, guards re-entrant renders, and applies hook-driven mutations in a follow-up pass. Adds regression tests for event-handler replacement/removal, document switching, render reentrancy and the onRendered follow-up render.

Review follow-ups

• SSR cleanup baseline is no longer single-use. createDomState previously deleted entry._o after seeding the class-removal baseline. Because the document-switch path can build state more than once, a second pre-rendered document could no longer strip stale htmlAttrs/bodyAttrs classes. _o is now kept intact and only read.
• Reused elements clear dropped props/content. trackCtx only applied truthy values and only registered cleanup for *Attrs. A reused (keyed) element that dropped textContent/innerHTML/class/an attribute kept the old DOM. Element content and attributes are now tracked too, with value-guarded clears so SSR-adopted or externally mutated content is never touched.

Both follow-ups have regression tests (state.test.ts baseline-across-documents, dom.test.ts reused-element clearing).

Performance & size

Two follow-up commits optimise the renderer the fixes touch, with no behaviour change (all 826 unhead tests + the Vue events test pass):

• Fewer per-render allocations (5ab4a5c9): hand the cleanup pool to _p by reference instead of spreading state._s into a fresh object every re-render, and reuse the previous render's cleanup closure for stable keys (the pattern trackEvent already uses) instead of reallocating ~one closure per tracked prop each frame. Cuts GC pressure under sustained re-rendering.
• Smaller event tracking (61e90387): store the listener side-effect as a tuple, hoist the repeated `data-${k}`, and drop a fast-path marker re-assert that can never fire once _l holds the listener. −32 B gz on the minimal client bundle; the observable data-on* markers are unchanged.

Out of scope (by design): deeper resolveTags-level caching and the core hook/dedupe/normalize perf belong with #794, which already rewrites those files. The opt-in event-renderer split (~308 B gz) would be a breaking API change and was left out.

Benchmark

Micro-benchmark of the re-render hot path (one head, ~12 tags incl. htmlAttrs/bodyAttrs with classes + a bodyAttrs event handler, forced dirty re-render each iteration; jsdom, vitest bench):

main is ~1.25x faster on this path, the expected cost of correctness: it stays fast only by re-binding listeners every render and skipping cleanup tracking, the exact leaks/staleness this PR fixes. The wall-clock gap is dominated by that listener/attribute-cleanup work, not allocations, so the perf commits above target memory churn and code size rather than this number. Absolute delta is ~3 µs per full re-render of a 12-tag head.

Summary by CodeRabbit

• Bug Fixes

  • Ensure DOM head rendering targets the correct Document, reruns when needed for pending updates, and safely clears dirty/re-entrancy state after rendering.
  • Improve isolation across multiple document instances and ensure SSR baseline attribute/class cleanup is replayed correctly.
  • Refine DOM patching and event handling: deterministic replacement/removal for script onload and bodyAttrs window listeners, and correct clearing for reused keyed elements (including attribute/class/style revert behavior).

• Tests

  • Added coverage for re-entrancy and dom:beforeRender/dom:rendered lifecycle, multi-document isolation, keyed diffing, and DOM event handler replacement/removal.