docs: changelog, roadmap and testing guide for the benchmark

Author: asif7774

CHANGELOG.md

@@ -5,6 +5,13 @@
 
 ---
 
+## [Unreleased]
+
+### Internal
+
+- **Large-dataset benchmark** — `npm run bench` (`bench/run.mjs`) packs the library, installs it into `bench/app` (a Vite + React 19 production app, like the smoke fixtures; port 4320) and measures it with Playwright in Chromium, Firefox and WebKit at 10k, 100k, 500k and 1M rows (1M also at 32 px): mount, sort, filter, quick filter, group + `sum`, a scripted 5 s scroll (frame-time percentiles and missed frames), DOM size, the furthest reachable row, and long tasks and JS heap in Chromium. Times run from the call to the first painted frame showing the result; medians of 5 runs after a warm-up. `bench/report.mjs` writes the Markdown tables; results and method are in `docs/performance.md` → Benchmarks. Flags `--rows`, `--engine`, `--repeat`, `--quick`. The weekly workflow runs a Chromium `--quick` pass and uploads the JSON; it never fails on numbers. Packing and tarball install are shared with the smoke suite (`scripts/lib/package-fixture.mjs`).
+- **Docs: the browser height limit, as measured** — `docs/performance.md`, `docs/features/virtualization.md` and the README now give the benchmark's numbers instead of unmeasured claims ("60fps for 100k+ rows"), and correct the Firefox limit: past about 17.9M px of content (about 344,000 rows at 52 px) Firefox does not stop at the cap like Chromium and WebKit; the content collapses and the grid does not scroll at all.
+
 ## [3.5.0] — 2026-10-09
 
 ### Added

docs/contributing/testing.md

@@ -8,7 +8,7 @@ Three layers, from fastest to closest to a real consumer.
 | `npm run test:browser` | Vitest browser mode in real Chromium, Firefox and WebKit | `lib/**/*.browser.test.ts(x)` |
 | `npm run test:smoke` | Package smoke suite: Playwright Test against apps that installed the packed tarball | `e2e/` |
 
-Other gates: `npm run lint`, `npm run typecheck` (lib, tests, demo, e2e), `npm run build:lib` (also checks that React stays external).
+Other gates: `npm run lint`, `npm run typecheck` (lib, tests, demo, e2e, bench), `npm run build:lib` (also checks that React stays external).
 
 React Compiler compatibility: `npm run check:compiler`, and `REACT_COMPILER=1` in front of any Vitest command runs it against `lib/` compiled. See [React Compiler compatibility](react-compiler.md).
 
@@ -52,8 +52,28 @@ npx playwright show-report playwright-report           # HTML report, traces of
 
 The fixtures are separate npm projects: they are not part of the root lint, typecheck or Vitest runs and install into their own `node_modules`. When you change a fixture's dependencies, run `npm install` in it and then delete the `integrity` field from the `node_modules/@opencorestack/opengridx` entry of its `package-lock.json` (the tarball changes on every build; the script refuses a lockfile that pins it).
 
+## The benchmark
+
+`npm run bench` (`bench/run.mjs`) measures the grid at 10k, 100k, 500k and 1M rows. It is a measuring tool, not a test: nothing fails on a number. The method and the published results are in [Performance → Benchmarks](../performance.md#benchmarks).
+
+1. Packs the library the same way as the smoke suite (`scripts/lib/package-fixture.mjs`) and installs it into `bench/app`, a Vite + React 19 app with its own lockfile (same rule: no `integrity` on the tarball entry).
+2. Builds the app for production (strict `tsc`, then `vite build`) and serves it with `vite preview` on port 4320.
+3. Drives it with Playwright (headless, 1280×800), one new browser context per run, and writes `bench/results/<date>-<machine>.json`.
+
+```bash
+npm run bench                                        # all engines, 10k/100k/500k/1M, 5 runs + 1 warm-up (about 30 min)
+npm run bench -- --quick                             # 1 run, no warm-up, no 500k
+npm run bench -- --rows 100000,1000000 --engine chromium
+npm run bench -- --repeat 5,1000000:3                # fewer runs for one size
+npm run bench -- --skip-build                        # reuse the built bench/app
+node bench/report.mjs                                # Markdown tables of the newest full results file
+node bench/report.mjs --write docs/performance.md    # replace the tables in docs/performance.md
+```
+
+Close other heavy programs first and keep the machine on power; the runner records the load average at the start and end and warns when it is high. Commit a results file only from a full run, and regenerate the tables in `docs/performance.md` from it. `bench/` is outside ESLint and the Vitest projects; `npm run typecheck` checks its TypeScript (`bench/tsconfig.json`, resolving the package to `lib/`).
+
 ## CI
 
 - `.github/workflows/ci.yml` (pull requests and pushes to branches other than `main`): lint, typecheck, unit, browser tests, `build:lib`, smoke suite. Playwright reports and traces are uploaded when a step fails.
 - `npm-publish.yml` runs the smoke suite after `build:lib` and before `npm publish`.
-- `nightly.yml` runs weekly: all Vitest projects and the smoke suite with `--fresh`.
+- `nightly.yml` runs weekly: all Vitest projects and the smoke suite with `--fresh`, and a separate `bench` job (`npm run bench -- --quick --engine chromium`) that puts the tables in the job summary and uploads the JSON as the `bench-results` artifact. It fails only when the benchmark script breaks, never on timings.

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.