@rivetjs/cdk 0.1.0-alpha.0 → 0.1.0-alpha.1

package/_adapters/selection.d.ts

@@ -1,4 +1,4 @@
-import { SelectionManager, type FocusStrategy, type Key, type KeyboardDelegate, type MultipleSelectionState, type Orientation } from "./collections.js";
+import { SelectionManager, type Collection, type FocusStrategy, type Key, type KeyboardDelegate, type LayoutDelegate, type MultipleSelectionState, type Orientation } from "./collections.js";
 import { type PressEvent } from "./interactions.js";
 export type LinkBehavior = "action" | "selection" | "override" | "none";
 /** Static (serializable) options of a selectable collection + its items. */
@@ -27,6 +27,17 @@ export interface SelectableCollection extends MultipleSelectionState {
     readonly onAction?: ((key: Key) => void) | undefined;
     /** Sections with their own selection (RAC `MenuSection selectionMode`), by section key. */
     readonly groups?: Readonly<Record<string, MultipleSelectionState>> | undefined;
+    /**
+     * Rivet: a virtualized collection (RAC `Virtualizer`, only a window of items is rendered): the handlers navigate its
+     * built collection (an accessor) instead of the rendered DOM, page keys use the virtualizer's layout delegate, focus
+     * waits for the focused item to render and the scroll position is the virtualizer's.
+     */
+    readonly virtual?: VirtualCollection | undefined;
+}
+/** A virtualized collection's built collection and layout (see `SelectableCollection.virtual`). */
+export interface VirtualCollection {
+    readonly collection: () => Collection;
+    readonly layoutDelegate?: LayoutDelegate | undefined;
 }
 /** The manager selecting `key`: its section's own (GroupSelectionManager) or the collection's. */
 export declare function groupManager(list: SelectableCollection, root: HTMLElement, manager: SelectionManager, key: Key): SelectionManager;
@@ -40,7 +51,7 @@ export interface ItemPressHooks {
     /** Called after the item performed its action (menu: close). */
     onAction?(list: SelectableCollection, key: Key, root: HTMLElement): void;
 }
-/** Selection manager over the rendered collection under `root`. */
+/** Selection manager over the rendered collection under `root` (a virtualized collection: its built collection). */
 export declare const managerOf: (list: MultipleSelectionState, root: HTMLElement) => SelectionManager;
 /** Keyboard delegate of `root` (useSelectableList's default `ListKeyboardDelegate`). */
 export declare function delegateOf(list: SelectableCollection, root: HTMLElement, manager: SelectionManager): KeyboardDelegate;

package/_adapters/selection.js

@@ -21,8 +21,8 @@ export function groupManager(list, root, manager, key) {
     const group = section && root.contains(section) ? list.groups[section.getAttribute("data-key") ?? ""] : undefined;
     return group ? new GroupSelectionManager(manager, group) : manager;
 }
-/** Selection manager over the rendered collection under `root`. */
-export const managerOf = (list, root) => new SelectionManager(domCollection(root), list);
+/** Selection manager over the rendered collection under `root` (a virtualized collection: its built collection). */
+export const managerOf = (list, root) => new SelectionManager(list.virtual?.collection() ?? domCollection(root), list);
 /** Keyboard delegate of `root` (useSelectableList's default `ListKeyboardDelegate`). */
 export function delegateOf(list, root, manager) {
     return new ListKeyboardDelegate({
@@ -34,6 +34,7 @@ export function delegateOf(list, root, manager) {
         layout: list.options.layout ?? "stack",
         orientation: list.options.orientation ?? "vertical",
         direction: dirOf(root),
+        layoutDelegate: list.virtual?.layoutDelegate,
     });
 }
 const selectOnFocusOf = (list) => list.options.selectOnFocus ?? untrack(list.selectionBehavior) === "replace";
@@ -51,23 +52,43 @@ export function syncFocus(list, root, previous, force = false) {
     const virtual = !!list.options.shouldUseVirtualFocus;
     if (focused && key != null && (key !== previous || force)) {
         const element = getItemElement(root, key);
-        if (element) {
-            if (virtual)
-                moveVirtualFocus(element);
-            else if (document.activeElement !== element)
-                focusSafely(element);
-            const modality = getInteractionModality();
-            if (modality === "keyboard" || force) {
-                scrollIntoView(root, element);
-                if (modality !== "virtual")
-                    scrollIntoViewport(element, { containingElement: root });
-            }
-        }
+        if (element)
+            focusItem(virtual, root, element, force);
+        // Virtualized: the item renders once the virtualizer persists the new focused key (RA: useSelectableItem's
+        // effect after that render) — focus and scroll it in when it appears.
+        else if (list.virtual)
+            whenRendered(list, root, key, force);
     }
     // The focused key went away (item removed): focus the collection itself.
     if (!virtual && focused && key == null && previous != null && root.isConnected)
         focusSafely(root);
 }
+function focusItem(virtual, root, element, force) {
+    if (virtual)
+        moveVirtualFocus(element);
+    else if (document.activeElement !== element)
+        focusSafely(element);
+    const modality = getInteractionModality();
+    if (modality === "keyboard" || force) {
+        scrollIntoView(root, element);
+        if (modality !== "virtual")
+            scrollIntoViewport(element, { containingElement: root });
+    }
+}
+/** Virtualized collections: focus the item of `key` after the render that adds it (a microtask, then a few frames). */
+function whenRendered(list, root, key, force) {
+    let frames = 0;
+    const attempt = () => {
+        if (untrack(list.focusedKey) !== key || !untrack(list.isFocused))
+            return;
+        const element = getItemElement(root, key);
+        if (element)
+            focusItem(!!list.options.shouldUseVirtualFocus, root, element, force);
+        else if (frames++ < 3)
+            requestAnimationFrame(attempt);
+    };
+    queueMicrotask(attempt);
+}
 // Typeahead (useTypeSelect): `./type-select.ts` (its own module, so a closed Select trigger's typeahead does not
 // load this collection adapter).
 export { typeSelectKeyDown, _resetTypeSelect } from "./type-select.js";
@@ -593,6 +614,9 @@ export function collectionPointerOver(list, e, root = e.currentTarget) {
 const scrollPositions = new WeakMap();
 /** scroll on the collection root (remembered, restored when focus re-enters). */
 export function collectionScroll(list, e) {
+    // RA: not for a virtualized collection (the virtualizer owns its scroll position).
+    if (list.virtual)
+        return;
     scrollPositions.set(list, { top: e.currentTarget.scrollTop, left: e.currentTarget.scrollLeft });
 }
 /** focusin on the collection root: item focus → focused key; entering → first / last / selected item. */
@@ -632,7 +656,7 @@ export function collectionFocusIn(list, e, root = e.currentTarget) {
         // selection-follows-focus collection selects it, as RAC's first focus does.
         if (selectOnFocus && modality !== "pointer" && manager.isEmpty && !manager.isDisabled(manager.focusedKey))
             manager.replaceSelection(manager.focusedKey);
-        const saved = scrollPositions.get(list);
+        const saved = list.virtual ? undefined : scrollPositions.get(list);
         if (saved) {
             root.scrollTop = saved.top;
             root.scrollLeft = saved.left;

package/button/index.jsx

@@ -149,10 +149,12 @@ export function Button(inProps) {
         ref = mergeRefValues(ref, responderRef);
     }
     // RA useButton → useFocusable: FocusableContext (TooltipTrigger) props / handlers / ref reach the <button>.
-    // `isDisabled` is read only with a context (it is unused without one): an accessor read here would make the
-    // whole Button re-render on its first change on a resumed page (Calendar page buttons), dropping focus.
+    // `isDisabled` is never read here: an accessor / live one goes to the merge as an accessor (gated at event time and
+    // in the attribute binding). A read here would make the Button's enclosing region re-create it on its first change
+    // on a resumed page (Calendar page buttons dropped focus; a live `isDisabled` under a TooltipTrigger threw).
     const focusable = useContext(FocusableContext);
-    const [focusableMerged, focusableRef, focusAttrs] = mergeFocusableContext(props, focusable, !!focusable && !!read(props.isDisabled));
+    const disabledAt = focusable ? liveAt(props, "isDisabled") : undefined;
+    const [focusableMerged, focusableRef, focusAttrs] = mergeFocusableContext(props, focusable, typeof disabledAt === "function" ? disabledAt : !!disabledAt);
     props = focusableMerged;
     ref = mergeRefValues(ref, focusableRef);
     // Live props (P5): with a live prop the state / ARIA props are read through a narrow view (getters unread, read in

package/collections/components.d.ts

@@ -1,5 +1,6 @@
 import { type Context } from "@rivetjs/reactivity";
 import type { RefProp } from "@rivetjs/runtime/jsx-runtime";
+import { type RowBox } from "./row-stamps.js";
 import { BaseCollection, type CollectionNodeClass } from "./base.js";
 import type { Collection as ICollection, Key, LayoutDelegate, Node, SelectionBehavior, SelectionMode } from "./types.js";
 export type { CollectionNodeClass, CollectionNodeSpec } from "./base.js";
@@ -53,6 +54,14 @@ export declare function isCollectionProbe(): boolean;
  * popovers). Server: built on first read. Browser: rebuilt when a signal the content reads changes.
  */
 export declare function collectionOf<C extends BaseCollection<any> = BaseCollection<any>>(content: unknown, createCollection?: () => C): () => C;
+/**
+ * Rivet: the built collection of a virtualized host's `content` (RAC: a collection inside a `Virtualizer` renders
+ * from its built collection, only the visible window has parts). One `collectionOf` computed per `instance` (a plain
+ * object the host creates in its body: serialized as data, so a resumed page rebuilds the computed from `content` on
+ * its first read). Created detached from the reading owner: the first read may be a binding that re-runs (the
+ * virtualizer's rows), which would dispose a computed it owns.
+ */
+export declare function builtCollectionOf<C extends BaseCollection<any> = BaseCollection<any>>(instance: object, content: unknown, createCollection?: () => C): C;
 export interface CollectionBuilderProps<C extends BaseCollection<any>> {
     /** The collection content (plain JSX children are lazy). */
     content: unknown;
@@ -157,6 +166,11 @@ export interface CollectionRootProps {
     idScope?: Key | undefined;
     /** A set of keys for items that should always be persisted in the DOM (virtualizers). */
     persistedKeys?: Set<Key> | null | undefined;
+    /**
+     * Rivet: the host's focused key (an accessor, e.g. the selection state's `focusedKey` signal): virtualizers keep it
+     * rendered (RAC `usePersistedKeys(focusedKey)`; a signal, not a set, so it resumes without a closure over the host state).
+     */
+    focusedKey?: (() => Key | null) | undefined;
     /** The scroll container (virtualizers). */
     scrollRef?: unknown;
     renderDropIndicator?: CollectionBranchProps["renderDropIndicator"];
@@ -172,6 +186,11 @@ export interface CollectionRenderer {
     CollectionRoot: (props: CollectionRootProps) => unknown;
     /** Renders the child items of a branch. */
     CollectionBranch: (props: CollectionBranchProps) => unknown;
+    /**
+     * Rivet: the host forwards its scroll container's `scroll` events here (virtualizers: the engine follows the scroll
+     * position; RAC's useScrollView listens on `scrollRef` itself, a resumed page needs the host element's handler).
+     */
+    onScroll?: ((event: Event) => void) | undefined;
 }
 /** A built collection, an accessor of one, or null (live mode). */
 export type CollectionInput = ICollection<Node<unknown>> | (() => ICollection<Node<unknown>>) | null | undefined;
@@ -189,7 +208,23 @@ export declare function sameRender(a: Node<unknown> | null | undefined, b: Node<
  * node renders the same (`sameRender`) and re-renders it when its render inputs changed, or when `depends` (read in the
  * region) changes: a part whose content renders from its parent's value (TreeItemContent).
  */
-export declare function renderNodeAt(collection: () => ICollection<Node<unknown>> | null | undefined, key: () => Key, depends?: () => unknown): unknown;
+export declare function renderNodeAt(collection: () => ICollection<Node<unknown>> | null | undefined, key: () => Key | RowBox, depends?: () => unknown): unknown;
+/**
+ * Server baseline of a resumed For over collection keys (ROW-RERENDER): `_regionState` with the stamps of the rows the server
+ * renders (`row-stamps.ts`) when the collection is an accessor whose build read signals (a static collection never rebuilds:
+ * null), recorded with the For's region; none (no slot) for the children of a section / table row (`parentType`). Called by the server and the browser alike (one `_regionState` slot per accessor
+ * collection, so the region's other slots keep their positions); the browser gets the server's value back when it
+ * re-creates that region (adopting the rows), null otherwise.
+ */
+export declare function serverRows(collection: CollectionInput, keys: () => readonly Key[], parentType?: string | undefined): string | null;
+/**
+ * The keys of a resumed For over collection keys (`renderNodeAt` rows), given the server baseline (`serverRows`): an adopted
+ * server row keeps its key while its node renders like the server's (stamp in the baseline; then `sameRender` against the
+ * last node checked), else its key is boxed (`RowBox`, one box per key for good) — a key the adopted list does not know, so
+ * the For re-creates that row (rows read `rowKey(key())`). Rows the server did not render get a box too (created anyway).
+ * Without a baseline: `keys` itself.
+ */
+export declare function resumedKeys(collection: CollectionInput, base: string | null, keys: () => readonly Key[]): () => readonly (Key | RowBox)[];
 /** RAC `DefaultCollectionRenderer`: built collections render node by node; live mode renders content in place. */
 export declare const DefaultCollectionRenderer: CollectionRenderer;
 /** RAC `CollectionRendererContext` (Virtualizer provides its own renderer). */

package/collections/components.jsx

@@ -29,11 +29,13 @@
 // Deviation: `dependencies` is accepted and ignored (signals re-render; no item cache to invalidate).
 // Deviation: React hook names → Rivet (`useIsHidden` → `isHidden`, `usePersistedKeys` →
 //   `persistedKeys`, `useCachedChildren` → `collectionChildren`).
-import { _observer, _reobserve, _scoped, computed, createContext, provide, runWithOwner, untrack, useContext, } from "@rivetjs/reactivity";
+import { _observer, _regionState, _reobserve, _scoped, _trackReads, computed, createContext, provide, runWithOwner, untrack, useContext, } from "@rivetjs/reactivity";
 import { For, Provider } from "@rivetjs/runtime/dom";
 import { _rUnrecorded, resumableContext } from "@rivetjs/runtime/resume-format";
 import { isSlot } from "@rivetjs/runtime/slot";
 import { HiddenContext } from "./hidden.js";
+import { domRowItem } from "#server";
+import { rowKey, stampSet, stamp } from "./row-stamps.js";
 import { hasLive } from "../utils/live.jsx";
 import { mergeProps as mergeLive, splitProps } from "@rivetjs/runtime/props";
 import { BaseCollection, buildCollection, collectionNodeClass, } from "./base.js";
@@ -93,8 +95,25 @@ export function buildCollectionFrom(content, createCollection) {
     finally {
         run.o = null;
     }
-    return buildCollection(scope.specs, createCollection);
+    const keyed = typeof content === "function" || (typeof content === "object" && content !== null);
+    try {
+        const built = buildCollection(scope.specs, createCollection);
+        if (keyed)
+            (lastBuilt ??= new WeakMap()).set(content, built);
+        return built;
+    }
+    catch (error) {
+        // A rebuild between two unbatched writes (an item moved from one `items` signal to another: added to the first, not
+        // yet removed from the second) sees a key twice; RAC never builds that state (React batches the renders). Keep the
+        // content's last collection: the build read every source, so the second write rebuilds it. A first build throws.
+        const last = keyed ? lastBuilt?.get(content) : undefined;
+        if (last !== undefined && error instanceof Error && error.message.startsWith("Duplicate key "))
+            return last;
+        throw error;
+    }
 }
+/** The last collection each content built (`buildCollectionFrom`'s duplicate-key tolerance on rebuilds). */
+let lastBuilt;
 /**
  * Rivet (server): evaluate `content` in build mode registering nothing, so the collection root in it (ListBox / Menu /
  * …, `isCollectionProbe`) merges its own `id` into the `SelectableCollectionContext` `MergedId` (`contextProps`) before
@@ -158,6 +177,20 @@ export function isCollectionProbe() {
 export function collectionOf(content, createCollection) {
     return computed(() => buildCollectionFrom(content, createCollection));
 }
+let builtCollections;
+/**
+ * Rivet: the built collection of a virtualized host's `content` (RAC: a collection inside a `Virtualizer` renders
+ * from its built collection, only the visible window has parts). One `collectionOf` computed per `instance` (a plain
+ * object the host creates in its body: serialized as data, so a resumed page rebuilds the computed from `content` on
+ * its first read). Created detached from the reading owner: the first read may be a binding that re-runs (the
+ * virtualizer's rows), which would dispose a computed it owns.
+ */
+export function builtCollectionOf(instance, content, createCollection) {
+    let built = (builtCollections ??= new WeakMap()).get(instance);
+    if (!built)
+        builtCollections.set(instance, (built = runWithOwner(null, () => collectionOf(content, createCollection))));
+    return built();
+}
 /**
  * Builds a `Collection` from the `content` and passes it to `children` (RAC `CollectionBuilder`).
  * Inside another builder's build pass it only renders the content (registers into that build).
@@ -173,10 +206,68 @@ export function CollectionBuilder(props) {
 function evaluate(content) {
     if (typeof content === "function" && (isSlot(content) || content.length === 0))
         return evaluate(content());
-    if (Array.isArray(content))
+    if (Array.isArray(content)) {
+        if (!isServer && hasThunk(content)) {
+            const build = useContext(BuildContext);
+            if (build)
+                return evaluateInOrder(content, build.specs);
+        }
         return content.map(evaluate);
+    }
     return content;
 }
+// Build-pass order (browser). A children array is built eagerly: its parts register while JSX builds the array, and a
+// `{() => …}` / `<Show>` / `<For>` child (an accessor) registers only when `evaluate` calls it, after its siblings. In
+// build mode, parts return a per-spec mark (an empty comment: renders nothing; a node, so array copies — the dev
+// runtime maps component output — keep it), so the array says where each eager part's spec belongs; an accessor's
+// specs go where the accessor sits. Server: the build calls everything in document order already.
+let marks;
+/** The value a part returns in build mode: `null` on the server, a mark of its spec in the browser. */
+const buildMark = (spec) => {
+    if (isServer)
+        return null;
+    // `globalThis.document`: the compiler rejects bare browser globals in a server-rendered module (RV2001).
+    const mark = globalThis.document.createComment("");
+    (marks ??= new WeakMap()).set(mark, spec);
+    return mark;
+};
+const isThunk = (value) => typeof value === "function" && (isSlot(value) || value.length === 0);
+function hasThunk(content) {
+    for (const value of content)
+        if (isThunk(value) || (Array.isArray(value) && hasThunk(value)))
+            return true;
+    return false;
+}
+function evaluateInOrder(content, list) {
+    const listed = new Set(list);
+    const order = [];
+    const walk = (value) => {
+        if (Array.isArray(value))
+            for (const item of value)
+                walk(item);
+        else if (isThunk(value)) {
+            const start = list.length;
+            evaluate(value);
+            for (const spec of list.splice(start))
+                order.push(spec);
+        }
+        else if (value !== null && typeof value === "object") {
+            const spec = marks?.get(value);
+            if (spec && listed.has(spec))
+                order.push(spec);
+        }
+    };
+    walk(content);
+    const placed = new Set(order);
+    let at = 0;
+    for (const spec of list)
+        if (!placed.has(spec))
+            list[at++] = spec;
+    list.length = at;
+    for (const spec of order)
+        list.push(spec);
+    return null;
+}
 /**
  * Live (rendered) content of a host / branch / row, placed inside the caller's providers: slots run now; any other
  * 0-arity function — a `{() => …}` render-function child or a DOM v2 structural accessor (`<For>` / `<Show>` /
@@ -276,7 +367,7 @@ export function createLeafComponent(CollectionNodeClass, render) {
             const value = all.value ?? defaults?.value;
             // RAC passes node.props as given: `id` only when the user (or an `items` row) supplied one.
             const explicitId = resolveId(all, defaults, collectionCtx);
-            build.specs.push({
+            const spec = {
                 type: NodeClass,
                 id: explicitId ?? generatedId(build.parentKey, build.ids),
                 value: value,
@@ -286,8 +377,9 @@ export function createLeafComponent(CollectionNodeClass, render) {
                 props: rest,
                 ownProps: true,
                 render: (node) => render(withNode(all, live && !defaults, node.props, live, explicitId == null ? { value: node.value } : { id: node.key, value: node.value }), p.ref, node),
-            });
-            return null;
+            };
+            build.specs.push(spec);
+            return buildMark(spec);
         }
         const scope = useContext(CollectionScopeContext);
         if (!scope) {
@@ -337,7 +429,7 @@ export function createBranchComponent(CollectionNodeClass, render, useChildren =
             };
             build.specs.push(spec);
             provide(BuildContext, { specs: spec.children, parentKey: key, ids: { n: 0 }, run: build.run }, () => provide(CollectionItemContext, null, () => tracked(build, () => evaluate(() => useChildren(childProps(props, all, id))))));
-            return null;
+            return buildMark(spec);
         }
         const scope = useContext(CollectionScopeContext);
         const key = id ?? generatedId(scope?.parentKey, scope?.ids ?? { n: 0 });
@@ -477,23 +569,136 @@ export function renderNodeAt(collection, key, depends) {
     // of its region (a sort re-created the table header and body: focus lost) instead of keeping it like a client rebuild.
     if (isServer)
         return untrack(() => {
-            const n = collection()?.getItem(key()) ?? null;
+            const n = collection()?.getItem(rowKey(key())) ?? null;
+            // DOM-DATA servers: the row's data object (the For iterates keys), registered with the row (`domRowItem`).
+            if (n !== null)
+                domRowItem(n.value);
             return n?.render ? n.render(n) : null;
         });
-    const node = computed(() => collection()?.getItem(key()) ?? null, { equals: sameRender });
+    const node = computed(() => collection()?.getItem(rowKey(key())) ?? null, { equals: sameRender });
     return serverNow(() => {
         depends?.();
         node();
         // The current node (the cut-off computed keeps the first of equal ones; `depends` re-renders with the latest).
-        const n = untrack(() => collection()?.getItem(key()) ?? null);
+        const n = untrack(() => collection()?.getItem(rowKey(key())) ?? null);
         return n?.render ? untrack(() => n.render(n)) : null;
     });
 }
-function renderNodes(collection, parent) {
+/**
+ * Lazy collection rows (`resume.lazyRows`, LAZY-T6): a loop over container nodes — a section, a table's header / body (nodes
+ * whose children have children) — is not the lazy `For`; the rows below it are (a lazy row is one option / table row, not a
+ * whole table body). Read by the server's lazy rows only.
+ */
+function leafNodes(collection, parent) {
+    const c = resolveCollection(collection);
+    if (!c?.getChildren)
+        return true;
+    for (const n of parent ? c.getChildren(parent.key) : c) {
+        if (n.type === "content")
+            continue;
+        if (n.type === "section")
+            return false;
+        // No children (built nodes keep `firstChildKey`): no iterator per leaf (LAZY-COST-2: 1000 options ≈ 0.5 ms / render).
+        if (n.firstChildKey === null)
+            continue;
+        for (const child of c.getChildren(n.key)) {
+            for (const _ of c.getChildren(child.key))
+                return false;
+            break;
+        }
+    }
+    return true;
+}
+/**
+ * The nodes a row of `n` renders (its stamp covers them): `n`, and a section's items / a table row's cells — a nested `For`
+ * inside the row (`CollectionBranch`) that keeps no baseline of its own (`serverRows`).
+ */
+function rowNodes(c, n) {
+    const row = [n];
+    if (n.firstChildKey != null && c.getChildren)
+        for (const child of c.getChildren(n.key))
+            if (n.type === "section" || child.type === "cell")
+                row.push(child);
+    return row;
+}
+/** The stamp of a row's nodes (`row-stamps.ts`). */
+const rowStamp = (row) => stamp(row[0], row.length > 1 ? row.slice(1) : null);
+/**
+ * Server baseline of a resumed For over collection keys (ROW-RERENDER): `_regionState` with the stamps of the rows the server
+ * renders (`row-stamps.ts`) when the collection is an accessor whose build read signals (a static collection never rebuilds:
+ * null), recorded with the For's region; none (no slot) for the children of a section / table row (`parentType`). Called by the server and the browser alike (one `_regionState` slot per accessor
+ * collection, so the region's other slots keep their positions); the browser gets the server's value back when it
+ * re-creates that region (adopting the rows), null otherwise.
+ */
+export function serverRows(collection, keys, parentType) {
+    // The rows of a section / a table row: covered by the stamp of the row holding them (`rowNodes`). Decided by the
+    // parent node's type alone (the same on the server and in the browser: the `_regionState` slot is positional).
+    if (typeof collection !== "function" || parentType === "section" || parentType === "item")
+        return null;
+    return _regionState(() => {
+        if (!isServer)
+            return null;
+        return untrack(() => {
+            const c = _trackReads(collection);
+            if (!c.signals.length || !c.value)
+                return null;
+            let out = "";
+            for (const k of keys()) {
+                const n = c.value.getItem(k);
+                out += n ? rowStamp(rowNodes(c.value, n)) : stamp(null);
+            }
+            return out || null;
+        });
+    });
+}
+/**
+ * The keys of a resumed For over collection keys (`renderNodeAt` rows), given the server baseline (`serverRows`): an adopted
+ * server row keeps its key while its node renders like the server's (stamp in the baseline; then `sameRender` against the
+ * last node checked), else its key is boxed (`RowBox`, one box per key for good) — a key the adopted list does not know, so
+ * the For re-creates that row (rows read `rowKey(key())`). Rows the server did not render get a box too (created anyway).
+ * Without a baseline: `keys` itself.
+ */
+export function resumedKeys(collection, base, keys) {
+    if (base === null || isServer)
+        return keys;
+    let set = null;
+    const boxes = new Map(), 
+    // The last node (`rowNodes`: + its items / cells) found to render like the server's, per key.
+    seen = new Map();
+    return () => {
+        const list = keys(), c = resolveCollection(collection);
+        return untrack(() => {
+            set ??= stampSet(base);
+            let out = null;
+            for (let i = 0; i < list.length; i++) {
+                const k = list[i];
+                let box = boxes.get(k);
+                if (box === undefined) {
+                    const n = c?.getItem(k) ?? null;
+                    if (n === null)
+                        continue;
+                    const row = rowNodes(c, n), last = seen.get(k);
+                    // Unchanged since the last check (`sameRender`, node by node): no stamp.
+                    if (last !== undefined && last.length === row.length && row.every((x, j) => sameRender(last[j], x)))
+                        continue;
+                    if (set.has(rowStamp(row))) {
+                        seen.set(k, row);
+                        continue;
+                    }
+                    seen.delete(k);
+                    boxes.set(k, (box = { k }));
+                }
+                (out ??= list.slice())[i] = box;
+            }
+            return out ?? list;
+        });
+    };
+}
+function renderNodes(collection, parent, parentType) {
     // Rows are keyed by primitive keys (stable across rebuilds) so an adopted (resumed) row survives a
     // collection rebuild; a row re-renders only when its node's render inputs changed (`renderNodeAt`) and parts
-    // read live data by key.
-    const each = () => {
+    // read live data by key. An adopted row whose node changed since the server render is re-created (`resumedKeys`).
+    const keys = () => {
         const c = resolveCollection(collection);
         const keys = [];
         for (const n of parent ? c.getChildren(parent.key) : c)
@@ -501,7 +706,8 @@ function renderNodes(collection, parent) {
                 keys.push(n.key);
         return keys;
     };
-    return (<For each={each} by={(key) => key}>
+    const each = resumedKeys(collection, serverRows(collection, keys, parentType), keys);
+    return (<For each={each} by={(key) => key} lazy={() => leafNodes(collection, parent)}>
       {(key) => renderNodeAt(() => resolveCollection(collection), key)}
     </For>);
 }
@@ -517,8 +723,10 @@ export const DefaultCollectionRenderer = {
     },
     CollectionBranch(props) {
         const { collection, parent } = props;
-        if (collection && untrack(() => resolveCollection(collection)?.getItem(parent.key)))
-            return renderNodes(collection, parent);
+        // `parent` may be row data (`{ key }`, a resumable capture), not the node: its type comes from the collection.
+        const node = collection ? untrack(() => resolveCollection(collection)?.getItem(parent.key)) : null;
+        if (node)
+            return renderNodes(collection, parent, node.type);
         return (parent.content?.() ?? null);
     },
 };

package/collections/nodes.d.ts

@@ -1,4 +1,4 @@
-import type { Collection, Node } from "./types.js";
+import type { Collection, Key, Node } from "./types.js";
 export declare function getChildNodes<T>(node: Node<T>, collection: Collection<Node<T>>): Iterable<Node<T>>;
 export declare function getFirstItem<T>(iterable: Iterable<T>): T | undefined;
 export declare function getNthItem<T>(iterable: Iterable<T>, index: number): T | undefined;
@@ -7,3 +7,11 @@ export declare function getLastItem<T>(iterable: Iterable<T>): T | undefined;
 export declare function compareNodeOrder<T>(collection: Collection<Node<T>>, a: Node<T>, b: Node<T>): number;
 /** Number of `item` nodes, descending into sections (cached per collection). */
 export declare function getItemCount<T>(collection: Collection<Node<T>>): number;
+/**
+ * Rivet: `[aria-posinset, aria-setsize]` of the item `key` in a virtualized collection (only a window of its items is
+ * in the DOM, so the browser cannot count them): its 1-based position among the items of its section and that
+ * section's item count; top-level items count among the top-level items. Headers, separators and loaders are not
+ * counted. RA useOption / useMenuItem use `node.index + 1` (a section's header counted) of `getItemCount` (every item
+ * of every section): equal without sections, per section (role `group`) with them. Cached per committed collection.
+ */
+export declare function itemPosition<T>(collection: Collection<Node<T>>, key: Key): readonly [number, number] | undefined;

package/collections/nodes.js

@@ -79,3 +79,29 @@ export function getItemCount(collection) {
     countCache.set(collection, counter);
     return counter;
 }
+const positionCache = new WeakMap();
+/**
+ * Rivet: `[aria-posinset, aria-setsize]` of the item `key` in a virtualized collection (only a window of its items is
+ * in the DOM, so the browser cannot count them): its 1-based position among the items of its section and that
+ * section's item count; top-level items count among the top-level items. Headers, separators and loaders are not
+ * counted. RA useOption / useMenuItem use `node.index + 1` (a section's header counted) of `getItemCount` (every item
+ * of every section): equal without sections, per section (role `group`) with them. Cached per committed collection.
+ */
+export function itemPosition(collection, key) {
+    let cache = positionCache.get(collection);
+    if (!cache)
+        positionCache.set(collection, (cache = new Map()));
+    const hit = cache.get(key);
+    if (hit)
+        return hit;
+    const node = collection.getItem(key);
+    if (!node || node.type !== "item")
+        return undefined;
+    const parent = node.parentKey != null ? collection.getItem(node.parentKey) : null;
+    const keys = [];
+    for (const sibling of parent ? getChildNodes(parent, collection) : collection)
+        if (sibling.type === "item")
+            keys.push(sibling.key);
+    keys.forEach((k, i) => cache.set(k, [i + 1, keys.length]));
+    return cache.get(key);
+}

package/collections/row-stamps.d.ts

@@ -0,0 +1,17 @@
+import type { Key, Node } from "./types.js";
+/** Characters per row stamp (24 bits). */
+export declare const STAMP = 4;
+/**
+ * The row stamp of a built node: a 24-bit hash of what `sameRender` compares (type, key, text, `rendered`, props, value), as
+ * 4 characters. A section's stamp covers its child nodes too (`children`): its rows are a For the section part creates in
+ * its body (ListBoxSection), which a resumed page never re-runs, so a changed child re-creates the section row.
+ */
+export declare function stamp(n: Node<unknown> | null | undefined, children?: Iterable<Node<unknown>> | null): string;
+/** The set of stamps in a baseline string. */
+export declare function stampSet(base: string): Set<string>;
+/** A row key the browser re-created (its node changed since the server render): a fresh For key for the same collection key. */
+export interface RowBox {
+    readonly k: Key;
+}
+/** The collection key of a `For` row key (`resumedKeys` boxes the keys of rows it re-creates). */
+export declare const rowKey: (key: Key | RowBox) => Key;