From 221cf3a22d5590f51323e6bd4da09ba084581089 Mon Sep 17 00:00:00 2001
From: Will Manning <will@willmanning.io>
Date: Fri, 30 Oct 2026 09:10:14 -0400
Subject: [PATCH 1/9] bench: pin Bun as bench/web's packageManager

pnpm refuses to install in a project that pins another package
manager, so a pnpm command run in bench/web now fails instead of
installing around the 7-day cooldown. The pin matches the root's.

Renovate reads packageManager as its own dep type. Without a rule,
bench's copy would take the bench- branch prefix and a PR of its own,
so the two pins could drift. A rule after bench's groups both in one
branch. A test fails when the pins differ or the rule is missing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Will Manning <will@willmanning.io>
---
 CLAUDE.md                             |  2 +-
 bench/web/lib/package-manager.test.ts | 52 +++++++++++++++++++++++++++
 bench/web/package.json                |  1 +
 renovate.json                         |  7 ++++
 4 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 bench/web/lib/package-manager.test.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index b93e8ff..e9b8dd2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -105,7 +105,7 @@ Keep them in lockstep when bumping, and move to a new major only after Vercel of
 
 `bench/web` is a member of the root Bun workspace, so the layers above cover it: the cooldown in `bunfig.toml`, `trustedDependencies` and `overrides` in the root `package.json`, `bun audit`, and the `bun.lock (bench/web)` manifest of the dependency snapshot. What is particular to bench:
 
-- **Install at the root.** `bun install --frozen-lockfile` at the root installs both apps, and `bun run --cwd bench/web <script>` runs bench's scripts; CI and `bench-deploy.yml` do the same, and `bench/web/vercel.json` gives `vercel build` the same install command. A `bun install` in `bench/web` also finds the root's `bunfig.toml`.
+- **Install at the root.** `bun install --frozen-lockfile` at the root installs both apps, and `bun run --cwd bench/web <script>` runs bench's scripts; CI and `bench-deploy.yml` do the same, and `bench/web/vercel.json` gives `vercel build` the same install command. A `bun install` in `bench/web` also finds the root's `bunfig.toml`. `bench/web/package.json` pins the root's `packageManager` (`bun@…`), so pnpm refuses to install there instead of installing around the cooldown; a `renovate.json` rule updates both pins in one branch, and `bench/web/lib/package-manager.test.ts` fails if they differ.
 - **Linker.** `bunfig.toml` sets `linker = "isolated"`, so every package gets the dependencies it resolved, as pnpm gave bench. That layout keeps one app's tools from loading the other's copy of a package; both apps now resolve the same TypeScript, so that no longer matters for it.
 - **Lifecycle scripts.** pnpm's `allowBuilds` let `sharp` build (and `unrs-resolver`, which left with ESLint). `trustedDependencies` already trusts `sharp`, and stays `["esbuild", "sharp"]`. Bun blocks three bench scripts, `protobufjs`, `ssh2` and `cpu-features`, which pnpm blocked too. With the isolated linker, `bun pm untrusted` lists only packages linked at the top of `node_modules`, so it reports none of them; to audit, install once with `bun install --linker hoisted` in a scratch copy and run it there.
 - **Deploy CLI:** `bench-deploy.yml` installs the Vercel CLI from `.github/vercel-cli` with `npm ci --ignore-scripts`. Its `package.json` pins the version, and its `package-lock.json` locks the whole tree. That job holds `VERCEL_TOKEN`. The lockfile is npm's, not Bun's, so GitHub's dependency graph, Dependabot and dependency review read it natively. To change it, run `npm install --package-lock-only --ignore-scripts --before=<7 days ago>` in that directory (Renovate passes the same `--before`), then `npm audit`. Its `overrides` patch advisories in dependencies the CLI pins; see "bench advisories".
diff --git a/bench/web/lib/package-manager.test.ts b/bench/web/lib/package-manager.test.ts
new file mode 100644
index 0000000..21c7936
--- /dev/null
+++ b/bench/web/lib/package-manager.test.ts
@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+function readJson<T>(relative: string): T {
+  return JSON.parse(readFileSync(fileURLToPath(new URL(relative, import.meta.url)), 'utf8')) as T;
+}
+
+interface PackageJson {
+  packageManager?: string;
+}
+
+interface RenovateRule {
+  matchDepTypes?: string[];
+  groupName?: string;
+  additionalBranchPrefix?: string;
+  commitMessageSuffix?: string;
+}
+
+const root = readJson<PackageJson>('../../../package.json');
+const bench = readJson<PackageJson>('../package.json');
+const renovate = readJson<{ packageRules: RenovateRule[] }>('../../../renovate.json');
+
+// pnpm refuses to install in a project whose `packageManager` names another package manager, so
+// the pin keeps a pnpm command in bench/web from installing around Bun's release-age cooldown.
+describe('bench/web packageManager', () => {
+  it('pins Bun, the same version as the root workspace', () => {
+    expect(root.packageManager).toMatch(/^bun@\d+\.\d+\.\d+$/);
+    expect(bench.packageManager).toBe(root.packageManager);
+  });
+
+  it('is updated with the root pin in one Renovate branch', () => {
+    // Renovate's npm manager reads `packageManager` as depType `packageManager`. Without this rule
+    // bench's copy would take the `bench-` branch prefix and land in a PR of its own.
+    const benchRule = renovate.packageRules.findIndex(
+      (rule) => rule.additionalBranchPrefix === 'bench-',
+    );
+    const pinRule = renovate.packageRules.findIndex((rule) =>
+      rule.matchDepTypes?.includes('packageManager'),
+    );
+    expect(benchRule).toBeGreaterThanOrEqual(0);
+    // Later rules win, so the pin's rule must come after bench's.
+    expect(pinRule).toBeGreaterThan(benchRule);
+    const rule = renovate.packageRules[pinRule]!;
+    expect(rule.groupName).toBeTruthy();
+    expect(rule.additionalBranchPrefix).toBe('');
+    expect(rule.commitMessageSuffix).toBe('');
+  });
+});
diff --git a/bench/web/package.json b/bench/web/package.json
index 43cd045..a9b501a 100644
--- a/bench/web/package.json
+++ b/bench/web/package.json
@@ -2,6 +2,7 @@
   "name": "benchmarks-web",
   "version": "0.1.0",
   "private": true,
+  "packageManager": "bun@1.4.3",
   "scripts": {
     "dev": "next dev",
     "build": "next build",
diff --git a/renovate.json b/renovate.json
index d2cafc9..0073cef 100644
--- a/renovate.json
+++ b/renovate.json
@@ -86,6 +86,13 @@
       "additionalBranchPrefix": "bench-",
       "commitMessageSuffix": "(bench)",
       "addLabels": ["bench"]
+    },
+    {
+      "description": "The root and bench/web package.json pin the same Bun in packageManager. Update both in one branch, without bench's prefix, so the two pins cannot drift. This rule comes after bench's so that it wins.",
+      "matchDepTypes": ["packageManager"],
+      "groupName": "Bun package manager",
+      "additionalBranchPrefix": "",
+      "commitMessageSuffix": ""
     }
   ]
 }

From 1d5226f4ec178e69e1f733f797163e8d1b4ee5b0 Mon Sep 17 00:00:00 2001
From: Will Manning <will@willmanning.io>
Date: Fri, 30 Oct 2026 09:16:24 -0400
Subject: [PATCH 2/9] bench: let a background cache refresh wait for the fill
 lock

After /api/revalidate marks the group caches stale, the next read
returns the stale value and Next refreshes the entry in the
background. If another instance holds the entry's fill lock, the
refresh failed at once with GroupCacheFillInProgressError, Next logged
it as an error, and the entry stayed stale until a later read started
another refresh.

A fill now learns from the read it runs in (an AsyncLocalStorage set by
retryGroupCacheFill) whether that read has already returned. If so, it
is a background refresh: on contention it releases its connection and
fill slot, backs off on the read retry schedule (about 15 seconds in
all), tries the lock again, and fills only once it holds the lock. A
fill that a read still waits for (a miss) fails fast as before, so the
read retries the Data Cache without holding a connection.

Unit tests cover the wait, the free slot, the bound and the unchanged
foreground path. A Postgres test holds the lock from a second session.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Will Manning <will@willmanning.io>
---
 bench/docs/architecture/read-path.md  |   5 +-
 bench/web/lib/cache-fill-lock.test.ts | 117 ++++++++++++++++++++++
 bench/web/lib/cache-fill.test.ts      | 137 ++++++++++++++++++++++++++
 bench/web/lib/cache-fill.ts           | 106 ++++++++++++++++----
 bench/web/lib/data-cache.test.ts      |  23 +++++
 5 files changed, 369 insertions(+), 19 deletions(-)
 create mode 100644 bench/web/lib/cache-fill-lock.test.ts

diff --git a/bench/docs/architecture/read-path.md b/bench/docs/architecture/read-path.md
index 90bbdf1..682c110 100644
--- a/bench/docs/architecture/read-path.md
+++ b/bench/docs/architecture/read-path.md
@@ -145,7 +145,10 @@ fills under its own PostgreSQL advisory lock (`web/lib/cache-fill.ts`), shared
 across production and preview functions. Different entries fill at once; for one
 entry, one invocation runs the fill, and contenders release their connections
 and retry the Data Cache read with bounded backoff instead of issuing duplicate
-queries. A bundle's fill resolves only its own group: one family's discovery,
+queries. A background refresh of a stale entry has no read to retry (the read
+already returned the stale value), so when it finds the lock taken it releases
+its connection, backs off on the same schedule (about 15 seconds in all) and
+tries the lock again, and fills only once it holds the lock. A bundle's fill resolves only its own group: one family's discovery,
 then that group's summary, not every group's. Entries and locks use the slug's
 canonical form, so the many spellings that decode to one group share them. In
 one process, a second request for an entry shares the running fill, and fills
diff --git a/bench/web/lib/cache-fill-lock.test.ts b/bench/web/lib/cache-fill-lock.test.ts
new file mode 100644
index 0000000..4ae4822
--- /dev/null
+++ b/bench/web/lib/cache-fill-lock.test.ts
@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+import { Client } from 'pg';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import {
+  cacheFillLockId,
+  GroupCacheFillInProgressError,
+  retryGroupCacheFill,
+  withGroupCacheFillLock,
+} from './cache-fill';
+import { getPool, resetPool } from './db';
+import {
+  type BenchDatabase,
+  integrationDatabaseAvailable,
+  startBenchDatabase,
+} from './test-harness';
+
+const databaseAvailable = integrationDatabaseAvailable();
+
+// The two ints of the advisory lock that guards the cache entry `key` (see `cache-fill.ts`).
+function lockOf(key: string): [number, number] {
+  return [0x62656e63, cacheFillLockId(key)];
+}
+
+/** Pool clients checked out now. */
+function clientsHeld(): number {
+  const pool = getPool();
+  return pool.totalCount - pool.idleCount;
+}
+
+// Another instance holds the fill lock, as on Vercel when two functions refresh one entry.
+describe.skipIf(!databaseAvailable)('group cache fill lock (Postgres)', () => {
+  let database: BenchDatabase;
+  let other: Client;
+
+  beforeAll(async () => {
+    database = await startBenchDatabase({ applySchema: false });
+    other = new Client({
+      host: process.env.BENCH_DB_HOST,
+      port: Number(process.env.BENCH_DB_PORT),
+      user: process.env.BENCH_DB_USER,
+      password: process.env.BENCH_DB_PASSWORD,
+      database: process.env.BENCH_DB_NAME,
+      ssl: false,
+    });
+    await other.connect();
+  });
+
+  afterEach(async () => {
+    await other.query('SELECT pg_advisory_unlock_all()');
+  });
+
+  afterAll(async () => {
+    await other.end();
+    await resetPool();
+    await database.stop();
+  });
+
+  it('makes a background refresh wait for the lock, then fill under it', async () => {
+    const key = 'group-charts:background';
+    await other.query('SELECT pg_advisory_lock($1, $2)', lockOf(key));
+    // While the refresh fills, the other instance cannot take the lock.
+    const fill = vi.fn(async () => {
+      const probe = await other.query<{ acquired: boolean }>(
+        'SELECT pg_try_advisory_lock($1, $2) AS acquired',
+        lockOf(key),
+      );
+      return probe.rows[0]?.acquired === true ? 'filled without the lock' : 'fresh';
+    });
+
+    // A stale entry: the read starts the refresh and returns the stale value without waiting.
+    let refresh!: Promise<string>;
+    await expect(
+      retryGroupCacheFill(async () => {
+        refresh = withGroupCacheFillLock(key, fill);
+        return 'stale';
+      }, []),
+    ).resolves.toBe('stale');
+    const settled = refresh.then(
+      (value) => ({ value }),
+      (error: unknown) => ({ error }),
+    );
+
+    // The first try lost the lock. The refresh waits for the next one without a connection.
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    expect(fill).not.toHaveBeenCalled();
+    expect(clientsHeld()).toBe(0);
+
+    await other.query('SELECT pg_advisory_unlock($1, $2)', lockOf(key));
+    await expect(settled).resolves.toEqual({ value: 'fresh' });
+    expect(fill).toHaveBeenCalledOnce();
+    expect(clientsHeld()).toBe(0);
+    // The refresh let go of the lock.
+    const after = await other.query<{ acquired: boolean }>(
+      'SELECT pg_try_advisory_lock($1, $2) AS acquired',
+      lockOf(key),
+    );
+    expect(after.rows[0]?.acquired).toBe(true);
+  });
+
+  it('fails a fill that a read waits for at once, and releases its connection', async () => {
+    const key = 'group-charts:foreground';
+    await other.query('SELECT pg_advisory_lock($1, $2)', lockOf(key));
+    const fill = vi.fn(async () => 'never');
+
+    const started = performance.now();
+    await expect(
+      retryGroupCacheFill(() => withGroupCacheFillLock(key, fill), []),
+    ).rejects.toBeInstanceOf(GroupCacheFillInProgressError);
+    // One round trip, not a wait for the lock.
+    expect(performance.now() - started).toBeLessThan(200);
+    expect(fill).not.toHaveBeenCalled();
+    expect(clientsHeld()).toBe(0);
+  });
+});
diff --git a/bench/web/lib/cache-fill.test.ts b/bench/web/lib/cache-fill.test.ts
index b5c62ed..ef58996 100644
--- a/bench/web/lib/cache-fill.test.ts
+++ b/bench/web/lib/cache-fill.test.ts
@@ -297,6 +297,143 @@ describe('cache fill slots', () => {
   });
 });
 
+describe('a background refresh that loses the lock', () => {
+  // The delays between tries of the lock, as in `cache-fill.ts`.
+  const delays = [250, 750, 2_000, 4_000, 8_000];
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    connect.mockReset();
+    query.mockReset();
+    release.mockReset();
+    connect.mockImplementation(async () => Object.assign(new EventEmitter(), { query, release }));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  /** The lock is taken by another process for the first `taken` tries. */
+  function lockTakenFor(taken: number): void {
+    let tries = 0;
+    query.mockImplementation(async (text: string) => {
+      if (text.includes('pg_try_advisory_lock')) {
+        tries += 1;
+        return { rows: [{ acquired: tries > taken }] };
+      }
+      return { rows: [] };
+    });
+  }
+
+  /** Start a fill the way `unstable_cache` refreshes a stale entry: the read starts it and
+   * returns the stale value without waiting for it. The refresh comes back in an object: an
+   * async function that returned it bare would wait for it. */
+  async function staleRead<T>(
+    key: string,
+    fill: () => Promise<T>,
+  ): Promise<{ refresh: Promise<T> }> {
+    let refresh!: Promise<T>;
+    await expect(
+      retryGroupCacheFill(async () => {
+        refresh = withGroupCacheFillLock(key, fill);
+        return 'stale';
+      }, []),
+    ).resolves.toBe('stale');
+    // Let the refresh settle as a rejection here, not as an unhandled one.
+    refresh.catch(() => {});
+    return { refresh };
+  }
+
+  /** How many pool clients are checked out now. */
+  function clientsHeld(): number {
+    return connect.mock.calls.length - release.mock.calls.length;
+  }
+
+  it('waits for the lock without a connection, then fills', async () => {
+    lockTakenFor(2);
+    const fill = vi.fn(async () => 'fresh');
+
+    const { refresh } = await staleRead('group-charts:stale', fill);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(connect).toHaveBeenCalledOnce();
+    expect(clientsHeld()).toBe(0);
+    expect(fill).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(delays[0]!);
+    expect(connect).toHaveBeenCalledTimes(2);
+    expect(clientsHeld()).toBe(0);
+    expect(fill).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(delays[1]!);
+    await expect(refresh).resolves.toBe('fresh');
+    expect(fill).toHaveBeenCalledOnce();
+    expect(connect).toHaveBeenCalledTimes(3);
+    expect(clientsHeld()).toBe(0);
+    // The fill ran under the lock, and released it.
+    expect(query.mock.calls.at(-1)![0]).toContain('pg_advisory_unlock');
+  });
+
+  it('frees its fill slot while it waits', async () => {
+    lockTakenFor(1);
+    const { refresh } = await staleRead('groups', async () => 'groups');
+    await vi.advanceTimersByTimeAsync(0);
+
+    // The group list waits for the lock. Another entry's fill takes the slots meanwhile.
+    query.mockImplementation(async (text: string) =>
+      text.includes('pg_try_advisory_lock') ? { rows: [{ acquired: true }] } : { rows: [] },
+    );
+    await expect(withGroupCacheFillLock('group-charts:other', async () => 'other')).resolves.toBe(
+      'other',
+    );
+
+    await vi.advanceTimersByTimeAsync(delays[0]!);
+    await expect(refresh).resolves.toBe('groups');
+  });
+
+  it('gives up after the bounded wait', async () => {
+    lockTakenFor(Number.POSITIVE_INFINITY);
+    const fill = vi.fn(async () => 'never');
+
+    const { refresh } = await staleRead('group-charts:busy', fill);
+    const total = delays.reduce((sum, delay) => sum + delay, 0);
+    await vi.advanceTimersByTimeAsync(total - 1);
+    expect(connect).toHaveBeenCalledTimes(delays.length);
+    await vi.advanceTimersByTimeAsync(1);
+
+    await expect(refresh).rejects.toBeInstanceOf(GroupCacheFillInProgressError);
+    expect(connect).toHaveBeenCalledTimes(delays.length + 1);
+    expect(clientsHeld()).toBe(0);
+    expect(fill).not.toHaveBeenCalled();
+  });
+
+  it('leaves a read that waits for its fill to fail fast and retry the cache', async () => {
+    lockTakenFor(Number.POSITIVE_INFINITY);
+    const fill = vi.fn(async () => 'never');
+
+    const read = retryGroupCacheFill(() => withGroupCacheFillLock('group-charts:miss', fill), []);
+    read.catch(() => {});
+    await vi.advanceTimersByTimeAsync(0);
+
+    await expect(read).rejects.toBeInstanceOf(GroupCacheFillInProgressError);
+    expect(connect).toHaveBeenCalledOnce();
+    expect(clientsHeld()).toBe(0);
+    expect(fill).not.toHaveBeenCalled();
+  });
+
+  it('does not retry a fill that fails for another reason', async () => {
+    lockTakenFor(0);
+    const failure = new Error('query failed');
+
+    const { refresh } = await staleRead('group-charts:broken', async () => {
+      throw failure;
+    });
+    await vi.advanceTimersByTimeAsync(0);
+
+    await expect(refresh).rejects.toBe(failure);
+    expect(connect).toHaveBeenCalledOnce();
+  });
+});
+
 describe('cache fill lock id', () => {
   it('is the 32-bit FNV-1a hash as a signed int4', () => {
     // The FNV-1a reference vectors: 0x811c9dc5, 0xe40c292c and 0xbf9cf968.
diff --git a/bench/web/lib/cache-fill.ts b/bench/web/lib/cache-fill.ts
index 534428a..afdf56b 100644
--- a/bench/web/lib/cache-fill.ts
+++ b/bench/web/lib/cache-fill.ts
@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
+import { AsyncLocalStorage } from 'node:async_hooks';
+
 import { getPool, resolvePoolMax } from '@/lib/db';
 
 // First int of every group cache fill's two-int PostgreSQL advisory-lock key: "benc". The second
@@ -9,6 +11,8 @@ import { getPool, resolvePoolMax } from '@/lib/db';
 // entries take turns.
 const GROUP_CACHE_FILL_LOCK_SPACE = 0x62656e63;
 
+// How long a read waits between retries of the Data Cache, and a background refresh between
+// tries of the lock, while another process fills the entry: 15 seconds in all.
 const CACHE_FILL_RETRY_DELAYS_MS = [250, 750, 2_000, 4_000, 8_000] as const;
 
 // At most this many fills run at once in one process, however large the pool.
@@ -85,16 +89,48 @@ async function withFillSlots<T>(exclusive: boolean, run: () => Promise<T>): Prom
 // running fill instead of queueing for a slot and then losing the entry's lock.
 const runningFills = new Map<string, Promise<unknown>>();
 
+/** One Data Cache read through [`retryGroupCacheFill`]: `answered` once the read has returned. */
+interface CacheRead {
+  answered: boolean;
+}
+
+// The read a fill runs under. Next's `unstable_cache` calls the fill function inside the read in
+// both of its paths, so the fill inherits the read's context either way:
+//
+// - On a miss the read awaits the fill, so the read is still unanswered when the fill finds the
+//   lock taken.
+// - On a stale entry (after `/api/revalidate` marks the tag stale) the read starts the fill as a
+//   background refresh and returns the stale value at once. The lock attempt needs a round trip
+//   to the database, so by the time the fill finds the lock taken, the read has been answered.
+//
+// Next's API offers no other way to tell the two apart.
+const cacheReads = new AsyncLocalStorage<CacheRead>();
+
+/** Whether the read that started this fill has already returned, so nobody waits on the fill. */
+function readAnswered(): boolean {
+  return cacheReads.getStore()?.answered === true;
+}
+
 /**
  * Run one group cache fill for the entry `key`, under a cross-instance PostgreSQL advisory lock
  * for that entry.
  *
  * In one process, a fill for an entry that is already filling shares that fill, and fills take
  * turns for [`cacheFillSlots`]; `exclusive` takes every slot. Lock contention with another
- * process (another instance, or a preview deployment on the same database) fails immediately and
- * releases the pool connection. The caller can then retry the Data Cache read without keeping a
- * database connection queued behind the active fill. Session advisory locks disappear
- * automatically if the function or its database connection terminates.
+ * process (another instance, or a preview deployment on the same database) releases the pool
+ * connection and the slot at once. Then:
+ *
+ * - A fill that a read is waiting for (a Data Cache miss) fails with
+ *   [`GroupCacheFillInProgressError`]. The read ([`retryGroupCacheFill`]) then retries the Data
+ *   Cache without keeping a database connection queued behind the active fill.
+ * - A background refresh (a stale entry, whose read has already returned the stale value) has no
+ *   read to retry. It backs off for [`CACHE_FILL_RETRY_DELAYS_MS`], holding no connection and no
+ *   slot, and tries the lock again, as often as those delays allow (about 15 seconds in all). Only
+ *   with the lock does it fill. Without this it would fail, Next would log the failure, and the
+ *   entry would stay stale until a later read started another refresh.
+ *
+ * A fill outside [`retryGroupCacheFill`] fails at once, as a waited-for fill does. Session
+ * advisory locks disappear automatically if the function or its database connection terminates.
  */
 export function withGroupCacheFillLock<T>(
   key: string,
@@ -105,15 +141,34 @@ export function withGroupCacheFillLock<T>(
   if (running !== undefined) {
     return running as Promise<T>;
   }
-  const started = withFillSlots(exclusive, () => fillUnderLock(cacheFillLockId(key), fill)).finally(
-    () => {
-      runningFills.delete(key);
-    },
-  );
+  const started = fillWhenLocked(cacheFillLockId(key), fill, exclusive).finally(() => {
+    runningFills.delete(key);
+  });
   runningFills.set(key, started);
   return started;
 }
 
+async function fillWhenLocked<T>(
+  lockId: number,
+  fill: () => Promise<T>,
+  exclusive: boolean,
+): Promise<T> {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await withFillSlots(exclusive, () => fillUnderLock(lockId, fill));
+    } catch (error) {
+      if (
+        !(error instanceof GroupCacheFillInProgressError) ||
+        !readAnswered() ||
+        attempt >= CACHE_FILL_RETRY_DELAYS_MS.length
+      ) {
+        throw error;
+      }
+    }
+    await new Promise((resolve) => setTimeout(resolve, CACHE_FILL_RETRY_DELAYS_MS[attempt]));
+  }
+}
+
 async function fillUnderLock<T>(lockId: number, fill: () => Promise<T>): Promise<T> {
   const lock = [GROUP_CACHE_FILL_LOCK_SPACE, lockId];
   const client = await getPool().connect();
@@ -155,19 +210,34 @@ async function fillUnderLock<T>(lockId: number, fill: () => Promise<T>): Promise
   }
 }
 
-/** Retry a Data Cache read while another process owns the entry's fill lock. */
+/**
+ * Retry a Data Cache read while another process owns the entry's fill lock. A fill that `read`
+ * starts runs as part of this read: once the read has returned, a fill still running is a
+ * background refresh, which waits for the lock instead of failing (see
+ * [`withGroupCacheFillLock`]).
+ */
 export async function retryGroupCacheFill<T>(
   read: () => Promise<T>,
   retryDelaysMs: readonly number[] = CACHE_FILL_RETRY_DELAYS_MS,
 ): Promise<T> {
-  for (let attempt = 0; ; attempt += 1) {
-    try {
-      return await read();
-    } catch (error) {
-      if (!(error instanceof GroupCacheFillInProgressError) || attempt >= retryDelaysMs.length) {
-        throw error;
+  const current: CacheRead = { answered: false };
+  try {
+    return await cacheReads.run(current, async () => {
+      for (let attempt = 0; ; attempt += 1) {
+        try {
+          return await read();
+        } catch (error) {
+          if (
+            !(error instanceof GroupCacheFillInProgressError) ||
+            attempt >= retryDelaysMs.length
+          ) {
+            throw error;
+          }
+          await new Promise((resolve) => setTimeout(resolve, retryDelaysMs[attempt]));
+        }
       }
-      await new Promise((resolve) => setTimeout(resolve, retryDelaysMs[attempt]));
-    }
+    });
+  } finally {
+    current.answered = true;
   }
 }
diff --git a/bench/web/lib/data-cache.test.ts b/bench/web/lib/data-cache.test.ts
index 54cdc75..cdc5389 100644
--- a/bench/web/lib/data-cache.test.ts
+++ b/bench/web/lib/data-cache.test.ts
@@ -96,6 +96,29 @@ describe('data-cache wrappers', () => {
     expect(withGroupCacheFillLock.mock.calls[1]![2]).toBeUndefined();
   });
 
+  // A fill learns from the read it runs in whether anyone still waits for it (a background
+  // refresh of a stale entry does not), so every locked fill must start inside its read.
+  it('starts every locked fill inside a cache read that retries on contention', async () => {
+    let reading = false;
+    const startedInRead: boolean[] = [];
+    retryGroupCacheFill.mockImplementation(async (read: () => Promise<unknown>) => {
+      reading = true;
+      try {
+        return await read();
+      } finally {
+        reading = false;
+      }
+    });
+    withGroupCacheFillLock.mockImplementation((_key, fill) => {
+      startedInRead.push(reading);
+      return fill();
+    });
+
+    await cachedGroups();
+    await cachedDefaultGroupCharts('gs');
+    expect(startedInRead).toEqual([true, true]);
+  });
+
   it('reads and fills an aliased slug under its canonical slug', async () => {
     const { collectGroupCharts, chartPayload } = await import('@/lib/queries');
     await cachedDefaultGroupCharts('gs-alias');

From b78f0fddcf4cdcdf33acbed2fcb6765048258940 Mon Sep 17 00:00:00 2001
From: Will Manning <will@willmanning.io>
Date: Fri, 30 Oct 2026 09:26:26 -0400
Subject: [PATCH 3/9] bench: drop fetch failures caused by leaving the page

Leaving a page cancels its in-flight fetches. In WebKit each one
rejects with TypeError "Load failed" as the navigation starts, before
pagehide, the same error as a real network failure. So on Back from a
chart page the hover-dwell ?n=all fetch logged "bench: full history
fetch failed" and put the chip in its error state, and on Back from the
landing page an open group's bundle fetch showed every card's error.
No unhandled rejection came from bench's code: each path caught the
error, but reported it as real. Next's own ?_rsc prefetch rejects the
same way and Next catches it.

lib/page-leave.ts holds a TypeError, or an AbortError that no
controller of ours raised (Firefox), for one second. If pagehide fires,
the failure is dropped, and reported only if the page comes back from
the back/forward cache. Otherwise it reports as before. HTTP errors,
timeouts and our own aborts are unchanged. It listens only to pagehide
and pageshow: a beforeunload listener would keep Firefox from caching
the page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Will Manning <will@willmanning.io>
---
 .../components/Chart.lazy-hydration.test.tsx  |  38 ++++++
 bench/web/components/Chart.loading.test.tsx   |  81 ++++++++++++
 bench/web/components/chart/controller.ts      |  42 +++++--
 bench/web/lib/chart-store/bundles.ts          |  19 ++-
 bench/web/lib/page-leave.test.ts              |  98 +++++++++++++++
 bench/web/lib/page-leave.ts                   | 117 ++++++++++++++++++
 6 files changed, 377 insertions(+), 18 deletions(-)
 create mode 100644 bench/web/lib/page-leave.test.ts
 create mode 100644 bench/web/lib/page-leave.ts

diff --git a/bench/web/components/Chart.lazy-hydration.test.tsx b/bench/web/components/Chart.lazy-hydration.test.tsx
index 20172f4..f0ae071 100644
--- a/bench/web/components/Chart.lazy-hydration.test.tsx
+++ b/bench/web/components/Chart.lazy-hydration.test.tsx
@@ -10,6 +10,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { Chart } from '@/components/Chart';
 import { GroupBody } from '@/components/GroupBody';
 import { FETCH_TIMEOUT_MS } from '@/lib/chart-format';
+import { PAGE_LEAVE_GRACE_MS } from '@/lib/page-leave';
 import { bundleQueue, hydrationQueue, resetPayloadCache } from '@/lib/chart-store';
 
 vi.mock('@/lib/chart-js', () => ({
@@ -512,6 +513,43 @@ describe('PR-5.0.97 group-bundle hydration', () => {
     },
   );
 
+  // Leaving the page cancels the bundle fetch. WebKit rejects it with a `TypeError` ("Load
+  // failed") before the page's `pagehide`, the same error as a real network failure.
+  it('drops a bundle failure quietly when the page is being left', async () => {
+    vi.useFakeTimers();
+    let reject: (e: unknown) => void = () => {};
+    vi.stubGlobal('fetch', (url: string | URL) => {
+      fetchCalls.push(String(url));
+      return new Promise<Response>((_resolve, rej) => {
+        reject = rej;
+      });
+    });
+    await renderGroup(2);
+    await act(async () => {
+      MockIO.instances[0]!.fire();
+      MockIO.instances[1]!.fire();
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(bundleFetchCount()).toBe(1);
+    await act(async () => {
+      reject(new TypeError('Load failed'));
+      await vi.advanceTimersByTimeAsync(0);
+      window.dispatchEvent(new Event('pagehide'));
+      await vi.advanceTimersByTimeAsync(PAGE_LEAVE_GRACE_MS * 5);
+    });
+    expect(container.querySelectorAll('[data-role="fetch-retry"]')).toHaveLength(0);
+    expect(container.querySelectorAll('.chart-error')).toHaveLength(0);
+    expect(chartFetchCount()).toBe(0);
+
+    // Back from the back/forward cache: the group did lose its charts, so the retry shows.
+    await act(async () => {
+      window.dispatchEvent(new Event('pageshow'));
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(container.querySelectorAll('[data-role="fetch-retry"]')).toHaveLength(2);
+    expect(chartFetchCount()).toBe(0);
+  });
+
   it('closing the group aborts the in-flight bundle (its fetch signal aborts)', async () => {
     const signals: AbortSignal[] = [];
     vi.stubGlobal('fetch', (url: string | URL, init?: { signal?: AbortSignal }) => {
diff --git a/bench/web/components/Chart.loading.test.tsx b/bench/web/components/Chart.loading.test.tsx
index 6b9f29d..37d2438 100644
--- a/bench/web/components/Chart.loading.test.tsx
+++ b/bench/web/components/Chart.loading.test.tsx
@@ -9,6 +9,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { Chart } from '@/components/Chart';
 import { FETCH_TIMEOUT_MS } from '@/lib/chart-format';
+import { PAGE_LEAVE_GRACE_MS } from '@/lib/page-leave';
 import { fullHistoryQueue } from '@/lib/chart-store';
 import { loadChartJs } from '@/lib/chart-js';
 
@@ -557,6 +558,86 @@ describe('Chart opt-in full-history loading', () => {
     });
   });
 
+  // Leaving the page cancels its fetches. WebKit rejects them with a `TypeError` ("Load failed")
+  // before the page's `pagehide`, the same error as a real network failure.
+  describe('a fetch cancelled by leaving the page', () => {
+    function stubRejectableFetch(urlPart: string): { reject: (e: unknown) => void } {
+      let rejecter: (e: unknown) => void = () => {};
+      responders.push({
+        match: (u) => u.includes(urlPart),
+        respond: () =>
+          new Promise<Response>((_res, rej) => {
+            rejecter = rej;
+          }),
+      });
+      return { reject: (e) => rejecter(e) };
+    }
+
+    async function leaveThenShow(shown: () => void): Promise<void> {
+      await act(async () => {
+        window.dispatchEvent(new Event('pagehide'));
+        await vi.advanceTimersByTimeAsync(PAGE_LEAVE_GRACE_MS * 5);
+      });
+      shown();
+      // Back from the back/forward cache: the page did lose the data, so now it reports.
+      await act(async () => {
+        window.dispatchEvent(new Event('pageshow'));
+        await vi.advanceTimersByTimeAsync(0);
+      });
+    }
+
+    it('drops the full-history failure quietly', async () => {
+      const full = stubRejectableFetch('n=all');
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const chip = await renderOpenGroup();
+      vi.useFakeTimers();
+      await act(async () => {
+        chip?.click();
+        await vi.advanceTimersByTimeAsync(0);
+      });
+      await act(async () => {
+        full.reject(new TypeError('Load failed'));
+        await vi.advanceTimersByTimeAsync(0);
+      });
+      await leaveThenShow(() => {
+        expect(warn).not.toHaveBeenCalled();
+        expect(chip?.dataset.state).not.toBe('error');
+      });
+      expect(chip?.dataset.state).toBe('error');
+    });
+
+    it('drops the initial fetch failure quietly', async () => {
+      vi.useFakeTimers();
+      const initial = stubRejectableFetch('n=100');
+      await renderOpenGroup();
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(0);
+        initial.reject(new TypeError('Load failed'));
+        await vi.advanceTimersByTimeAsync(0);
+      });
+      await leaveThenShow(() => {
+        expect(container.querySelector('.chart-error')).toBeNull();
+      });
+      expect(container.querySelector('.chart-error [data-role="fetch-retry"]')).not.toBeNull();
+    });
+
+    it('still reports a network failure while the page stays', async () => {
+      vi.useFakeTimers();
+      const initial = stubRejectableFetch('n=100');
+      await renderOpenGroup();
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(0);
+        initial.reject(new TypeError('Failed to fetch'));
+        await vi.advanceTimersByTimeAsync(PAGE_LEAVE_GRACE_MS - 1);
+      });
+      expect(container.querySelector('.chart-error')).toBeNull();
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(1);
+      });
+      expect(container.querySelector('.chart-error')?.textContent).toContain('Failed to fetch');
+    });
+  });
+
   describe('PR-5.0.95 loading spinner', () => {
     it('renders an animated spinner element (not bare text) while loading', async () => {
       // A never-resolving window fetch keeps the card in the loading state.
diff --git a/bench/web/components/chart/controller.ts b/bench/web/components/chart/controller.ts
index 3a2a303..9713a0a 100644
--- a/bench/web/components/chart/controller.ts
+++ b/bench/web/components/chart/controller.ts
@@ -42,6 +42,7 @@ import {
   retryGroupBundle,
   subscribeGroupBundleRetry,
 } from '@/lib/chart-store';
+import { unlessPageLeft } from '@/lib/page-leave';
 import type { ChartResponse } from '@/lib/queries';
 import { effectiveTheme, onThemeChange } from '@/lib/theme';
 
@@ -365,15 +366,23 @@ export class ChartController {
         if (err instanceof DOMException && err.name === 'AbortError') {
           return;
         }
-        this.cb.setLoading(false);
-        const message =
-          err instanceof DOMException && err.name === 'TimeoutError'
-            ? 'timed out'
-            : err instanceof Error
-              ? err.message
-              : 'unknown error';
-        this.cb.setError(`failed to load: ${message}`);
-        this.cb.setRetryable(true);
+        // Leaving the page cancels the fetch with what looks like a network failure; that is
+        // dropped quietly (`lib/page-leave.ts`). By the time a failure reports, the island may be
+        // gone, or a reopen may have started a newer fetch whose loading state this must keep.
+        return unlessPageLeft(err, () => {
+          if (state.disposed || state.payload || state.initialFetchEntry !== null) {
+            return;
+          }
+          this.cb.setLoading(false);
+          const message =
+            err instanceof DOMException && err.name === 'TimeoutError'
+              ? 'timed out'
+              : err instanceof Error
+                ? err.message
+                : 'unknown error';
+          this.cb.setError(`failed to load: ${message}`);
+          this.cb.setRetryable(true);
+        });
       },
     );
   }
@@ -494,10 +503,17 @@ export class ChartController {
         if (err instanceof DOMException && err.name === 'AbortError') {
           return;
         }
-        // Quiet: the latest-100 payload is still usable. Surface to the console
-        // for debugging; the chip exposes the retry affordance.
-        console.warn('bench: full history fetch failed', err);
-        state.chipError = true;
+        // Leaving the page cancels the fetch with what looks like a network failure; that is
+        // dropped quietly (`lib/page-leave.ts`). Otherwise quiet too: the latest-100 payload is
+        // still usable. Surface to the console for debugging; the chip exposes the retry
+        // affordance.
+        return unlessPageLeft(err, () => {
+          if (state.disposed) {
+            return;
+          }
+          console.warn('bench: full history fetch failed', err);
+          state.chipError = true;
+        });
       })
       .then(() => {
         if (state.fullFetchEntry === entry) {
diff --git a/bench/web/lib/chart-store/bundles.ts b/bench/web/lib/chart-store/bundles.ts
index 2b76289..3cf331d 100644
--- a/bench/web/lib/chart-store/bundles.ts
+++ b/bench/web/lib/chart-store/bundles.ts
@@ -2,6 +2,7 @@
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
 import { chartHasRecentData, FETCH_TIMEOUT_MS } from '@/lib/chart-format';
+import { unlessPageLeft } from '@/lib/page-leave';
 import type { ChartResponse, GroupChartsResponse } from '@/lib/queries';
 
 import { noteChartRecentData, noteGroupSeries } from './group-store';
@@ -161,17 +162,25 @@ export function ensureGroupBundle(groupSlug: string, priority: number): Promise<
       }
       return { status: 'unavailable' };
     })
-    .catch((err: unknown): BundleResult => {
+    .catch((err: unknown): BundleResult | Promise<BundleResult> => {
       if (
         inFlightBundles.get(groupSlug)?.entry !== entry ||
         (controller.signal.aborted && controller.signal.reason?.name === 'AbortError')
       ) {
         return { status: 'aborted' };
       }
-      return {
-        status: 'failed',
-        error: controller.signal.aborted ? controller.signal.reason : err,
-      };
+      if (controller.signal.aborted) {
+        return { status: 'failed', error: controller.signal.reason };
+      }
+      // Leaving the page cancels the fetch with what looks like a network failure; that is
+      // dropped quietly (`lib/page-leave.ts`). A group closed meanwhile has aborted it.
+      return unlessPageLeft(
+        err,
+        (): BundleResult =>
+          inFlightBundles.get(groupSlug)?.entry === entry
+            ? { status: 'failed', error: err }
+            : { status: 'aborted' },
+      );
     })
     .then((result): BundleResult => {
       if (inFlightBundles.get(groupSlug)?.entry !== entry) {
diff --git a/bench/web/lib/page-leave.test.ts b/bench/web/lib/page-leave.test.ts
new file mode 100644
index 0000000..41feeed
--- /dev/null
+++ b/bench/web/lib/page-leave.test.ts
@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { PAGE_LEAVE_GRACE_MS, unlessPageLeft, watchPageLeave } from '@/lib/page-leave';
+
+// A window stand-in: the helper only listens on it.
+function fakeWindow(): Window {
+  return new EventTarget() as unknown as Window;
+}
+
+describe('unlessPageLeft', () => {
+  let win: Window;
+  let report: ReturnType<typeof vi.fn<() => string>>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    win = fakeWindow();
+    // As the module does for the real window when it loads.
+    watchPageLeave(win);
+    report = vi.fn(() => 'reported');
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('reports a failure that leaving the page cannot cause at once', () => {
+    for (const error of [
+      new Error('HTTP 500'),
+      new DOMException('Fetch timed out', 'TimeoutError'),
+      new SyntaxError('Unexpected end of JSON input'),
+    ]) {
+      expect(unlessPageLeft(error, report, win)).toBe('reported');
+    }
+    expect(report).toHaveBeenCalledTimes(3);
+  });
+
+  it('reports at once without a window (on the server)', () => {
+    expect(unlessPageLeft(new TypeError('fetch failed'), report, undefined)).toBe('reported');
+  });
+
+  it('reports a network failure after the grace while the page stays', async () => {
+    const result = unlessPageLeft(new TypeError('Failed to fetch'), report, win);
+    await vi.advanceTimersByTimeAsync(PAGE_LEAVE_GRACE_MS - 1);
+    expect(report).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(1);
+    await expect(result).resolves.toBe('reported');
+  });
+
+  it('drops a network failure when the page starts to unload within the grace', async () => {
+    const result = unlessPageLeft(new TypeError('Load failed'), report, win);
+    await vi.advanceTimersByTimeAsync(20);
+    win.dispatchEvent(new Event('pagehide'));
+    await vi.advanceTimersByTimeAsync(PAGE_LEAVE_GRACE_MS * 10);
+    expect(report).not.toHaveBeenCalled();
+
+    // Restored from the back/forward cache: the data never came, so the failure counts now.
+    win.dispatchEvent(new Event('pageshow'));
+    await expect(result).resolves.toBe('reported');
+  });
+
+  it('drops an AbortError that no controller of ours raised (Firefox)', async () => {
+    void unlessPageLeft(new DOMException('The operation was aborted.', 'AbortError'), report, win);
+    win.dispatchEvent(new Event('pagehide'));
+    await vi.advanceTimersByTimeAsync(PAGE_LEAVE_GRACE_MS * 10);
+    expect(report).not.toHaveBeenCalled();
+  });
+
+  it('holds a failure that comes after the page hid until it shows again', async () => {
+    win.dispatchEvent(new Event('pagehide'));
+    const result = unlessPageLeft(new TypeError('Load failed'), report, win);
+    await vi.advanceTimersByTimeAsync(PAGE_LEAVE_GRACE_MS * 10);
+    expect(report).not.toHaveBeenCalled();
+    win.dispatchEvent(new Event('pageshow'));
+    await expect(result).resolves.toBe('reported');
+
+    // Shown again, a later failure waits only for the grace.
+    const later = unlessPageLeft(new TypeError('Failed to fetch'), report, win);
+    await vi.advanceTimersByTimeAsync(PAGE_LEAVE_GRACE_MS);
+    await expect(later).resolves.toBe('reported');
+  });
+
+  it('rejects when the report throws', async () => {
+    const failure = new Error('island gone');
+    const result = unlessPageLeft(
+      new TypeError('Failed to fetch'),
+      () => {
+        throw failure;
+      },
+      win,
+    );
+    const settled = expect(result).rejects.toBe(failure);
+    await vi.advanceTimersByTimeAsync(PAGE_LEAVE_GRACE_MS);
+    await settled;
+  });
+});
diff --git a/bench/web/lib/page-leave.ts b/bench/web/lib/page-leave.ts
new file mode 100644
index 0000000..f3cc32c
--- /dev/null
+++ b/bench/web/lib/page-leave.ts
@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+/**
+ * Fetch failures caused by leaving the page.
+ *
+ * Leaving the page (Back from a chart page, a link, a reload) cancels its in-flight fetches.
+ * WebKit rejects each one with a `TypeError` ("Load failed") as the navigation starts, before the
+ * page's `pagehide`; Firefox rejects with an `AbortError` that no `AbortController` of ours
+ * raised. A real network failure is a `TypeError` too, so the error alone does not tell them
+ * apart. [`unlessPageLeft`] therefore holds such a failure for [`PAGE_LEAVE_GRACE_MS`]: if the
+ * page fires `pagehide` meanwhile, or already has, the failure is dropped quietly, and only a
+ * page restored from the back/forward cache (`pageshow`) reports it, because that page did lose
+ * the data. Any other failure (an HTTP status, a timeout, a bad body) reports at once.
+ *
+ * Only `pagehide` and `pageshow` are watched: a `beforeunload` listener would keep Firefox from
+ * putting the page in its back/forward cache.
+ */
+
+/** How long a network failure waits for the page to start unloading before it counts. */
+export const PAGE_LEAVE_GRACE_MS = 1000;
+
+interface LeaveWatch {
+  /** `pagehide` fired, and no `pageshow` since. */
+  left: boolean;
+  onHide: Set<() => void>;
+  onShow: Set<() => void>;
+}
+
+const watches = new WeakMap<Window, LeaveWatch>();
+
+function runAll(callbacks: Set<() => void>): void {
+  const pending = [...callbacks];
+  callbacks.clear();
+  for (const callback of pending) {
+    callback();
+  }
+}
+
+function leaveWatch(win: Window): LeaveWatch {
+  let watch = watches.get(win);
+  if (watch === undefined) {
+    const created: LeaveWatch = { left: false, onHide: new Set(), onShow: new Set() };
+    win.addEventListener('pagehide', () => {
+      created.left = true;
+      runAll(created.onHide);
+    });
+    win.addEventListener('pageshow', () => {
+      created.left = false;
+      runAll(created.onShow);
+    });
+    watches.set(win, created);
+    watch = created;
+  }
+  return watch;
+}
+
+/** Start watching `win` for `pagehide` and `pageshow`, once per window. The module does this for
+ * the page's window when it loads, so a `pagehide` before the first failure is not missed. */
+export function watchPageLeave(win: Window): void {
+  leaveWatch(win);
+}
+
+if (typeof window !== 'undefined') {
+  watchPageLeave(window);
+}
+
+/** Whether `error` is how a browser fails a fetch that leaving the page cancelled. */
+function mayBeFromLeaving(error: unknown): boolean {
+  return (
+    error instanceof TypeError ||
+    (typeof error === 'object' &&
+      error !== null &&
+      (error as { name?: unknown }).name === 'AbortError')
+  );
+}
+
+/**
+ * Report a fetch failure with `report`, unless leaving the page caused it. A failure that cannot
+ * come from leaving the page reports at once, and this returns what `report` returns. Otherwise
+ * it returns a promise: it reports after [`PAGE_LEAVE_GRACE_MS`] if the page has not started to
+ * unload by then; if it has, it reports only when the page is shown again from the back/forward
+ * cache, which for a page that unloads is never. The caller checks in `report` that the failure
+ * still matters (the island may be gone, or a newer fetch running).
+ */
+export function unlessPageLeft<T>(
+  error: unknown,
+  report: () => T,
+  win: Window | undefined = typeof window === 'undefined' ? undefined : window,
+): T | Promise<T> {
+  if (win === undefined || !mayBeFromLeaving(error)) {
+    return report();
+  }
+  const watch = leaveWatch(win);
+  return new Promise<T>((resolve, reject) => {
+    const settle = (): void => {
+      try {
+        resolve(report());
+      } catch (reportError) {
+        reject(reportError);
+      }
+    };
+    if (watch.left) {
+      watch.onShow.add(settle);
+      return;
+    }
+    const onHide = (): void => {
+      clearTimeout(timer);
+      watch.onShow.add(settle);
+    };
+    const timer = setTimeout(() => {
+      watch.onHide.delete(onHide);
+      settle();
+    }, PAGE_LEAVE_GRACE_MS);
+    watch.onHide.add(onHide);
+  });
+}

From 09a77826a3dab5bdcc27001c7d9b434887d9eafd Mon Sep 17 00:00:00 2001
From: Will Manning <will@willmanning.io>
Date: Fri, 30 Oct 2026 09:29:10 -0400
Subject: [PATCH 4/9] bench: coalesce the filter bar's URL writes with the open
 groups'

Each chip click called history.replaceState at once. Safari refuses
more than 100 calls in 10 seconds, and Next.js adds one to each of
ours, so about 50 fast chip clicks could replace the page with Next's
error page, as group toggles did before they were coalesced.

lib/url-writes.ts generalizes the open groups' scheduler: the fragment
and the filter query are named parts of one per-window schedule. A
write applies every pending part in one replaceState call, at once
after a quiet spell, otherwise once a burst stops, and never closer
than 300 ms to the last write. The fragment part is still dropped when
the fragment changes under it; a path change drops every part.
open-groups.ts keeps its API on top of it. The filter bar also makes a
pending write on pagehide; on the landing page LandingState's flushes
before a chart link and on pagehide now cover the filter too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Will Manning <will@willmanning.io>
---
 bench/web/components/FilterBar.test.tsx |  80 +++++++++-
 bench/web/components/FilterBar.tsx      |  37 ++++-
 bench/web/lib/open-groups.ts            | 136 ++++++-----------
 bench/web/lib/url-writes.test.ts        | 118 ++++++++++++++
 bench/web/lib/url-writes.ts             | 195 ++++++++++++++++++++++++
 5 files changed, 467 insertions(+), 99 deletions(-)
 create mode 100644 bench/web/lib/url-writes.test.ts
 create mode 100644 bench/web/lib/url-writes.ts

diff --git a/bench/web/components/FilterBar.test.tsx b/bench/web/components/FilterBar.test.tsx
index 08b27ec..187de26 100644
--- a/bench/web/components/FilterBar.test.tsx
+++ b/bench/web/components/FilterBar.test.tsx
@@ -5,11 +5,17 @@
 
 import { act } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { FilterBar } from '@/components/FilterBar';
 import { parseFilterCsv, seriesPassesFilter } from '@/lib/chart-format';
 import { getGlobalFilterSnapshot } from '@/lib/chart-store';
+import { resetUrlWrites, URL_WRITE_DELAY_MS } from '@/lib/url-writes';
+
+/** Fake the write scheduler's timers and its clock, `performance.now()`. */
+function useFakeClock(): void {
+  vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date', 'performance'] });
+}
 
 const universe = { engines: ['duckdb', 'datafusion'], formats: ['vortex', 'parquet', 'lance'] };
 
@@ -19,6 +25,7 @@ describe('global filter URL round trips', () => {
 
   beforeEach(() => {
     (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+    resetUrlWrites(window);
     container = document.createElement('div');
     document.body.appendChild(container);
   });
@@ -26,6 +33,8 @@ describe('global filter URL round trips', () => {
   afterEach(async () => {
     await act(async () => root.unmount());
     container.remove();
+    vi.useRealTimers();
+    resetUrlWrites(window);
   });
 
   async function mount(): Promise<void> {
@@ -50,7 +59,16 @@ describe('global filter URL round trips', () => {
     });
   }
 
+  /** The URL once a pending write has landed: chip clicks inside the write delay wait for it. */
+  async function settledUrl(): Promise<URL> {
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, URL_WRITE_DELAY_MS));
+    });
+    return new URL(window.location.href);
+  }
+
   async function reload(): Promise<void> {
+    await settledUrl();
     await act(async () => root.unmount());
     await mount();
   }
@@ -68,7 +86,7 @@ describe('global filter URL round trips', () => {
 
       for (const engine of universe.engines) await click('engine', engine);
       for (const format of ['vortex', 'parquet']) await click('format', format);
-      let url = new URL(window.location.href);
+      let url = await settledUrl();
       expect(url.searchParams.get('engine')).toBe('');
       expect(url.searchParams.get('format')).toBe('');
       await reload();
@@ -76,7 +94,7 @@ describe('global filter URL round trips', () => {
 
       await click('engine', '*');
       await click('format', '*');
-      url = new URL(window.location.href);
+      url = await settledUrl();
       expect(url.searchParams.has('engine')).toBe(false);
       expect(url.searchParams.get('format')).toBe('vortex,parquet,lance');
       expect(url.searchParams.get('n')).toBe('all');
@@ -100,8 +118,62 @@ describe('global filter URL round trips', () => {
     expect(seriesPassesFilter({ engine: 'duckdb', format: 'lance' }, active, universe)).toBe(false);
     expect(container.querySelector('[data-role="filter-badge"]')?.textContent).toBe('3');
     await click('engine', '*');
-    expect(new URL(window.location.href).searchParams.get('format')).toBe('vortex,old,older');
+    expect((await settledUrl()).searchParams.get('format')).toBe('vortex,old,older');
     await reload();
     expect(getGlobalFilterSnapshot().active.formats).toEqual(['vortex', 'old', 'older']);
   });
+
+  // Safari refuses more than 100 `history.replaceState` calls in 10 seconds, and Next.js adds one
+  // of its own to each of ours, so the chips share the open groups' coalesced writes.
+  it('writes the URL a few times for a burst of chip clicks, and ends current', async () => {
+    window.history.replaceState(null, '', '/?n=all#tpc-h-nvme-sf-1');
+    await mount();
+    useFakeClock();
+    const replaceState = vi.spyOn(window.history, 'replaceState');
+    const writes: number[] = [];
+    replaceState.mockImplementation(function (this: History, ...args) {
+      writes.push(Date.now());
+      return History.prototype.replaceState.apply(this, args);
+    });
+
+    // 200 clicks 25 ms apart: 5 seconds, twice Safari's budget of calls if each one wrote.
+    for (let i = 0; i < 200; i += 1) {
+      await click('engine', 'duckdb');
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(25);
+      });
+    }
+    expect(writes.length).toBeLessThanOrEqual(3);
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(URL_WRITE_DELAY_MS);
+    });
+    expect(writes.length).toBeLessThanOrEqual(4);
+
+    // 200 toggles leave duckdb as it started: on.
+    const url = new URL(window.location.href);
+    expect(url.searchParams.has('engine')).toBe(false);
+    expect(url.searchParams.get('n')).toBe('all');
+    expect(url.hash).toBe('#tpc-h-nvme-sf-1');
+
+    // One more click after a quiet spell writes at once.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(URL_WRITE_DELAY_MS);
+    });
+    await click('engine', 'duckdb');
+    expect(new URL(window.location.href).searchParams.get('engine')).toBe('datafusion');
+  });
+
+  it('writes a pending chip change when the page is hidden', async () => {
+    window.history.replaceState(null, '', '/chart/qm.example');
+    await mount();
+    useFakeClock();
+    await click('format', 'vortex');
+    await click('format', 'parquet');
+    expect(new URL(window.location.href).searchParams.get('format')).toBe('parquet');
+
+    await act(async () => {
+      window.dispatchEvent(new Event('pagehide'));
+    });
+    expect(new URL(window.location.href).searchParams.get('format')).toBe('');
+  });
 });
diff --git a/bench/web/components/FilterBar.tsx b/bench/web/components/FilterBar.tsx
index 516295b..6046494 100644
--- a/bench/web/components/FilterBar.tsx
+++ b/bench/web/components/FilterBar.tsx
@@ -18,6 +18,7 @@ import {
   toggleGlobalFilterValue,
 } from '@/lib/chart-store';
 import { FilterIcon } from '@/components/icons';
+import { flushUrlWrites, scheduleUrlWrite } from '@/lib/url-writes';
 
 /**
  * The global engine/format filter dropdown in the sticky header, the client
@@ -32,7 +33,12 @@ import { FilterIcon } from '@/components/icons';
  * indicator. Every change re-paints the chips (via the store subscription, here
  * and in every chart island) and syncs the URL `?engine=`/`?format=` allowlists
  * with `history.replaceState`, so a refresh or share preserves the view; the
- * params are omitted only when the active set matches the defaults.
+ * params are omitted only when the active set matches the defaults. The URL
+ * writes go through the coalesced schedule the landing page's open groups use
+ * (`lib/url-writes.ts`): at once after a quiet spell, otherwise once a burst of
+ * clicks stops, because Safari refuses more than 100 `replaceState` calls in 10
+ * seconds and Next.js adds one to each of ours. A write still pending when the
+ * page is hidden is made then.
  *
  * Without JavaScript the dropdown cannot open, so it carries
  * `data-requires-js` and is hidden (globals.css).
@@ -81,6 +87,16 @@ export function FilterBar({
     ? snapshot.active.formats
     : seedActiveFormats(initialFormats, universe.formats);
 
+  // Make a pending URL write when the page is left, so Back and a restored tab
+  // return to the current chips. On the landing page `LandingState` flushes too.
+  useEffect(() => {
+    const onPageHide = (): void => {
+      flushUrlWrites(window);
+    };
+    window.addEventListener('pagehide', onPageHide);
+    return () => window.removeEventListener('pagehide', onPageHide);
+  }, []);
+
   // Close on outside click and on Escape, mirroring v3's document listeners.
   useEffect(() => {
     if (!open) {
@@ -207,20 +223,25 @@ function FilterRow({
   );
 }
 
+// The filter's part in the coalesced URL writes.
+const FILTER_PART = 'filters';
+
 /**
  * Mirror the active filter onto the URL as `?engine=`/`?format=` allowlists via
- * `history.replaceState`. Only default selections omit their parameter. An
- * empty selection writes an empty value, and all formats includes Lance.
+ * `history.replaceState`, on the coalesced schedule ([`scheduleUrlWrite`]).
+ * Only default selections omit their parameter. An empty selection writes an
+ * empty value, and all formats includes Lance. The write reads the store when
+ * it is made, so a burst of clicks writes the state it ends in.
  */
 function syncFilterUrl(): void {
   if (!window.history?.replaceState) {
     return;
   }
-  const { universe, active } = getGlobalFilterSnapshot();
-  const url = new URL(window.location.href);
-  syncDimensionUrl(url, 'engine', active.engines, universe.engines);
-  syncDimensionUrl(url, 'format', active.formats, seedActiveFormats(null, universe.formats));
-  window.history.replaceState(null, '', url.toString());
+  scheduleUrlWrite(window, FILTER_PART, (url) => {
+    const { universe, active } = getGlobalFilterSnapshot();
+    syncDimensionUrl(url, 'engine', active.engines, universe.engines);
+    syncDimensionUrl(url, 'format', active.formats, seedActiveFormats(null, universe.formats));
+  });
 }
 
 function syncDimensionUrl(url: URL, paramName: string, active: string[], defaults: string[]): void {
diff --git a/bench/web/lib/open-groups.ts b/bench/web/lib/open-groups.ts
index 715f03b..f0aa975 100644
--- a/bench/web/lib/open-groups.ts
+++ b/bench/web/lib/open-groups.ts
@@ -14,7 +14,8 @@
  * the group nav) rewrites the fragment with [`syncOpenFragment`], which uses
  * `history.replaceState`, so a toggle adds no history entry. Toggles go
  * through [`scheduleOpenFragmentSync`], which coalesces a burst of them into
- * two writes (see there for why). Readers: the pre-paint
+ * two writes, on the schedule the filter bar's query writes share
+ * (`lib/url-writes.ts`). Readers: the pre-paint
  * script ([`OpenGroupsScript`]) opens the listed groups before the first
  * paint and leaves a marker on its document ([`takeOpenGroupsBootstrap`]).
  * After hydration, [`LandingState`] takes that marker and writes the fragment
@@ -31,6 +32,16 @@
  * `instanceof`, so a test can run them against a second JSDOM realm.
  */
 
+import {
+  cancelUrlWrite,
+  flushUrlWrites,
+  resetUrlWrites,
+  scheduleUrlWrite,
+  URL_WRITE_DELAY_MS,
+  type UrlEdit,
+  writeUrlNow,
+} from '@/lib/url-writes';
+
 /** One group section on the page: its readable anchor (the section `id`) and
  * its opaque API slug (`data-group-slug`). */
 export interface GroupRef {
@@ -186,6 +197,18 @@ export function scrollToGroup(doc: Document, anchor: string): boolean {
   return true;
 }
 
+// The fragment's part in the coalesced URL writes (`lib/url-writes.ts`).
+const FRAGMENT_PART = 'open-groups';
+
+/** Write the open groups into `url`'s fragment. A page without group sections is left alone. */
+function editOpenFragment(doc: Document): UrlEdit {
+  return (url) => {
+    if (groupSections(doc).length > 0) {
+      url.hash = formatOpenFragment(openAnchors(doc));
+    }
+  };
+}
+
 /**
  * Write the open groups into the fragment now, keeping the path and the
  * query. It writes with `history.replaceState`, and only when the URL would
@@ -194,124 +217,63 @@ export function scrollToGroup(doc: Document, anchor: string): boolean {
  * next toggle tries again. A page without group sections is left alone.
  * Returns whether it wrote.
  *
- * The write is current, so it also drops a write that
- * [`scheduleOpenFragmentSync`] has pending.
+ * The write is current, so it replaces a write that
+ * [`scheduleOpenFragmentSync`] has pending, and makes any other pending URL
+ * write (the filter bar's) with it.
  */
 export function syncOpenFragment(win: Window): boolean {
-  cancelOpenFragmentSync(win);
-  const doc = win.document;
-  if (groupSections(doc).length === 0) {
-    return false;
-  }
-  const { pathname, search, hash } = win.location;
-  const target = `${pathname}${search}${formatOpenFragment(openAnchors(doc))}`;
-  if (target === `${pathname}${search}${hash}`) {
-    return false;
-  }
-  lastWrites.set(win, win.performance.now());
-  try {
-    win.history.replaceState(null, '', target);
-  } catch {
-    return false;
-  }
-  return true;
+  return writeUrlNow(win, FRAGMENT_PART, editOpenFragment(win.document));
 }
 
 /**
  * The shortest time between two fragment writes from toggles, in
- * milliseconds; also how long the last toggle of a burst waits before its
- * write. At most about three writes a second, whatever the toggling.
+ * milliseconds: the delay of the coalesced URL writes, [`URL_WRITE_DELAY_MS`].
  */
-export const OPEN_FRAGMENT_SYNC_DELAY_MS = 300;
-
-/** A scheduled write: its timer, and the path and fragment when it was
- * scheduled. */
-interface PendingSync {
-  timer: ReturnType<typeof setTimeout>;
-  pathname: string;
-  hash: string;
-}
-
-const pendingSyncs = new WeakMap<Window, PendingSync>();
-// When [`syncOpenFragment`] last called `replaceState`, per window, on the
-// monotonic `performance.now()` clock: a wall clock that jumps forward would
-// let two writes come closer than the delay.
-const lastWrites = new WeakMap<Window, number>();
+export const OPEN_FRAGMENT_SYNC_DELAY_MS = URL_WRITE_DELAY_MS;
 
 /**
- * Write the open groups into the fragment after a toggle, at most once per
- * [`OPEN_FRAGMENT_SYNC_DELAY_MS`]. After a quiet spell (no write and nothing
- * pending for the delay) it writes at once, so the URL of a page with one
- * toggle is current at once, ready for a reload. Inside the delay it waits
- * instead, and each call restarts the wait, so the rest of a burst (fast
- * clicks, or Enter held on a summary) is one more write, made once the burst
- * stops. Writes are therefore always at least the delay apart.
- *
- * Why: Safari throws a `SecurityError` from a document's 101st
- * `history.replaceState` within 10 seconds, and Next.js makes a second call
- * of its own after each of ours (its router re-syncs its history state). Ours
- * is caught; Next's is not, and the App Router then replaces the page with its
- * error page. A write per toggle reached that limit after about 50 toggles.
- * At one write per 300 ms the page makes at most about 68 calls in 10 seconds.
+ * Write the open groups into the fragment after a toggle, through the
+ * coalesced URL writes ([`scheduleUrlWrite`]): at once after a quiet spell,
+ * otherwise once the burst stops, and never closer than
+ * [`OPEN_FRAGMENT_SYNC_DELAY_MS`] to another write. The filter bar's writes
+ * share the same schedule, so toggles and chip clicks together stay under
+ * Safari's limit of 100 `history.replaceState` calls in 10 seconds (see
+ * `lib/url-writes.ts` for why that limit matters).
  *
  * The URL can therefore lag the page by the delay. Code that reads the URL as
  * the open set (the scroll save on leaving the page) calls
  * [`flushOpenFragmentSync`] first.
  */
 export function scheduleOpenFragmentSync(win: Window): void {
-  const lastWrite = lastWrites.get(win);
-  const quiet =
-    !pendingSyncs.has(win) &&
-    (lastWrite === undefined || win.performance.now() - lastWrite >= OPEN_FRAGMENT_SYNC_DELAY_MS);
-  if (quiet) {
-    syncOpenFragment(win);
-    return;
-  }
-  cancelOpenFragmentSync(win);
-  const timer = setTimeout(() => {
-    flushOpenFragmentSync(win);
-  }, OPEN_FRAGMENT_SYNC_DELAY_MS);
-  pendingSyncs.set(win, { timer, pathname: win.location.pathname, hash: win.location.hash });
+  scheduleUrlWrite(win, FRAGMENT_PART, editOpenFragment(win.document), { ownsHash: true });
 }
 
 /**
- * Make a pending write now, instead of after the delay. Returns whether it
- * wrote; with nothing pending it writes nothing.
+ * Make a pending URL write now, instead of after the delay: the fragment's,
+ * and any other part's. Returns whether it wrote; with nothing pending it
+ * writes nothing.
  *
  * A fragment that changed after the write was scheduled is not ours (a link,
  * or one typed into the address bar, whose `hashchange` may not have run
- * yet), so the pending write is dropped rather than written over it; the
- * `hashchange` handler reads that fragment and writes the open set itself.
+ * yet), so the pending fragment write is dropped rather than written over it;
+ * the `hashchange` handler reads that fragment and writes the open set itself.
  * A path that changed means the page is another route's now (a client
  * navigation that has not unmounted the landing page yet), so the write is
  * dropped too.
  */
 export function flushOpenFragmentSync(win: Window): boolean {
-  const pending = pendingSyncs.get(win);
-  if (pending === undefined) {
-    return false;
-  }
-  cancelOpenFragmentSync(win);
-  if (win.location.pathname !== pending.pathname || win.location.hash !== pending.hash) {
-    return false;
-  }
-  return syncOpenFragment(win);
+  return flushUrlWrites(win);
 }
 
-/** Drop a pending write, if any, without writing. */
+/** Drop a pending fragment write, if any, without writing. */
 export function cancelOpenFragmentSync(win: Window): void {
-  const pending = pendingSyncs.get(win);
-  if (pending !== undefined) {
-    clearTimeout(pending.timer);
-    pendingSyncs.delete(win);
-  }
+  cancelUrlWrite(win, FRAGMENT_PART);
 }
 
-/** Drop a pending write and forget the last write's time. TEST-ONLY: a page
- * load starts with neither. */
+/** Drop every pending URL write and forget the last write's time. TEST-ONLY:
+ * a page load starts with neither. */
 export function resetOpenFragmentSync(win: Window): void {
-  cancelOpenFragmentSync(win);
-  lastWrites.delete(win);
+  resetUrlWrites(win);
 }
 
 /**
diff --git a/bench/web/lib/url-writes.test.ts b/bench/web/lib/url-writes.test.ts
new file mode 100644
index 0000000..ace1800
--- /dev/null
+++ b/bench/web/lib/url-writes.test.ts
@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  cancelUrlWrite,
+  flushUrlWrites,
+  resetUrlWrites,
+  scheduleUrlWrite,
+  URL_WRITE_DELAY_MS,
+  urlWritePending,
+  writeUrlNow,
+} from '@/lib/url-writes';
+
+const setHash = (hash: string) => (url: URL) => {
+  url.hash = hash;
+};
+const setParam = (name: string, value: string) => (url: URL) => {
+  url.searchParams.set(name, value);
+};
+
+describe('coalesced URL writes', () => {
+  let writes: string[];
+
+  beforeEach(() => {
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'Date', 'performance'] });
+    window.history.replaceState(null, '', '/?n=all');
+    resetUrlWrites(window);
+    writes = [];
+    const replaceState = History.prototype.replaceState;
+    vi.spyOn(window.history, 'replaceState').mockImplementation(function (
+      this: History,
+      data,
+      unused,
+      url,
+    ) {
+      writes.push(String(url));
+      replaceState.call(this, data, unused, url);
+    });
+  });
+
+  afterEach(() => {
+    resetUrlWrites(window);
+    vi.useRealTimers();
+  });
+
+  function here(): string {
+    return `${window.location.pathname}${window.location.search}${window.location.hash}`;
+  }
+
+  it('writes every pending part in one call', () => {
+    scheduleUrlWrite(window, 'filters', setParam('engine', 'a'));
+    scheduleUrlWrite(window, 'filters', setParam('engine', 'b'));
+    scheduleUrlWrite(window, 'open-groups', setHash('#g1'), { ownsHash: true });
+    expect(writes).toEqual(['/?n=all&engine=a']);
+
+    vi.advanceTimersByTime(URL_WRITE_DELAY_MS);
+    expect(writes).toEqual(['/?n=all&engine=a', '/?n=all&engine=b#g1']);
+    expect(here()).toBe('/?n=all&engine=b#g1');
+  });
+
+  it('shares one rate limit between the parts', () => {
+    scheduleUrlWrite(window, 'open-groups', setHash('#g1'), { ownsHash: true });
+    // Inside the delay after the fragment write, a filter write waits.
+    vi.advanceTimersByTime(URL_WRITE_DELAY_MS - 1);
+    scheduleUrlWrite(window, 'filters', setParam('format', ''));
+    expect(writes).toHaveLength(1);
+    vi.advanceTimersByTime(URL_WRITE_DELAY_MS);
+    expect(writes).toHaveLength(2);
+    expect(here()).toBe('/?n=all&format=#g1');
+  });
+
+  it('writes a part now with the other pending parts', () => {
+    scheduleUrlWrite(window, 'filters', setParam('engine', 'a'));
+    scheduleUrlWrite(window, 'filters', setParam('engine', 'b'));
+    expect(writeUrlNow(window, 'open-groups', setHash('#g2'))).toBe(true);
+    expect(here()).toBe('/?n=all&engine=b#g2');
+    expect(urlWritePending(window, 'filters')).toBe(false);
+  });
+
+  it('cancels one part and keeps the other', () => {
+    scheduleUrlWrite(window, 'filters', setParam('engine', 'a'));
+    scheduleUrlWrite(window, 'filters', setParam('engine', 'b'));
+    scheduleUrlWrite(window, 'open-groups', setHash('#g1'), { ownsHash: true });
+    cancelUrlWrite(window, 'open-groups');
+    expect(flushUrlWrites(window)).toBe(true);
+    expect(here()).toBe('/?n=all&engine=b');
+  });
+
+  it('drops the fragment part when the fragment changed, but not the query part', () => {
+    scheduleUrlWrite(window, 'filters', setParam('engine', 'a'));
+    scheduleUrlWrite(window, 'filters', setParam('engine', 'b'));
+    scheduleUrlWrite(window, 'open-groups', setHash('#g1'), { ownsHash: true });
+    // A link changes the fragment before its `hashchange` runs.
+    History.prototype.replaceState.call(window.history, null, '', '/?n=all&engine=a#typed');
+    expect(flushUrlWrites(window)).toBe(true);
+    expect(here()).toBe('/?n=all&engine=b#typed');
+  });
+
+  it('drops every part when the path changed', () => {
+    scheduleUrlWrite(window, 'filters', setParam('engine', 'a'));
+    scheduleUrlWrite(window, 'filters', setParam('engine', 'b'));
+    History.prototype.replaceState.call(window.history, null, '', '/chart/x');
+    expect(flushUrlWrites(window)).toBe(false);
+    expect(here()).toBe('/chart/x');
+  });
+
+  it('survives a browser that refuses the write', () => {
+    vi.mocked(window.history.replaceState).mockImplementationOnce(() => {
+      throw new DOMException('too many calls', 'SecurityError');
+    });
+    expect(writeUrlNow(window, 'filters', setParam('engine', 'a'))).toBe(false);
+    expect(here()).toBe('/?n=all');
+  });
+});
diff --git a/bench/web/lib/url-writes.ts b/bench/web/lib/url-writes.ts
new file mode 100644
index 0000000..5616928
--- /dev/null
+++ b/bench/web/lib/url-writes.ts
@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+/**
+ * Coalesced `history.replaceState` writes of page state into the URL.
+ *
+ * Two parts of the page keep state in the URL: the landing page's open groups in the fragment
+ * (`lib/open-groups.ts`) and the filter bar's chips in the query (`components/FilterBar.tsx`).
+ * Each is a *part*: a name and an edit that writes its current state into a `URL`. A part either
+ * writes now ([`writeUrlNow`]) or schedules a write ([`scheduleUrlWrite`]), and every write
+ * applies all the parts that are pending, in one `replaceState` call, and only when the URL would
+ * change.
+ *
+ * Why: Safari throws a `SecurityError` from a document's 101st `history.replaceState` within 10
+ * seconds, and Next.js makes a second call of its own after each of ours (its router re-syncs its
+ * history state). Ours is caught; Next's is not, and the App Router then replaces the page with
+ * its error page. A write per toggle or chip click reached that limit after about 50 clicks.
+ * Scheduled writes are at least [`URL_WRITE_DELAY_MS`] apart, so the page makes at most about 68
+ * calls in 10 seconds however fast the clicks come.
+ *
+ * Every helper takes the window it acts on, so a test can run them against a second JSDOM realm.
+ */
+
+/**
+ * The shortest time between two scheduled writes, in milliseconds; also how long the last change
+ * of a burst waits before its write. At most about three writes a second.
+ */
+export const URL_WRITE_DELAY_MS = 300;
+
+/** Write a part's current state into `url`. Leave `url` alone to write nothing for the part. */
+export type UrlEdit = (url: URL) => void;
+
+/** A part waiting for the next write: its edit, and the URL when it was scheduled. */
+interface PendingPart {
+  edit: UrlEdit;
+  pathname: string;
+  hash: string;
+  /** Drop the part when the fragment changed after it was scheduled. */
+  ownsHash: boolean;
+}
+
+interface PendingWrite {
+  timer: ReturnType<typeof setTimeout> | null;
+  parts: Map<string, PendingPart>;
+}
+
+const pendingWrites = new WeakMap<Window, PendingWrite>();
+// When this module last called `replaceState`, per window, on the monotonic `performance.now()`
+// clock: a wall clock that jumps forward would let two writes come closer than the delay.
+const lastWrites = new WeakMap<Window, number>();
+
+function pendingFor(win: Window): PendingWrite {
+  let pending = pendingWrites.get(win);
+  if (pending === undefined) {
+    pending = { timer: null, parts: new Map() };
+    pendingWrites.set(win, pending);
+  }
+  return pending;
+}
+
+function addPart(win: Window, name: string, edit: UrlEdit, ownsHash: boolean): void {
+  pendingFor(win).parts.set(name, {
+    edit,
+    pathname: win.location.pathname,
+    hash: win.location.hash,
+    ownsHash,
+  });
+}
+
+/**
+ * Apply every pending part and write the URL now, cancelling the scheduled write. Returns whether
+ * it called `replaceState`.
+ *
+ * A part whose path changed since it was scheduled is dropped: the page is another route's now (a
+ * client navigation that has not unmounted the old page yet). A part that owns the fragment is
+ * dropped too when the fragment changed: that fragment is not ours (a link, or one typed into the
+ * address bar, whose `hashchange` may not have run yet), and the `hashchange` handler writes the
+ * part itself.
+ */
+function writePending(win: Window): boolean {
+  const pending = pendingWrites.get(win);
+  if (pending === undefined) {
+    return false;
+  }
+  if (pending.timer !== null) {
+    clearTimeout(pending.timer);
+  }
+  pendingWrites.delete(win);
+  const { pathname, search, hash, href } = win.location;
+  const url = new URL(href);
+  for (const part of pending.parts.values()) {
+    if (part.pathname === pathname && (!part.ownsHash || part.hash === hash)) {
+      part.edit(url);
+    }
+  }
+  const target = `${url.pathname}${url.search}${url.hash}`;
+  if (target === `${pathname}${search}${hash}`) {
+    return false;
+  }
+  lastWrites.set(win, win.performance.now());
+  try {
+    win.history.replaceState(null, '', target);
+  } catch {
+    // Browsers rate-limit `replaceState` (Safari throws a `SecurityError` past its limit). The
+    // state stays on the page, and the next write tries again.
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Write the part `name` now, with any other part that is pending. For a change the reader asked
+ * to see in the URL at once (a new fragment, the group nav). Returns whether it wrote.
+ */
+export function writeUrlNow(win: Window, name: string, edit: UrlEdit): boolean {
+  addPart(win, name, edit, false);
+  return writePending(win);
+}
+
+/**
+ * Write the part `name` after a change, at most once per [`URL_WRITE_DELAY_MS`]. After a quiet
+ * spell (no write and nothing pending for the delay) it writes at once, so the URL of a page with
+ * one change is current at once, ready for a reload. Inside the delay it waits instead, and each
+ * call restarts the wait, so the rest of a burst (fast clicks, or Enter held on a button) is one
+ * more write, made once the burst stops. Writes are therefore always at least the delay apart.
+ *
+ * `ownsHash` marks a part that writes the fragment: it is dropped if the fragment changes before
+ * the write (see [`flushUrlWrites`]).
+ *
+ * The URL can therefore lag the page by the delay. Code that reads the URL as page state (the
+ * scroll save on leaving the page) calls [`flushUrlWrites`] first.
+ */
+export function scheduleUrlWrite(
+  win: Window,
+  name: string,
+  edit: UrlEdit,
+  { ownsHash = false }: { ownsHash?: boolean } = {},
+): void {
+  const lastWrite = lastWrites.get(win);
+  const quiet =
+    !pendingWrites.has(win) &&
+    (lastWrite === undefined || win.performance.now() - lastWrite >= URL_WRITE_DELAY_MS);
+  addPart(win, name, edit, ownsHash);
+  const pending = pendingFor(win);
+  if (quiet) {
+    writePending(win);
+    return;
+  }
+  if (pending.timer !== null) {
+    clearTimeout(pending.timer);
+  }
+  pending.timer = setTimeout(() => {
+    writePending(win);
+  }, URL_WRITE_DELAY_MS);
+}
+
+/**
+ * Make a pending write now, instead of after the delay. Returns whether it wrote; with nothing
+ * pending it writes nothing. A part whose path changed since it was scheduled, or that owns the
+ * fragment and the fragment changed, is dropped rather than written.
+ */
+export function flushUrlWrites(win: Window): boolean {
+  return writePending(win);
+}
+
+/** Drop the pending write of the part `name`, if any, without writing it. */
+export function cancelUrlWrite(win: Window, name: string): void {
+  const pending = pendingWrites.get(win);
+  if (pending === undefined) {
+    return;
+  }
+  pending.parts.delete(name);
+  if (pending.parts.size === 0) {
+    if (pending.timer !== null) {
+      clearTimeout(pending.timer);
+    }
+    pendingWrites.delete(win);
+  }
+}
+
+/** Whether the part `name` has a write pending. */
+export function urlWritePending(win: Window, name: string): boolean {
+  return pendingWrites.get(win)?.parts.has(name) === true;
+}
+
+/** Drop every pending write and forget the last write's time. TEST-ONLY: a page load starts with
+ * neither. */
+export function resetUrlWrites(win: Window): void {
+  const pending = pendingWrites.get(win);
+  if (pending?.timer != null) {
+    clearTimeout(pending.timer);
+  }
+  pendingWrites.delete(win);
+  lastWrites.delete(win);
+}

From 030cf64068929e7ed7e60bdae940201f5a30ea51 Mon Sep 17 00:00:00 2001
From: Will Manning <will@willmanning.io>
Date: Fri, 30 Oct 2026 09:30:23 -0400
Subject: [PATCH 5/9] bench: scroll to the top when the header logo is clicked
 on /

The logo is a Link to /. On / it soft-navigated to /, which dropped the
fragment that lists the open groups (and the filter query) while the
groups stayed open, so the URL no longer matched the page.

On / a plain click, or Enter on the focused logo, now scrolls to the
top without navigating, smoothly unless the visitor prefers reduced
motion. A click with a modifier key or another button is left to the
browser, and on every other page the logo navigates home as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Will Manning <will@willmanning.io>
---
 bench/web/components/Header.logo.test.tsx | 91 +++++++++++++++++++++++
 bench/web/components/Header.tsx           | 45 ++++++++++-
 2 files changed, 134 insertions(+), 2 deletions(-)
 create mode 100644 bench/web/components/Header.logo.test.tsx

diff --git a/bench/web/components/Header.logo.test.tsx b/bench/web/components/Header.logo.test.tsx
new file mode 100644
index 0000000..3c588f3
--- /dev/null
+++ b/bench/web/components/Header.logo.test.tsx
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+// @vitest-environment jsdom
+
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { Header } from '@/components/Header';
+
+// The logo is a `next/link` to `/`. On `/` a soft navigation to `/` would drop the fragment that
+// lists the open groups while the groups stay open, so there the logo scrolls to the top instead.
+describe('the header logo', () => {
+  let root: Root | null = null;
+  let host: HTMLDivElement;
+  let scrollTo: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    scrollTo = vi.fn();
+    vi.stubGlobal('scrollTo', scrollTo);
+    root = createRoot(host);
+    act(() => {
+      root?.render(<Header />);
+    });
+  });
+
+  afterEach(() => {
+    act(() => root?.unmount());
+    root = null;
+    host.remove();
+    vi.unstubAllGlobals();
+    document.documentElement.className = '';
+  });
+
+  /** Click the logo the way `init` says; returns whether the click was allowed to navigate. */
+  function clickLogo(init: MouseEventInit = {}): boolean {
+    const logo = host.querySelector<HTMLAnchorElement>('a.logo-link')!;
+    const event = new MouseEvent('click', { bubbles: true, cancelable: true, button: 0, ...init });
+    act(() => {
+      logo.dispatchEvent(event);
+    });
+    return !event.defaultPrevented;
+  }
+
+  it('scrolls to the top of `/` in place, keeping the fragment', () => {
+    window.history.replaceState(null, '', '/?engine=duckdb#tpc-h-nvme-sf-1,clickbench');
+    expect(clickLogo()).toBe(false);
+    expect(scrollTo).toHaveBeenCalledExactlyOnceWith({ top: 0, behavior: 'smooth' });
+    expect(window.location.hash).toBe('#tpc-h-nvme-sf-1,clickbench');
+    expect(window.location.search).toBe('?engine=duckdb');
+  });
+
+  it('scrolls at once for a visitor who prefers reduced motion', () => {
+    vi.stubGlobal(
+      'matchMedia',
+      vi.fn((query: string) => ({ matches: query === '(prefers-reduced-motion: reduce)' })),
+    );
+    window.history.replaceState(null, '', '/#clickbench');
+    expect(clickLogo()).toBe(false);
+    expect(scrollTo).toHaveBeenCalledExactlyOnceWith({ top: 0, behavior: 'auto' });
+  });
+
+  it('treats keyboard activation like a click', () => {
+    window.history.replaceState(null, '', '/#clickbench');
+    // Enter on a link fires a click with no pointer detail.
+    expect(clickLogo({ detail: 0 })).toBe(false);
+    expect(scrollTo).toHaveBeenCalledOnce();
+  });
+
+  it.each([
+    ['ctrlKey', { ctrlKey: true }],
+    ['metaKey', { metaKey: true }],
+    ['shiftKey', { shiftKey: true }],
+    ['altKey', { altKey: true }],
+    ['middle button', { button: 1 }],
+  ])('leaves a modified click (%s) to the browser', (_name, init) => {
+    window.history.replaceState(null, '', '/#clickbench');
+    expect(clickLogo(init)).toBe(true);
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+
+  it('navigates home from any other page', () => {
+    window.history.replaceState(null, '', '/chart/qm.example');
+    expect(clickLogo()).toBe(true);
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+});
diff --git a/bench/web/components/Header.tsx b/bench/web/components/Header.tsx
index 81804bc..aed0bc5 100644
--- a/bench/web/components/Header.tsx
+++ b/bench/web/components/Header.tsx
@@ -4,7 +4,13 @@
 'use client';
 
 import Link from 'next/link';
-import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import {
+  type MouseEvent as ReactMouseEvent,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react';
 
 import { FilterBar } from '@/components/FilterBar';
 import type { FilterUniverse } from '@/lib/chart-format';
@@ -45,6 +51,10 @@ import { effectiveTheme } from '@/lib/theme';
  * the mount effect immediately corrects the label to name the NEXT theme, the
  * exact v3 `updateThemeButtons` sequencing.
  *
+ * The logo links home. On `/` itself a click scrolls to the top in place
+ * ([`scrollHomeInPlace`]): a soft navigation to `/` would drop the fragment that
+ * lists the open groups while the groups stayed open.
+ *
  * Without JavaScript none of the buttons can work, so each carries
  * `data-requires-js`, which hides it under the root's `no-js` class
  * (globals.css), as does the filter dropdown ([`FilterBar`]). The mobile nav
@@ -139,7 +149,12 @@ export function Header({
           >
             <MenuIcon size={18} />
           </button>
-          <Link className="logo-link" href="/" aria-label="bench.vortex.dev home">
+          <Link
+            className="logo-link"
+            href="/"
+            aria-label="bench.vortex.dev home"
+            onClick={scrollHomeInPlace}
+          >
             <img
               className="site-logo logo-light"
               src="/Vortex_Black_NoBG.svg"
@@ -235,3 +250,29 @@ export function Header({
     </header>
   );
 }
+
+/**
+ * The logo's click on `/`: scroll to the top without navigating, so the open
+ * groups, the fragment that lists them and the query stay as they are. Next's
+ * `Link` skips its navigation for a click whose default is prevented. Enter on
+ * the focused logo fires the same click. A click with a modifier key or another
+ * button (open in a new tab or window) is left to the browser, and on any other
+ * page the logo navigates home as a link. The scroll is smooth unless the
+ * visitor prefers reduced motion.
+ */
+function scrollHomeInPlace(event: ReactMouseEvent<HTMLAnchorElement>): void {
+  if (
+    event.defaultPrevented ||
+    event.button !== 0 ||
+    event.metaKey ||
+    event.ctrlKey ||
+    event.shiftKey ||
+    event.altKey ||
+    window.location.pathname !== '/'
+  ) {
+    return;
+  }
+  event.preventDefault();
+  const reduceMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches === true;
+  window.scrollTo({ top: 0, behavior: reduceMotion ? 'auto' : 'smooth' });
+}

From 45ae656d860d168cf30fa0b053c3fb61ddf00006 Mon Sep 17 00:00:00 2001
From: Will Manning <will@willmanning.io>
Date: Fri, 30 Oct 2026 09:40:05 -0400
Subject: [PATCH 6/9] bench: keep native scroll restoration while no landing
 group is open

LandingState set history.scrollRestoration to 'manual' on mount even
with every group closed. So a Reload or Back of the collapsed list
showed the page top for a frame or two and then restored after
hydration, though the collapsed list is as tall before hydration as
after and the browser could restore it itself.

The page now keeps 'auto' while no group is open and switches to
'manual' on the first open and back on the last close (toggles and
hashchange). The browser uses the mode the history entry had when the
page was left, which the page reads on arrival: with no group open and
'auto', it skips its own restore. With groups open, or 'manual' on
arrival (a group opened just before a reload whose fragment write had
not landed), the element save and restore run as before.

In Chromium and WebKit (Playwright) with no group open, Back now lands
on the first frame; Reload does in Chromium, and in WebKit after its
own 1-2 frames. With two groups open nothing changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Will Manning <will@willmanning.io>
---
 bench/docs/architecture/performance.md     |  4 +-
 bench/web/components/LandingState.test.tsx | 71 +++++++++++++++++++++-
 bench/web/components/LandingState.tsx      | 56 ++++++++++++-----
 bench/web/lib/scroll-restore.ts            |  4 +-
 4 files changed, 118 insertions(+), 17 deletions(-)

diff --git a/bench/docs/architecture/performance.md b/bench/docs/architecture/performance.md
index 99f23c7..b4f2b06 100644
--- a/bench/docs/architecture/performance.md
+++ b/bench/docs/architecture/performance.md
@@ -269,7 +269,9 @@ nor by the scroll to a link's first group. Scroll is
 restored by element, not by pixel
 ([`lib/scroll-restore.ts`](../../web/lib/scroll-restore.ts)): the open bodies
 mount only after hydration, so a saved `scrollY` would land against a shorter
-page.
+page. While no group is open the page leaves restoration to the browser
+(`history.scrollRestoration` stays `auto`), because the collapsed list is as
+tall before hydration as after; it switches to `manual` while a group is open.
 
 Measured against the previous build, the head of `claude/bench-cleanup`
 (b4caf7c): a local restore of the production dump, desktop (1440×900), no
diff --git a/bench/web/components/LandingState.test.tsx b/bench/web/components/LandingState.test.tsx
index c189c50..e4197d5 100644
--- a/bench/web/components/LandingState.test.tsx
+++ b/bench/web/components/LandingState.test.tsx
@@ -573,8 +573,43 @@ describe('LandingState', () => {
   });
 
   describe('scroll restoration', () => {
-    it('switches the page to manual scroll restoration and sets back the mode it found on unmount', async () => {
+    // The browser restores natively while no group is open: the collapsed list is the same
+    // height before and after hydration. An open group's body exists only after hydration, so
+    // then the page restores by element and the browser must not.
+    it('keeps native scroll restoration while no group is open, and manual while one is', async () => {
       await mount('/');
+      expect(window.history.scrollRestoration).toBe('auto');
+
+      disclosure(FIRST).open = true;
+      await flush();
+      expect(window.history.scrollRestoration).toBe('manual');
+
+      disclosure('clickbench').open = true;
+      disclosure(FIRST).open = false;
+      await flush();
+      expect(window.history.scrollRestoration).toBe('manual');
+
+      setAllGroupsOpen(window, false);
+      await flush();
+      expect(window.history.scrollRestoration).toBe('auto');
+
+      window.location.hash = 'random-access';
+      await flush();
+      expect(window.history.scrollRestoration).toBe('manual');
+    });
+
+    it('switches to manual on mount when the fragment opens groups', async () => {
+      await mount(`/#${FIRST},clickbench`);
+      expect(window.history.scrollRestoration).toBe('manual');
+    });
+
+    it('switches to manual on mount when the pre-paint script opened groups', async () => {
+      await hydrate('/#clickbench');
+      expect(window.history.scrollRestoration).toBe('manual');
+    });
+
+    it('sets back the mode it found on unmount', async () => {
+      await mount(`/#${FIRST}`);
       expect(window.history.scrollRestoration).toBe('manual');
 
       await act(async () => {
@@ -584,6 +619,40 @@ describe('LandingState', () => {
       expect(window.history.scrollRestoration).toBe('auto');
     });
 
+    // On Reload or Back the browser uses the mode the history entry had when the page was left.
+    it.each(['reload', 'back_forward'] as const)(
+      'on %s with no group open, leaves the scroll to the browser',
+      async (type) => {
+        navigation(type);
+        sessionStorage.setItem(
+          'bench-scroll:/',
+          JSON.stringify({ kind: 'group', slug: 'qm.click', offset: 40 }),
+        );
+        place(document.getElementById('clickbench')!, 900);
+        window.history.scrollRestoration = 'auto';
+        await mount('/');
+        await nextFrame();
+        expect(scrollTo).not.toHaveBeenCalled();
+        expect(scrollSpy).not.toHaveBeenCalled();
+      },
+    );
+
+    // A group opened just before a reload: the fragment write had not landed, so the page
+    // reloads with no group open, but the browser kept the manual mode and restores nothing.
+    it('on reload with no group open after leaving in manual mode, restores by element', async () => {
+      navigation('reload');
+      sessionStorage.setItem(
+        'bench-scroll:/',
+        JSON.stringify({ kind: 'group', slug: 'qm.click', offset: 40 }),
+      );
+      place(document.getElementById('clickbench')!, 900);
+      window.history.scrollRestoration = 'manual';
+      await mount('/');
+      await nextFrame();
+      expect(scrollTo).toHaveBeenCalledWith({ top: 860, behavior: 'instant' });
+      expect(window.history.scrollRestoration).toBe('auto');
+    });
+
     it('saves the reading position on pagehide and when a chart link is followed', async () => {
       await mount(`/#${FIRST}`);
       await flush();
diff --git a/bench/web/components/LandingState.tsx b/bench/web/components/LandingState.tsx
index b8437b7..c400108 100644
--- a/bench/web/components/LandingState.tsx
+++ b/bench/web/components/LandingState.tsx
@@ -54,10 +54,16 @@ const CHART_LINK = 'a[href^="/chart/"]';
  *   the new fragment, then opens what it lists, rewrites the fragment to the
  *   whole open set (a group that was already open fires no `toggle`, so
  *   nothing else would) and scrolls to the first listed group.
- * - **Scroll** (`lib/scroll-restore.ts`). While mounted, the page sets
- *   `history.scrollRestoration = 'manual'`, and on unmount sets back the mode
- *   it found (the browser's own on a fresh history entry; after a reload or
- *   Back, it may be the `manual` this page left on the entry). On `pagehide`,
+ * - **Scroll** (`lib/scroll-restore.ts`). While no group is open, the page
+ *   keeps `history.scrollRestoration = 'auto'`: the collapsed list is as tall
+ *   before hydration as after, so the browser's own restoration lands right,
+ *   and lands before the first paint. While a group is open it sets `manual`,
+ *   because the open bodies exist only after hydration, and restores by
+ *   element itself. It switches on every open and close, so the mode on the
+ *   history entry when the page is left is the one the browser uses on Reload
+ *   or Back. On unmount it sets back the mode it found (the browser's own on a
+ *   fresh history entry; after a reload or Back, the one this page left on the
+ *   entry). On `pagehide`,
  *   when the tab goes hidden (a mobile browser may discard a hidden tab
  *   without a `pagehide`) and when a chart link is clicked, it saves the
  *   element nearest the top of the viewport. On mount, [`planScroll`]
@@ -65,9 +71,10 @@ const CHART_LINK = 'a[href^="/chart/"]';
  *   scrolled, touched, clicked or pressed a key, it leaves the scroll alone
  *   (they have taken over); otherwise a reload or Back/Forward with a saved
  *   position restores that element to its offset (falling back to the
- *   fragment scroll if the element is gone); otherwise, if the fragment lists
- *   groups, it scrolls to the first one (a fresh visit ignores anything
- *   saved); otherwise it leaves the scroll alone.
+ *   fragment scroll if the element is gone), unless no group is open and the
+ *   entry's mode was `auto`, where the browser has restored it already;
+ *   otherwise, if the fragment lists groups, it scrolls to the first one (a
+ *   fresh visit ignores anything saved); otherwise it leaves the scroll alone.
  *
  * Both scrolls wait for the open groups' bodies to mount their cards
  * ([`groupBodiesReady`]): the upper groups' cards push a target down as they
@@ -83,11 +90,19 @@ export function LandingState(): null {
   useEffect(() => {
     let active = true;
     const { history } = window;
+    // Before anything here changes it: on a reload or Back, the mode the
+    // history entry kept, which the browser has just used.
+    firstRun.current ??= openOnFirstRun();
     const previousRestoration = history.scrollRestoration;
-    history.scrollRestoration = 'manual';
+    // `manual` while a group is open, `auto` otherwise (see above).
+    const syncRestoration = (): void => {
+      history.scrollRestoration = openGroupSlugs(document).length > 0 ? 'manual' : 'auto';
+    };
+    syncRestoration();
     const onToggle = (event: Event): void => {
       const target = event.target as Element | null;
       if (target?.matches?.('details.group-disclosure')) {
+        syncRestoration();
         scheduleOpenFragmentSync(window);
       }
     };
@@ -131,12 +146,20 @@ export function LandingState(): null {
         }
       });
     };
-    firstRun.current ??= openOnFirstRun();
-    const { saved, listed, inputBeforeMount } = firstRun.current;
-    const ready = groupBodiesReady(openGroupSlugs(document));
+    const { saved, listed, inputBeforeMount, arrivalRestoration } = firstRun.current;
+    const openSlugs = openGroupSlugs(document);
+    const ready = groupBodiesReady(openSlugs);
     const fragmentScroll = (): void => scrollToGroupAfter(ready.mounted, listed[0]);
     let cancelRestore = (): void => {};
-    const plan = planScroll(navigationKind(window), saved, listed.length > 0, inputBeforeMount);
+    // With no group open and the entry in `auto` mode, the browser restored
+    // the collapsed list itself.
+    const restoredNatively = openSlugs.length === 0 && arrivalRestoration === 'auto';
+    const plan = planScroll(
+      navigationKind(window),
+      restoredNatively ? null : saved,
+      listed.length > 0,
+      inputBeforeMount,
+    );
     if (plan.kind === 'restore') {
       pendingRestore = plan.saved;
       cancelRestore = restoreScroll(window, plan.saved, ready, fragmentScroll, () => {
@@ -151,6 +174,7 @@ export function LandingState(): null {
       cancelOpenFragmentSync(window);
       cancelRestore();
       const listedNow = openGroupsFromHash(document, window.location.hash);
+      syncRestoration();
       syncOpenFragment(window);
       scrollToGroupAfter(groupBodiesReady(openGroupSlugs(document)).mounted, listedNow[0]);
     };
@@ -176,16 +200,19 @@ export function LandingState(): null {
   return null;
 }
 /** What [`LandingState`]'s first run found: the saved position, the listed
- * groups that are open, and whether the reader moved before hydration. */
+ * groups that are open, whether the reader moved before hydration, and the
+ * scroll restoration mode the page arrived with. */
 interface FirstRun {
   saved: SavedScroll | null;
   listed: string[];
   inputBeforeMount: boolean;
+  arrivalRestoration: ScrollRestoration;
 }
 /** Take the pre-paint script's marker, read the saved position and open the
  * listed groups (or, after the script, keep what the reader left open and
  * write it to the fragment). */
 function openOnFirstRun(): FirstRun {
+  const arrivalRestoration = window.history.scrollRestoration;
   const bootstrap = takeOpenGroupsBootstrap(document);
   // Read the saved position before anything can rewrite the fragment that
   // keys it.
@@ -195,10 +222,11 @@ function openOnFirstRun(): FirstRun {
       saved,
       listed: openGroupsFromHash(document, window.location.hash),
       inputBeforeMount: false,
+      arrivalRestoration,
     };
   }
   // The script opened the listed groups; what is open now is the reader's.
   const listed = listedOpenAnchors(document, window.location.hash);
   syncOpenFragment(window);
-  return { saved, listed, inputBeforeMount: bootstrap.input };
+  return { saved, listed, inputBeforeMount: bootstrap.input, arrivalRestoration };
 }
diff --git a/bench/web/lib/scroll-restore.ts b/bench/web/lib/scroll-restore.ts
index 0dc26d2..e08b0ef 100644
--- a/bench/web/lib/scroll-restore.ts
+++ b/bench/web/lib/scroll-restore.ts
@@ -9,7 +9,9 @@ import type { GroupBodiesReady } from '@/lib/group-bodies';
  * The server never sees the fragment, so an open group's body (its toolbar and
  * chart cards) exists only after hydration, and the browser's own restoration
  * would land against a shorter page. [`LandingState`] therefore sets
- * `history.scrollRestoration = 'manual'` on `/` and does the work here:
+ * `history.scrollRestoration = 'manual'` on `/` while a group is open (with
+ * none open the collapsed list is as tall before hydration as after, so the
+ * browser's own restoration stays on) and does the work here:
  *
  * - **Save.** On `pagehide`, when the tab goes hidden, and before a chart
  *   link is followed, it records the element nearest the top of the viewport

From dc3700a69c76eb69642c175f351d425e496f1092 Mon Sep 17 00:00:00 2001
From: Will Manning <will@willmanning.io>
Date: Fri, 30 Oct 2026 10:10:32 -0400
Subject: [PATCH 7/9] bench: drop the background refresh's wait for the fill
 lock

Review found that a refresh which waits for the lock then fills again,
so after an ingest several instances repeat the same query one after
another. Within one deployment the holder's fill already refreshes the
shared entry, so the losers' failures are only log noise. Keep failing
fast and document the noise instead.

This reverts commit 1d5226f.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Will Manning <will@willmanning.io>
---
 bench/docs/architecture/read-path.md  |   5 +-
 bench/web/lib/cache-fill-lock.test.ts | 117 ----------------------
 bench/web/lib/cache-fill.test.ts      | 137 --------------------------
 bench/web/lib/cache-fill.ts           | 106 ++++----------------
 bench/web/lib/data-cache.test.ts      |  23 -----
 5 files changed, 19 insertions(+), 369 deletions(-)
 delete mode 100644 bench/web/lib/cache-fill-lock.test.ts

diff --git a/bench/docs/architecture/read-path.md b/bench/docs/architecture/read-path.md
index 682c110..90bbdf1 100644
--- a/bench/docs/architecture/read-path.md
+++ b/bench/docs/architecture/read-path.md
@@ -145,10 +145,7 @@ fills under its own PostgreSQL advisory lock (`web/lib/cache-fill.ts`), shared
 across production and preview functions. Different entries fill at once; for one
 entry, one invocation runs the fill, and contenders release their connections
 and retry the Data Cache read with bounded backoff instead of issuing duplicate
-queries. A background refresh of a stale entry has no read to retry (the read
-already returned the stale value), so when it finds the lock taken it releases
-its connection, backs off on the same schedule (about 15 seconds in all) and
-tries the lock again, and fills only once it holds the lock. A bundle's fill resolves only its own group: one family's discovery,
+queries. A bundle's fill resolves only its own group: one family's discovery,
 then that group's summary, not every group's. Entries and locks use the slug's
 canonical form, so the many spellings that decode to one group share them. In
 one process, a second request for an entry shares the running fill, and fills
diff --git a/bench/web/lib/cache-fill-lock.test.ts b/bench/web/lib/cache-fill-lock.test.ts
deleted file mode 100644
index 4ae4822..0000000
--- a/bench/web/lib/cache-fill-lock.test.ts
+++ /dev/null
@@ -1,117 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-FileCopyrightText: Copyright the Vortex contributors
-
-import { Client } from 'pg';
-import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
-
-import {
-  cacheFillLockId,
-  GroupCacheFillInProgressError,
-  retryGroupCacheFill,
-  withGroupCacheFillLock,
-} from './cache-fill';
-import { getPool, resetPool } from './db';
-import {
-  type BenchDatabase,
-  integrationDatabaseAvailable,
-  startBenchDatabase,
-} from './test-harness';
-
-const databaseAvailable = integrationDatabaseAvailable();
-
-// The two ints of the advisory lock that guards the cache entry `key` (see `cache-fill.ts`).
-function lockOf(key: string): [number, number] {
-  return [0x62656e63, cacheFillLockId(key)];
-}
-
-/** Pool clients checked out now. */
-function clientsHeld(): number {
-  const pool = getPool();
-  return pool.totalCount - pool.idleCount;
-}
-
-// Another instance holds the fill lock, as on Vercel when two functions refresh one entry.
-describe.skipIf(!databaseAvailable)('group cache fill lock (Postgres)', () => {
-  let database: BenchDatabase;
-  let other: Client;
-
-  beforeAll(async () => {
-    database = await startBenchDatabase({ applySchema: false });
-    other = new Client({
-      host: process.env.BENCH_DB_HOST,
-      port: Number(process.env.BENCH_DB_PORT),
-      user: process.env.BENCH_DB_USER,
-      password: process.env.BENCH_DB_PASSWORD,
-      database: process.env.BENCH_DB_NAME,
-      ssl: false,
-    });
-    await other.connect();
-  });
-
-  afterEach(async () => {
-    await other.query('SELECT pg_advisory_unlock_all()');
-  });
-
-  afterAll(async () => {
-    await other.end();
-    await resetPool();
-    await database.stop();
-  });
-
-  it('makes a background refresh wait for the lock, then fill under it', async () => {
-    const key = 'group-charts:background';
-    await other.query('SELECT pg_advisory_lock($1, $2)', lockOf(key));
-    // While the refresh fills, the other instance cannot take the lock.
-    const fill = vi.fn(async () => {
-      const probe = await other.query<{ acquired: boolean }>(
-        'SELECT pg_try_advisory_lock($1, $2) AS acquired',
-        lockOf(key),
-      );
-      return probe.rows[0]?.acquired === true ? 'filled without the lock' : 'fresh';
-    });
-
-    // A stale entry: the read starts the refresh and returns the stale value without waiting.
-    let refresh!: Promise<string>;
-    await expect(
-      retryGroupCacheFill(async () => {
-        refresh = withGroupCacheFillLock(key, fill);
-        return 'stale';
-      }, []),
-    ).resolves.toBe('stale');
-    const settled = refresh.then(
-      (value) => ({ value }),
-      (error: unknown) => ({ error }),
-    );
-
-    // The first try lost the lock. The refresh waits for the next one without a connection.
-    await new Promise((resolve) => setTimeout(resolve, 150));
-    expect(fill).not.toHaveBeenCalled();
-    expect(clientsHeld()).toBe(0);
-
-    await other.query('SELECT pg_advisory_unlock($1, $2)', lockOf(key));
-    await expect(settled).resolves.toEqual({ value: 'fresh' });
-    expect(fill).toHaveBeenCalledOnce();
-    expect(clientsHeld()).toBe(0);
-    // The refresh let go of the lock.
-    const after = await other.query<{ acquired: boolean }>(
-      'SELECT pg_try_advisory_lock($1, $2) AS acquired',
-      lockOf(key),
-    );
-    expect(after.rows[0]?.acquired).toBe(true);
-  });
-
-  it('fails a fill that a read waits for at once, and releases its connection', async () => {
-    const key = 'group-charts:foreground';
-    await other.query('SELECT pg_advisory_lock($1, $2)', lockOf(key));
-    const fill = vi.fn(async () => 'never');
-
-    const started = performance.now();
-    await expect(
-      retryGroupCacheFill(() => withGroupCacheFillLock(key, fill), []),
-    ).rejects.toBeInstanceOf(GroupCacheFillInProgressError);
-    // One round trip, not a wait for the lock.
-    expect(performance.now() - started).toBeLessThan(200);
-    expect(fill).not.toHaveBeenCalled();
-    expect(clientsHeld()).toBe(0);
-  });
-});
diff --git a/bench/web/lib/cache-fill.test.ts b/bench/web/lib/cache-fill.test.ts
index ef58996..b5c62ed 100644
--- a/bench/web/lib/cache-fill.test.ts
+++ b/bench/web/lib/cache-fill.test.ts
@@ -297,143 +297,6 @@ describe('cache fill slots', () => {
   });
 });
 
-describe('a background refresh that loses the lock', () => {
-  // The delays between tries of the lock, as in `cache-fill.ts`.
-  const delays = [250, 750, 2_000, 4_000, 8_000];
-
-  beforeEach(() => {
-    vi.useFakeTimers();
-    connect.mockReset();
-    query.mockReset();
-    release.mockReset();
-    connect.mockImplementation(async () => Object.assign(new EventEmitter(), { query, release }));
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  /** The lock is taken by another process for the first `taken` tries. */
-  function lockTakenFor(taken: number): void {
-    let tries = 0;
-    query.mockImplementation(async (text: string) => {
-      if (text.includes('pg_try_advisory_lock')) {
-        tries += 1;
-        return { rows: [{ acquired: tries > taken }] };
-      }
-      return { rows: [] };
-    });
-  }
-
-  /** Start a fill the way `unstable_cache` refreshes a stale entry: the read starts it and
-   * returns the stale value without waiting for it. The refresh comes back in an object: an
-   * async function that returned it bare would wait for it. */
-  async function staleRead<T>(
-    key: string,
-    fill: () => Promise<T>,
-  ): Promise<{ refresh: Promise<T> }> {
-    let refresh!: Promise<T>;
-    await expect(
-      retryGroupCacheFill(async () => {
-        refresh = withGroupCacheFillLock(key, fill);
-        return 'stale';
-      }, []),
-    ).resolves.toBe('stale');
-    // Let the refresh settle as a rejection here, not as an unhandled one.
-    refresh.catch(() => {});
-    return { refresh };
-  }
-
-  /** How many pool clients are checked out now. */
-  function clientsHeld(): number {
-    return connect.mock.calls.length - release.mock.calls.length;
-  }
-
-  it('waits for the lock without a connection, then fills', async () => {
-    lockTakenFor(2);
-    const fill = vi.fn(async () => 'fresh');
-
-    const { refresh } = await staleRead('group-charts:stale', fill);
-    await vi.advanceTimersByTimeAsync(0);
-    expect(connect).toHaveBeenCalledOnce();
-    expect(clientsHeld()).toBe(0);
-    expect(fill).not.toHaveBeenCalled();
-
-    await vi.advanceTimersByTimeAsync(delays[0]!);
-    expect(connect).toHaveBeenCalledTimes(2);
-    expect(clientsHeld()).toBe(0);
-    expect(fill).not.toHaveBeenCalled();
-
-    await vi.advanceTimersByTimeAsync(delays[1]!);
-    await expect(refresh).resolves.toBe('fresh');
-    expect(fill).toHaveBeenCalledOnce();
-    expect(connect).toHaveBeenCalledTimes(3);
-    expect(clientsHeld()).toBe(0);
-    // The fill ran under the lock, and released it.
-    expect(query.mock.calls.at(-1)![0]).toContain('pg_advisory_unlock');
-  });
-
-  it('frees its fill slot while it waits', async () => {
-    lockTakenFor(1);
-    const { refresh } = await staleRead('groups', async () => 'groups');
-    await vi.advanceTimersByTimeAsync(0);
-
-    // The group list waits for the lock. Another entry's fill takes the slots meanwhile.
-    query.mockImplementation(async (text: string) =>
-      text.includes('pg_try_advisory_lock') ? { rows: [{ acquired: true }] } : { rows: [] },
-    );
-    await expect(withGroupCacheFillLock('group-charts:other', async () => 'other')).resolves.toBe(
-      'other',
-    );
-
-    await vi.advanceTimersByTimeAsync(delays[0]!);
-    await expect(refresh).resolves.toBe('groups');
-  });
-
-  it('gives up after the bounded wait', async () => {
-    lockTakenFor(Number.POSITIVE_INFINITY);
-    const fill = vi.fn(async () => 'never');
-
-    const { refresh } = await staleRead('group-charts:busy', fill);
-    const total = delays.reduce((sum, delay) => sum + delay, 0);
-    await vi.advanceTimersByTimeAsync(total - 1);
-    expect(connect).toHaveBeenCalledTimes(delays.length);
-    await vi.advanceTimersByTimeAsync(1);
-
-    await expect(refresh).rejects.toBeInstanceOf(GroupCacheFillInProgressError);
-    expect(connect).toHaveBeenCalledTimes(delays.length + 1);
-    expect(clientsHeld()).toBe(0);
-    expect(fill).not.toHaveBeenCalled();
-  });
-
-  it('leaves a read that waits for its fill to fail fast and retry the cache', async () => {
-    lockTakenFor(Number.POSITIVE_INFINITY);
-    const fill = vi.fn(async () => 'never');
-
-    const read = retryGroupCacheFill(() => withGroupCacheFillLock('group-charts:miss', fill), []);
-    read.catch(() => {});
-    await vi.advanceTimersByTimeAsync(0);
-
-    await expect(read).rejects.toBeInstanceOf(GroupCacheFillInProgressError);
-    expect(connect).toHaveBeenCalledOnce();
-    expect(clientsHeld()).toBe(0);
-    expect(fill).not.toHaveBeenCalled();
-  });
-
-  it('does not retry a fill that fails for another reason', async () => {
-    lockTakenFor(0);
-    const failure = new Error('query failed');
-
-    const { refresh } = await staleRead('group-charts:broken', async () => {
-      throw failure;
-    });
-    await vi.advanceTimersByTimeAsync(0);
-
-    await expect(refresh).rejects.toBe(failure);
-    expect(connect).toHaveBeenCalledOnce();
-  });
-});
-
 describe('cache fill lock id', () => {
   it('is the 32-bit FNV-1a hash as a signed int4', () => {
     // The FNV-1a reference vectors: 0x811c9dc5, 0xe40c292c and 0xbf9cf968.
diff --git a/bench/web/lib/cache-fill.ts b/bench/web/lib/cache-fill.ts
index afdf56b..534428a 100644
--- a/bench/web/lib/cache-fill.ts
+++ b/bench/web/lib/cache-fill.ts
@@ -1,8 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
-import { AsyncLocalStorage } from 'node:async_hooks';
-
 import { getPool, resolvePoolMax } from '@/lib/db';
 
 // First int of every group cache fill's two-int PostgreSQL advisory-lock key: "benc". The second
@@ -11,8 +9,6 @@ import { getPool, resolvePoolMax } from '@/lib/db';
 // entries take turns.
 const GROUP_CACHE_FILL_LOCK_SPACE = 0x62656e63;
 
-// How long a read waits between retries of the Data Cache, and a background refresh between
-// tries of the lock, while another process fills the entry: 15 seconds in all.
 const CACHE_FILL_RETRY_DELAYS_MS = [250, 750, 2_000, 4_000, 8_000] as const;
 
 // At most this many fills run at once in one process, however large the pool.
@@ -89,48 +85,16 @@ async function withFillSlots<T>(exclusive: boolean, run: () => Promise<T>): Prom
 // running fill instead of queueing for a slot and then losing the entry's lock.
 const runningFills = new Map<string, Promise<unknown>>();
 
-/** One Data Cache read through [`retryGroupCacheFill`]: `answered` once the read has returned. */
-interface CacheRead {
-  answered: boolean;
-}
-
-// The read a fill runs under. Next's `unstable_cache` calls the fill function inside the read in
-// both of its paths, so the fill inherits the read's context either way:
-//
-// - On a miss the read awaits the fill, so the read is still unanswered when the fill finds the
-//   lock taken.
-// - On a stale entry (after `/api/revalidate` marks the tag stale) the read starts the fill as a
-//   background refresh and returns the stale value at once. The lock attempt needs a round trip
-//   to the database, so by the time the fill finds the lock taken, the read has been answered.
-//
-// Next's API offers no other way to tell the two apart.
-const cacheReads = new AsyncLocalStorage<CacheRead>();
-
-/** Whether the read that started this fill has already returned, so nobody waits on the fill. */
-function readAnswered(): boolean {
-  return cacheReads.getStore()?.answered === true;
-}
-
 /**
  * Run one group cache fill for the entry `key`, under a cross-instance PostgreSQL advisory lock
  * for that entry.
  *
  * In one process, a fill for an entry that is already filling shares that fill, and fills take
  * turns for [`cacheFillSlots`]; `exclusive` takes every slot. Lock contention with another
- * process (another instance, or a preview deployment on the same database) releases the pool
- * connection and the slot at once. Then:
- *
- * - A fill that a read is waiting for (a Data Cache miss) fails with
- *   [`GroupCacheFillInProgressError`]. The read ([`retryGroupCacheFill`]) then retries the Data
- *   Cache without keeping a database connection queued behind the active fill.
- * - A background refresh (a stale entry, whose read has already returned the stale value) has no
- *   read to retry. It backs off for [`CACHE_FILL_RETRY_DELAYS_MS`], holding no connection and no
- *   slot, and tries the lock again, as often as those delays allow (about 15 seconds in all). Only
- *   with the lock does it fill. Without this it would fail, Next would log the failure, and the
- *   entry would stay stale until a later read started another refresh.
- *
- * A fill outside [`retryGroupCacheFill`] fails at once, as a waited-for fill does. Session
- * advisory locks disappear automatically if the function or its database connection terminates.
+ * process (another instance, or a preview deployment on the same database) fails immediately and
+ * releases the pool connection. The caller can then retry the Data Cache read without keeping a
+ * database connection queued behind the active fill. Session advisory locks disappear
+ * automatically if the function or its database connection terminates.
  */
 export function withGroupCacheFillLock<T>(
   key: string,
@@ -141,34 +105,15 @@ export function withGroupCacheFillLock<T>(
   if (running !== undefined) {
     return running as Promise<T>;
   }
-  const started = fillWhenLocked(cacheFillLockId(key), fill, exclusive).finally(() => {
-    runningFills.delete(key);
-  });
+  const started = withFillSlots(exclusive, () => fillUnderLock(cacheFillLockId(key), fill)).finally(
+    () => {
+      runningFills.delete(key);
+    },
+  );
   runningFills.set(key, started);
   return started;
 }
 
-async function fillWhenLocked<T>(
-  lockId: number,
-  fill: () => Promise<T>,
-  exclusive: boolean,
-): Promise<T> {
-  for (let attempt = 0; ; attempt += 1) {
-    try {
-      return await withFillSlots(exclusive, () => fillUnderLock(lockId, fill));
-    } catch (error) {
-      if (
-        !(error instanceof GroupCacheFillInProgressError) ||
-        !readAnswered() ||
-        attempt >= CACHE_FILL_RETRY_DELAYS_MS.length
-      ) {
-        throw error;
-      }
-    }
-    await new Promise((resolve) => setTimeout(resolve, CACHE_FILL_RETRY_DELAYS_MS[attempt]));
-  }
-}
-
 async function fillUnderLock<T>(lockId: number, fill: () => Promise<T>): Promise<T> {
   const lock = [GROUP_CACHE_FILL_LOCK_SPACE, lockId];
   const client = await getPool().connect();
@@ -210,34 +155,19 @@ async function fillUnderLock<T>(lockId: number, fill: () => Promise<T>): Promise
   }
 }
 
-/**
- * Retry a Data Cache read while another process owns the entry's fill lock. A fill that `read`
- * starts runs as part of this read: once the read has returned, a fill still running is a
- * background refresh, which waits for the lock instead of failing (see
- * [`withGroupCacheFillLock`]).
- */
+/** Retry a Data Cache read while another process owns the entry's fill lock. */
 export async function retryGroupCacheFill<T>(
   read: () => Promise<T>,
   retryDelaysMs: readonly number[] = CACHE_FILL_RETRY_DELAYS_MS,
 ): Promise<T> {
-  const current: CacheRead = { answered: false };
-  try {
-    return await cacheReads.run(current, async () => {
-      for (let attempt = 0; ; attempt += 1) {
-        try {
-          return await read();
-        } catch (error) {
-          if (
-            !(error instanceof GroupCacheFillInProgressError) ||
-            attempt >= retryDelaysMs.length
-          ) {
-            throw error;
-          }
-          await new Promise((resolve) => setTimeout(resolve, retryDelaysMs[attempt]));
-        }
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await read();
+    } catch (error) {
+      if (!(error instanceof GroupCacheFillInProgressError) || attempt >= retryDelaysMs.length) {
+        throw error;
       }
-    });
-  } finally {
-    current.answered = true;
+      await new Promise((resolve) => setTimeout(resolve, retryDelaysMs[attempt]));
+    }
   }
 }
diff --git a/bench/web/lib/data-cache.test.ts b/bench/web/lib/data-cache.test.ts
index cdc5389..54cdc75 100644
--- a/bench/web/lib/data-cache.test.ts
+++ b/bench/web/lib/data-cache.test.ts
@@ -96,29 +96,6 @@ describe('data-cache wrappers', () => {
     expect(withGroupCacheFillLock.mock.calls[1]![2]).toBeUndefined();
   });
 
-  // A fill learns from the read it runs in whether anyone still waits for it (a background
-  // refresh of a stale entry does not), so every locked fill must start inside its read.
-  it('starts every locked fill inside a cache read that retries on contention', async () => {
-    let reading = false;
-    const startedInRead: boolean[] = [];
-    retryGroupCacheFill.mockImplementation(async (read: () => Promise<unknown>) => {
-      reading = true;
-      try {
-        return await read();
-      } finally {
-        reading = false;
-      }
-    });
-    withGroupCacheFillLock.mockImplementation((_key, fill) => {
-      startedInRead.push(reading);
-      return fill();
-    });
-
-    await cachedGroups();
-    await cachedDefaultGroupCharts('gs');
-    expect(startedInRead).toEqual([true, true]);
-  });
-
   it('reads and fills an aliased slug under its canonical slug', async () => {
     const { collectGroupCharts, chartPayload } = await import('@/lib/queries');
     await cachedDefaultGroupCharts('gs-alias');

From 8d18d40b74fc0a09c219decf3ca399f282038d82 Mon Sep 17 00:00:00 2001
From: Will Manning <will@willmanning.io>
Date: Fri, 30 Oct 2026 10:11:25 -0400
Subject: [PATCH 8/9] bench: flush chip changes before a link is followed; trim
 the pin test

A chip change still waiting to be written was dropped when a same-origin
link navigated within 300 ms, so Back showed the URL without it. The
filter bar now writes it on the link's click, as it does on pagehide.

Drop the Renovate rule-order test: the pin-equality test is the one
that guards the pnpm refusal. Document the expected lock errors after
an ingest in read-path.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Will Manning <will@willmanning.io>
---
 bench/docs/architecture/read-path.md    |  6 ++++++
 bench/web/components/FilterBar.test.tsx | 19 ++++++++++++++++++
 bench/web/components/FilterBar.tsx      | 17 ++++++++++++++--
 bench/web/lib/package-manager.test.ts   | 26 -------------------------
 4 files changed, 40 insertions(+), 28 deletions(-)

diff --git a/bench/docs/architecture/read-path.md b/bench/docs/architecture/read-path.md
index 90bbdf1..350e16c 100644
--- a/bench/docs/architecture/read-path.md
+++ b/bench/docs/architecture/read-path.md
@@ -155,6 +155,12 @@ the fills never ask for more connections at once than the pool holds. The pool
 is never smaller than 2 (`resolvePoolMax`), because a fill queries on a second
 connection while the first holds its lock.
 
+A background refresh (a stale read after an ingest, see above) has no retry: if
+another invocation holds the entry's lock, it fails at once and Next logs the
+`GroupCacheFillInProgressError`. That is expected. The lock holder's fill
+refreshes the shared entry, so a few of these errors after each ingest cost
+nothing; waiting and filling again would repeat the holder's query.
+
 `bench_read` uses a **static password** rather than RDS IAM auth because the
 Vercel runtime has no AWS credentials to mint an IAM token, and RDS `rds_iam`
 membership disables password auth. The CI roles (`migrator`, `bench_ingest`) do
diff --git a/bench/web/components/FilterBar.test.tsx b/bench/web/components/FilterBar.test.tsx
index 187de26..2a35237 100644
--- a/bench/web/components/FilterBar.test.tsx
+++ b/bench/web/components/FilterBar.test.tsx
@@ -176,4 +176,23 @@ describe('global filter URL round trips', () => {
     });
     expect(new URL(window.location.href).searchParams.get('format')).toBe('');
   });
+
+  it('writes a pending chip change before a same-origin link is followed', async () => {
+    window.history.replaceState(null, '', '/chart/qm.example');
+    await mount();
+    useFakeClock();
+    await click('format', 'vortex');
+    await click('format', 'parquet');
+    expect(new URL(window.location.href).searchParams.get('format')).toBe('parquet');
+
+    const link = document.createElement('a');
+    link.href = '/';
+    link.addEventListener('click', (event) => event.preventDefault());
+    document.body.appendChild(link);
+    await act(async () => {
+      link.click();
+    });
+    link.remove();
+    expect(new URL(window.location.href).searchParams.get('format')).toBe('');
+  });
 });
diff --git a/bench/web/components/FilterBar.tsx b/bench/web/components/FilterBar.tsx
index 6046494..0c7793f 100644
--- a/bench/web/components/FilterBar.tsx
+++ b/bench/web/components/FilterBar.tsx
@@ -88,13 +88,26 @@ export function FilterBar({
     : seedActiveFormats(initialFormats, universe.formats);
 
   // Make a pending URL write when the page is left, so Back and a restored tab
-  // return to the current chips. On the landing page `LandingState` flushes too.
+  // return to the current chips: on `pagehide`, and before a same-origin link
+  // navigates on the client (a pending write is dropped once the path changes).
+  // Capturing, so a handler that stops the click cannot skip the flush. On the
+  // landing page `LandingState` flushes too.
   useEffect(() => {
     const onPageHide = (): void => {
       flushUrlWrites(window);
     };
+    const onClick = (event: MouseEvent): void => {
+      const link = (event.target as Element | null)?.closest?.('a[href]');
+      if (link instanceof HTMLAnchorElement && link.origin === window.location.origin) {
+        flushUrlWrites(window);
+      }
+    };
     window.addEventListener('pagehide', onPageHide);
-    return () => window.removeEventListener('pagehide', onPageHide);
+    document.addEventListener('click', onClick, true);
+    return () => {
+      window.removeEventListener('pagehide', onPageHide);
+      document.removeEventListener('click', onClick, true);
+    };
   }, []);
 
   // Close on outside click and on Escape, mirroring v3's document listeners.
diff --git a/bench/web/lib/package-manager.test.ts b/bench/web/lib/package-manager.test.ts
index 21c7936..b362ad8 100644
--- a/bench/web/lib/package-manager.test.ts
+++ b/bench/web/lib/package-manager.test.ts
@@ -13,16 +13,8 @@ interface PackageJson {
   packageManager?: string;
 }
 
-interface RenovateRule {
-  matchDepTypes?: string[];
-  groupName?: string;
-  additionalBranchPrefix?: string;
-  commitMessageSuffix?: string;
-}
-
 const root = readJson<PackageJson>('../../../package.json');
 const bench = readJson<PackageJson>('../package.json');
-const renovate = readJson<{ packageRules: RenovateRule[] }>('../../../renovate.json');
 
 // pnpm refuses to install in a project whose `packageManager` names another package manager, so
 // the pin keeps a pnpm command in bench/web from installing around Bun's release-age cooldown.
@@ -31,22 +23,4 @@ describe('bench/web packageManager', () => {
     expect(root.packageManager).toMatch(/^bun@\d+\.\d+\.\d+$/);
     expect(bench.packageManager).toBe(root.packageManager);
   });
-
-  it('is updated with the root pin in one Renovate branch', () => {
-    // Renovate's npm manager reads `packageManager` as depType `packageManager`. Without this rule
-    // bench's copy would take the `bench-` branch prefix and land in a PR of its own.
-    const benchRule = renovate.packageRules.findIndex(
-      (rule) => rule.additionalBranchPrefix === 'bench-',
-    );
-    const pinRule = renovate.packageRules.findIndex((rule) =>
-      rule.matchDepTypes?.includes('packageManager'),
-    );
-    expect(benchRule).toBeGreaterThanOrEqual(0);
-    // Later rules win, so the pin's rule must come after bench's.
-    expect(pinRule).toBeGreaterThan(benchRule);
-    const rule = renovate.packageRules[pinRule]!;
-    expect(rule.groupName).toBeTruthy();
-    expect(rule.additionalBranchPrefix).toBe('');
-    expect(rule.commitMessageSuffix).toBe('');
-  });
 });

From 620cde57d23ea5809d67f78603daae8bbc277e16 Mon Sep 17 00:00:00 2001
From: Will Manning <will@willmanning.io>
Date: Fri, 30 Oct 2026 10:12:20 -0400
Subject: [PATCH 9/9] bench: wait 300 ms for the landing data before the
 loading view

On Vercel a Data Cache hit is a network read. On 2026-10-30, 1 of 12
cache-busted production renders of / missed the 150 ms wait and streamed
the loading view, a copy the CDN keeps for five minutes. 300 ms gives a
hit room; a miss still shows the loading view early.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Will Manning <will@willmanning.io>
---
 bench/docs/architecture/performance.md | 12 +++++++-----
 bench/web/app/page.tsx                 | 12 ++++++------
 2 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/bench/docs/architecture/performance.md b/bench/docs/architecture/performance.md
index b4f2b06..5457c71 100644
--- a/bench/docs/architecture/performance.md
+++ b/bench/docs/architecture/performance.md
@@ -295,7 +295,7 @@ with one-off scripts that are not in this repository.
 
 Each request to `/` decides how to send the groups
 ([`app/page.tsx`](../../web/app/page.tsx)). It starts reading them and waits up
-to 150 ms (`LOADING_VIEW_AFTER_MS`). A Data Cache hit answers well inside that,
+to 300 ms (`LOADING_VIEW_AFTER_MS`). A Data Cache hit answers well inside that,
 so the page renders the groups directly, with no Suspense boundary: plain,
 visible HTML that a reader with JavaScript off can read in full. A miss gets a
 Suspense boundary instead: the "Loading benchmark summaries…" view streams at
@@ -330,10 +330,12 @@ keep misses rare, and an ingest causes none: it marks the entries stale rather
 than dropping them (see "Refresh on ingest"), so the next render of `/` takes
 the plain-HTML path with the previous data.
 
-The 150 ms threshold was measured against the local Data Cache, where a hit
-answers in a few milliseconds. Check it against Vercel's function logs on a
-preview deployment before relying on it: a hit there reads the cache over the
-network.
+The threshold was first 150 ms, measured against the local Data Cache, where a
+hit answers in a few milliseconds. On Vercel a hit reads the cache over the
+network: on 2026-10-30, 1 of 12 cache-busted production renders of `/` missed
+150 ms and streamed the loading view, which the CDN would then keep for five
+minutes. At 300 ms a hit has room, and a miss still shows the loading view
+early.
 
 ### Visual downsampling (LTTB)
 
diff --git a/bench/web/app/page.tsx b/bench/web/app/page.tsx
index d5afca8..c36e19b 100644
--- a/bench/web/app/page.tsx
+++ b/bench/web/app/page.tsx
@@ -93,13 +93,13 @@ export default async function Home({
 
 /**
  * How long the landing page waits for its data before it streams the loading
- * view instead. A Data Cache hit reads in a few milliseconds, well inside it,
- * so the common case stays plain HTML; a miss reads the database, about half a
- * second locally and seconds in production after an idle gap. Long enough that
- * a busy server's hit still lands inside it, short enough that a reader on a
- * miss sees the loading view almost at once.
+ * view instead. A Data Cache hit reads in a few milliseconds locally, but on
+ * Vercel it is a network read, and at 150 ms about one hit in twelve missed the
+ * wait (2026-10-30). The CDN then kept that loading-view copy for five minutes.
+ * A miss reads the database, about half a second locally and seconds in
+ * production after an idle gap, so 300 ms still shows the loading view early.
  */
-const LOADING_VIEW_AFTER_MS = 150;
+const LOADING_VIEW_AFTER_MS = 300;
 
 type SearchParams = Record<string, string | string[] | undefined>;
 type LandingData = [SearchParams, Group[], FilterUniverse];