@oxyhq/bloom 0.6.21 → 0.6.23

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

@@ -0,0 +1,26 @@
+import type { ScrollRestorationProviderProps, ScrollRestorationTarget, UseScrollRestorationOptions } from './types';
+export type { ScrollableHandle, ScrollRestorationProviderProps, ScrollRestorationTarget, UseScrollRestorationOptions, } from './types';
+/**
+ * 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).
+ */
+export declare function ScrollRestorationProvider({ children, }: ScrollRestorationProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * 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).
+ *
+ * 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.
+ */
+export declare function useScrollRestoration(target: ScrollRestorationTarget, options?: UseScrollRestorationOptions): void;
+//# sourceMappingURL=index.web.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../src/scroll/index.web.tsx"],"names":[],"mappings":"AAuCA,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,CAoGN"}

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

@@ -0,0 +1,29 @@
+import type { ScrollRestorationTarget } from './types';
+/**
+ * A normalized read/write interface over whatever the caller registered, so
+ * 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
+ * writes the document scroller; everything else operates on the resolved
+ * element's `scrollTop`.
+ */
+export declare function createScroller(target: ScrollRestorationTarget): ResolvedScroller;
+//# sourceMappingURL=scrollable.web.d.ts.map

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

@@ -0,0 +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;IACpC;;;;;;;;;;OAUG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;CAC1B;AAuCD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,uBAAuB,GAAG,gBAAgB,CAyBhF"}

package/lib/typescript/module/scroll/store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Pure, platform-agnostic core of the scroll-restoration primitive.
+ *
+ * This file deliberately contains NO React and NO DOM/native imports so the
+ * logic can be unit-tested in isolation and shared verbatim by the web and
+ * native barrels. The web barrel drives it with real scroll offsets; the
+ * native barrel never instantiates it (native-stack already restores scroll).
+ */
+/**
+ * Derive the storage key for a scrollable from its owning route key and an
+ * optional caller sub-key.
+ *
+ * - `routeKey` is React Navigation's stable per-route `route.key`.
+ * - `subKey` distinguishes multiple scrollables that share a single route.
+ *
+ * Returns `null` when there is no route key to anchor against (the scrollable
+ * is not inside a navigator), which the caller treats as "do not persist".
+ */
+export declare function deriveScrollKey(routeKey: string | undefined, subKey?: string): string | null;
+/**
+ * In-memory map of `scrollKey -> last-known scroll offset`.
+ *
+ * Mirrors the semantics of Bluesky's `Map<screenKey, scrollY>`: offsets live
+ * only for the lifetime of the document/session. We never persist them — a
+ * full reload should start at the top — and we never auto-evict, because a
+ * route can be revisited via browser Forward/Back long after it blurred.
+ */
+export declare class ScrollOffsetStore {
+    private readonly offsets;
+    /** Persist the offset for a key. A negative offset is clamped to 0. */
+    save(key: string, offset: number): void;
+    /**
+     * Read the saved offset for a key. Returns `0` when nothing was saved, so
+     * callers can restore unconditionally (an unseen list restores to the top).
+     */
+    read(key: string): number;
+    /** Whether an offset was ever saved for this key. */
+    has(key: string): boolean;
+    /** Drop a saved offset (e.g. when a route is permanently removed). */
+    forget(key: string): void;
+    /** Clear every saved offset. Primarily for tests and full resets. */
+    clear(): void;
+    /** Number of distinct keys currently tracked. */
+    get size(): number;
+}
+//# sourceMappingURL=store.d.ts.map

package/lib/typescript/module/scroll/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/scroll/store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CAIf;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD,uEAAuE;IACvE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAIvC;;;OAGG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAIzB,qDAAqD;IACrD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,sEAAsE;IACtE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,qEAAqE;IACrE,KAAK,IAAI,IAAI;IAIb,iDAAiD;IACjD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/lib/typescript/module/scroll/types.d.ts

@@ -0,0 +1,46 @@
+import type { ReactNode, RefObject } from 'react';
+/**
+ * Anything `useScrollRestoration` knows how to read/write a vertical scroll
+ * offset from. The hook accepts a ref to one of these:
+ *
+ * - a React Native `ScrollView` / `FlatList` ref (which on web is backed by a
+ *   DOM node and exposes `getScrollableNode()`),
+ * - a raw DOM element ref (when a component renders its own scroll container),
+ * - the literal `'window'` sentinel, for the rare layout where the list IS the
+ *   window scroller (matches Bluesky's default).
+ *
+ * Native never reads any of these — the native hook is a no-op — so the type is
+ * intentionally permissive rather than coupled to a specific RN class.
+ */
+export interface ScrollableHandle {
+    /** Imperative scroll API exposed by RN scrollables. */
+    scrollTo?: (options: {
+        x?: number;
+        y?: number;
+        animated?: boolean;
+    }) => void;
+    /** Web/RNW path: returns the underlying DOM node. */
+    getScrollableNode?: () => unknown;
+}
+/**
+ * The accepted ref shapes. `'window'` is a sentinel for the document scroller.
+ */
+export type ScrollRestorationTarget = RefObject<ScrollableHandle | null> | RefObject<unknown> | 'window';
+export interface UseScrollRestorationOptions {
+    /**
+     * Sub-key to disambiguate multiple scrollables that live on the same route
+     * (e.g. the tabs of a profile screen). Combined with the active route key to
+     * form the storage key. Omit when a route has a single scrollable.
+     */
+    key?: string;
+    /**
+     * When `false`, the hook is inert (saves and restores are skipped). Useful to
+     * gate restoration behind a feature flag without changing call sites.
+     * Defaults to `true`.
+     */
+    enabled?: boolean;
+}
+export interface ScrollRestorationProviderProps {
+    children: ReactNode;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/module/scroll/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/scroll/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IAC7E,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAClC,SAAS,CAAC,OAAO,CAAC,GAClB,QAAQ,CAAC;AAEb,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,SAAS,CAAC;CACrB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.6.21",
+  "version": "0.6.23",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -535,6 +535,22 @@
         "default": "./lib/commonjs/fonts/index.js"
       }
     },
+    "./scroll": {
+      "react-native": "./src/scroll/index.ts",
+      "browser": {
+        "types": "./lib/typescript/module/scroll/index.web.d.ts",
+        "import": "./lib/module/scroll/index.web.js",
+        "require": "./lib/commonjs/scroll/index.web.js"
+      },
+      "import": {
+        "types": "./lib/typescript/module/scroll/index.d.ts",
+        "default": "./lib/module/scroll/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/scroll/index.d.ts",
+        "default": "./lib/commonjs/scroll/index.js"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -615,6 +631,7 @@
     }
   },
   "devDependencies": {
+    "@react-navigation/native": "^7.0.0",
     "@storybook/addon-docs": "^10",
     "@storybook/react-vite": "^10",
     "@testing-library/react-native": "^13.3.3",
@@ -645,6 +662,7 @@
     "vite": "^7"
   },
   "peerDependencies": {
+    "@react-navigation/native": ">=6.0.0",
     "expo": "*",
     "expo-font": "*",
     "react": ">=18.0.0",
@@ -658,6 +676,9 @@
     "sonner-native": ">=0.17.0"
   },
   "peerDependenciesMeta": {
+    "@react-navigation/native": {
+      "optional": true
+    },
     "expo": {
       "optional": true
     },

package/src/__tests__/scroll-native.test.ts

@@ -0,0 +1,25 @@
+import {
+  ScrollRestorationProvider,
+  useScrollRestoration,
+} from '../scroll/index';
+
+// The native barrel is a deliberate no-op: native-stack already preserves
+// scroll. These tests pin that contract so a future refactor can't silently
+// turn the native path into something that touches the DOM or throws.
+
+describe('native scroll-restoration barrel', () => {
+  it('ScrollRestorationProvider renders its children unchanged', () => {
+    const child = { sentinel: true } as unknown as React.ReactElement;
+    expect(ScrollRestorationProvider({ children: child })).toBe(child);
+  });
+
+  it('useScrollRestoration is a no-op for any target/options', () => {
+    const ref = { current: null };
+    expect(() => useScrollRestoration(ref)).not.toThrow();
+    expect(() => useScrollRestoration('window')).not.toThrow();
+    expect(() =>
+      useScrollRestoration(ref, { key: 'feed', enabled: true }),
+    ).not.toThrow();
+    expect(useScrollRestoration(ref)).toBeUndefined();
+  });
+});

package/src/__tests__/scroll-store.test.ts

@@ -0,0 +1,85 @@
+import { ScrollOffsetStore, deriveScrollKey } from '../scroll/store';
+
+describe('deriveScrollKey', () => {
+  it('returns null when there is no route key', () => {
+    expect(deriveScrollKey(undefined)).toBeNull();
+    expect(deriveScrollKey(undefined, 'feed')).toBeNull();
+  });
+
+  it('returns the route key verbatim when no sub-key is given', () => {
+    expect(deriveScrollKey('Home-abc')).toBe('Home-abc');
+  });
+
+  it('treats an empty sub-key the same as no sub-key', () => {
+    expect(deriveScrollKey('Home-abc', '')).toBe('Home-abc');
+  });
+
+  it('composes route key and sub-key for multiple lists on one route', () => {
+    const a = deriveScrollKey('Profile-xyz', 'posts');
+    const b = deriveScrollKey('Profile-xyz', 'media');
+    expect(a).not.toBe(b);
+    expect(a).toBe('Profile-xyz\0posts');
+  });
+
+  it('does not collide across routes that share a sub-key', () => {
+    expect(deriveScrollKey('A', 'feed')).not.toBe(deriveScrollKey('B', 'feed'));
+  });
+});
+
+describe('ScrollOffsetStore', () => {
+  it('reads 0 for an unseen key so callers can restore unconditionally', () => {
+    const store = new ScrollOffsetStore();
+    expect(store.read('missing')).toBe(0);
+    expect(store.has('missing')).toBe(false);
+  });
+
+  it('saves and reads an offset back', () => {
+    const store = new ScrollOffsetStore();
+    store.save('k', 420);
+    expect(store.read('k')).toBe(420);
+    expect(store.has('k')).toBe(true);
+    expect(store.size).toBe(1);
+  });
+
+  it('keeps offsets independent per key', () => {
+    const store = new ScrollOffsetStore();
+    store.save('a', 100);
+    store.save('b', 250);
+    expect(store.read('a')).toBe(100);
+    expect(store.read('b')).toBe(250);
+    expect(store.size).toBe(2);
+  });
+
+  it('overwrites the offset on subsequent saves', () => {
+    const store = new ScrollOffsetStore();
+    store.save('k', 100);
+    store.save('k', 300);
+    expect(store.read('k')).toBe(300);
+    expect(store.size).toBe(1);
+  });
+
+  it('clamps negative offsets to 0 (e.g. rubber-band overscroll)', () => {
+    const store = new ScrollOffsetStore();
+    store.save('k', -50);
+    expect(store.read('k')).toBe(0);
+  });
+
+  it('forgets a single key', () => {
+    const store = new ScrollOffsetStore();
+    store.save('a', 1);
+    store.save('b', 2);
+    store.forget('a');
+    expect(store.has('a')).toBe(false);
+    expect(store.read('b')).toBe(2);
+    expect(store.size).toBe(1);
+  });
+
+  it('clears every key', () => {
+    const store = new ScrollOffsetStore();
+    store.save('a', 1);
+    store.save('b', 2);
+    store.clear();
+    expect(store.size).toBe(0);
+    expect(store.has('a')).toBe(false);
+  });
+});

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

@@ -0,0 +1,325 @@
+/**
+ * @jest-environment jsdom
+ */
+
+// Exercises the WEB scroll-restoration hook (`scroll/index.web`) against the
+// exact failure mode it was written to survive: React Navigation's 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 `@react-navigation/native` 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;
+
+// ---- React Navigation 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';
+
+jest.mock('@react-navigation/native', () => {
+  const react = jest.requireActual<typeof import('react')>('react');
+  return {
+    useFocusEffect: (effect: () => undefined | (() => void)) => {
+      react.useEffect(effect, [effect]);
+    },
+    useRoute: () => ({ key: currentRouteKey, name: 'Test', params: {} }),
+  };
+});
+
+// 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);
+  });
+});