fix: restore For hydration id parity at source position (#3161)

rc.4's patch-mode list seam made For's mapArray creation lazy (created
on first read so an engaged driver never builds it), but hydration ids
mint at CREATION time and the server spends the list's id scope at
For's source position. Deferred creation ran at insert's hole
evaluation — after later siblings had claimed their template keys — so
every hydration key after a <For> shifted and the siblings hydrated
detached (dead buttons; clean at rc.3). A hydrating For now creates
the map eagerly at source position; outside hydration the laziness
stands. Adds the issue's fragment shape to the parity harness.

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

Author: ryansolid

.changeset/for-hydration-id-parity.md

@@ -0,0 +1,5 @@
+---
+"solid-js": patch
+---
+
+Fix `<For>` followed by siblings desyncing hydration (#3161, rc.4 regression). The patch-mode list seam made `For`'s `mapArray` creation lazy, but hydration ids mint at creation time — deferring to first read spent the list's id scope after later siblings had already claimed their template keys, shifting every hydration key after the list and leaving the siblings detached (dead buttons). A hydrating `For` now creates its map eagerly at source position, restoring rc.3 id parity; outside hydration the lazy creation stands.

packages/solid/src/client/flow.ts

@@ -8,7 +8,7 @@ import {
   getOwner,
   runWithOwner
 } from "@solidjs/signals";
-import { createErrorBoundary, createLoadingBoundary } from "./hydration.js";
+import { createErrorBoundary, createLoadingBoundary, sharedConfig } from "./hydration.js";
 import type { Accessor, RevealOrder } from "@solidjs/signals";
 export type { RevealOrder };
 import type { Element as SolidElement } from "../types.js";
@@ -98,13 +98,22 @@ export function For<T extends readonly any[], U extends SolidElement>(props: {
   // path, created lazily under the component's owner on first read.
   const owner = getOwner();
   let mapped: (() => any) | undefined;
-  const list = () => {
-    if (mapped === undefined)
-      mapped = runWithOwner(owner, () =>
-        mapArray(() => props.each, props.children as any, options as any)
-      ) as () => any;
-    return mapped();
-  };
+  const create = () =>
+    runWithOwner(owner, () =>
+      mapArray(() => props.each, props.children as any, options as any)
+    ) as () => any;
+  // Hydration id parity (#3161): hydration ids mint at CREATION time, and
+  // the server spends the list's id slot at For's source position — so a
+  // hydrating client must create the map HERE, not on first read. Deferred
+  // creation ran at insert's hole evaluation, AFTER later siblings had
+  // already claimed their template keys, shifting every hydration id after
+  // the list (the siblings hydrated detached: dead buttons). Outside
+  // hydration the laziness stands — it is the driver seam's point: an
+  // engaged list never builds the mapArray at all. (A driver-ENGAGED
+  // hydration does not read this accessor either; driveList claims rows
+  // positionally through their own _hk keys.)
+  if (sharedConfig.hydrating) mapped = create();
+  const list = () => (mapped ?? (mapped = create()))();
   if (props.keyed !== false && !("fallback" in props) && props.children.length < 2)
     // `keyed` rides along so the driver implements the DECLARED identity
     // semantics (reference vs key fn) — see driveList's identity ruling.

packages/web/test/harness/__artifacts__/for-then-siblings.json

@@ -0,0 +1,5 @@
+{
+  "name": "for-then-siblings",
+  "shell": "<div _hk=000 class=\"row\">row <!--$-->1<!--/--></div><div _hk=010 class=\"row\">row <!--$-->2<!--/--></div><button _hk=2 id=\"bump\">bump</button><pre _hk=3 id=\"after\">count: <!--$-->0<!--/--></pre>",
+  "rest": ""
+}

packages/web/test/harness/scenarios.tsx

@@ -198,6 +198,24 @@ function ForList() {
   );
 }
 
+// ---------------------------------------------------------------------------
+// 8b. For followed by static siblings in a top-level fragment (#3161): the
+// rc.4 regression — server spends top-level id slots on the rows and gives
+// the siblings the next ones; the rc.4 client asked for the siblings at 0/1,
+// so everything after the list hydrated detached (dead buttons).
+let bumpAfterFor!: () => void;
+function ForThenSiblings() {
+  const [count, setCount] = createSignal(0);
+  bumpAfterFor = () => setCount(c => c + 1);
+  return (
+    <>
+      <For each={[{ id: 1 }, { id: 2 }]}>{row => <div class="row">row {row.id}</div>}</For>
+      <button id="bump">bump</button>
+      <pre id="after">count: {count()}</pre>
+    </>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // 9. Spread with children in the spread object
 function SpreadChildren() {
@@ -1558,6 +1576,14 @@ export const scenarios: Scenario[] = [
     expectedTextAfterUpdate: "abcd",
     stableSelector: "ul"
   },
+  {
+    name: "for-then-siblings",
+    App: ForThenSiblings,
+    expectedText: "row 1row 2bumpcount: 0",
+    update: () => bumpAfterFor(),
+    expectedTextAfterUpdate: "row 1row 2bumpcount: 1",
+    stableSelector: "button, pre"
+  },
   {
     name: "spread-children",
     App: SpreadChildren,