feat: shouldSkipChildren — leave a node's children to another renderer

[aralroca]

What

New shouldSkipChildren?: (node: Node | null) => boolean option: a node it matches keeps its subtree out of the diff entirely. The node itself still participates (attributes sync as usual), but its children are never updated, moved, pruned — or donated to a replacement element.

Why

An embedded renderer (a live React root mounted inside a host element) keeps internal references to its DOM nodes. When the diff walks into such a host:

• Text rewritten behind the renderer's back makes its later renders bail out against content they never wrote — the DOM shows the incoming markup while the renderer believes its own output is committed.
• A positional match against a different tag replaces the host and re-parents its (already-diffed, in the normal case) children into the clone. For renderer-owned children this steals nodes the renderer still tracks, and its teardown then throws NotFoundError: removeChild.

Callers that own such hosts can now declare them, diff the rest of the page, and refresh the embedded root through their own channel (e.g. serialized props on the host attribute, which still syncs).

Details

• The predicate is called with nodes from both trees, so the answer must come from the node itself (tag name, attributes), not external identity — documented in the README, index.d.ts and the option's JSDoc.
• A skipped subtree may still be streaming when the walk passes its host: its late-arriving children are not awaited, and the settled reconciliation pass does not count them as unvisited pending work.
• On a same-position replacement by a different element, the incoming subtree is applied wholesale (settled, then deep-cloned); the old children leave the document attached to their old node, so the embedded renderer can tear down cleanly.

Tests

Three new cases (run across chrome/firefox/safari like the rest of the suite): subtree kept while attributes sync, chunk boundaries inside the skipped subtree, and no child donation on replacement. Full suite: 150/150.

🤖 Generated with Claude Code