From 940dfa4b9db16b6cf84b27a93586c5311879a385 Mon Sep 17 00:00:00 2001
From: Harry Brundage <harry.brundage@shopify.com>
Date: Thu, 16 Jul 2026 11:21:07 -0400
Subject: [PATCH 1/2] Fix insertBefore leaving the previous sibling pointing
 past the inserted node

ParentNode.insertBefore relinked the new child's NEXT/PREV and the reference
node's PREV, but only repointed the previous sibling's NEXT when the reference
node was the first child. Inserting before any later child therefore left the
forward sibling chain skipping the new node.

That chain is what querySelector, querySelectorAll, and firstChild/nextSibling
traversal walk, so an affected node was unreachable from every selector query and
sibling walk, while childNodes, parentNode, previousSibling, and the host mirror
all still reported it as present. The node rendered correctly on the host and was
invisible to the remote environment's own lookups, with no error raised.
replaceChild, prepend of more than one node, and ChildNode.after all route
through the same branch and were affected too.

Hoist the reference node's previous sibling and link it forward to the new child,
keeping the insert-at-front case that the old branch already handled.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../polyfill-insert-before-sibling-chain.md   |  11 +
 packages/polyfill/source/ParentNode.ts        |   6 +-
 .../polyfill/source/tests/ParentNode.test.ts  | 189 ++++++++++++++++++
 3 files changed, 204 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/polyfill-insert-before-sibling-chain.md
 create mode 100644 packages/polyfill/source/tests/ParentNode.test.ts

diff --git a/.changeset/polyfill-insert-before-sibling-chain.md b/.changeset/polyfill-insert-before-sibling-chain.md
new file mode 100644
index 00000000..48c0ee33
--- /dev/null
+++ b/.changeset/polyfill-insert-before-sibling-chain.md
@@ -0,0 +1,11 @@
+---
+'@remote-dom/polyfill': patch
+---
+
+Fix `insertBefore()` leaving the previous sibling pointing past the inserted node
+
+`ParentNode.insertBefore()` relinked the new child's `NEXT`/`PREV` and the reference node's `PREV`, but only repointed the previous sibling's `NEXT` when the reference node was the first child. Inserting before any _later_ child therefore left the forward sibling chain skipping the new node.
+
+That chain is what `querySelector()`, `querySelectorAll()`, and `firstChild`/`nextSibling` traversal walk, so an affected node was unreachable from every selector query and sibling walk — while `childNodes`, `parentNode`, `previousSibling`, and the host mirror all still reported it as present. The node rendered correctly on the host and was invisible to the remote environment's own lookups, with no error raised. `replaceChild()`, `prepend()` (of more than one node), and `ChildNode.after()` all route through the same branch and were affected too.
+
+This is easy to hit whenever a framework renders ahead of existing content — for example inserting content before an already-appended `<style>` element — where it silently breaks code as ordinary as `document.querySelector('#my-modal').showModal()`.
diff --git a/packages/polyfill/source/ParentNode.ts b/packages/polyfill/source/ParentNode.ts
index b40d0c34..d73fb543 100644
--- a/packages/polyfill/source/ParentNode.ts
+++ b/packages/polyfill/source/ParentNode.ts
@@ -121,9 +121,11 @@ export class ParentNode extends ChildNode {
       if (before.parentNode !== this) {
         throw Error('reference node is not a child of this parent');
       }
+      const prev = before[PREV];
       child[NEXT] = before;
-      child[PREV] = before[PREV];
-      if (before[PREV] === null) this[CHILD] = child;
+      child[PREV] = prev;
+      if (prev === null) this[CHILD] = child;
+      else prev[NEXT] = child;
       before[PREV] = child;
     } else {
       child[NEXT] = null;
diff --git a/packages/polyfill/source/tests/ParentNode.test.ts b/packages/polyfill/source/tests/ParentNode.test.ts
new file mode 100644
index 00000000..429a9d1f
--- /dev/null
+++ b/packages/polyfill/source/tests/ParentNode.test.ts
@@ -0,0 +1,189 @@
+import {Window} from '../index.ts';
+
+import {describe, it, expect, beforeEach} from 'vitest';
+
+/**
+ * Walks the forward sibling chain, the traversal selector queries recurse
+ * through. It is stored independently of `childNodes`, so the two can disagree.
+ */
+function siblingChain(parent: ParentNode) {
+  const names: string[] = [];
+  for (let node = parent.firstChild; node; node = node.nextSibling) {
+    names.push(node.nodeName.toLowerCase());
+  }
+  return names;
+}
+
+function childNodeNames(parent: ParentNode) {
+  return Array.from(parent.childNodes, (node) => node.nodeName.toLowerCase());
+}
+
+describe('ParentNode child list', () => {
+  beforeEach(() => {
+    const window = new Window();
+    Window.setGlobalThis(window);
+  });
+
+  describe('insertBefore', () => {
+    it('links the previous sibling to a node inserted before a non-first child', () => {
+      const first = document.createElement('first-child');
+      const last = document.createElement('last-child');
+      document.body.append(first, last);
+
+      const inserted = document.createElement('inserted-child');
+      document.body.insertBefore(inserted, last);
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'first-child',
+        'inserted-child',
+        'last-child',
+      ]);
+      expect(first.nextSibling).toBe(inserted);
+      expect(inserted.previousSibling).toBe(first);
+    });
+
+    it('inserts before the first child', () => {
+      const existing = document.createElement('existing-child');
+      document.body.appendChild(existing);
+
+      const inserted = document.createElement('inserted-child');
+      document.body.insertBefore(inserted, existing);
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'inserted-child',
+        'existing-child',
+      ]);
+      expect(document.body.firstChild).toBe(inserted);
+    });
+
+    it('keeps the sibling chain and childNodes in agreement', () => {
+      const anchor = document.createElement('anchor-child');
+      document.body.appendChild(anchor);
+
+      for (let i = 0; i < 3; i++) {
+        document.body.insertBefore(
+          document.createElement(`child-${i}`),
+          anchor,
+        );
+      }
+
+      expect(siblingChain(document.body)).toStrictEqual(
+        childNodeNames(document.body),
+      );
+      expect(siblingChain(document.body)).toStrictEqual([
+        'child-0',
+        'child-1',
+        'child-2',
+        'anchor-child',
+      ]);
+    });
+
+    it('finds a node inserted before a non-first child by selector', () => {
+      const style = document.createElement('style');
+      document.body.appendChild(style);
+
+      const modal = document.createElement('s-modal');
+      modal.setAttribute('id', 'add-zone');
+      document.body.insertBefore(modal, style);
+
+      expect(document.querySelector('s-modal#add-zone')).toBe(modal);
+      expect(document.querySelectorAll('s-modal')).toHaveLength(1);
+    });
+
+    it('inserts the children of a document fragment in order', () => {
+      const anchor = document.createElement('anchor-child');
+      document.body.appendChild(anchor);
+
+      const fragment = document.createDocumentFragment();
+      fragment.append(
+        document.createElement('fragment-first'),
+        document.createElement('fragment-last'),
+      );
+      document.body.insertBefore(fragment, anchor);
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'fragment-first',
+        'fragment-last',
+        'anchor-child',
+      ]);
+      expect(siblingChain(document.body)).toStrictEqual(
+        childNodeNames(document.body),
+      );
+    });
+
+    it('relinks a node moved from later to earlier in the same parent', () => {
+      const first = document.createElement('first-child');
+      const middle = document.createElement('middle-child');
+      const last = document.createElement('last-child');
+      document.body.append(first, middle, last);
+
+      document.body.insertBefore(last, middle);
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'first-child',
+        'last-child',
+        'middle-child',
+      ]);
+      expect(siblingChain(document.body)).toStrictEqual(
+        childNodeNames(document.body),
+      );
+    });
+  });
+
+  describe('replaceChild', () => {
+    it('keeps the chain walkable after replacing a middle child', () => {
+      const first = document.createElement('first-child');
+      const placeholder = document.createElement('placeholder-child');
+      const last = document.createElement('last-child');
+      document.body.append(first, placeholder, last);
+
+      const replacement = document.createElement('replacement-child');
+      document.body.replaceChild(replacement, placeholder);
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'first-child',
+        'replacement-child',
+        'last-child',
+      ]);
+      expect(document.querySelector('replacement-child')).toBe(replacement);
+      expect(document.querySelector('placeholder-child')).toBeNull();
+    });
+  });
+
+  describe('prepend', () => {
+    it('prepends multiple nodes ahead of an existing child', () => {
+      const existing = document.createElement('existing-child');
+      document.body.appendChild(existing);
+
+      document.body.prepend(
+        document.createElement('prepended-first'),
+        document.createElement('prepended-last'),
+      );
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'prepended-first',
+        'prepended-last',
+        'existing-child',
+      ]);
+      expect(siblingChain(document.body)).toStrictEqual(
+        childNodeNames(document.body),
+      );
+    });
+  });
+
+  describe('ChildNode.after', () => {
+    it('inserts after a non-last child', () => {
+      const first = document.createElement('first-child');
+      const last = document.createElement('last-child');
+      document.body.append(first, last);
+
+      first.after(document.createElement('inserted-child'));
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'first-child',
+        'inserted-child',
+        'last-child',
+      ]);
+    });
+  });
+});

From 7a366134ea33c29dfb32d2927a98fd58671078d5 Mon Sep 17 00:00:00 2001
From: Harry Brundage <harry.brundage@shopify.com>
Date: Thu, 16 Jul 2026 11:51:09 -0400
Subject: [PATCH 2/2] Fix ChildNode.replaceWith throwing instead of replacing
 the node

replaceWith passed its arguments to replaceChild in the wrong order.
replaceChild(newChild, oldChild) was called as parent.replaceChild(this, node),
naming the incoming node as the child to replace. That node is usually fresh and
has no parent, so the reference check rejected it and every call on a node with a
parent threw "reference node is not a child of this parent". It also read the
following sibling off the incoming node rather than off this, so the remaining
arguments had no correct insertion point to anchor to, and a call with no
arguments stringified undefined into a text node instead of removing the node.

Remove this and insert the given nodes at its position in argument order,
anchored on the first following sibling that is not itself being moved so that
replacing a node with one of its own siblings still has a reference node left.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .changeset/polyfill-replace-with.md           |   9 +
 packages/polyfill/source/ChildNode.ts         |  13 +-
 .../polyfill/source/tests/ChildNode.test.ts   | 178 ++++++++++++++++++
 3 files changed, 195 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/polyfill-replace-with.md
 create mode 100644 packages/polyfill/source/tests/ChildNode.test.ts

diff --git a/.changeset/polyfill-replace-with.md b/.changeset/polyfill-replace-with.md
new file mode 100644
index 00000000..30c7f6db
--- /dev/null
+++ b/.changeset/polyfill-replace-with.md
@@ -0,0 +1,9 @@
+---
+'@remote-dom/polyfill': patch
+---
+
+Fix `ChildNode.replaceWith()` throwing instead of replacing the node
+
+`replaceWith()` passed its arguments to `replaceChild()` in the wrong order — `replaceChild(newChild, oldChild)` was called as `parent.replaceChild(this, node)`, naming the incoming node as the child to replace. Since that node is usually fresh and has no parent, the reference check rejected it and every call threw `reference node is not a child of this parent`. It also read the following sibling off the incoming node rather than off `this`, so the remaining arguments had no correct insertion point to anchor to.
+
+The method now removes `this` and inserts the given nodes at its position, in argument order, anchored on the first following sibling that is not itself being moved. Strings become text nodes, calling it with no arguments removes the node (matching `remove()`), and a node with no parent is still left alone.
diff --git a/packages/polyfill/source/ChildNode.ts b/packages/polyfill/source/ChildNode.ts
index 6d983969..4bf81ad5 100644
--- a/packages/polyfill/source/ChildNode.ts
+++ b/packages/polyfill/source/ChildNode.ts
@@ -12,11 +12,14 @@ export class ChildNode extends Node {
   replaceWith(...nodes: (Node | string)[]) {
     const parent = this.parentNode;
     if (!parent) return;
-    const node = toNode(parent, nodes[0]);
-    const next = node[NEXT];
-    parent.replaceChild(this, node);
-    for (let i = 1; i < nodes.length; i++) {
-      parent.insertBefore(toNode(parent, nodes[i]), next);
+    // Anchor on the first following sibling that isn't itself being moved, so
+    // that replacing a node with one of its own siblings still has a reference
+    // node left to insert before.
+    let next = this[NEXT];
+    while (next && nodes.includes(next)) next = next[NEXT];
+    parent.removeChild(this);
+    for (const node of nodes) {
+      parent.insertBefore(toNode(parent, node), next);
     }
   }
 
diff --git a/packages/polyfill/source/tests/ChildNode.test.ts b/packages/polyfill/source/tests/ChildNode.test.ts
new file mode 100644
index 00000000..7b5c0050
--- /dev/null
+++ b/packages/polyfill/source/tests/ChildNode.test.ts
@@ -0,0 +1,178 @@
+import {Window} from '../index.ts';
+
+import {describe, it, expect, beforeEach} from 'vitest';
+
+function siblingChain(parent: ParentNode) {
+  const names: string[] = [];
+  for (let node = parent.firstChild; node; node = node.nextSibling) {
+    names.push(node.nodeName.toLowerCase());
+  }
+  return names;
+}
+
+describe('ChildNode', () => {
+  beforeEach(() => {
+    const window = new Window();
+    Window.setGlobalThis(window);
+  });
+
+  describe('replaceWith', () => {
+    let first: Element;
+    let target: Element;
+    let last: Element;
+
+    beforeEach(() => {
+      first = document.createElement('first-child');
+      target = document.createElement('target-child');
+      last = document.createElement('last-child');
+      document.body.append(first, target, last);
+    });
+
+    it('replaces a middle child with a single node', () => {
+      const replacement = document.createElement('replacement-child');
+
+      target.replaceWith(replacement);
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'first-child',
+        'replacement-child',
+        'last-child',
+      ]);
+      expect(replacement.parentNode).toBe(document.body);
+      expect(target.parentNode).toBeNull();
+      expect(document.querySelector('replacement-child')).toBe(replacement);
+    });
+
+    it('replaces the last child', () => {
+      const replacement = document.createElement('replacement-child');
+
+      last.replaceWith(replacement);
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'first-child',
+        'target-child',
+        'replacement-child',
+      ]);
+      expect(document.body.lastChild).toBe(replacement);
+    });
+
+    it('replaces the first child', () => {
+      const replacement = document.createElement('replacement-child');
+
+      first.replaceWith(replacement);
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'replacement-child',
+        'target-child',
+        'last-child',
+      ]);
+      expect(document.body.firstChild).toBe(replacement);
+    });
+
+    it('inserts multiple nodes in argument order', () => {
+      target.replaceWith(
+        document.createElement('replacement-one'),
+        document.createElement('replacement-two'),
+      );
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'first-child',
+        'replacement-one',
+        'replacement-two',
+        'last-child',
+      ]);
+    });
+
+    it('inserts strings as text nodes', () => {
+      target.replaceWith('replacement text');
+
+      expect(document.body.childNodes[1]!.nodeType).toBe(3);
+      expect(document.body.childNodes[1]!.textContent).toBe('replacement text');
+      expect(siblingChain(document.body)).toStrictEqual([
+        'first-child',
+        '#text',
+        'last-child',
+      ]);
+    });
+
+    it('mixes nodes and strings', () => {
+      target.replaceWith(
+        'before ',
+        document.createElement('mixed-child'),
+        ' after',
+      );
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'first-child',
+        '#text',
+        'mixed-child',
+        '#text',
+        'last-child',
+      ]);
+    });
+
+    it('removes the node when called with no arguments', () => {
+      target.replaceWith();
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'first-child',
+        'last-child',
+      ]);
+      expect(target.parentNode).toBeNull();
+    });
+
+    it('does nothing to a node without a parent', () => {
+      const detached = document.createElement('detached-child');
+
+      expect(() =>
+        detached.replaceWith(document.createElement('replacement-child')),
+      ).not.toThrow();
+      expect(detached.parentNode).toBeNull();
+    });
+
+    it('moves a node that is already in the document', () => {
+      target.replaceWith(first);
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'first-child',
+        'last-child',
+      ]);
+      expect(first.parentNode).toBe(document.body);
+      expect(target.parentNode).toBeNull();
+    });
+
+    it('replaces a node with its own next sibling', () => {
+      target.replaceWith(last);
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'first-child',
+        'last-child',
+      ]);
+      expect(target.parentNode).toBeNull();
+    });
+
+    it('replaces a node with itself', () => {
+      target.replaceWith(target);
+
+      expect(siblingChain(document.body)).toStrictEqual([
+        'first-child',
+        'target-child',
+        'last-child',
+      ]);
+      expect(target.parentNode).toBe(document.body);
+    });
+
+    it('keeps the sibling chain and childNodes in agreement', () => {
+      target.replaceWith(
+        document.createElement('replacement-one'),
+        document.createElement('replacement-two'),
+      );
+
+      expect(siblingChain(document.body)).toStrictEqual(
+        Array.from(document.body.childNodes, (node) =>
+          node.nodeName.toLowerCase(),
+        ),
+      );
+    });
+  });
+});