cursedbelt 5.20.0 → 5.22.0

package/scripts/guardrails-baseline.json

@@ -15,7 +15,8 @@
     "micro-typography-floor": 0,
     "no-fast-tooltip": 0,
     "no-raw-lazy": 0,
-    "no-raw-popover": 0
+    "no-raw-popover": 0,
+    "no-hand-rolled-scroll-memory": 0
   },
   "cursedshell": {
     "no-raw-action-button": 0,

package/scripts/guardrailsEnforce.spec.ts

@@ -1417,6 +1417,36 @@ describe('no-raw-nav', () => {
   });
 });
 
+describe('no-hand-rolled-scroll-memory', () => {
+  test('🔴 flags taking restoration off the browser — the first line of flix\'s hand-rolled copy', () => {
+    expect(
+      check('no-hand-rolled-scroll-memory', `if ("scrollRestoration" in window.history) window.history.scrollRestoration = "manual";`),
+    ).toHaveLength(1);
+    expect(check('no-hand-rolled-scroll-memory', `history.scrollRestoration='manual'`)).toHaveLength(1);
+  });
+
+  test('passes reading it, comparing it, prose, and the belt\'s own hook', () => {
+    expect(check('no-hand-rolled-scroll-memory', `const was = history.scrollRestoration;`)).toHaveLength(0);
+    expect(check('no-hand-rolled-scroll-memory', `if (history.scrollRestoration === "auto") log();`)).toHaveLength(0);
+    expect(check('no-hand-rolled-scroll-memory', `// history.scrollRestoration = "manual" fights the hook`)).toHaveLength(0);
+    expect(
+      RULES['no-hand-rolled-scroll-memory']?.check(
+        'src/react/hooks/useScrollMemory.ts',
+        `window.history.scrollRestoration = 'manual';`,
+      ),
+    ).toHaveLength(0);
+  });
+
+  test('passes one with a stated reason in the block above', () => {
+    expect(
+      check(
+        'no-hand-rolled-scroll-memory',
+        `// guardrails-ignore no-hand-rolled-scroll-memory: a canvas app with no page to scroll\nhistory.scrollRestoration = "manual";`,
+      ),
+    ).toHaveLength(0);
+  });
+});
+
 describe('no-raw-lazy', () => {
   test('🔴 flags React.lazy — the Player chunk flix 404ed on from a pre-deploy tab', () => {
     expect(

package/scripts/guardrailsEnforce.ts

@@ -122,6 +122,9 @@
 //   no-raw-popover — owner, 2026-09-27: no hand-rolled `{open && <div className="absolute …">}`
 //     popup; they never close when you tap away. Use `Popover` (`unstyled` for your own look)
 //     or `DropdownMenu`. See the rule's own block below.
+
+//   no-hand-rolled-scroll-memory — 2026-09-28, flix: Back landed at the top of a long grid. An
+//     app setting `history.scrollRestoration` is hand-rolling what `useScrollMemory` does.
 //
 //   no-fast-tooltip — owner, 2026-09-08: a hover-only hint must REST before it opens.
 //     Flags a hover delay written as a numeric literal below 500ms (`delayDuration={120}`,
@@ -1922,6 +1925,41 @@ const noRawLazy: Rule = {
 	},
 };
 
+// ── no-hand-rolled-scroll-memory ────────────────────────────────────────────
+// 2026-09-28, a household viewer on flix, from a phone: Back from a film landed at the top of a
+// grid they had scrolled 30,000px down — *"my thumb is exhausted and I've just looked at 2 movies
+// starting with 'a'"*. flix fixed it by hand that morning, and the same bug was in roms, family and
+// music, each of which would have grown its own copy. `useScrollMemory` (cursedbelt/react) is the
+// one copy: per history entry, any router, the window or a ScrollArea.
+//
+// The signal is exact: the first line of any hand-rolled scroll memory takes restoration off the
+// browser — `history.scrollRestoration = "manual"` — because the browser's own restore fights
+// it. The belt's `hooks/useScrollMemory.ts` is that line's one legitimate home, and specs are exempt.
+const SCROLL_RESTORATION_RE = /\bscrollRestoration\s*=(?!=)/g;
+const SCROLL_MEMORY_IGNORE_RE = /guardrails-ignore\s+no-hand-rolled-scroll-memory\s*:/;
+
+const noHandRolledScrollMemory: Rule = {
+	name: "no-hand-rolled-scroll-memory",
+	description:
+		"Setting `history.scrollRestoration` is the first line of a hand-rolled scroll memory. Use `useScrollMemory` from `cursedbelt/react`: it keeps each history entry's offset for the window or a ScrollArea, waits for a list to grow back, and yields to the viewer's own scrolling.",
+	check(filePath, source) {
+		const normalized = filePath.replace(/\\/g, "/");
+		if (/(^|\/)src\/react\/hooks\/useScrollMemory\.ts$/.test(normalized)) return [];
+		if (isTestSource(normalized)) return [];
+		const scan = blankNonMarkupText(source).split("\n");
+		const raws = source.split("\n");
+		const out: Violation[] = [];
+		for (const [i, line] of scan.entries()) {
+			SCROLL_RESTORATION_RE.lastIndex = 0;
+			if (!SCROLL_RESTORATION_RE.test(line)) continue;
+			const raw = raws[i] ?? "";
+			if (SCROLL_MEMORY_IGNORE_RE.test(raw) || SCROLL_MEMORY_IGNORE_RE.test(blockAbove(raws, i + 1))) continue;
+			out.push({ file: filePath, line: i + 1, snippet: raw.trim().slice(0, 160) });
+		}
+		return out;
+	},
+};
+
 // ── no-raw-popover ──────────────────────────────────────────────────────────
 // Owner report, 2026-09-27, on an iPhone: "many popup menu places don't shut when you
 // click off of them". flix's subtitle menu, music's folder menu — each a hand-rolled
@@ -2126,6 +2164,7 @@ export const RULES: Record<string, Rule> = {
 	[noRawNav.name]: noRawNav,
 	[noRawLazy.name]: noRawLazy,
 	[noRawPopover.name]: noRawPopover,
+	[noHandRolledScrollMemory.name]: noHandRolledScrollMemory,
 };
 
 /**

package/src/react/hooks/useScrollMemory.spec.tsx

@@ -0,0 +1,227 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { act, cleanup, fireEvent, render } from '@testing-library/react';
+import { StrictMode } from 'react';
+import { useScrollMemory } from './useScrollMemory.js';
+
+afterEach(cleanup);
+
+/**
+ * happy-dom lays nothing out, so the scroller is a fake with the three numbers the hook reads —
+ * which is the right level anyway: the hook's whole job is WHEN to write them.
+ */
+function fakeScroller(height: number, viewport = 800) {
+  const el = document.createElement('div');
+  let top = 0;
+  let scrollHeight = height;
+  Object.defineProperty(el, 'scrollTop', {
+    configurable: true,
+    get: () => top,
+    set: (y: number) => {
+      top = Math.max(0, Math.min(y, scrollHeight - viewport));
+    },
+  });
+  Object.defineProperty(el, 'scrollHeight', { configurable: true, get: () => scrollHeight });
+  Object.defineProperty(el, 'clientHeight', { configurable: true, get: () => viewport });
+  document.body.append(el);
+  return {
+    el,
+    /** The viewer scrolls: the offset moves and the element says so. */
+    scrollTo(y: number) {
+      el.scrollTop = y;
+      fireEvent.scroll(el);
+    },
+    /** The content changes height; like a browser, a shrink clamps the offset (no event yet). */
+    grow(to: number) {
+      scrollHeight = to;
+      top = Math.max(0, Math.min(top, to - viewport));
+    },
+  };
+}
+
+function Shell({ at, el, enabled }: { at: string; el: HTMLElement; enabled?: boolean }) {
+  useScrollMemory(at, { scroller: () => el, enabled });
+  return null;
+}
+
+/** A forward navigation: a new entry, as every app's `navigate` makes one. */
+function push(path: string) {
+  window.history.pushState({}, '', path);
+}
+
+const frames = (n: number) =>
+  act(async () => {
+    for (let i = 0; i < n; i++) await new Promise((r) => requestAnimationFrame(() => r(null)));
+  });
+
+/**
+ * Back, as the hook sees it: the entry that was current before comes back WITH ITS STATE.
+ * happy-dom's `history.back()` does not restore `state`, so the state is put back by hand.
+ */
+function back(to: { state: unknown; path: string }) {
+  window.history.replaceState(to.state, '', to.path);
+}
+
+beforeEach(() => {
+  window.history.replaceState(null, '', '/');
+  window.sessionStorage.clear();
+});
+
+describe('useScrollMemory', () => {
+  test('Back returns to the offset the list was left at; the detail opened at the top', () => {
+    const s = fakeScroller(20_000);
+    const { rerender } = render(<Shell at='/' el={s.el} />);
+    s.scrollTo(9_000);
+    const list = { state: window.history.state, path: '/' };
+
+    push('/item/7');
+    rerender(<Shell at='/item/7' el={s.el} />);
+    expect(s.el.scrollTop).toBe(0); // a fresh arrival — not 9,000px down the item's page
+
+    back(list);
+    rerender(<Shell at='/' el={s.el} />);
+    expect(s.el.scrollTop).toBe(9_000);
+  });
+
+  test('a list that is still growing is waited for, and lands once it can hold the offset', async () => {
+    const s = fakeScroller(20_000);
+    const { rerender } = render(<Shell at='/' el={s.el} />);
+    s.scrollTo(15_000);
+    const list = { state: window.history.state, path: '/' };
+    push('/item/7');
+    rerender(<Shell at='/item/7' el={s.el} />);
+
+    s.grow(3_000); // only the first page is back yet
+    back(list);
+    rerender(<Shell at='/' el={s.el} />);
+    expect(s.el.scrollTop).toBe(2_200); // as far as it goes — which asks the list for more
+    await frames(2);
+    s.grow(20_000);
+    await frames(2);
+    expect(s.el.scrollTop).toBe(15_000);
+  });
+
+  test('the viewer taking the page back cancels a restore that is still waiting', async () => {
+    const s = fakeScroller(20_000);
+    const { rerender } = render(<Shell at='/' el={s.el} />);
+    s.scrollTo(15_000);
+    const list = { state: window.history.state, path: '/' };
+    push('/item/7');
+    rerender(<Shell at='/item/7' el={s.el} />);
+
+    s.grow(3_000);
+    back(list);
+    rerender(<Shell at='/' el={s.el} />);
+    fireEvent.touchStart(window);
+    s.scrollTo(500);
+    s.grow(20_000);
+    await frames(3);
+    expect(s.el.scrollTop).toBe(500);
+  });
+
+  test('leaving mid-restore files the TARGET, not the shallow offset it had reached', async () => {
+    const s = fakeScroller(20_000);
+    const { rerender } = render(<Shell at='/' el={s.el} />);
+    s.scrollTo(15_000);
+    const list = { state: window.history.state, path: '/' };
+    push('/item/7');
+    rerender(<Shell at='/item/7' el={s.el} />);
+    const item = { state: window.history.state, path: '/item/7' };
+
+    s.grow(3_000);
+    back(list);
+    rerender(<Shell at='/' el={s.el} />); // restore pending at 2,200
+    window.history.replaceState(item.state, '', item.path); // Forward, before it landed
+    rerender(<Shell at='/item/7' el={s.el} />);
+
+    s.grow(20_000);
+    back(list);
+    rerender(<Shell at='/' el={s.el} />);
+    expect(s.el.scrollTop).toBe(15_000);
+  });
+
+  test('a URL replaced in place (a filter) is the same entry, and its scroll is left alone', async () => {
+    const s = fakeScroller(20_000);
+    const { rerender } = render(<Shell at='/' el={s.el} />);
+    s.scrollTo(4_000);
+    // The filter narrows the list and the browser clamps the offset; the new results then
+    // stream in. Treated as an arrival, the old 4,000 would be "restored" into a different list.
+    s.grow(1_500);
+    window.history.replaceState(window.history.state, '', '/?genre=drama');
+    rerender(<Shell at='/?genre=drama' el={s.el} />);
+    s.grow(20_000);
+    await frames(3);
+    expect(s.el.scrollTop).toBe(700);
+  });
+
+  test('two trips into the same list keep two positions — memory is per entry, not per URL', () => {
+    const s = fakeScroller(20_000);
+    const { rerender } = render(<Shell at='/' el={s.el} />);
+    s.scrollTo(1_000);
+    const first = { state: window.history.state, path: '/' };
+    push('/'); // the same list, arrived at again
+    rerender(<Shell at='/?again' el={s.el} />);
+    expect(s.el.scrollTop).toBe(0);
+    s.scrollTo(6_000);
+    const second = { state: window.history.state, path: '/' };
+
+    back(first);
+    rerender(<Shell at='/' el={s.el} />);
+    expect(s.el.scrollTop).toBe(1_000);
+    back(second);
+    rerender(<Shell at='/?again' el={s.el} />);
+    expect(s.el.scrollTop).toBe(6_000);
+  });
+
+  test('enabled: false leaves the offset beneath a full-screen surface alone', () => {
+    const s = fakeScroller(20_000);
+    const { rerender } = render(<Shell at='/film/1' el={s.el} />);
+    s.scrollTo(700);
+    const film = { state: window.history.state, path: '/film/1' };
+    push('/watch/1');
+    rerender(<Shell at='/watch/1' el={s.el} enabled={false} />);
+    expect(s.el.scrollTop).toBe(700);
+    back(film);
+    rerender(<Shell at='/film/1' el={s.el} />);
+    expect(s.el.scrollTop).toBe(700);
+  });
+
+  test("the app's own history.state keys survive the entry id being minted into it", () => {
+    window.history.replaceState({ appDepth: 3 }, '');
+    const s = fakeScroller(2_000);
+    render(<Shell at='/' el={s.el} />);
+    expect((window.history.state as { appDepth: number }).appDepth).toBe(3);
+  });
+
+  test('a reload comes back scrolled: the offset is in sessionStorage by pagehide', () => {
+    const s = fakeScroller(20_000);
+    render(<Shell at='/' el={s.el} />);
+    s.scrollTo(3_300);
+    window.dispatchEvent(new Event('pagehide'));
+    const stored = JSON.parse(window.sessionStorage.getItem('cursedbelt:scroll-memory') ?? '{}');
+    const id = (window.history.state as { cbScrollEntry: string }).cbScrollEntry;
+    expect(stored[id]).toBe(3_300);
+  });
+
+  test("StrictMode's rehearsal unmount does not file a deep entry as the top", () => {
+    const s = fakeScroller(20_000);
+    const { rerender, unmount } = render(<Shell at='/' el={s.el} />);
+    s.scrollTo(12_000);
+    const list = { state: window.history.state, path: '/' };
+    push('/item/7');
+    rerender(<Shell at='/item/7' el={s.el} />);
+    unmount();
+
+    s.grow(3_000);
+    back(list);
+    render(
+      <StrictMode>
+        <Shell at='/' el={s.el} />
+      </StrictMode>,
+    );
+    s.grow(20_000);
+    back(list);
+    cleanup();
+    render(<Shell at='/' el={s.el} />);
+    expect(s.el.scrollTop).toBe(12_000);
+  });
+});

package/src/react/hooks/useScrollMemory.ts

@@ -0,0 +1,245 @@
+import { type RefObject, useLayoutEffect, useRef } from 'react';
+
+/**
+ * Back returns you to where you were on the page, not to the top of it.
+ *
+ * 🔴 **Why this exists.** A household viewer on flix, 2026-09-28, from a phone: *"when I click
+ * on one to read the synopsis when I page back it was … back at the top again. my thumb is
+ * exhausted and I've just looked at 2 movies starting with 'a'"*. Every app here swaps screens
+ * in place under ONE scroller — the window, or a `ScrollArea` — so the browser's own
+ * restoration has nothing to restore into: the list it would scroll is not there yet when it
+ * tries, the page is one screen tall, and the offset clamps to zero. flix fixed it by hand
+ * (`scrollMemory.ts`, recording at its `navigate`); this is that fix for every app, and it
+ * needs no seam in the app's router at all.
+ *
+ * **How.** Each history entry gets an id in `history.state` the first time a screen arrives on
+ * it. While the entry is current, the scroller's offset is tracked; when the entry is left (the
+ * `location` changes) or the page is hidden (a reload, a tab put away), the offset is filed
+ * under that id — in memory and in `sessionStorage`, so a reload comes back scrolled. Arriving
+ * on an entry that has an offset puts it back once the page is tall enough to hold it; arriving
+ * on one that has none (a fresh push) starts at the top — without that, an item opened from
+ * deep in a list opens partway down its own page.
+ *
+ * - **Per ENTRY, not per URL**: two trips into the same list keep two positions, and a forward
+ *   move to a place you have been before starts at its top.
+ * - **The list may still be growing.** A virtualized grid sizes itself a frame or two late and
+ *   a paged one may hold only its first page, so the restore retries each frame, scrolling as
+ *   far as the page allows meanwhile — which is what asks an infinite list for its next page —
+ *   until {@link ScrollMemoryOptions.deadlineMs}. Keep the list's pages across the trip
+ *   (`usePagedList` does, through the query cache) and it lands in the first frame.
+ * - **The viewer always wins**: a touch, wheel, key or pointer press while it waits cancels it.
+ * - **A replaced URL is the same place**: when the location changes but the history entry does
+ *   not (a filter written with `replaceState`), the scroll is left alone.
+ *
+ * Mount it ONCE per scroller, above the screens that swap — the app shell, keyed on the route.
+ */
+export function useScrollMemory(location: string, options: ScrollMemoryOptions = {}): void {
+  const { enabled = true, deadlineMs = RESTORE_DEADLINE_MS } = options;
+  // The scroller is read through a ref so an inline `() => el` does not re-run the effect
+  // every render — which would file and restore on every keystroke.
+  const scrollerRef = useRef(options.scroller);
+  scrollerRef.current = options.scroller;
+  const last = useRef<{ id: string; location: string } | null>(null);
+
+  useLayoutEffect(() => {
+    if (!enabled) return;
+    const scroller = resolveScroller(scrollerRef.current ?? 'window');
+    if (!scroller) return;
+    if (scroller.isWindow && 'scrollRestoration' in window.history) {
+      // Left on `auto`, the browser restores at `popstate` — into the screen being LEFT, before
+      // React has swapped it — and the restore below would have to fight it.
+      window.history.scrollRestoration = 'manual';
+    }
+    const id = entryId();
+    if (!id) return;
+
+    // Same entry, different location: the URL was replaced in place. It is the same place.
+    const replacedInPlace = last.current?.id === id && last.current.location !== location;
+    last.current = { id, location };
+
+    // What gets filed when this entry is left. While a restore is pending it is the TARGET, not
+    // the partial offset on screen — leaving mid-restore (or StrictMode's rehearsal unmount) must
+    // not overwrite a deep position with a shallow one.
+    let offset = scroller.get();
+    let cancelRestore: (() => void) | null = null;
+
+    if (!replacedInPlace) {
+      const target = recalled(id);
+      if (target > 0) {
+        offset = target;
+        cancelRestore = restore(scroller, target, deadlineMs, (outcome) => {
+          cancelRestore = null;
+          if (outcome !== 'reached') offset = scroller.get();
+        });
+      } else {
+        scroller.set(0);
+        offset = 0;
+      }
+    }
+
+    const onScroll = () => {
+      if (!cancelRestore) offset = scroller.get();
+    };
+    const onHide = () => file(id, offset);
+    scroller.events.addEventListener('scroll', onScroll, { passive: true });
+    window.addEventListener('pagehide', onHide);
+    return () => {
+      const pending = cancelRestore;
+      cancelRestore = null;
+      pending?.();
+      scroller.events.removeEventListener('scroll', onScroll);
+      window.removeEventListener('pagehide', onHide);
+      file(id, offset);
+    };
+  }, [location, enabled, deadlineMs]);
+}
+
+/** What scrolls: the window, or an element — by ref or by a getter read when the screen arrives. */
+export type ScrollMemoryScroller = 'window' | RefObject<HTMLElement | null> | (() => HTMLElement | null);
+
+export interface ScrollMemoryOptions {
+  /** The one scroller the screens swap under. Default `'window'`. */
+  scroller?: ScrollMemoryScroller;
+  /**
+   * `false` leaves this location's scroll entirely alone — no restore, no reset to the top, and
+   * nothing filed. For a fixed full-screen surface (a player) over a page whose offset must
+   * survive underneath it. Default `true`.
+   */
+  enabled?: boolean;
+  /**
+   * How long a restore waits for the page to grow tall enough before settling as close as it
+   * got. Default 3000ms — a reload, where only the first page of a list exists, needs a few
+   * pages' round trips.
+   */
+  deadlineMs?: number;
+}
+
+const RESTORE_DEADLINE_MS = 3_000;
+const ENTRY_KEY = 'cbScrollEntry';
+const STORE_KEY = 'cursedbelt:scroll-memory';
+/** Entries kept in `sessionStorage` — a tab's history, not a cache; the oldest go first. */
+const KEEP = 100;
+
+/** What counts as the viewer taking the page back. `scroll` is NOT one — the restore causes those. */
+const INPUT_EVENTS = ['wheel', 'touchstart', 'keydown', 'pointerdown'] as const;
+
+interface Scroller {
+  isWindow: boolean;
+  events: EventTarget;
+  get(): number;
+  set(y: number): void;
+  /** How far it can scroll right now. */
+  room(): number;
+}
+
+function resolveScroller(spec: ScrollMemoryScroller): Scroller | null {
+  if (spec === 'window') {
+    return {
+      isWindow: true,
+      events: window,
+      get: () => Math.round(window.scrollY),
+      set: (y) => window.scrollTo(0, y),
+      room: () => document.documentElement.scrollHeight - window.innerHeight,
+    };
+  }
+  const el = typeof spec === 'function' ? spec() : spec.current;
+  if (!el) return null;
+  return {
+    isWindow: false,
+    events: el,
+    get: () => Math.round(el.scrollTop),
+    set: (y) => {
+      el.scrollTop = y;
+    },
+    room: () => el.scrollHeight - el.clientHeight,
+  };
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null;
+
+/** This entry's id, minted into `history.state` (merged, never replacing an app's own keys). */
+function entryId(): string | null {
+  const state: unknown = window.history.state;
+  if (state !== null && state !== undefined && !isRecord(state)) return null; // not ours to reshape
+  const existing = state?.[ENTRY_KEY];
+  if (typeof existing === 'string') return existing;
+  const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  window.history.replaceState({ ...(state ?? {}), [ENTRY_KEY]: id }, '');
+  return id;
+}
+
+const memory = new Map<string, number>();
+
+function stored(): Record<string, number> {
+  try {
+    const parsed: unknown = JSON.parse(window.sessionStorage.getItem(STORE_KEY) ?? '{}');
+    return isRecord(parsed) ? (parsed as Record<string, number>) : {};
+  } catch {
+    return {};
+  }
+}
+
+function recalled(id: string): number {
+  const y = memory.get(id) ?? stored()[id];
+  return typeof y === 'number' && y > 0 ? y : 0;
+}
+
+function file(id: string, y: number): void {
+  memory.set(id, y);
+  try {
+    const all = stored();
+    delete all[id]; // re-inserted last, so insertion order is recency
+    all[id] = y;
+    const ids = Object.keys(all);
+    for (const old of ids.slice(0, Math.max(0, ids.length - KEEP))) delete all[old];
+    window.sessionStorage.setItem(STORE_KEY, JSON.stringify(all));
+  } catch {
+    // Private mode, quota, blocked storage: memory still covers Back within this page load.
+  }
+}
+
+type RestoreOutcome = 'reached' | 'input' | 'deadline';
+
+/** Scroll to `target` once there is room for it; returns a cancel that reports nothing. */
+function restore(
+  scroller: Scroller,
+  target: number,
+  deadlineMs: number,
+  settled: (outcome: RestoreOutcome) => void,
+): () => void {
+  const deadline = performance.now() + deadlineMs;
+  let frame = 0;
+  let done = false;
+
+  const stop = () => {
+    if (done) return false;
+    done = true;
+    cancelAnimationFrame(frame);
+    for (const type of INPUT_EVENTS) window.removeEventListener(type, onInput);
+    return true;
+  };
+  const onInput = () => {
+    if (stop()) settled('input');
+  };
+
+  const attempt = () => {
+    if (done) return;
+    const room = scroller.room();
+    if (room >= target) {
+      scroller.set(target);
+      if (stop()) settled('reached');
+      return;
+    }
+    // Short of it: go as far as the page allows — that is what asks an infinite list for more.
+    scroller.set(Math.max(0, room));
+    if (performance.now() >= deadline) {
+      if (stop()) settled('deadline');
+    } else frame = requestAnimationFrame(attempt);
+  };
+
+  for (const type of INPUT_EVENTS) window.addEventListener(type, onInput, { passive: true });
+  attempt();
+  return () => {
+    stop();
+  };
+}

package/src/react/index.ts

@@ -100,6 +100,11 @@ export {
   scrollFadeMask,
   useScrollEdges,
 } from './hooks/useScrollEdges.js';
+export {
+  type ScrollMemoryOptions,
+  type ScrollMemoryScroller,
+  useScrollMemory,
+} from './hooks/useScrollMemory.js';
 export {
   AmbientBackdrop,
   type AmbientBackdropProps,

package/src/react/usePagedList.spec.tsx

@@ -54,4 +54,82 @@ describe('usePagedList', () => {
     expect(result.current.items).toEqual([]);
     expect(calls).toBe(0);
   });
+
+  test('total is the newest page\'s count, and undefined before any page', async () => {
+    const fetchPage = pagedFetcher({
+      '@first': { items: ['a'], nextCursor: 'c1', total: 3 },
+      c1: { items: ['b', 'c'], total: 2 },
+    });
+    const { result } = renderHook(() => usePagedList({ queryKey: ['total'], fetchPage }), {
+      wrapper: makeWrapper(),
+    });
+    expect(result.current.total).toBeUndefined();
+    await waitFor(() => expect(result.current.total).toBe(3));
+    act(() => result.current.loadMore());
+    await waitFor(() => expect(result.current.total).toBe(2));
+  });
+
+  test('coming back to a list holds every page in its FIRST render, and fetches nothing', async () => {
+    let fetches = 0;
+    const pages = pagedFetcher({
+      '@first': { items: ['a', 'b'], nextCursor: 'c1' },
+      c1: { items: ['c', 'd'] },
+    });
+    const fetchPage = (cursor: string | undefined) => {
+      fetches++;
+      return pages(cursor);
+    };
+    const wrapper = makeWrapper();
+    const opts = { queryKey: ['back'], fetchPage, staleTime: 60_000 };
+    const first = renderHook(() => usePagedList(opts), { wrapper });
+    await waitFor(() => expect(first.result.current.items).toHaveLength(2));
+    act(() => first.result.current.loadMore());
+    await waitFor(() => expect(first.result.current.items).toHaveLength(4));
+    first.unmount();
+
+    const seen: number[] = [];
+    renderHook(
+      () => {
+        const list = usePagedList(opts);
+        seen.push(list.items.length);
+        return list;
+      },
+      { wrapper },
+    );
+    expect(seen[0]).toBe(4);
+    expect(fetches).toBe(2);
+  });
+
+  test('items is the same array across renders until a page changes', async () => {
+    const fetchPage = pagedFetcher({ '@first': { items: ['a', 'b'] } });
+    const { result, rerender } = renderHook(() => usePagedList({ queryKey: ['stable'], fetchPage }), {
+      wrapper: makeWrapper(),
+    });
+    await waitFor(() => expect(result.current.items).toHaveLength(2));
+    const before = result.current.items;
+    rerender();
+    expect(result.current.items).toBe(before);
+  });
+
+  test('keepPreviousItems holds the old list on screen while a new query loads', async () => {
+    let release: () => void = () => {};
+    const fetchPage = (key: string) => (cursor: string | undefined) =>
+      key === 'b'
+        ? new Promise<PagedPage<string>>((r) => {
+            release = () => r({ items: ['b1'] });
+          })
+        : pagedFetcher({ '@first': { items: ['a1', 'a2'] } })(cursor);
+    const { result, rerender } = renderHook(
+      ({ q }: { q: string }) =>
+        usePagedList({ queryKey: ['keep', q], fetchPage: fetchPage(q), keepPreviousItems: true }),
+      { wrapper: makeWrapper(), initialProps: { q: 'a' } },
+    );
+    await waitFor(() => expect(result.current.items).toEqual(['a1', 'a2']));
+    rerender({ q: 'b' });
+    await waitFor(() => expect(result.current.isFetching).toBe(true));
+    expect(result.current.items).toEqual(['a1', 'a2']);
+    expect(result.current.isLoading).toBe(false);
+    act(() => release());
+    await waitFor(() => expect(result.current.items).toEqual(['b1']));
+  });
 });