fix: address CodeRabbit findings on PR #1168

Real bugs:
- iOS deferred flush now rolls its delta into scrollAdjustments so any
  resize landing before the resulting scroll event sees the correct
  effective offset (previously the running accumulator stayed at 0 and
  a follow-up correction would compute from the stale pre-flush offset).
- measure() now resets pendingMin so the rebuild starts from index 0.
  Without this, a prior resizeItem() that left pendingMin > 0 would
  cause the next getMeasurements() to preserve stale entries before
  that index, partially defeating the invalidation.

Tests:
- Add a regression test for the measure() / pendingMin interaction.
- Add a regression test that asserts scrollAdjustments tracks the
  flushed iOS delta.
- Replace the wall-clock perf budget on the 1M-item lazy-path test
  with deterministic functional assertions (length + spot-checks of
  start/size/end across the range).

Benchmarks:
- VirtuaPage.getTotalSize() now actually uses the queried sized node
  before falling back to firstElementChild / host.
- Runner reads scenarios from window.bench.scenarios instead of a
  runtime import('/src/scenarios/types.ts'), which wouldn't resolve
  under vite preview (only the built dist is served).
- Persist the full scenario object on every result row (success and
  error) and add landingErrorPx to the error-path metrics so the
  schema is consistent.
- Use Array<T> annotations in dataset.ts / scenarios/types.ts to
  satisfy @typescript-eslint/array-type.
- README: language hint on the tree fence (MD040) and React 18 in
  the fairness notes.

Author: tannerlinsley

benchmarks/README.md

@@ -28,7 +28,7 @@ Results land in `benchmarks/results/<timestamp>.json` (raw, every run) and
 
 ## How it works
 
-```
+```text
 benchmarks/
 ├── src/
 │   ├── main.tsx                Reads ?lib=... &scenario=...
@@ -159,7 +159,7 @@ it's measuring — it just calls one global function per page.
   TanStack uses `useVirtualizer` + `measureElement`; virtua uses `VList` with
   the `data`/`item` props; virtuoso uses `Virtuoso` with `fixedItemHeight`
   when applicable; react-window uses `List` + `useDynamicRowHeight`.
-- React 19 runs in production mode (no `<StrictMode>`).
+- React 18 runs in production mode (no `<StrictMode>`).
 - Dataset is deterministic (LCG-seeded) and identical across libraries.
 - `--enable-precise-memory-info` + `--js-flags=--expose-gc` are passed to
   Chromium so memory readings aren't bucketed and we can force GC between

benchmarks/runner/run.mjs

@@ -86,18 +86,20 @@ async function runScenario(page, lib, scenarioId) {
     timeout: 15_000,
   })
   // Pull the scenario object back from the page so we run with the exact same
-  // shape the page is using.
+  // shape the page is using. We read from window.bench.scenarios (populated
+  // at mount) rather than a runtime `import('/src/scenarios/types.ts')`,
+  // since `vite preview` only serves the built dist, not source files.
   const result = await page.evaluate(async (id) => {
-    const mod = await import('/src/scenarios/types.ts')
-    const scenario = mod.SCENARIOS.find((s) => s.id === id)
+    const scenario = window.bench?.scenarios.find((s) => s.id === id)
     if (!scenario) throw new Error('unknown scenario: ' + id)
     // Force GC where supported so memory readings aren't poisoned by previous run.
     if ('gc' in globalThis) {
       try {
         globalThis.gc()
       } catch {}
     }
-    return await window.bench.run(scenario)
+    const metrics = await window.bench.run(scenario)
+    return { scenario, metrics }
   }, scenarioId)
   return result
 }
@@ -264,10 +266,14 @@ async function main() {
             `\n  ${lib.padEnd(9)} ${scenarioId.padEnd(28)} run ${r + 1}/${opts.runs} ... `,
           )
           try {
-            const metrics = await runScenario(page, lib, scenarioId)
+            const { scenario, metrics } = await runScenario(
+              page,
+              lib,
+              scenarioId,
+            )
             results.push({
               library: lib,
-              scenario: { id: scenarioId },
+              scenario,
               metrics,
               ranAt: new Date().toISOString(),
             })
@@ -287,6 +293,7 @@ async function main() {
                 longFrames: null,
                 jankMs: null,
                 memoryBytes: null,
+                landingErrorPx: null,
               },
               ranAt: new Date().toISOString(),
               notes: 'error: ' + e.message,

benchmarks/src/lib/dataset.ts

@@ -54,25 +54,25 @@ export function makeDataset(
   count: number,
   dynamic: boolean,
   wideVariance = false,
-): Item[] {
+): Array<Item> {
   const rand = lcg(424242)
-  const items: Item[] = new Array(count)
+  const items: Array<Item> = new Array(count)
   for (let i = 0; i < count; i++) {
     if (dynamic) {
       if (wideVariance) {
         // Wide-variance dataset: heights span ~30..500 px (≈16× ratio).
         // 1 → 50 words distributed log-normally so most items are short
         // but a meaningful tail is very tall.
         const wc = 1 + Math.floor(Math.pow(rand(), 2) * 49)
-        const parts: string[] = new Array(wc)
+        const parts: Array<string> = new Array(wc)
         for (let w = 0; w < wc; w++) {
           parts[w] = WORDS[Math.floor(rand() * WORDS.length)]!
         }
         items[i] = { id: i, text: `#${i} ${parts.join(' ')}` }
       } else {
         // 5..14 words → ~ one line; lengths picked deterministically.
         const wc = 5 + Math.floor(rand() * 10)
-        const parts: string[] = new Array(wc)
+        const parts: Array<string> = new Array(wc)
         for (let w = 0; w < wc; w++) {
           parts[w] = WORDS[Math.floor(rand() * WORDS.length)]!
         }

benchmarks/src/lib/harness.ts

@@ -1,3 +1,4 @@
+import { SCENARIOS } from '../scenarios/types'
 import type { ScenarioInput, ScenarioMetrics } from '../scenarios/types'
 
 // Each library page mounts and waits, then a global driver runs the scripted
@@ -31,6 +32,10 @@ declare global {
     bench?: {
       run: (scenario: ScenarioInput) => Promise<ScenarioMetrics>
       ready: () => boolean
+      // Exposed so the Node-side Playwright runner can resolve a scenario
+      // id to its full object without a runtime source-file import (which
+      // wouldn't survive `vite preview`'s built-only serving).
+      scenarios: ReadonlyArray<ScenarioInput>
     }
   }
 }
@@ -128,6 +133,7 @@ export function markFirstPaint(): void {
 export function installBenchAPI(): void {
   window.bench = {
     ready: () => !!window.__bench?.ready,
+    scenarios: SCENARIOS,
     run: async (scenario: ScenarioInput): Promise<ScenarioMetrics> => {
       const h = await waitFor(() => window.__bench?.handle ?? null)
       const mountStart = window.__bench?.mountStart ?? 0

benchmarks/src/pages/VirtuaPage.tsx

@@ -36,11 +36,13 @@ export function VirtuaPage({ scenario }: Props) {
           align: opts?.align ?? 'start',
         }),
       getTotalSize: () => {
+        // VList sets scrollSize implicitly on its sized inner div; prefer
+        // that node's scrollHeight, then firstElementChild, then host.
         const el = hostRef.current?.querySelector(
           '[style*="height:"]',
         ) as HTMLElement | null
-        // VList sets scrollSize implicitly; fall back to scrollHeight.
         return (
+          el?.scrollHeight ??
           (hostRef.current?.firstElementChild as HTMLElement | null)
             ?.scrollHeight ??
           hostRef.current?.scrollHeight ??

benchmarks/src/scenarios/types.ts

@@ -56,7 +56,7 @@ export interface ScenarioResult {
 
 // The fixed scenarios all libraries run. Adding scenarios here surfaces them
 // in the runner without further plumbing.
-export const SCENARIOS: ScenarioInput[] = [
+export const SCENARIOS: Array<ScenarioInput> = [
   {
     id: 'mount-fixed-1k',
     count: 1_000,

packages/virtual-core/src/index.ts

@@ -702,8 +702,11 @@ export class Virtualizer<
     if (cur < 0 || cur > max) return
     const delta = this._iosDeferredAdjustment
     this._iosDeferredAdjustment = 0
+    // Roll the deferred delta into the running accumulator so any resize
+    // landing between now and the resulting scroll event computes from the
+    // post-flush offset rather than the stale one.
     this._scrollToOffset(cur, {
-      adjustments: delta,
+      adjustments: (this.scrollAdjustments += delta),
       behavior: undefined,
     })
   }
@@ -1616,6 +1619,10 @@ export class Virtualizer<
   }
 
   measure = () => {
+    // Reset pendingMin so the next getMeasurements rebuilds from index 0.
+    // Without this, a prior resizeItem() that left pendingMin > 0 would
+    // cause the rebuild to preserve stale items before that index.
+    this.pendingMin = null
     this.itemSizeCache.clear()
     this.laneAssignments.clear() // Clear lane cache for full re-layout
     this.itemSizeCacheVersion++

packages/virtual-core/tests/index.test.ts

@@ -638,6 +638,39 @@ test('measure() should clear size cache and lane assignments', () => {
   expect(measurements[1]!.size).toBe(50)
 })
 
+test('measure() should fully invalidate when a later index was dirtied without an intervening getMeasurements()', () => {
+  // Regression: measure() used to clear itemSizeCache but not pendingMin.
+  // If resizeItem() had been called without a subsequent getMeasurements()
+  // to flush pendingMin, the next rebuild would preserve measurementsCache
+  // entries before that index — even though measure() is supposed to wipe
+  // everything.
+  const virtualizer = new Virtualizer({
+    count: 6,
+    estimateSize: () => 50,
+    getScrollElement: () => null,
+    scrollToFn: vi.fn(),
+    observeElementRect: vi.fn(),
+    observeElementOffset: vi.fn(),
+  })
+
+  // Seed item 0 with a non-estimate size, then flush so it's in measurementsCache.
+  virtualizer.resizeItem(0, 999)
+  virtualizer['getMeasurements']()
+  // Now dirty a later index without flushing — pendingMin will be 2.
+  virtualizer.resizeItem(2, 888)
+  expect(virtualizer['pendingMin']).toBe(2)
+
+  virtualizer.measure()
+
+  // After measure(), pendingMin must be null so the rebuild starts at 0
+  // and discards the stale item-0 entry.
+  expect(virtualizer['pendingMin']).toBe(null)
+
+  const m = virtualizer['getMeasurements']()
+  expect(m[0]!.size).toBe(50)
+  expect(m[2]!.size).toBe(50)
+})
+
 test('measure() should trigger a re-measurement on subsequent getMeasurements', () => {
   let sizeFn = (i: number) => 50
   const virtualizer = new Virtualizer({
@@ -1320,8 +1353,13 @@ test('lazy fast path: getVirtualItemForOffset binary search returns correct item
   expect(found?.end).toBe(510)
 })
 
-test('lazy fast path: large list (1M items) does not allocate per-item objects upfront', () => {
-  const start = performance.now()
+test('lazy fast path: 1M-item list returns a sparse view, not an eagerly-allocated array', () => {
+  // Functional contract for the lazy fast path: a 1M-item virtualizer
+  // returns measurements that report the correct total length and produce
+  // exact start/size/end values on indexed access without requiring the
+  // whole array to be materialized. Sparse spot-checks across the range
+  // would fail if the fast path were silently allocating N VirtualItems
+  // (or if the typed-array backing computed offsets incorrectly).
   const v = new Virtualizer({
     count: 1_000_000,
     estimateSize: () => 30,
@@ -1330,10 +1368,15 @@ test('lazy fast path: large list (1M items) does not allocate per-item objects u
     observeElementRect: vi.fn(),
     observeElementOffset: vi.fn(),
   })
-  v['getMeasurements']()
-  const elapsed = performance.now() - start
-  // Should be sub-50ms even at 1M items (typed array fill + proxy alloc only)
-  expect(elapsed).toBeLessThan(50)
+  const m = v['getMeasurements']()
+  expect(m.length).toBe(1_000_000)
+  expect(m[0]!.start).toBe(0)
+  expect(m[0]!.size).toBe(30)
+  expect(m[0]!.end).toBe(30)
+  expect(m[500_000]!.start).toBe(15_000_000)
+  expect(m[500_000]!.end).toBe(15_000_030)
+  expect(m[999_999]!.start).toBe(29_999_970)
+  expect(m[999_999]!.end).toBe(30_000_000)
 })
 
 // ─── iOS momentum-safe scroll adjustments ───────────────────────────────────
@@ -1447,6 +1490,60 @@ test('iOS deferral: multiple resizes during scroll accumulate and flush as one',
   })
 })
 
+test('iOS deferral: flushed delta is rolled into scrollAdjustments so back-to-back resizes stay consistent', () => {
+  // Regression: the deferred flush used to write `adjustments: delta`
+  // directly without updating `this.scrollAdjustments`. If a second resize
+  // landed before the resulting scroll event fired (and reset the
+  // accumulator), the comparison `itemStart < getScrollOffset() +
+  // scrollAdjustments` would miss the flushed delta and the next correction
+  // would compute from the stale offset.
+  withFakeIOSUserAgent(() => {
+    const scrollToFn = vi.fn()
+    let scrollCallback:
+      | ((offset: number, isScrolling: boolean) => void)
+      | null = null
+    const v = new Virtualizer({
+      count: 10,
+      estimateSize: () => 50,
+      getScrollElement: () =>
+        ({
+          scrollTop: 200,
+          scrollLeft: 0,
+          scrollHeight: 500,
+          clientHeight: 200,
+          offsetHeight: 200,
+        }) as any,
+      scrollToFn,
+      observeElementRect: () => {},
+      observeElementOffset: (_inst, cb) => {
+        scrollCallback = cb
+        cb(200, true)
+        return () => {}
+      },
+    })
+    v._willUpdate()
+    v['getMeasurements']()
+    scrollToFn.mockClear()
+
+    // Build up a deferred adjustment of 50 during scroll.
+    v.resizeItem(0, 100)
+    expect(v['_iosDeferredAdjustment']).toBe(50)
+    expect(v['scrollAdjustments']).toBe(0)
+
+    // Settle: scroll event resets scrollAdjustments to 0, then the flush
+    // runs and must roll the deferred delta back into scrollAdjustments.
+    scrollCallback!(200, false)
+
+    expect(scrollToFn).toHaveBeenCalledTimes(1)
+    const [, opts] = scrollToFn.mock.calls[0]!
+    expect(opts.adjustments).toBe(50)
+    // The running accumulator must now reflect the flushed delta — any
+    // resize landing before the resulting scroll event fires has to see
+    // the correct effective offset.
+    expect(v['scrollAdjustments']).toBe(50)
+  })
+})
+
 // ─── Phase 1: touch event distinction ────────────────────────────────────────
 
 // Mock EventTarget that records listeners so tests can dispatch events