Recognize nodes from other realms via realm-safe type checks

[lizarusi]

Hi!

While using idiomorph at Walnut, we hit a bug that we've been carrying as a local patch — contributing the fix upstream.

The bug

Passing a node created in another JS realm (e.g. an iframe's contentDocument) as newContent throws:

TypeError: newContent is not iterable
    at normalizeParent (src/idiomorph.js)
    at Object.morph (src/idiomorph.js)

Repro:

const target = document.querySelector("#target");
const iframe = document.createElement("iframe");
document.body.append(iframe);
const foreign = iframe.contentDocument.createElement("button");
foreign.textContent = "Bar";
Idiomorph.morph(target, foreign); // 💥 TypeError: newContent is not iterable

Every realm has its own constructors, so cross-realm nodes fail instanceof Node in normalizeParent and fall through to the array/HTMLCollection branch, which blows up on the spread.

The crash is only the visible part. instanceof stays false for these nodes even after they are adopted into this document, so once past normalization they also silently fail every other realm-sensitive instanceof check: template content handling, id-based matching of new children (newChild instanceof Element), and syncInputValue — meaning input/option/textarea values would silently not sync from cross-realm content. The second test demonstrates that.

We hit this in production at Walnut, where we morph DOM captured from customer apps across document boundaries — we've been carrying a fix as a local patch since 0.7.2.

The fix

Replace realm-sensitive instanceof checks with tiny duck-typing helpers (nodeType / localName) — the same approach morphdom uses. The helpers carry JSDoc type predicates, so TypeScript narrows exactly like instanceof did and npm run typecheck stays green. The document.activeElement checks in the focus-preservation code keep instanceof, since the active element always belongs to this document.

First commit adds the failing tests, second commit makes them pass. There is a dedicated test per converted check — entry normalization, id-based element preservation (both the dummy-parent and SlicedParentNode paths), template content morphing, input/option/textarea value syncing, head handling, and Document normalization — and each test was verified to fail if its single check alone is reverted to instanceof. npm run typecheck, npm run format:check, and the full suite pass, with coverage at 100%.

Relates to #103 — whichever direction the newContent type-narrowing goes, cross-realm nodes currently crash rather than being handled or rejected cleanly, so this seems worth fixing today.

[myabc]

@lizarusi I'm not a maintainer - just a contributor/community member - so please take my drive-by suggestions with a grain of salt! That said - with a few fixes to the JSDocs and a guard for HTML docs - this patch has my vote!

[myabc]

Additionally, restoreFocus hardcodes document.activeElement (src/idiomorph.js:301) rather than ctx.target.ownerDocument. This would need to be fixed to fully support morphing foreign documents.

[lizarusi]

@myabc Thanks a lot for looking into this! I've applied your suggestions (the isHtmlElement namespace guard and the JSDoc types) and added tests to verify them, plus fixed restoreFocus to resolve the active element via ctx.target.ownerDocument as you pointed out.

Additionally, I decided to keep value instanceof <constructor> as a first check before duck-typing: property probes can be fooled by form named-property shadowing (e.g. a form containing <input name="nodeType">), which instanceof is immune to — duck-typing now only kicks in for nodes from other realms.