@oxyhq/bloom 0.55.0 → 0.57.0

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

@@ -0,0 +1,67 @@
+/**
+ * The shared plumbing every portaled surface needs: an interactive ROOT and a
+ * press-to-dismiss BACKDROP. Dialog, BottomSheet, the image gallery, menus and
+ * toasts each used to hand-roll both, and each one got the web contract subtly
+ * wrong in its own way.
+ *
+ * ## The contract these two components encode
+ *
+ * Bloom's web `Portal` renders into `#bloom-portal-root`, which is
+ * `position: fixed; inset: 0; pointer-events: none` — an idle portal must let
+ * clicks reach the app underneath. `pointer-events` INHERITS in CSS, so every
+ * portaled descendant starts out click-through and has to opt back in.
+ *
+ * The opt-in only works through the `pointerEvents` **prop**. Passing it inside
+ * a `style` object (`style={{ pointerEvents: 'box-none' }}`) does NOT reach the
+ * DOM: react-native-web resolves the RN-only `box-none`/`box-only` values in
+ * `createDOMProps`, mapping the PROP onto its own class pair
+ * (`self { none !important }` + `> * { auto }`), while a style-object value is
+ * not valid CSS and is dropped. `pointerEvents: 'auto'`/`'none'` do survive as
+ * styles, which is what makes this so easy to get wrong — the two RN-only
+ * values silently do nothing. The symptom is brutal and silent: the whole
+ * surface — backdrop AND panel — renders perfectly and is completely
+ * click-through. Backdrop taps don't dismiss, buttons don't press, and the
+ * clicks land on whatever is behind the overlay (so a tap "through" a viewer
+ * navigates the page underneath). Only keyboard paths (Escape) keep working,
+ * which is what makes it look like a dismissal bug rather than a hit-testing
+ * one.
+ *
+ * Use `<OverlayRoot>` for the surface's outermost node and `<Backdrop>` for its
+ * dimming layer; do not re-implement either with raw `View`s.
+ */
+import { type ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+export interface OverlayRootProps {
+    children?: ReactNode;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * Outermost node of a portaled surface. Fills the viewport and re-enables
+ * pointer events for its own children while empty gaps stay click-through
+ * (`box-none`), so a surface that only covers part of the screen never steals
+ * clicks from the app behind it.
+ */
+export declare function OverlayRoot({ children, style, testID }: OverlayRootProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace OverlayRoot {
+    var displayName: string;
+}
+export interface BackdropProps {
+    /** Dismiss handler. Omit (or pass `disabled`) for a backdrop that only dims. */
+    onPress?: () => void;
+    /** `true` keeps the dim but makes it inert — a blocking dialog, a busy state. */
+    disabled?: boolean;
+    /** Extra style (dim colour, animated opacity). Rendered over `absoluteFill`. */
+    style?: StyleProp<ViewStyle>;
+    /** Rendered inside the backdrop — e.g. a blur layer that must dim with it. */
+    children?: ReactNode;
+    accessibilityLabel?: string;
+    testID?: string;
+}
+/**
+ * Full-bleed dimming layer that dismisses the surface when pressed. Always
+ * takes pointer events (that is its whole job), so it must render UNDER the
+ * surface's panel in the tree, never over it.
+ */
+export declare const Backdrop: import("react").NamedExoticComponent<BackdropProps>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/overlay/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAyC,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAIrG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,gBAAgB,2CAMxE;yBANe,WAAW;;;AAU3B,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,qDA0BnB,CAAC"}

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/commonjs/toast/ToastHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToastHost.d.ts","sourceRoot":"","sources":["../../../../src/toast/ToastHost.tsx"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,qBAAqB,EAAE,EAAE,cAAc,2CAgB5E;yBAhBe,SAAS"}
+{"version":3,"file":"ToastHost.d.ts","sourceRoot":"","sources":["../../../../src/toast/ToastHost.tsx"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,qBAAqB,EAAE,EAAE,cAAc,2CAqB5E;yBArBe,SAAS"}

package/lib/typescript/commonjs/zoomable-image-gallery/ZoomableImageGallery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ZoomableImageGallery.d.ts","sourceRoot":"","sources":["../../../../src/zoomable-image-gallery/ZoomableImageGallery.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAC;AAkEjF,OAAO,KAAK,EAGV,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,SAAS,CAAC;AA64BjB,eAAO,MAAM,oBAAoB,8GAA4B,CAAC;AAyK9D,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"ZoomableImageGallery.d.ts","sourceRoot":"","sources":["../../../../src/zoomable-image-gallery/ZoomableImageGallery.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAC;AAmEjF,OAAO,KAAK,EAGV,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,SAAS,CAAC;AAu4BjB,eAAO,MAAM,oBAAoB,8GAA4B,CAAC;AAyK9D,eAAe,oBAAoB,CAAC"}

package/lib/typescript/module/bottom-sheet/index.web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../src/bottom-sheet/index.web.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B,OAAO,EAEH,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAEtB,MAAM,mBAAmB,CAAC;AA8B3B,QAAA,MAAM,WAAW,yFAEf,CAAC;AAoBH,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAC;AACjD,eAAe,WAAW,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../src/bottom-sheet/index.web.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAQ/B,OAAO,EAEH,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAEtB,MAAM,mBAAmB,CAAC;AAoC3B,QAAA,MAAM,WAAW,yFAEf,CAAC;AAkBH,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAC;AACjD,eAAe,WAAW,CAAC;AAC3B,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/lib/typescript/module/dialog/Dialog.web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Dialog.web.d.ts","sourceRoot":"","sources":["../../../../src/dialog/Dialog.web.tsx"],"names":[],"mappings":"AAsCA,OAAO,EAOL,4BAA4B,EAM7B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,YAAY,EAGZ,WAAW,EACZ,MAAM,SAAS,CAAC;AAsDjB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,WAAW,2CAazD;AA8ZD,OAAO,EAAE,4BAA4B,EAAE,CAAC;AAkQxC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,WAAW,EACX,OAAO,EACP,SAAS,GACV,EAAE;IACD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB,2CAgBA;AAiCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,gBAAgB,mZAK5B,CAAC"}
+{"version":3,"file":"Dialog.web.d.ts","sourceRoot":"","sources":["../../../../src/dialog/Dialog.web.tsx"],"names":[],"mappings":"AAuCA,OAAO,EAOL,4BAA4B,EAM7B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,YAAY,EAGZ,WAAW,EACZ,MAAM,SAAS,CAAC;AAsDjB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,WAAW,2CAazD;AA4ZD,OAAO,EAAE,4BAA4B,EAAE,CAAC;AAiQxC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,WAAW,EACX,OAAO,EACP,SAAS,GACV,EAAE;IACD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB,2CAgBA;AAiCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,gBAAgB,mZAK5B,CAAC"}

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

@@ -0,0 +1,67 @@
+/**
+ * The shared plumbing every portaled surface needs: an interactive ROOT and a
+ * press-to-dismiss BACKDROP. Dialog, BottomSheet, the image gallery, menus and
+ * toasts each used to hand-roll both, and each one got the web contract subtly
+ * wrong in its own way.
+ *
+ * ## The contract these two components encode
+ *
+ * Bloom's web `Portal` renders into `#bloom-portal-root`, which is
+ * `position: fixed; inset: 0; pointer-events: none` — an idle portal must let
+ * clicks reach the app underneath. `pointer-events` INHERITS in CSS, so every
+ * portaled descendant starts out click-through and has to opt back in.
+ *
+ * The opt-in only works through the `pointerEvents` **prop**. Passing it inside
+ * a `style` object (`style={{ pointerEvents: 'box-none' }}`) does NOT reach the
+ * DOM: react-native-web resolves the RN-only `box-none`/`box-only` values in
+ * `createDOMProps`, mapping the PROP onto its own class pair
+ * (`self { none !important }` + `> * { auto }`), while a style-object value is
+ * not valid CSS and is dropped. `pointerEvents: 'auto'`/`'none'` do survive as
+ * styles, which is what makes this so easy to get wrong — the two RN-only
+ * values silently do nothing. The symptom is brutal and silent: the whole
+ * surface — backdrop AND panel — renders perfectly and is completely
+ * click-through. Backdrop taps don't dismiss, buttons don't press, and the
+ * clicks land on whatever is behind the overlay (so a tap "through" a viewer
+ * navigates the page underneath). Only keyboard paths (Escape) keep working,
+ * which is what makes it look like a dismissal bug rather than a hit-testing
+ * one.
+ *
+ * Use `<OverlayRoot>` for the surface's outermost node and `<Backdrop>` for its
+ * dimming layer; do not re-implement either with raw `View`s.
+ */
+import { type ReactNode } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+export interface OverlayRootProps {
+    children?: ReactNode;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * Outermost node of a portaled surface. Fills the viewport and re-enables
+ * pointer events for its own children while empty gaps stay click-through
+ * (`box-none`), so a surface that only covers part of the screen never steals
+ * clicks from the app behind it.
+ */
+export declare function OverlayRoot({ children, style, testID }: OverlayRootProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace OverlayRoot {
+    var displayName: string;
+}
+export interface BackdropProps {
+    /** Dismiss handler. Omit (or pass `disabled`) for a backdrop that only dims. */
+    onPress?: () => void;
+    /** `true` keeps the dim but makes it inert — a blocking dialog, a busy state. */
+    disabled?: boolean;
+    /** Extra style (dim colour, animated opacity). Rendered over `absoluteFill`. */
+    style?: StyleProp<ViewStyle>;
+    /** Rendered inside the backdrop — e.g. a blur layer that must dim with it. */
+    children?: ReactNode;
+    accessibilityLabel?: string;
+    testID?: string;
+}
+/**
+ * Full-bleed dimming layer that dismisses the surface when pressed. Always
+ * takes pointer events (that is its whole job), so it must render UNDER the
+ * surface's panel in the tree, never over it.
+ */
+export declare const Backdrop: import("react").NamedExoticComponent<BackdropProps>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/overlay/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAyC,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAIrG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,gBAAgB,2CAMxE;yBANe,WAAW;;;AAU3B,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,qDA0BnB,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/lib/typescript/module/toast/ToastHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToastHost.d.ts","sourceRoot":"","sources":["../../../../src/toast/ToastHost.tsx"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,qBAAqB,EAAE,EAAE,cAAc,2CAgB5E;yBAhBe,SAAS"}
+{"version":3,"file":"ToastHost.d.ts","sourceRoot":"","sources":["../../../../src/toast/ToastHost.tsx"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,qBAAqB,EAAE,EAAE,cAAc,2CAqB5E;yBArBe,SAAS"}

package/lib/typescript/module/zoomable-image-gallery/ZoomableImageGallery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ZoomableImageGallery.d.ts","sourceRoot":"","sources":["../../../../src/zoomable-image-gallery/ZoomableImageGallery.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAC;AAkEjF,OAAO,KAAK,EAGV,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,SAAS,CAAC;AA64BjB,eAAO,MAAM,oBAAoB,8GAA4B,CAAC;AAyK9D,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"ZoomableImageGallery.d.ts","sourceRoot":"","sources":["../../../../src/zoomable-image-gallery/ZoomableImageGallery.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAC;AAmEjF,OAAO,KAAK,EAGV,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,SAAS,CAAC;AAu4BjB,eAAO,MAAM,oBAAoB,8GAA4B,CAAC;AAyK9D,eAAe,oBAAoB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.55.0",
+  "version": "0.57.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": {
@@ -137,6 +148,17 @@
         "default": "./lib/commonjs/portal/index.js"
       }
     },
+    "./overlay": {
+      "react-native": "./src/overlay/index.tsx",
+      "import": {
+        "types": "./lib/typescript/module/overlay/index.d.ts",
+        "default": "./lib/module/overlay/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/overlay/index.d.ts",
+        "default": "./lib/commonjs/overlay/index.js"
+      }
+    },
     "./dialog": {
       "react-native": "./src/dialog/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/__tests__/TabBarBlur.test.tsx

@@ -76,11 +76,16 @@ function flattenStyle(style: unknown): Record<string, unknown> {
 /**
  * The bar's outermost view — `styles.root`, the absolutely-positioned
  * `box-none` layer the blur and the pill wrap are the two children of.
+ *
+ * `box-none` is matched on the PROP, not on the flattened style: react-native-web
+ * only resolves that RN-only value from the prop path, so this bar (a full-width
+ * band pinned to the bottom of every page) would silently swallow clicks if it
+ * ever moved back into the style object. See `pointer-events-style-form.test.ts`.
  */
 function barRoot(tree: RenderedTree): ReactTestRendererJSON {
   const found = hostNodes(tree).find((node) => {
     const style = flattenStyle(node.props.style);
-    return style.position === 'absolute' && style.pointerEvents === 'box-none';
+    return style.position === 'absolute' && node.props.pointerEvents === 'box-none';
   });
   if (!found) throw new Error('The bar rendered no absolute box-none root');
   return found;

package/src/__tests__/overlay-pointer-events.test.tsx

@@ -0,0 +1,124 @@
+/**
+ * @jest-environment jsdom
+ */
+
+// The bug these tests exist for: Bloom's web `Portal` root is
+// `pointer-events: none`, so every portaled surface has to opt back in. The
+// surfaces did that with a `style={{ pointerEvents: 'box-none' }}` entry, which
+// never reached the DOM — react-native-web resolves the `pointerEvents` PROP
+// into its class pair, and the style-object form was dropped on the way
+// through. The result on production web: dialogs, bottom sheets, the image
+// viewer and toasts all rendered perfectly and were completely click-through.
+// Backdrops didn't dismiss, panels didn't press, and clicks landed on the app
+// behind the overlay.
+//
+// `OverlayRoot` / `Backdrop` encode the working contract; these tests pin it.
+
+import { createElement } from 'react';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+// The whole point is what react-native-web puts in the DOM, so this suite runs
+// against the REAL RNW — not the repo-wide `react-native` mock, which never
+// emits a class and would make every assertion below vacuous.
+jest.mock('react-native', () => jest.requireActual('react-native-web'));
+
+import { Backdrop, OverlayRoot } from '../overlay';
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+  true;
+
+/** Every `pointer-events` declaration react-native-web injected for `className`. */
+function pointerEventsRulesFor(className: string): string[] {
+  const classes = className.split(/\s+/).filter(Boolean);
+  const out: string[] = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRuleList;
+    try {
+      rules = sheet.cssRules;
+    } catch {
+      continue;
+    }
+    for (const rule of Array.from(rules)) {
+      const text = rule.cssText ?? '';
+      if (!text.includes('pointer-events')) continue;
+      if (classes.some((c) => text.includes(`.${c}`))) out.push(text);
+    }
+  }
+  return out;
+}
+
+function render(node: ReturnType<typeof createElement>): {
+  root: Root;
+  container: HTMLElement;
+} {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  act(() => {
+    root.render(node);
+  });
+  return { root, container };
+}
+
+describe('overlay pointer-events contract (web)', () => {
+  it('OverlayRoot emits box-none: itself inert, its children interactive', () => {
+    const { root, container } = render(
+      createElement(OverlayRoot, { testID: 'root', children: null }),
+    );
+
+    const el = container.querySelector('[data-testid="root"]');
+    expect(el).not.toBeNull();
+    const rules = pointerEventsRulesFor(el?.className ?? '');
+
+    // The two halves of react-native-web's `box-none`: the box itself does not
+    // take events (empty gaps stay click-through), direct children do.
+    expect(rules.some((r) => /pointer-events:\s*none/.test(r) && !/>\s*\*/.test(r))).toBe(true);
+    expect(rules.some((r) => />\s*\*/.test(r) && /pointer-events:\s*auto/.test(r))).toBe(true);
+
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  it('Backdrop takes pointer events and dismisses on press', () => {
+    const onPress = jest.fn();
+    const { root, container } = render(
+      createElement(Backdrop, { onPress, testID: 'backdrop' }),
+    );
+
+    const el = container.querySelector('[data-testid="backdrop"]') as HTMLElement | null;
+    expect(el).not.toBeNull();
+
+    // Without this the element inherits the portal root's `none` and the press
+    // below can never happen in a real browser.
+    expect(
+      pointerEventsRulesFor(el?.className ?? '').some((r) =>
+        /pointer-events:\s*auto/.test(r),
+      ),
+    ).toBe(true);
+
+    act(() => {
+      el?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+    expect(onPress).toHaveBeenCalledTimes(1);
+
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  it('a disabled Backdrop dims without dismissing', () => {
+    const onPress = jest.fn();
+    const { root, container } = render(
+      createElement(Backdrop, { onPress, disabled: true, testID: 'backdrop' }),
+    );
+
+    const el = container.querySelector('[data-testid="backdrop"]') as HTMLElement | null;
+    act(() => {
+      el?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+    expect(onPress).not.toHaveBeenCalled();
+
+    act(() => root.unmount());
+    container.remove();
+  });
+});