feat: unified For is the keyed-For engine — all modes, no seam, mapArray as the oracle

.changeset/unified-for-slot.md

@@ -0,0 +1,18 @@
+---
+"solid-js": patch
+"@solidjs/web": patch
+"@solidjs/signals": patch
+"@solidjs/universal": patch
+---
+
+Unified For: on web, keyed `<For>` is driven by one persistent engine that owns both row bookkeeping and DOM placement — an intrusive row chain updated by a prefix/suffix walk plus a middle-window pass (mapArray's own matching, duplicates included) inside an ordinary two-phase render effect, with LIS placement at commit — replacing the mapArray + reconcileArrays double pass. Structural operations (swap, reorder, insert, remove) run 1.2–7x faster across jfb and uibench; creation and clear stay at parity via flat-mode first fills for identity-keyed rows (parallel arrays; the chain materializes lazily on the first partial structural op).
+
+**Semantics are mapArray's, unchanged.** The engine implements every `For` mode itself — `keyed` default (reference identity), `keyed={false}` (positional reuse, item accessor + plain index), `keyed={fn}` (key function, item accessor + index accessor), index accessors by row arity, legal duplicates (the second occurrence of a key reuses the second old row, in mapArray's pairing order), `fallback` as an owned empty-state row, array-like subjects — so there is no engage/decline/demote seam and no classic fallback path on web. **There is one list implementation.** The engine lives in `@solidjs/signals` (`list.ts`); `mapArray` _is_ its array output (same API and contract: same values, same array identity while structurally unchanged, `[fallback]` when empty, `_parentComputed` routing for row bodies), and a plain call of a `<For>` accessor (`children()`, introspection, renderers that don't engage) returns the same. `For`'s rendered output drives the engine through a **node layer** — the only code that touches nodes — which solid-js builds over a renderer's `SlotOps`; web (`domOps`) and `@solidjs/universal` (`createRenderer` primitives) both consume it. The pre-engine mapArray is kept only as a test reference: the oracle harness compares the engine against it across every mode, dynamic rows, duplicates, fallback and hydration. Rows live under the `<For>`'s creation owner (context, boundaries, lifetime follow the source position); a row that throws during its build disposes its owner before the error rides the boundary; empty-rendering rows render zero nodes (neighbor-anchored); the list end stays contiguous past foreign trailing nodes; removes only detach nodes still under the list's parent.
+
+Rows whose top level resolves to a function — a component returning `<Show>`/`<Dynamic>`/a conditional, a memo, a fragment with accessor children — are dynamic rows: built once (owned, untracked) and resolved by the engine's own compute, tracked, exactly the `flatten` read classic's insert effect performs for them. No per-row effect, no marker nodes, so user row code never runs twice; a flip splices only that row's range, reusing positional text nodes with a `.data` write; a NotReady thrown from a row's resolution parks the built plan and the retry reuses the rows.
+
+Delivery is zero-API and zero-compiler: `For` stamps a `$for` descriptor on its accessor, the engine rides `For`'s module graph, and web's `insert` engages it with a renderer-ops singleton (`domOps`); the engine itself is platform-free (opaque `SlotNode`, every node touch through `SlotOps`). `@solidjs/universal`'s `createRenderer` engages it too, with ops built from the renderer's own primitives (`insertNode`, `removeNode`, `getNextSibling`, `replaceText`, …; nodes are non-array objects, and text data is tracked for engine-created text nodes) — no new renderer options. A `For` passed through a component's `{props.children}` engages on both platforms.
+
+Hydration: lists engage during hydration and claim the server rows themselves (whole-parent and comment-bounded holes), minting the same ids classic's mapArray owner would (`For` peeks the id via an `enableHydration()`-installed hook; mapArray gains an internal `lazy` option). Primitive rows adopt the server's positional text nodes; the fill commit reconciles against the region only on server/client mismatch and reports the repair once in dev. Nothing can demote mid-fill, so claims are never handed back. Hydration code lives in a module installed by `enableHydration()` — CSR bundles shake it.
+
+Internal: `@solidjs/signals` exports the engine (`createListEngine`, `listArray`, the node-layer types) marked `@internal` for solid-js.

packages/signals/src/index.ts

@@ -81,6 +81,30 @@ export type {
 } from "./signals.js";
 export { affects } from "./affects.js";
 export { mapArray, repeat, type Maybe } from "./map.js";
+/** @internal The list engine behind mapArray and <For>: solid-js builds a
+ * node layer over its renderer ops and drives the RENDERED output; the
+ * ARRAY output is mapArray itself. */
+export {
+  createListEngine,
+  listArray,
+  IDENTICAL as LIST_IDENTICAL,
+  firstOf,
+  lastOf,
+  nodesOf,
+  firstNodeOf,
+  lastNodeOf,
+  firstNodeFrom,
+  type ListEngine,
+  type ListMeta,
+  type ListNodeLayer,
+  type ListSlot,
+  type ListRow,
+  type ListFlatPlan,
+  type ListPlan,
+  type ListNode,
+  type Nodes as ListNodes,
+  type Leaves as ListLeaves
+} from "./list.js";
 export * from "./store/index.js";
 export {
   createLoadingBoundary,