@oxyhq/bloom 0.55.0 → 0.57.0

package/src/__tests__/pointer-events-style-form.test.ts

@@ -0,0 +1,58 @@
+// A source gate for the one mistake that took every Bloom overlay down on web:
+// writing `pointerEvents: 'box-none'` (or `'box-only'`) inside a STYLE object.
+//
+// react-native-web resolves those two RN-only values in `createDOMProps`, from
+// the `pointerEvents` PROP — it maps the prop onto its own class pair
+// (`self { none !important }` + `> * { auto }`). As a style-object value it is
+// not valid CSS and is dropped, so the element silently keeps whatever it
+// inherits. Inside the web Portal (root: `pointer-events: none`) that makes the
+// entire surface click-through; outside it, a full-bleed `box-none` container
+// becomes click-CATCHING and eats presses meant for the app under it. Both
+// failure modes render perfectly and log nothing.
+//
+// `pointerEvents: 'auto' | 'none'` ARE valid CSS and stay allowed as styles —
+// only the two RN-only values are banned.
+//
+// The runtime half of this contract is asserted in `overlay-pointer-events.test.tsx`.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SRC = join(__dirname, '..');
+const BANNED = /pointerEvents:\s*['"](box-none|box-only)['"]/;
+
+function sourceFiles(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    if (entry === '__tests__' || entry === 'node_modules') continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      sourceFiles(full, out);
+    } else if (/\.tsx?$/.test(entry)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+describe('pointerEvents style-object form', () => {
+  const files = sourceFiles(SRC);
+
+  // Vacuity floor: a broken traversal would otherwise report a clean sweep.
+  it('scans the whole source tree', () => {
+    expect(files.length).toBeGreaterThan(200);
+    expect(files.some((f) => f.endsWith(join('overlay', 'index.tsx')))).toBe(true);
+  });
+
+  it('never uses the RN-only values as styles — pass them as the prop', () => {
+    const offenders = files
+      .flatMap((file) =>
+        readFileSync(file, 'utf8')
+          .split('\n')
+          .map((line, i) => ({ file: file.slice(SRC.length + 1), line: i + 1, text: line.trim() }))
+          .filter(({ text }) => BANNED.test(text) && !text.startsWith('*') && !text.startsWith('//')),
+      )
+      .map(({ file, line, text }) => `${file}:${line}  ${text}`);
+
+    expect(offenders).toEqual([]);
+  });
+});

package/src/bottom-sheet/index.web.tsx

@@ -2,6 +2,7 @@ import type React from 'react';
 import { forwardRef } from 'react';
 import { StyleSheet } from 'react-native';
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { OverlayRoot } from '../overlay';
 import { Portal } from '../portal/index.web';
 import { Z_INDEX } from '../styles/z-index';
 import { WEB_POSITION_FIXED } from '../styles/web-view-style';
@@ -33,9 +34,15 @@ import {
 function WebShell({ children }: BottomSheetShellProps) {
     return (
         <Portal>
-            <GestureHandlerRootView style={[webStyles.rootView, { pointerEvents: 'box-none' }]}>
-                {children}
-            </GestureHandlerRootView>
+            {/* `OverlayRoot` owns the portal-root pointer-events opt-in (see
+                `src/overlay`). It used to ride in the style array below as an
+                RN-only box-none value, which never reached the DOM — the whole
+                sheet, backdrop included, was click-through on web. */}
+            <OverlayRoot style={webStyles.rootView}>
+                <GestureHandlerRootView style={StyleSheet.absoluteFill}>
+                    {children}
+                </GestureHandlerRootView>
+            </OverlayRoot>
         </Portal>
     );
 }
@@ -48,11 +55,9 @@ BottomSheet.displayName = 'BottomSheet';
 
 const webStyles = StyleSheet.create({
     rootView: {
-        // The bloom Portal root is `position: fixed; inset: 0; pointer-events:
-        // none`; this fixed, full-viewport root re-enables pointer events for
-        // the sheet's own interactive descendants (backdrop, sheet) while empty
-        // gaps stay click-through (`box-none`). `StyleSheet.absoluteFill` from
-        // the sheet body then anchors to this box.
+        // Fixed, full-viewport box the sheet's `StyleSheet.absoluteFill` body
+        // anchors to. The pointer-events opt-in lives in `OverlayRoot`; this
+        // only adds the stacking context.
         position: WEB_POSITION_FIXED,
         top: 0,
         left: 0,

package/src/dialog/Dialog.tsx

@@ -523,13 +523,13 @@ function SideSheet({
 
   return (
     <View
+      pointerEvents="box-none"
       style={[
         sideStyles.root,
         // Per-layer offset so a side dialog stacked on top of another (surface
         // stack) paints above it. Layer 0 → offset 0 → unchanged.
         { zIndex: Z_INDEX.fullscreen + Z_INDEX_LAYER_STEP * (layer ?? 0) },
         containerStyle,
-        { pointerEvents: 'box-none' },
       ]}
       {...(containerClassName ? ({ className: containerClassName } as Record<string, string>) : {})}
     >

package/src/dialog/Dialog.web.tsx

@@ -19,6 +19,7 @@ import {
 import Animated from 'react-native-reanimated';
 import { RemoveScrollBar } from 'react-remove-scroll-bar';
 
+import { Backdrop, OverlayRoot } from '../overlay';
 import { Portal } from '../portal/index.web';
 import { createOverlayZIndex } from '../styles/z-index';
 import { WEB_POSITION_FIXED, type WebCssStyle } from '../styles/web-view-style';
@@ -315,23 +316,21 @@ function CenterOrSideDialog({
         <Context.Provider value={context}>
           <ClosingContext.Provider value={isClosing}>
             <RemoveScrollBar />
-            <Pressable
-              onPress={dismissOnBackdrop ? () => close() : undefined}
+            {/* The press target IS the full-viewport box, so it uses
+                `Backdrop` (which opts back in from the Portal root's
+                `pointer-events: none` via the `pointerEvents` PROP — the style
+                form is dropped before it reaches the DOM, see `src/overlay`)
+                and lays the panel out inside itself. */}
+            <Backdrop
+              onPress={() => close()}
               disabled={!dismissOnBackdrop}
-              // `pointerEvents: 'auto'` opts back in from the Portal root's
-              // `pointer-events: none`, which is set so the idle portal
-              // doesn't intercept clicks on the underlying app.
+              accessibilityLabel={label ? `Dismiss ${label}` : 'Dismiss dialog'}
               style={{
                 position: WEB_POSITION_FIXED,
-                top: 0,
-                left: 0,
-                right: 0,
-                bottom: 0,
                 zIndex: dialogZIndex.backdrop,
                 alignItems: 'center',
                 justifyContent: 'center',
                 paddingHorizontal: 20,
-                pointerEvents: 'auto',
               }}
             >
               <DialogBackdrop isClosing={isClosing} />
@@ -353,7 +352,7 @@ function CenterOrSideDialog({
               >
                 {children}
               </DialogPanel>
-            </Pressable>
+            </Backdrop>
           </ClosingContext.Provider>
         </Context.Provider>
       </Portal>
@@ -685,13 +684,12 @@ function SheetSurface({
   }, [dismissOnBackdrop, onDismiss]);
 
   return (
-    <View
-      style={[sheetStyles.root, { zIndex: backdropZIndex }, containerStyle, { pointerEvents: 'box-none' }]}
+    <OverlayRoot
+      style={[sheetStyles.root, { zIndex: backdropZIndex }, containerStyle]}
       {...(containerClassName ? ({ className: containerClassName } as Record<string, string>) : {})}
     >
-      <Pressable
+      <Backdrop
         testID={testID ? `${testID}-backdrop` : DIALOG_SHEET_BACKDROP_TESTID}
-        accessibilityRole="button"
         accessibilityLabel={label ? `Dismiss ${label}` : 'Dismiss dialog'}
         onPress={handleBackdropPress}
         disabled={!dismissOnBackdrop}
@@ -776,7 +774,7 @@ function SheetSurface({
           </View>
         )}
       </View>
-    </View>
+    </OverlayRoot>
   );
 }
 

package/src/dialog/DialogHeader.tsx

@@ -534,7 +534,7 @@ export const DialogNavHeader = memo(function DialogNavHeader({
     ) : null);
 
   return (
-    <View style={[styles.overlay, style, { pointerEvents: 'box-none' }]}>
+    <View pointerEvents="box-none" style={[styles.overlay, style]}>
       {/* Opaque (surface bg) at the top → transparent at the bottom, so scrolled
           content fades out under the bar. `onImage` swaps to a dark scrim so the
           chrome reads over media. Pure NativeWind — no SVG dependency. */}
@@ -546,7 +546,7 @@ export const DialogNavHeader = memo(function DialogNavHeader({
         }
         style={[StyleSheet.absoluteFill, { height: DIALOG_HEADER_OVERLAY_HEIGHT, pointerEvents: 'none' }]}
       />
-      <View style={[styles.navRow, { pointerEvents: 'box-none' }]}>
+      <View pointerEvents="box-none" style={styles.navRow}>
         <View style={styles.side}>{left}</View>
         <Animated.View
           testID="dialog-nav-title"

package/src/overlay/index.tsx

@@ -0,0 +1,115 @@
+/**
+ * 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 { memo, type ReactNode } from 'react';
+import { Platform, Pressable, StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
+
+import { WEB_POSITION_FIXED } from '../styles/web-view-style';
+
+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 function OverlayRoot({ children, style, testID }: OverlayRootProps) {
+  return (
+    <View pointerEvents="box-none" style={[styles.root, style]} testID={testID}>
+      {children}
+    </View>
+  );
+}
+
+OverlayRoot.displayName = 'OverlayRoot';
+
+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 const Backdrop = memo(function Backdrop({
+  onPress,
+  disabled = false,
+  style,
+  children,
+  accessibilityLabel = 'Dismiss',
+  testID,
+}: BackdropProps) {
+  const inert = disabled || !onPress;
+  return (
+    <Pressable
+      pointerEvents="auto"
+      onPress={inert ? undefined : onPress}
+      disabled={inert}
+      // A dimming layer is not a focus stop on web: Escape and the panel's own
+      // controls are the keyboard paths out. It stays labelled for screen
+      // readers that surface it as the dismiss affordance.
+      focusable={false}
+      accessibilityRole={inert ? undefined : 'button'}
+      accessibilityLabel={inert ? undefined : accessibilityLabel}
+      testID={testID}
+      style={[StyleSheet.absoluteFill, style]}
+    >
+      {children}
+    </Pressable>
+  );
+});
+
+const styles = StyleSheet.create({
+  root: {
+    // Web: the portal root is `fixed; inset: 0`, but a plain absolute child of
+    // it anchors to the document flow in some browsers once the page scrolls —
+    // pin this box to the viewport itself. Native: absolute fill inside the
+    // Outlet, which is already full-screen.
+    ...(Platform.OS === 'web'
+      ? { position: WEB_POSITION_FIXED, top: 0, left: 0, right: 0, bottom: 0 }
+      : StyleSheet.absoluteFillObject),
+  },
+});

package/src/portal/index.tsx

@@ -63,7 +63,7 @@ function createPortalGroup() {
   function Outlet() {
     const ctx = useContext(Context);
     if (Platform.OS === 'web') {
-      return <View style={styles.portalOutlet}>{ctx.outlet}</View>;
+      return <View pointerEvents="box-none" style={styles.portalOutlet}>{ctx.outlet}</View>;
     }
     return ctx.outlet;
   }
@@ -123,7 +123,9 @@ const styles = StyleSheet.create({
     left: 0,
     right: 0,
     bottom: 0,
-    pointerEvents: 'box-none',
+    // `box-none` rides on the PROP above — react-native-web only resolves that
+    // RN-only value from the prop path, so as a style entry it is silently
+    // inert and this full-viewport outlet swallows every click in the app.
     zIndex: Z_INDEX.portalRoot,
   },
 });

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';

package/src/tab-bar/TabBarBase.tsx

@@ -440,7 +440,7 @@ function TabBarBody({
   );
 
   return (
-    <View {...viewProps} style={[styles.root, style]}>
+    <View {...viewProps} pointerEvents="box-none" style={[styles.root, style]}>
       {/* Progressive blur rising from the screen's bottom edge behind the pill.
           Rendered CONDITIONALLY, and as nothing at all when off: the band is
           full-bleed and 114pt tall at a zero bottom inset, so it blurs whatever
@@ -462,7 +462,7 @@ function TabBarBody({
           }}
         />
       )}
-      <View style={[styles.barWrap, { marginBottom: bottomOffset }, constrainedWrapStyle]}>
+      <View pointerEvents="box-none" style={[styles.barWrap, { marginBottom: bottomOffset }, constrainedWrapStyle]}>
         <GestureDetector gesture={gesture}>
           <Animated.View style={barStyle}>
             <Surface theme={theme} style={shapeStyle} />
@@ -642,17 +642,19 @@ export function createTabBarButton(Glyph: ComponentType<TabBarGlyphProps>) {
 
 const styles = StyleSheet.create({
   root: {
+    // `pointerEvents="box-none"` is passed as a PROP on the views using these
+    // styles, NOT as a style entry: react-native-web resolves the RN-only
+    // `box-none` value only from the prop path, so as a style it silently does
+    // nothing and this full-width bottom band swallows every click in it. RNW
+    // logs a deprecation notice for the prop exactly once per session — the
+    // trade against a dead strip across the bottom of every page is not close.
     position: 'absolute',
     left: 0,
     right: 0,
     bottom: 0,
-    // In the style object, not as a prop: RN-Web deprecated the `pointerEvents`
-    // prop and warns on every render when it is used.
-    pointerEvents: 'box-none',
   },
   barWrap: {
     marginHorizontal: BAR_MARGIN,
-    pointerEvents: 'box-none',
   },
   highlight: {
     position: 'absolute',

package/src/toast/ToastHost.tsx

@@ -19,13 +19,14 @@
  *    swipe-to-dismiss would never receive touches. This provides its own, exactly
  *    as `bottom-sheet/index.web.tsx` does. Web consumers need no setup.
  *
- * `pointerEvents: 'box-none'` keeps the empty area click-through while the rows
+ * `OverlayRoot`'s `box-none` keeps the empty area click-through while the rows
  * themselves stay interactive.
  */
 import * as React from 'react';
 import { StyleSheet } from 'react-native';
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
 
+import { OverlayRoot } from '../overlay';
 import { Portal } from '../portal/index.web';
 import { WEB_POSITION_FIXED } from '../styles/web-view-style';
 import { Z_INDEX } from '../styles/z-index';
@@ -33,9 +34,14 @@ import type { ToastHostProps } from './types';
 
 export function ToastHost({ children, ToasterOverlayWrapper }: ToastHostProps) {
   const content = (
-    <GestureHandlerRootView style={styles.host}>
-      {children}
-    </GestureHandlerRootView>
+    // `OverlayRoot` carries the pointer-events opt-in as a PROP; as a style
+    // entry it never reached the DOM, so the rows inherited the portal root's
+    // `pointer-events: none` and no toast could be pressed or swiped away.
+    <OverlayRoot style={styles.host}>
+      <GestureHandlerRootView style={StyleSheet.absoluteFill}>
+        {children}
+      </GestureHandlerRootView>
+    </OverlayRoot>
   );
 
   return (
@@ -62,6 +68,5 @@ const styles = StyleSheet.create({
     // Inside `#bloom-portal-root` (which owns the document layer at 999999),
     // this keeps toasts above Dialog's surface (60) and tooltips (70).
     zIndex: Z_INDEX.toast,
-    pointerEvents: 'box-none',
   },
 });

package/src/zoomable-image-gallery/ZoomableImageGallery.tsx

@@ -28,6 +28,7 @@ import {
   GestureDetector,
 } from 'react-native-gesture-handler';
 import { useTheme } from '../theme/use-theme';
+import { Backdrop, OverlayRoot } from '../overlay';
 import { Portal } from '../portal';
 import { PressableWithHover } from '../pressable-with-hover';
 import {
@@ -423,19 +424,6 @@ const ZoomableImageGalleryInner = React.forwardRef<ZoomableImageGalleryHandle, Z
 
   React.useImperativeHandle(ref, () => ({ open }), [open]);
 
-  // Tapping the backdrop dismisses. Uses the same Gesture system as every
-  // other interaction in this component (image tap, pinch, pan, double-tap)
-  // instead of a plain RN Pressable, so the backdrop isn't the one interaction
-  // mixing two different event-handling systems under the same
-  // GestureHandlerRootView.
-  const backdropTapGesture = useMemo(
-    () =>
-      Gesture.Tap().onEnd(() => {
-        runOnJS(handleDismiss)();
-      }),
-    [handleDismiss]
-  );
-
   const panGesture = useMemo(
     () =>
       Gesture.Pan()
@@ -756,9 +744,16 @@ const ZoomableImageGalleryInner = React.forwardRef<ZoomableImageGalleryHandle, Z
   }, [handleDismiss, isOpen, pageTo]);
 
   const renderContent = () => (
-    <GestureHandlerRootView style={styles.modalContainer}>
-      <GestureDetector gesture={backdropTapGesture}>
-        <Animated.View style={StyleSheet.absoluteFill}>
+    <OverlayRoot style={styles.modalContainer}>
+      <GestureHandlerRootView style={StyleSheet.absoluteFill}>
+        {/* Shared `Backdrop` (a Pressable) rather than a `Gesture.Tap()`: the
+            viewer renders through the web Portal, whose root is
+            `pointer-events: none`, and a gesture handler on a node that never
+            receives pointer events simply never fires — tapping the backdrop
+            did nothing on web while Escape still closed. `Backdrop` opts back
+            in via the `pointerEvents` PROP, the only form that reaches the DOM
+            (see `src/overlay`). */}
+        <Backdrop onPress={handleDismiss} accessibilityLabel="Close image viewer">
           <AnimatedBlurView
             intensity={80}
             tint={theme.isDark ? 'dark' : 'light'}
@@ -769,8 +764,7 @@ const ZoomableImageGalleryInner = React.forwardRef<ZoomableImageGalleryHandle, Z
               style={[StyleSheet.absoluteFill, { backgroundColor: theme.colors.overlay }, backdropStyle]}
             />
           </AnimatedBlurView>
-        </Animated.View>
-      </GestureDetector>
+        </Backdrop>
 
       <GestureDetector gesture={panGesture}>
         <Animated.View
@@ -961,8 +955,9 @@ const ZoomableImageGalleryInner = React.forwardRef<ZoomableImageGalleryHandle, Z
             </Animated.View>
           ) : null}
         </Animated.View>
-      </GestureDetector>
-    </GestureHandlerRootView>
+        </GestureDetector>
+      </GestureHandlerRootView>
+    </OverlayRoot>
   );
 
   if (!isOpen) return null;