@oxyhq/bloom 0.55.0 → 0.56.0

package/README.md

@@ -24,9 +24,40 @@ Also required:
 
 ## Usage
 
+### App root
+
+Mount `BloomProvider` once, at the very top of the app. It composes every piece of
+app-wide Bloom state — theme, haptics, image resolution, scroll restoration and the
+tab-bar minimize progress — so none of them can end up at the wrong depth. It takes
+all of `BloomThemeProvider`'s props plus `imageResolver` and `haptics`.
+
+```tsx
+import { BloomProvider } from '@oxyhq/bloom/provider';
+
+<BloomProvider
+  defaultMode="system"
+  defaultColorPreset="blue"
+  persistKey="app.theme"
+  storage={storage}
+  imageResolver={(id, variant) => oxyServices.getFileDownloadUrl(id, variant)}
+>
+  <App />
+</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.
+
+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
+`BloomProvider`: `<ToastOutlet>`, `<Portal.Provider>`/`<Portal.Outlet>`,
+`<SurfaceHost>`, `<BloomDialogProvider>`, `<AlertDialogHost>`.
+
 ### Theme
 
-Wrap your app with `BloomThemeProvider`. It accepts controlled `mode` and `colorPreset` props — persist them however you like (AsyncStorage, Zustand, etc.).
+`BloomProvider` already mounts `BloomThemeProvider`; mount it directly only when you
+need a nested/scoped theme. It accepts controlled `mode` and `colorPreset` props — persist them however you like (AsyncStorage, Zustand, etc.).
 
 ```tsx
 import { BloomThemeProvider } from '@oxyhq/bloom/theme';

package/lib/commonjs/provider/index.js

@@ -0,0 +1,67 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.BloomProvider = BloomProvider;
+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 _jsxRuntime = require("react/jsx-runtime");
+/**
+ * `BloomProvider` — the ONE Bloom root an app mounts.
+ *
+ * Bloom's app-wide state used to be a handful of separate providers that every
+ * consumer wired by hand (theme, haptics, image resolution, scroll restoration,
+ * tab-bar minimize progress). Mounting them separately means each one can end
+ * up at a different depth, and a provider mounted too low fails in ways that
+ * are hard to trace:
+ *
+ *   - `useScrollRestoration()` THROWS on web outside `ScrollRestorationProvider`,
+ *     so any scrollable rendered beside the provider (a right rail, an overlay)
+ *     crashes the screen.
+ *   - `useMinimizeState()` silently hands each caller a private fallback, so a
+ *     tab bar below the provider just never minimizes — no error anywhere.
+ *
+ * Mounting this single provider at the app root makes both classes of mistake
+ * impossible: everything Bloom renders is under all of them, at the same depth.
+ * Nesting extra contexts costs nothing at runtime — the win is that scope is no
+ * longer a per-app decision.
+ *
+ * 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
+ * second one duplicates every surface it renders):
+ * `<ToastOutlet>`, `<Portal.Provider>`/`<Portal.Outlet>`, `<SurfaceHost>`,
+ * `<BloomDialogProvider>`, `<AlertDialogHost>`.
+ */
+
+function BloomProvider({
+  children,
+  imageResolver,
+  haptics = true,
+  ...themeProps
+}) {
+  return (
+    /*#__PURE__*/
+    // `value` is passed unconditionally (null when unset) so toggling a resolver
+    // never changes the tree shape and remounts everything below it.
+    (0, _jsxRuntime.jsx)(_index.ImageResolverProvider, {
+      value: imageResolver ?? null,
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_index2.BloomThemeProvider, {
+        ...themeProps,
+        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_scrollProvider.ScrollRestorationProvider, {
+          children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_useHaptics.BloomHapticsProvider, {
+            enabled: haptics,
+            children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_minimizeContext.TabBarMinimizeProvider, {
+              children: children
+            })
+          })
+        })
+      })
+    })
+  );
+}
+BloomProvider.displayName = 'BloomProvider';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +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":";;;;;;AA4BA,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;AAhC9D;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":[]}

package/lib/commonjs/provider/scroll-provider.js

@@ -0,0 +1,13 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "ScrollRestorationProvider", {
+  enumerable: true,
+  get: function () {
+    return _index.ScrollRestorationProvider;
+  }
+});
+var _index = require("../scroll/index.js");
+//# sourceMappingURL=scroll-provider.js.map

package/lib/commonjs/provider/scroll-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_index","require"],"sourceRoot":"../../../src","sources":["provider/scroll-provider.ts"],"mappings":";;;;;;;;;;;AAYA,IAAAA,MAAA,GAAAC,OAAA","ignoreList":[]}

package/lib/commonjs/provider/scroll-provider.web.js

@@ -0,0 +1,13 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "ScrollRestorationProvider", {
+  enumerable: true,
+  get: function () {
+    return _indexWeb.ScrollRestorationProvider;
+  }
+});
+var _indexWeb = require("../scroll/index.web.js");
+//# sourceMappingURL=scroll-provider.web.js.map

package/lib/commonjs/provider/scroll-provider.web.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_indexWeb","require"],"sourceRoot":"../../../src","sources":["provider/scroll-provider.web.ts"],"mappings":";;;;;;;;;;;AACA,IAAAA,SAAA,GAAAC,OAAA","ignoreList":[]}

package/lib/module/provider/index.js

@@ -0,0 +1,63 @@
+"use strict";
+
+/**
+ * `BloomProvider` — the ONE Bloom root an app mounts.
+ *
+ * Bloom's app-wide state used to be a handful of separate providers that every
+ * consumer wired by hand (theme, haptics, image resolution, scroll restoration,
+ * tab-bar minimize progress). Mounting them separately means each one can end
+ * up at a different depth, and a provider mounted too low fails in ways that
+ * are hard to trace:
+ *
+ *   - `useScrollRestoration()` THROWS on web outside `ScrollRestorationProvider`,
+ *     so any scrollable rendered beside the provider (a right rail, an overlay)
+ *     crashes the screen.
+ *   - `useMinimizeState()` silently hands each caller a private fallback, so a
+ *     tab bar below the provider just never minimizes — no error anywhere.
+ *
+ * Mounting this single provider at the app root makes both classes of mistake
+ * impossible: everything Bloom renders is under all of them, at the same depth.
+ * Nesting extra contexts costs nothing at runtime — the win is that scope is no
+ * longer a per-app decision.
+ *
+ * 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
+ * second one duplicates every surface it renders):
+ * `<ToastOutlet>`, `<Portal.Provider>`/`<Portal.Outlet>`, `<SurfaceHost>`,
+ * `<BloomDialogProvider>`, `<AlertDialogHost>`.
+ */
+
+import { ImageResolverProvider } from "../image-resolver/index.js";
+import { BloomHapticsProvider } from "../hooks/useHaptics.js";
+import { TabBarMinimizeProvider } from "../tab-bar/minimize-context.js";
+import { BloomThemeProvider } from "../theme/index.js";
+import { ScrollRestorationProvider } from './scroll-provider';
+import { jsx as _jsx } from "react/jsx-runtime";
+export function BloomProvider({
+  children,
+  imageResolver,
+  haptics = true,
+  ...themeProps
+}) {
+  return (
+    /*#__PURE__*/
+    // `value` is passed unconditionally (null when unset) so toggling a resolver
+    // never changes the tree shape and remounts everything below it.
+    _jsx(ImageResolverProvider, {
+      value: imageResolver ?? null,
+      children: /*#__PURE__*/_jsx(BloomThemeProvider, {
+        ...themeProps,
+        children: /*#__PURE__*/_jsx(ScrollRestorationProvider, {
+          children: /*#__PURE__*/_jsx(BloomHapticsProvider, {
+            enabled: haptics,
+            children: /*#__PURE__*/_jsx(TabBarMinimizeProvider, {
+              children: children
+            })
+          })
+        })
+      })
+    })
+  );
+}
+BloomProvider.displayName = 'BloomProvider';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["ImageResolverProvider","BloomHapticsProvider","TabBarMinimizeProvider","BloomThemeProvider","ScrollRestorationProvider","jsx","_jsx","BloomProvider","children","imageResolver","haptics","themeProps","value","enabled","displayName"],"sourceRoot":"../../../src","sources":["provider/index.tsx"],"mappings":";;AAAA;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;;AAGA,SAASA,qBAAqB,QAA4B,4BAAmB;AAC7E,SAASC,oBAAoB,QAAQ,wBAAqB;AAC1D,SAASC,sBAAsB,QAAQ,gCAA6B;AACpE,SAASC,kBAAkB,QAAsC,mBAAU;AAC3E,SAASC,yBAAyB,QAAQ,mBAAmB;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAc9D,OAAO,SAASC,aAAaA,CAAC;EAC5BC,QAAQ;EACRC,aAAa;EACbC,OAAO,GAAG,IAAI;EACd,GAAGC;AACe,CAAC,EAAE;EACrB;IAAA;IACE;IACA;IACAL,IAAA,CAACN,qBAAqB;MAACY,KAAK,EAAEH,aAAa,IAAI,IAAK;MAAAD,QAAA,eAClDF,IAAA,CAACH,kBAAkB;QAAA,GAAKQ,UAAU;QAAAH,QAAA,eAChCF,IAAA,CAACF,yBAAyB;UAAAI,QAAA,eACxBF,IAAA,CAACL,oBAAoB;YAACY,OAAO,EAAEH,OAAQ;YAAAF,QAAA,eACrCF,IAAA,CAACJ,sBAAsB;cAAAM,QAAA,EAAEA;YAAQ,CAAyB;UAAC,CACvC;QAAC,CACE;MAAC,CACV;IAAC,CACA;EAAC;AAE5B;AAEAD,aAAa,CAACO,WAAW,GAAG,eAAe","ignoreList":[]}

package/lib/module/provider/scroll-provider.js

@@ -0,0 +1,16 @@
+"use strict";
+
+/**
+ * Native/default binding for the scroll-restoration provider used by
+ * {@link BloomProvider}.
+ *
+ * `@oxyhq/bloom/scroll` is web-forked, so its `browser` export condition hands
+ * web consumers the real implementation while native gets the no-op. A compiled
+ * `lib/module/provider/index.js` cannot benefit from that condition (it imports
+ * a relative path, not the package subpath), so the platform choice is made
+ * here by FILENAME instead: Metro picks `scroll-provider.web.ts` on web, and
+ * every web bundler that resolves `.web.js` picks the compiled sibling. Same
+ * mechanism the toast engine uses for `ToastHost.native.tsx`.
+ */
+export { ScrollRestorationProvider } from "../scroll/index.js";
+//# sourceMappingURL=scroll-provider.js.map

package/lib/module/provider/scroll-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["ScrollRestorationProvider"],"sourceRoot":"../../../src","sources":["provider/scroll-provider.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,yBAAyB,QAAQ,oBAAW","ignoreList":[]}

package/lib/module/provider/scroll-provider.web.js

@@ -0,0 +1,5 @@
+"use strict";
+
+/** Web binding for {@link BloomProvider}'s scroll-restoration provider — see `./scroll-provider.ts`. */
+export { ScrollRestorationProvider } from "../scroll/index.web.js";
+//# sourceMappingURL=scroll-provider.web.js.map

package/lib/module/provider/scroll-provider.web.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["ScrollRestorationProvider"],"sourceRoot":"../../../src","sources":["provider/scroll-provider.web.ts"],"mappings":";;AAAA;AACA,SAASA,yBAAyB,QAAQ,wBAAqB","ignoreList":[]}

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

@@ -0,0 +1,45 @@
+/**
+ * `BloomProvider` — the ONE Bloom root an app mounts.
+ *
+ * Bloom's app-wide state used to be a handful of separate providers that every
+ * consumer wired by hand (theme, haptics, image resolution, scroll restoration,
+ * tab-bar minimize progress). Mounting them separately means each one can end
+ * up at a different depth, and a provider mounted too low fails in ways that
+ * are hard to trace:
+ *
+ *   - `useScrollRestoration()` THROWS on web outside `ScrollRestorationProvider`,
+ *     so any scrollable rendered beside the provider (a right rail, an overlay)
+ *     crashes the screen.
+ *   - `useMinimizeState()` silently hands each caller a private fallback, so a
+ *     tab bar below the provider just never minimizes — no error anywhere.
+ *
+ * Mounting this single provider at the app root makes both classes of mistake
+ * impossible: everything Bloom renders is under all of them, at the same depth.
+ * Nesting extra contexts costs nothing at runtime — the win is that scope is no
+ * longer a per-app decision.
+ *
+ * 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
+ * second one duplicates every surface it renders):
+ * `<ToastOutlet>`, `<Portal.Provider>`/`<Portal.Outlet>`, `<SurfaceHost>`,
+ * `<BloomDialogProvider>`, `<AlertDialogHost>`.
+ */
+import type { ReactNode } from 'react';
+import { type ImageResolver } from '../image-resolver';
+import { type BloomThemeProviderProps } from '../theme';
+export interface BloomProviderProps extends Omit<BloomThemeProviderProps, 'children'> {
+    children: ReactNode;
+    /**
+     * Resolves bare media identifiers (Oxy file ids) to loadable URLs for every
+     * Bloom surface that takes a `source` — `<Avatar>`, image galleries, cards.
+     * Typically `(id, variant) => oxyServices.getFileDownloadUrl(id, variant)`.
+     */
+    imageResolver?: ImageResolver;
+    /** `false` disables haptic feedback app-wide (honored by every `useHaptics()` call). */
+    haptics?: boolean;
+}
+export declare function BloomProvider({ children, imageResolver, haptics, ...themeProps }: BloomProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace BloomProvider {
+    var displayName: string;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/provider/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG9E,OAAO,EAAsB,KAAK,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAG5E,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC;IACnF,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,wFAAwF;IACxF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,aAAa,EACb,OAAc,EACd,GAAG,UAAU,EACd,EAAE,kBAAkB,2CAcpB;yBAnBe,aAAa"}

package/lib/typescript/commonjs/provider/scroll-provider.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Native/default binding for the scroll-restoration provider used by
+ * {@link BloomProvider}.
+ *
+ * `@oxyhq/bloom/scroll` is web-forked, so its `browser` export condition hands
+ * web consumers the real implementation while native gets the no-op. A compiled
+ * `lib/module/provider/index.js` cannot benefit from that condition (it imports
+ * a relative path, not the package subpath), so the platform choice is made
+ * here by FILENAME instead: Metro picks `scroll-provider.web.ts` on web, and
+ * every web bundler that resolves `.web.js` picks the compiled sibling. Same
+ * mechanism the toast engine uses for `ToastHost.native.tsx`.
+ */
+export { ScrollRestorationProvider } from '../scroll';
+//# sourceMappingURL=scroll-provider.d.ts.map

package/lib/typescript/commonjs/provider/scroll-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-provider.d.ts","sourceRoot":"","sources":["../../../../src/provider/scroll-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC"}

package/lib/typescript/commonjs/provider/scroll-provider.web.d.ts

@@ -0,0 +1,3 @@
+/** Web binding for {@link BloomProvider}'s scroll-restoration provider — see `./scroll-provider.ts`. */
+export { ScrollRestorationProvider } from '../scroll/index.web';
+//# sourceMappingURL=scroll-provider.web.d.ts.map

package/lib/typescript/commonjs/provider/scroll-provider.web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-provider.web.d.ts","sourceRoot":"","sources":["../../../../src/provider/scroll-provider.web.ts"],"names":[],"mappings":"AAAA,wGAAwG;AACxG,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC"}

package/lib/typescript/module/provider/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `BloomProvider` — the ONE Bloom root an app mounts.
+ *
+ * Bloom's app-wide state used to be a handful of separate providers that every
+ * consumer wired by hand (theme, haptics, image resolution, scroll restoration,
+ * tab-bar minimize progress). Mounting them separately means each one can end
+ * up at a different depth, and a provider mounted too low fails in ways that
+ * are hard to trace:
+ *
+ *   - `useScrollRestoration()` THROWS on web outside `ScrollRestorationProvider`,
+ *     so any scrollable rendered beside the provider (a right rail, an overlay)
+ *     crashes the screen.
+ *   - `useMinimizeState()` silently hands each caller a private fallback, so a
+ *     tab bar below the provider just never minimizes — no error anywhere.
+ *
+ * Mounting this single provider at the app root makes both classes of mistake
+ * impossible: everything Bloom renders is under all of them, at the same depth.
+ * Nesting extra contexts costs nothing at runtime — the win is that scope is no
+ * longer a per-app decision.
+ *
+ * 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
+ * second one duplicates every surface it renders):
+ * `<ToastOutlet>`, `<Portal.Provider>`/`<Portal.Outlet>`, `<SurfaceHost>`,
+ * `<BloomDialogProvider>`, `<AlertDialogHost>`.
+ */
+import type { ReactNode } from 'react';
+import { type ImageResolver } from '../image-resolver';
+import { type BloomThemeProviderProps } from '../theme';
+export interface BloomProviderProps extends Omit<BloomThemeProviderProps, 'children'> {
+    children: ReactNode;
+    /**
+     * Resolves bare media identifiers (Oxy file ids) to loadable URLs for every
+     * Bloom surface that takes a `source` — `<Avatar>`, image galleries, cards.
+     * Typically `(id, variant) => oxyServices.getFileDownloadUrl(id, variant)`.
+     */
+    imageResolver?: ImageResolver;
+    /** `false` disables haptic feedback app-wide (honored by every `useHaptics()` call). */
+    haptics?: boolean;
+}
+export declare function BloomProvider({ children, imageResolver, haptics, ...themeProps }: BloomProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace BloomProvider {
+    var displayName: string;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/provider/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG9E,OAAO,EAAsB,KAAK,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAG5E,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC;IACnF,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,wFAAwF;IACxF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,aAAa,EACb,OAAc,EACd,GAAG,UAAU,EACd,EAAE,kBAAkB,2CAcpB;yBAnBe,aAAa"}

package/lib/typescript/module/provider/scroll-provider.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Native/default binding for the scroll-restoration provider used by
+ * {@link BloomProvider}.
+ *
+ * `@oxyhq/bloom/scroll` is web-forked, so its `browser` export condition hands
+ * web consumers the real implementation while native gets the no-op. A compiled
+ * `lib/module/provider/index.js` cannot benefit from that condition (it imports
+ * a relative path, not the package subpath), so the platform choice is made
+ * here by FILENAME instead: Metro picks `scroll-provider.web.ts` on web, and
+ * every web bundler that resolves `.web.js` picks the compiled sibling. Same
+ * mechanism the toast engine uses for `ToastHost.native.tsx`.
+ */
+export { ScrollRestorationProvider } from '../scroll';
+//# sourceMappingURL=scroll-provider.d.ts.map

package/lib/typescript/module/provider/scroll-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-provider.d.ts","sourceRoot":"","sources":["../../../../src/provider/scroll-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC"}

package/lib/typescript/module/provider/scroll-provider.web.d.ts

@@ -0,0 +1,3 @@
+/** Web binding for {@link BloomProvider}'s scroll-restoration provider — see `./scroll-provider.ts`. */
+export { ScrollRestorationProvider } from '../scroll/index.web';
+//# sourceMappingURL=scroll-provider.web.d.ts.map

package/lib/typescript/module/provider/scroll-provider.web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-provider.web.d.ts","sourceRoot":"","sources":["../../../../src/provider/scroll-provider.web.ts"],"names":[],"mappings":"AAAA,wGAAwG;AACxG,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.55.0",
+  "version": "0.56.0",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -28,6 +28,17 @@
         "default": "./lib/commonjs/index.js"
       }
     },
+    "./provider": {
+      "react-native": "./src/provider/index.tsx",
+      "import": {
+        "types": "./lib/typescript/module/provider/index.d.ts",
+        "default": "./lib/module/provider/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/provider/index.d.ts",
+        "default": "./lib/commonjs/provider/index.js"
+      }
+    },
     "./surfaces": {
       "react-native": "./src/surfaces/index.ts",
       "browser": {

package/src/__tests__/BloomProvider.web.test.tsx

@@ -0,0 +1,114 @@
+/**
+ * @jest-environment jsdom
+ */
+
+// `BloomProvider` exists so an app mounts ONE Bloom root instead of five, and
+// the concrete bug that motivated it is web-only: `useScrollRestoration()`
+// THROWS outside `ScrollRestorationProvider`, so anything scrollable that an
+// app renders beside — rather than under — that provider crashes the screen.
+//
+// These tests therefore assert the WEB binding: `provider/scroll-provider` is
+// mapped to the web implementation the same way a web bundler resolves the
+// `.web` sibling (jest has no platform-extension resolution of its own, so
+// without this mapping the suite would silently exercise the native no-op and
+// pass no matter what).
+
+import { createElement, type ReactNode } from 'react';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+  true;
+
+// Only the two navigation hooks `scroll/index.web` consumes; `virtual` keeps
+// the real (native-heavy) expo-router off the resolver.
+jest.mock(
+  'expo-router',
+  () => {
+    const react = jest.requireActual<typeof import('react')>('react');
+    return {
+      useFocusEffect: (effect: () => undefined | (() => void)) => {
+        react.useEffect(effect, [effect]);
+      },
+      useRoute: () => ({ key: 'route-test', name: 'Test', params: {} }),
+    };
+  },
+  { virtual: true },
+);
+
+// What a web bundler does with `provider/scroll-provider.web.ts`.
+jest.mock('../provider/scroll-provider', () => ({
+  ScrollRestorationProvider:
+    jest.requireActual<typeof import('../scroll/index.web')>('../scroll/index.web')
+      .ScrollRestorationProvider,
+}));
+
+// Imported AFTER the mocks are registered.
+import { BloomProvider } from '../provider';
+import { useImageResolver } from '../image-resolver';
+import { useScrollRestoration } from '../scroll/index.web';
+
+/**
+ * Stands in for any Bloom-consuming scrollable an app renders under the root —
+ * a feed, a right-rail replies list, an overlay.
+ */
+function Scrollable({ onResolve }: { onResolve?: (url: string | undefined) => void }): ReactNode {
+  useScrollRestoration('window');
+  const resolver = useImageResolver();
+  onResolve?.(resolver?.('file-id', 'avatar'));
+  return null;
+}
+
+function render(node: ReactNode): { root: Root; container: HTMLElement } {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  act(() => {
+    root.render(node);
+  });
+  return { root, container };
+}
+
+function unmount({ root, container }: { root: Root; container: HTMLElement }): void {
+  act(() => {
+    root.unmount();
+  });
+  container.remove();
+}
+
+describe('BloomProvider (web)', () => {
+  it('provides scroll restoration to everything below it', () => {
+    let resolved: string | undefined;
+    let mounted: { root: Root; container: HTMLElement } | undefined;
+
+    expect(() => {
+      mounted = render(
+        createElement(BloomProvider, {
+          fonts: false,
+          imageResolver: (id: string, variant?: string) => `${id}:${variant}`,
+          children: createElement(Scrollable, { onResolve: (url) => { resolved = url; } }),
+        }),
+      );
+    }).not.toThrow();
+
+    // The image resolver reaches the same subtree — one root, every context.
+    expect(resolved).toBe('file-id:avatar');
+
+    if (mounted) unmount(mounted);
+  });
+
+  // Vacuity guard: proves the assertion above is actually load-bearing. If the
+  // provider ever stops mounting the WEB scroll provider (a bad platform
+  // binding, a dropped nesting level) this control case is what makes the test
+  // above meaningful — remove the provider and the very same child throws.
+  it('is what keeps the hook from throwing — the same child crashes without it', () => {
+    const consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+    try {
+      expect(() => render(createElement(Scrollable, {}))).toThrow(
+        /useScrollRestoration must be used within a <ScrollRestorationProvider>/,
+      );
+    } finally {
+      consoleError.mockRestore();
+    }
+  });
+});

package/src/provider/index.tsx

@@ -0,0 +1,68 @@
+/**
+ * `BloomProvider` — the ONE Bloom root an app mounts.
+ *
+ * Bloom's app-wide state used to be a handful of separate providers that every
+ * consumer wired by hand (theme, haptics, image resolution, scroll restoration,
+ * tab-bar minimize progress). Mounting them separately means each one can end
+ * up at a different depth, and a provider mounted too low fails in ways that
+ * are hard to trace:
+ *
+ *   - `useScrollRestoration()` THROWS on web outside `ScrollRestorationProvider`,
+ *     so any scrollable rendered beside the provider (a right rail, an overlay)
+ *     crashes the screen.
+ *   - `useMinimizeState()` silently hands each caller a private fallback, so a
+ *     tab bar below the provider just never minimizes — no error anywhere.
+ *
+ * Mounting this single provider at the app root makes both classes of mistake
+ * impossible: everything Bloom renders is under all of them, at the same depth.
+ * Nesting extra contexts costs nothing at runtime — the win is that scope is no
+ * longer a per-app decision.
+ *
+ * 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
+ * second one duplicates every surface it renders):
+ * `<ToastOutlet>`, `<Portal.Provider>`/`<Portal.Outlet>`, `<SurfaceHost>`,
+ * `<BloomDialogProvider>`, `<AlertDialogHost>`.
+ */
+import type { ReactNode } from 'react';
+
+import { ImageResolverProvider, type ImageResolver } from '../image-resolver';
+import { BloomHapticsProvider } from '../hooks/useHaptics';
+import { TabBarMinimizeProvider } from '../tab-bar/minimize-context';
+import { BloomThemeProvider, type BloomThemeProviderProps } from '../theme';
+import { ScrollRestorationProvider } from './scroll-provider';
+
+export interface BloomProviderProps extends Omit<BloomThemeProviderProps, 'children'> {
+  children: ReactNode;
+  /**
+   * Resolves bare media identifiers (Oxy file ids) to loadable URLs for every
+   * Bloom surface that takes a `source` — `<Avatar>`, image galleries, cards.
+   * Typically `(id, variant) => oxyServices.getFileDownloadUrl(id, variant)`.
+   */
+  imageResolver?: ImageResolver;
+  /** `false` disables haptic feedback app-wide (honored by every `useHaptics()` call). */
+  haptics?: boolean;
+}
+
+export function BloomProvider({
+  children,
+  imageResolver,
+  haptics = true,
+  ...themeProps
+}: BloomProviderProps) {
+  return (
+    // `value` is passed unconditionally (null when unset) so toggling a resolver
+    // never changes the tree shape and remounts everything below it.
+    <ImageResolverProvider value={imageResolver ?? null}>
+      <BloomThemeProvider {...themeProps}>
+        <ScrollRestorationProvider>
+          <BloomHapticsProvider enabled={haptics}>
+            <TabBarMinimizeProvider>{children}</TabBarMinimizeProvider>
+          </BloomHapticsProvider>
+        </ScrollRestorationProvider>
+      </BloomThemeProvider>
+    </ImageResolverProvider>
+  );
+}
+
+BloomProvider.displayName = 'BloomProvider';

package/src/provider/scroll-provider.ts

@@ -0,0 +1,13 @@
+/**
+ * Native/default binding for the scroll-restoration provider used by
+ * {@link BloomProvider}.
+ *
+ * `@oxyhq/bloom/scroll` is web-forked, so its `browser` export condition hands
+ * web consumers the real implementation while native gets the no-op. A compiled
+ * `lib/module/provider/index.js` cannot benefit from that condition (it imports
+ * a relative path, not the package subpath), so the platform choice is made
+ * here by FILENAME instead: Metro picks `scroll-provider.web.ts` on web, and
+ * every web bundler that resolves `.web.js` picks the compiled sibling. Same
+ * mechanism the toast engine uses for `ToastHost.native.tsx`.
+ */
+export { ScrollRestorationProvider } from '../scroll';

package/src/provider/scroll-provider.web.ts

@@ -0,0 +1,2 @@
+/** Web binding for {@link BloomProvider}'s scroll-restoration provider — see `./scroll-provider.ts`. */
+export { ScrollRestorationProvider } from '../scroll/index.web';