@oxyhq/bloom 0.6.22 → 0.6.24

package/lib/typescript/module/scroll/index.web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../src/scroll/index.web.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,8BAA8B,EAC9B,uBAAuB,EACvB,2BAA2B,EAC5B,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,gBAAgB,EAChB,8BAA8B,EAC9B,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,SAAS,CAAC;AAgBjB;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,QAAQ,GACT,EAAE,8BAA8B,2CAOhC;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,uBAAuB,EAC/B,OAAO,CAAC,EAAE,2BAA2B,GACpC,IAAI,CAyDN"}
+{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../src/scroll/index.web.tsx"],"names":[],"mappings":"AAgDA,OAAO,KAAK,EACV,8BAA8B,EAC9B,uBAAuB,EACvB,2BAA2B,EAC5B,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,gBAAgB,EAChB,8BAA8B,EAC9B,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,SAAS,CAAC;AAmCjB;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,QAAQ,GACT,EAAE,8BAA8B,2CAOhC;AAYD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,uBAAuB,EAC/B,OAAO,CAAC,EAAE,2BAA2B,GACpC,IAAI,CAqGN"}

package/lib/typescript/module/scroll/scrollable.web.d.ts

@@ -1,12 +1,24 @@
 import type { ScrollRestorationTarget } from './types';
 /**
  * A normalized read/write interface over whatever the caller registered, so
- * the hook does not branch on target shape. Both methods are no-ops when the
- * underlying element is not yet (or no longer) attached.
+ * the hook does not branch on target shape. All methods are safe no-ops when
+ * the underlying element is not yet (or no longer) attached.
  */
 export interface ResolvedScroller {
     getOffset: () => number;
     setOffset: (offset: number) => void;
+    /**
+     * Whether the scroll container can currently hold a non-zero offset, i.e.
+     * its content is taller than its viewport (`scrollHeight > clientHeight`).
+     *
+     * React Navigation's web stack collapses a hidden background screen so its
+     * content height drops to the viewport height; while collapsed the container
+     * cannot be scrolled and its `scrollTop` is forced to 0. The hook uses this
+     * to ignore a spurious 0 read coming from a collapsed container rather than
+     * persisting it over a previously-saved good offset. The `'window'` scroller
+     * is never collapsed by the navigator, so it always reports `true`.
+     */
+    canScroll: () => boolean;
 }
 /**
  * Build a {@link ResolvedScroller} for a target. The window sentinel reads and

package/lib/typescript/module/scroll/scrollable.web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scrollable.web.d.ts","sourceRoot":"","sources":["../../../../src/scroll/scrollable.web.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAuCD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,uBAAuB,GAAG,gBAAgB,CAoBhF"}
+{"version":3,"file":"scrollable.web.d.ts","sourceRoot":"","sources":["../../../../src/scroll/scrollable.web.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC;;;;;;;;;;OAUG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;CAC1B;AAuCD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,uBAAuB,GAAG,gBAAgB,CAyBhF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.6.22",
+  "version": "0.6.24",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -631,7 +631,6 @@
     }
   },
   "devDependencies": {
-    "@react-navigation/native": "^7.0.0",
     "@storybook/addon-docs": "^10",
     "@storybook/react-vite": "^10",
     "@testing-library/react-native": "^13.3.3",
@@ -641,6 +640,7 @@
     "@types/react-native": "*",
     "@vitejs/plugin-react": "^6.0.2",
     "expo-font": "^56.0.5",
+    "expo-router": "^56.0.0",
     "jest": "^30.3.0",
     "jest-environment-jsdom": "^30.4.1",
     "react": "19.2.0",
@@ -662,9 +662,9 @@
     "vite": "^7"
   },
   "peerDependencies": {
-    "@react-navigation/native": ">=6.0.0",
     "expo": "*",
     "expo-font": "*",
+    "expo-router": ">=3.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "react-native": ">=0.73.0",
@@ -676,15 +676,15 @@
     "sonner-native": ">=0.17.0"
   },
   "peerDependenciesMeta": {
-    "@react-navigation/native": {
-      "optional": true
-    },
     "expo": {
       "optional": true
     },
     "expo-font": {
       "optional": true
     },
+    "expo-router": {
+      "optional": true
+    },
     "react-dom": {
       "optional": true
     },

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

@@ -0,0 +1,334 @@
+/**
+ * @jest-environment jsdom
+ */
+
+// 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.
+//
+// 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.
+
+import { createElement, useRef, type ReactNode } from 'react';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+// 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 },
+);
+
+// Imported AFTER the mock is registered.
+import {
+  ScrollRestorationProvider,
+  useScrollRestoration,
+} from '../scroll/index.web';
+
+// ---- requestAnimationFrame harness ---------------------------------------
+
+type FrameCallback = (time: number) => void;
+
+class FrameScheduler {
+  private queue = new Map<number, FrameCallback>();
+  private nextId = 1;
+
+  install(): void {
+    window.requestAnimationFrame = ((cb: FrameCallback): number => {
+      const id = this.nextId++;
+      this.queue.set(id, cb);
+      return id;
+    }) as typeof window.requestAnimationFrame;
+    window.cancelAnimationFrame = (id: number): void => {
+      this.queue.delete(id);
+    };
+  }
+
+  /** Run one frame's worth of scheduled callbacks (those queued before now). */
+  flushOneFrame(): void {
+    const batch = [...this.queue.entries()];
+    this.queue.clear();
+    for (const [, cb] of batch) cb(performance.now());
+  }
+
+  get pending(): number {
+    return this.queue.size;
+  }
+}
+
+// ---- A fake RNW scrollable -------------------------------------------------
+// Models a FlashList's underlying DOM node. It MUST be a real HTMLElement
+// because the scroller resolves the live node via `instanceof HTMLElement`.
+// jsdom does no layout, so we own `scrollHeight`/`clientHeight`/`scrollTop`
+// ourselves: `scrollTop` is clamped to `scrollHeight - clientHeight` on write
+// (as a real element is), content starts collapsed and grows on "relayout".
+
+const VIEWPORT_HEIGHT = 879;
+
+class FakeScrollNode {
+  readonly el: HTMLDivElement;
+  private _scrollHeight = VIEWPORT_HEIGHT; // collapsed: equals clientHeight
+  private _scrollTop = 0;
+
+  constructor() {
+    const el = document.createElement('div');
+    Object.defineProperty(el, 'clientHeight', {
+      configurable: true,
+      get: () => VIEWPORT_HEIGHT,
+    });
+    Object.defineProperty(el, 'scrollHeight', {
+      configurable: true,
+      get: () => this._scrollHeight,
+    });
+    Object.defineProperty(el, 'scrollTop', {
+      configurable: true,
+      get: () => this._scrollTop,
+      set: (value: number) => {
+        const max = Math.max(0, this._scrollHeight - VIEWPORT_HEIGHT);
+        this._scrollTop = Math.min(Math.max(0, value), max);
+      },
+    });
+    this.el = el;
+  }
+
+  get scrollTop(): number {
+    return this.el.scrollTop;
+  }
+  set scrollTop(value: number) {
+    this.el.scrollTop = value;
+  }
+
+  /** Grow content to its full laid-out height (re-show relayout). */
+  growTo(height: number): void {
+    this._scrollHeight = height;
+  }
+
+  /**
+   * Reproduce what React Navigation's web stack does to a hidden background
+   * screen: collapse its content to the viewport height and force scrollTop to
+   * 0 (a collapsed container cannot hold a non-zero offset).
+   */
+  collapseLikeNavigator(): void {
+    this._scrollHeight = VIEWPORT_HEIGHT;
+    this._scrollTop = 0;
+  }
+
+  emitScroll(): void {
+    this.el.dispatchEvent(new Event('scroll'));
+  }
+}
+
+// A RNW-style handle exposing `getScrollableNode()` -> the DOM node.
+function makeHandle(node: FakeScrollNode): { getScrollableNode: () => HTMLElement } {
+  return { getScrollableNode: () => node.el };
+}
+
+// ---- Render harness --------------------------------------------------------
+//
+// 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.
+
+function Screen({ node }: { node: FakeScrollNode }): ReactNode {
+  const ref = useRef(makeHandle(node));
+  useScrollRestoration(ref);
+  return null;
+}
+
+class Harness {
+  readonly root: Root;
+  private readonly container: HTMLElement;
+
+  constructor() {
+    this.container = document.createElement('div');
+    document.body.appendChild(this.container);
+    this.root = createRoot(this.container);
+  }
+
+  /** Mount (focus) the screen bound to `node`. */
+  focus(node: FakeScrollNode): void {
+    act(() => {
+      this.root.render(
+        createElement(
+          ScrollRestorationProvider,
+          null,
+          createElement(Screen, { node }),
+        ),
+      );
+    });
+  }
+
+  /** 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();
+    });
+    this.container.remove();
+  }
+}
+
+describe('web scroll-restoration hook', () => {
+  let frames: FrameScheduler;
+  let harness: Harness;
+
+  beforeEach(() => {
+    frames = new FrameScheduler();
+    frames.install();
+    currentRouteKey = `route-${Math.random().toString(36).slice(2)}`;
+    harness = new Harness();
+  });
+
+  afterEach(() => {
+    harness.teardown();
+  });
+
+  it('does not clobber the saved offset when the navigator collapses the screen on blur (bug A)', () => {
+    const node = new FakeScrollNode();
+    node.growTo(6586); // real content
+    harness.focus(node);
+
+    // User scrolls to 3520 — the live scroll listener records it.
+    node.scrollTop = 3520;
+    act(() => {
+      node.emitScroll();
+    });
+
+    // Navigator collapses the hidden screen and forces scrollTop to 0 while the
+    // screen is still technically focused (a stray scroll event fires). This
+    // must NOT be persisted over the good 3520.
+    node.collapseLikeNavigator();
+    act(() => {
+      node.emitScroll();
+    });
+
+    // Blur: cleanup runs and must persist the last GOOD offset, not the 0.
+    harness.blur();
+
+    // Re-show with full content height: restore should reach 3520 in one frame.
+    node.growTo(6586);
+    node.scrollTop = 0;
+    harness.focus(node);
+    act(() => {
+      frames.flushOneFrame();
+    });
+    expect(node.scrollTop).toBe(3520);
+  });
+
+  it('re-applies the offset across frames until the list reaches full height (bug B)', () => {
+    const node = new FakeScrollNode();
+    node.growTo(6586);
+    harness.focus(node);
+    node.scrollTop = 3520;
+    act(() => {
+      node.emitScroll();
+    });
+    harness.blur();
+
+    // 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.focus(node);
+
+    // Frame 1: still collapsed — the write is clamped to 0, loop keeps retrying.
+    act(() => {
+      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(6586);
+    act(() => {
+      frames.flushOneFrame();
+    });
+    expect(node.scrollTop).toBe(3520);
+  });
+
+  it('treats a saved offset of 0 as a no-op (no restore loop scheduled)', () => {
+    const node = new FakeScrollNode();
+    node.growTo(6586);
+    harness.focus(node);
+    // Nothing saved for this fresh route key => read() is 0 => no rAF queued.
+    expect(frames.pending).toBe(0);
+  });
+
+  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();
+    });
+    // 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;
+    act(() => {
+      node.emitScroll();
+    });
+    harness.blur();
+
+    // 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);
+    expect(frames.pending).toBe(0);
+    expect(node.scrollTop).toBe(500);
+  });
+
+  it('stops retrying after the frame cap even if the content never grows', () => {
+    const node = new FakeScrollNode();
+    node.growTo(6586);
+    harness.focus(node);
+    node.scrollTop = 3520;
+    act(() => {
+      node.emitScroll();
+    });
+    harness.blur();
+
+    // Re-show that never reaches full height.
+    node.collapseLikeNavigator();
+    harness.focus(node);
+
+    // 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);
+  });
+});

package/src/scroll/index.web.tsx

@@ -2,18 +2,47 @@
  * Web variant of the scroll-restoration primitive.
  *
  * Mirrors the proven Bluesky pattern (`history.scrollRestoration = 'manual'`
- * plus an in-memory `Map<routeKey, offset>` saved on blur and restored on focus
- * inside a single `requestAnimationFrame`) with one deliberate difference:
- * Bluesky restores the WINDOW scroller, whereas Oxy apps keep multi-column
- * layouts whose feed scrolls an INNER container. So we restore the offset of a
- * caller-registered scrollable (a ref to an element / RN scroll component, or
- * the `'window'` sentinel), keyed by the active navigation route.
+ * plus an in-memory `Map<routeKey, offset>`) with two deliberate differences
+ * forced by Oxy's layouts and the behaviour of the (expo-router-wrapped)
+ * React Navigation web stack:
+ *
+ *  1. Bluesky restores the WINDOW scroller, whereas Oxy apps keep multi-column
+ *     layouts whose feed scrolls an INNER container. So we restore the offset
+ *     of a caller-registered scrollable (a ref to an element / RN scroll
+ *     component, or the `'window'` sentinel), keyed by the active route.
+ *
+ *  2. The web stack HIDES the background screen on push. While
+ *     hidden, the previous screen's scroll container collapses
+ *     (`scrollHeight === clientHeight`) and the navigator forces its
+ *     `scrollTop` to 0. The screen is NOT unmounted, so a virtualized list
+ *     (e.g. FlashList) keeps its rows but re-lays them out over SEVERAL frames
+ *     once the screen is re-shown. Two problems follow, both handled here:
+ *
+ *       (a) A blur-time read of `scrollTop` returns the navigator's forced 0,
+ *           not the user's real offset — saving it would clobber the good
+ *           value. We therefore persist the last offset OBSERVED by the live
+ *           scroll listener, never a fresh read taken at blur time.
+ *
+ *       (b) A single-frame restore writes `scrollTop` while the list is still
+ *           collapsed; the write is clamped to 0 and never re-applied once the
+ *           content grows. We therefore re-apply the target offset across a
+ *           bounded run of animation frames, stopping as soon as the write
+ *           sticks (the content has grown tall enough) or a small frame cap is
+ *           reached.
  *
  * Native bundlers use `./index.ts` (a no-op); web bundlers select this file via
  * the `"browser"` export condition in `package.json`.
+ *
+ * The navigation hooks are imported from `expo-router` (which re-exports
+ * `useFocusEffect` and `useRoute` from its bundled React Navigation core) rather
+ * than from `@react-navigation/native` directly. Every Oxy app uses expo-router
+ * as its router, so it is always a DIRECT, top-level dependency that resolves
+ * cleanly under Bun's isolated linker — whereas `@react-navigation/native` is
+ * only a nested/transitive dependency of expo-router and would fail to resolve
+ * when bundling those apps.
  */
 import { createContext, useCallback, useContext, useMemo, useRef } from 'react';
-import { useFocusEffect, useRoute } from '@react-navigation/native';
+import { useFocusEffect, useRoute } from 'expo-router';
 
 import { createScroller } from './scrollable.web';
 import { ScrollOffsetStore, deriveScrollKey } from './store';
@@ -33,6 +62,25 @@ export type {
 const ScrollOffsetContext = createContext<ScrollOffsetStore | null>(null);
 ScrollOffsetContext.displayName = 'BloomScrollOffsetContext';
 
+/**
+ * Maximum number of animation frames the focus restore will re-apply the saved
+ * offset before giving up. A virtualized list re-lays out its rows over a
+ * handful of frames after its screen is re-shown; ~30 frames (≈0.5s at 60fps)
+ * is comfortably longer than any observed relayout while staying short enough
+ * that the loop never lingers as a perceptible cost. The loop normally exits
+ * far earlier — as soon as the write sticks.
+ */
+const RESTORE_FRAME_CAP = 30;
+
+/**
+ * Tolerance (in CSS pixels) for considering a restore "stuck". After writing
+ * `element.scrollTop = target`, the browser may clamp it to the current
+ * `scrollHeight - clientHeight`; if the resulting offset is within this many
+ * pixels of the target we treat the restore as complete. Sub-pixel rounding and
+ * fractional device-pixel ratios make an exact equality check unreliable.
+ */
+const RESTORE_STICK_TOLERANCE_PX = 2;
+
 /**
  * Switch the browser to manual scroll restoration exactly once per document.
  *
@@ -76,11 +124,15 @@ function useScrollOffsetStore(): ScrollOffsetStore {
  * multiple scrollables).
  *
  * Behaviour (web):
- * - On every scroll while the screen is focused, the current offset is saved.
- * - On focus, the saved offset is applied in a single `requestAnimationFrame`,
- *   giving a remounted list one frame to lay out its content first (no retry
- *   loops, no hide/show tricks).
- * - On blur, the latest offset is captured as a final safety net.
+ * - On every scroll while the screen is focused, the current offset is recorded
+ *   in memory and persisted. This live stream of saves is the source of truth.
+ * - On focus, the saved offset is re-applied across a bounded run of animation
+ *   frames, stopping as soon as the write sticks (the list has re-rendered its
+ *   rows and grown tall enough) or {@link RESTORE_FRAME_CAP} is reached. A
+ *   saved offset of 0 is a no-op (nothing to restore).
+ * - On blur, the LAST OBSERVED offset is persisted as a final safety net — not
+ *   a fresh `scrollTop` read, which the navigator may already have forced to 0
+ *   while collapsing the hidden screen.
  */
 export function useScrollRestoration(
   target: ScrollRestorationTarget,
@@ -104,7 +156,8 @@ export function useScrollRestoration(
 
   useFocusEffect(
     // The effect identity is intentionally stable across renders: it reads all
-    // varying inputs from refs. React Navigation re-runs it on each focus.
+    // varying inputs from refs. expo-router's `useFocusEffect` re-runs it on
+    // each focus.
     useCallback(
       () => {
         const key = scrollKeyRef.current;
@@ -116,27 +169,70 @@ export function useScrollRestoration(
             ? (typeof window !== 'undefined' ? window : null)
             : resolveScrollEventTarget(targetRef.current);
 
+        // The last offset the live scroll listener observed for this focus
+        // session. This — not a blur-time `getOffset()` — is what we persist on
+        // blur, because by blur time the navigator may have collapsed the
+        // hidden screen and forced its `scrollTop` to 0 (bug A). `null` means
+        // the user never scrolled this session, so there is nothing newer to
+        // persist than what the scroll listener already saved live.
+        let lastObservedOffset: number | null = null;
+
         const save = () => {
           const currentKey = scrollKeyRef.current;
-          if (enabledRef.current && currentKey !== null) {
-            store.save(currentKey, scroller.getOffset());
-          }
+          if (!enabledRef.current || currentKey === null) return;
+          const offset = scroller.getOffset();
+          // Ignore a spurious 0 produced by the navigator collapsing a hidden
+          // background screen: while collapsed the container cannot scroll, so
+          // its `scrollTop` is forced to 0. Persisting it would clobber the
+          // good offset recorded by earlier live saves (bug A). A genuine
+          // scroll-to-top keeps the container scrollable and is saved normally.
+          if (offset === 0 && !scroller.canScroll()) return;
+          lastObservedOffset = offset;
+          store.save(currentKey, offset);
         };
 
-        // Restore on the next frame so a freshly remounted list has rendered
-        // its content (and thus reached its full scroll height) before we move.
-        const frame = requestAnimationFrame(() => {
-          scroller.setOffset(store.read(key));
-        });
+        // Restore across a bounded run of frames. A freshly re-shown
+        // virtualized list re-lays out its rows over several frames, so a
+        // single write while it is still collapsed would be clamped to 0 and
+        // never re-applied (bug B). We re-apply each frame until the write
+        // sticks or the frame cap is hit.
+        const targetOffset = store.read(key);
+        let rafId: number | null = null;
+
+        if (targetOffset > 0 && typeof requestAnimationFrame !== 'undefined') {
+          let framesLeft = RESTORE_FRAME_CAP;
+          const applyOffset = () => {
+            rafId = null;
+            scroller.setOffset(targetOffset);
+            framesLeft -= 1;
+            // Stop once the write took effect (content grew tall enough) or we
+            // exhaust the frame budget. `getOffset` re-reads the clamped value.
+            const reached =
+              Math.abs(scroller.getOffset() - targetOffset) <=
+              RESTORE_STICK_TOLERANCE_PX;
+            if (!reached && framesLeft > 0) {
+              rafId = requestAnimationFrame(applyOffset);
+            }
+          };
+          rafId = requestAnimationFrame(applyOffset);
+        }
 
         element?.addEventListener('scroll', save, { passive: true });
 
         return () => {
-          cancelAnimationFrame(frame);
+          if (rafId !== null) cancelAnimationFrame(rafId);
           element?.removeEventListener('scroll', save);
-          // Final capture on blur, covering navigations that don't fire a
-          // trailing scroll event.
-          save();
+          // Final capture on blur: persist the last offset the scroll listener
+          // OBSERVED, never a fresh read (which the navigator may have forced
+          // to 0 while collapsing the hidden screen). When the user never
+          // scrolled this session there is nothing newer to persist than the
+          // live saves already recorded.
+          if (lastObservedOffset !== null) {
+            const currentKey = scrollKeyRef.current;
+            if (enabledRef.current && currentKey !== null) {
+              store.save(currentKey, lastObservedOffset);
+            }
+          }
         };
       },
       [store],

package/src/scroll/scrollable.web.ts

@@ -2,12 +2,24 @@ import type { ScrollableHandle, ScrollRestorationTarget } from './types';
 
 /**
  * A normalized read/write interface over whatever the caller registered, so
- * the hook does not branch on target shape. Both methods are no-ops when the
- * underlying element is not yet (or no longer) attached.
+ * the hook does not branch on target shape. All methods are safe no-ops when
+ * the underlying element is not yet (or no longer) attached.
  */
 export interface ResolvedScroller {
   getOffset: () => number;
   setOffset: (offset: number) => void;
+  /**
+   * Whether the scroll container can currently hold a non-zero offset, i.e.
+   * its content is taller than its viewport (`scrollHeight > clientHeight`).
+   *
+   * React Navigation's web stack collapses a hidden background screen so its
+   * content height drops to the viewport height; while collapsed the container
+   * cannot be scrolled and its `scrollTop` is forced to 0. The hook uses this
+   * to ignore a spurious 0 read coming from a collapsed container rather than
+   * persisting it over a previously-saved good offset. The `'window'` scroller
+   * is never collapsed by the navigator, so it always reports `true`.
+   */
+  canScroll: () => boolean;
 }
 
 function isElement(value: unknown): value is HTMLElement {
@@ -59,6 +71,7 @@ export function createScroller(target: ScrollRestorationTarget): ResolvedScrolle
       setOffset: (offset) => {
         if (typeof window !== 'undefined') window.scrollTo(0, offset);
       },
+      canScroll: () => true,
     };
   }
 
@@ -71,5 +84,9 @@ export function createScroller(target: ScrollRestorationTarget): ResolvedScrolle
       const element = resolveElement(target);
       if (element) element.scrollTop = offset;
     },
+    canScroll: () => {
+      const element = resolveElement(target);
+      return element ? element.scrollHeight > element.clientHeight : false;
+    },
   };
 }