Interactivity API: Lazy hydration of interactive islands, with an idle-time fallback - #81249

Closes #58225

Relates to: PR #58284 — "Interactivity API: Defer hydration until node is scrolled near the viewport" (@westonruter ). This is an updated, rebased-on-trunk version of that work, incorporating the maintainer discussion (notably @luisherranz's request for an idle-CPU fallback) and fixes for regressions found along the way.

I was not able to edit #58284 directly, so just ported those changes to trunk and added idle hydration and tests. I dont know how to, so feel free to add attribution to whoever should have it (I see @westonruter, @felixarntz, @luisherranz. @sirreal). I removed @sirreal's scroll-to-bottom edits to the wp-each directive test, as they were no longer necessary after my improvements.

The problem

Today, @wordpress/interactivity hydrates every interactive island at DOMContentLoaded. On pages with many blocks below the fold, that means running hydration JS (and firing data-wp-init / data-wp-watch callbacks) for content the user may never scroll to — contributing to slow initial load on long pages (feeds, archives, long-form posts).

What this does

Defers hydration of each interactive island until it is near the viewport, and guarantees the rest are hydrated when the CPU is idle:

• An IntersectionObserver (rootMargin: one viewport height, top and bottom) hydrates each island as it approaches the viewport.
• A one-shot idle-time sweep (requestIdleCallback, bounded by a timeout: 2000) hydrates everything remaining within a bounded time, guaranteeing that islands the user never scrolls to — and the router regions the router needs to diff — are hydrated even on a busy page. This also keeps the router's initialVdomPromise caching reliable (the original hang that plagued early iterations of Interactivity API: Defer hydration until node is scrolled near the viewport #58284 is gone). Implemented via the requestidlecallback npm package, already used by @wordpress/priority-queue, which provides a comprehensive polyfill for Safari.
• Router integration: the router force-hydrates all remaining islands before rendering a navigation, so its regions are always available for diffing regardless of scroll position or idle timing. Router-rendered regions are preact-rendered (fully interactive) and are never re-hydrated.

Once hydration has completed (idle sweep ran, or the observer finished all islands), hydrateAllRemaining() is a permanent no-op:

• Islands inserted into the DOM later (e.g. raw HTML) are not auto-hydrated — developers hydrate injected markup explicitly (see the companion renderElement() / renderHTML() PR Interactivity API: Add renderElement() and renderHTML() to hydrate HTML inserted into the live DOM #81190).
• The observer's "all done" detection uses a Set of observed nodes (idempotent delete) instead of a counter. We hit a flake during integration where duplicate intersection entries double-decremented the counter and prematurely disarmed the sweep; the Set makes it idempotent.
• The router caches the initial page from initialVdomPromise rather than re-running toVdom on the live DOM at module-eval time. Under lazy hydration, islands may not be hydrated yet when the router initializes, so toVdom could mark them as hydrated before hydration actually ran — a regression we hit when integrating the idle sweep with the router (the static-import race-condition failures).

Testing

• New lazy-hydration e2e spec: 5 tests, all passing, run 10+ times with zero flakes.
• Full interactivity e2e suite: 234/234 passing.
• Unit tests unaffected (this is e2e-tested behavior; the observer/sweep are browser-timing features).

Screenshots

Here's a Performance Profile for a site with 978 data-wp- attributes in the document. 6x Slowdown. Filtered/highlighted for interactivity.

Before:

After:

The bulk moved to after the Load event. Interestingly, but perhaps unsurprisingly, the processing looks a lot more fragmented and takes longer.

I commented-out splitTask and the bars get much tighter. All test pass like this - is splitTask truly needed?

Decisions for reviewers

1. timeout: 2000 — bounds how long we wait for a quiet CPU. On an idle page the sweep fires at the first idle moment (typically well under 2s); the timeout only caps the worst case (busy main thread). Do you want to increase the limit, or get rid of it altogether (waiting until whenever the main thread frees up, if ever)? I'm actually preferential to not forcing the hydration at all - hydrating elements/directives that are out of the viewport is just wasted battery life on mobile phones. The hydration will happen if they scroll and will ultimately be forced before a router navigation.

2. requestidlecallback polyfill — reused from @wordpress/priority-queue rather than a new polyfill; no-op on modern browsers. Similar to the previous point, this adds over 1KB min.gz to the bundle, which is a lot for something that we might not even need...

3. One-shot semantics — Concerns were raised in in Interactivity API: Defer hydration until node is scrolled near the viewport #58284 about how to handle html that might have been
   added outside of the iAPI. @luisherranz decided "I don’t think we should consider that scenario. If someone wants to modify the DOM and have the Interactivity API recognize those changes, they should do it through the methods provided by the Interactivity API."
   As it turns out, there's currently no such mechanism in the iAPI for doing this. As such, PR Interactivity API: renderHTML function to insert and hydrate html strings #81462 could be considered a companion to this PR, as it brings precisely these capabilities via its renderHTML() function. Of course anything there is open to discussion and change.

4. Are the two splitTask() calls that wrap toVdom() necessary? It seems to perform much better without them, and all tests pass.

Use of AI Tools

Deepseek V4 Flash via vscode