@oxyhq/bloom 0.79.0 → 0.80.0

package/README.md

@@ -45,9 +45,9 @@ import { BloomProvider } from '@oxyhq/bloom/provider';
 </BloomProvider>
 ```
 
-Everything scrollable must be **under** it: on web `useScrollRestoration()` throws
-outside its provider, so a list rendered beside the root (a right rail, an overlay)
-crashes the screen.
+Everything scrollable must be **under** it: `useScrollRestoration()` throws outside
+its provider, so a list rendered beside the root (a right rail, an overlay) crashes
+the screen.
 
 Outlets are **not** included — their position in the tree is a real app decision, and
 a second mount duplicates every surface they render. Mount these yourself, under

package/lib/commonjs/provider/index.js

@@ -8,7 +8,8 @@ var _index = require("../image-resolver/index.js");
 var _useHaptics = require("../hooks/useHaptics.js");
 var _minimizeContext = require("../tab-bar/minimize-context.js");
 var _index2 = require("../theme/index.js");
-var _scrollProvider = require("./scroll-provider");
+var _context = require("../scroll/context.js");
+var _index3 = require("../scroll/expo-router/index.js");
 var _jsxRuntime = require("react/jsx-runtime");
 /**
  * `BloomProvider` — the ONE Bloom root an app mounts.
@@ -30,11 +31,13 @@ var _jsxRuntime = require("react/jsx-runtime");
  * Nesting extra contexts costs nothing at runtime — the win is that scope is no
  * longer a per-app decision.
  *
- * EXPO/EXPO-ROUTER APPS ONLY. The scroll-restoration provider it mounts imports
- * `expo-router` (its web implementation keys offsets on the focused route), so
- * a Vite/SPA consumer that has no expo-router cannot resolve this module. Those
- * apps keep mounting `BloomThemeProvider` (and any other piece they need)
- * directly — that is not a lesser path, just the one without a router.
+ * EXPO/EXPO-ROUTER APPS ONLY, and now for one narrow reason: it binds the
+ * scroll store to the expo-router ADAPTER, which is the only module in the
+ * scroll primitive that imports `expo-router`. The scroll core itself is
+ * router-agnostic, so a Vite/SPA consumer can mount
+ * `<ScrollRestorationProvider adapter={...}>` from `@oxyhq/bloom/scroll` with
+ * an adapter for its own router — alongside `BloomThemeProvider` and whatever
+ * else it needs — rather than going without.
  *
  * NOT included, on purpose — these are OUTLETS, not state, and their placement
  * in the tree is a real app decision (z-order, safe areas, and mounting a
@@ -57,7 +60,8 @@ function BloomProvider({
       value: imageResolver ?? null,
       children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_index2.BloomThemeProvider, {
         ...themeProps,
-        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_scrollProvider.ScrollRestorationProvider, {
+        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_context.ScrollRestorationProvider, {
+          adapter: _index3.expoRouterScrollAdapter,
           children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_useHaptics.BloomHapticsProvider, {
             enabled: haptics,
             children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_minimizeContext.TabBarMinimizeProvider, {

package/lib/commonjs/provider/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_index","require","_useHaptics","_minimizeContext","_index2","_scrollProvider","_jsxRuntime","BloomProvider","children","imageResolver","haptics","themeProps","jsx","ImageResolverProvider","value","BloomThemeProvider","ScrollRestorationProvider","BloomHapticsProvider","enabled","TabBarMinimizeProvider","displayName"],"sourceRoot":"../../../src","sources":["provider/index.tsx"],"mappings":";;;;;;AAkCA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,WAAA,GAAAD,OAAA;AACA,IAAAE,gBAAA,GAAAF,OAAA;AACA,IAAAG,OAAA,GAAAH,OAAA;AACA,IAAAI,eAAA,GAAAJ,OAAA;AAA8D,IAAAK,WAAA,GAAAL,OAAA;AAtC9D;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAqBO,SAASM,aAAaA,CAAC;EAC5BC,QAAQ;EACRC,aAAa;EACbC,OAAO,GAAG,IAAI;EACd,GAAGC;AACe,CAAC,EAAE;EACrB;IAAA;IACE;IACA;IACA,IAAAL,WAAA,CAAAM,GAAA,EAACZ,MAAA,CAAAa,qBAAqB;MAACC,KAAK,EAAEL,aAAa,IAAI,IAAK;MAAAD,QAAA,eAClD,IAAAF,WAAA,CAAAM,GAAA,EAACR,OAAA,CAAAW,kBAAkB;QAAA,GAAKJ,UAAU;QAAAH,QAAA,eAChC,IAAAF,WAAA,CAAAM,GAAA,EAACP,eAAA,CAAAW,yBAAyB;UAAAR,QAAA,eACxB,IAAAF,WAAA,CAAAM,GAAA,EAACV,WAAA,CAAAe,oBAAoB;YAACC,OAAO,EAAER,OAAQ;YAAAF,QAAA,eACrC,IAAAF,WAAA,CAAAM,GAAA,EAACT,gBAAA,CAAAgB,sBAAsB;cAAAX,QAAA,EAAEA;YAAQ,CAAyB;UAAC,CACvC;QAAC,CACE;MAAC,CACV;IAAC,CACA;EAAC;AAE5B;AAEAD,aAAa,CAACa,WAAW,GAAG,eAAe","ignoreList":[]}
+{"version":3,"names":["_index","require","_useHaptics","_minimizeContext","_index2","_context","_index3","_jsxRuntime","BloomProvider","children","imageResolver","haptics","themeProps","jsx","ImageResolverProvider","value","BloomThemeProvider","ScrollRestorationProvider","adapter","expoRouterScrollAdapter","BloomHapticsProvider","enabled","TabBarMinimizeProvider","displayName"],"sourceRoot":"../../../src","sources":["provider/index.tsx"],"mappings":";;;;;;AAoCA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,WAAA,GAAAD,OAAA;AACA,IAAAE,gBAAA,GAAAF,OAAA;AACA,IAAAG,OAAA,GAAAH,OAAA;AACA,IAAAI,QAAA,GAAAJ,OAAA;AACA,IAAAK,OAAA,GAAAL,OAAA;AAAgE,IAAAM,WAAA,GAAAN,OAAA;AAzChE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAsBO,SAASO,aAAaA,CAAC;EAC5BC,QAAQ;EACRC,aAAa;EACbC,OAAO,GAAG,IAAI;EACd,GAAGC;AACe,CAAC,EAAE;EACrB;IAAA;IACE;IACA;IACA,IAAAL,WAAA,CAAAM,GAAA,EAACb,MAAA,CAAAc,qBAAqB;MAACC,KAAK,EAAEL,aAAa,IAAI,IAAK;MAAAD,QAAA,eAClD,IAAAF,WAAA,CAAAM,GAAA,EAACT,OAAA,CAAAY,kBAAkB;QAAA,GAAKJ,UAAU;QAAAH,QAAA,eAChC,IAAAF,WAAA,CAAAM,GAAA,EAACR,QAAA,CAAAY,yBAAyB;UAACC,OAAO,EAAEC,+BAAwB;UAAAV,QAAA,eAC1D,IAAAF,WAAA,CAAAM,GAAA,EAACX,WAAA,CAAAkB,oBAAoB;YAACC,OAAO,EAAEV,OAAQ;YAAAF,QAAA,eACrC,IAAAF,WAAA,CAAAM,GAAA,EAACV,gBAAA,CAAAmB,sBAAsB;cAAAb,QAAA,EAAEA;YAAQ,CAAyB;UAAC,CACvC;QAAC,CACE;MAAC,CACV;IAAC,CACA;EAAC;AAE5B;AAEAD,aAAa,CAACe,WAAW,GAAG,eAAe","ignoreList":[]}

package/lib/commonjs/scroll/context.js

@@ -0,0 +1,96 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ScrollRestorationProvider = ScrollRestorationProvider;
+exports.useScrollRestorationContext = useScrollRestorationContext;
+var _react = require("react");
+var _store = require("./store.js");
+var _jsxRuntime = require("react/jsx-runtime");
+/**
+ * The provider and context both platform barrels share.
+ *
+ * Nothing here is platform-specific: the provider holds an offset store and the
+ * router adapter, and that composition is identical on web and native. Keeping
+ * it in one module also guarantees ONE context identity — a provider mounted
+ * from the native barrel and a hook imported from the web barrel would
+ * otherwise read two different contexts and the hook would throw.
+ */
+
+const ScrollRestorationContext = /*#__PURE__*/(0, _react.createContext)(null);
+ScrollRestorationContext.displayName = 'BloomScrollRestorationContext';
+
+/**
+ * Holds the offset map and the router binding for the subtree. One provider
+ * near the app root is enough; the store lives as long as the provider, so
+ * offsets survive navigating away and back (including browser Back/Forward).
+ */
+function ScrollRestorationProvider({
+  children,
+  adapter
+}) {
+  const store = (0, _react.useMemo)(() => new _store.ScrollOffsetStore(), []);
+  const value = (0, _react.useMemo)(() => ({
+    store,
+    adapter
+  }), [store, adapter]);
+  useManualBrowserScrollRestoration();
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(ScrollRestorationContext.Provider, {
+    value: value,
+    children: children
+  });
+}
+function useScrollRestorationContext() {
+  const value = (0, _react.useContext)(ScrollRestorationContext);
+  if (value === null) {
+    throw new Error('useScrollRestoration must be used within a <ScrollRestorationProvider>.');
+  }
+  return value;
+}
+
+/**
+ * Take over scroll restoration from the browser for as long as this provider is
+ * mounted, and hand it back both on unmount and on `pagehide`.
+ *
+ * The browser's default `'auto'` restoration fights our restore on
+ * Back/Forward, so it has to be turned off — but only while something is
+ * actually going to restore instead. Two moments where that stops being true:
+ *
+ *  - **Unmount.** This used to run at MODULE scope, which meant merely
+ *    importing the module disabled the browser's own restoration. Now that the
+ *    core is importable by apps that mount no provider (and by SSR and Node
+ *    tooling), that would have left those apps with neither restoration. Tying
+ *    the switch to the provider's lifetime makes it describe exactly the period
+ *    during which a replacement exists. The provider mounts at the app root on
+ *    the first commit, which is before any navigation can create a history
+ *    entry, so nothing is lost by not doing it at module scope.
+ *  - **`pagehide`.** The offset map lives in memory only. A reload starts with
+ *    an empty one, and a bfcache restore resumes a document whose provider is
+ *    already mounted and whose focus effects therefore never re-run — so in
+ *    both cases `'manual'` means NOBODY restores. Handing the mode back to the
+ *    browser on the way out lets it do the job we are no longer able to.
+ *    (react-router does exactly this, for the same reason.)
+ *
+ * The feature detect is also the platform test — `history` exists on web and
+ * nowhere else — so this stays one implementation rather than a fork. On React
+ * Native and during SSR it is a no-op.
+ */
+function useManualBrowserScrollRestoration() {
+  (0, _react.useEffect)(() => {
+    if (typeof window === 'undefined' || typeof history === 'undefined' || !('scrollRestoration' in history)) {
+      return undefined;
+    }
+    const previous = history.scrollRestoration;
+    history.scrollRestoration = 'manual';
+    const handBackToBrowser = () => {
+      history.scrollRestoration = 'auto';
+    };
+    window.addEventListener('pagehide', handBackToBrowser);
+    return () => {
+      window.removeEventListener('pagehide', handBackToBrowser);
+      history.scrollRestoration = previous;
+    };
+  }, []);
+}
+//# sourceMappingURL=context.js.map

package/lib/commonjs/scroll/context.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","_store","_jsxRuntime","ScrollRestorationContext","createContext","displayName","ScrollRestorationProvider","children","adapter","store","useMemo","ScrollOffsetStore","value","useManualBrowserScrollRestoration","jsx","Provider","useScrollRestorationContext","useContext","Error","useEffect","window","history","undefined","previous","scrollRestoration","handBackToBrowser","addEventListener","removeEventListener"],"sourceRoot":"../../../src","sources":["scroll/context.tsx"],"mappings":";;;;;;;AASA,IAAAA,MAAA,GAAAC,OAAA;AAEA,IAAAC,MAAA,GAAAD,OAAA;AAA4C,IAAAE,WAAA,GAAAF,OAAA;AAX5C;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAcA,MAAMG,wBAAwB,gBAC5B,IAAAC,oBAAa,EAAuC,IAAI,CAAC;AAC3DD,wBAAwB,CAACE,WAAW,GAAG,+BAA+B;;AAEtE;AACA;AACA;AACA;AACA;AACO,SAASC,yBAAyBA,CAAC;EACxCC,QAAQ;EACRC;AAC8B,CAAC,EAAE;EACjC,MAAMC,KAAK,GAAG,IAAAC,cAAO,EAAC,MAAM,IAAIC,wBAAiB,CAAC,CAAC,EAAE,EAAE,CAAC;EACxD,MAAMC,KAAK,GAAG,IAAAF,cAAO,EAAC,OAAO;IAAED,KAAK;IAAED;EAAQ,CAAC,CAAC,EAAE,CAACC,KAAK,EAAED,OAAO,CAAC,CAAC;EAEnEK,iCAAiC,CAAC,CAAC;EAEnC,oBACE,IAAAX,WAAA,CAAAY,GAAA,EAACX,wBAAwB,CAACY,QAAQ;IAACH,KAAK,EAAEA,KAAM;IAAAL,QAAA,EAC7CA;EAAQ,CACwB,CAAC;AAExC;AAEO,SAASS,2BAA2BA,CAAA,EAAkC;EAC3E,MAAMJ,KAAK,GAAG,IAAAK,iBAAU,EAACd,wBAAwB,CAAC;EAClD,IAAIS,KAAK,KAAK,IAAI,EAAE;IAClB,MAAM,IAAIM,KAAK,CACb,yEACF,CAAC;EACH;EACA,OAAON,KAAK;AACd;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,iCAAiCA,CAAA,EAAS;EACjD,IAAAM,gBAAS,EAAC,MAAM;IACd,IACE,OAAOC,MAAM,KAAK,WAAW,IAC7B,OAAOC,OAAO,KAAK,WAAW,IAC9B,EAAE,mBAAmB,IAAIA,OAAO,CAAC,EACjC;MACA,OAAOC,SAAS;IAClB;IACA,MAAMC,QAAQ,GAAGF,OAAO,CAACG,iBAAiB;IAC1CH,OAAO,CAACG,iBAAiB,GAAG,QAAQ;IAEpC,MAAMC,iBAAiB,GAAGA,CAAA,KAAM;MAC9BJ,OAAO,CAACG,iBAAiB,GAAG,MAAM;IACpC,CAAC;IACDJ,MAAM,CAACM,gBAAgB,CAAC,UAAU,EAAED,iBAAiB,CAAC;IAEtD,OAAO,MAAM;MACXL,MAAM,CAACO,mBAAmB,CAAC,UAAU,EAAEF,iBAAiB,CAAC;MACzDJ,OAAO,CAACG,iBAAiB,GAAGD,QAAQ;IACtC,CAAC;EACH,CAAC,EAAE,EAAE,CAAC;AACR","ignoreList":[]}

package/lib/commonjs/scroll/expo-router/index.js

@@ -0,0 +1,133 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.expoRouterScrollAdapter = void 0;
+var _react = require("react");
+var _expoRouter = require("expo-router");
+/**
+ * The expo-router binding for `@oxyhq/bloom/scroll`.
+ *
+ * This is the only file in the scroll primitive that knows a router exists. It
+ * is separate from the core so a consumer with a different router — or none —
+ * can still use the core with its own adapter; before the split, a module-scope
+ * `expo-router` import made the whole subpath unresolvable for them.
+ *
+ * The navigation hooks come from `expo-router` (which re-exports React
+ * Navigation's) 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.
+ */
+
+/**
+ * Params that describe how a screen was REACHED rather than what it shows, and
+ * so must not contribute to a content id — the same screen showing the same
+ * thing would otherwise get two ids depending on how the user got there.
+ *
+ * - `screen` / `params` are React Navigation's nested-navigator plumbing.
+ *   expo-router strips both wherever it derives a URL from state
+ *   (`global-state/getRouteInfoFromState.js` deletes them before building the
+ *   pathname; `global-state/stateUtils.js` deletes `screen` from a payload;
+ *   `hooks/useSearchParams.js` skips both).
+ * - `initial` is React Navigation's reserved anchor flag, set by expo-router's
+ *   `withAnchor` handling in `global-state/getNavigationAction.js` — which also
+ *   warns if an app supplies it as a real param.
+ */
+const NON_CONTENT_PARAM_KEYS = new Set(['screen', 'params', 'initial']);
+
+/**
+ * expo-router's own internal params all carry this prefix
+ * (`build/navigationParams.js` — `__internal_expo_router_no_animation`,
+ * `__internal__expo_router_is_preview_navigation`, and the two zoom-transition
+ * ids, verified identical in expo-router 56.2.10 and 57.0.9). They are appended
+ * to the params of an ordinary navigation, so matching the prefix rather than
+ * the four literals means a fifth one added upstream cannot silently split one
+ * screen's content id in two.
+ */
+const INTERNAL_PARAM_PREFIX = '__internal';
+
+/**
+ * Depth at which nested param objects stop being described. React Navigation
+ * expects params to be serializable, but nothing enforces it, and a serializer
+ * that a cyclic value can hang is not one to put on a render path. Four levels
+ * is far past anything a URL produces.
+ */
+const MAX_PARAM_DEPTH = 4;
+function serializeValue(value, depth) {
+  if (value === undefined) return '~undefined';
+  if (value === null) return '~null';
+  // JSON.stringify quotes and escapes, so a string can never be confused with
+  // a marker above or with the punctuation of a nested structure below.
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  if (depth >= MAX_PARAM_DEPTH) return '~deep';
+  if (Array.isArray(value)) {
+    return `[${value.map(entry => serializeValue(entry, depth + 1)).join(',')}]`;
+  }
+  if (typeof value === 'object') {
+    const source = value;
+    return `{${Object.keys(source).sort().map(key => `${JSON.stringify(key)}:${serializeValue(source[key], depth + 1)}`).join(',')}}`;
+  }
+  // A function, symbol or bigint reached a screen's params. Nothing about it
+  // identifies content, and it cannot be compared across renders anyway.
+  return '~opaque';
+}
+
+/**
+ * Render a screen's params as a stable string. Keys are SORTED so params that
+ * differ only in insertion order — routinely, since expo-router rebuilds the
+ * object on every navigation — can never produce two ids for one screen.
+ *
+ * The exclusions apply at the top level only, because that is where React
+ * Navigation and expo-router inject theirs; a nested user object keeps every
+ * key it has.
+ */
+function serializeContentParams(params) {
+  if (params === undefined) return '';
+  const source = params;
+  return Object.keys(source).filter(key => !NON_CONTENT_PARAM_KEYS.has(key) && !key.startsWith(INTERNAL_PARAM_PREFIX)).sort().map(key => `${JSON.stringify(key)}:${serializeValue(source[key], 1)}`).join(',');
+}
+
+/**
+ * Identify WHAT the calling screen is showing: its route name plus its params.
+ *
+ * `useRoute()` is the source, and it has to be: it reads the route object of
+ * the nearest screen, so a background screen keeps reporting its own content.
+ * `usePathname()` would not do — it reads the globally focused route, so a
+ * background screen would adopt the foreground one's pathname and save its
+ * offset under a key that is not its own.
+ *
+ * `route.key` is deliberately NOT part of this. An offset belongs to what the
+ * user was looking at, not to the history slot it occupied — see
+ * `deriveScrollKey` for the full reasoning and the trade it makes.
+ *
+ * Params are what separate two screens sharing a route name. That matters most
+ * where expo-router RECYCLES a route object: `layouts/StackClient.js` reuses
+ * the current route — key included — when `NAVIGATE` targets the current route
+ * name and `getSingularId` matches, i.e. when only the query changed. Measured
+ * on 56.2.10 and 57.0.9: `search?q=cats` -> `search?q=dogs` keeps one key and
+ * swaps `params`, so without the params the two searches would share an offset.
+ */
+function useScreenContentId() {
+  const route = (0, _expoRouter.useRoute)();
+  const contentId = `${route.name}?${serializeContentParams(route.params)}`;
+  return (0, _react.useMemo)(() => contentId, [contentId]);
+}
+function useScreenFocusEffect(effect) {
+  (0, _expoRouter.useFocusEffect)(effect);
+}
+
+/**
+ * The adapter to hand `<ScrollRestorationProvider adapter={...}>` in an
+ * expo-router app. A module-level constant, as the adapter contract requires.
+ */
+const expoRouterScrollAdapter = exports.expoRouterScrollAdapter = {
+  useScreenContentId,
+  useScreenFocusEffect
+};
+//# sourceMappingURL=index.js.map

package/lib/commonjs/scroll/expo-router/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","_expoRouter","NON_CONTENT_PARAM_KEYS","Set","INTERNAL_PARAM_PREFIX","MAX_PARAM_DEPTH","serializeValue","value","depth","undefined","JSON","stringify","String","Array","isArray","map","entry","join","source","Object","keys","sort","key","serializeContentParams","params","filter","has","startsWith","useScreenContentId","route","useRoute","contentId","name","useMemo","useScreenFocusEffect","effect","useFocusEffect","expoRouterScrollAdapter","exports"],"sourceRoot":"../../../../src","sources":["scroll/expo-router/index.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/scroll/index.js

@@ -3,37 +3,101 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.ScrollRestorationProvider = ScrollRestorationProvider;
+Object.defineProperty(exports, "ScrollRestorationProvider", {
+  enumerable: true,
+  get: function () {
+    return _context.ScrollRestorationProvider;
+  }
+});
 exports.useScrollRestoration = useScrollRestoration;
+var _react = require("react");
+var _context = require("./context.js");
+var _scrollableNative = require("./scrollable.native.js");
+var _store = require("./store.js");
 /**
- * Native variant of the scroll-restoration primitive — a deliberate no-op.
+ * Native variant of the scroll-restoration primitive.
+ *
+ * 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 — this file
+ * must not interfere with that, and does not: nothing here runs on focus.
  *
- * 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.
+ * What native does not survive is a KEY CHANGE: an in-screen tab or folder swap
+ * that re-keys a list, and a screen that genuinely unmounts and remounts. The
+ * effect below is therefore keyed on the storage key (plus `enabled`) rather
+ * than on focus, which draws exactly that line with no bookkeeping: React
+ * re-runs it when the key changes and leaves it alone when a push/pop merely
+ * re-focuses the same screen showing the same content.
  *
  * Web bundlers select `./index.web` via the `"browser"` export condition in
  * `package.json`; native bundlers fall through to this file.
  */
 
 /**
- * No-op provider. Renders children unchanged — native scroll persistence is
- * handled by the navigator, so no per-route state is kept.
+ * Preserve and restore the scroll offset of `target` across content changes,
+ * keyed by the content its screen is showing plus an optional `options.key`.
+ *
+ * Behaviour (native):
+ * - Offsets are recorded from the returned `onScroll` binding, which the caller
+ *   wires onto the list. There is no other way to observe a list's offset.
+ * - When the storage key changes — a re-keyed list, a remount, or `enabled`
+ *   turning on — the saved offset is applied, or 0 when the key was never seen.
+ * - A push/pop that re-focuses the same screen scrolls nothing. The navigator
+ *   already preserved the position, and re-applying it would at best be a
+ *   no-op and at worst fight a list that has legitimately moved on.
  */
-function ScrollRestorationProvider({
-  children
-}) {
-  return children;
-}
+function useScrollRestoration(target, options) {
+  const {
+    store,
+    adapter
+  } = (0, _context.useScrollRestorationContext)();
+  const contentId = adapter.useScreenContentId();
+  const enabled = options?.enabled ?? true;
+  const scrollKey = (0, _store.deriveScrollKey)(contentId, options?.key);
 
-/**
- * No-op hook. Accepts the same arguments as the web implementation so call
- * sites are identical across platforms.
- */
-function useScrollRestoration(_target, _options) {
-  // Intentionally empty: native-stack already preserves scroll position.
+  // The key the live `onScroll` binding is allowed to record against. It is
+  // assigned by the effect below only AFTER that effect's own write has landed,
+  // and cleared by its cleanup — so the relayout the outgoing content emits
+  // while a new key is already rendered is never attributed to the new key.
+  const recordingKeyRef = (0, _react.useRef)(null);
+  (0, _react.useEffect)(() => {
+    if (!enabled || scrollKey === null) return undefined;
+    const scroller = (0, _scrollableNative.createScroller)(target);
+    let frame = null;
+
+    // Restore and reset are ONE write: a miss reads 0, and 0 is exactly what a
+    // list showing content never seen this session must be sent to rather than
+    // left at the offset its predecessor had.
+    const apply = () => {
+      frame = null;
+      scroller.setOffset(store.read(scrollKey));
+      recordingKeyRef.current = scrollKey;
+    };
+
+    // Defer one frame. This effect fires in the same commit that rendered the
+    // incoming rows, and a list cannot honour an offset before it has laid them
+    // out — the write would be clamped to whatever height it has reached so
+    // far, with no second chance (unlike web, native gets no scroll event to
+    // re-apply from). One frame is all that is needed because `enabled` has
+    // already guaranteed the rows are there; what remains is the layout pass.
+    if (typeof requestAnimationFrame === 'function') {
+      frame = requestAnimationFrame(apply);
+    } else {
+      // No frame scheduler (SSR, or a bare Node import of this barrel).
+      // Applying immediately is still the correct write; only the wait is lost.
+      apply();
+    }
+    return () => {
+      if (frame !== null) cancelAnimationFrame(frame);
+      recordingKeyRef.current = null;
+    };
+  }, [store, scrollKey, enabled, target]);
+  const onScroll = (0, _react.useCallback)(event => {
+    const key = recordingKeyRef.current;
+    if (key === null) return;
+    store.save(key, event.nativeEvent.contentOffset.y);
+  }, [store]);
+  return (0, _react.useMemo)(() => ({
+    onScroll
+  }), [onScroll]);
 }
 //# sourceMappingURL=index.js.map

package/lib/commonjs/scroll/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["ScrollRestorationProvider","children","useScrollRestoration","_target","_options"],"sourceRoot":"../../../src","sources":["scroll/index.ts"],"mappings":";;;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAeA;AACA;AACA;AACA;AACO,SAASA,yBAAyBA,CAAC;EACxCC;AAC8B,CAAC,EAAgB;EAC/C,OAAOA,QAAQ;AACjB;;AAEA;AACA;AACA;AACA;AACO,SAASC,oBAAoBA,CAClCC,OAAgC,EAChCC,QAAsC,EAChC;EACN;AAAA","ignoreList":[]}
+{"version":3,"names":["_react","require","_context","_scrollableNative","_store","useScrollRestoration","target","options","store","adapter","useScrollRestorationContext","contentId","useScreenContentId","enabled","scrollKey","deriveScrollKey","key","recordingKeyRef","useRef","useEffect","undefined","scroller","createScroller","frame","apply","setOffset","read","current","requestAnimationFrame","cancelAnimationFrame","onScroll","useCallback","event","save","nativeEvent","contentOffset","y","useMemo"],"sourceRoot":"../../../src","sources":["scroll/index.ts"],"mappings":";;;;;;;;;;;;AAiBA,IAAAA,MAAA,GAAAC,OAAA;AAEA,IAAAC,QAAA,GAAAD,OAAA;AACA,IAAAE,iBAAA,GAAAF,OAAA;AACA,IAAAG,MAAA,GAAAH,OAAA;AArBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAwBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASI,oBAAoBA,CAClCC,MAA+B,EAC/BC,OAAqC,EACX;EAC1B,MAAM;IAAEC,KAAK;IAAEC;EAAQ,CAAC,GAAG,IAAAC,oCAA2B,EAAC,CAAC;EACxD,MAAMC,SAAS,GAAGF,OAAO,CAACG,kBAAkB,CAAC,CAAC;EAC9C,MAAMC,OAAO,GAAGN,OAAO,EAAEM,OAAO,IAAI,IAAI;EACxC,MAAMC,SAAS,GAAG,IAAAC,sBAAe,EAACJ,SAAS,EAAEJ,OAAO,EAAES,GAAG,CAAC;;EAE1D;EACA;EACA;EACA;EACA,MAAMC,eAAe,GAAG,IAAAC,aAAM,EAAgB,IAAI,CAAC;EAEnD,IAAAC,gBAAS,EAAC,MAAM;IACd,IAAI,CAACN,OAAO,IAAIC,SAAS,KAAK,IAAI,EAAE,OAAOM,SAAS;IAEpD,MAAMC,QAAQ,GAAG,IAAAC,gCAAc,EAAChB,MAAM,CAAC;IACvC,IAAIiB,KAAoB,GAAG,IAAI;;IAE/B;IACA;IACA;IACA,MAAMC,KAAK,GAAGA,CAAA,KAAY;MACxBD,KAAK,GAAG,IAAI;MACZF,QAAQ,CAACI,SAAS,CAACjB,KAAK,CAACkB,IAAI,CAACZ,SAAS,CAAC,CAAC;MACzCG,eAAe,CAACU,OAAO,GAAGb,SAAS;IACrC,CAAC;;IAED;IACA;IACA;IACA;IACA;IACA;IACA,IAAI,OAAOc,qBAAqB,KAAK,UAAU,EAAE;MAC/CL,KAAK,GAAGK,qBAAqB,CAACJ,KAAK,CAAC;IACtC,CAAC,MAAM;MACL;MACA;MACAA,KAAK,CAAC,CAAC;IACT;IAEA,OAAO,MAAM;MACX,IAAID,KAAK,KAAK,IAAI,EAAEM,oBAAoB,CAACN,KAAK,CAAC;MAC/CN,eAAe,CAACU,OAAO,GAAG,IAAI;IAChC,CAAC;EACH,CAAC,EAAE,CAACnB,KAAK,EAAEM,SAAS,EAAED,OAAO,EAAEP,MAAM,CAAC,CAAC;EAEvC,MAAMwB,QAAQ,GAAG,IAAAC,kBAAW,EACzBC,KAAK,IAAK;IACT,MAAMhB,GAAG,GAAGC,eAAe,CAACU,OAAO;IACnC,IAAIX,GAAG,KAAK,IAAI,EAAE;IAClBR,KAAK,CAACyB,IAAI,CAACjB,GAAG,EAAEgB,KAAK,CAACE,WAAW,CAACC,aAAa,CAACC,CAAC,CAAC;EACpD,CAAC,EACD,CAAC5B,KAAK,CACR,CAAC;EAED,OAAO,IAAA6B,cAAO,EAAC,OAAO;IAAEP;EAAS,CAAC,CAAC,EAAE,CAACA,QAAQ,CAAC,CAAC;AAClD","ignoreList":[]}