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

.cursor/rules/benchmarking.mdc

@@ -1,12 +1,79 @@
 ---
-description: Benchmarking guidelines using examples/benchmark (suite selection, commands, and what packages are exercised)
-globs: examples/benchmark/**, .github/workflows/benchmark.yml, packages/normalizr/src/**, packages/core/src/**, packages/endpoint/src/schemas/**
+description: Benchmarking guidelines using examples/benchmark and examples/benchmark-react (suite selection, commands, and what packages are exercised)
+globs: examples/benchmark/**, examples/benchmark-react/**, .github/workflows/benchmark.yml, .github/workflows/benchmark-react.yml, packages/normalizr/src/**, packages/core/src/**, packages/endpoint/src/schemas/**, packages/react/src/**
 alwaysApply: false
 ---
 
-# Benchmarking (`@examples/benchmark`)
+# Benchmarking
 
-When working on performance investigations or changes that might impact performance, use **`@examples/benchmark`** as the canonical benchmark harness.
+## Node benchmark (`@examples/benchmark`)
+
+When working on performance investigations or changes that might impact **core, normalizr, or endpoint** (no browser, no React), use **`@examples/benchmark`** as the canonical harness.
+
+## React benchmark (`@examples/benchmark-react`)
+
+When working on **`packages/react`** or comparing data-client to other React data libraries (TanStack Query, SWR, baseline), use **`@examples/benchmark-react`**.
+
+- **Where it lives**: `examples/benchmark-react/`
+- **How to run**: From repo root: `yarn build:benchmark-react`, then `yarn workspace example-benchmark-react preview &` and in another terminal `cd examples/benchmark-react && yarn bench`
+- **What it measures**: Browser-based init/update duration, ref-stability counts, sorted-view (Query memoization), optional memory (heap delta), startup metrics (FCP/TBT), and React Profiler commit times. Compares data-client, TanStack Query, SWR, and a plain React baseline.
+- **CI**: `.github/workflows/benchmark-react.yml` runs on changes to `packages/react/src/**`, `packages/core/src/**`, `packages/endpoint/src/schemas/**`, `packages/normalizr/src/**`, or `examples/benchmark-react/**` and reports via `rhysd/github-action-benchmark` (customSmallerIsBetter). CI runs **data-client only** (hot-path scenarios) to track regressions; competitor libraries (TanStack Query, SWR, baseline) are for local comparison only.
+- **Report viewer**: Open `examples/benchmark-react/bench/report-viewer.html` in a browser and paste `react-bench-output.json` to view a comparison table and charts. Toggle "React commit" and "Trace" filters. Use "Load history" for time-series.
+
+See `@examples/benchmark-react/README.md` for methodology, adding a new library, and interpreting results.
+
+### Scenarios and what they exercise
+
+Use this mapping when deciding which React benchmark scenarios are relevant to a change:
+
+- **Get list scenarios** (`getlist-100`, `getlist-500`)
+  - Exercises: full fetch + normalization + render pipeline (ListView auto-fetches from list endpoint)
+  - Relevant for: `@data-client/react` hooks, `@data-client/core` store initialization
+  - All libraries
+
+- **Update propagation** (`update-single-entity`, `update-shared-author-500-mounted`, `update-shared-author-10000-mounted`)
+  - Exercises: store update → React rerender → DOM mutation
+  - Relevant for: `@data-client/core` dispatch/reducer, `@data-client/react` subscription/selector
+  - All libraries (normalization advantage shows with shared author at scale)
+
+- **Ref-stability** (`ref-stability-item-changed`, `ref-stability-author-changed`)
+  - Exercises: referential equality preservation through normalization
+  - Relevant for: `@data-client/normalizr` denormalize memoization, Entity identity
+  - All libraries (data-client should show fewest changed refs)
+
+- **Sorted/derived view** (`sorted-view-mount-500`, `sorted-view-update-entity`)
+  - Exercises: `Query` schema memoization via `useQuery` (data-client) vs `useMemo` sort (competitors)
+  - Relevant for: `@data-client/endpoint` Query, `@data-client/normalizr` MemoCache, `@data-client/react` useQuery
+  - All libraries
+
+- **Optimistic update** (`optimistic-update`) — data-client only
+  - Exercises: `getOptimisticResponse` + `controller.fetch` pipeline
+  - Relevant for: `@data-client/core` optimistic dispatch
+
+- **Invalidation** (`invalidate-and-resolve`) — data-client only
+  - Exercises: `controller.invalidate` → Suspense fallback → `controller.setResponse` re-resolve
+  - Relevant for: `@data-client/core` invalidation, `@data-client/react` Suspense integration
+
+### Expected variance
+
+| Category | Scenarios | Typical run-to-run spread |
+|---|---|---|
+| **Stable** | `getlist-*`, `update-single-entity`, `ref-stability-*`, `sorted-view-mount-*` | 2–5% |
+| **Moderate** | `update-shared-author-*`, `sorted-view-update-*` | 5–10% |
+| **Volatile** | `memory-mount-unmount-cycle`, `startup-*`, `(react commit)` suffixes | 10–25% |
+
+Regressions >5% on stable scenarios or >15% on volatile scenarios are worth investigating.
+
+### When to use Node vs React benchmark
+
+- **Core/normalizr/endpoint changes only** (no rendering impact): Run `examples/benchmark` (Node). Faster iteration, no browser needed.
+- **React hook or Provider changes**: Run `examples/benchmark-react`. Captures real rendering cost.
+- **Schema changes** (Entity, Query, All): Run both — Node benchmark for raw throughput, React benchmark for rendering impact.
+- **Performance investigation**: Start with Node benchmark to isolate the JS layer, then validate with React benchmark for end-to-end confirmation.
+
+---
+
+# Node benchmark details (`@examples/benchmark`)
 
 ## Optimization workflow
 

.github/workflows/benchmark-react.yml

@@ -0,0 +1,101 @@
+name: Benchmark React
+
+on:
+  pull_request:
+    branches:
+      - master
+    paths:
+      - 'packages/react/src/**'
+      - 'packages/core/src/**'
+      - 'packages/endpoint/src/schemas/**'
+      - 'packages/normalizr/src/**'
+      - 'examples/benchmark-react/**'
+      - '.github/workflows/benchmark-react.yml'
+  push:
+    branches:
+      - master
+    paths:
+      - 'packages/react/src/**'
+      - 'packages/core/src/**'
+      - 'packages/endpoint/src/schemas/**'
+      - 'packages/normalizr/src/**'
+      - 'examples/benchmark-react/**'
+      - '.github/workflows/benchmark-react.yml'
+
+concurrency:
+  group: ${{ github.event_name == 'push' && 'gh-pages-bench-react-push' || format('benchmark-react-{0}', github.head_ref) }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+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

.github/workflows/benchmark.yml

@@ -19,6 +19,14 @@ on:
       - 'packages/core/src/**'
       - 'examples/benchmark/**'
       - '.github/workflows/benchmark.yml'
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.event_name == 'push' && 'gh-pages-bench-node-push' || format('benchmark-node-{0}', github.head_ref) }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   benchmark:
 
@@ -48,7 +56,7 @@ jobs:
       uses: actions/cache@v5
       with:
         path: ./cache
-        key: ${{ runner.os }}-benchmark-pr-${{ env.GITHUB_RUN_NUMBER }}
+        key: ${{ runner.os }}-benchmark-pr-${{ github.run_number }}
         restore-keys: |
           ${{ runner.os }}-benchmark
     - name: Store benchmark result (PR)

.github/workflows/bundle_size.yml

@@ -17,6 +17,11 @@ on:
       - 'yarn.lock'
       - 'examples/test-bundlesize/**'
       - '.github/workflows/bundle_size.yml'
+
+concurrency:
+  group: bundle-size-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
 

.github/workflows/codeql-analysis.yml

@@ -27,6 +27,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: codeql-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   analyze:
     permissions:

.github/workflows/site-preview.yml

@@ -10,6 +10,11 @@ on:
       - 'website/**'
       - 'docs/**'
       - '.github/workflows/site-preview.yml'
+
+concurrency:
+  group: site-preview-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   deploy:
     runs-on: ubuntu-latest

.github/workflows/site-release.yml

@@ -11,6 +11,11 @@ on:
       - 'website/**'
       - 'docs/**'
       - '.github/workflows/site-release.yml'
+
+concurrency:
+  group: site-release-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   deploy:
     runs-on: ubuntu-latest

AGENTS.md

@@ -37,6 +37,7 @@ Any user-facing change in `packages/*` requires a changeset. Core packages are v
 - **Examples**: `examples/todo-app`, `examples/github-app`, `examples/nextjs`
 - **Documentation**: `docs/core/api`, `docs/rest`, `docs/core/guides`
 - **Tests**: `packages/*/src/**/__tests__`
+- **Benchmarks**: `examples/benchmark` (Node: core/normalizr/endpoint throughput), `examples/benchmark-react` (browser: React rendering and data-library comparison). See `.cursor/rules/benchmarking.mdc` and each example’s README.
 
 ## Key Principles
 

examples/AGENTS.md

@@ -4,7 +4,7 @@
 
 ### Monorepo workspace members
 
-`benchmark`, `test-bundlesize`, `normalizr-*`, `coin-app` — listed in root `package.json` workspaces, managed by yarn. Most use `workspace:*` for `@data-client/*` deps.
+`benchmark`, `benchmark-react`, `test-bundlesize`, `normalizr-*`, `coin-app` — listed in root `package.json` workspaces, managed by yarn. Most use `workspace:*` for `@data-client/*` deps.
 
 ### Standalone (StackBlitz demos)
 

examples/benchmark-react/.babelrc.js

@@ -0,0 +1,8 @@
+const options = { polyfillMethod: false };
+if (process.env.REACT_COMPILER === 'true') {
+  options.reactCompiler = {};
+}
+
+module.exports = {
+  presets: [['@anansi', options]],
+};