Arm clientOnly's swap without an owner so sibling hydration ids stay aligned

A hydrated clientOnly desynced DOM bookkeeping for every FOLLOWING sibling:
the client half armed its post-settle swap with onSettled, which registers a
tracked effect — a non-transparent owner, and every such owner consumes one
of the component's child ids at creation. The server half's only owner is the
fallback mirror memo, so the client ran one id ahead: a sibling created after
the clientOnly derived its hydration id one slot past the server's (_hk=30
server, key 40 asked), its template claim missed the registry, and insert
tracked a freshly-cloned phantom node that was never inserted (insertExpression
skips while hydrating). The DOM looked correct — the unclaimed server node
just stayed put — until the sibling's first post-hydration re-render
reconciled against the detached phantom and inserted the new content beside
the orphaned server node instead of replacing it. First surfaced as duplicated
nodes after an HMR hot-swap of a component following a clientOnly; any
signal-driven element swap in a following sibling hits it.

The swap is now armed through sharedConfig.onHydrationEnd — the ownerless
"all hydration complete" channel (waits for pending streamed boundaries,
microtask-fires when already done) — so clientOnly consumes exactly one child
id on both sides. New parity-harness scenario client-only-sibling-update pins
the contract: a resolving clientOnly followed by an element-swapping hole,
asserting the post-settle update REPLACES (both loaded and streamed modes).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

.changeset/client-only-sibling-id-drift.md

@@ -0,0 +1,5 @@
+---
+"@solidjs/web": patch
+---
+
+Fix hydrated `clientOnly` desyncing DOM bookkeeping for following siblings. The client half's post-settle swap was armed with `onSettled`, which registers a tracked effect — an id-consuming owner the server half (whose only owner is the fallback mirror memo) never mints. Every sibling created after a hydrated `clientOnly` therefore derived its hydration id one slot past the server's, its template claim missed the registry, and `insert` tracked a never-inserted phantom node: the sibling's first post-hydration re-render reconciled against the phantom and inserted the new content beside the orphaned server node instead of replacing it (first surfaced as duplicated nodes after an HMR hot-swap of a component following a `clientOnly`). The swap is now armed through `sharedConfig.onHydrationEnd` — the ownerless "all hydration complete" channel — so `clientOnly` consumes exactly one child id on both sides.

packages/solid-web/src/index.ts

@@ -18,7 +18,6 @@ import {
   createRoot,
   createSignal,
   getOwner,
-  onSettled,
   runWithOwner,
   untrack,
   omit,
@@ -495,21 +494,28 @@ export function clientOnly<T extends Component<any>>(
     // fallback must render DURING the walk (mounted=false branch) to adopt
     // that DOM, and only the post-settle swap is deferred.
     const [mounted, setMounted] = createSignal(!sharedConfig.hydrating);
-    // The gate memo must be the component's FIRST id-consuming child so the
+    // The gate memo must be the component's ONLY id-consuming child so the
     // fallback's elements derive the same hydration ids as under the server
-    // half's mirror memo and get claimed instead of duplicated. onSettled
-    // creates a tracked effect (an id-consuming owner), so it registers
-    // AFTER the memo.
+    // half's mirror memo and get claimed instead of duplicated.
     const gate = createMemo(
       () => (
         (Comp = comp()),
         (m = mounted()),
         untrack(() => (Comp && m ? Comp(rest) : props.fallback))
       )
     ) as unknown as JSX.Element;
-    onSettled(() => {
-      setMounted(true);
-    });
+    // The swap trigger must NOT hold an owner: onSettled registers a tracked
+    // effect, and every non-transparent owner consumes one of the component's
+    // child ids — an id the server half (whose only owner is the mirror memo)
+    // never mints. That shifted the hydration ids of every sibling AFTER a
+    // hydrated clientOnly by one slot, so their template claims missed the
+    // registry and insert tracked never-inserted phantom nodes: the sibling's
+    // first post-hydration re-render then reconciled against the phantom and
+    // inserted beside the orphaned server node instead of replacing it.
+    // onHydrationEnd is the ownerless "all hydration complete" channel
+    // (waits for pending streamed boundaries; microtask-fires if already
+    // done) — exactly the gate's semantics, and it consumes nothing.
+    sharedConfig.onHydrationEnd!(() => setMounted(true));
     return gate;
   };
 }

packages/solid-web/test/harness/__artifacts__/client-only-sibling-update.json

@@ -0,0 +1,5 @@
+{
+  "name": "client-only-sibling-update",
+  "shell": "<div _hk=0><span>lead </span><!--$--><button _hk=10>fb</button><!--/--><!--$--><em _hk=30>one</em><!--/--><span> tail</span></div>",
+  "rest": ""
+}

packages/solid-web/test/harness/scenarios.tsx

@@ -649,6 +649,31 @@ function ClientOnlyElementFallback() {
   );
 }
 
+// ---------------------------------------------------------------------------
+// clientOnly whose module RESOLVES, followed by a reactive element hole. The
+// post-settle swap (fallback → widget) must not desync insert bookkeeping for
+// siblings AFTER the clientOnly: when the sibling's hole later flips its
+// element, insert must REPLACE the old element (single node), not leave it
+// orphaned in place and append a fresh copy beside it. Found via a refresh
+// hot-swap of a component following a hydrated clientOnly (the duplicated
+// node surfaced there first), but any signal-driven element swap hits it.
+const ResolvingWidget = clientOnly(() =>
+  Promise.resolve({ default: (_props: {}) => <b>widget</b> })
+);
+let setSiblingSwap: (v: boolean) => void;
+function ClientOnlySiblingUpdate() {
+  const [sw, setSw] = createSignal(true);
+  setSiblingSwap = setSw;
+  return (
+    <div>
+      <span>lead </span>
+      <ResolvingWidget fallback={<button>fb</button>} />
+      {sw() ? <em>one</em> : <q>two</q>}
+      <span> tail</span>
+    </div>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // A <Loading> whose fragment settles AFTER hydration completes (#2964). The
 // boundary renders behind an async gate with NO boundary above it — the
@@ -924,6 +949,16 @@ export const scenarios: Scenario[] = [
     expectedText: "lead fb tail",
     stableSelector: "div, span, button"
   },
+  {
+    name: "client-only-sibling-update",
+    App: ClientOnlySiblingUpdate,
+    async: true,
+    expectedText: "lead widgetone tail",
+    serverText: "lead fbone tail",
+    update: () => setSiblingSwap(false),
+    expectedTextAfterUpdate: "lead widgettwo tail",
+    stableSelector: "div, span"
+  },
   {
     name: "late-boundary-after-done",
     App: LateBoundaryAfterDone,