@charcuterie/ui 3.29.1 → 3.30.0

package/dist/Main/Main.d.ts

@@ -2,6 +2,16 @@ import { type ComponentPropsWithRef, type ReactNode } from "react";
 import { type ContentWidth } from "../Shell/contentWidth.ts";
 export type MainProps = ComponentPropsWithRef<"main"> & {
     contentWidth?: ContentWidth;
+    /**
+     * The history entry this page belongs to — react-router's
+     * `useLocation().key`, and the same value under a different
+     * router. Given it, `<main>` remembers where each entry was
+     * scrolled to and puts the offset back on Back and Forward.
+     *
+     * Omit it and nothing is remembered, which is the right default
+     * for a page with no history to remember.
+     */
+    scrollKey?: string;
 };
 /**
  * The `<main>` landmark and the content column.
@@ -80,6 +90,30 @@ export type MainProps = ComponentPropsWithRef<"main"> & {
  *    an app's own fixed chrome belongs in `Shell`, beside `Main`
  *    rather than in it.
  *
+ * ## It remembers where each history entry was scrolled to
+ *
+ * `Shell` gives this element the page's only vertical scrollport,
+ * so the header and the rails stay put while the content moves.
+ * The browser's own scroll restoration does not follow it there: a
+ * browser remembers **the document scroller's** offset per history
+ * entry, and `<main>` is not the document scroller. It also does
+ * not restore anything at all across a same-document `pushState`
+ * navigation, which is every link press in a single-page app. Back
+ * therefore lands at the top of a list the reader had scrolled
+ * half-way down, and no browser setting changes that.
+ *
+ * Pass `scrollKey` — react-router's `useLocation().key` — and the
+ * offset comes back. `useScrollMemory.ts` holds the mechanism and
+ * `scrollMemory.ts` the reasoning.
+ *
+ * ```tsx
+ * const location = useLocation()
+ *
+ * <Main scrollKey={location.key}>
+ *   <Outlet />
+ * </Main>
+ * ```
+ *
  * ## Two more things it does, both one line
  *
  * `tabIndex={-1}` so `Shell`'s skip link moves **focus** and not
@@ -109,5 +143,5 @@ export type MainProps = ComponentPropsWithRef<"main"> & {
  * wrap, so a wide one goes in an `overflow-x-auto` wrapper, which
  * `Main.mdx` shows.
  */
-export declare const Main: ({ children, className, contentWidth, id, ...mainProps }: MainProps) => ReactNode;
+export declare const Main: ({ children, className, contentWidth, id, ref, scrollKey, ...mainProps }: MainProps) => ReactNode;
 //# sourceMappingURL=Main.d.ts.map

package/dist/Main/Main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Main.d.ts","sourceRoot":"","sources":["../../src/Main/Main.tsx"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EAEf,MAAM,OAAO,CAAA;AAEd,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,0BAA0B,CAAA;AAIjC,MAAM,MAAM,SAAS,GAAG,qBAAqB,CAAC,MAAM,CAAC,GAAG;IACtD,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AACH,eAAO,MAAM,IAAI,GAAI,yDAMlB,SAAS,KAAG,SA0Cd,CAAA"}
+{"version":3,"file":"Main.d.ts","sourceRoot":"","sources":["../../src/Main/Main.tsx"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EAGf,MAAM,OAAO,CAAA;AAEd,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,0BAA0B,CAAA;AAKjC,MAAM,MAAM,SAAS,GAAG,qBAAqB,CAAC,MAAM,CAAC,GAAG;IACtD,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiIG;AACH,eAAO,MAAM,IAAI,GAAI,yEAQlB,SAAS,KAAG,SAyDd,CAAA"}

package/dist/Main/Main.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useUniqueId } from "@charcuterie/logic";
+import { mergeRefs, useUniqueId, } from "@charcuterie/logic";
 import { useContext, } from "react";
 import { DEFAULT_CONTENT_WIDTH, toMaxInlineSize, } from "../Shell/contentWidth.js";
 import { ShellContext } from "../Shell/shellContext.js";
 import { toClassName } from "../toClassName.js";
+import { useScrollMemory } from "./useScrollMemory.js";
 /**
  * The `<main>` landmark and the content column.
  *
@@ -81,6 +82,30 @@ import { toClassName } from "../toClassName.js";
  *    an app's own fixed chrome belongs in `Shell`, beside `Main`
  *    rather than in it.
  *
+ * ## It remembers where each history entry was scrolled to
+ *
+ * `Shell` gives this element the page's only vertical scrollport,
+ * so the header and the rails stay put while the content moves.
+ * The browser's own scroll restoration does not follow it there: a
+ * browser remembers **the document scroller's** offset per history
+ * entry, and `<main>` is not the document scroller. It also does
+ * not restore anything at all across a same-document `pushState`
+ * navigation, which is every link press in a single-page app. Back
+ * therefore lands at the top of a list the reader had scrolled
+ * half-way down, and no browser setting changes that.
+ *
+ * Pass `scrollKey` — react-router's `useLocation().key` — and the
+ * offset comes back. `useScrollMemory.ts` holds the mechanism and
+ * `scrollMemory.ts` the reasoning.
+ *
+ * ```tsx
+ * const location = useLocation()
+ *
+ * <Main scrollKey={location.key}>
+ *   <Outlet />
+ * </Main>
+ * ```
+ *
  * ## Two more things it does, both one line
  *
  * `tabIndex={-1}` so `Shell`'s skip link moves **focus** and not
@@ -110,14 +135,24 @@ import { toClassName } from "../toClassName.js";
  * wrap, so a wide one goes in an `overflow-x-auto` wrapper, which
  * `Main.mdx` shows.
  */
-export const Main = ({ children, className, contentWidth, id, ...mainProps }) => {
+export const Main = ({ children, className, contentWidth, id, ref, scrollKey, ...mainProps }) => {
     const shell = useContext(ShellContext);
+    const setScrollport = useScrollMemory(scrollKey);
     // Always called, never conditionally: a `Main` outside a `Shell`
     // still needs an id an app can point its own skip link at.
     const fallbackId = useUniqueId();
     const maxInlineSize = toMaxInlineSize(contentWidth ??
         shell?.contentWidth ??
         DEFAULT_CONTENT_WIDTH);
-    return (_jsx("main", { ...mainProps, className: toClassName("charcuterie-scrollbar col-start-1 row-start-3 min-h-0 min-w-0 overflow-y-auto md:col-start-2 md:row-start-2", className), id: id ?? shell?.mainId ?? fallbackId, tabIndex: -1, children: _jsx("div", { className: "@container mx-auto flex w-full min-w-0 flex-col gap-6 wrap-anywhere px-4 py-6 sm:px-6", style: { maxInlineSize }, children: children }) }));
+    return (_jsx("main", { ...mainProps, className: toClassName("charcuterie-scrollbar col-start-1 row-start-3 min-h-0 min-w-0 overflow-y-auto md:col-start-2 md:row-start-2", className), id: id ?? shell?.mainId ?? fallbackId, 
+        // A caller's `ref` is a subscription, not a value, so the
+        // scroll memory composes with it rather than replacing it.
+        //
+        // The cast is `mergeRefs`' prop-merging signature, where
+        // every value is `unknown`; a caller's `ref` is narrower than
+        // that, never wider.
+        ref: ref
+            ? mergeRefs(ref, setScrollport)
+            : setScrollport, tabIndex: -1, children: _jsx("div", { className: "@container mx-auto flex w-full min-w-0 flex-col gap-6 wrap-anywhere px-4 py-6 sm:px-6", style: { maxInlineSize }, children: children }) }));
 };
 //# sourceMappingURL=Main.js.map

package/dist/Main/Main.js.map

@@ -1 +1 @@
-{"version":3,"file":"Main.js","sourceRoot":"","sources":["../../src/Main/Main.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAGL,UAAU,GACX,MAAM,OAAO,CAAA;AAEd,OAAO,EAEL,qBAAqB,EACrB,eAAe,GAChB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAM/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,EACnB,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,EAAE,EACF,GAAG,SAAS,EACF,EAAa,EAAE;IACzB,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAA;IAEtC,iEAAiE;IACjE,2DAA2D;IAC3D,MAAM,UAAU,GAAG,WAAW,EAAE,CAAA;IAEhC,MAAM,aAAa,GAAG,eAAe,CACnC,YAAY;QACV,KAAK,EAAE,YAAY;QACnB,qBAAqB,CACxB,CAAA;IAED,OAAO,CACL,kBACM,SAAS,EACb,SAAS,EAAE,WAAW,CACpB,6GAA6G,EAC7G,SAAS,CACV,EACD,EAAE,EAAE,EAAE,IAAI,KAAK,EAAE,MAAM,IAAI,UAAU,EACrC,QAAQ,EAAE,CAAC,CAAC,YAaZ,cACE,SAAS,EAAC,uFAAuF,EACjG,KAAK,EAAE,EAAE,aAAa,EAAE,YAEvB,QAAQ,GACL,GACD,CACR,CAAA;AACH,CAAC,CAAA"}
+{"version":3,"file":"Main.js","sourceRoot":"","sources":["../../src/Main/Main.tsx"],"names":[],"mappings":";AAAA,OAAO,EAEL,SAAS,EACT,WAAW,GACZ,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAIL,UAAU,GACX,MAAM,OAAO,CAAA;AAEd,OAAO,EAEL,qBAAqB,EACrB,eAAe,GAChB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAgBtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiIG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,EACnB,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,EAAE,EACF,GAAG,EACH,SAAS,EACT,GAAG,SAAS,EACF,EAAa,EAAE;IACzB,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAA;IACtC,MAAM,aAAa,GAAG,eAAe,CAAC,SAAS,CAAC,CAAA;IAEhD,iEAAiE;IACjE,2DAA2D;IAC3D,MAAM,UAAU,GAAG,WAAW,EAAE,CAAA;IAEhC,MAAM,aAAa,GAAG,eAAe,CACnC,YAAY;QACV,KAAK,EAAE,YAAY;QACnB,qBAAqB,CACxB,CAAA;IAED,OAAO,CACL,kBACM,SAAS,EACb,SAAS,EAAE,WAAW,CACpB,6GAA6G,EAC7G,SAAS,CACV,EACD,EAAE,EAAE,EAAE,IAAI,KAAK,EAAE,MAAM,IAAI,UAAU;QACrC,0DAA0D;QAC1D,2DAA2D;QAC3D,EAAE;QACF,yDAAyD;QACzD,8DAA8D;QAC9D,qBAAqB;QACrB,GAAG,EACD,GAAG;YACD,CAAC,CAAE,SAAS,CACR,GAAmB,EACnB,aAAa,CACe;YAChC,CAAC,CAAC,aAAa,EAEnB,QAAQ,EAAE,CAAC,CAAC,YAaZ,cACE,SAAS,EAAC,uFAAuF,EACjG,KAAK,EAAE,EAAE,aAAa,EAAE,YAEvB,QAAQ,GACL,GACD,CACR,CAAA;AACH,CAAC,CAAA"}

package/dist/Main/scrollMemory.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What the browser will not remember for you.
+ *
+ * `Shell` gives `<main>` the page's only vertical scrollport, so
+ * the header and the rails stay put while the content moves —
+ * that is the whole reason `Shell.test.tsx` asserts "only main
+ * scrolls vertically, keeping the rail available".
+ *
+ * It costs exactly one thing, and this module is it. A browser
+ * remembers **the document scroller's** offset per history entry
+ * and puts it back on Back. It does that for a cross-document
+ * load, and `history.scrollRestoration` is the switch for it. It
+ * does **not** do it for an arbitrary element with
+ * `overflow-y: auto`, and it does not do it at all for a
+ * same-document `pushState` navigation, which is every link press
+ * in a single-page app. So a page that scrolls its own `<main>`
+ * loses the reader's place on Back, and no browser setting brings
+ * it back:
+ *
+ * > *"If I scroll, click on an item, then go back, it resets me to
+ * > the top. […] It should remember where the scroll position was
+ * > previously. Isn't this handled by Chrome already?"*
+ *
+ * The offsets are held **in memory**, not in `sessionStorage`. A
+ * history key survives a reload, but the DOM it described does
+ * not: the app re-fetches, re-measures and often re-orders, so a
+ * pixel offset from before the reload points at a different row.
+ * Restoring a stale number is worse than restoring nothing,
+ * because it looks deliberate.
+ */
+export declare const rememberScrollOffset: (key: string, offset: number) => void;
+/**
+ * `0` for an entry nobody has scrolled, which is also the right
+ * answer for an entry nobody has *seen* — a link press lands at
+ * the top of the new page.
+ */
+export declare const recallScrollOffset: (key: string) => number;
+/** Test-only. Module state outlives a mount; a test must not. */
+export declare const forgetScrollOffsets: () => void;
+//# sourceMappingURL=scrollMemory.d.ts.map

package/dist/Main/scrollMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrollMemory.d.ts","sourceRoot":"","sources":["../../src/Main/scrollMemory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAaH,eAAO,MAAM,oBAAoB,GAC/B,KAAK,MAAM,EACX,QAAQ,MAAM,SAef,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,KAAK,MAAM,WACb,CAAA;AAEjC,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,YAE/B,CAAA"}

package/dist/Main/scrollMemory.js

@@ -0,0 +1,63 @@
+/**
+ * What the browser will not remember for you.
+ *
+ * `Shell` gives `<main>` the page's only vertical scrollport, so
+ * the header and the rails stay put while the content moves —
+ * that is the whole reason `Shell.test.tsx` asserts "only main
+ * scrolls vertically, keeping the rail available".
+ *
+ * It costs exactly one thing, and this module is it. A browser
+ * remembers **the document scroller's** offset per history entry
+ * and puts it back on Back. It does that for a cross-document
+ * load, and `history.scrollRestoration` is the switch for it. It
+ * does **not** do it for an arbitrary element with
+ * `overflow-y: auto`, and it does not do it at all for a
+ * same-document `pushState` navigation, which is every link press
+ * in a single-page app. So a page that scrolls its own `<main>`
+ * loses the reader's place on Back, and no browser setting brings
+ * it back:
+ *
+ * > *"If I scroll, click on an item, then go back, it resets me to
+ * > the top. […] It should remember where the scroll position was
+ * > previously. Isn't this handled by Chrome already?"*
+ *
+ * The offsets are held **in memory**, not in `sessionStorage`. A
+ * history key survives a reload, but the DOM it described does
+ * not: the app re-fetches, re-measures and often re-orders, so a
+ * pixel offset from before the reload points at a different row.
+ * Restoring a stale number is worse than restoring nothing,
+ * because it looks deliberate.
+ */
+/**
+ * How many history entries keep an offset. A reader goes back
+ * through a handful of screens, never fifty, so this is a ceiling
+ * against a long session rather than a working set — the map holds
+ * one small number per entry and evicts the least recently
+ * written.
+ */
+const REMEMBERED_ENTRY_LIMIT = 50;
+const rememberedOffsets = new Map();
+export const rememberScrollOffset = (key, offset) => {
+    // Delete before set, so insertion order is least-recent-first
+    // and the eviction below takes the right one. A plain `set` on
+    // an existing key keeps its original position.
+    rememberedOffsets.delete(key);
+    rememberedOffsets.set(key, offset);
+    for (const oldestKey of rememberedOffsets.keys()) {
+        if (rememberedOffsets.size <= REMEMBERED_ENTRY_LIMIT) {
+            break;
+        }
+        rememberedOffsets.delete(oldestKey);
+    }
+};
+/**
+ * `0` for an entry nobody has scrolled, which is also the right
+ * answer for an entry nobody has *seen* — a link press lands at
+ * the top of the new page.
+ */
+export const recallScrollOffset = (key) => rememberedOffsets.get(key) ?? 0;
+/** Test-only. Module state outlives a mount; a test must not. */
+export const forgetScrollOffsets = () => {
+    rememberedOffsets.clear();
+};
+//# sourceMappingURL=scrollMemory.js.map

package/dist/Main/scrollMemory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrollMemory.js","sourceRoot":"","sources":["../../src/Main/scrollMemory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;GAMG;AACH,MAAM,sBAAsB,GAAG,EAAE,CAAA;AAEjC,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAkB,CAAA;AAEnD,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,GAAW,EACX,MAAc,EACd,EAAE;IACF,8DAA8D;IAC9D,+DAA+D;IAC/D,+CAA+C;IAC/C,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC7B,iBAAiB,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IAElC,KAAK,MAAM,SAAS,IAAI,iBAAiB,CAAC,IAAI,EAAE,EAAE,CAAC;QACjD,IAAI,iBAAiB,CAAC,IAAI,IAAI,sBAAsB,EAAE,CAAC;YACrD,MAAK;QACP,CAAC;QAED,iBAAiB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACrC,CAAC;AACH,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAW,EAAE,EAAE,CAChD,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAEjC,iEAAiE;AACjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,EAAE;IACtC,iBAAiB,CAAC,KAAK,EAAE,CAAA;AAC3B,CAAC,CAAA"}

package/dist/Main/useScrollMemory.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Remember where this history entry was scrolled to, and put it
+ * back when the reader returns to it.
+ *
+ * `scrollMemory.ts` says why the browser will not. This is the
+ * part that has to survive the two things a real page does:
+ *
+ *  1. **The content arrives late.** An offset applied against a
+ *     600px skeleton clamps to `0` and looks like it did nothing.
+ *     A `ResizeObserver` on the scrollport and on its content
+ *     column re-applies the offset every time either grows, until
+ *     the offset lands or the window closes.
+ *  2. **The reader scrolls during all that.** Any wheel, touch,
+ *     key or pointer press ends the restore immediately. The
+ *     alternative is a page that jumps out from under somebody who
+ *     has already started reading.
+ *
+ * The save is a passive `scroll` listener, suppressed while a
+ * restore is in flight. Without that suppression the feature eats
+ * itself: writing `scrollTop` on a still-short page clamps to `0`
+ * and fires a `scroll` event reading `0`, which would be saved
+ * over the very offset being restored.
+ *
+ * @param scrollKey Identifies the history entry — react-router's
+ *   `useLocation().key`. `undefined` turns the memory off, which is
+ *   what an app with no router gets.
+ */
+export declare const useScrollMemory: (scrollKey: string | undefined) => (node: unknown) => void;
+//# sourceMappingURL=useScrollMemory.d.ts.map

package/dist/Main/useScrollMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollMemory.d.ts","sourceRoot":"","sources":["../../src/Main/useScrollMemory.ts"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,eAAe,GAC1B,WAAW,MAAM,GAAG,SAAS,YAaS,OAAO,SA6F9C,CAAA"}

package/dist/Main/useScrollMemory.js

@@ -0,0 +1,131 @@
+import { useCallback, useLayoutEffect, useRef } from "react";
+import { recallScrollOffset, rememberScrollOffset, } from "./scrollMemory.js";
+/**
+ * How long a restore keeps trying while the content is still
+ * arriving.
+ *
+ * The offset cannot be applied until the scrollport is tall enough
+ * to hold it, and on a client-rendered page it is not: the commit
+ * that changes the route draws a skeleton, and the rows land a
+ * fetch later. So the restore re-applies as the content grows, and
+ * gives up after this. A page that takes longer than three seconds
+ * to fill has already been read from the top, and moving it then
+ * is a worse answer than leaving it where the reader put it.
+ */
+const RESTORE_WINDOW_MS = 3000;
+/** A scroll the reader asked for. It ends the restore at once. */
+const READER_INTENT_EVENTS = [
+    "keydown",
+    "pointerdown",
+    "touchstart",
+    "wheel",
+];
+/**
+ * Remember where this history entry was scrolled to, and put it
+ * back when the reader returns to it.
+ *
+ * `scrollMemory.ts` says why the browser will not. This is the
+ * part that has to survive the two things a real page does:
+ *
+ *  1. **The content arrives late.** An offset applied against a
+ *     600px skeleton clamps to `0` and looks like it did nothing.
+ *     A `ResizeObserver` on the scrollport and on its content
+ *     column re-applies the offset every time either grows, until
+ *     the offset lands or the window closes.
+ *  2. **The reader scrolls during all that.** Any wheel, touch,
+ *     key or pointer press ends the restore immediately. The
+ *     alternative is a page that jumps out from under somebody who
+ *     has already started reading.
+ *
+ * The save is a passive `scroll` listener, suppressed while a
+ * restore is in flight. Without that suppression the feature eats
+ * itself: writing `scrollTop` on a still-short page clamps to `0`
+ * and fires a `scroll` event reading `0`, which would be saved
+ * over the very offset being restored.
+ *
+ * @param scrollKey Identifies the history entry — react-router's
+ *   `useLocation().key`. `undefined` turns the memory off, which is
+ *   what an app with no router gets.
+ */
+export const useScrollMemory = (scrollKey) => {
+    const elementRef = useRef(null);
+    const isRestoringRef = useRef(false);
+    // A ref rather than a query for the `<main>` id: the effect
+    // below runs in the same commit that mounts the node, and only a
+    // ref can say which node that was.
+    //
+    // `unknown` in, narrowed here, so the returned function is both a
+    // `RefCallback<HTMLElement>` and something `mergeRefs` accepts —
+    // that library's merge is typed for the prop-merging path, where
+    // every value is `unknown`.
+    const setElement = useCallback((node) => {
+        elementRef.current =
+            node instanceof HTMLElement ? node : null;
+    }, []);
+    useLayoutEffect(() => {
+        const element = elementRef.current;
+        if (!element || scrollKey === undefined) {
+            return undefined;
+        }
+        const offset = recallScrollOffset(scrollKey);
+        // The arrow defers the read of `applyOffset`, so the three
+        // pieces can be declared in the order they depend on each
+        // other rather than in the order they are used.
+        const observer = new ResizeObserver(() => {
+            applyOffset();
+        });
+        const deadline = globalThis.setTimeout(() => {
+            stopRestoring();
+        }, RESTORE_WINDOW_MS);
+        const stopRestoring = () => {
+            if (!isRestoringRef.current) {
+                return;
+            }
+            isRestoringRef.current = false;
+            observer.disconnect();
+            globalThis.clearTimeout(deadline);
+            for (const eventName of READER_INTENT_EVENTS) {
+                element.removeEventListener(eventName, stopRestoring);
+            }
+        };
+        const applyOffset = () => {
+            if (!isRestoringRef.current) {
+                return;
+            }
+            element.scrollTop = offset;
+            // Landed. Anything further would only fight the reader.
+            if (element.scrollTop === offset) {
+                stopRestoring();
+            }
+        };
+        const onScroll = () => {
+            if (isRestoringRef.current) {
+                return;
+            }
+            rememberScrollOffset(scrollKey, element.scrollTop);
+        };
+        isRestoringRef.current = true;
+        for (const eventName of READER_INTENT_EVENTS) {
+            element.addEventListener(eventName, stopRestoring, {
+                passive: true,
+            });
+        }
+        // The scrollport's own height changes with the window; its
+        // content column's changes when the rows land. Both move the
+        // ceiling the offset is clamped against.
+        observer.observe(element);
+        for (const child of Array.from(element.children)) {
+            observer.observe(child);
+        }
+        element.addEventListener("scroll", onScroll, {
+            passive: true,
+        });
+        applyOffset();
+        return () => {
+            stopRestoring();
+            element.removeEventListener("scroll", onScroll);
+        };
+    }, [scrollKey]);
+    return setElement;
+};
+//# sourceMappingURL=useScrollMemory.js.map

package/dist/Main/useScrollMemory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScrollMemory.js","sourceRoot":"","sources":["../../src/Main/useScrollMemory.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@charcuterie/ui",
-  "version": "3.29.1",
+  "version": "3.30.0",
   "description": "The Charcuterie components. Tokens for look, @charcuterie/logic for state, ARIA that agents can actually drive.",
   "license": "MIT",
   "type": "module",

package/src/Main/Main.mdx

@@ -147,3 +147,56 @@ region, so the table is announced as a thing rather than as loose content.
 `<main>` accepts focus so `Shell`'s skip link moves **focus** and not merely the scroll
 position. Without it, Safari and Firefox scroll to `<main>` and leave the next Tab back up
 in the header — which looks exactly like a skip link that works.
+
+## `scrollKey` — the reader's place, kept
+
+<Canvas of={MainStories.ScrollMemory} />
+
+`Shell` gives this element the page's only vertical scrollport, so the header and the rails
+stay put while the content moves. That is what `Shell.test.tsx` asserts, and this is what it
+costs.
+
+**The browser will not put the offset back.** A browser remembers the **document scroller's**
+position per history entry, and `<main>` is not the document scroller. It also restores
+nothing at all across a same-document `pushState` navigation, which is every link press in a
+single-page app. So Back lands at the top of a list the reader had scrolled half-way down,
+`history.scrollRestoration` has no bearing on it, and there is no browser setting that
+changes it. The owner, on Docket:
+
+> "If I scroll, click on an item, then go back, it resets me to the top. […] It should
+> remember where the scroll position was previously. Isn't this handled by Chrome already?"
+
+Pass the history entry's key and it is:
+
+```tsx
+const location = useLocation()
+
+<Main scrollKey={location.key}>
+  <Outlet />
+</Main>
+```
+
+Omit it and nothing is remembered, which is right for a page with no history to remember.
+
+### It has to wait for the content
+
+<Canvas of={MainStories.ScrollMemoryWithLateContent} />
+
+A one-shot `scrollTop = offset` does **nothing** on a real page. The commit that changes the
+route draws a skeleton, the rows land a fetch later, and an offset written against an empty
+scrollport is clamped to `0` by the browser. Every check a one-shot restore could make still
+passes — the offset was remembered, the write happened — and the reader is looking at the top
+of the list.
+
+So the restore re-applies through a `ResizeObserver` on the scrollport and on its content
+column, and stops at the first of three things:
+
+1. **The offset lands.** Anything past that would only fight the reader.
+2. **The reader scrolls.** Any `wheel`, `touchstart`, `keydown` or `pointerdown` on the
+   scrollport ends it, because a page that jumps out from under somebody who has already
+   started reading is a worse bug than the one being fixed.
+3. **Three seconds pass.** A page that slow has been read from the top already.
+
+The offsets live in memory, not in `sessionStorage`. A history key survives a reload; the DOM
+it described does not, and a pixel offset from before the reload points at a different row.
+Restoring a stale number is worse than restoring nothing, because it looks deliberate.

package/src/Main/Main.stories.tsx

@@ -1,11 +1,14 @@
 import type { Meta, StoryObj } from "@storybook/react"
+import { useEffect, useState } from "react"
 
 import { toStoryChoice } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
 import { Card } from "../Card/Card.tsx"
 import { Header } from "../Header/Header.tsx"
 import { Rail } from "../Rail/Rail.tsx"
 import { toMaxInlineSize } from "../Shell/contentWidth.ts"
 import { Shell } from "../Shell/Shell.tsx"
+import { Spinner } from "../Spinner/Spinner.tsx"
 import {
   HeaderSchemeToggle,
   OverflowingContent,
@@ -162,3 +165,152 @@ export const Interactive: Story = {
     </Shell>
   ),
 }
+
+const EPISODE_TITLES = Array.from(
+  { length: 40 },
+  (_unused, index) => `Episode ${index + 1}`,
+)
+
+type HistoryEntry = {
+  episode: string | null
+  key: string
+}
+
+/**
+ * A history stack, small enough to read and honest about the one
+ * thing that matters: **Back returns to the entry it left, with
+ * the key it had.** That key is what the offset is filed under,
+ * and reusing it is the whole mechanism.
+ *
+ * `contentDelayMs` is the second half of the problem. A real list
+ * is fetched, so the commit that changes the route draws an empty
+ * scrollport and the rows land later — an offset applied against
+ * that clamps to `0`. Set it and the restore has to wait for the
+ * content, which is the case the `ResizeObserver` in
+ * `useScrollMemory` exists for.
+ */
+const ScrollMemoryDemo = ({
+  contentDelayMs,
+}: {
+  contentDelayMs: number
+}) => {
+  const [entries, setEntries] = useState<HistoryEntry[]>([
+    { episode: null, key: "entry-1" },
+  ])
+  const [entryIndex, setEntryIndex] = useState(0)
+  const [isContentReady, setIsContentReady] = useState(
+    contentDelayMs === 0,
+  )
+
+  const entry = entries[entryIndex]
+
+  useEffect(() => {
+    if (contentDelayMs === 0) {
+      return undefined
+    }
+
+    setIsContentReady(false)
+
+    const timer = globalThis.setTimeout(() => {
+      setIsContentReady(true)
+    }, contentDelayMs)
+
+    return () => {
+      globalThis.clearTimeout(timer)
+    }
+  }, [contentDelayMs])
+
+  const open = (episode: string) => {
+    const opened = [
+      ...entries.slice(0, entryIndex + 1),
+      { episode, key: `entry-${entries.length + 1}` },
+    ]
+
+    setEntries(opened)
+    setEntryIndex(opened.length - 1)
+  }
+
+  return (
+    <Shell>
+      <Header
+        actions={
+          <Button
+            appearance="outline"
+            isDisabled={entryIndex === 0}
+            onClick={() => {
+              setEntryIndex(entryIndex - 1)
+            }}
+            size="sm"
+          >
+            Back
+          </Button>
+        }
+        heading="Library"
+      />
+
+      <Main scrollKey={entry?.key}>
+        {!isContentReady && <Spinner label="Loading" />}
+
+        {isContentReady && entry?.episode == null && (
+          <div className="flex flex-col gap-3">
+            {EPISODE_TITLES.map((title) => (
+              <Card
+                heading={title}
+                key={title}
+                padding="sm"
+              >
+                <Button
+                  appearance="ghost"
+                  onClick={() => {
+                    open(title)
+                  }}
+                  size="sm"
+                >
+                  Open {title}
+                </Button>
+              </Card>
+            ))}
+          </div>
+        )}
+
+        {isContentReady && entry?.episode != null && (
+          <Card heading={entry.episode}>
+            <p className="text-content-secondary text-sm">
+              A page short enough that the scrollport
+              collapses behind it. Press Back: the list
+              returns to where it was, not to the top.
+            </p>
+          </Card>
+        )}
+      </Main>
+    </Shell>
+  )
+}
+
+/**
+ * The reader's place, kept.
+ *
+ * `Shell` makes `<main>` the page's only vertical scrollport, and
+ * a browser restores the **document** scroller and nothing else —
+ * so without `scrollKey` this list comes back at the top every
+ * time, in every browser, with no setting that changes it.
+ *
+ * Scroll the list, open an episode, then press Back.
+ */
+export const ScrollMemory: Story = {
+  render: () => <ScrollMemoryDemo contentDelayMs={0} />,
+}
+
+/**
+ * The same thing, with the rows arriving 250ms late — which is
+ * what a fetched list does, and what makes a naive
+ * `scrollTop = offset` do nothing at all.
+ *
+ * Back lands on an empty scrollport with no room for the offset,
+ * so the browser clamps it to `0`. The restore therefore re-applies
+ * as the content grows and stops the moment the offset lands, or
+ * the moment the reader scrolls.
+ */
+export const ScrollMemoryWithLateContent: Story = {
+  render: () => <ScrollMemoryDemo contentDelayMs={250} />,
+}

package/src/Main/Main.test.tsx

@@ -1,6 +1,6 @@
 import { composeStories } from "@storybook/react"
-import { expect, userEvent } from "storybook/test"
-import { afterAll, test } from "vitest"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { afterAll, afterEach, test } from "vitest"
 
 import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
 import { mountStory } from "../mountStory.testHelpers.ts"
@@ -11,14 +11,26 @@ import {
   setViewport,
 } from "../viewport.testHelpers.ts"
 import * as stories from "./Main.stories.tsx"
+import { forgetScrollOffsets } from "./scrollMemory.ts"
 
-const { Default, Interactive, Responsive } =
-  composeStories(stories)
+const {
+  Default,
+  Interactive,
+  Responsive,
+  ScrollMemory,
+  ScrollMemoryWithLateContent,
+} = composeStories(stories)
 
 afterAll(async () => {
   await setViewport(DESKTOP)
 })
 
+// The offsets are module state, so they outlive a mount. A test
+// must not.
+afterEach(() => {
+  forgetScrollOffsets()
+})
+
 test("the content column is capped at the token, not at the window", async () => {
   await setViewport(DESKTOP)
 
@@ -165,3 +177,182 @@ test("main takes focus from a skip link without joining the tab order", async ()
 
   await expectNoAxeViolations(canvasElement)
 })
+
+/**
+ * A `scroll` event is dispatched at the next rendering step, not
+ * at the assignment, so a test that scrolls and immediately
+ * navigates measures the listener before it has been told
+ * anything.
+ */
+const scrollTo = async (
+  element: HTMLElement,
+  offset: number,
+) => {
+  element.scrollTop = offset
+
+  await waitFor(async () => {
+    await expect(element.scrollTop).toBe(offset)
+  })
+
+  await new Promise((resolve) => {
+    globalThis.requestAnimationFrame(() => {
+      globalThis.requestAnimationFrame(resolve)
+    })
+  })
+}
+
+/**
+ * The whole point, and the thing no browser does for you.
+ *
+ * `Shell` makes `<main>` the page's only vertical scrollport.
+ * `history.scrollRestoration` governs the **document** scroller, so
+ * it has nothing to say about this element — and it says nothing at
+ * all about a same-document navigation, which is every link press
+ * in a single-page app.
+ */
+test("back returns the list to where it was scrolled, not to the top", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas, canvasElement } =
+    await mountStory(ScrollMemory)
+
+  const main = canvas.getByRole("main")
+
+  // The fixture genuinely scrolls, or the assertion below would
+  // pass against a page that was never long enough to lose a
+  // place in.
+  await expect(main.scrollHeight).toBeGreaterThan(
+    main.clientHeight + 900,
+  )
+
+  await scrollTo(main, 900)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open Episode 12",
+      role: "button",
+    }),
+  )
+
+  await expect(
+    canvas.getByRole("heading", { name: "Episode 12" }),
+  ).toBeVisible()
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Back",
+      role: "button",
+    }),
+  )
+
+  await waitFor(async () => {
+    await expect(main.scrollTop).toBe(900)
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The failure a naive `scrollTop = offset` produces, and the
+ * reason `useScrollMemory` keeps a `ResizeObserver` rather than
+ * writing the number once.
+ *
+ * Back commits before the rows arrive, so the scrollport has no
+ * room for the offset and the browser clamps the write to `0`.
+ * Every assertion a one-shot restore could make still passes — the
+ * offset was remembered, the write happened — and the reader is
+ * looking at the top of the list.
+ */
+test("a restore waits for content that arrives after the navigation", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas } = await mountStory(
+    ScrollMemoryWithLateContent,
+  )
+
+  const main = await waitFor(() => canvas.getByRole("main"))
+
+  await waitFor(async () => {
+    await expect(
+      canvas.getByRole("heading", { name: "Episode 1" }),
+    ).toBeVisible()
+  })
+
+  await scrollTo(main, 900)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open Episode 12",
+      role: "button",
+    }),
+  )
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Back",
+      role: "button",
+    }),
+  )
+
+  // No assertion on the intermediate `0`: whether the rows have
+  // landed by this line depends on how loaded the machine is, and
+  // a test that reads the clock is a test that fails on CI. What
+  // proves the wait is load-bearing is that deleting the
+  // `ResizeObserver` from `useScrollMemory` fails **this** test and
+  // no other.
+  await waitFor(async () => {
+    await expect(main.scrollTop).toBe(900)
+  })
+})
+
+/**
+ * A restore that outlives the reader's first scroll is a page that
+ * fights them. Anything the reader does to the scrollport ends it.
+ */
+test("a reader scrolling during a restore keeps their own position", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas } = await mountStory(
+    ScrollMemoryWithLateContent,
+  )
+
+  await waitFor(async () => {
+    await expect(
+      canvas.getByRole("heading", { name: "Episode 1" }),
+    ).toBeVisible()
+  })
+
+  const main = canvas.getByRole("main")
+
+  await scrollTo(main, 900)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Open Episode 12",
+      role: "button",
+    }),
+  )
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Back",
+      role: "button",
+    }),
+  )
+
+  // Before the rows land, so the restore is still pending.
+  main.dispatchEvent(
+    new WheelEvent("wheel", { bubbles: true }),
+  )
+
+  await waitFor(async () => {
+    await expect(
+      canvas.getByRole("heading", { name: "Episode 1" }),
+    ).toBeVisible()
+  })
+
+  await scrollTo(main, 200)
+
+  // Given up, rather than dragging the reader back to 900.
+  await expect(main.scrollTop).toBe(200)
+})

package/src/Main/Main.tsx

@@ -1,7 +1,12 @@
-import { useUniqueId } from "@charcuterie/logic"
+import {
+  type MergeableRef,
+  mergeRefs,
+  useUniqueId,
+} from "@charcuterie/logic"
 import {
   type ComponentPropsWithRef,
   type ReactNode,
+  type RefCallback,
   useContext,
 } from "react"
 
@@ -12,9 +17,20 @@ import {
 } from "../Shell/contentWidth.ts"
 import { ShellContext } from "../Shell/shellContext.ts"
 import { toClassName } from "../toClassName.ts"
+import { useScrollMemory } from "./useScrollMemory.ts"
 
 export type MainProps = ComponentPropsWithRef<"main"> & {
   contentWidth?: ContentWidth
+  /**
+   * The history entry this page belongs to — react-router's
+   * `useLocation().key`, and the same value under a different
+   * router. Given it, `<main>` remembers where each entry was
+   * scrolled to and puts the offset back on Back and Forward.
+   *
+   * Omit it and nothing is remembered, which is the right default
+   * for a page with no history to remember.
+   */
+  scrollKey?: string
 }
 
 /**
@@ -94,6 +110,30 @@ export type MainProps = ComponentPropsWithRef<"main"> & {
  *    an app's own fixed chrome belongs in `Shell`, beside `Main`
  *    rather than in it.
  *
+ * ## It remembers where each history entry was scrolled to
+ *
+ * `Shell` gives this element the page's only vertical scrollport,
+ * so the header and the rails stay put while the content moves.
+ * The browser's own scroll restoration does not follow it there: a
+ * browser remembers **the document scroller's** offset per history
+ * entry, and `<main>` is not the document scroller. It also does
+ * not restore anything at all across a same-document `pushState`
+ * navigation, which is every link press in a single-page app. Back
+ * therefore lands at the top of a list the reader had scrolled
+ * half-way down, and no browser setting changes that.
+ *
+ * Pass `scrollKey` — react-router's `useLocation().key` — and the
+ * offset comes back. `useScrollMemory.ts` holds the mechanism and
+ * `scrollMemory.ts` the reasoning.
+ *
+ * ```tsx
+ * const location = useLocation()
+ *
+ * <Main scrollKey={location.key}>
+ *   <Outlet />
+ * </Main>
+ * ```
+ *
  * ## Two more things it does, both one line
  *
  * `tabIndex={-1}` so `Shell`'s skip link moves **focus** and not
@@ -128,9 +168,12 @@ export const Main = ({
   className,
   contentWidth,
   id,
+  ref,
+  scrollKey,
   ...mainProps
 }: MainProps): ReactNode => {
   const shell = useContext(ShellContext)
+  const setScrollport = useScrollMemory(scrollKey)
 
   // Always called, never conditionally: a `Main` outside a `Shell`
   // still needs an id an app can point its own skip link at.
@@ -150,6 +193,20 @@ export const Main = ({
         className,
       )}
       id={id ?? shell?.mainId ?? fallbackId}
+      // A caller's `ref` is a subscription, not a value, so the
+      // scroll memory composes with it rather than replacing it.
+      //
+      // The cast is `mergeRefs`' prop-merging signature, where
+      // every value is `unknown`; a caller's `ref` is narrower than
+      // that, never wider.
+      ref={
+        ref
+          ? (mergeRefs(
+              ref as MergeableRef,
+              setScrollport,
+            ) as RefCallback<HTMLElement>)
+          : setScrollport
+      }
       tabIndex={-1}
     >
       {/*

package/src/Main/scrollMemory.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, expect, test } from "vitest"
+
+import {
+  forgetScrollOffsets,
+  recallScrollOffset,
+  rememberScrollOffset,
+} from "./scrollMemory.ts"
+
+afterEach(() => {
+  forgetScrollOffsets()
+})
+
+test("an entry nobody has scrolled recalls the top", () => {
+  expect(recallScrollOffset("entry-never-seen")).toBe(0)
+})
+
+test("an entry recalls the offset it was last left at", () => {
+  rememberScrollOffset("entry-1", 900)
+  rememberScrollOffset("entry-1", 1240)
+
+  expect(recallScrollOffset("entry-1")).toBe(1240)
+})
+
+/**
+ * A long session pushes a new history entry per link press, and
+ * every one of them would otherwise keep a number forever. The
+ * eviction is least-recently-*written*, which is why re-writing an
+ * entry has to move it to the end — a plain `Map.set` on an
+ * existing key keeps its original position, so the entry the
+ * reader is using would age out while it was in use.
+ */
+test("a long session evicts the least recently written entry", () => {
+  for (let index = 0; index < 60; index += 1) {
+    rememberScrollOffset(`entry-${index}`, index * 10)
+  }
+
+  // Written first, never re-written: gone.
+  expect(recallScrollOffset("entry-0")).toBe(0)
+
+  // Inside the last fifty: kept.
+  expect(recallScrollOffset("entry-59")).toBe(590)
+  expect(recallScrollOffset("entry-10")).toBe(100)
+})
+
+test("re-writing an entry saves it from eviction", () => {
+  rememberScrollOffset("entry-old", 500)
+
+  for (let index = 0; index < 49; index += 1) {
+    rememberScrollOffset(`entry-${index}`, index * 10)
+  }
+
+  rememberScrollOffset("entry-old", 640)
+
+  for (let index = 49; index < 60; index += 1) {
+    rememberScrollOffset(`entry-${index}`, index * 10)
+  }
+
+  expect(recallScrollOffset("entry-old")).toBe(640)
+})

package/src/Main/scrollMemory.ts

@@ -0,0 +1,73 @@
+/**
+ * What the browser will not remember for you.
+ *
+ * `Shell` gives `<main>` the page's only vertical scrollport, so
+ * the header and the rails stay put while the content moves —
+ * that is the whole reason `Shell.test.tsx` asserts "only main
+ * scrolls vertically, keeping the rail available".
+ *
+ * It costs exactly one thing, and this module is it. A browser
+ * remembers **the document scroller's** offset per history entry
+ * and puts it back on Back. It does that for a cross-document
+ * load, and `history.scrollRestoration` is the switch for it. It
+ * does **not** do it for an arbitrary element with
+ * `overflow-y: auto`, and it does not do it at all for a
+ * same-document `pushState` navigation, which is every link press
+ * in a single-page app. So a page that scrolls its own `<main>`
+ * loses the reader's place on Back, and no browser setting brings
+ * it back:
+ *
+ * > *"If I scroll, click on an item, then go back, it resets me to
+ * > the top. […] It should remember where the scroll position was
+ * > previously. Isn't this handled by Chrome already?"*
+ *
+ * The offsets are held **in memory**, not in `sessionStorage`. A
+ * history key survives a reload, but the DOM it described does
+ * not: the app re-fetches, re-measures and often re-orders, so a
+ * pixel offset from before the reload points at a different row.
+ * Restoring a stale number is worse than restoring nothing,
+ * because it looks deliberate.
+ */
+
+/**
+ * How many history entries keep an offset. A reader goes back
+ * through a handful of screens, never fifty, so this is a ceiling
+ * against a long session rather than a working set — the map holds
+ * one small number per entry and evicts the least recently
+ * written.
+ */
+const REMEMBERED_ENTRY_LIMIT = 50
+
+const rememberedOffsets = new Map<string, number>()
+
+export const rememberScrollOffset = (
+  key: string,
+  offset: number,
+) => {
+  // Delete before set, so insertion order is least-recent-first
+  // and the eviction below takes the right one. A plain `set` on
+  // an existing key keeps its original position.
+  rememberedOffsets.delete(key)
+  rememberedOffsets.set(key, offset)
+
+  for (const oldestKey of rememberedOffsets.keys()) {
+    if (rememberedOffsets.size <= REMEMBERED_ENTRY_LIMIT) {
+      break
+    }
+
+    rememberedOffsets.delete(oldestKey)
+  }
+}
+
+/**
+ * `0` for an entry nobody has scrolled, which is also the right
+ * answer for an entry nobody has *seen* — a link press lands at
+ * the top of the new page.
+ */
+export const recallScrollOffset = (key: string) =>
+  rememberedOffsets.get(key) ?? 0
+
+/** Test-only. Module state outlives a mount; a test must not. */
+export const forgetScrollOffsets = () => {
+  rememberedOffsets.clear()
+}

package/src/Main/useScrollMemory.ts

@@ -0,0 +1,164 @@
+import { useCallback, useLayoutEffect, useRef } from "react"
+
+import {
+  recallScrollOffset,
+  rememberScrollOffset,
+} from "./scrollMemory.ts"
+
+/**
+ * How long a restore keeps trying while the content is still
+ * arriving.
+ *
+ * The offset cannot be applied until the scrollport is tall enough
+ * to hold it, and on a client-rendered page it is not: the commit
+ * that changes the route draws a skeleton, and the rows land a
+ * fetch later. So the restore re-applies as the content grows, and
+ * gives up after this. A page that takes longer than three seconds
+ * to fill has already been read from the top, and moving it then
+ * is a worse answer than leaving it where the reader put it.
+ */
+const RESTORE_WINDOW_MS = 3000
+
+/** A scroll the reader asked for. It ends the restore at once. */
+const READER_INTENT_EVENTS = [
+  "keydown",
+  "pointerdown",
+  "touchstart",
+  "wheel",
+] as const
+
+/**
+ * Remember where this history entry was scrolled to, and put it
+ * back when the reader returns to it.
+ *
+ * `scrollMemory.ts` says why the browser will not. This is the
+ * part that has to survive the two things a real page does:
+ *
+ *  1. **The content arrives late.** An offset applied against a
+ *     600px skeleton clamps to `0` and looks like it did nothing.
+ *     A `ResizeObserver` on the scrollport and on its content
+ *     column re-applies the offset every time either grows, until
+ *     the offset lands or the window closes.
+ *  2. **The reader scrolls during all that.** Any wheel, touch,
+ *     key or pointer press ends the restore immediately. The
+ *     alternative is a page that jumps out from under somebody who
+ *     has already started reading.
+ *
+ * The save is a passive `scroll` listener, suppressed while a
+ * restore is in flight. Without that suppression the feature eats
+ * itself: writing `scrollTop` on a still-short page clamps to `0`
+ * and fires a `scroll` event reading `0`, which would be saved
+ * over the very offset being restored.
+ *
+ * @param scrollKey Identifies the history entry — react-router's
+ *   `useLocation().key`. `undefined` turns the memory off, which is
+ *   what an app with no router gets.
+ */
+export const useScrollMemory = (
+  scrollKey: string | undefined,
+) => {
+  const elementRef = useRef<HTMLElement | null>(null)
+  const isRestoringRef = useRef(false)
+
+  // A ref rather than a query for the `<main>` id: the effect
+  // below runs in the same commit that mounts the node, and only a
+  // ref can say which node that was.
+  //
+  // `unknown` in, narrowed here, so the returned function is both a
+  // `RefCallback<HTMLElement>` and something `mergeRefs` accepts —
+  // that library's merge is typed for the prop-merging path, where
+  // every value is `unknown`.
+  const setElement = useCallback((node: unknown) => {
+    elementRef.current =
+      node instanceof HTMLElement ? node : null
+  }, [])
+
+  useLayoutEffect(() => {
+    const element = elementRef.current
+
+    if (!element || scrollKey === undefined) {
+      return undefined
+    }
+
+    const offset = recallScrollOffset(scrollKey)
+
+    // The arrow defers the read of `applyOffset`, so the three
+    // pieces can be declared in the order they depend on each
+    // other rather than in the order they are used.
+    const observer = new ResizeObserver(() => {
+      applyOffset()
+    })
+
+    const deadline = globalThis.setTimeout(() => {
+      stopRestoring()
+    }, RESTORE_WINDOW_MS)
+
+    const stopRestoring = () => {
+      if (!isRestoringRef.current) {
+        return
+      }
+
+      isRestoringRef.current = false
+      observer.disconnect()
+      globalThis.clearTimeout(deadline)
+
+      for (const eventName of READER_INTENT_EVENTS) {
+        element.removeEventListener(
+          eventName,
+          stopRestoring,
+        )
+      }
+    }
+
+    const applyOffset = () => {
+      if (!isRestoringRef.current) {
+        return
+      }
+
+      element.scrollTop = offset
+
+      // Landed. Anything further would only fight the reader.
+      if (element.scrollTop === offset) {
+        stopRestoring()
+      }
+    }
+
+    const onScroll = () => {
+      if (isRestoringRef.current) {
+        return
+      }
+
+      rememberScrollOffset(scrollKey, element.scrollTop)
+    }
+
+    isRestoringRef.current = true
+
+    for (const eventName of READER_INTENT_EVENTS) {
+      element.addEventListener(eventName, stopRestoring, {
+        passive: true,
+      })
+    }
+
+    // The scrollport's own height changes with the window; its
+    // content column's changes when the rows land. Both move the
+    // ceiling the offset is clamped against.
+    observer.observe(element)
+
+    for (const child of Array.from(element.children)) {
+      observer.observe(child)
+    }
+
+    element.addEventListener("scroll", onScroll, {
+      passive: true,
+    })
+
+    applyOffset()
+
+    return () => {
+      stopRestoring()
+      element.removeEventListener("scroll", onScroll)
+    }
+  }, [scrollKey])
+
+  return setElement
+}