@oxyhq/bloom 0.69.0 → 0.70.0

package/src/__tests__/SheetShell.test.tsx

@@ -0,0 +1,82 @@
+import React from 'react';
+import { Text } from 'react-native';
+import { act, render } from '@testing-library/react-native';
+import type { ReactTestInstance } from 'react-test-renderer';
+
+import BottomSheet, { type BottomSheetRef } from '../bottom-sheet';
+import { useDialogControl } from '../dialog/context';
+import { SheetShell } from '../dialog/SheetShell';
+import { Z_INDEX } from '../styles/z-index';
+import { BloomThemeProvider } from '../theme/BloomThemeProvider';
+
+/**
+ * `BottomSheet` draws a decorative drag handle by default; `SheetShell` draws
+ * its own PRESSABLE one (tap to dismiss). Leaving both on painted two pills
+ * 2dp apart in every Bloom sheet menu, select, popover and context menu, so
+ * `SheetShell` turns the built-in one off.
+ *
+ * The built-in handle is identified by the z-index reserved for it, which no
+ * other element in the tree uses. `describe('control case')` below proves that
+ * query can actually FIND a handle — without it, a query that silently matched
+ * nothing would report the fix as working whether or not it did.
+ */
+const sheetHandles = (root: ReactTestInstance) =>
+  root.findAll((node) => {
+    const style: unknown = node.props?.style;
+    return (
+      typeof style === 'object' &&
+      style !== null &&
+      !Array.isArray(style) &&
+      (style as { zIndex?: number }).zIndex === Z_INDEX.sheetHandle
+    );
+  });
+
+function renderWithTheme(ui: React.ReactElement) {
+  return render(
+    <BloomThemeProvider mode="light" colorPreset="teal">
+      {ui}
+    </BloomThemeProvider>,
+  );
+}
+
+function OpenSheetShell() {
+  const control = useDialogControl();
+  React.useEffect(() => {
+    control.open();
+  }, [control]);
+  return (
+    <SheetShell control={control} label="Menu">
+      <Text>Row</Text>
+    </SheetShell>
+  );
+}
+
+describe('SheetShell drag handle', () => {
+  it('renders exactly one handle — its own pressable one', () => {
+    const { UNSAFE_root, getByHintText, getByText } = renderWithTheme(<OpenSheetShell />);
+    act(() => {});
+
+    expect(getByText('Row')).toBeTruthy();
+    // SheetShell's own handle: a Pressable that dismisses the sheet on tap.
+    // Matched on the hint rather than the label, which the backdrop shares.
+    expect(getByHintText('Tap to close')).toBeTruthy();
+    // BottomSheet's built-in decorative handle must be suppressed.
+    expect(sheetHandles(UNSAFE_root)).toHaveLength(0);
+  });
+
+  describe('control case', () => {
+    it('finds the built-in handle on a plain BottomSheet, which leaves it on', () => {
+      const ref = React.createRef<BottomSheetRef>();
+      const { UNSAFE_root } = renderWithTheme(
+        <BottomSheet ref={ref}>
+          <Text>Row</Text>
+        </BottomSheet>,
+      );
+      act(() => {
+        ref.current?.present();
+      });
+
+      expect(sheetHandles(UNSAFE_root).length).toBeGreaterThan(0);
+    });
+  });
+});

package/src/__tests__/dropdown-placement.test.ts

@@ -0,0 +1,90 @@
+import {
+  resolveDropdownPlacement,
+  type DropdownPlacementInput,
+} from '../overlay/dropdown-placement';
+
+const VIEWPORT = { width: 1000, height: 500 };
+const GUTTER = 8;
+
+/** A 200x40 trigger at (400, y), the shape the web `Menu` anchors against. */
+function trigger(y: number) {
+  return { top: y, bottom: y + 40, left: 400, right: 600 };
+}
+
+function place(overrides: Partial<DropdownPlacementInput>): { top: number; left: number } {
+  return resolveDropdownPlacement({
+    anchor: trigger(100),
+    size: { width: 180, height: 100 },
+    viewport: VIEWPORT,
+    offset: 6,
+    gutter: GUTTER,
+    align: 'end',
+    ...overrides,
+  });
+}
+
+describe('resolveDropdownPlacement', () => {
+  describe('vertical', () => {
+    it('sits below the anchor when it fits', () => {
+      // Trigger 100..140, surface 100 tall, offset 6 → 146..246, well inside 500.
+      expect(place({}).top).toBe(146);
+    });
+
+    it('flips above the anchor when there is no room below', () => {
+      // Trigger 420..460: below would end at 566, past 500 - 8. Above starts at
+      // 420 - 6 - 100 = 314, which clears the top gutter.
+      expect(place({ anchor: trigger(420) }).top).toBe(314);
+    });
+
+    it('prefers below when BOTH sides fit — flipping is a fallback, not a preference', () => {
+      expect(place({ anchor: trigger(200), size: { width: 180, height: 100 } }).top).toBe(246);
+    });
+
+    it('clamps into the viewport when neither side fits', () => {
+      // 460 tall against a 500 viewport: nothing fits either side of a
+      // mid-screen trigger, so it pins to 500 - 8 - 460 = 32.
+      expect(place({ anchor: trigger(200), size: { width: 180, height: 460 } }).top).toBe(32);
+    });
+
+    it('pins to the top gutter when the surface is taller than the viewport', () => {
+      // Overflowing the BOTTOM keeps the first rows reachable; the opposite
+      // choice would push the surface's start off-screen and strand every row.
+      expect(place({ anchor: trigger(200), size: { width: 180, height: 900 } }).top).toBe(GUTTER);
+    });
+
+    it('treats a zero-area anchor (a right-click point) as its own edge', () => {
+      const point = { top: 300, bottom: 300, left: 900, right: 900 };
+      expect(place({ anchor: point, offset: 0, align: 'start' }).top).toBe(300);
+      // 300 + 250 = 550 > 500 - 8, so it flips to 300 - 250 = 50.
+      expect(
+        place({ anchor: point, offset: 0, align: 'start', size: { width: 180, height: 250 } }).top,
+      ).toBe(50);
+    });
+  });
+
+  describe('horizontal', () => {
+    it("align 'end' lines the surface's right edge up with the anchor's", () => {
+      expect(place({ size: { width: 180, height: 100 } }).left).toBe(420);
+    });
+
+    it("align 'start' lines the surface's left edge up with the anchor's", () => {
+      expect(place({ align: 'start' }).left).toBe(400);
+    });
+
+    it('clamps a surface that would overflow the right edge', () => {
+      const point = { top: 100, bottom: 100, left: 980, right: 980 };
+      // 980 + 180 would reach 1160; pinned to 1000 - 8 - 180.
+      expect(place({ anchor: point, align: 'start' }).left).toBe(812);
+    });
+
+    it('clamps a surface that would overflow the left edge', () => {
+      const narrow = { top: 100, bottom: 140, left: 0, right: 20 };
+      // Right-aligning to x=20 would start at -160.
+      expect(place({ anchor: narrow }).left).toBe(GUTTER);
+    });
+
+    it('pins to the left gutter when the surface is wider than the viewport', () => {
+      expect(place({ size: { width: 1200, height: 100 } }).left).toBe(GUTTER);
+    });
+  });
+});

package/src/__tests__/optional-peer-imports.test.ts

@@ -50,6 +50,7 @@ import ts from 'typescript';
 
 const SRC = join(__dirname, '..');
 const PKG = JSON.parse(readFileSync(join(SRC, '..', 'package.json'), 'utf8')) as {
+  dependencies?: Record<string, string>;
   peerDependencies: Record<string, string>;
   peerDependenciesMeta: Record<string, { optional?: boolean }>;
 };
@@ -94,6 +95,7 @@ const DYNAMIC_BOUNDARIES: { peer: string; file: string }[] = [
   { peer: 'expo-haptics', file: 'hooks/haptics-module.ts' },
   { peer: 'nativewind', file: 'theme/color-scope/style-builder.ts' },
   { peer: 'expo-router', file: 'theme/adaptive-colors.ts' },
+  { peer: 'react-native-keyboard-controller', file: 'bottom-sheet/index.tsx' },
 ];
 
 /**
@@ -341,6 +343,58 @@ describe('optional peers are loaded through Metro’s optional-dependency form',
     expect(notOptional).toEqual([]);
   });
 
+  it('declares every package it loads at runtime, by import OR require', () => {
+    // The inverse direction, and the one that matters: every other assertion in
+    // this file starts from `peerDependenciesMeta` and asks whether the code
+    // matches it, so by construction none of them can see a package the manifest
+    // never mentions. `react-native-keyboard-controller` sat in `bottom-sheet`
+    // for exactly that reason — loaded, degraded correctly, and invisible to a
+    // consumer, who had no range to install against and no way to learn the
+    // integration existed.
+    //
+    // BOTH vectors are scanned. Checking only `require` would leave the more
+    // common one open: a plain `import` of an undeclared package is the ordinary
+    // way one arrives, it resolves fine as long as some transitive dependency
+    // happens to hoist it into `node_modules`, and it disappears the moment that
+    // unrelated package drops it. Verified by mutation in both directions — a
+    // require-only scan passes an undeclared static import.
+    const declared = new Set([
+      ...Object.keys(PKG.peerDependencies),
+      ...Object.keys(PKG.dependencies ?? {}),
+    ]);
+
+    /** `react-dom/client` -> `react-dom`, `@scope/pkg/sub` -> `@scope/pkg`. */
+    function packageOf(specifier: string): string | null {
+      if (specifier.startsWith('.') || specifier.startsWith('/')) return null;
+      const parts = specifier.split('/');
+      return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : (parts[0] as string);
+    }
+
+    const undeclared = new Set<string>();
+    for (const file of files) {
+      const source = parse(file);
+      const relative = file.slice(SRC.length + 1);
+
+      const check = (specifier: string | null, line: number, verb: string): void => {
+        // A non-literal specifier names no package to check; the shape rule for
+        // those is the separate `VARIABLE_REQUIRE_ALLOWED` scan below.
+        if (specifier === null) return;
+        const pkg = packageOf(specifier);
+        if (pkg === null || declared.has(pkg)) return;
+        undeclared.add(
+          `${relative}:${line}  ${verb} '${pkg}', which appears in neither dependencies nor ` +
+            'peerDependencies — a consumer cannot know the integration exists or which ' +
+            'versions satisfy it',
+        );
+      };
+
+      for (const { specifier, line } of requireCalls(source)) check(specifier, line, 'requires');
+      for (const { specifier, line } of valueImportSpecifiers(source)) check(specifier, line, 'imports');
+    }
+
+    expect([...undeclared].sort()).toEqual([]);
+  });
+
   it('loads each optional peer from exactly the documented boundary file', () => {
     // Both directions in one assertion: a boundary that moved (or was deleted)
     // leaves a stale table entry; a second load site for the same peer, or a new

package/src/context-menu/index.web.tsx

@@ -9,6 +9,7 @@ import React, {
   useCallback,
   useContext,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -22,6 +23,10 @@ import { Portal } from '../portal/index.web';
 import { useInteractionState } from '../hooks/useInteractionState';
 import { createOverlayZIndex } from '../styles/z-index';
 import { WEB_POSITION_FIXED } from '../styles/web-view-style';
+import {
+  resolveDropdownPlacement,
+  type DropdownPlacement,
+} from '../overlay/dropdown-placement';
 import { bloomShadowStyle } from '../design-tokens/shadows';
 import { ItemCtx, useItemContext } from './context';
 import type {
@@ -36,6 +41,7 @@ import type {
 } from './types';
 
 const contextMenuZIndex = createOverlayZIndex();
+const VIEWPORT_GUTTER = 8;
 
 // ---------------------------------------------------------------------------
 // Web-specific context (extends base with position)
@@ -156,6 +162,38 @@ export function ContextMenuContent({ children, style }: ContextMenuContentProps)
   const ctx = useWebContextMenuContext();
   const theme = useTheme();
   const { isOpen, close, position } = ctx;
+  // The mounted menu node, as STATE rather than a bare ref: placement has to
+  // measure it, and `Portal` renders null on its first pass (it resolves its
+  // host in its own layout effect), so the node lands one render after the
+  // menu opens. An effect keyed only on `position` would measure nothing.
+  const [menuNode, setMenuNode] = useState<HTMLElement | null>(null);
+  const [placement, setPlacement] = useState<DropdownPlacement | null>(null);
+
+  const attachMenu = useCallback((node: View | null) => {
+    setMenuNode(node as unknown as HTMLElement | null);
+  }, []);
+
+  // The right-click point is a zero-area anchor, so the surface sits below-right
+  // of the cursor when it fits, flips above when it doesn't, and clamps into the
+  // viewport when neither fits. Without this a menu opened near an edge hung off
+  // the fold with its rows unreachable.
+  useLayoutEffect(() => {
+    if (!position || !menuNode || typeof window === 'undefined') {
+      setPlacement(null);
+      return;
+    }
+    const surface = menuNode.getBoundingClientRect();
+    setPlacement(
+      resolveDropdownPlacement({
+        anchor: { top: position.y, bottom: position.y, left: position.x, right: position.x },
+        size: { width: surface.width, height: surface.height },
+        viewport: { width: window.innerWidth, height: window.innerHeight },
+        offset: 0,
+        gutter: VIEWPORT_GUTTER,
+        align: 'start',
+      }),
+    );
+  }, [position, menuNode]);
 
   useEffect(() => {
     if (!isOpen || typeof document === 'undefined') return;
@@ -179,11 +217,14 @@ export function ContextMenuContent({ children, style }: ContextMenuContentProps)
         accessibilityLabel="Close context menu"
       />
       <View
+        ref={attachMenu}
         style={[
           styles.dropdown,
           {
-            top: position.y,
-            left: position.x,
+            // The raw click point is the pre-measurement anchor; the layout
+            // effect above replaces it before the browser paints.
+            top: placement?.top ?? position.y,
+            left: placement?.left ?? position.x,
             backgroundColor: theme.isDark
               ? theme.colors.backgroundSecondary
               : theme.colors.background,
@@ -358,7 +399,10 @@ const styles = StyleSheet.create({
     borderRadius: 6,
     overflow: 'hidden',
     paddingHorizontal: 10,
-    minHeight: 32,
+    // Matches the native sheet row (`index.tsx`). Bloom's web build is what
+    // renders on touch tablets, where this dropdown — not the sheet — is the
+    // menu, so the row carries the same 44dp target on both platforms.
+    minHeight: 44,
   },
   itemText: {
     flex: 1,

package/src/dialog/SheetShell.tsx

@@ -100,6 +100,11 @@ export function SheetShell({
       detached
       backdropOpacity={0.7}
       style={sheetStyle}
+      // `SheetShell` draws its own PRESSABLE handle below (tap to dismiss);
+      // `BottomSheet`'s built-in one is decorative and defaults to on, so
+      // leaving it enabled painted two pills 2dp apart in every Bloom sheet
+      // menu, select, popover and context menu.
+      showHandle={false}
     >
       <Context.Provider value={context}>
         <SheetHandle onPress={() => close()} />

package/src/menu/index.web.tsx

@@ -18,6 +18,7 @@ import type { DialogControlProps } from '../dialog/types';
 import { Portal } from '../portal/index.web';
 import { createDropdownZIndex } from '../styles/z-index';
 import { WEB_POSITION_FIXED } from '../styles/web-view-style';
+import { resolveDropdownPlacement } from '../overlay/dropdown-placement';
 import { bloomShadowStyle } from '../design-tokens/shadows';
 import {
   MenuContext,
@@ -198,6 +199,22 @@ export function MenuContent({
   const theme = useTheme();
   const context = useMenuContext();
   const [position, setPosition] = useState<ViewStyle | null>(null);
+  // The mounted dropdown node, as STATE rather than a bare ref: positioning has
+  // to measure it, and `Portal` renders null on its first pass (it resolves its
+  // host in its own layout effect), so the node lands one render after
+  // `isOpen` flips. An effect keyed only on `isOpen` would measure nothing.
+  const [dropdownNode, setDropdownNode] = useState<HTMLElement | null>(null);
+
+  const attachDropdown = useCallback(
+    (node: View | null) => {
+      // The shared ref stays in sync — `Menu`'s outside-pointerdown check reads it.
+      if (context.dropdownRef) {
+        context.dropdownRef.current = node;
+      }
+      setDropdownNode(node as unknown as HTMLElement | null);
+    },
+    [context.dropdownRef],
+  );
 
   useLayoutEffect(() => {
     if (!context.isOpen || typeof window === 'undefined') {
@@ -205,27 +222,28 @@ export function MenuContent({
     }
 
     const triggerNode = context.triggerRef?.current as HTMLElement | null;
-    if (!triggerNode?.getBoundingClientRect) {
+    if (!triggerNode?.getBoundingClientRect || !dropdownNode) {
       return;
     }
 
     const updatePosition = () => {
       const rect = triggerNode.getBoundingClientRect();
-      const width = Math.max(180, rect.width);
-      const availableRight = window.innerWidth - VIEWPORT_GUTTER;
-      const left = Math.min(
-        Math.max(VIEWPORT_GUTTER, rect.right - width),
-        Math.max(VIEWPORT_GUTTER, availableRight - width),
-      );
-      const top = Math.min(
-        rect.bottom + MENU_OFFSET,
-        Math.max(VIEWPORT_GUTTER, window.innerHeight - VIEWPORT_GUTTER),
-      );
+      // Measured BEFORE `minWidth` is applied, so the final surface can only be
+      // wider than this — and a wider surface wraps less, so the measured height
+      // is an upper bound. Erring that way flips early in a tie, never late.
+      const surface = dropdownNode.getBoundingClientRect();
+      const width = Math.max(surface.width, rect.width);
 
       setPosition({
         position: WEB_POSITION_FIXED,
-        top,
-        left,
+        ...resolveDropdownPlacement({
+          anchor: rect,
+          size: { width, height: surface.height },
+          viewport: { width: window.innerWidth, height: window.innerHeight },
+          offset: MENU_OFFSET,
+          gutter: VIEWPORT_GUTTER,
+          align: 'end',
+        }),
         right: undefined,
         bottom: undefined,
         minWidth: width,
@@ -240,7 +258,7 @@ export function MenuContent({
       window.removeEventListener('resize', updatePosition);
       window.removeEventListener('scroll', updatePosition, true);
     };
-  }, [context.isOpen, context.triggerRef]);
+  }, [context.isOpen, context.triggerRef, dropdownNode]);
 
   if (!context.isOpen) {
     return null;
@@ -249,7 +267,7 @@ export function MenuContent({
   return (
     <Portal>
       <View
-        ref={context.dropdownRef as React.Ref<View>}
+        ref={attachDropdown}
         style={[
           styles.dropdown,
           {
@@ -390,6 +408,14 @@ const styles = StyleSheet.create({
     zIndex: menuZIndex.root,
   },
   dropdown: {
+    // Fixed from the outset, not only once positioned: the `Portal` root is a
+    // block container, so a static child would stretch to the full viewport
+    // width and the pre-position measurement would under-read the height (less
+    // wrapping at a width the surface never actually has). A fixed box
+    // shrink-wraps to the same width it ends up with.
+    position: WEB_POSITION_FIXED,
+    top: 0,
+    left: 0,
     borderRadius: 8,
     padding: 4,
     borderWidth: 1,
@@ -409,7 +435,10 @@ const styles = StyleSheet.create({
     borderRadius: 6,
     overflow: 'hidden',
     paddingHorizontal: 10,
-    minHeight: 32,
+    // Matches the native sheet row (`index.tsx`). Bloom's web build is what
+    // renders on touch tablets, where this dropdown — not the sheet — is the
+    // menu, so the row carries the same 44dp target on both platforms.
+    minHeight: 44,
   },
   webItemText: {
     flex: 1,

package/src/overlay/dropdown-placement.ts

@@ -0,0 +1,88 @@
+/**
+ * Placement arithmetic for a portaled dropdown surface — shared by the web
+ * `Menu` and `ContextMenu` forks, which anchor differently (a trigger's rect
+ * vs. a right-click point) but need the same fit / flip / clamp decision.
+ *
+ * Internal: deliberately NOT re-exported from `overlay/index.ts`. The web forks
+ * import it directly, the same way `dialog/SheetShell` is shared without
+ * becoming public API.
+ *
+ * Kept as a pure function so the arithmetic is unit-testable on its own — the
+ * DOM half (measuring the surface before positioning it) is the call site's
+ * job and is verified in a browser.
+ */
+
+/** Viewport-relative box the surface is positioned against. A right-click point is a zero-area anchor. */
+export interface DropdownAnchor {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+
+export interface DropdownPlacementInput {
+  anchor: DropdownAnchor;
+  /** The surface's size, measured at the width it will finally be laid out at. */
+  size: { width: number; height: number };
+  viewport: { width: number; height: number };
+  /** Gap left between the anchor and the surface on the vertical axis. */
+  offset: number;
+  /** Minimum distance kept from every viewport edge. */
+  gutter: number;
+  /**
+   * Which of the surface's horizontal edges lines up with the anchor's matching
+   * edge: `'start'` pins left-to-left (a menu opening rightward from a click),
+   * `'end'` pins right-to-right (a trigger-anchored dropdown).
+   */
+  align: 'start' | 'end';
+}
+
+export interface DropdownPlacement {
+  top: number;
+  left: number;
+}
+
+/**
+ * Clamp into `[min, max]`, resolving an inverted range to `min`.
+ *
+ * The range inverts exactly when the surface is larger than the viewport minus
+ * its gutters. Preferring `min` then pins the surface to the top/left gutter and
+ * lets it overflow the far edge, so its FIRST rows stay reachable — the opposite
+ * choice would push its start off-screen and strand every row.
+ */
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(value, max));
+}
+
+/**
+ * Resolve the viewport-relative `top`/`left` for a dropdown surface.
+ *
+ * Vertical: sit below the anchor when it fits, else flip above it, else clamp
+ * into the viewport. Horizontal: align per `align`, then clamp into the
+ * viewport.
+ */
+export function resolveDropdownPlacement({
+  anchor,
+  size,
+  viewport,
+  offset,
+  gutter,
+  align,
+}: DropdownPlacementInput): DropdownPlacement {
+  const below = anchor.bottom + offset;
+  const above = anchor.top - offset - size.height;
+
+  const fitsBelow = below + size.height <= viewport.height - gutter;
+  const fitsAbove = above >= gutter;
+
+  const top = fitsBelow
+    ? below
+    : fitsAbove
+      ? above
+      : clamp(below, gutter, viewport.height - gutter - size.height);
+
+  const preferredLeft = align === 'end' ? anchor.right - size.width : anchor.left;
+  const left = clamp(preferredLeft, gutter, viewport.width - gutter - size.width);
+
+  return { top, left };
+}

package/src/select/index.web.tsx

@@ -358,7 +358,11 @@ const styles = StyleSheet.create({
   item: {
     position: 'relative',
     flexDirection: 'row',
-    minHeight: 25,
+    // Matches the native sheet row (`index.tsx`) and the web `Menu` row. Bloom's
+    // web build is what renders on touch tablets, where this dropdown — not the
+    // sheet — is the select, so the row carries the same 44dp target on both
+    // platforms.
+    minHeight: 44,
     paddingLeft: 30,
     paddingRight: 8,
     alignItems: 'center',

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

@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import {
   View,
   Text,
@@ -180,8 +180,6 @@ const ZoomableImageGalleryInner = React.forwardRef<ZoomableImageGalleryHandle, Z
   const originScale = useSharedValue(1);
 
   const pagerRef = useRef<ScrollView>(null);
-  // Latch the index the pager must land on once it has mounted + laid out.
-  const pendingIndexRef = useRef(0);
   // Mirror of `activeIndex` readable synchronously from callbacks/worklets
   // (`handleDismiss` runs via `runOnJS` and from `Pressable.onPress`, where the
   // state closure can be stale). Kept in lockstep by `setActiveIndexBoth`.
@@ -360,8 +358,8 @@ const ZoomableImageGalleryInner = React.forwardRef<ZoomableImageGalleryHandle, Z
   ]);
 
   // Reveal the swipeable pager once the open animation has settled. The index it
-  // lands on is held in `pendingIndexRef` (set synchronously in `open`) and
-  // applied in `onPagerLayout`.
+  // lands on is `activeIndexRef` (set synchronously in `open`), seated by the
+  // layout effect below.
   const revealPager = useCallback(() => {
     setPagerReady(true);
   }, []);
@@ -388,7 +386,6 @@ const ZoomableImageGalleryInner = React.forwardRef<ZoomableImageGalleryHandle, Z
         if (r !== undefined) initialRatios[i] = r;
       });
       setPageRatios(initialRatios);
-      pendingIndexRef.current = safeIndex;
 
       // Resolve the opening ratio if it was not yet known, then re-fit.
       if (knownRatio === undefined) {
@@ -595,14 +592,31 @@ const ZoomableImageGalleryInner = React.forwardRef<ZoomableImageGalleryHandle, Z
     [updateIndexFromOffset]
   );
 
-  // When the pager mounts, jump it to the open index without animation so the
-  // swap from the open-image to the pager is seamless.
-  const onPagerLayout = useCallback(() => {
-    const idx = pendingIndexRef.current;
-    if (idx > 0) {
-      pagerRef.current?.scrollTo({ x: idx * SCREEN_WIDTH, animated: false });
-    }
-  }, [SCREEN_WIDTH]);
+  // Re-seat the pager on the CURRENT page, without animation, whenever it mounts
+  // or the page width changes.
+  //
+  // Rotation is the case that needs this: the pager's retained scroll offset is
+  // in PIXELS, so when `SCREEN_WIDTH` changes the page widths change underneath
+  // a stale offset and the pager lands between two pages — showing the wrong
+  // image while the counter and dots still point at the right one. Nothing else
+  // corrects it: `contentOffset` below is only an initial value, and `pageTo`
+  // runs only on an explicit page change. Reading the index from
+  // `activeIndexRef` (rather than the index the viewer was opened at) is what
+  // makes it land on the page the user is actually looking at.
+  //
+  // This is a layout EFFECT rather than the pager's `onLayout` on purpose. The
+  // pages are sized from `SCREEN_WIDTH`, so the scroll offset is only meaningful
+  // once React has committed a render carrying the new width. `onLayout` fires
+  // from a different signal (the pager's own frame) than the one that resizes
+  // the pages (`useWindowDimensions`), and the two are not ordered against each
+  // other — so an `onLayout` handler can run holding the previous `SCREEN_WIDTH`
+  // and re-seat the pager to the offset it already had. Keying the effect on
+  // `SCREEN_WIDTH` makes the two agree by construction, and running it before
+  // paint keeps the corrected offset from being visible as a jump.
+  useLayoutEffect(() => {
+    if (!pagerReady) return;
+    pagerRef.current?.scrollTo({ x: activeIndexRef.current * SCREEN_WIDTH, y: 0, animated: false });
+  }, [pagerReady, SCREEN_WIDTH]);
 
   // Double-tap toggles zoom: reset when already zoomed, else zoom to the tapped
   // point (biased toward it, clamped near the image center). `x`/`y` are local
@@ -834,8 +848,7 @@ const ZoomableImageGalleryInner = React.forwardRef<ZoomableImageGalleryHandle, Z
                 // instead of paging away from it.
                 scrollEnabled={!isZoomed}
                 showsHorizontalScrollIndicator={false}
-                contentOffset={{ x: pendingIndexRef.current * SCREEN_WIDTH, y: 0 }}
-                onLayout={onPagerLayout}
+                contentOffset={{ x: activeIndexRef.current * SCREEN_WIDTH, y: 0 }}
                 onMomentumScrollEnd={onPagerScroll}
                 {...(Platform.OS === 'web' ? { onScroll: onPagerScroll } : {})}
                 scrollEventThrottle={16}