feat(benchmarks): add React Aria Virtualizer to cross-library harness

benchmarks/README.md

@@ -1,9 +1,23 @@
 # Virtualization benchmarks
 
-Reproducible browser benchmarks comparing **@tanstack/react-virtual**, **virtua**, **react-virtuoso**, and **react-window** v2.
+Reproducible browser benchmarks comparing **@tanstack/react-virtual**, **virtua**, **react-virtuoso**, **react-window** v2, and **react-aria-components** `Virtualizer`.
 
 Same data, same scenarios, same harness — driven by Playwright against a real browser running a real Vite-built React app for each library.
 
+### Library matrix
+
+| id | What it measures |
+| --- | --- |
+| `tanstack` | Headless `@tanstack/react-virtual` + plain DOM rows |
+| `tanstack-rac` | TanStack virtual + `role="listbox"` / `role="option"` (no RAC collection) |
+| `rac-listbox` | React Aria `ListBox` only — collection overhead, all items in DOM |
+| `rac` | React Aria `Virtualizer` + `ListBox` — full integrated stack |
+| `virtua`, `virtuoso`, `window` | Existing third-party baselines |
+
+`rac-listbox` skips `mount-fixed-100k` (100k DOM nodes is intentionally out of scope).
+
+**RAC accuracy scenarios:** React Aria's virtualizer does not expose `scrollToIndex`. The harness uses layout-derived `scrollTop` + native scroll events. If the target row is not mounted after scroll settles, `landingErrorPx` is `-1` (item missing from DOM). `rac-listbox` (non-virtualized) reports accurate landings because every row stays in the DOM.
+
 ## Running
 
 ```bash
@@ -177,6 +191,7 @@ Add an entry to `SCENARIOS` in `src/scenarios/types.ts`. The runner discovers it
 1. Create `src/pages/MyLibPage.tsx` that registers a `HarnessHandle` (see existing pages for the contract).
 2. Wire it into `src/main.tsx`'s switch.
 3. Add the library name to `ALL_LIBS` in `runner/run.mjs`.
+4. If a library cannot run certain scenarios, add exclusions to `LIB_SCENARIO_EXCLUSIONS` in `src/scenarios/libScenarioExclusions.mjs` (also re-exported from `scenarios/types.ts`).
 
 ## Known limitations
 

benchmarks/package.json

@@ -13,6 +13,7 @@
   "dependencies": {
     "@tanstack/react-virtual": "workspace:*",
     "react": "^19.2.7",
+    "react-aria-components": "^1.19.0",
     "react-dom": "^19.2.7",
     "react-virtuoso": "^4.15.0",
     "react-window": "^2.2.4",

benchmarks/runner/run.mjs

@@ -10,13 +10,22 @@ import { setTimeout as sleep } from 'node:timers/promises'
 import { writeFileSync, mkdirSync } from 'node:fs'
 import path from 'node:path'
 import url from 'node:url'
+import { LIB_SCENARIO_EXCLUSIONS } from '../src/scenarios/libScenarioExclusions.mjs'
 
 const __dirname = path.dirname(url.fileURLToPath(import.meta.url))
 const BENCH_DIR = path.resolve(__dirname, '..')
 const PORT = 4173
 const BASE = `http://localhost:${PORT}`
 
-const ALL_LIBS = ['tanstack', 'virtua', 'virtuoso', 'window']
+const ALL_LIBS = [
+  'tanstack',
+  'tanstack-rac',
+  'virtua',
+  'virtuoso',
+  'window',
+  'rac',
+  'rac-listbox',
+]
 const ALL_SCENARIOS = [
   'mount-fixed-1k',
   'mount-fixed-10k',
@@ -260,7 +269,9 @@ async function main() {
 
     const results = []
     for (const lib of opts.libs) {
-      for (const scenarioId of opts.scenarios) {
+      const excluded = LIB_SCENARIO_EXCLUSIONS[lib] ?? []
+      const scenarios = opts.scenarios.filter((id) => !excluded.includes(id))
+      for (const scenarioId of scenarios) {
         for (let r = 0; r < opts.runs; r++) {
           process.stderr.write(
             `\n  ${lib.padEnd(9)} ${scenarioId.padEnd(28)} run ${r + 1}/${opts.runs} ... `,

benchmarks/src/lib/harness.ts

@@ -8,6 +8,8 @@ import type { ScenarioInput, ScenarioMetrics } from '../scenarios/types'
 export interface HarnessHandle {
   /** Container element the library is told to scroll. */
   getScrollContainer: () => HTMLElement | null
+  /** Optional wider DOM root for accuracy probes (e.g. virtualized item wrappers). */
+  getSearchRoot?: () => HTMLElement | null
   /** Programmatically scroll to a target offset (px). */
   scrollToOffset?: (offset: number) => void
   /** Programmatically scroll to a target index. Some libraries expose
@@ -44,6 +46,21 @@ function nextFrame(): Promise<number> {
   return new Promise((resolve) => requestAnimationFrame(resolve))
 }
 
+async function waitForTargetItem(
+  searchRoot: HTMLElement,
+  targetIndex: number,
+  timeoutMs = 2000,
+): Promise<HTMLElement | null> {
+  const selector = `[data-index="${targetIndex}"]`
+  const start = performance.now()
+  while (performance.now() - start < timeoutMs) {
+    const el = searchRoot.querySelector(selector) as HTMLElement | null
+    if (el) return el
+    await nextFrame()
+  }
+  return searchRoot.querySelector(selector) as HTMLElement | null
+}
+
 function waitFor<T>(
   predicate: () => T | false | null | undefined,
   timeoutMs = 8000,
@@ -203,13 +220,8 @@ export function installBenchAPI(): void {
         }
         actionMs = performance.now() - t0
 
-        // Now: find the DOM element for the target index. Its viewport-relative
-        // top tells us where it actually landed. With align:'start', we want
-        // item[targetIndex]'s top to be at viewport top — i.e., offset 0.
-        const itemSelector = `[data-index="${targetIndex}"]`
-        const itemEl = container.querySelector(
-          itemSelector,
-        ) as HTMLElement | null
+        const searchRoot = h.getSearchRoot?.() ?? container
+        const itemEl = await waitForTargetItem(searchRoot, targetIndex)
         if (itemEl) {
           const itemRect = itemEl.getBoundingClientRect()
           const containerRect = container.getBoundingClientRect()
@@ -269,11 +281,8 @@ export function installBenchAPI(): void {
         }
         actionMs = performance.now() - t0
 
-        // Compute landing error: distance between the relevant edge of the
-        // target item and the relevant edge of the viewport.
-        const itemEl = container.querySelector(
-          `[data-index="${targetIndex}"]`,
-        ) as HTMLElement | null
+        const searchRoot = h.getSearchRoot?.() ?? container
+        const itemEl = await waitForTargetItem(searchRoot, targetIndex)
         if (itemEl) {
           const iRect = itemEl.getBoundingClientRect()
           const cRect = container.getBoundingClientRect()

benchmarks/src/lib/itemRow.tsx

@@ -0,0 +1,26 @@
+import type { Item } from './dataset'
+
+export function ItemRow({
+  item,
+  itemSize,
+  dynamic,
+  index,
+}: {
+  item: Item
+  itemSize: number
+  dynamic: boolean
+  index: number
+}) {
+  return (
+    <div
+      data-index={index}
+      className={'item ' + (index % 2 === 0 ? 'even' : '')}
+      style={{
+        minHeight: dynamic ? undefined : itemSize,
+        boxSizing: 'border-box',
+      }}
+    >
+      {item.text}
+    </div>
+  )
+}

benchmarks/src/lib/racBench.ts

@@ -0,0 +1,114 @@
+import type { ListLayout } from 'react-aria-components'
+import type { HarnessHandle } from './harness'
+import type { ScenarioInput } from '../scenarios/types'
+import type { Item } from './dataset'
+
+export function findRacScrollContainer(
+  root: HTMLElement | null,
+): HTMLElement | null {
+  if (!root) return null
+  for (const node of root.querySelectorAll('div')) {
+    const el = node as HTMLElement
+    const oy = getComputedStyle(el).overflowY
+    if (oy === 'auto' || oy === 'scroll') return el
+  }
+  return root
+}
+
+export function scrollRacToIndex(
+  container: HTMLElement,
+  layout: ListLayout<unknown> | null,
+  items: Array<Item>,
+  index: number,
+  itemSize: number,
+  align: 'start' | 'end' = 'start',
+): void {
+  const key = items[index]?.id ?? index
+
+  for (let attempt = 0; attempt < 4; attempt++) {
+    let scrollTop = index * itemSize
+
+    if (layout?.virtualizer) {
+      layout.update({})
+      layout.getLayoutInfo(key)
+      const layoutInfo = layout.getLayoutInfo(key)
+      if (layoutInfo) {
+        scrollTop =
+          align === 'end'
+            ? layoutInfo.rect.y + layoutInfo.rect.height - container.clientHeight
+            : layoutInfo.rect.y
+      }
+    } else if (align === 'end') {
+      scrollTop += itemSize - container.clientHeight
+    }
+
+    const maxScroll = Math.max(
+      0,
+      container.scrollHeight - container.clientHeight,
+    )
+    container.scrollTop = Math.max(0, Math.min(scrollTop, maxScroll))
+    container.scrollTo({ top: container.scrollTop, behavior: 'instant' })
+    container.dispatchEvent(new Event('scroll', { bubbles: true }))
+  }
+}
+
+export function createRacVirtualHarness({
+  hostRef,
+  scrollerRef,
+  layoutRef,
+  items,
+  scenario,
+}: {
+  hostRef: { current: HTMLDivElement | null }
+  scrollerRef: { current: HTMLElement | null }
+  layoutRef: { current: ListLayout<unknown> | null }
+  items: Array<Item>
+  scenario: ScenarioInput
+}): Omit<HarnessHandle, 'getScrollContainer'> & {
+  getScrollContainer: () => HTMLElement | null
+} {
+  return {
+    getScrollContainer: () =>
+      scrollerRef.current ?? findRacScrollContainer(hostRef.current),
+    getSearchRoot: () => hostRef.current,
+    scrollToIndex: (index, opts) => {
+      const container =
+        scrollerRef.current ?? findRacScrollContainer(hostRef.current)
+      if (!container) return
+      scrollRacToIndex(
+        container,
+        layoutRef.current,
+        items,
+        index,
+        scenario.itemSize,
+        opts?.align ?? 'start',
+      )
+    },
+    getTotalSize: () => {
+      const container =
+        scrollerRef.current ?? findRacScrollContainer(hostRef.current)
+      if (!container) return 0
+      const content = container.firstElementChild as HTMLElement | null
+      return content?.offsetHeight ?? container.scrollHeight
+    },
+    isFullyMeasured: () => {
+      if (!scenario.dynamic) return true
+      const container =
+        scrollerRef.current ?? findRacScrollContainer(hostRef.current)
+      const total = container?.scrollHeight ?? 0
+      const estimate = scenario.count * scenario.itemSize
+      return total > 0 && total !== estimate
+    },
+  }
+}
+
+export function cacheRacScroller(
+  host: HTMLDivElement | null,
+  scrollerRef: { current: HTMLElement | null },
+): void {
+  const scroller = findRacScrollContainer(host)
+  if (scroller) {
+    scrollerRef.current = scroller
+    scroller.dataset.benchRacScroller = 'true'
+  }
+}

benchmarks/src/main.tsx

@@ -1,6 +1,9 @@
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
+import { RacListboxPageRoot } from './pages/RacListboxPage'
+import { RacPageRoot } from './pages/RacPage'
 import { TanstackPageRoot } from './pages/TanstackPage'
+import { TanstackRacPageRoot } from './pages/TanstackRacPage'
 import { VirtuaPageRoot } from './pages/VirtuaPage'
 import { VirtuosoPageRoot } from './pages/VirtuosoPage'
 import { WindowPageRoot } from './pages/WindowPage'
@@ -28,12 +31,18 @@ function App() {
   switch (lib) {
     case 'tanstack':
       return <TanstackPageRoot scenario={scenario} />
+    case 'tanstack-rac':
+      return <TanstackRacPageRoot scenario={scenario} />
     case 'virtua':
       return <VirtuaPageRoot scenario={scenario} />
     case 'virtuoso':
       return <VirtuosoPageRoot scenario={scenario} />
     case 'window':
       return <WindowPageRoot scenario={scenario} />
+    case 'rac':
+      return <RacPageRoot scenario={scenario} />
+    case 'rac-listbox':
+      return <RacListboxPageRoot scenario={scenario} />
     default:
       return (
         <div style={{ padding: 24 }}>