@oxyhq/bloom 0.78.0 → 0.79.1

package/src/scroll/index.web.tsx

@@ -1,22 +1,22 @@
 /**
  * Web variant of the scroll-restoration primitive.
  *
- * Mirrors the proven Bluesky pattern (`history.scrollRestoration = 'manual'`
- * 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:
+ * Mirrors the proven Bluesky pattern (manual `history.scrollRestoration` plus
+ * an in-memory `Map<key, offset>`) with three deliberate differences forced by
+ * Oxy's layouts and by 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.
+ *     component, or the `'window'` sentinel).
  *
- *  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:
+ *  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
@@ -30,45 +30,44 @@
  *           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`.
+ *  3. A document-scrolled app (one window scroller shared by every route) has
+ *     no per-screen container to reset, so an unrecognised key MUST be written
+ *     to 0 explicitly. Doing nothing leaves the previous screen's offset in
+ *     place and the new screen opens mid-page.
  *
- * 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.
+ * Native bundlers use `./index.ts`; web bundlers select this file via the
+ * `"browser"` export condition in `package.json`.
  */
-import { createContext, useCallback, useContext, useMemo, useRef } from 'react';
-import { useFocusEffect, useRoute } from 'expo-router';
+import { useCallback, useRef } from 'react';
 
+import { useScrollRestorationContext } from './context';
 import { createScroller } from './scrollable.web';
-import { ScrollOffsetStore, deriveScrollKey } from './store';
+import { deriveScrollKey } from './store';
 import type {
-  ScrollRestorationProviderProps,
+  ScrollRestorationBinding,
   ScrollRestorationTarget,
   UseScrollRestorationOptions,
 } from './types';
 
+export { ScrollRestorationProvider } from './context';
+
 export type {
+  ScreenFocusEffect,
   ScrollableHandle,
+  ScrollRestorationBinding,
   ScrollRestorationProviderProps,
   ScrollRestorationTarget,
+  ScrollRouterAdapter,
   UseScrollRestorationOptions,
 } from './types';
 
-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.
+ * Maximum number of animation frames the 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;
 
@@ -82,162 +81,220 @@ const RESTORE_FRAME_CAP = 30;
 const RESTORE_STICK_TOLERANCE_PX = 2;
 
 /**
- * Switch the browser to manual scroll restoration exactly once per document.
- *
- * The browser's default `'auto'` restoration fights our manual restore on
- * Back/Forward navigations. Doing this at module scope (guarded for SSR) means
- * it is set before any provider mounts, matching Bluesky's module-level call.
+ * The web binding is a constant: this platform observes offsets by subscribing
+ * to the resolved DOM node's own `scroll` event, so it needs nothing from the
+ * caller. It is still returned — and still safe to spread onto a list — so a
+ * call site is written once and runs on both platforms.
  */
-if (typeof history !== 'undefined' && 'scrollRestoration' in history) {
-  history.scrollRestoration = 'manual';
-}
+const WEB_BINDING: ScrollRestorationBinding = { onScroll: () => undefined };
 
 /**
- * Holds the per-route offset map for the subtree. One provider near the app
- * root is enough; the store lives for the document's lifetime so offsets
- * survive navigating away and back (including browser Back/Forward).
+ * Events that mean the USER has taken over the scroller, and the restore must
+ * stop trying to put them back.
+ *
+ * The browser's own restoration is specified the same way: HTML §7.4.6.5 has
+ * the UA re-attempt the saved position and "may continue to attempt to do so
+ * periodically, until document's has been scrolled by the user becomes true".
+ * Without this the loop fights anyone who starts scrolling inside the frame
+ * budget, yanking them back once per frame for up to {@link RESTORE_FRAME_CAP}
+ * frames.
+ *
+ * Two designs were rejected, and the reasons are the point:
+ *
+ *  - **"Any `scroll` event aborts"** — the obvious version, and it aborts on the
+ *    FIRST frame every time: `setOffset` is itself a scroll, so the loop would
+ *    cancel on the event its own write produced and no restore would ever
+ *    complete.
+ *  - **"Abort on an offset we did not write"** — tempting because it needs no
+ *    listeners, but a virtualized list inserting rows ABOVE the viewport makes
+ *    the browser's scroll anchoring move `scrollTop` on its own. That is
+ *    precisely the situation the loop exists for, so the unexplained-delta test
+ *    would abort exactly when it must not.
+ *
+ * What is being detected is user INPUT, so this detects user input. `pointerdown`
+ * covers a scrollbar drag and a touch-less press; `keydown` covers arrow/page
+ * keys, and reaches us whenever focus is inside the scroller it would scroll.
  */
-export function ScrollRestorationProvider({
-  children,
-}: ScrollRestorationProviderProps) {
-  const store = useMemo(() => new ScrollOffsetStore(), []);
-  return (
-    <ScrollOffsetContext.Provider value={store}>
-      {children}
-    </ScrollOffsetContext.Provider>
-  );
-}
-
-function useScrollOffsetStore(): ScrollOffsetStore {
-  const store = useContext(ScrollOffsetContext);
-  if (store === null) {
-    throw new Error(
-      'useScrollRestoration must be used within a <ScrollRestorationProvider>.',
-    );
-  }
-  return store;
-}
+const USER_TAKEOVER_EVENTS = ['wheel', 'touchstart', 'pointerdown', 'keydown'];
 
 /**
  * Preserve and restore the scroll offset of `target` across navigation, keyed
- * by the active route (plus an optional `options.key` for routes that host
- * multiple scrollables).
+ * by the content its screen is showing plus an optional `options.key`.
  *
  * Behaviour (web):
  * - 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.
+ *   under the key that was live when the listener was attached. This stream of
+ *   saves is the source of truth.
+ * - On focus — and again whenever the key changes while the screen STAYS
+ *   focused, which is how an in-screen tab or folder swap is seen at all — the
+ *   offset saved for the new key is re-applied across a bounded run of
+ *   animation frames, stopping as soon as the write sticks or
+ *   {@link RESTORE_FRAME_CAP} is reached. Content never seen this session is
+ *   written to 0 once instead; a write to 0 always sticks, so it needs no loop.
+ * - On blur (and on a key change), the LAST OBSERVED offset is persisted under
+ *   the OUTGOING key 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,
   options?: UseScrollRestorationOptions,
-): void {
-  const store = useScrollOffsetStore();
-  const route = useRoute();
-  const subKey = options?.key;
+): ScrollRestorationBinding {
+  const { store, adapter } = useScrollRestorationContext();
+  const contentId = adapter.useScreenContentId();
   const enabled = options?.enabled ?? true;
+  const scrollKey = deriveScrollKey(contentId, options?.key);
 
-  const scrollKey = deriveScrollKey(route.key, subKey);
+  // The key this hook instance has already sent to the top. Writing 0 is a
+  // one-time ARRIVAL action: a later re-run for the SAME key (`enabled` turning
+  // on once the rows exist, a screen regaining focus) must not repeat it,
+  // because by then the user may have scrolled somewhere the hook never got to
+  // record. Restoring twice is harmless; resetting twice is data loss.
+  const resetKeyRef = useRef<string | null>(null);
 
-  // Keep the latest target/enabled/key in refs so the focus effect can read
-  // them without being re-subscribed on every render.
-  const targetRef = useRef(target);
-  targetRef.current = target;
-  const enabledRef = useRef(enabled);
-  enabledRef.current = enabled;
-  const scrollKeyRef = useRef(scrollKey);
-  scrollKeyRef.current = scrollKey;
+  adapter.useScreenFocusEffect(
+    // Every varying input is a dependency rather than a ref read, so the
+    // session below CLOSES OVER the key it belongs to. That is what makes a
+    // key change mid-focus correct in both directions: the outgoing session's
+    // cleanup persists to the old key, and the incoming one restores the new.
+    useCallback(() => {
+      if (!enabled || scrollKey === null) return undefined;
 
-  useFocusEffect(
-    // The effect identity is intentionally stable across renders: it reads all
-    // varying inputs from refs. expo-router's `useFocusEffect` re-runs it on
-    // each focus.
-    useCallback(
-      () => {
-        const key = scrollKeyRef.current;
-        if (!enabledRef.current || key === null) return undefined;
+      const scroller = createScroller(target);
+      const element =
+        target === 'window'
+          ? typeof window === 'undefined'
+            ? null
+            : window
+          : resolveScrollEventTarget(target);
 
-        const scroller = createScroller(targetRef.current);
-        const element =
-          targetRef.current === 'window'
-            ? (typeof window !== 'undefined' ? window : null)
-            : resolveScrollEventTarget(targetRef.current);
+      // The last offset the live scroll listener observed for this session.
+      // This — not a cleanup-time `getOffset()` — is what we persist at the
+      // end, because by then the navigator may have collapsed the hidden
+      // screen and forced its `scrollTop` to 0 (problem 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;
 
-        // 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;
+      // 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.
+      let echoOffset: number | null = null;
 
-        const save = () => {
-          const currentKey = scrollKeyRef.current;
-          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);
-        };
+      const save = () => {
+        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 (problem A). A genuine
+        // scroll-to-top keeps the container scrollable and is saved normally.
+        if (offset === 0 && !scroller.canScroll()) return;
+        if (offset === echoOffset) {
+          // Our own write coming back. Consume the arming so a real scroll to
+          // the same offset later is saved normally.
+          echoOffset = null;
+          return;
+        }
+        echoOffset = null;
+        lastObservedOffset = offset;
+        store.save(scrollKey, offset);
+      };
 
-        // 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;
+      // Restore and reset are ONE write. A miss reads 0, and 0 is exactly what
+      // an unseen screen must be written to — left alone it would show the
+      // previous screen's offset, since a document-scrolled app shares one
+      // scroller across every route.
+      const targetOffset = store.read(scrollKey);
 
-        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);
-        }
+      // They remain two DECISIONS, though, and `read` cannot tell them apart:
+      // a key never seen and a key deliberately saved at the top both read 0.
+      // Only the first is a RESET, and a reset is a one-time ARRIVAL action
+      // gated on `resetKeyRef` — repeating it on a later re-run for the same
+      // key would send a user who has since scrolled back to the top, and the
+      // hook was inert while they did it so there is nothing to restore them
+      // to afterwards. A 0 the user deliberately saved is theirs, and always
+      // re-applies. `has` is the only thing that answers this.
+      const isReset = !store.has(scrollKey);
+      const alreadyReset = isReset && resetKeyRef.current === scrollKey;
+      if (isReset) resetKeyRef.current = scrollKey;
+
+      let rafId: number | null = null;
 
-        element?.addEventListener('scroll', save, { passive: true });
+      const stopRestore = () => {
+        if (rafId === null) return;
+        cancelAnimationFrame(rafId);
+        rafId = null;
+      };
 
-        return () => {
-          if (rafId !== null) cancelAnimationFrame(rafId);
-          element?.removeEventListener('scroll', 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);
-            }
+      if (alreadyReset) {
+        // Nothing to write: this content has already been sent to the top once
+        // and the user is wherever they have moved to since.
+      } else if (targetOffset === 0) {
+        // A write to 0 is never clamped away, so it needs no re-apply loop.
+        echoOffset = 0;
+        scroller.setOffset(0);
+      } else if (typeof requestAnimationFrame !== 'undefined') {
+        // Re-apply 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 (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.
+        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);
           }
         };
-      },
-      [store],
-    ),
+        rafId = requestAnimationFrame(applyOffset);
+        // Only while a loop is actually in flight — the reset path has nothing
+        // to abort, and the listeners would be idle on every screen.
+        for (const type of USER_TAKEOVER_EVENTS) {
+          element?.addEventListener(type, stopRestore, { passive: true });
+        }
+      }
+
+      element?.addEventListener('scroll', save, { passive: true });
+
+      return () => {
+        stopRestore();
+        element?.removeEventListener('scroll', save);
+        // Removing a listener that was never added is a no-op, so this needs no
+        // flag tracking whether the loop branch ran.
+        for (const type of USER_TAKEOVER_EVENTS) {
+          element?.removeEventListener(type, stopRestore);
+        }
+        // Final capture: 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 than the live saves already recorded.
+        if (lastObservedOffset !== null) {
+          store.save(scrollKey, lastObservedOffset);
+        }
+      };
+    }, [store, scrollKey, enabled, target]),
   );
+
+  return WEB_BINDING;
 }
 
 /**
@@ -247,7 +304,7 @@ export function useScrollRestoration(
 function resolveScrollEventTarget(
   target: Exclude<ScrollRestorationTarget, 'window'>,
 ): EventTarget | null {
-  const current = (target as { current: unknown }).current;
+  const current = target.current;
   if (current == null) return null;
   if (typeof EventTarget !== 'undefined' && current instanceof EventTarget) {
     return current;

package/src/scroll/scrollable.native.ts

@@ -0,0 +1,64 @@
+import type { ScrollableHandle, ScrollRestorationTarget } from './types';
+
+/**
+ * The write half of a scrollable, on native. There is no read half: native
+ * offers no way to sample a list's offset from outside it, so offsets arrive
+ * through the `onScroll` binding the hook returns instead.
+ */
+export interface NativeScroller {
+  setOffset: (offset: number) => void;
+}
+
+function hasScrollToOffset(
+  value: unknown,
+): value is Required<Pick<ScrollableHandle, 'scrollToOffset'>> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as ScrollableHandle).scrollToOffset === 'function'
+  );
+}
+
+function hasScrollTo(
+  value: unknown,
+): value is Required<Pick<ScrollableHandle, 'scrollTo'>> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as ScrollableHandle).scrollTo === 'function'
+  );
+}
+
+/**
+ * Build a {@link NativeScroller} for a target.
+ *
+ * `scrollToOffset` (`FlatList`, `FlashList`) is preferred over `scrollTo`
+ * (`ScrollView`) because a list exposes both shapes on some versions and only
+ * the former accounts for the list's own header. The `'window'` sentinel has no
+ * native meaning — there is no document scroller — so it resolves to a no-op
+ * rather than an error: a call site shared with web legitimately passes it.
+ *
+ * The handle is re-resolved on every write; it is never cached, because a ref
+ * can be swapped or detached between the schedule and the write.
+ */
+export function createScroller(
+  target: ScrollRestorationTarget,
+): NativeScroller {
+  if (target === 'window') {
+    return { setOffset: () => undefined };
+  }
+
+  return {
+    setOffset: (offset) => {
+      const current = target.current;
+      if (current == null) return;
+      if (hasScrollToOffset(current)) {
+        current.scrollToOffset({ offset, animated: false });
+        return;
+      }
+      if (hasScrollTo(current)) {
+        current.scrollTo({ y: offset, animated: false });
+      }
+    },
+  };
+}