@oxyhq/bloom 0.79.1 → 0.80.0

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

@@ -177,12 +177,23 @@ 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, subKey, enabled, onBinding }: ScreenProps): ReactNode {
+function Screen({
+  node,
+  subKey,
+  enabled,
+  windowTarget,
+  onBinding,
+}: ScreenProps): ReactNode {
   const ref = useRef(makeHandle(node));
-  const binding = useScrollRestoration(ref, { key: subKey, enabled });
+  const binding = useScrollRestoration(windowTarget ? 'window' : ref, {
+    key: subKey,
+    enabled,
+  });
   onBinding?.(binding);
   return null;
 }
@@ -675,6 +686,248 @@ describe('web scroll-restoration hook', () => {
     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();
+    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);
+
+    // 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[] = [];

package/src/scroll/index.web.tsx

@@ -176,23 +176,55 @@ export function useScrollRestoration(
       // than what the scroll listener already saved live.
       let lastObservedOffset: number | null = null;
 
-      // The 0 WE wrote, which a real browser dispatches back as a `scroll`
-      // event (jsdom does not, so the test for this emits it explicitly).
-      // Persisting it would record an offset the user never chose, under a key
-      // another LIVE screen may share — the two-live-entries trade content
-      // keying makes (see `deriveScrollKey`) means a sibling showing the same
-      // content can save a real offset between our write and its echo, and the
-      // echo would clobber it.
+      // The offset WE last wrote, which a real browser dispatches back as a
+      // `scroll` event (jsdom does not, so the tests for this emit it
+      // explicitly). Both writers arm it: the reset, and every frame of the
+      // restore loop. Persisting either records an offset the user never
+      // chose — the reset's 0 under a key another LIVE screen may share (the
+      // two-live-entries trade content keying makes, see `deriveScrollKey`),
+      // and the loop's intermediate value as a PARTIAL that outlives an
+      // interrupted restore.
+      //
+      // A `restoring` FLAG covering the loop's duration is the obvious
+      // alternative and is wrong. It could only be cleared by a takeover
+      // event, so a session whose scroll came from a source that fires none —
+      // `scrollIntoView` from another component, a focus-driven scroll — would
+      // suppress saves indefinitely and never record the user's position at
+      // all: an unbounded corruption traded for a bounded one. Arming a VALUE
+      // is bounded to one event per write and covers every way the loop can
+      // end (stuck, capped, aborted), because each frame re-arms.
       let echoOffset: number | null = null;
 
+      // The largest offset reachable when we last PERSISTED one. A browser
+      // clamp is recognised against this rather than against the previous
+      // OBSERVATION, and that distinction is the whole mechanism: Chrome
+      // dispatches TWO `scroll` events for one clamp, so an
+      // observation-relative test sees the shrink on the first and nothing on
+      // the second, which then saves the clamped value anyway. Measured.
+      let maxOffsetAtLastSave = scroller.getMaxOffset();
+
       const save = () => {
         const offset = scroller.getOffset();
+        const maxOffset = scroller.getMaxOffset();
         // 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 (problem A). A genuine
         // scroll-to-top keeps the container scrollable and is saved normally.
-        if (offset === 0 && !scroller.canScroll()) return;
+        if (offset === 0 && maxOffset <= 0) return;
+        // A partial clamp: the reachable range SHRANK and the offset is sitting
+        // exactly at the new bottom. That is what the browser does to a tab
+        // whose document has been taken over by a shorter sibling — the two
+        // together are a signature a genuine scroll does not have, because
+        // reaching the bottom on your own does not shrink the page in the same
+        // breath. Suppressing keeps the pre-clamp offset, which on return
+        // simply clamps to the same place if the content really did shrink.
+        if (
+          maxOffset < maxOffsetAtLastSave &&
+          Math.abs(offset - maxOffset) <= RESTORE_STICK_TOLERANCE_PX
+        ) {
+          return;
+        }
         if (offset === echoOffset) {
           // Our own write coming back. Consume the arming so a real scroll to
           // the same offset later is saved normally.
@@ -201,6 +233,7 @@ export function useScrollRestoration(
         }
         echoOffset = null;
         lastObservedOffset = offset;
+        maxOffsetAtLastSave = maxOffset;
         store.save(scrollKey, offset);
       };
 
@@ -243,24 +276,27 @@ export function useScrollRestoration(
         // single write while it is still collapsed would be clamped to 0 and
         // never re-applied (problem B).
         //
-        // KNOWN PROPERTY, not a bug: each of these writes echoes back as a
-        // `scroll` event and IS persisted (only the reset arms `echoOffset`,
-        // and `canScroll()` is always true for the `'window'` sentinel so the
-        // collapsed-container guard never fires there). A loop that reaches
-        // the target self-heals on its last echo. A loop that exhausts the cap
-        // leaves the CLAMPED offset stored — which is the right thing to
-        // remember when the content genuinely shrank, since that is as far as
-        // the user can now scroll.
+        // Every write the loop makes is suppressed from the save path (see
+        // `echoOffset` below), so an interrupted restore leaves the ORIGINAL
+        // target stored rather than a partial. Nothing is lost on the success
+        // path: `targetOffset` came out of the store, so persisting it again
+        // would write back the same number.
         let framesLeft = RESTORE_FRAME_CAP;
         const applyOffset = () => {
           rafId = null;
           scroller.setOffset(targetOffset);
           framesLeft -= 1;
+          // `getOffset` re-reads the value the browser actually took, which is
+          // clamped to the content height it has reached so far. Arm it as the
+          // echo to swallow: this write is about to come back as a `scroll`
+          // event, and persisting a PARTIAL offset we wrote ourselves is how a
+          // restore that is aborted or capped corrupts the stored position.
+          const landed = scroller.getOffset();
+          echoOffset = landed;
           // Stop once the write took effect (content grew tall enough) or we
-          // exhaust the frame budget. `getOffset` re-reads the clamped value.
+          // exhaust the frame budget.
           const reached =
-            Math.abs(scroller.getOffset() - targetOffset) <=
-            RESTORE_STICK_TOLERANCE_PX;
+            Math.abs(landed - targetOffset) <= RESTORE_STICK_TOLERANCE_PX;
           if (!reached && framesLeft > 0) {
             rafId = requestAnimationFrame(applyOffset);
           }

package/src/scroll/scrollable.web.ts

@@ -9,17 +9,30 @@ 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`).
+   * The largest offset the container can currently hold — `scrollHeight -
+   * clientHeight`, clamped at 0. Answers two questions the save path needs:
+   * whether a 0 read is real (`maxOffset > 0`) and whether an offset is sitting
+   * exactly at the bottom, which is the signature of a browser clamp.
    *
    * 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`.
+   * persisting it over a previously-saved good offset.
+   *
+   * The DOCUMENT collapses the same way, so the `'window'` sentinel answers the
+   * same question honestly rather than hardcoding `true`. It used to, on the
+   * premise that the navigator never collapses the document — false under a
+   * tabbed navigator, where every tab stays MOUNTED and non-focused ones are
+   * `display: none` (expo-router's `ui/TabSlot`, and react-native-screens' web
+   * `Screen` at `activityState === 0`). Measured in Chrome 150: switching from
+   * a tall tab to a short one drops `documentElement.scrollHeight` from 8040 to
+   * the 800px viewport, forces `scrollY` to 0 and dispatches two `scroll`
+   * events — which the outgoing tab's still-attached listener would otherwise
+   * persist as 0 over its real offset, because blur is emitted from an effect
+   * that has not run yet.
    */
-  canScroll: () => boolean;
+  getMaxOffset: () => number;
 }
 
 function isElement(value: unknown): value is HTMLElement {
@@ -71,7 +84,15 @@ export function createScroller(target: ScrollRestorationTarget): ResolvedScrolle
       setOffset: (offset) => {
         if (typeof window !== 'undefined') window.scrollTo(0, offset);
       },
-      canScroll: () => true,
+      getMaxOffset: () => {
+        if (typeof window === 'undefined' || typeof document === 'undefined') {
+          return 0;
+        }
+        return Math.max(
+          0,
+          document.documentElement.scrollHeight - window.innerHeight,
+        );
+      },
     };
   }
 
@@ -84,9 +105,10 @@ export function createScroller(target: ScrollRestorationTarget): ResolvedScrolle
       const element = resolveElement(target);
       if (element) element.scrollTop = offset;
     },
-    canScroll: () => {
+    getMaxOffset: () => {
       const element = resolveElement(target);
-      return element ? element.scrollHeight > element.clientHeight : false;
+      if (!element) return 0;
+      return Math.max(0, element.scrollHeight - element.clientHeight);
     },
   };
 }