demo: Add benchmark-react with normalization and ref-stability scenarios

- Browser benchmark comparing @data-client/react (Playwright, customSmallerIsBetter).
- Scenarios: mount, update entity/author, ref-stability (item/author ref counts).
- Hot-path (CI) vs with-network (local): simulated delay for overfetch comparison.
- CI workflow runs hot-path only; reports to rhysd/github-action-benchmark.

Made-with: Cursor

Author: ntucker

.github/workflows/benchmark-react.yml

@@ -0,0 +1,89 @@
+name: Benchmark React
+
+on:
+  pull_request:
+    branches:
+      - master
+    paths:
+      - 'packages/react/src/**'
+      - 'packages/core/src/**'
+      - 'examples/benchmark-react/**'
+      - '.github/workflows/benchmark-react.yml'
+  push:
+    branches:
+      - master
+    paths:
+      - 'packages/react/src/**'
+      - 'packages/core/src/**'
+      - 'examples/benchmark-react/**'
+      - '.github/workflows/benchmark-react.yml'
+
+jobs:
+  benchmark-react:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: 'yarn'
+      - name: Install packages
+        run: |
+          corepack enable
+          yarn install --immutable
+      - name: Install Playwright (Chromium + system deps)
+        run: npx playwright install chromium --with-deps
+      - name: Build packages
+        run: yarn build:benchmark-react
+      - name: Run benchmark
+        run: |
+          yarn workspace example-benchmark-react preview &
+          sleep 10
+          cd examples/benchmark-react && yarn bench | tee react-bench-output.json
+
+      # PR comments on changes
+      - name: Download previous benchmark data (PR)
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: actions/cache@v5
+        with:
+          path: ./cache
+          key: ${{ runner.os }}-benchmark-react-pr-${{ github.run_number }}
+          restore-keys: |
+            ${{ runner.os }}-benchmark-react
+      - name: Store benchmark result (PR)
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: rhysd/github-action-benchmark@v1
+        with:
+          tool: 'customSmallerIsBetter'
+          output-file-path: examples/benchmark-react/react-bench-output.json
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+          gh-pages-branch: 'gh-pages-bench'
+          benchmark-data-dir-path: react-bench
+          alert-threshold: '150%'
+          comment-always: true
+          fail-on-alert: false
+          alert-comment-cc-users: '@ntucker'
+          save-data-file: false
+          auto-push: false
+
+      # master reports to history
+      - name: Download previous benchmark data (main)
+        if: ${{ github.event_name == 'push' }}
+        uses: actions/cache@v5
+        with:
+          path: ./cache
+          key: ${{ runner.os }}-benchmark-react
+      - name: Store benchmark result (main)
+        if: ${{ github.event_name == 'push' }}
+        uses: rhysd/github-action-benchmark@v1
+        with:
+          tool: 'customSmallerIsBetter'
+          output-file-path: examples/benchmark-react/react-bench-output.json
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+          gh-pages-branch: 'gh-pages-bench'
+          benchmark-data-dir-path: react-bench
+          auto-push: true
+          fail-on-alert: false

examples/benchmark-react/.babelrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [['@anansi', { polyfillMethod: false }]],
+};

examples/benchmark-react/PLAN.md

@@ -0,0 +1,61 @@
+# React Rendering Benchmark – Future Work
+
+Follow this plan in later sessions to extend the benchmark suite.
+
+---
+
+## Session 2: Competitor implementations
+
+Add apps that implement the same `BenchAPI` (`window.__BENCH__`) and use the same presentational components so results are comparable.
+
+- **`apps/tanstack-query/`** (or `src/tanstack-query/` if keeping single webpack entry)
+  - Use `@tanstack/react-query` with `useQuery` and `queryClient.setQueryData` for cache seeding.
+  - Same scenarios: mount N items, update single entity.
+- **`apps/swr/`**
+  - Use `swr` with `mutate` for cache seeding.
+- **`apps/baseline/`**
+  - Plain `useState` + `useContext`, no caching library (baseline).
+
+**Deliverables:** Each app exposes the same `window.__BENCH__` interface and uses the same `ItemRow` (or shared) presentational component. Extend webpack to multi-entry so each app is built and served at e.g. `/data-client/`, `/tanstack-query/`, etc. Update `bench/runner.ts` and `bench/scenarios.ts` to iterate over all libraries and report per-library results.
+
+---
+
+## Session 3: Entity update propagation (normalization showcase) — Done
+
+Implemented:
+
+- **`update-shared-author-duration`** — Mount 100 items (sharing 20 authors), update one author; measure duration (ms).
+- **Ref-stability scenarios** — `ref-stability-item-changed` and `ref-stability-author-changed` report how many components received a new object reference after an update (unit: count; smaller is better). data-client’s normalized cache keeps referential equality for unchanged entities, so these counts stay low (1 and ~25 respectively).
+- Shared `refStability` module and `BenchAPI.captureRefSnapshot` / `getRefStabilityReport` / `updateAuthor`; `getAuthor` endpoint and `FIXTURE_AUTHORS` for seeding.
+
+---
+
+## Session 4: Memory and scaling scenarios
+
+Add memory and stress scenarios.
+
+- **Memory under repeated operations:** Cycle mount → unmount N times; measure heap (e.g. `Performance.getMetrics` / JSHeapUsedSize via CDP) to detect growth.
+- **Many-subscriber scaling:** Mount 500+ components subscribed to overlapping entities; measure per-update cost (time and/or memory).
+- **Optimistic update + rollback:** Optimistic mutation, then simulate error and rollback; measure time to revert DOM.
+
+**Deliverables:** New scenarios in `bench/scenarios.ts`, optional `bench/memory.ts` for CDP heap collection, and report entries for memory metrics (e.g. `customSmallerIsBetter` with unit `bytes` where applicable).
+
+---
+
+## Session 5: Advanced measurement and reporting
+
+- **React Profiler:** Use `<Profiler onRender>` (and/or `performance.measure`) to record React commit duration as a separate metric alongside existing measures.
+- **Local HTML report:** Build a small report viewer (e.g. `bench/report-viewer.html` or a small app) that loads saved JSON and displays a table/charts for comparing libraries (similar to krausest results table).
+- **Lighthouse-style metrics:** Optionally add FCP, TBT, or other metrics for initial load comparison (e.g. via CDP or Lighthouse CI).
+
+**Deliverables:** Profiler instrumentation in app(s), report viewer, and optionally Lighthouse/load metrics in the runner and report format.
+
+---
+
+## Session 6: Polish and documentation
+
+- **README:** Expand with methodology (what we measure, why), how to add a new library, and how to run locally vs CI.
+- **Cursor rule:** Update `.cursor/rules/benchmarking.mdc` (or equivalent) to document the React benchmark: where it lives, how to run it, and how it relates to the existing Node `example-benchmark` suite.
+- **AGENTS.md:** If appropriate, add a short mention of the React benchmark and link to this plan or the README.
+
+**Deliverables:** Updated README, rule file, and any AGENTS.md changes.

examples/benchmark-react/README.md

@@ -0,0 +1,51 @@
+# React Rendering Benchmark
+
+Browser-based benchmark comparing `@data-client/react` (and future: TanStack Query, SWR, baseline) on mount/update scenarios. Built with Webpack via `@anansi/webpack-config`. Results are reported to CI via `rhysd/github-action-benchmark`.
+
+## Scenario categories
+
+- **Hot path (in CI)** — JS-only: mount, update propagation, ref-stability. No simulated network. These run in CI and track regression.
+- **With network (comparison only)** — Same shared-author update but with simulated network delay (consistent ms per "request"). Used to compare overfetching: data-client needs one store update (1 × delay); non-normalized libs typically invalidate/refetch multiple queries (N × delay). **Not run in CI** — run locally with `yarn bench` (no `CI` env) to include these.
+
+## Scenarios
+
+**Hot path (CI)**
+
+- **Mount** — Time to mount 100 or 500 item rows (unit: ms).
+- **Update single entity** — Time to update one item and propagate to the UI (unit: ms).
+- **Update shared author** (`update-shared-author-duration`) — 100 components, shared authors; update one author. Measures time to propagate (unit: ms). Normalized cache: one store update, all views of that author update.
+- **Ref-stability item/author** (`ref-stability-item-changed`, `ref-stability-author-changed`) — Count of components that received a **new** object reference after an update (unit: count; smaller is better). Normalization keeps referential equality for unchanged entities.
+
+**With network (local comparison)**
+
+- **Update shared author with network** (`update-shared-author-with-network`) — Same as above with a simulated delay (e.g. 50 ms) per "request." data-client uses 1 request; other libs can be compared with higher `simulatedRequestCount` to model overfetching.
+
+## Running locally
+
+1. **Install system dependencies (Linux / WSL)**  
+   Playwright needs system libraries to run Chromium. If you see “Host system is missing dependencies to run browsers”:
+
+   ```bash
+   sudo npx playwright install-deps chromium
+   ```
+
+   Or install manually (e.g. Debian/Ubuntu):
+
+   ```bash
+   sudo apt-get install libnss3 libnspr4 libasound2t64
+   ```
+
+2. **Build and run**
+
+   ```bash
+   yarn build:benchmark-react
+   yarn workspace example-benchmark-react preview &
+   sleep 5
+   cd examples/benchmark-react && yarn bench
+   ```
+
+   Or from repo root after a build: start preview in one terminal, then in another run `yarn workspace example-benchmark-react bench`.
+
+## Output
+
+The runner prints a JSON array in `customSmallerIsBetter` format (name, unit, value, range) to stdout. In CI this is written to `react-bench-output.json` and sent to the benchmark action.

examples/benchmark-react/bench/measure.ts

@@ -0,0 +1,32 @@
+import type { Page } from 'playwright';
+
+export interface PerformanceMeasure {
+  name: string;
+  duration: number;
+}
+
+/**
+ * Collect performance.measure() entries from the page.
+ */
+export async function collectMeasures(
+  page: Page,
+): Promise<PerformanceMeasure[]> {
+  return page.evaluate(() => {
+    const entries = performance.getEntriesByType('measure');
+    return entries.map(e => ({
+      name: e.name,
+      duration: e.duration,
+    }));
+  });
+}
+
+/**
+ * Get the duration for a specific measure name (e.g. 'mount-duration', 'update-duration').
+ */
+export function getMeasureDuration(
+  measures: PerformanceMeasure[],
+  name: string,
+): number {
+  const m = measures.find(x => x.name === name);
+  return m?.duration ?? 0;
+}

examples/benchmark-react/bench/report.ts

@@ -0,0 +1,13 @@
+/**
+ * Format results as customSmallerIsBetter JSON for rhysd/github-action-benchmark.
+ */
+export interface BenchmarkResult {
+  name: string;
+  unit: string;
+  value: number;
+  range: string;
+}
+
+export function formatReport(results: BenchmarkResult[]): string {
+  return JSON.stringify(results, null, 2);
+}