@oxyhq/bloom 0.79.0 → 0.80.0

package/src/__tests__/scroll-web.test.tsx

@@ -3,55 +3,65 @@
  */
 
 // Exercises the WEB scroll-restoration hook (`scroll/index.web`) against the
-// exact failure mode it was written to survive: the (expo-router-wrapped)
-// React Navigation web stack collapses a hidden background screen (forcing its
-// `scrollTop` to 0) on push, and a re-shown virtualized list re-lays out its
-// rows — and thus reaches its full scroll height — over SEVERAL frames after
-// focus.
+// three things it exists to get right:
 //
-// We mock `expo-router` (the module the hook imports its navigation hooks from)
-// so `useFocusEffect` runs the effect on mount and its cleanup on unmount, and
-// drive `requestAnimationFrame` manually so the multi-frame restore is
-// deterministic.
+//   1. Restore-or-reset. A document-scrolled app shares ONE scroller across
+//      every route, so a key with nothing saved has to be written to 0 — doing
+//      nothing leaves the previous screen's offset in place.
+//   2. Identity on two axes. An entry the router RECYCLED to show different
+//      content is a different screen; the same content in a new entry is too.
+//   3. The collapsed-screen behaviour of the (expo-router-wrapped) React
+//      Navigation web stack, which forces a hidden screen's `scrollTop` to 0
+//      and re-lays out a re-shown virtualized list over SEVERAL frames.
+//
+// The router is supplied through the adapter the core now takes, so this suite
+// mocks nothing: it drives identity and focus directly, which is also how a
+// non-expo consumer would use the hook. `requestAnimationFrame` is driven
+// manually so the multi-frame restore is deterministic.
 
-import { createElement, useRef, type ReactNode } from 'react';
+import {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useRef,
+  type ReactNode,
+} from 'react';
 import { act } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
+import type { NativeScrollEvent, NativeSyntheticEvent } from 'react-native';
+
+import {
+  ScrollRestorationProvider,
+  useScrollRestoration,
+} from '../scroll/index.web';
+import type {
+  ScreenFocusEffect,
+  ScrollRestorationBinding,
+  ScrollRouterAdapter,
+} from '../scroll/types';
 
 // React 19's `act` requires this flag to be set when driving updates manually
 // outside a testing-library renderer.
 (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
   true;
 
-// ---- expo-router mock ------------------------------------------------------
-// `useFocusEffect` here mirrors the real contract closely enough for this hook:
-// it runs the callback in a layout effect and runs the returned cleanup on
-// unmount. `useRoute` yields a stable per-test route key.
-
-let currentRouteKey = 'route-test';
-
-// `virtual: true` keeps the test isolated from the real (native-heavy)
-// `expo-router` package: only the two hooks the scroll primitive consumes are
-// stubbed, and jest never has to resolve the full module from disk.
-jest.mock(
-  'expo-router',
-  () => {
-    const react = jest.requireActual<typeof import('react')>('react');
-    return {
-      useFocusEffect: (effect: () => undefined | (() => void)) => {
-        react.useEffect(effect, [effect]);
-      },
-      useRoute: () => ({ key: currentRouteKey, name: 'Test', params: {} }),
-    };
-  },
-  { virtual: true },
-);
+// ---- A test router ---------------------------------------------------------
+// `useScreenFocusEffect` mirrors expo-router's contract on the two points this
+// hook depends on: while the screen is focused the effect re-runs whenever its
+// IDENTITY changes (which is how a key change mid-focus is seen at all), and it
+// does not run while the screen is blurred.
 
-// Imported AFTER the mock is registered.
-import {
-  ScrollRestorationProvider,
-  useScrollRestoration,
-} from '../scroll/index.web';
+const ContentContext = createContext<string | null>(null);
+const FocusContext = createContext(true);
+
+const testAdapter: ScrollRouterAdapter = {
+  useScreenContentId: () => useContext(ContentContext),
+  useScreenFocusEffect: (effect: ScreenFocusEffect) => {
+    const focused = useContext(FocusContext);
+    useEffect(() => (focused ? effect() : undefined), [effect, focused]);
+  },
+};
 
 // ---- requestAnimationFrame harness ---------------------------------------
 
@@ -92,6 +102,7 @@ class FrameScheduler {
 // (as a real element is), content starts collapsed and grows on "relayout".
 
 const VIEWPORT_HEIGHT = 879;
+const FULL_CONTENT_HEIGHT = 6586;
 
 class FakeScrollNode {
   readonly el: HTMLDivElement;
@@ -144,6 +155,11 @@ class FakeScrollNode {
   emitScroll(): void {
     this.el.dispatchEvent(new Event('scroll'));
   }
+
+  /** The user grabs the scroller mid-restore (wheel, touch, scrollbar, keys). */
+  emitUserTakeover(type: string): void {
+    this.el.dispatchEvent(new Event(type));
+  }
 }
 
 // A RNW-style handle exposing `getScrollableNode()` -> the DOM node.
@@ -155,14 +171,38 @@ function makeHandle(node: FakeScrollNode): { getScrollableNode: () => HTMLElemen
 //
 // A single <ScrollRestorationProvider> stays mounted (mirroring the real app
 // root, where the offset store lives for the document's lifetime) while the
-// screen under it mounts and unmounts to model push/pop navigation.
+// screen under it changes identity, focus and mount state.
+
+interface ScreenProps {
+  node: FakeScrollNode;
+  subKey?: string;
+  enabled?: boolean;
+  /** Drive the `'window'` sentinel instead of the node ref. */
+  windowTarget?: boolean;
+  onBinding?: (binding: ScrollRestorationBinding) => void;
+}
 
-function Screen({ node }: { node: FakeScrollNode }): ReactNode {
+function Screen({
+  node,
+  subKey,
+  enabled,
+  windowTarget,
+  onBinding,
+}: ScreenProps): ReactNode {
   const ref = useRef(makeHandle(node));
-  useScrollRestoration(ref);
+  const binding = useScrollRestoration(windowTarget ? 'window' : ref, {
+    key: subKey,
+    enabled,
+  });
+  onBinding?.(binding);
   return null;
 }
 
+interface ShowOptions extends ScreenProps {
+  content: string | null;
+  focused?: boolean;
+}
+
 class Harness {
   readonly root: Root;
   private readonly container: HTMLElement;
@@ -173,26 +213,26 @@ class Harness {
     this.root = createRoot(this.container);
   }
 
-  /** Mount (focus) the screen bound to `node`. */
-  focus(node: FakeScrollNode): void {
+  /** Render the screen showing `content`, with a focus state and options. */
+  show({ content, focused = true, ...screen }: ShowOptions): void {
     act(() => {
       this.root.render(
-        createElement(
-          ScrollRestorationProvider,
-          null,
-          createElement(Screen, { node }),
-        ),
+        createElement(ScrollRestorationProvider, {
+          adapter: testAdapter,
+          children: createElement(
+            FocusContext.Provider,
+            { value: focused },
+            createElement(
+              ContentContext.Provider,
+              { value: content },
+              createElement(Screen, screen),
+            ),
+          ),
+        }),
       );
     });
   }
 
-  /** Unmount (blur) the screen while keeping the provider/store alive. */
-  blur(): void {
-    act(() => {
-      this.root.render(createElement(ScrollRestorationProvider, null, null));
-    });
-  }
-
   teardown(): void {
     act(() => {
       this.root.unmount();
@@ -201,6 +241,20 @@ class Harness {
   }
 }
 
+function scrollTo(node: FakeScrollNode, offset: number): void {
+  node.scrollTop = offset;
+  act(() => {
+    node.emitScroll();
+  });
+}
+
+let contentSeq = 0;
+/** A content id no earlier test has used, i.e. never seen this session. */
+function unseenContent(): string {
+  contentSeq += 1;
+  return `route-${contentSeq}?`;
+}
+
 describe('web scroll-restoration hook', () => {
   let frames: FrameScheduler;
   let harness: Harness;
@@ -208,7 +262,6 @@ describe('web scroll-restoration hook', () => {
   beforeEach(() => {
     frames = new FrameScheduler();
     frames.install();
-    currentRouteKey = `route-${Math.random().toString(36).slice(2)}`;
     harness = new Harness();
   });
 
@@ -216,16 +269,155 @@ describe('web scroll-restoration hook', () => {
     harness.teardown();
   });
 
-  it('does not clobber the saved offset when the navigator collapses the screen on blur (bug A)', () => {
+  it('resets an unseen screen to the top instead of leaving it where the last one was', () => {
+    // The defect this replaces: a key with nothing saved read 0 and the hook
+    // did nothing at all. On a document-scrolled app (one window scroller for
+    // every route) that means the new screen opens at the previous screen's
+    // offset.
     const node = new FakeScrollNode();
-    node.growTo(6586); // real content
-    harness.focus(node);
+    node.growTo(FULL_CONTENT_HEIGHT);
+    node.scrollTop = 3000; // where the previous screen left the shared scroller
 
-    // User scrolls to 3520 — the live scroll listener records it.
-    node.scrollTop = 3520;
+    harness.show({ node, content: unseenContent() });
+
+    expect(node.scrollTop).toBe(0);
+  });
+
+  it('restores a saved offset across frames while the list is still short', () => {
+    const node = new FakeScrollNode();
+    node.growTo(FULL_CONTENT_HEIGHT);
+    const content = unseenContent();
+
+    harness.show({ node, content });
+    scrollTo(node, 3520);
+    harness.show({ node, content, focused: false });
+
+    // Re-show: list starts collapsed (rows not yet rendered) and grows over
+    // frames. A single-frame restore would be clamped to 0 and never recover.
+    node.collapseLikeNavigator();
+    harness.show({ node, content });
+
+    // Frame 1: still collapsed — the write is clamped to 0, loop keeps retrying.
     act(() => {
-      node.emitScroll();
+      frames.flushOneFrame();
+    });
+    expect(node.scrollTop).toBe(0);
+    expect(frames.pending).toBeGreaterThan(0);
+
+    // A few frames later the rows lay out and the content reaches full height.
+    node.growTo(FULL_CONTENT_HEIGHT);
+    act(() => {
+      frames.flushOneFrame();
+    });
+    expect(node.scrollTop).toBe(3520);
+  });
+
+  it('saves the outgoing list and restores-or-resets the incoming one when the key changes MID-FOCUS', () => {
+    // An in-screen tab or folder swap: the screen never blurs, so nothing in a
+    // focus transition can be relied on to notice.
+    const node = new FakeScrollNode();
+    node.growTo(FULL_CONTENT_HEIGHT);
+    const content = unseenContent();
+
+    harness.show({ node, content, subKey: 'posts' });
+    scrollTo(node, 3520);
+
+    // Swap to a never-seen tab while still focused: reset to the top.
+    harness.show({ node, content, subKey: 'media' });
+    expect(node.scrollTop).toBe(0);
+
+    scrollTo(node, 900);
+
+    // Back to the first tab: its own offset is intact.
+    harness.show({ node, content, subKey: 'posts' });
+    act(() => {
+      frames.flushOneFrame();
     });
+    expect(node.scrollTop).toBe(3520);
+
+    // ...and so is the second tab's.
+    harness.show({ node, content, subKey: 'media' });
+    act(() => {
+      frames.flushOneFrame();
+    });
+    expect(node.scrollTop).toBe(900);
+  });
+
+  it('resets when the route name is the same but the params differ', () => {
+    // The case that makes params part of the content id: expo-router RECYCLES
+    // one route object — `route.key` included — when `NAVIGATE` targets the
+    // current route name and its dynamic segments match, i.e. when only the
+    // query changed. Measured on 56.2.10 and 57.0.9 with `search?q=cats` ->
+    // `search?q=dogs`.
+    const node = new FakeScrollNode();
+    node.growTo(FULL_CONTENT_HEIGHT);
+    const cats = 'search?"q":"cats"';
+    const dogs = 'search?"q":"dogs"';
+
+    harness.show({ node, content: cats });
+    scrollTo(node, 2000);
+
+    harness.show({ node, content: dogs });
+    expect(node.scrollTop).toBe(0);
+
+    // ...and cats keeps its own offset.
+    harness.show({ node, content: cats });
+    act(() => {
+      frames.flushOneFrame();
+    });
+    expect(node.scrollTop).toBe(2000);
+  });
+
+  it('restores content already seen, whatever entry it is reached through', () => {
+    // The rule in one test: an offset belongs to WHAT the user was looking at.
+    // The same url reached through a second history entry — a tab press, an
+    // in-app link, `router.replace` — is the same content and restores.
+    const node = new FakeScrollNode();
+    node.growTo(FULL_CONTENT_HEIGHT);
+    const post = 'p/[id]?"id":"42"';
+    const elsewhere = unseenContent();
+
+    harness.show({ node, content: post });
+    scrollTo(node, 1500);
+
+    harness.show({ node, content: elsewhere });
+    expect(node.scrollTop).toBe(0);
+
+    harness.show({ node, content: post });
+    act(() => {
+      frames.flushOneFrame();
+    });
+    expect(node.scrollTop).toBe(1500);
+  });
+
+  it('is completely inert while disabled — no save, no restore, no reset', () => {
+    const node = new FakeScrollNode();
+    node.growTo(FULL_CONTENT_HEIGHT);
+    node.scrollTop = 3000;
+    const content = unseenContent();
+
+    harness.show({ node, content, enabled: false });
+
+    // No reset, and no restore loop scheduled.
+    expect(node.scrollTop).toBe(3000);
+    expect(frames.pending).toBe(0);
+
+    // No save either: scrolling while disabled records nothing, which the
+    // enabled render below proves by resetting instead of restoring.
+    scrollTo(node, 4200);
+    harness.show({ node, content, enabled: true });
+    expect(node.scrollTop).toBe(0);
+    expect(frames.pending).toBe(0);
+  });
+
+  it('does not clobber the saved offset when the navigator collapses the screen on blur', () => {
+    const node = new FakeScrollNode();
+    node.growTo(FULL_CONTENT_HEIGHT);
+    const content = unseenContent();
+    harness.show({ node, content });
+
+    // User scrolls to 3520 — the live scroll listener records it.
+    scrollTo(node, 3520);
 
     // Navigator collapses the hidden screen and forces scrollTop to 0 while the
     // screen is still technically focused (a stray scroll event fires). This
@@ -236,99 +428,596 @@ describe('web scroll-restoration hook', () => {
     });
 
     // Blur: cleanup runs and must persist the last GOOD offset, not the 0.
-    harness.blur();
+    harness.show({ node, content, focused: false });
 
     // Re-show with full content height: restore should reach 3520 in one frame.
-    node.growTo(6586);
+    node.growTo(FULL_CONTENT_HEIGHT);
     node.scrollTop = 0;
-    harness.focus(node);
+    harness.show({ node, content });
     act(() => {
       frames.flushOneFrame();
     });
     expect(node.scrollTop).toBe(3520);
   });
 
-  it('re-applies the offset across frames until the list reaches full height (bug B)', () => {
+  it('persists a genuine scroll-to-top over a previously-saved offset', () => {
     const node = new FakeScrollNode();
-    node.growTo(6586);
-    harness.focus(node);
-    node.scrollTop = 3520;
-    act(() => {
-      node.emitScroll();
-    });
-    harness.blur();
+    node.growTo(FULL_CONTENT_HEIGHT);
+    const content = unseenContent();
+    harness.show({ node, content });
+    scrollTo(node, 3520);
 
-    // Re-show: list starts collapsed (rows not yet rendered) and grows over
-    // frames. A single-frame restore would be clamped to 0 and never recover.
+    // User scrolls all the way back to the top; container is NOT collapsed, so
+    // this 0 is genuine and must overwrite the saved 3520.
+    scrollTo(node, 0);
+    harness.show({ node, content, focused: false });
+
+    // Re-show: the saved 0 is written back, so anything that nudged the shared
+    // scroller in between is undone.
+    node.scrollTop = 500;
+    harness.show({ node, content });
+    expect(node.scrollTop).toBe(0);
+    // A write to 0 always sticks, so it never schedules the re-apply loop.
+    expect(frames.pending).toBe(0);
+  });
+
+  it('stops retrying after the frame cap even if the content never grows', () => {
+    const node = new FakeScrollNode();
+    node.growTo(FULL_CONTENT_HEIGHT);
+    const content = unseenContent();
+    harness.show({ node, content });
+    scrollTo(node, 3520);
+    harness.show({ node, content, focused: false });
+
+    // Re-show that never reaches full height.
     node.collapseLikeNavigator();
-    harness.focus(node);
+    harness.show({ node, content });
+
+    // Flush far more than the cap; the loop must terminate.
+    for (let i = 0; i < 60; i++) {
+      act(() => {
+        frames.flushOneFrame();
+      });
+    }
+    expect(frames.pending).toBe(0);
+  });
+
+  it.each(['wheel', 'touchstart', 'pointerdown', 'keydown'])(
+    'abandons the restore as soon as the user takes over (%s)',
+    (takeoverEvent) => {
+      // HTML §7.4.6.5 makes this a condition on the browser's own restoration:
+      // it re-attempts the saved position "until document's has been scrolled by
+      // the user becomes true". Without the abort the loop yanks the user back
+      // up to once a frame for the whole frame budget.
+      const node = new FakeScrollNode();
+      node.growTo(FULL_CONTENT_HEIGHT);
+      const content = unseenContent();
+      harness.show({ node, content });
+      scrollTo(node, 3520);
+      harness.show({ node, content, focused: false });
+
+      // Re-show collapsed, so the loop is still retrying rather than done.
+      node.collapseLikeNavigator();
+      harness.show({ node, content });
+      act(() => {
+        frames.flushOneFrame();
+      });
+      expect(frames.pending).toBeGreaterThan(0);
+
+      // The user grabs it and scrolls somewhere of their own.
+      act(() => {
+        node.emitUserTakeover(takeoverEvent);
+      });
+      node.growTo(FULL_CONTENT_HEIGHT);
+      scrollTo(node, 120);
+
+      for (let i = 0; i < 10; i++) {
+        act(() => {
+          frames.flushOneFrame();
+        });
+      }
+      expect(frames.pending).toBe(0);
+      expect(node.scrollTop).toBe(120);
+    },
+  );
+
+  it('does not abandon the restore on the scroll events its own writes produce', () => {
+    // The naive form of the abort above — "any scroll event cancels" — cancels
+    // on the first frame, because `setOffset` IS a scroll. This is the control
+    // that keeps the two apart.
+    const node = new FakeScrollNode();
+    node.growTo(FULL_CONTENT_HEIGHT);
+    const content = unseenContent();
+    harness.show({ node, content });
+    scrollTo(node, 3520);
+    harness.show({ node, content, focused: false });
+
+    node.collapseLikeNavigator();
+    harness.show({ node, content });
 
-    // Frame 1: still collapsed — the write is clamped to 0, loop keeps retrying.
     act(() => {
       frames.flushOneFrame();
+      node.emitScroll(); // what a real browser emits after our clamped write
     });
-    expect(node.scrollTop).toBe(0);
     expect(frames.pending).toBeGreaterThan(0);
 
-    // A few frames later the rows lay out and the content reaches full height.
-    node.growTo(6586);
+    node.growTo(FULL_CONTENT_HEIGHT);
     act(() => {
       frames.flushOneFrame();
     });
     expect(node.scrollTop).toBe(3520);
   });
 
-  it('treats a saved offset of 0 as a no-op (no restore loop scheduled)', () => {
+  it('is inert when the adapter cannot identify the screen', () => {
     const node = new FakeScrollNode();
-    node.growTo(6586);
-    harness.focus(node);
-    // Nothing saved for this fresh route key => read() is 0 => no rAF queued.
+    node.growTo(FULL_CONTENT_HEIGHT);
+    node.scrollTop = 3000;
+
+    harness.show({ node, content: null });
+
+    expect(node.scrollTop).toBe(3000);
     expect(frames.pending).toBe(0);
   });
 
-  it('persists a genuine scroll-to-top over a previously-saved offset', () => {
+  it('follows the real navigation sequence: home -> post -> TAP HOME -> back -> back', () => {
+    // The user's own scenario, and the reason the key is CONTENT rather than
+    // the navigation entry. Driving expo-router's own forked router
+    // (`build/layouts/StackClient.js`) on 56.2.10 and 57.0.9 shows what tapping
+    // Home actually does:
+    //
+    //   [home#A]                      user scrolls home
+    //   push /p/1   -> [home#A, post#B]
+    //   navigate /  -> [home#A, post#B, home#C]   <- a NEW entry, NEW key
+    //   back        -> post#B  (resetRoot to the recorded state, keys intact)
+    //   back        -> home#A
+    //
+    // Keyed on the entry, home#C misses and opens at the top. Keyed on content,
+    // every one of these is `index?` or `p/[id]?"id":"1"` and the user gets
+    // back what they were looking at — the Twitter/Instagram convention.
     const node = new FakeScrollNode();
-    node.growTo(6586);
-    harness.focus(node);
-    node.scrollTop = 3520;
+    node.growTo(FULL_CONTENT_HEIGHT);
+    const home = 'index?';
+    const post = 'p/[id]?"id":"1"';
+
+    harness.show({ node, content: home });
+    scrollTo(node, 2400);
+
+    harness.show({ node, content: post });
+    expect(node.scrollTop).toBe(0);
+    scrollTo(node, 800);
+
+    // TAP HOME — a new history entry, but the same content.
+    harness.show({ node, content: home });
     act(() => {
-      node.emitScroll();
+      frames.flushOneFrame();
     });
-    // User scrolls all the way back to the top; container is NOT collapsed, so
-    // this 0 is genuine and must overwrite the saved 3520.
-    node.scrollTop = 0;
+    expect(node.scrollTop).toBe(2400);
+
+    // Browser Back to the post.
+    harness.show({ node, content: post });
     act(() => {
-      node.emitScroll();
+      frames.flushOneFrame();
     });
-    harness.blur();
+    expect(node.scrollTop).toBe(800);
 
-    // Re-show: saved offset is 0 => restore is a no-op, nothing scheduled.
-    node.scrollTop = 500; // pretend something nudged it after re-show
-    harness.focus(node);
+    // Browser Back again to home.
+    harness.show({ node, content: home });
+    act(() => {
+      frames.flushOneFrame();
+    });
+    expect(node.scrollTop).toBe(2400);
+  });
+
+  it('opens content never seen this session at the top', () => {
+    // The other half of the rule, and the defect that started the task: with
+    // one shared document scroller, "never seen" has to mean "written to 0".
+    const node = new FakeScrollNode();
+    node.growTo(FULL_CONTENT_HEIGHT);
+
+    harness.show({ node, content: unseenContent() });
+    scrollTo(node, 2600);
+
+    harness.show({ node, content: unseenContent() });
+    expect(node.scrollTop).toBe(0);
     expect(frames.pending).toBe(0);
-    expect(node.scrollTop).toBe(500);
   });
 
-  it('stops retrying after the frame cap even if the content never grows', () => {
+  it('sends content to the top ONCE, not on every re-run for the same key', () => {
+    // `enabled` turning on after being off is not a fresh arrival. The hook was
+    // inert while it was off, so a scroll during that window was never
+    // recorded — resetting on the way back in would throw it away with nothing
+    // to restore from. Restoring twice is harmless; resetting twice is loss.
     const node = new FakeScrollNode();
-    node.growTo(6586);
-    harness.focus(node);
-    node.scrollTop = 3520;
+    node.growTo(FULL_CONTENT_HEIGHT);
+    const content = unseenContent();
+
+    harness.show({ node, content });
+    expect(node.scrollTop).toBe(0);
+
+    harness.show({ node, content, enabled: false });
+    node.scrollTop = 1800; // the user scrolls while the hook is inert
+
+    harness.show({ node, content, enabled: true });
+    expect(node.scrollTop).toBe(1800);
+  });
+
+  it('does not persist the browser echo of its own reset write', () => {
+    // A real browser dispatches `scroll` for our `setOffset(0)` (jsdom does
+    // not, hence the explicit emit). Persisting it records an offset the user
+    // never chose — and under content keying a SIBLING screen showing the same
+    // content shares the key, so the echo can land after that sibling saved a
+    // real offset and clobber it. This is the two-live-entries trade made
+    // observable.
+    const shared = 'p/[id]?"id":"42"';
+    const first = new FakeScrollNode();
+    const second = new FakeScrollNode();
+    first.growTo(FULL_CONTENT_HEIGHT);
+    second.growTo(FULL_CONTENT_HEIGHT);
+
+    // Two live screens on the same content, both arriving with nothing saved.
     act(() => {
-      node.emitScroll();
+      harness.root.render(
+        createElement(ScrollRestorationProvider, {
+          adapter: testAdapter,
+          children: createElement(
+            ContentContext.Provider,
+            { value: shared },
+            createElement(Screen, { node: first }),
+            createElement(Screen, { node: second }),
+          ),
+        }),
+      );
     });
-    harness.blur();
 
-    // Re-show that never reaches full height.
+    // The first screen scrolls and saves a real offset under the shared key...
+    scrollTo(first, 2400);
+    // ...and only then does the second screen's reset echo arrive.
+    act(() => {
+      second.emitScroll();
+    });
+
+    // A later visit to that content must still get 2400, not the echoed 0.
+    const later = new FakeScrollNode();
+    later.growTo(FULL_CONTENT_HEIGHT);
+    harness.show({ node: later, content: shared });
+    act(() => {
+      frames.flushOneFrame();
+    });
+    expect(later.scrollTop).toBe(2400);
+  });
+
+  it('does not persist a PARTIAL offset when the restore is aborted mid-loop', () => {
+    // The corruption this closes: every loop write echoes back as a `scroll`
+    // event, so before suppression an interrupted restore left whatever the
+    // browser had clamped to in the store, and that content's remembered
+    // position stayed wrong for the rest of the session. A swipe that commits
+    // a route change mid-restore hits this every time.
+    const node = new FakeScrollNode();
+    node.growTo(FULL_CONTENT_HEIGHT);
+    const content = unseenContent();
+
+    harness.show({ node, content });
+    scrollTo(node, 3520);
+    harness.show({ node, content, focused: false });
+
+    // Re-show with the content still short, so the write clamps to a partial.
     node.collapseLikeNavigator();
-    harness.focus(node);
+    node.growTo(1500); // 621px of scroll range against a 3520 target
+    harness.show({ node, content });
+    act(() => {
+      frames.flushOneFrame();
+      node.emitScroll(); // the browser echoing our own clamped write
+    });
+    expect(node.scrollTop).toBe(1500 - 879);
 
-    // Flush far more than the cap; the loop must terminate.
-    for (let i = 0; i < 60; i++) {
+    // The user grabs it, which aborts the loop, and then navigates away.
+    act(() => {
+      node.emitUserTakeover('touchstart');
+    });
+    harness.show({ node, content, focused: false });
+
+    // The original offset must have survived, not the partial.
+    node.growTo(FULL_CONTENT_HEIGHT);
+    node.scrollTop = 0;
+    harness.show({ node, content });
+    act(() => {
+      frames.flushOneFrame();
+    });
+    expect(node.scrollTop).toBe(3520);
+  });
+
+  it('keeps the original target when the loop exhausts its frame budget', () => {
+    // Same mechanism, the other end state. Content that is short right now is
+    // usually a list still loading, not a permanent shrink — remembering the
+    // target means the position is right once the rows arrive.
+    const node = new FakeScrollNode();
+    node.growTo(FULL_CONTENT_HEIGHT);
+    const content = unseenContent();
+
+    harness.show({ node, content });
+    scrollTo(node, 3520);
+    harness.show({ node, content, focused: false });
+
+    node.collapseLikeNavigator();
+    node.growTo(1500);
+    harness.show({ node, content });
+    for (let i = 0; i < 40; i++) {
+      const wrote = frames.pending > 0;
       act(() => {
         frames.flushOneFrame();
+        // Only a frame that actually wrote produces an echo; a real browser
+        // dispatches `scroll` when something moves, not on a timer.
+        if (wrote) node.emitScroll();
       });
     }
     expect(frames.pending).toBe(0);
+    harness.show({ node, content, focused: false });
+
+    node.growTo(FULL_CONTENT_HEIGHT);
+    node.scrollTop = 0;
+    harness.show({ node, content });
+    act(() => {
+      frames.flushOneFrame();
+    });
+    expect(node.scrollTop).toBe(3520);
+  });
+
+  describe('the window sentinel and a collapsing document', () => {
+    // Every Oxy web feed passes `'window'`. Under a TABBED navigator each tab
+    // stays MOUNTED and non-focused ones are `display: none`, which collapses
+    // the DOCUMENT — measured in Chrome 150: `documentElement.scrollHeight`
+    // 8040 -> 800, `scrollY` forced to 0, two `scroll` events dispatched. Blur
+    // is emitted from an effect that has not run yet, so the outgoing tab's
+    // listener is still attached when they arrive.
+    const DOC_VIEWPORT = 800;
+    let docHeight = 8040;
+    let scrollY = 0;
+
+    beforeEach(() => {
+      docHeight = 8040;
+      scrollY = 0;
+      Object.defineProperty(window, 'scrollY', {
+        configurable: true,
+        get: () => scrollY,
+      });
+      Object.defineProperty(window, 'innerHeight', {
+        configurable: true,
+        get: () => DOC_VIEWPORT,
+      });
+      Object.defineProperty(document.documentElement, 'scrollHeight', {
+        configurable: true,
+        get: () => docHeight,
+      });
+      window.scrollTo = ((_x: number, y: number) => {
+        scrollY = Math.min(Math.max(0, y), Math.max(0, docHeight - DOC_VIEWPORT));
+      }) as typeof window.scrollTo;
+    });
+
+    function emitWindowScroll(): void {
+      act(() => {
+        window.dispatchEvent(new Event('scroll'));
+      });
+    }
+
+    it('does not persist the 0 a collapsing document forces', () => {
+      const node = new FakeScrollNode();
+      const content = unseenContent();
+
+      harness.show({ node, content, windowTarget: true });
+      // Positive control: the document is genuinely scrollable, so a 0 read
+      // here would be a real user position rather than a collapse artefact.
+      expect(document.documentElement.scrollHeight).toBeGreaterThan(
+        window.innerHeight,
+      );
+      scrollY = 5000;
+      emitWindowScroll();
+
+      // The tab switch: this screen is hidden, the document collapses to the
+      // viewport and the browser forces the offset to 0, dispatching `scroll`
+      // while this screen's listener is still attached.
+      docHeight = DOC_VIEWPORT;
+      scrollY = 0;
+      emitWindowScroll();
+
+      // Leaving and returning must bring back 5000, not the forced 0.
+      harness.show({ node, content, windowTarget: true, focused: false });
+      docHeight = 8040;
+      harness.show({ node, content, windowTarget: true });
+      act(() => {
+        frames.flushOneFrame();
+      });
+      expect(window.scrollY).toBe(5000);
+    });
+
+    it('does not persist a PARTIAL clamp when a shorter tab takes over the document', () => {
+      // The residual the collapse guard cannot see: the destination tab is
+      // still taller than the viewport, so `maxOffset > 0` and the offset is
+      // not 0 — it is the destination's MAXIMUM. Measured in Chrome 150:
+      // 5000 -> 2215 with `scrollHeight` 8040 -> 3015, dispatched as TWO
+      // identical scroll events.
+      const node = new FakeScrollNode();
+      const content = unseenContent();
+
+      harness.show({ node, content, windowTarget: true });
+      scrollY = 5000;
+      emitWindowScroll();
+
+      // The shorter tab takes over: the range shrinks and the browser parks the
+      // offset at the new bottom, twice.
+      docHeight = 3015;
+      scrollY = 3015 - DOC_VIEWPORT;
+      emitWindowScroll();
+      emitWindowScroll();
+
+      harness.show({ node, content, windowTarget: true, focused: false });
+      docHeight = 8040;
+      harness.show({ node, content, windowTarget: true });
+      act(() => {
+        frames.flushOneFrame();
+      });
+      expect(window.scrollY).toBe(5000);
+    });
+
+    it('persists a GENUINE scroll to the very bottom when nothing shrank', () => {
+      // The collision worth worrying about, and it does not fire: reaching the
+      // bottom under your own steam does not shrink the page in the same
+      // breath, so only one of the two conditions holds.
+      const node = new FakeScrollNode();
+      const content = unseenContent();
+
+      harness.show({ node, content, windowTarget: true });
+      scrollY = docHeight - DOC_VIEWPORT; // 7240, exactly at the maximum
+      emitWindowScroll();
+
+      harness.show({ node, content, windowTarget: true, focused: false });
+      scrollY = 0;
+      harness.show({ node, content, windowTarget: true });
+      act(() => {
+        frames.flushOneFrame();
+      });
+      expect(window.scrollY).toBe(7240);
+    });
+
+    it('recovers as soon as the user scrolls off the bottom after a shrink', () => {
+      // The suppression must not stick: while it holds, the reference range is
+      // not updated, so the only thing that clears it is an offset that is not
+      // at the maximum. Measured to recover on the first such scroll.
+      const node = new FakeScrollNode();
+      const content = unseenContent();
+
+      harness.show({ node, content, windowTarget: true });
+      scrollY = 7240;
+      emitWindowScroll();
+
+      docHeight = 4020; // something collapsed under them
+      scrollY = 4020 - DOC_VIEWPORT;
+      emitWindowScroll();
+
+      scrollY = 1000; // and now they scroll on their own
+      emitWindowScroll();
+
+      harness.show({ node, content, windowTarget: true, focused: false });
+      scrollY = 0;
+      docHeight = 4020;
+      harness.show({ node, content, windowTarget: true });
+      act(() => {
+        frames.flushOneFrame();
+      });
+      expect(window.scrollY).toBe(1000);
+    });
+
+    it('still persists a GENUINE scroll to the top of a scrollable document', () => {
+      // The other direction, and the reason `canScroll` cannot simply answer
+      // `false`: on a document that can scroll, 0 is where the user is.
+      const node = new FakeScrollNode();
+      const content = unseenContent();
+
+      harness.show({ node, content, windowTarget: true });
+      scrollY = 5000;
+      emitWindowScroll();
+      scrollY = 0; // the user scrolls back up; the document is still tall
+      emitWindowScroll();
+      expect(document.documentElement.scrollHeight).toBeGreaterThan(
+        window.innerHeight,
+      );
+
+      harness.show({ node, content, windowTarget: true, focused: false });
+      scrollY = 3000; // something nudges the shared scroller in between
+      harness.show({ node, content, windowTarget: true });
+      expect(window.scrollY).toBe(0);
+    });
+  });
+
+  it('returns a binding that is safe to wire onto a list on either platform', () => {
+    const node = new FakeScrollNode();
+    const seen: ScrollRestorationBinding[] = [];
+
+    harness.show({
+      node,
+      content: unseenContent(),
+      onBinding: (binding) => seen.push(binding),
+    });
+
+    expect(typeof seen[0]?.onScroll).toBe('function');
+    // Calling it on web must be harmless: this platform records offsets from
+    // the DOM node's own scroll event, and a shared call site still passes it.
+    expect(() =>
+      seen[0]?.onScroll({
+        nativeEvent: { contentOffset: { x: 0, y: 1234 } },
+      } as NativeSyntheticEvent<NativeScrollEvent>),
+    ).not.toThrow();
+  });
+});
+
+// ---- history.scrollRestoration ---------------------------------------------
+// jsdom does not implement `history.scrollRestoration` at all ('scrollRestoration'
+// in history === false), so the provider's feature detect makes it a no-op in
+// every other suite here. This block installs the property first, which is what
+// makes these the only tests that exercise the switch.
+
+describe('manual browser scroll restoration', () => {
+  let installed: HTMLElement | null = null;
+  let root: Root | null = null;
+
+  function mountProvider(): void {
+    installed = document.createElement('div');
+    document.body.appendChild(installed);
+    root = createRoot(installed);
+    act(() => {
+      root?.render(
+        createElement(ScrollRestorationProvider, {
+          adapter: testAdapter,
+          children: null,
+        }),
+      );
+    });
+  }
+
+  beforeEach(() => {
+    Object.defineProperty(window.history, 'scrollRestoration', {
+      configurable: true,
+      writable: true,
+      value: 'auto',
+    });
+  });
+
+  afterEach(() => {
+    if (root && installed) {
+      act(() => {
+        root?.unmount();
+      });
+      installed.remove();
+    }
+    root = null;
+    installed = null;
+    delete (window.history as { scrollRestoration?: string }).scrollRestoration;
+  });
+
+  it('takes restoration over while the provider is mounted', () => {
+    mountProvider();
+    expect(history.scrollRestoration).toBe('manual');
+  });
+
+  it('hands restoration back to the browser on pagehide', () => {
+    // The offset map is in memory only: a reload starts empty and a bfcache
+    // restore resumes a document whose focus effects never re-run. Leaving it
+    // 'manual' on the way out means nobody restores at all.
+    mountProvider();
+    act(() => {
+      window.dispatchEvent(new Event('pagehide'));
+    });
+    expect(history.scrollRestoration).toBe('auto');
+  });
+
+  it('hands restoration back on unmount', () => {
+    mountProvider();
+    expect(history.scrollRestoration).toBe('manual');
+    act(() => {
+      root?.unmount();
+    });
+    installed?.remove();
+    root = null;
+    installed = null;
+    expect(history.scrollRestoration).toBe('auto');
   });
 });