A block can render inside the WordPress 7.1 editor canvas while its JavaScript still queries the outer wp-admin document. The symptom may be a missing element, broken selection overlay, keyboard shortcut that never fires, resize calculation based on the wrong viewport, or duplicate event handling after the block rerenders.
Use this for block developers and plugin maintainers whose editor code uses query selectors, mutation or resize observers, selection events, keyboard listeners, portals, popovers, canvas dimensions, or direct DOM manipulation.
Quick answer
Start from the actual rendered element. Read its `ownerDocument`, then read `ownerDocument.defaultView` for the matching window. Attach listeners and observers through a ref lifecycle that always removes them when the element or document changes. Test insertion, selection, duplication, undo, redo, mode changes, and editor navigation so stale handlers cannot survive.
What to check first
- Search source and built bundles for `document`, `window`, `document.body`, `querySelector`, `addEventListener`, `MutationObserver`, `ResizeObserver`, and portal targets.
- For each call, label whether it belongs to editor interface chrome, iframe content, the selected element, or the browser viewport.
- Replace canvas-global queries with an element ref, `ownerDocument`, and `defaultView`, while preserving null checks during mount and teardown.
- Pair every event listener and observer with cleanup, then test React rerenders, block duplication, undo, redo, editor mode switches, and post navigation.
- Use two simultaneous editor surfaces when the plugin supports them so cached global references cannot silently bind to the first document.
Diagnostic table
Use this table to keep the work practical. It connects the symptom to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Inventory global DOM access | Search source and built bundles for `document`, `window`, `document.body`, `querySelector`, `addEventListener`, `MutationObserver`, `ResizeObserver`, and portal targets. | Canvas selectors find only the intended block nodes, while admin interface selectors still resolve in the outer document. |
| Classify each document boundary | For each call, label whether it belongs to editor interface chrome, iframe content, the selected element, or the browser viewport. | A listener counter remains stable after repeated insertion, duplication, undo, redo, navigation, and editor mode changes. |
| Anchor canvas code to an element | Replace canvas-global queries with an element ref, `ownerDocument`, and `defaultView`, while preserving null checks during mount and teardown. | Keyboard, resize, selection, mutation, focus, and drag behavior works in current Chrome, Safari, and Firefox at supported widths. |
| Add deterministic cleanup | Pair every event listener and observer with cleanup, then test React rerenders, block duplication, undo, redo, editor mode switches, and post navigation. | The console has no detached-node errors, null global assumptions, cross-document type mismatch, or duplicate callback evidence. |
Why this usually happens
- JavaScript globals belong to the outer admin page even when the component DOM is rendered in the iframe.
- A callback can close over an old node or document after React replaces the component.
- Portals and popovers may intentionally belong in the parent document while selection overlays belong in the canvas.
- A listener added anonymously cannot be removed with a matching function reference.
Field notes
- Log document identity as a boolean comparison, not the full DOM or page content.
- Use a synthetic block with repeated mount and unmount controls to make listener leaks visible before production.
- Check the production bundle, not only source code, because bundled dependencies may read globals internally.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
import { useRefEffect } from '@wordpress/compose';
const setNode = useRefEffect( ( element ) => {
const doc = element.ownerDocument;
const view = doc.defaultView;
const onKeyDown = ( event ) => handleCanvasKey( event, view );
doc.addEventListener( 'keydown', onKeyDown );
return () => doc.removeEventListener( 'keydown', onKeyDown );
}, [] );
Safe fix order
Do the work in a sequence that makes each result easy to prove. Stop if a step produces new evidence that changes the incident scope.
- Inventory global DOM access
- Classify each document boundary
- Anchor canvas code to an element
- Add deterministic cleanup
- Stress-test remount and navigation
Decision rule
Use the outer global only for interface elements that are proven to live outside the iframe. Use element-owned document and window objects for canvas behavior. When a feature crosses both documents, split it into two explicit adapters and test the message or state boundary.
What to tell the client or owner
Include the failing selector or listener, expected owning document, actual owning document, mount sequence, cleanup proof, browser, WordPress build, block name, and a minimal stack trace without client content.
Production verification checklist
- Canvas selectors find only the intended block nodes, while admin interface selectors still resolve in the outer document.
- A listener counter remains stable after repeated insertion, duplication, undo, redo, navigation, and editor mode changes.
- Keyboard, resize, selection, mutation, focus, and drag behavior works in current Chrome, Safari, and Firefox at supported widths.
- The console has no detached-node errors, null global assumptions, cross-document type mismatch, or duplicate callback evidence.
Mistakes to avoid
- Do not replace every `document` reference mechanically without deciding which document owns the feature.
- Do not store the first iframe document in a module-level singleton.
- Do not attach anonymous listeners that cannot be removed during cleanup.
- Do not assume `instanceof` checks behave the same for objects created by another window.
Questions teams ask during testing
Why can `instanceof HTMLElement` fail?
DOM classes belong to a window. Use the element's `ownerDocument.defaultView` when you need a constructor from the same realm.
Should popovers use the canvas document?
Only when the visual and interaction contract places them in the canvas. Toolbar and admin chrome may intentionally live in the outer document.
Why use a ref effect?
It ties setup and cleanup to the actual element lifecycle, which is safer when the node or its document changes.
When HandL WP should help
HandL WP can isolate editor JavaScript that crosses document boundaries, produce a minimal fixture, patch listener ownership, and verify the production bundle across browsers before a WordPress 7.1 upgrade.
If this is active on a production site, fix a WordPress iframe editor regression.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references