demo(benchmark-react): add multi-view entity update scenario (#3806)

* demo(benchmark-react): add multi-view entity update scenario

Add `update-entity-multi-view` benchmark where the same issue entity
is displayed across three structurally different component trees (list
row, detail panel, pinned card strip). A single entity update must
propagate to all three views, exercising normalized cache cross-query
propagation vs. multi-query invalidation + refetch.

Made-with: Cursor

* demo(benchmark-react): fix post-mount GC inflating data-client times

Remove forced HeapProfiler.collectGarbage after pre-mount. The full GC
promoted all recently-allocated entities into V8's old generation,
causing write-barrier overhead during the timed action that
disproportionately penalized data-client's CPU-bound optimistic updates
(~1.8x inflation) while leaving network-bound libraries unaffected.

Also re-measure all scenarios and reorganize the README summary table
into Navigation / Mutations / Scaling categories.

Made-with: Cursor

* demo(benchmark-react): fix initMultiView double-setComplete race

measureMount's MutationObserver called setComplete() (setting
data-bench-complete) as soon as list items appeared, before the
detail panel and pinned card views were ready. The runner could
see this premature signal, proceed to the timed update phase, and
then receive a stale second setComplete() — corrupting the
measurement.

Refactor measureMount to return a Promise and accept
{ signalComplete: false } so initMultiView can suppress the
early completion signal and call setComplete() once after all
three views are ready.

Made-with: Cursor

Author: ntucker

.cursor/rules/benchmarking.mdc

@@ -41,6 +41,11 @@ Use this mapping when deciding which React benchmark scenarios are relevant to a
   - Relevant for: `@data-client/normalizr` denormalize memoization, Entity identity
   - All libraries (data-client should show fewest changed refs)
 
+- **Multi-view entity update** (`update-entity-multi-view`)
+  - Exercises: cross-query entity propagation — one update to a shared entity reflected in list, detail panel, and pinned cards
+  - Relevant for: `@data-client/normalizr` normalized cache, `@data-client/core` subscription fan-out
+  - All libraries (normalization advantage: one store write vs. multiple query invalidations + refetches)
+
 - **Sorted/derived view** (`getlist-500-sorted`, `update-entity-sorted`)
   - 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

examples/benchmark-react/README.md

@@ -31,6 +31,7 @@ The repo has two benchmark suites:
 - **Get list sorted** (`getlist-500-sorted`) — Mount 500 issues through a sorted/derived view. data-client uses `useQuery(sortedIssuesQuery)` with `Query` schema memoization; competitors use `useMemo` + sort.
 - **Update entity** (`update-entity`) — Time to update one issue and propagate to the UI (unit: ms).
 - **Update entity sorted** (`update-entity-sorted`) — After mounting a sorted view, update one entity. data-client's `Query` memoization avoids re-sorting when sort keys are unchanged.
+- **Update entity multi-view** (`update-entity-multi-view`) — Update one issue that appears simultaneously in a list, a detail panel, and a pinned-cards strip. Exercises cross-query entity propagation: normalized cache updates once and all three views reflect the change; non-normalized libraries must invalidate and refetch each query independently.
 - **Update user (scaling)** (`update-user`, `update-user-10000`) — Update one shared user with 1,000 or 10,000 mounted issues to test subscriber scaling. Normalized cache: one store update, all views of that user update.
 - **Ref-stability** (`ref-stability-issue-changed`, `ref-stability-user-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.
 - **Invalidate and resolve** (`invalidate-and-resolve`) — data-client only; invalidates a cached endpoint and immediately re-resolves. Measures Suspense boundary round-trip.
@@ -54,12 +55,10 @@ Illustrative **relative** results with **SWR = 100%** (baseline). For **duration
 
 | Category | Scenarios (representative) | data-client | tanstack-query | swr |
 |---|---|---:|---:|---:|
-| Get list (fetch + render) | `getlist-100`, `getlist-500`, `getlist-500-sorted` | ~104% | ~101% | **100%** |
-| Mutations (with network sim) | `update-entity`, `unshift-item`, `delete-item`, `move-item` | ~2% | ~104% | **100%** |
-| Sorted view: entity update | `update-entity-sorted` | ~2% | ~100% | **100%** |
-| Large data: shared user update | `update-user` (1k rows rendered) | ~2% | ~102% | **100%** |
-| Large data: shared user update | `update-user-10000` | ~5% | ~122% | **100%** |
-| Large data: list ↔ detail | `list-detail-switch` | ~25% | ~106% | **100%** |
+| Navigation | `getlist-100`, `getlist-500`, `getlist-500-sorted` | ~103% | ~102% | **100%** |
+| Navigation | `list-detail-switch` | ~21% | ~102% | **100%** |
+| Mutations | `update-entity`, `update-user`, `update-entity-sorted`, `update-entity-multi-view`, `unshift-item`, `delete-item`, `move-item` | ~2% | ~102% | **100%** |
+| Scaling (10k items) | `update-user-10000` | ~5% | ~122% | **100%** |
 
 
 ## Latest measured results (network simulation on)
@@ -70,24 +69,25 @@ Run: **2026-03-21**, Linux (WSL2), `yarn build:benchmark-react`, static preview
 
 | Scenario | Unit | data-client | tanstack-query | swr |
 |---|---|---:|---:|---:|
-| `getlist-100` | ms | 89.3 ± 0.11 | 88.9 ± 0.17 | 87.2 ± 0.49 |
-| `getlist-500` | ms | 104.8 ± 1.37 | 101.2 ± 0.29 | 99.4 ± 0.69 |
-| `update-entity` | ms | 2.1 ± 0.11 | 144.9 ± 0.58 | 143.0 ± 0.23 |
-| `update-user` | ms | 3.1 ± 0.29 | 141.9 ± 0.00 | 139.0 ± 0.00 |
-| `getlist-500-sorted` | ms | 103.2 ± 0.59 | 98.8 ± 0.39 | 98.9 ± 0.88 |
-| `update-entity-sorted` | ms | 2.7 ± 0.00 | 139.7 ± 0.10 | 140.4 ± 0.88 |
-| `list-detail-switch` | ms | 165.5 ± 21.69 | 694.4 ± 3.72 | 656.9 ± 26.95 |
-| `update-user-10000` | ms | 9.1 ± 0.49 | 239.4 ± 0.59 | 195.7 ± 1.86 |
-| `unshift-item` | ms | 3.0 ± 0.07 | 144.1 ± 0.46 | 139.8 ± 0.47 |
-| `delete-item` | ms | 2.6 ± 0.07 | 142.2 ± 0.07 | 138.5 ± 0.36 |
-| `move-item` | ms | 3.6 ± 0.11 | 154.5 ± 0.82 | 143.9 ± 0.82 |
+| `getlist-100` | ms | 89.3 ± 0.22 | 88.7 ± 0.15 | 87.5 ± 0.50 |
+| `getlist-500` | ms | 102.3 ± 1.25 | 99.9 ± 1.25 | 98.4 ± 1.25 |
+| `getlist-500-sorted` | ms | 101.8 ± 1.61 | 99.2 ± 1.29 | 97.9 ± 0.63 |
+| `list-detail-switch` | ms | 144.4 ± 21.22 | 689.4 ± 20.83 | 674.5 ± 35.67 |
+| `update-entity` | ms | 2.8 ± 0.09 | 142.6 ± 0.31 | 142.4 ± 0.34 |
+| `update-user` | ms | 3.0 ± 0.13 | 142.7 ± 0.43 | 139.4 ± 0.51 |
+| `update-entity-sorted` | ms | 3.2 ± 0.24 | 141.3 ± 0.07 | 141.4 ± 0.56 |
+| `update-entity-multi-view` | ms | 2.8 ± 0.41 | 146.6 ± 7.25 | 145.3 ± 8.21 |
+| `update-user-10000` | ms | 10.3 ± 0.82 | 246.0 ± 1.35 | 201.2 ± 0.75 |
+| `unshift-item` | ms | 3.5 ± 0.06 | 144.5 ± 0.38 | 139.7 ± 0.07 |
+| `delete-item` | ms | 3.2 ± 0.10 | 144.4 ± 0.11 | 139.9 ± 0.11 |
+| `move-item` | ms | 3.5 ± 0.13 | 156.4 ± 0.50 | 146.4 ± 0.05 |
 
 ## Expected variance
 
 | Category | Scenarios | Typical run-to-run spread |
 |---|---|---|
 | **Stable** | `getlist-*`, `update-entity`, `ref-stability-*` | 2-5% |
-| **Moderate** | `update-user-*`, `update-entity-sorted` | 5-10% |
+| **Moderate** | `update-user-*`, `update-entity-sorted`, `update-entity-multi-view` | 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.
@@ -186,7 +186,7 @@ Regressions >5% on stable scenarios or >15% on volatile scenarios are worth inve
    Scenarios are classified as `small` or `large` based on their cost:
 
    - **Small** (3 warmup + 15 measurement): `getlist-100`, `update-entity`, `ref-stability-*`, `invalidate-and-resolve`, `unshift-item`, `delete-item`
-   - **Large** (1 warmup + 4 measurement): `getlist-500`, `getlist-500-sorted`, `update-user`, `update-user-10000`, `update-entity-sorted`, `list-detail-switch`
+   - **Large** (1 warmup + 4 measurement): `getlist-500`, `getlist-500-sorted`, `update-user`, `update-user-10000`, `update-entity-sorted`, `update-entity-multi-view`, `list-detail-switch`
    - **Memory** (opt-in, 1 warmup + 3 measurement): `memory-mount-unmount-cycle` — run with `--action memory`
 
    When running all scenarios (`yarn bench`), each group runs with its own warmup/measurement count. Use `--size` to run only one group.

examples/benchmark-react/bench/runner.ts

@@ -272,13 +272,6 @@ async function runScenario(
       performance.clearMarks();
       performance.clearMeasures();
     });
-    // Force GC after pre-mount so V8 doesn't collect during the timed action
-    if (cdp) {
-      try {
-        await cdp.send('HeapProfiler.collectGarbage');
-      } catch {}
-      await page.waitForTimeout(50);
-    }
   }
 
   if (isRefStability) {

examples/benchmark-react/src/data-client/index.tsx

@@ -14,6 +14,8 @@ import {
 import {
   DOUBLE_LIST_STYLE,
   IssueRow,
+  PINNED_STRIP_STYLE,
+  PinnedCardView,
   PlainIssueList,
 } from '@shared/components';
 import {
@@ -110,6 +112,21 @@ function DetailView({ number }: { number: number }) {
   );
 }
 
+function PinnedCard({ number }: { number: number }) {
+  const issue = useSuspense(IssueResource.get, { number });
+  return <PinnedCardView issue={issue as Issue} />;
+}
+
+function PinnedStrip({ numbers }: { numbers: number[] }) {
+  return (
+    <div data-pinned-strip style={PINNED_STRIP_STYLE}>
+      {numbers.map(n => (
+        <PinnedCard key={n} number={n} />
+      ))}
+    </div>
+  );
+}
+
 function BenchmarkHarness() {
   const controller = useController();
   const {
@@ -119,6 +136,7 @@ function BenchmarkHarness() {
     showDoubleList,
     doubleListCount,
     detailIssueNumber,
+    pinnedNumbers,
     renderLimit,
     containerRef,
     measureUpdate,
@@ -220,10 +238,44 @@ function BenchmarkHarness() {
     [measureUpdate, controller, containerRef, doubleListCount, listViewCount],
   );
 
+  const updateEntityMultiView = useCallback(
+    (number: number) => {
+      const issue = FIXTURE_ISSUES_BY_NUMBER.get(number);
+      if (!issue) return;
+      const expected = `${issue.title} (updated)`;
+      measureUpdate(
+        () => {
+          controller.fetch(
+            IssueResource.update,
+            { number },
+            { title: expected },
+          );
+        },
+        () => {
+          const container = containerRef.current!;
+          const listTitle = container.querySelector(
+            `[data-issue-number="${number}"] [data-title]`,
+          );
+          const detailTitle = container.querySelector(
+            '[data-detail-view] [data-title]',
+          );
+          const pinnedTitle = container.querySelector(
+            `[data-pinned-number="${number}"] [data-title]`,
+          );
+          return [listTitle, detailTitle, pinnedTitle].every(
+            el => el?.textContent === expected,
+          );
+        },
+      );
+    },
+    [measureUpdate, controller, containerRef],
+  );
+
   registerAPI({
     updateEntity,
     updateUser,
     invalidateAndResolve,
+    updateEntityMultiView,
     unshiftItem,
     deleteEntity,
     moveItem,
@@ -246,6 +298,11 @@ function BenchmarkHarness() {
           <DetailView number={detailIssueNumber} />
         </React.Suspense>
       )}
+      {pinnedNumbers.length > 0 && (
+        <React.Suspense fallback={<div>Loading pinned...</div>}>
+          <PinnedStrip numbers={pinnedNumbers} />
+        </React.Suspense>
+      )}
     </div>
   );
 }

examples/benchmark-react/src/shared/benchHarness.tsx

@@ -80,6 +80,7 @@ export function useBenchState() {
   const [detailIssueNumber, setDetailIssueNumber] = useState<number | null>(
     null,
   );
+  const [pinnedNumbers, setPinnedNumbers] = useState<number[]>([]);
   const [renderLimit, setRenderLimit] = useState<number | undefined>();
   const containerRef = useRef<HTMLDivElement>(null);
   const completeResolveRef = useRef<(() => void) | null>(null);
@@ -95,29 +96,41 @@ export function useBenchState() {
    * Measure a mount action via MutationObserver. Ends when expected content
    * ([data-bench-item] or [data-sorted-list]) appears in the container,
    * skipping intermediate states like Suspense fallbacks or empty first renders.
+   *
+   * Returns a promise that resolves when the mount content is detected.
+   * Pass `signalComplete: false` to suppress the data-bench-complete attribute
+   * (useful when the caller needs additional async work before signaling).
    */
   const measureMount = useCallback(
-    (fn: () => unknown) => {
+    (fn: () => unknown, { signalComplete = true } = {}): Promise<void> => {
       const container = containerRef.current!;
-      const observer = new MutationObserver(() => {
-        if (container.querySelector('[data-bench-item], [data-sorted-list]')) {
+      return new Promise<void>(resolve => {
+        const done = () => {
+          if (signalComplete) setComplete();
+          resolve();
+        };
+        const observer = new MutationObserver(() => {
+          if (
+            container.querySelector('[data-bench-item], [data-sorted-list]')
+          ) {
+            performance.mark('mount-end');
+            performance.measure('mount-duration', 'mount-start', 'mount-end');
+            observer.disconnect();
+            clearTimeout(timer);
+            done();
+          }
+        });
+        observer.observe(container, OBSERVE_MUTATIONS);
+        const timer = setTimeout(() => {
+          observer.disconnect();
           performance.mark('mount-end');
           performance.measure('mount-duration', 'mount-start', 'mount-end');
-          observer.disconnect();
-          clearTimeout(timer);
-          setComplete();
-        }
+          container.setAttribute('data-bench-timeout', 'true');
+          done();
+        }, 30000);
+        performance.mark('mount-start');
+        fn();
       });
-      observer.observe(container, OBSERVE_MUTATIONS);
-      const timer = setTimeout(() => {
-        observer.disconnect();
-        performance.mark('mount-end');
-        performance.measure('mount-duration', 'mount-start', 'mount-end');
-        container.setAttribute('data-bench-timeout', 'true');
-        setComplete();
-      }, 30000);
-      performance.mark('mount-start');
-      fn();
     },
     [setComplete],
   );
@@ -195,6 +208,7 @@ export function useBenchState() {
     setShowDoubleList(false);
     setDoubleListCount(undefined);
     setDetailIssueNumber(null);
+    setPinnedNumbers([]);
   }, []);
 
   const initDoubleList = useCallback(
@@ -272,6 +286,31 @@ export function useBenchState() {
     ],
   );
 
+  const initMultiView = useCallback(
+    async (n: number) => {
+      await seedIssueList(FIXTURE_ISSUES.slice(0, n));
+
+      setDetailIssueNumber(1);
+      setPinnedNumbers(Array.from({ length: 10 }, (_, i) => i + 1));
+
+      await measureMount(() => setListViewCount(n), {
+        signalComplete: false,
+      });
+
+      await waitForElement('[data-detail-view]');
+      await waitForElement('[data-pinned-number]');
+      setComplete();
+    },
+    [
+      measureMount,
+      setListViewCount,
+      setDetailIssueNumber,
+      setPinnedNumbers,
+      waitForElement,
+      setComplete,
+    ],
+  );
+
   const getRenderedCount = useCallback(
     () => listViewCount ?? 0,
     [listViewCount],
@@ -289,6 +328,7 @@ export function useBenchState() {
     apiRef.current = {
       init,
       initDoubleList,
+      initMultiView,
       unmountAll,
       mountUnmountCycle,
       mountSortedView,
@@ -323,6 +363,7 @@ export function useBenchState() {
     showDoubleList,
     doubleListCount,
     detailIssueNumber,
+    pinnedNumbers,
     renderLimit,
     containerRef,
 

examples/benchmark-react/src/shared/components.tsx

@@ -74,6 +74,28 @@ export function IssueRow({ issue }: { issue: Issue }) {
   );
 }
 
+export const PINNED_STRIP_STYLE = {
+  display: 'flex',
+  gap: 4,
+  flexWrap: 'wrap',
+} as const;
+
+/**
+ * Compact card for "pinned/bookmarked" issues — structurally different from
+ * IssueRow. Each card fetches its issue individually by ID (per-library),
+ * so the multi-view scenario tests cross-query entity propagation.
+ */
+export function PinnedCardView({ issue }: { issue: Issue }) {
+  return (
+    <div data-pinned-number={issue.number} data-bench-item>
+      <span data-title>{issue.title}</span>
+      <UserView user={issue.user} />
+      <span data-state>{STATE_ICONS[issue.state] ?? issue.state}</span>
+      <span data-comments>{issue.comments}</span>
+    </div>
+  );
+}
+
 /** Plain keyed list. React can reconcile inserts/deletes by key without
  *  re-rendering every row (unlike index-based virtualized lists). */
 export function PlainIssueList({

examples/benchmark-react/src/shared/types.ts

@@ -45,6 +45,10 @@ export interface BenchAPI {
   moveItem?(id: number): void;
   /** Switch between sorted list view and individual issue detail views 10 times (20 renders). Exercises normalized cache lookup (data-client) vs per-navigation fetch (others). */
   listDetailSwitch?(count: number): void;
+  /** Mount list + detail panel + pinned card strip for multi-view entity propagation. */
+  initMultiView?(count: number): void;
+  /** Update an entity that appears in list + detail + pinned views; waits for all three to reflect the change. */
+  updateEntityMultiView?(id: number): void;
   /** Trigger store garbage collection (data-client only). Used by memory scenarios to flush unreferenced data before heap measurement. */
   triggerGC?(): void;
   /** Cap DOM rendering to the first N items while keeping all data in the store. */
@@ -110,6 +114,7 @@ export interface Issue {
 export type ScenarioAction =
   | { action: 'init'; args: [number] }
   | { action: 'updateEntity'; args: [number] }
+  | { action: 'updateEntityMultiView'; args: [number] }
   | { action: 'updateUser'; args: [string] }
   | { action: 'unmountAll'; args: [] }
   | { action: 'unshiftItem'; args: [] }