demo: Add benchmark-react with normalization and ref-stability scenarios (#3783)

* 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

* more of the plan

* More scenarios

* more scenarios

* add react compiler option

* bugbot: dead code

* No throttling

* yarn lock

* bugbot + fix test data client correctness

* fair comparisons

* ts 6

* bugbot

* update website types

* improve ci

* internal: Bench runs concurrently

* better abstractions

* CRUD

* virtualize

* create adds to list; larger high end case

* No seeding

fix yarn lock

* fix test conditions to be more accurate

* dynamic accuracy

* fix bench measurements

* remove unneeded bench

* fix measurement by eliminating paint timings from measurement

* increase scale, remove redundant

* bench name updates

* more realistic data

* MutationObserver timeout silently fails without signaling completion

* Make sorted mount consistent

* fix sorted-view-update-entity for some frameworks

* change reporting

* move scenario

* Init scenarios capture wrong react-commit-update measurement

* Upgrade benchmark baseline from dual list to triple list

Made-with: Cursor

* bugbot

* server sim

* Make author component more expensive

* network sim flag; new scenario

* bugbot

* DRY

* Potential fix for code scanning alert no. 83: DOM text reinterpreted as HTML

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

* delete dead code

* movewith docs

* review

* switch to github data

---------

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Author: ntucker

.changeset/collection-movewith.md

@@ -0,0 +1,21 @@
+---
+'@data-client/endpoint': minor
+'@data-client/rest': minor
+---
+
+Add `Collection.moveWith()` for custom move schemas
+
+Analogous to [`addWith()`](https://dataclient.io/rest/api/Collection#addWith), `moveWith()` constructs a custom move schema that controls how entities are added to their destination collection. The remove behavior is automatically derived from the collection type (Array or Values).
+
+New exports: `unshift` merge function for convenience.
+
+```ts
+import { Collection, unshift } from '@data-client/rest';
+
+class MyCollection extends Collection {
+  constructor(schema, options) {
+    super(schema, options);
+    this.move = this.moveWith(unshift);
+  }
+}
+```

.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-user-500-mounted`, `update-shared-user-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 user at scale)
+
+- **Ref-stability** (`ref-stability-issue-changed`, `ref-stability-user-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-user-*`, `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
 

docs/rest/api/Collection.md

@@ -601,6 +601,44 @@ e.g., `'10' == 10`
     boolean;
 ```
 
+### moveWith(merge): MoveSchema {#moveWith}
+
+Constructs a custom move schema for this collection. This is analogous to [addWith](#addWith)
+but for [move](#move) operations. The `merge` function controls how entities are added to
+their destination collection, while the remove behavior is automatically derived from
+the collection type (Array or Values).
+
+This is useful when you need to control the insertion position of moved items
+(e.g., prepending instead of appending).
+
+#### merge(collection, moved)
+
+Controls how the moved entity is added to its destination collection.
+
+The exported [`unshift`](#unshift-merge) merge function places items at the start:
+
+```ts
+import { Collection, unshift } from '@data-client/rest';
+
+class MyCollection extends Collection {
+  constructor(schema, options) {
+    super(schema, options);
+    // Prepend moved items instead of appending
+    // highlight-next-line
+    this.move = this.moveWith(unshift);
+  }
+}
+```
+
+### unshift (merge function) {#unshift-merge}
+
+A merge function that places incoming items at the _start_ of the collection.
+Use with [moveWith](#moveWith) or [addWith](#addWith) to control insertion order.
+
+```ts
+import { unshift } from '@data-client/rest';
+```
+
 ## Lifecycle Methods
 
 ### static shouldReorder(existingMeta, incomingMeta, existing, incoming): boolean {#shouldReorder}