@oxyhq/bloom 0.6.21 → 0.6.22

package/lib/module/scroll/store.js

@@ -0,0 +1,84 @@
+"use strict";
+
+/**
+ * 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).
+ */
+
+/**
+ * Separator between the navigation route key and an optional caller-supplied
+ * sub-key. A route may host more than one independently-scrolling list (e.g.
+ * a tabbed profile screen), so each list contributes its own sub-key.
+ *
+ * `\0` (NUL) can never appear in a React Navigation route key or in a
+ * developer-authored sub-key, so it is collision-free as a delimiter. It is
+ * written as an escape sequence (not a literal byte) so the source stays
+ * text-diffable.
+ */
+const COMPOSITE_KEY_SEPARATOR = '\0';
+
+/**
+ * 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 function deriveScrollKey(routeKey, subKey) {
+  if (!routeKey) return null;
+  if (subKey === undefined || subKey === '') return routeKey;
+  return `${routeKey}${COMPOSITE_KEY_SEPARATOR}${subKey}`;
+}
+
+/**
+ * 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 class ScrollOffsetStore {
+  offsets = new Map();
+
+  /** Persist the offset for a key. A negative offset is clamped to 0. */
+  save(key, offset) {
+    this.offsets.set(key, offset > 0 ? offset : 0);
+  }
+
+  /**
+   * 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) {
+    return this.offsets.get(key) ?? 0;
+  }
+
+  /** Whether an offset was ever saved for this key. */
+  has(key) {
+    return this.offsets.has(key);
+  }
+
+  /** Drop a saved offset (e.g. when a route is permanently removed). */
+  forget(key) {
+    this.offsets.delete(key);
+  }
+
+  /** Clear every saved offset. Primarily for tests and full resets. */
+  clear() {
+    this.offsets.clear();
+  }
+
+  /** Number of distinct keys currently tracked. */
+  get size() {
+    return this.offsets.size;
+  }
+}
+//# sourceMappingURL=store.js.map

package/lib/module/scroll/store.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["COMPOSITE_KEY_SEPARATOR","deriveScrollKey","routeKey","subKey","undefined","ScrollOffsetStore","offsets","Map","save","key","offset","set","read","get","has","forget","delete","clear","size"],"sourceRoot":"../../../src","sources":["scroll/store.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMA,uBAAuB,GAAG,IAAI;;AAEpC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,eAAeA,CAC7BC,QAA4B,EAC5BC,MAAe,EACA;EACf,IAAI,CAACD,QAAQ,EAAE,OAAO,IAAI;EAC1B,IAAIC,MAAM,KAAKC,SAAS,IAAID,MAAM,KAAK,EAAE,EAAE,OAAOD,QAAQ;EAC1D,OAAO,GAAGA,QAAQ,GAAGF,uBAAuB,GAAGG,MAAM,EAAE;AACzD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAME,iBAAiB,CAAC;EACZC,OAAO,GAAG,IAAIC,GAAG,CAAiB,CAAC;;EAEpD;EACAC,IAAIA,CAACC,GAAW,EAAEC,MAAc,EAAQ;IACtC,IAAI,CAACJ,OAAO,CAACK,GAAG,CAACF,GAAG,EAAEC,MAAM,GAAG,CAAC,GAAGA,MAAM,GAAG,CAAC,CAAC;EAChD;;EAEA;AACF;AACA;AACA;EACEE,IAAIA,CAACH,GAAW,EAAU;IACxB,OAAO,IAAI,CAACH,OAAO,CAACO,GAAG,CAACJ,GAAG,CAAC,IAAI,CAAC;EACnC;;EAEA;EACAK,GAAGA,CAACL,GAAW,EAAW;IACxB,OAAO,IAAI,CAACH,OAAO,CAACQ,GAAG,CAACL,GAAG,CAAC;EAC9B;;EAEA;EACAM,MAAMA,CAACN,GAAW,EAAQ;IACxB,IAAI,CAACH,OAAO,CAACU,MAAM,CAACP,GAAG,CAAC;EAC1B;;EAEA;EACAQ,KAAKA,CAAA,EAAS;IACZ,IAAI,CAACX,OAAO,CAACW,KAAK,CAAC,CAAC;EACtB;;EAEA;EACA,IAAIC,IAAIA,CAAA,EAAW;IACjB,OAAO,IAAI,CAACZ,OAAO,CAACY,IAAI;EAC1B;AACF","ignoreList":[]}

package/lib/module/scroll/types.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=types.js.map

package/lib/module/scroll/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["scroll/types.ts"],"mappings":"","ignoreList":[]}

package/lib/typescript/commonjs/scroll/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Native variant of the scroll-restoration primitive — a deliberate no-op.
+ *
+ * React Navigation's native-stack keeps every screen mounted while it is in the
+ * stack, so a list's scroll position survives a push/pop for free. There is
+ * nothing to save or restore. We still ship the full API surface (provider +
+ * hook) so consumers write one set of call sites that compile and run on every
+ * platform; on native the provider just renders its children and the hook does
+ * nothing.
+ *
+ * Web bundlers select `./index.web` via the `"browser"` export condition in
+ * `package.json`; native bundlers fall through to this file.
+ */
+import type { ReactElement } from 'react';
+import type { ScrollRestorationProviderProps, ScrollRestorationTarget, UseScrollRestorationOptions } from './types';
+export type { ScrollableHandle, ScrollRestorationProviderProps, ScrollRestorationTarget, UseScrollRestorationOptions, } from './types';
+/**
+ * No-op provider. Renders children unchanged — native scroll persistence is
+ * handled by the navigator, so no per-route state is kept.
+ */
+export declare function ScrollRestorationProvider({ children, }: ScrollRestorationProviderProps): ReactElement;
+/**
+ * No-op hook. Accepts the same arguments as the web implementation so call
+ * sites are identical across platforms.
+ */
+export declare function useScrollRestoration(_target: ScrollRestorationTarget, _options?: UseScrollRestorationOptions): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/commonjs/scroll/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/scroll/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC1C,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;AAEjB;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,QAAQ,GACT,EAAE,8BAA8B,GAAG,YAAY,CAE/C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,uBAAuB,EAChC,QAAQ,CAAC,EAAE,2BAA2B,GACrC,IAAI,CAEN"}

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

@@ -0,0 +1,22 @@
+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 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.
+ */
+export declare function useScrollRestoration(target: ScrollRestorationTarget, options?: UseScrollRestorationOptions): void;
+//# sourceMappingURL=index.web.d.ts.map

package/lib/typescript/commonjs/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":"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"}

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

@@ -0,0 +1,17 @@
+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.
+ */
+export interface ResolvedScroller {
+    getOffset: () => number;
+    setOffset: (offset: number) => void;
+}
+/**
+ * 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/commonjs/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;CACrC;AAuCD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,uBAAuB,GAAG,gBAAgB,CAoBhF"}

package/lib/typescript/commonjs/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/commonjs/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/commonjs/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/commonjs/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/lib/typescript/module/scroll/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Native variant of the scroll-restoration primitive — a deliberate no-op.
+ *
+ * React Navigation's native-stack keeps every screen mounted while it is in the
+ * stack, so a list's scroll position survives a push/pop for free. There is
+ * nothing to save or restore. We still ship the full API surface (provider +
+ * hook) so consumers write one set of call sites that compile and run on every
+ * platform; on native the provider just renders its children and the hook does
+ * nothing.
+ *
+ * Web bundlers select `./index.web` via the `"browser"` export condition in
+ * `package.json`; native bundlers fall through to this file.
+ */
+import type { ReactElement } from 'react';
+import type { ScrollRestorationProviderProps, ScrollRestorationTarget, UseScrollRestorationOptions } from './types';
+export type { ScrollableHandle, ScrollRestorationProviderProps, ScrollRestorationTarget, UseScrollRestorationOptions, } from './types';
+/**
+ * No-op provider. Renders children unchanged — native scroll persistence is
+ * handled by the navigator, so no per-route state is kept.
+ */
+export declare function ScrollRestorationProvider({ children, }: ScrollRestorationProviderProps): ReactElement;
+/**
+ * No-op hook. Accepts the same arguments as the web implementation so call
+ * sites are identical across platforms.
+ */
+export declare function useScrollRestoration(_target: ScrollRestorationTarget, _options?: UseScrollRestorationOptions): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/scroll/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC1C,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;AAEjB;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,QAAQ,GACT,EAAE,8BAA8B,GAAG,YAAY,CAE/C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,uBAAuB,EAChC,QAAQ,CAAC,EAAE,2BAA2B,GACrC,IAAI,CAEN"}

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

@@ -0,0 +1,22 @@
+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 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.
+ */
+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":"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"}

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

@@ -0,0 +1,17 @@
+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.
+ */
+export interface ResolvedScroller {
+    getOffset: () => number;
+    setOffset: (offset: number) => void;
+}
+/**
+ * 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;CACrC;AAuCD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,uBAAuB,GAAG,gBAAgB,CAoBhF"}

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.22",
   "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);
+  });
+});