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

package/virtualizer/behaviour.js

@@ -4,18 +4,26 @@
 // Apache-2.0, © Adobe): layout + layoutOptions, persisted keys, item measurement, load more.
 // Resume: the model is plain signals + JSON + resumable functions; engine instances live only in the browser
 // (one driver per scroller element, in a lazily created WeakMap).
-import { computed, createRoot, effect, untrack } from "@rivetjs/reactivity";
+import { computed, createRoot, effect, runWithOwner, untrack } from "@rivetjs/reactivity";
 import { direction as directionOf } from "../bidi/index.js";
 import { createCollection, loaderNode } from "./collection.js";
 import { createScrollView, getScrollLeft, layoutInfoToStyle, measureItem, setScrollLeft } from "./dom.js";
+import { Layout } from "./layout.js";
 import { Rect } from "./rect.js";
 import { Size } from "./size.js";
 import { createVirtualizerState } from "./state.js";
 import { Virtualizer } from "./virtualizer-core.js";
 /** Key of the loader sentinel node the component appends when `isLoading` / `onLoadMore` are given. */
 export const LOADER_KEY = "rv-virtualizer-loader";
+/** A layout instance from a class or a factory (RAC `Virtualizer` takes a class or an instance). */
+export function createLayout(layout) {
+    const fn = layout;
+    return fn.prototype instanceof Layout ? new layout() : layout();
+}
 const read = (value) => (typeof value === "function" ? value() : value);
 function collectionOf(model) {
+    if (model.source)
+        return (model.source() ?? createCollection([], {}));
     const loading = model.isLoading === undefined && !model.onLoadMore ? null : !!read(model.isLoading ?? false);
     return createCollection(read(model.items), model.collection, loading === null ? [] : [loaderNode(LOADER_KEY, loading)]);
 }
@@ -24,8 +32,38 @@ const persistedOf = (model) => {
     const focused = model.focusedKey();
     if (focused != null)
         keys.add(focused);
+    const hostFocused = model.focus?.();
+    if (hostFocused != null)
+        keys.add(hostFocused);
+    // Collection mode: the view holding DOM focus stays until focus moves on — the focused key changes before its
+    // item renders (and before the engine sees the scroll that brings it in), and removing the focused element
+    // would blur the collection (fast keyboard navigation across the window edge).
+    if (model.focus) {
+        const active = activeViewKey(model);
+        if (active != null)
+            keys.add(active);
+    }
     return keys;
 };
+function activeViewKey(model) {
+    if (typeof document === "undefined")
+        return null;
+    const scroller = scrollerOf(model);
+    const active = document.activeElement;
+    const view = active && scroller?.contains(active) ? active.closest("[data-rv-view]") : null;
+    return view && scroller.contains(view) ? keyOfView(untrack(model.views), view.dataset.rvView) : null;
+}
+/** The view key whose `String(key)` is `text` (keys render as `data-rv-view` text), at any depth. */
+function keyOfView(views, text) {
+    for (const view of views) {
+        if (String(view.key) === text)
+            return view.key;
+        const nested = view.children.length ? keyOfView(view.children, text) : null;
+        if (nested != null)
+            return nested;
+    }
+    return null;
+}
 const sameStyle = (a, b) => {
     const ka = Object.keys(a).filter((k) => a[k] != null), kb = Object.keys(b).filter((k) => b[k] != null);
     return ka.length === kb.length && ka.every((k) => a[k] === b[k]);
@@ -85,7 +123,7 @@ const sizeOfContent = (size) => ({ width: size.width, height: size.height });
 export function initialWindow(model) {
     return untrack(() => {
         const collection = collectionOf(model);
-        const layout = model.layout();
+        const layout = createLayout(model.layout);
         const virtualizer = new Virtualizer({
             collection,
             layout,
@@ -95,7 +133,7 @@ export function initialWindow(model) {
         const views = virtualizer.render({
             layout,
             collection,
-            persistedKeys: new Set(model.persistedKeys),
+            persistedKeys: persistedOf(model),
             visibleRect: new Rect(0, 0, width, height),
             size: new Size(width, height),
             invalidationContext: model.layoutOptions != null ? { layoutOptions: model.layoutOptions } : {},
@@ -106,6 +144,12 @@ export function initialWindow(model) {
     });
 }
 let drivers;
+/** The scroll container of `model`: the host's `scrollRef` (collection mode), else the element with `model.id`. */
+function scrollerOf(model) {
+    if (typeof document === "undefined")
+        return null;
+    return (model.scrollRef ? model.scrollRef() : document.getElementById(model.id)) ?? null;
+}
 const viewElement = (root, key) => {
     for (const el of root.querySelectorAll("[data-rv-view]"))
         if (el.dataset.rvView === String(key))
@@ -114,16 +158,24 @@ const viewElement = (root, key) => {
 };
 /** The browser driver of `model` (created on first use: engine, scroll view, measurement). */
 export function driverOf(model, element) {
-    const el = (element ?? (typeof document === "undefined" ? null : document.getElementById(model.id)));
-    if (!el)
+    const el = (element ?? scrollerOf(model));
+    // Not in the document yet (a client render's first pass): no size to start from.
+    if (!el || !el.isConnected)
         return null;
     drivers ??= new WeakMap();
     const existing = drivers.get(el);
     if (existing)
         return existing;
+    // Detached from the caller's owner: `createRoot` attaches to the current owner, and the first caller may be the
+    // rows' `For` binding (`visibleViews` on a resumed page's first projection), which disposes its children on its
+    // next run — the cached driver then kept dead effects and an items change no longer reached the engine
+    // (cdk-docs `virtualizer-items`, cold scroll then filter, 2026-10-19). The driver lives with its element.
+    return runWithOwner(null, () => createDriver(model, el));
+}
+function createDriver(model, el) {
     const dir = () => model.dir ?? directionOf(el);
     const collection = computed(() => collectionOf(model));
-    const layout = untrack(() => model.layout());
+    const layout = untrack(() => createLayout(model.layout));
     let state;
     const scrollView = createScrollView(el, {
         contentSize: () => untrack(() => state?.contentSize() ?? new Size(model.contentSize().width, model.contentSize().height)),
@@ -216,23 +268,80 @@ export function driverOf(model, element) {
     });
     return driver;
 }
-// The driver's projection effect: detached from any component owner (the driver outlives region re-creation).
+// The driver's projection effect: its own root (created under the detached driver, so it outlives region re-creation).
 function computedEffect(fn) {
     createRoot(() => effect(fn));
 }
 /** Rows of the model: the server window, or (browser) the driver's projection; reads `items` for reactivity. */
 export function visibleViews(model) {
-    if (typeof model.items === "function")
+    if (model.source) {
+        // Collection mode: a rebuilt collection or a focus move (persisted key) starts the driver on a resumed page.
+        model.source();
+        model.focus?.();
+    }
+    else if (typeof model.items === "function")
         model.items();
     if (typeof model.isLoading === "function")
         model.isLoading();
     if (typeof document !== "undefined")
-        untrack(() => driverOf(model));
+        untrack(() => driverOf(model) ?? (model.source && startWhenMounted(model)));
     return model.views();
 }
+let mounting;
+/**
+ * Collection mode, client render: the host element exists but is not in the document during its first pass. Start
+ * the engine once it is (RAC measures the scroll view on mount); the server window stays until then.
+ */
+function startWhenMounted(model) {
+    if ((mounting ??= new WeakSet()).has(model) || !scrollerOf(model))
+        return null;
+    mounting.add(model);
+    queueMicrotask(() => {
+        mounting.delete(model);
+        untrack(() => driverOf(model));
+    });
+    return null;
+}
 /** Keys of `views`: the rows' `For` items. Keys keep their identity across windows, so resumed server rows are
  * adopted and kept (a `For` re-creates an adopted row whose item changed; view descriptors change on every move). */
 export const viewKeys = (views) => views.map((view) => view.key);
+const byLayoutOrder = (a, b) => a.y - b.y || a.x - b.x;
+/** Keys in layout order (top to bottom, then start to end); the engine's reusable views come in recycling order. */
+export const orderedViewKeys = (views) => views
+    .slice()
+    .sort(byLayoutOrder)
+    .map((view) => view.key);
+/** `rowOrder` parent of the root views. */
+export const ROOT_VIEW = {};
+let orders;
+/**
+ * The keyed rows' order: layout order (top to bottom) — except while DOM focus is inside the collection, when kept
+ * keys keep their DOM order and new ones go last. A keyed list moves (detaches) a kept row to reorder it, and a
+ * detached focused option / cell loses focus (keyboard navigation across the window edge inserts rows before the
+ * focused one). Positions are absolute: DOM order is not visual order; options carry `aria-posinset`, rows
+ * `aria-rowindex` (RAC renders in the engine's recycling order).
+ */
+export function rowOrder(model, parent, views) {
+    const next = orderedViewKeys(views);
+    if (typeof document === "undefined")
+        return next;
+    const byParent = (orders ??= new WeakMap()).get(model) ?? new Map();
+    orders.set(model, byParent);
+    const prev = byParent.get(parent);
+    const scroller = model.scrollRef?.();
+    if (prev && scroller?.contains(document.activeElement)) {
+        const present = new Set(next);
+        const kept = prev.filter((key) => present.has(key));
+        const known = new Set(kept);
+        for (const key of next)
+            if (!known.has(key))
+                kept.push(key);
+        byParent.set(parent, kept);
+        return kept;
+    }
+    byParent.set(parent, next);
+    return next;
+}
 let indexes;
 let last;
 const seenOf = (model) => {
@@ -259,6 +368,19 @@ export function viewOf(model, views, key) {
     seen.set(key, view);
     return view;
 }
+let trees;
+/**
+ * Collection mode: the child views of the view with key `parentKey` (a host part's `CollectionBranch`: section items,
+ * table header rows / columns, body rows, cells), from the whole projected tree; `[]` when it is not rendered.
+ */
+export function childViews(model, parentKey) {
+    const views = model.views();
+    let tree = (trees ??= new WeakMap()).get(views);
+    if (!tree)
+        trees.set(views, (tree = flatten(views)));
+    return (tree.get(parentKey)?.children ?? EMPTY);
+}
+const EMPTY = [];
 /** Scroll handler of the scroller: drive the engine, load more near the end, then the caller's `onScroll`. */
 export function virtualizerScroll(model, event) {
     const el = event.currentTarget;

package/virtualizer/collection-renderer.d.ts

@@ -0,0 +1,62 @@
+import { type CollectionBranchProps, type CollectionRenderer, type CollectionRootProps } from "../collections/components.jsx";
+import type { Key } from "../collections/types.js";
+import { type LayoutInput, type VirtualizerModel } from "./behaviour.js";
+import { Rect } from "./rect.js";
+import { Size } from "./size.js";
+import type { Direction } from "./types.js";
+/** What the renderer's functions capture (plain data + the root's model, set when the host renders its root). */
+export interface VirtualizerLink<O = unknown> {
+    layout: LayoutInput<O>;
+    layoutOptions: O | undefined;
+    initialSize: {
+        width: number;
+        height: number;
+    };
+    dir: Direction | undefined;
+    /** The model of the host's `CollectionRoot` (one collection per Virtualizer). */
+    model: VirtualizerModel<unknown, O> | null;
+}
+/**
+ * The virtualized `CollectionRenderer` of `link` (one per link). Not read from `CollectionRendererContext` below the
+ * host: a resumed page re-creates a part's branch (a binding re-run) without the server's providers, where the
+ * context is the default renderer; the renderer object resumes from `link` instead.
+ */
+export declare function rendererOf(link: VirtualizerLink<any>): CollectionRenderer;
+/** The scroll handler hosts forward their scroll container's `scroll` events to (the engine starts on the first). */
+export declare function virtualizerLinkScroll(link: VirtualizerLink<any>, event: Event): void;
+/** RAC: the layout is the collection's layout delegate (keyboard Page Up / Down, range selection). */
+export declare function layoutRect(link: VirtualizerLink<any>, key: Key): Rect | null;
+export declare function layoutVisibleRect(link: VirtualizerLink<any>): Rect;
+export declare function layoutContentSize(link: VirtualizerLink<any>): Size;
+/** `CollectionRoot` of the virtualizer renderer: the sized content element and the root views. */
+export declare function VirtualizerRoot(props: {
+    link: VirtualizerLink<any>;
+    root: CollectionRootProps;
+}): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/** `CollectionBranch` of the virtualizer renderer: the rendered child views of `parentKey`'s view. */
+export declare function VirtualizerBranch(props: {
+    link: VirtualizerLink<any>;
+    branch: CollectionBranchProps;
+}): unknown;
+/**
+ * RAC `Virtualizer` for a collection component: wraps one `ListBox` / `GridList` / `Menu` / `Tree` / `Table` and renders its collection with
+ * `layout` — only the views in the visible rect (plus overscan and the focused item) are in the DOM. The component's
+ * own element is the scroll container (give it a height and `overflow: auto`).
+ */
+export interface CollectionVirtualizerProps<O> {
+    /** The collection component (`<ListBox>`, `<GridList>`, `<Menu>`, `<Tree>`, `<Table>`). */
+    children: unknown;
+    /** Layout class (`ListLayout`, `TableLayout`, `GridLayout`, `WaterfallLayout`) or factory (`() => new ListLayout()`). */
+    layout: LayoutInput<O>;
+    /** Options for the layout (JSON: `{ rowHeight: 48 }`). */
+    layoutOptions?: O;
+    /** Rivet: viewport size of the server-rendered window: the scroll container's client size (inside the borders, padding included; a resumed page keeps it until its first interaction). Default 800 x 600. */
+    initialSize?: {
+        width: number;
+        height: number;
+    };
+    /** Rivet: text direction of view positions (`left` / `right`); default: logical `inset-inline-start`. */
+    dir?: Direction;
+}
+/** Provides the virtualized `CollectionRenderer` (layout = layout delegate) to its child collection. */
+export declare function CollectionVirtualizer<O = unknown>(props: CollectionVirtualizerProps<O>): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/virtualizer/collection-renderer.jsx

@@ -0,0 +1,190 @@
+// `<CollectionVirtualizer>`: the react-aria-components `Virtualizer` (src/Virtualizer.tsx: the
+// `CollectionRenderer` with `CollectionRoot` / `CollectionBranch` over useVirtualizerState + useScrollView, and
+// VirtualizerItem / useVirtualizerItem; React Spectrum, Apache-2.0, © Adobe) for the cdk collection components:
+// `<CollectionVirtualizer layout={ListLayout}><ListBox …/></CollectionVirtualizer>`, `<CollectionVirtualizer layout={TableLayout}><Table …/></CollectionVirtualizer>`.
+// Hosts: ListBox (+ sections), GridList (ListLayout / GridLayout), Menu, Tree (flattened rows), Table.
+// A separate component from the standalone `<Virtualizer items>` (`./virtualizer.tsx`) so items users (Masonry) ship none of this.
+// Rivet:
+// - The host (ListBox, GridList, Menu, Tree, Table) builds its collection and passes an accessor of it to `CollectionRoot` with its
+//   scroll container (`scrollRef`, the host element) and its focused key (`focusedKey`, persisted); the engine
+//   is the standalone component's driver (`./behaviour.ts`): the server renders the first window at `initialSize`,
+//   the browser starts the engine on the first scroll (the host forwards its `scroll` events to `onScroll`), focus
+//   move (a persisted key) or layout delegate call (keyboard Page Up / Down).
+// - Every view renders in a wrapper `div[role=presentation]` (VirtualizerItem: `data-rv-view`, `data-rv-type`,
+//   absolute / sticky position from the layout); the node's part renders inside it (`node.render(node)`) with this
+//   renderer provided, so a part rendering its children (`CollectionBranch`: sections, table rows / cells) gets
+//   the child views of its own view.
+// - Resume: the renderer object's functions capture only `link` (layout factory, options, the root's model);
+//   the model holds signals, the host's collection accessor, its focused key signal and its scroll ref.
+// Deviations: no drop indicators (DnD); no window scrolling; rows are keyed by collection key (no DOM recycling
+// across items, as the standalone component); a layout instance is not accepted (a class or a factory: the
+// instance would be serialized).
+import { computed, signal, untrack } from "@rivetjs/reactivity";
+import { For, Provider } from "@rivetjs/runtime/dom";
+import { CollectionRendererContext, DefaultCollectionRenderer, resumedKeys, sameRender, serverRows, } from "../collections/components.jsx";
+import { rowKey } from "../collections/row-stamps.js";
+import { childViews, contentStyle, driverOf, initialWindow, ROOT_VIEW, rowOrder, viewOf, visibleViews, } from "./behaviour.js";
+import { Rect } from "./rect.js";
+import { Size } from "./size.js";
+const engineOf = (link) => (link.model ? (driverOf(link.model)?.state.virtualizer ?? null) : null);
+let renderers;
+/**
+ * The virtualized `CollectionRenderer` of `link` (one per link). Not read from `CollectionRendererContext` below the
+ * host: a resumed page re-creates a part's branch (a binding re-run) without the server's providers, where the
+ * context is the default renderer; the renderer object resumes from `link` instead.
+ */
+export function rendererOf(link) {
+    let renderer = (renderers ??= new WeakMap()).get(link);
+    if (!renderer)
+        renderers.set(link, (renderer = VirtualizerRenderer(link)));
+    return renderer;
+}
+/** A PascalCase factory: its object-literal arrows are resumable closures over `link` only. */
+function VirtualizerRenderer(link) {
+    return {
+        isVirtualized: true,
+        // RAC: the layout is the collection's layout delegate (keyboard Page Up / Down, range selection).
+        layoutDelegate: {
+            getItemRect: (key) => layoutRect(link, key),
+            getVisibleRect: () => layoutVisibleRect(link),
+            getContentSize: () => layoutContentSize(link),
+        },
+        CollectionRoot: (root) => <VirtualizerRoot link={link} root={root}/>,
+        CollectionBranch: (branch) => <VirtualizerBranch link={link} branch={branch}/>,
+        onScroll: (event) => virtualizerLinkScroll(link, event),
+    };
+}
+/** The scroll handler hosts forward their scroll container's `scroll` events to (the engine starts on the first). */
+export function virtualizerLinkScroll(link, event) {
+    const model = link.model;
+    if (!model)
+        return;
+    const driver = driverOf(model, event.currentTarget);
+    driver?.scrollView.onScroll(event);
+}
+/** RAC: the layout is the collection's layout delegate (keyboard Page Up / Down, range selection). */
+export function layoutRect(link, key) {
+    return engineOf(link)?.layout.getLayoutInfo(key)?.rect ?? null;
+}
+export function layoutVisibleRect(link) {
+    return engineOf(link)?.visibleRect ?? new Rect();
+}
+export function layoutContentSize(link) {
+    return engineOf(link)?.layout.getContentSize() ?? new Size();
+}
+const isServer = typeof document === "undefined";
+/**
+ * The node at `key` of the host's collection. As `renderNodeAt`: server once, untracked; browser a region that keeps
+ * the part while the node renders the same (`sameRender`).
+ */
+function renderNode(model, key) {
+    const at = () => model.source?.()?.getItem(key) ?? null;
+    if (isServer)
+        return untrack(() => {
+            const n = at();
+            return n?.render ? n.render(n) : null;
+        });
+    const node = computed(at, { equals: sameRender });
+    return () => {
+        node();
+        const n = untrack(at);
+        return n?.render ? untrack(() => n.render(n)) : null;
+    };
+}
+/**
+ * VirtualizerItem: one view's wrapper (position + size of its layout info) and its node's part, rendered with this
+ * renderer provided (a `Provider` binding: a part's lazily evaluated content still sees it) — a part rendering its
+ * children (`CollectionBranch`: sections, table rows / cells) gets the child views of its own view.
+ */
+function VirtualizerView(props) {
+    const { model, renderer, viewKey, views } = props;
+    const view = () => viewOf(model, views(), viewKey);
+    return (<div role="presentation" class="rv-Virtualizer-item" data-rv-view={String(viewKey)} data-rv-type={view().type} style={view().style}>
+      <Provider token={CollectionRendererContext} value={renderer}>
+        {renderNode(model, viewKey)}
+      </Provider>
+    </div>);
+}
+/**
+ * Lazy collection rows (`resume.lazyRows`, LAZY-T6): a loop over container views — a section, a table's header / body
+ * (views whose children have children) — is not the lazy `For`; the collection's rows below it are (a lazy row is one
+ * option / table row, not the whole table). Read by the server's lazy rows only.
+ */
+const leafViews = (views) => !views.some((view) => view.type === "section" || view.children.some((child) => child.children.length > 0));
+/**
+ * The keyed `For` of the rendered views below `parent` (the root / a section / a table body). Resumed page: an adopted view
+ * whose node changed since the server render is re-created (ROW-RERENDER, `resumedKeys`) — called in the region read that
+ * creates the For, so its `serverRows` baseline is recorded with (and adopted by) the For's region.
+ */
+function viewRows(model, parent, views, renderer, parentType) {
+    const order = () => rowOrder(model, parent, views());
+    const source = model.source, each = resumedKeys(source, serverRows(source, order, parentType), order);
+    return (<For each={each} by={(key) => key} lazy={() => leafViews(views())}>
+      {(key) => <VirtualizerView model={model} renderer={renderer} viewKey={rowKey(untrack(key))} views={views}/>}
+    </For>);
+}
+/** `CollectionRoot` of the virtualizer renderer: the sized content element and the root views. */
+export function VirtualizerRoot(props) {
+    const { link, root } = props;
+    const renderer = rendererOf(link);
+    const collection = root.collection;
+    const scrollRef = root.scrollRef;
+    const model = {
+        id: "",
+        items: [],
+        source: typeof collection === "function" ? collection : undefined,
+        focus: root.focusedKey,
+        scrollRef: typeof scrollRef === "function" ? scrollRef : undefined,
+        // The class / factory itself (a module reference or a resumable function), never a closure over `link`.
+        layout: link.layout,
+        layoutOptions: link.layoutOptions,
+        collection: {},
+        initialSize: link.initialSize,
+        dir: link.dir,
+        loadMoreOffset: 1,
+        shouldObserveItemSize: false,
+        persistedKeys: [],
+        focusedKey: signal(null),
+        views: signal([]),
+        contentSize: signal({ width: 0, height: 0 }),
+        isScrolling: signal(false),
+    };
+    if (!model.source)
+        throw new Error("Virtualizer: the collection component must pass its built collection (an accessor) to CollectionRoot.");
+    link.model = model;
+    // Untracked: the body must not depend on the collection / focused key (a resumed page would re-create the
+    // root, its content element and the focused option on the first focus move).
+    const first = untrack(() => initialWindow(model));
+    model.views.set(first.views);
+    model.contentSize.set(first.contentSize);
+    const rootViews = () => visibleViews(model);
+    return (<div role="presentation" class="rv-Virtualizer-content" style={contentStyle(model)}>
+      {viewRows(model, ROOT_VIEW, rootViews, renderer)}
+    </div>);
+}
+/** `CollectionBranch` of the virtualizer renderer: the rendered child views of `parentKey`'s view. */
+export function VirtualizerBranch(props) {
+    const link = props.link;
+    const model = link.model;
+    const renderer = rendererOf(link);
+    // A part rendered outside the window (no root yet): render its children as the default renderer would.
+    if (!model)
+        return DefaultCollectionRenderer.CollectionBranch(props.branch);
+    const parentKey = props.branch.parent.key;
+    const parentType = untrack(() => model.source?.()?.getItem(parentKey)?.type);
+    return viewRows(model, parentKey, () => childViews(model, parentKey), renderer, parentType);
+}
+/** Provides the virtualized `CollectionRenderer` (layout = layout delegate) to its child collection. */
+export function CollectionVirtualizer(props) {
+    const link = {
+        layout: props.layout,
+        layoutOptions: props.layoutOptions,
+        initialSize: props.initialSize ?? { width: 800, height: 600 },
+        dir: props.dir,
+        model: null,
+    };
+    const renderer = rendererOf(link);
+    return (<Provider token={CollectionRendererContext} value={renderer}>
+      {props.children}
+    </Provider>);
+}

package/virtualizer/engine.d.ts

@@ -1,4 +1,4 @@
-export { LOADER_KEY, initialWindow, projectViews, type VirtualView, type VirtualizerModel } from "./behaviour.js";
+export { LOADER_KEY, initialWindow, projectViews, type LayoutInput, type VirtualView, type VirtualizerModel } from "./behaviour.js";
 export { Virtualizer as VirtualizerEngine, type VirtualizerOptions } from "./virtualizer-core.js";
 export { createVirtualizerState, type VirtualizerState, type VirtualizerStateOptions } from "./state.js";
 export { Point } from "./point.js";

package/virtualizer/index.d.ts

@@ -1,2 +1,3 @@
 export { Virtualizer, type VirtualizerProps } from "./virtualizer.jsx";
+export { CollectionVirtualizer, type CollectionVirtualizerProps } from "./collection-renderer.jsx";
 export * from "./engine.js";

package/virtualizer/index.jsx

@@ -1,4 +1,5 @@
 // @rivetjs/cdk/virtualizer — React Spectrum's virtualizer (react-stately engine + layouts, react-aria
 // Virtualizer / ScrollView / VirtualizerItem) for Rivet. Apache-2.0 portions © Adobe; see NOTICE.
 export { Virtualizer } from "./virtualizer.jsx";
+export { CollectionVirtualizer } from "./collection-renderer.jsx";
 export * from "./engine.js";

package/virtualizer/list-layout.js

@@ -305,8 +305,10 @@ export class ListLayout extends Layout {
             if (child.type === "content")
                 continue;
             const rowHeight = (this.rowSize ?? this.estimatedRowSize ?? DEFAULT_HEIGHT) + this.gap;
-            // Skip rows before the valid rectangle unless they are already cached.
-            if (offset + rowHeight < this.requestedRect[offsetProperty] && !this.isValid(node, offset)) {
+            // Skip rows before the valid rectangle unless they are already cached. Rivet: never the section header —
+            // a cold-started engine (resumed page, first scroll) lays out from the scrolled rect, not from 0 as upstream
+            // does, and a skipped header was estimated at the row height and never rendered (story `#vsections`).
+            if (child.type !== "header" && offset + rowHeight < this.requestedRect[offsetProperty] && !this.isValid(node, offset)) {
                 offset += rowHeight;
                 skipped++;
                 continue;

package/virtualizer/state.js

@@ -43,8 +43,8 @@ export function createVirtualizerState(opts) {
                 lastOptions = layoutOptions;
                 merged = layoutOptions != null ? { ...context, layoutOptions } : context;
             }
-            const rect = visibleRect();
-            const views = virtualizer.render({
+            let rect = visibleRect();
+            const render = () => virtualizer.render({
                 layout: read(opts.layout),
                 collection: read(opts.collection),
                 persistedKeys: read(opts.persistedKeys) ?? null,
@@ -54,6 +54,16 @@ export function createVirtualizerState(opts) {
                 invalidationContext: merged,
                 isScrolling: isScrolling(),
             });
+            let views = render();
+            // A render that moved the visible rect (the layout clamped the scroll offset, or a scroll anchor) laid out no
+            // subviews: render again at the new rect before publishing, as the original's `setVisibleRect` (a state update
+            // during render) re-renders before commit. Publishing the empty pass emptied the rows' `For` once — on a resumed
+            // page that dropped every adopted server row (a first click that scrolled the scroller 4px past its clamped
+            // offset re-created all rows and lost focus; resume fuzz `/list-data`, 2026-10-20).
+            for (let pass = 0; pass < 3 && visibleRectChanged && !untrack(visibleRect).equals(rect); pass++) {
+                rect = untrack(visibleRect);
+                views = render();
+            }
             visibleViews.set(views);
             contentSize.set(virtualizer.contentSize);
             // onVisibleRectChange runs after the render (a layout effect in the original).

package/virtualizer/virtualizer.d.ts

@@ -1,8 +1,7 @@
 import type { Slot } from "@rivetjs/runtime/jsx-runtime";
 import type { Key } from "../collections/index.js";
-import { type MaybeAccessor, type VirtualView } from "./behaviour.js";
-import type { CollectionOptions, Node } from "./collection.js";
-import type { Layout } from "./layout.js";
+import { type LayoutInput, type MaybeAccessor, type VirtualView } from "./behaviour.js";
+import type { CollectionOptions } from "./collection.js";
 import type { Direction } from "./types.js";
 import type { StyleObject } from "@rivetjs/runtime/style";
 import { type GlobalDOMAttributes } from "@rivetjs/cdk/dom-props";
@@ -10,8 +9,8 @@ import { type GlobalDOMAttributes } from "@rivetjs/cdk/dom-props";
 export interface VirtualizerProps<T, O> extends Omit<GlobalDOMAttributes<HTMLDivElement>, "dir" | "onScroll"> {
     /** The data: an array, or an accessor (`() => list()`) whose changes re-render the window. */
     items: MaybeAccessor<readonly T[]>;
-    /** Layout factory, e.g. `() => new ListLayout()` (a resumable function: called on the server and on first scroll). */
-    layout: () => Layout<Node<any>, O>;
+    /** Layout class (`ListLayout`) or factory (`() => new ListLayout()`): resumable, instantiated on the server and on first scroll. */
+    layout: LayoutInput<O>;
     /** Options for the layout (JSON: `{ rowHeight: 32 }`, `{ minItemSize: { width: 120, height: 120 } }`). */
     layoutOptions?: O;
     /** View content: `(item, view) => …`; `view().type` tells items from sections / headers / loaders. */
@@ -57,6 +56,9 @@ export interface VirtualizerProps<T, O> extends Omit<GlobalDOMAttributes<HTMLDiv
 }
 /**
  * Renders a scrollable collection with a layout (ListLayout, GridLayout, TableLayout, WaterfallLayout): only
- * views inside the visible rect (plus overscan and persisted keys) are in the DOM.
+ * views inside the visible rect (plus overscan and persisted keys) are in the DOM. Renders its own views
+ * (`children(item, view)`) from `items`; a cdk collection component (`ListBox`, `Table`) is virtualized by
+ * `CollectionVirtualizer` (`./collection-renderer.tsx`), kept apart so this component and its users (Masonry)
+ * carry none of the collection renderer.
  */
 export declare function Virtualizer<T, O = unknown>(props: VirtualizerProps<T, O>): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/virtualizer/virtualizer.jsx

@@ -11,7 +11,10 @@ import { globalDOMProps } from "@rivetjs/cdk/dom-props";
 const OWNED = ["onScroll", "dir"];
 /**
  * Renders a scrollable collection with a layout (ListLayout, GridLayout, TableLayout, WaterfallLayout): only
- * views inside the visible rect (plus overscan and persisted keys) are in the DOM.
+ * views inside the visible rect (plus overscan and persisted keys) are in the DOM. Renders its own views
+ * (`children(item, view)`) from `items`; a cdk collection component (`ListBox`, `Table`) is virtualized by
+ * `CollectionVirtualizer` (`./collection-renderer.tsx`), kept apart so this component and its users (Masonry)
+ * carry none of the collection renderer.
  */
 export function Virtualizer(props) {
     const collection = {};