@opencorestack/opengridx 3.5.0 → 3.5.1

package/docs/architecture/datagrid-orchestration.md

@@ -71,7 +71,8 @@ in an effect, so **keep the call order when you move or add a hook**. In particu
 | 31 | `useGridScrollToIndexesApi` | `hooks/core/useGridScrollToIndexesApi.ts` | `scrollToIndexes` |
 | 31a | `useGridColumnAutosize` | `hooks/core/useGridColumnAutosize.ts` | `autosizeColumn` / `autosizeColumns` on the API, and the resize handle's auto-size handler (v3.1) |
 | 32 | `useGridViewport` | `hooks/core/useGridViewport.ts` | Scroll sync, viewport measurement, viewport callback ref |
-| 33 | `useGridVirtualization` | `hooks/core/useGridVirtualization.ts` | Render window |
+| 32a | `useGridMaxContentHeight` | `hooks/core/useGridMaxContentHeight.ts` | The tallest element this browser lays out (`utils/maxElementHeight.ts`, measured once per document after mount; `undefined` until then, `Infinity` without a layout engine) |
+| 33 | `useGridVirtualization` | `hooks/core/useGridVirtualization.ts` | Render window; `virtualContainerHeight` caps the rows' container to `maxContentHeight` (Firefox collapses taller elements) |
 | 34 | `useGridSortHandlers` | `hooks/core/useGridHeaderHandlers.ts` | Header sort / shift-sort |
 | 35 | `useGridKeyboardNavigation` | `hooks/core/useGridKeyboardNavigation.ts` | Focus and keyboard handling; takes `cellSelection.keyboard` (Shift+navigation, Escape, Ctrl/Cmd+A) |
 | 36 | `useGridPointerFocusHandlers` | `hooks/core/useGridFocusHandlers.ts` | Cell and header click focus |

package/docs/features/virtualization.md

@@ -29,11 +29,11 @@ The grid calculates which rows are visible based on:
 />
 ```
 
-**Performance characteristics** (when the grid has a bounded height — see below):
-- ✅ Renders ~15-25 rows regardless of total dataset size
-- ✅ Constant memory usage
-- ✅ Smooth 60fps scrolling
-- ⚠️ Not millions of rows. Browsers cap an element's height (33,554,432px in Chromium, about 17.9M px in Firefox) and the grid does no scroll scaling: it lays every row out at its real height, so rows past the cap cannot be scrolled to. The limit is roughly `33,554,432 / rowHeight` rows in Chromium (about 645,000 at the default 52px), and about half that in Firefox (about 340,000). Beyond that, use pagination, or server-side paging / infinite scroll. In development the grid warns when the content passes 17.8M px.
+**Performance characteristics** (when the grid has a bounded height — see below), measured by the [benchmark](../performance.md#benchmarks):
+- ✅ About 19 row elements at rest in an 800 px page at 52 px rows, at most about 86 while scrolling fast, whatever the row count (10k to 1M)
+- ✅ Scrolling keeps up with a 60 Hz display at 1M rows in Chromium (no missed frames) and Firefox; WebKit misses a frame or two on each long jump of the scroll position
+- ✅ The grid itself adds about 10 MB of JS heap at 100k rows and 79 MB at 1M (Chromium), on top of your row data
+- ⚠️ Not millions of rows at the default height. Browsers cap an element's height and the grid does no scroll scaling: it lays every row out at its real height. Chromium and WebKit stop at 33,554,428 px, so rows past about `33,554,428 / rowHeight` cannot be scrolled to (645,277 at the default 52 px; 1M rows fit at 32 px). Firefox's limit is about 17.9M px (about 344,000 rows at 52 px); since 3.5.1 the grid caps its content to the limit it measures, so Firefox scrolls normally up to there (on 3.5.0 and earlier, content past the limit collapsed and the grid did not scroll at all). Beyond that, use pagination, or server-side paging / infinite scroll. In development the grid warns when rows are cut off and names how many can be scrolled to. Measured reach per browser: [Performance → Reach](../performance.md#reach-the-browser-height-ceiling).
 
 ### Column Virtualization
 

package/docs/performance.md

@@ -87,7 +87,12 @@ import '@opencorestack/opengridx/styles';
 
 ## Know the browser's height limit
 
-The grid sizes its scroll content to `rowCount × rowHeight` pixels and does not scale scroll positions. Browsers cap an element's height (Chromium at 33,554,432 px, Firefox lower), so at the default 52 px row height rows past roughly 645,000 cannot be scrolled to. A dev-mode warning reports it. For more rows, use pagination, `paginationMode="server"` or infinite scroll with a `dataSource`.
+The grid sizes its scroll content to `rowCount × rowHeight` pixels and does not scale scroll positions. Browsers cap an element's height, and the [benchmark](#reach-the-browser-height-ceiling) measures what happens past the cap:
+
+- **Chromium and WebKit** clamp the content at 33,554,428 px. Rows below that cannot be scrolled to: at the default 52 px row height that is every row past 645,277.
+- **Firefox** has a lower limit, about 17.9M px, and collapses a taller element instead of clamping it. Up to 3.5.0 that made a grid with more content unscrollable in Firefox (only the first screen of rows was reachable). **Since 3.5.1 the grid measures the browser's limit once and caps its scroll content to it**, so Firefox scrolls normally and reaches the rows above the cap: about 344,000 rows at 52 px, 559,000 at 32 px.
+
+In development the grid warns when rows are cut off, naming how many can be scrolled to in that browser. For more rows, use pagination, `paginationMode="server"` or infinite scroll with a `dataSource`, or a smaller `rowHeight` (`density="compact"`, 32 px, keeps 1M rows under the Chromium and WebKit cap).
 
 ## Use server-side operations for very large datasets
 
@@ -116,9 +121,215 @@ Without a `dataSource`, fetch the rows yourself from the change callbacks and co
 In server modes the grid shows `rows` as given: it does not re-filter, re-sort or slice them (v3.0+; earlier versions did unless a `dataSource` was set).
 
 
+## Benchmarks
+
+Measured with `npm run bench` (`bench/`), which installs the packed npm package into a production Vite + React 19 app and drives it with Playwright in Chromium, Firefox and WebKit. The numbers below are from one machine (Apple M1, 8 GB RAM): compare them with each other and with your own runs, not with other machines.
+
+**In short** (Chromium, median):
+
+| Rows | Mount | Sort (number / string) | Filter | Quick filter | Group + sum | Scroll frames over 16.7 ms | JS heap |
+| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| 10,000 | 79 ms | 34 / 42 ms | 19 ms | 52 ms | 30 ms | 0 % | 2.9 MB |
+| 100,000 | 89 ms | 102 / 160 ms | 28 ms | 205 ms | 87 ms | 0 % | 10.4 MB |
+| 500,000 | 295 ms | 493 / 641 ms | 59 ms | 958 ms | 331 ms | 0 % | 39.4 MB |
+| 1,000,000 | 688 ms | 1,105 / 1,316 ms | 95 ms | 1,845 ms | 681 ms | 0 % | 79.1 MB |
+
+- **Scrolling keeps up with the display at every size.** Chromium missed no frames; Firefox missed 0–2.4 %. The DOM holds about 19 row elements at rest (28 at 32 px) and at most 86 while scrolling fast, whatever the row count. WebKit scrolls steadily without missed frames too, but misses one or two frames each time the scroll position jumps far (the *during the jumps* rows below). Firefox's scroll numbers at 500k and 1M rows are not comparable: the grid cannot scroll there (see Reach).
+- **Sorting, the quick filter and grouping run on the main thread in one piece.** Up to 100k rows they finish in a few frames; at 1M a sort blocks the page for about 1.1–1.3 s in Chromium (up to 2.9 s for a string sort in WebKit), and the first quick-filter keystroke for about 2–3 s. For sorting or searching a million rows interactively, use server-side sorting and filtering.
+- **Reach:** past the browser's height cap rows cannot be scrolled to, and in Firefox the grid stops scrolling altogether. See [Reach](#reach-the-browser-height-ceiling).
+
+### Method
+
+- **The app is the built package.** `bench/app` installs the tarball from `npm pack`, like a consumer, and is a production build (no React development checks).
+- **Data:** 12 columns (`id`, two strings, two `singleSelect`, four numbers of which two have a `valueFormatter`, a date, a boolean, a short code), `id` and `name` pinned left. Rows come from a seeded random generator in the page and are generated before any timer starts.
+- **Page:** 1280×800, the grid fills it, headless browsers launched by Playwright, one new browser context per run.
+- **Timing:** each operation is timed from the call (`root.render`, `apiRef.setSortModel`, `setFilterModel`, `setRowGroupingModel` + `setAggregationModel`) to the first painted frame that shows its result: the page waits on `requestAnimationFrame` until the grid's DOM shows the result, then one more frame so that frame has been painted. The time therefore includes React's render and commit, style, layout and paint, and up to one frame of waiting for the next refresh. The method is described in detail at the top of `bench/app/src/harness.tsx`.
+- **Operations:** sort ascending on `amount` (number) and on `name` (string); filter `name contains "nova"` (6 % of rows) and `amount > 5000` (50 %); one quick-filter term over all columns (the first search reads and formats every cell, so this is the first keystroke's cost); group by `region` (8 groups) with `sum` of `amount`. Each is undone before the next.
+- **Scroll:** 5 s driven from `requestAnimationFrame`: 3 s at a constant 2,400 px/s, then a jump to a random position anywhere in the scrollable range every 100 ms. Frame times are the gaps between consecutive animation frames. Headless browsers do not pace frames by a display, so idle frames already vary between about 16.6 and 18 ms (17–21 ms in WebKit); a frame therefore counts as *over 16.7 ms* when it took more than 1.5 refresh intervals (25 ms at 60 Hz, a missed refresh) and as *over 33 ms* above 2.5 intervals (41.7 ms, two or more missed).
+- **Chromium only:** long tasks (`PerformanceObserver('longtask')`; Firefox and WebKit have no such entries) and the JS heap (Chrome DevTools Protocol `Runtime.getHeapUsage` after a forced garbage collection, after mount minus the same page with the rows generated and no grid, so it is what the grid adds on top of your data).
+- **DOM size:** row elements and cells at the end of the scroll test, and row elements after scrolling back to the top and letting the grid settle.
+- **Repeats:** 6 runs per row count and engine; the first is discarded as warm-up, the tables show the median of the other 5 and the min–max range.
+- **Machine load:** the runner records the load average before and after. This machine had a steady load of about 3.5–4 from desktop apps (an IDE, a browser) during the run; nothing else heavy ran.
+
+### Results
+
+<!-- bench:start -->
+<!-- Generated by `node bench/report.mjs --write docs/performance.md` from bench/results/2026-10-09-apple-m1-darwin.json. Do not edit by hand. -->
+
+- **Machine:** Apple M1, 8 cores, 8 GB RAM, macOS 26.5.1 (arm64)
+- **Browsers:** Chromium 145.0.7632.6, Firefox 146.0.1, WebKit 26.0 (Playwright, headless, 1280×800 page)
+- **Package:** @opencorestack/opengridx 3.5.0 (commit `f2ad5cb`), production build
+- **Date:** 2026-10-09; load average at start 3.88 / 3.73 / 4.04, at end 3.46 / 3.71 / 3.77
+- **Runs:** median of 5 runs after one discarded warm-up run, with the min–max range in brackets
+
+¹ Chromium only: Firefox and WebKit have no long-task entries, and the heap is read through the Chrome DevTools Protocol.
+
+#### 10,000 rows, 52 px rows
+
+| Metric | Chromium | Firefox | WebKit |
+| :--- | ---: | ---: | ---: |
+| Mount | 79 ms (59–88) | 84 ms (82–85) | 116 ms (110–128) |
+| Sort, number column | 34 ms (28–38) | 44 ms (43–46) | 81 ms (72–85) |
+| Sort, string column | 42 ms (22–45) | 56 ms (36–58) | 83 ms (76–108) |
+| Filter, string `contains` | 19 ms (14–31) | 31 ms (26–40) | 51 ms (47–57) |
+| Filter, number `>` | 18 ms (13–19) | 25 ms (24–28) | 37 ms (34–39) |
+| Quick filter, one term | 52 ms (33–60) | 76 ms (68–83) | 96 ms (84–110) |
+| Group by region + `sum` | 30 ms (22–37) | 41 ms (31–47) | 77 ms (72–126) |
+| Scroll frame time p50 | 16.7 ms | 16.7 ms | 17.0 ms |
+| Scroll frame time p95 | 17.6 ms (17.5–17.6) | 17.6 ms (17.6–18.6) | 45.0 ms (43.0–46.0) |
+| Scroll frame time p99 | 17.6 ms (17.6–17.7) | 33.3 ms (33.3–34.1) | 49.0 ms (47.0–58.0) |
+| Scroll frames over 16.7 ms | 0.0 % (0.0–0.3) | 1.7 % (1.4–4.2) | 8.6 % (7.6–9.7) |
+| Scroll frames over 33 ms | 0.0 % | 0.0 % (0.0–0.7) | 6.5 % (5.4–7.1) |
+| … over 16.7 ms while scrolling steadily | 0.0 % | 0.6 % (0.0–4.7) | 0.0 % |
+| … over 16.7 ms during the jumps | 0.0 % (0.0–0.8) | 3.5 % (2.6–4.3) | 26.1 % (21.9–29.9) |
+| Long tasks during scroll ¹ | 0 | – | – |
+| Longest task during a sort ¹ | none | – | – |
+| JS heap for the grid ¹ | 2.9 MB | – | – |
+| Row elements in the DOM, end of scroll | 76 | 76 | 76 |
+| Cells in the DOM, end of scroll | 912 | 912 | 912 |
+| Row elements in the DOM, at rest | 19 | 19 | 19 |
+| Reach: last row on screen at the bottom | all rows | all rows | all rows |
+
+#### 100,000 rows, 52 px rows
+
+| Metric | Chromium | Firefox | WebKit |
+| :--- | ---: | ---: | ---: |
+| Mount | 89 ms (86–100) | 138 ms (133–155) | 157 ms (138–204) |
+| Sort, number column | 102 ms (85–119) | 129 ms (120–136) | 159 ms (126–237) |
+| Sort, string column | 160 ms (152–165) | 213 ms (180–224) | 241 ms (211–259) |
+| Filter, string `contains` | 28 ms (20–34) | 42 ms (28–46) | 56 ms (47–109) |
+| Filter, number `>` | 33 ms (27–39) | 39 ms (24–57) | 48 ms (31–60) |
+| Quick filter, one term | 205 ms (193–232) | 348 ms (322–359) | 323 ms (269–340) |
+| Group by region + `sum` | 87 ms (81–91) | 107 ms (99–109) | 118 ms (105–143) |
+| Scroll frame time p50 | 16.7 ms | 16.7 ms | 17.0 ms |
+| Scroll frame time p95 | 17.4 ms (17.3–17.5) | 17.5 ms (17.4–17.6) | 44.0 ms (43.0–45.0) |
+| Scroll frame time p99 | 17.6 ms (17.6–17.7) | 33.3 ms | 48.0 ms (47.0–55.0) |
+| Scroll frames over 16.7 ms | 0.0 % (0.0–0.3) | 2.4 % (1.0–2.7) | 7.9 % (7.1–9.3) |
+| Scroll frames over 33 ms | 0.0 % | 0.0 % (0.0–0.3) | 6.4 % (5.4–7.0) |
+| … over 16.7 ms while scrolling steadily | 0.0 % | 0.6 % (0.0–1.7) | 0.0 % (0.0–0.6) |
+| … over 16.7 ms during the jumps | 0.0 % (0.0–0.8) | 4.3 % (1.7–6.2) | 22.7 % (20.2–26.1) |
+| Long tasks during scroll ¹ | 0 | – | – |
+| Longest task during a sort ¹ | 155 ms (144–160) | – | – |
+| JS heap for the grid ¹ | 10.4 MB | – | – |
+| Row elements in the DOM, end of scroll | 76 | 76 | 76 |
+| Cells in the DOM, end of scroll | 912 | 912 | 912 |
+| Row elements in the DOM, at rest | 19 | 19 | 19 |
+| Reach: last row on screen at the bottom | all rows | all rows | all rows |
+
+#### 500,000 rows, 52 px rows
+
+| Metric | Chromium | Firefox | WebKit |
+| :--- | ---: | ---: | ---: |
+| Mount | 295 ms (287–307) | 482 ms (473–505) | 402 ms (338–463) |
+| Sort, number column | 493 ms (485–567) | 660 ms (629–936) | 483 ms (413–564) |
+| Sort, string column | 641 ms (600–807) | 1,105 ms (1,045–1,188) | 1,407 ms (1,203–1,568) |
+| Filter, string `contains` | 59 ms (51–67) | 63 ms (56–68) | 75 ms (72–87) |
+| Filter, number `>` | 80 ms (70–111) | 100 ms (92–111) | 89 ms (77–101) |
+| Quick filter, one term | 958 ms (836–976) | 1,565 ms (1,503–1,828) | 1,442 ms (1,275–1,619) |
+| Group by region + `sum` | 331 ms (307–338) | 641 ms (419–675) | 386 ms (351–1,244) |
+| Scroll frame time p50 | 16.7 ms | 16.7 ms | 17.0 ms |
+| Scroll frame time p95 | 17.6 ms (17.5–17.6) | 17.5 ms (17.5–17.6) | 45.0 ms (44.0–46.0) |
+| Scroll frame time p99 | 17.7 ms (17.6–17.7) | 17.6 ms (17.6–17.7) | 49.0 ms (46.0–50.0) |
+| Scroll frames over 16.7 ms | 0.0 % (0.0–0.7) | 0.0 % | 7.7 % (7.6–10.1) |
+| Scroll frames over 33 ms | 0.0 % (0.0–0.3) | 0.0 % | 7.3 % (5.8–7.8) |
+| … over 16.7 ms while scrolling steadily | 0.0 % | 0.0 % | 0.0 % (0.0–1.1) |
+| … over 16.7 ms during the jumps | 0.0 % (0.0–1.8) | 0.0 % | 23.1 % (20.6–28.4) |
+| Long tasks during scroll ¹ | 0 | – | – |
+| Longest task during a sort ¹ | 635 ms (595–799) | – | – |
+| JS heap for the grid ¹ | 39.4 MB | – | – |
+| Row elements in the DOM, end of scroll | 76 | 22 | 76 |
+| Cells in the DOM, end of scroll | 912 | 264 | 912 |
+| Row elements in the DOM, at rest | 19 | 19 | 19 |
+| Reach: last row on screen at the bottom | all rows | 24 (<0.1 %) | all rows |
+
+#### 1,000,000 rows, 52 px rows
+
+| Metric | Chromium | Firefox | WebKit |
+| :--- | ---: | ---: | ---: |
+| Mount | 688 ms (673–715) | 1,097 ms (1,011–1,503) | 589 ms (576–735) |
+| Sort, number column | 1,105 ms (1,094–1,140) | 1,540 ms (1,477–1,795) | 1,023 ms (956–1,075) |
+| Sort, string column | 1,316 ms (1,227–1,463) | 2,434 ms (2,371–2,716) | 2,913 ms (2,715–3,277) |
+| Filter, string `contains` | 95 ms (87–152) | 100 ms (90–108) | 102 ms (102–112) |
+| Filter, number `>` | 144 ms (129–149) | 192 ms (175–237) | 136 ms (123–242) |
+| Quick filter, one term | 1,845 ms (1,761–1,977) | 3,161 ms (2,920–3,327) | 2,914 ms (2,762–3,272) |
+| Group by region + `sum` | 681 ms (664–703) | 1,754 ms (1,695–2,059) | 764 ms (720–901) |
+| Scroll frame time p50 | 16.7 ms | 16.7 ms | 17.0 ms |
+| Scroll frame time p95 | 17.4 ms (17.4–17.6) | 17.6 ms (17.4–17.6) | 44.0 ms (44.0–46.0) |
+| Scroll frame time p99 | 17.7 ms (17.6–17.7) | 17.6 ms (17.6–17.7) | 46.0 ms (45.0–48.0) |
+| Scroll frames over 16.7 ms | 0.0 % (0.0–0.7) | 0.0 % (0.0–0.3) | 7.2 % (7.1–9.3) |
+| Scroll frames over 33 ms | 0.0 % | 0.0 % | 7.0 % (6.5–7.1) |
+| … over 16.7 ms while scrolling steadily | 0.0 % | 0.0 % (0.0–0.6) | 0.0 % |
+| … over 16.7 ms during the jumps | 0.0 % (0.0–1.7) | 0.0 % | 20.8 % (20.0–28.1) |
+| Long tasks during scroll ¹ | 0 | – | – |
+| Longest task during a sort ¹ | 1,307 ms (1,220–1,455) | – | – |
+| JS heap for the grid ¹ | 79.1 MB | – | – |
+| Row elements in the DOM, end of scroll | 77 | 22 | 77 |
+| Cells in the DOM, end of scroll | 924 | 264 | 924 |
+| Row elements in the DOM, at rest | 19 | 19 | 19 |
+| Reach: last row on screen at the bottom | 645,277 (64.5 %) | 24 (<0.1 %) | 645,277 (64.5 %) |
+
+#### 1,000,000 rows, 32 px rows
+
+| Metric | Chromium | Firefox | WebKit |
+| :--- | ---: | ---: | ---: |
+| Mount | 674 ms (668–680) | 1,106 ms (1,032–1,329) | 604 ms (585–621) |
+| Sort, number column | 1,143 ms (1,090–1,254) | 1,475 ms (1,462–1,837) | 1,077 ms (986–1,137) |
+| Sort, string column | 1,295 ms (1,236–1,456) | 2,517 ms (2,268–2,675) | 2,758 ms (2,720–2,947) |
+| Filter, string `contains` | 92 ms (91–109) | 99 ms (99–109) | 107 ms (106–121) |
+| Filter, number `>` | 137 ms (133–140) | 206 ms (172–232) | 140 ms (126–161) |
+| Quick filter, one term | 1,818 ms (1,651–1,855) | 2,960 ms (2,910–3,200) | 2,750 ms (2,677–2,776) |
+| Group by region + `sum` | 694 ms (673–758) | 2,071 ms (1,224–2,745) | 749 ms (689–798) |
+| Scroll frame time p50 | 16.7 ms | 16.7 ms | 17.0 ms |
+| Scroll frame time p95 | 17.5 ms (17.5–18.5) | 17.5 ms (17.3–17.5) | 49.0 ms (48.0–49.0) |
+| Scroll frame time p99 | 17.6 ms (17.6–18.7) | 17.6 ms (17.6–17.7) | 52.0 ms (51.0–52.0) |
+| Scroll frames over 16.7 ms | 0.0 % (0.0–0.3) | 0.0 % (0.0–0.3) | 15.5 % (15.4–15.8) |
+| Scroll frames over 33 ms | 0.0 % | 0.0 % | 7.7 % (7.7–7.8) |
+| … over 16.7 ms while scrolling steadily | 0.0 % (0.0–0.6) | 0.0 % (0.0–0.6) | 0.0 % (0.0–0.6) |
+| … over 16.7 ms during the jumps | 0.0 % | 0.0 % | 51.3 % (50.6–53.3) |
+| Long tasks during scroll ¹ | 0 | – | – |
+| Longest task during a sort ¹ | 1,286 ms (1,229–1,436) | – | – |
+| JS heap for the grid ¹ | 79.5 MB | – | – |
+| Row elements in the DOM, end of scroll | 86 | 32 | 86 |
+| Cells in the DOM, end of scroll | 1,032 | 384 | 1,032 |
+| Row elements in the DOM, at rest | 28 | 28 | 28 |
+| Reach: last row on screen at the bottom | all rows | 33 (<0.1 %) | all rows |
+
+#### Reach: rows that can be scrolled into view
+
+| Rows × row height | Content height | Chromium | Firefox | WebKit |
+| :--- | ---: | ---: | ---: | ---: |
+| 10,000 × 52 px | 520,000 px | all | all | all |
+| 100,000 × 52 px | 5,200,000 px | all | all | all |
+| 500,000 × 52 px | 26,000,000 px | all | 24 (<0.1 %) | all |
+| 1,000,000 × 52 px | 52,000,000 px | 645,277 (64.5 %) | 24 (<0.1 %) | 645,277 (64.5 %) |
+| 1,000,000 × 32 px | 32,000,000 px | all | 33 (<0.1 %) | all |
+<!-- bench:end -->
+
+### Reach: the browser height ceiling
+
+The grid makes its scroll area as tall as all the rows: `rowCount × rowHeight` pixels. It does not compress scroll positions, so every row keeps its real offset. Browsers limit how tall an element can be, and the *Reach* rows above report the last row that actually appears on screen after scrolling to the very bottom:
+
+- **Chromium and WebKit** stop the element at 33,554,428 px. Everything above that is reachable, everything below is not. At 52 px that is 645,277 rows, so 1M rows at 52 px reach 64.5 %. At 32 px (`density="compact"`), 1M rows need 32,000,000 px and are all reachable.
+- **Firefox** has a lower limit, about 17.9M px, and handles it differently: an element taller than that collapses instead of stopping at the limit. On 3.5.0, which these tables were measured on, the grid then had nothing to scroll: 500k rows at 52 px (26M px) and 1M rows at either height showed only their first screen of rows (24 or 33 rows). **3.5.1 fixes this**: the grid caps its scroll content to the limit it measures, so Firefox reaches about 344,000 rows at 52 px and 559,000 at 32 px, like Chromium and WebKit reach theirs.
+
+If you need more rows than this in one scrolling grid, page them (`pagination`), load them from the server (`paginationMode="server"`, or infinite scroll with a `dataSource`), or reduce the row height.
+
+### Rerun
+
+```bash
+npx playwright install chromium firefox webkit   # once
+npm run bench                                    # all engines, 10k/100k/500k/1M, about 30 min
+npm run bench -- --quick                         # 1 run per size, no 500k, a few minutes
+npm run bench -- --rows 100000 --engine firefox  # one size, one engine
+node bench/report.mjs                            # Markdown tables of the newest results file
+```
+
+Results are written to `bench/results/<date>-<machine>.json` with the machine, browser versions and package version. Close other heavy programs first and keep a laptop on power. More options: [Testing → The benchmark](contributing/testing.md#the-benchmark). A weekly CI job runs a quick Chromium pass and keeps the JSON as a build artifact; CI machines are shared and noisy, so it is for spotting trends, not for comparing with these numbers.
+
 ## Related
 
 - [Virtualization](./features/virtualization.md)
 - [Server-Side Data](./features/data-source.md)
 - [Sorting & Pagination](./features/sorting-pagination.md)
 - [Infinite Scroll](./features/infinite-scroll.md)
+- [Testing → The benchmark](./contributing/testing.md#the-benchmark)

package/docs/roadmap.md

@@ -89,7 +89,7 @@ This document tracks the current status of features in `OpenGridX` and outlines
 
 ### Across the quarter
 
-*   **Published benchmark**: reproducible 100k / 1M-row numbers (scroll frame rate, sort and filter time, memory) in `docs/performance.md`.
+*   ✅ **Published benchmark** (done 9 Oct): reproducible 10k / 100k / 500k / 1M-row numbers (scroll frame times, sort, filter and grouping time, memory, the reachable row) in [`docs/performance.md`](performance.md#benchmarks); rerun with `npm run bench`.
 *   **Next.js App Router guide**: using the grid from a `'use client'` component, with the stylesheet in `app/layout.tsx`.
 *   **RTL check**: verify right-to-left layouts and document the result.
 *   **Demo site**: source viewer on all examples (`DocsLayout` with Vite `?raw`) and syntax highlighting, done alongside each release's demo page.

package/lib/components/DataGrid/DataGrid.tsx

@@ -4,6 +4,8 @@ import { useGridKeyboardNavigation } from '../../hooks/core/useGridKeyboardNavig
 import { useGridControlledState } from '../../hooks/core/useGridControlledState';
 import { useGridThemeDimensions } from '../../hooks/core/useGridThemeDimensions';
 import { useGridRowPipeline, type GridRowPipelineResult } from '../../hooks/core/useGridRowPipeline';
+import { useGridMaxContentHeight } from '../../hooks/core/useGridMaxContentHeight';
+import { countReachableRows } from '../../utils/maxElementHeight';
 import { useGridVirtualization } from '../../hooks/core/useGridVirtualization';
 import { useGridColumns } from '../../hooks/core/useGridColumns';
 import { useGridVisibleRows } from '../../hooks/core/useGridVisibleRows';
@@ -585,12 +587,14 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         onRowsScrollEnd, overscanRowCount, rowCount: layout.unpinnedRowsLength, autoHeight, setDimensions, viewportRef,
     });
 
+    const maxContentHeight = useGridMaxContentHeight(containerRef);
     const virtualization = useGridVirtualization({
         layout, scrollTop, scrollLeft,
         viewportWidth: state.dimensions.viewportWidth,
         viewportHeight: state.dimensions.viewportHeight,
         autoHeight, rowReordering, hasDetailPanel, checkboxSelection, pinCheckboxColumn, pinExpandColumn,
         overscanRows,
+        maxContentHeight: maxContentHeight ?? Infinity,
     });
 
 
@@ -743,6 +747,9 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         totalRowCount: pinnedTopRows.length + centerRows.length + pinnedBottomRows.length,
         pinnedRowsIgnored: isHierarchyEnabled && Boolean(pinnedRows?.top?.length || pinnedRows?.bottom?.length),
         scrollHeight: virtualization.totalHeight,
+        maxContentHeight,
+        reachableRowCount: countReachableRows(virtualization.cumulativeHeights, virtualization.virtualContainerHeight),
+        unpinnedRowCount: virtualization.cumulativeHeights.length,
         listViewWithoutColumn: listViewRequested && !listViewColumn,
         listViewRowCount: listView && listViewColumn ? allRenderableRows.length : 0,
     });
@@ -1008,7 +1015,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
 
                         <GridVirtualRows<R>
                             {...rowRenderProps}
-                            virtualContainerHeight={virtualization.totalHeight - virtualization.pinnedTopHeight - virtualization.pinnedBottomHeight}
+                            virtualContainerHeight={virtualization.virtualContainerHeight}
                             offsetTop={spanRowWindow.offsetTop}
                             effectiveLoading={effectiveLoading}
                             visibleRows={visibleRows}

package/lib/hooks/core/useGridDevWarnings.ts

@@ -10,8 +10,16 @@ export interface UseGridDevWarningsParams {
     totalRowCount: number;
     /** `pinnedRows` is set while tree data or row grouping is active, where it has no effect. */
     pinnedRowsIgnored?: boolean;
-    /** Pixel height of the scrollable content. */
+    /** Pixel height of the scrollable content, uncapped. */
     scrollHeight?: number;
+    /**
+     * The tallest element the browser lays out (`getMaxElementHeight`): `undefined` until measured (the warning
+     * waits), `Infinity` where there is no layout engine (the lowest known cap is used).
+     */
+    maxContentHeight?: number;
+    /** Unpinned rows the user can scroll to, and how many unpinned rows there are. */
+    reachableRowCount?: number;
+    unpinnedRowCount?: number;
     /** `listView` is set but `listViewColumn` is not, so the grid view is shown. */
     listViewWithoutColumn?: boolean;
     /** Number of items the list view renders (0 when the list view is not shown). It does not virtualize. */
@@ -31,7 +39,7 @@ export const LIST_VIEW_WARN_THRESHOLD = 2000;
 export const MAX_SCROLLABLE_HEIGHT = 17_800_000;
 
 export function useGridDevWarnings(params: UseGridDevWarningsParams): void {
-    const { paginationRequested, isRowGrouping, autoHeight, viewportHeight, renderedRowCount, totalRowCount, pinnedRowsIgnored = false, scrollHeight = 0, listViewWithoutColumn = false, listViewRowCount = 0 } = params;
+    const { paginationRequested, isRowGrouping, autoHeight, viewportHeight, renderedRowCount, totalRowCount, pinnedRowsIgnored = false, scrollHeight = 0, maxContentHeight, reachableRowCount, unpinnedRowCount, listViewWithoutColumn = false, listViewRowCount = 0 } = params;
     const warnedPaginationRef = useRef(false);
     const warnedUnboundedRef = useRef(false);
     const warnedPinnedRowsRef = useRef(false);
@@ -67,14 +75,21 @@ export function useGridDevWarnings(params: UseGridDevWarningsParams): void {
     }, [pinnedRowsIgnored]);
 
     useEffect(() => {
-        if (process.env.NODE_ENV === 'production' || warnedHeightRef.current || scrollHeight <= MAX_SCROLLABLE_HEIGHT) return;
+        if (process.env.NODE_ENV === 'production' || warnedHeightRef.current || maxContentHeight === undefined) return;
+        const measured = Number.isFinite(maxContentHeight);
+        // Once the browser's cap is measured, warn only when rows are actually cut off; before that (and
+        // where there is no layout engine) fall back to the lowest known cap.
+        if (measured ? scrollHeight <= maxContentHeight : scrollHeight <= MAX_SCROLLABLE_HEIGHT) return;
         warnedHeightRef.current = true;
+        const reach = measured && reachableRowCount !== undefined && unpinnedRowCount !== undefined
+            ? `Only the first ${reachableRowCount.toLocaleString('en-US')} of ${unpinnedRowCount.toLocaleString('en-US')} rows can be scrolled to in this browser. `
+            : 'The last rows may not be reachable by scrolling. ';
         console.warn(
-            `[OpenGridX] The grid content is ${Math.round(scrollHeight)}px tall. Browsers cap element heights ` +
-            '(about 17.9M px in Firefox, 33.5M px in Chrome and Safari), so the last rows may not be reachable by scrolling. ' +
+            `[OpenGridX] The grid content is ${Math.round(scrollHeight)}px tall, more than this browser lays out ` +
+            '(about 17.9M px in Firefox, 33.5M px in Chrome and Safari). ' + reach +
             'Use pagination, server-side or infinite loading, or a smaller rowHeight. See docs/features/virtualization.md.'
         );
-    }, [scrollHeight]);
+    }, [scrollHeight, maxContentHeight, reachableRowCount, unpinnedRowCount]);
 
     useEffect(() => {
         if (process.env.NODE_ENV === 'production' || warnedPaginationRef.current) return;

package/lib/hooks/core/useGridMaxContentHeight.ts

@@ -0,0 +1,16 @@
+import { useLayoutEffect, useState } from 'react';
+import type { RefObject } from 'react';
+import { getMaxElementHeight } from '../../utils/maxElementHeight';
+
+/**
+ * The tallest element this browser lays out (see `getMaxElementHeight`), measured once per document after
+ * mount: `undefined` until measured, `Infinity` where there is no layout engine (jsdom, SSR).
+ */
+export function useGridMaxContentHeight(containerRef: RefObject<HTMLElement | null>): number | undefined {
+    const [maxHeight, setMaxHeight] = useState<number | undefined>(undefined);
+    useLayoutEffect(() => {
+        const measured = getMaxElementHeight(containerRef.current?.ownerDocument);
+        setMaxHeight(prev => (prev === measured ? prev : measured));
+    }, [containerRef]);
+    return maxHeight;
+}

package/lib/hooks/core/useGridVirtualization.ts

@@ -16,6 +16,11 @@ export interface UseGridVirtualizationParams<R extends GridRowModel> {
     pinExpandColumn: boolean;
     /** Adaptive overscan row count from useGridScrollSync. Defaults to 5. */
     overscanRows?: number;
+    /**
+     * The tallest element the browser lays out (`getMaxElementHeight`); the scrollable content is capped to
+     * it. Defaults to no cap.
+     */
+    maxContentHeight?: number;
 }
 
 export interface GridVirtualizationResult<R extends GridRowModel = GridRowModel> {
@@ -28,6 +33,11 @@ export interface GridVirtualizationResult<R extends GridRowModel = GridRowModel>
     offsetTop: number;
     offsetLeft: number;
     totalHeight: number;
+    /**
+     * Height of the unpinned rows' container: their full height, capped so the whole content stays under
+     * `maxContentHeight`. Rows below the cap cannot be scrolled to (the dev warning names how many can).
+     */
+    virtualContainerHeight: number;
     pinnedTopHeight: number;
     pinnedBottomHeight: number;
     totalWidth: number;
@@ -60,6 +70,7 @@ export function useGridVirtualization<R extends GridRowModel>(
         pinCheckboxColumn,
         pinExpandColumn,
         overscanRows = 5,
+        maxContentHeight = Infinity,
     } = params;
 
     return useMemo<GridVirtualizationResult<R>>(() => {
@@ -122,6 +133,12 @@ export function useGridVirtualization<R extends GridRowModel>(
         const hasHorizontalScroll = viewportWidth > 0 && totalWidth > viewportWidth;
         const scrollbarBuffer = hasHorizontalScroll ? 16 : 0;
         const totalHeight = pinnedTopHeight + unpinnedRowsHeight + pinnedBottomHeight + scrollbarBuffer + 2;
+        // Firefox collapses an element taller than its cap (about 17.9M px) instead of clamping it, which
+        // made a large grid unscrollable there; keep the rows' container under the browser's cap.
+        const fullContainerHeight = totalHeight - pinnedTopHeight - pinnedBottomHeight;
+        const virtualContainerHeight = Number.isFinite(maxContentHeight)
+            ? Math.max(0, Math.min(fullContainerHeight, maxContentHeight - pinnedTopHeight - pinnedBottomHeight))
+            : fullContainerHeight;
 
         let firstRowIndex = 0;
         let lastRowIndex  = unpinnedRowsLength - 1;
@@ -157,6 +174,7 @@ export function useGridVirtualization<R extends GridRowModel>(
             offsetTop,
             offsetLeft: 0,
             totalHeight,
+            virtualContainerHeight,
             pinnedTopHeight,
             pinnedBottomHeight,
             totalWidth,
@@ -185,5 +203,6 @@ export function useGridVirtualization<R extends GridRowModel>(
         pinCheckboxColumn,
         pinExpandColumn,
         overscanRows,
+        maxContentHeight,
     ]);
 }

package/lib/utils/maxElementHeight.ts

@@ -0,0 +1,53 @@
+/**
+ * The tallest element this browser lays out. Browsers cap element heights: Chromium and Safari at
+ * about 33.5M px, Firefox at about 17.9M px. Firefox does not clamp an element that is taller — it
+ * collapses it, so a grid whose content is taller than the cap cannot be scrolled at all.
+ *
+ * Measured once per document with an invisible probe (one layout), from the largest candidate down.
+ * Returns `Infinity` where there is no layout engine (jsdom, SSR), so nothing is capped there.
+ */
+const CANDIDATES = [33_554_400, 17_895_000, 10_000_000, 5_000_000] as const;
+
+const cache = new WeakMap<Document, number>();
+
+function measure(doc: Document): number {
+    const body = doc.body;
+    if (!body) return Infinity;
+    const probe = doc.createElement('div');
+    probe.setAttribute('aria-hidden', 'true');
+    probe.style.cssText = 'position:absolute;top:0;left:-10000px;width:1px;visibility:hidden;pointer-events:none;';
+    body.appendChild(probe);
+    try {
+        probe.style.height = '100px';
+        // No layout engine: every element reads 0 tall.
+        if (Math.abs(probe.getBoundingClientRect().height - 100) > 1) return Infinity;
+        for (const height of CANDIDATES) {
+            probe.style.height = `${height}px`;
+            if (Math.abs(probe.getBoundingClientRect().height - height) < 2) return height;
+        }
+        return CANDIDATES[CANDIDATES.length - 1];
+    } finally {
+        probe.remove();
+    }
+}
+
+export function getMaxElementHeight(doc: Document | null | undefined): number {
+    if (!doc) return Infinity;
+    const known = cache.get(doc);
+    if (known !== undefined) return known;
+    const height = measure(doc);
+    cache.set(doc, height);
+    return height;
+}
+
+/** How many of the unpinned rows end at or above `limit` px (the rows a user can scroll to). */
+export function countReachableRows(cumulativeHeights: readonly number[], limit: number): number {
+    if (!Number.isFinite(limit)) return cumulativeHeights.length;
+    let lo = 0;
+    let hi = cumulativeHeights.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (cumulativeHeights[mid] <= limit) lo = mid + 1; else hi = mid;
+    }
+    return lo;
+}

package/llms.txt

@@ -1,6 +1,6 @@
 # OpenGridX — AI Agent Context
 # Package: @opencorestack/opengridx
-# Version: 3.5.0
+# Version: 3.5.1
 # Docs: https://opencorestack.github.io/OpenGridX/
 # This file is machine-readable. AI developers: start here.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencorestack/opengridx",
-  "version": "3.5.0",
+  "version": "3.5.1",
   "description": "OpenGridX: High-performance React data infrastructure. Unlock advanced Row Grouping, Excel Export, and Column Pinning without the usual \"Pro\" gatekeeping. Built for speed, scale, and complete architectural freedom. Fully open, virtualization-ready, and feature-complete.",
   "type": "module",
   "main": "./dist/opengridx.umd.js",
@@ -53,12 +53,13 @@
     "build": "tsc --project tsconfig.build.json && vite build",
     "build:lib": "tsc --project tsconfig.build.json && vite build --config vite.config.lib.js && vite build --config vite.config.lib.js --mode ai && cp lib/styles/opengridx.css.d.ts dist/opengridx.css.d.ts && node scripts/check-bundle.mjs",
     "lint": "eslint .",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit && tsc -p e2e/tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit && tsc -p e2e/tsconfig.json && tsc -p bench/tsconfig.json",
     "preview": "vite preview",
     "test": "vitest run --project unit",
     "test:browser": "vitest run --project browser",
     "test:all": "vitest run",
     "test:smoke": "node scripts/smoke.mjs",
+    "bench": "node bench/run.mjs",
     "test:watch": "vitest --project unit",
     "coverage": "vitest run --coverage",
     "prepublishOnly": "npm run build:lib",