@astryxdesign/core 0.4.4 → 0.4.5-canary.013e728

package/src/BottomSheet/useSheetGestures.test.ts

@@ -129,7 +129,9 @@ describe('useSheetGestures', () => {
     expect(onDismiss).not.toHaveBeenCalled();
     expect(hook.result.current.settledOffset).toBe(200);
     expect(onSnap).toHaveBeenLastCalledWith(200);
-    expect(onScrimOpacity).toHaveBeenLastCalledWith(0.3);
+    // The 200px stop is half the sheet — a working surface, not a peek — so
+    // the backdrop stays full there.
+    expect(onScrimOpacity).toHaveBeenLastCalledWith(1);
   });
 
   it('expands to the tallest detent on a fast upward flick', () => {
@@ -218,13 +220,62 @@ describe('useSheetGestures', () => {
     expect(hook.result.current.settledLayoutOffset).toBe(0);
   });
 
-  it('treats the only collapsed stop as a peek, like the scrim does', () => {
+  it('re-anchors to the same stop when the snap heights change at rest', () => {
+    const onDismiss = vi.fn();
+    const hook = renderHook(
+      (props: UseSheetGesturesOptions) => useSheetGestures(props),
+      {
+        initialProps: {
+          isOpen: true,
+          onDismiss,
+          snapHeights: () => [200],
+        },
+      },
+    );
+    const t = makeTarget();
+
+    // Settle on the one collapsed stop: 400 - 200 = 200px of travel.
+    down(hook, 0, 0, t);
+    move(hook, 180, 700, t);
+    up(hook, 180, 1100, t);
+    act(() => hook.result.current.completeScrollAreaSettle());
+    expect(hook.result.current.settledOffset).toBe(200);
+
+    // A new resolver is a new set of stops. The sheet is resting on the one it
+    // names, so it follows: a 150px stop is 250px of travel. The resolver is
+    // read during render, not from a passive effect — the re-anchor runs in a
+    // layout effect, which would otherwise still see the previous one.
+    hook.rerender({
+      isOpen: true,
+      onDismiss,
+      snapHeights: () => [150],
+    });
+
+    expect(hook.result.current.settledOffset).toBe(250);
+    expect(hook.result.current.settledLayoutOffset).toBe(250);
+  });
+
+  it('resizes the scrolling area at a collapsed stop that is a working height', () => {
+    // A 200px stop on the 400px sheet is half of it: the scrolling area takes
+    // that travel as layout height rather than sliding the sheet away.
     const {hook} = setup({snapHeights: () => [200]});
     const t = makeTarget();
     down(hook, 0, 0, t);
     move(hook, 180, 700, t);
     up(hook, 180, 1100, t);
     expect(hook.result.current.settledOffset).toBe(200);
+    expect(hook.result.current.settledLayoutOffset).toBe(200);
+  });
+
+  it('treats the only collapsed stop as a peek when it is a sliver', () => {
+    // 60px of a 400px sheet is inside the quarter that makes a peek, so the
+    // sheet keeps its full layout height and slides below the viewport.
+    const {hook} = setup({snapHeights: () => [60]});
+    const t = makeTarget();
+    down(hook, 0, 0, t);
+    move(hook, 320, 700, t);
+    up(hook, 320, 1100, t);
+    expect(hook.result.current.settledOffset).toBe(340);
     expect(hook.result.current.settledLayoutOffset).toBe(0);
   });
 
@@ -297,20 +348,22 @@ describe('useSheetGestures', () => {
 
     expect(onDismiss).not.toHaveBeenCalled();
     expect(hook.result.current.settledOffset).toBe(200);
-    expect(onScrimOpacity).toHaveBeenLastCalledWith(0.3);
+    // Rebounding restores the scrim the 200px stop rests under — full, since
+    // half a sheet is a working surface rather than a glance.
+    expect(onScrimOpacity).toHaveBeenLastCalledWith(1);
   });
 
   it('fades the scrim from full toward the peek floor as it collapses onto the peek detent', () => {
     const onScrimOpacity = vi.fn();
-    // Sheet 400, detents at 200 and 300 -> offsets [0, 100, 200]. The fade
-    // spans the mid detent (offset 100) to the peek detent (offset 200):
-    // full at/above 100, thinned to the peek floor (0.3) at/below 200.
-    const {hook} = setup({snapHeights: () => [200, 300], onScrimOpacity});
+    // Sheet 400, stops at 300 and a 60px sliver -> offsets [0, 100, 340]. The
+    // fade spans the mid detent (offset 100) to the peek (offset 340): full
+    // at/above 100, thinned to the peek floor (0.3) at/below 340.
+    const {hook} = setup({snapHeights: () => [60, 300], onScrimOpacity});
     const t = makeTarget();
     down(hook, 0, 0, t);
     move(hook, 60, 200, t); // offset 60, above the mid detent -> full
-    move(hook, 150, 600, t); // offset 150, halfway -> between 1 and 0.3 (~0.65)
-    move(hook, 220, 1000, t); // offset 220, past the peek -> peek floor
+    move(hook, 220, 600, t); // offset 220, halfway -> between 1 and 0.3 (~0.65)
+    move(hook, 360, 1000, t); // offset 360, past the peek -> peek floor
     const values = onScrimOpacity.mock.calls.map(c => Number(c[0]));
     expect(values[0]).toBe(1);
     expect(values[1]).toBeGreaterThan(0.55);
@@ -320,14 +373,14 @@ describe('useSheetGestures', () => {
 
   it('thins the scrim to the peek floor when settled at the peek detent (still modal)', () => {
     const onScrimOpacity = vi.fn();
-    const {hook} = setup({snapHeights: () => [200, 300], onScrimOpacity});
+    const {hook} = setup({snapHeights: () => [60, 300], onScrimOpacity});
     const t = makeTarget();
-    // Slow drag down to the peek detent (offset 200).
+    // Slow drag down to the peek detent (offset 340).
     down(hook, 0, 0, t);
-    move(hook, 100, 400, t);
-    move(hook, 200, 900, t);
-    up(hook, 200, 1400, t);
-    expect(hook.result.current.settledOffset).toBe(200);
+    move(hook, 170, 400, t);
+    move(hook, 340, 900, t);
+    up(hook, 340, 1400, t);
+    expect(hook.result.current.settledOffset).toBe(340);
     // Last reported opacity (on settle) is the peek floor, not fully hidden —
     // the sheet is still modal, so the backdrop keeps a minimum dim.
     const values = onScrimOpacity.mock.calls.map(c => Number(c[0]));
@@ -726,6 +779,51 @@ describe('useSheetGestures', () => {
       return el;
     }
 
+    // iOS Safari raises PointerEvents for a finger under the SAME numeric id
+    // it puts in `Touch.identifier`, so a drag the touch path starts is keyed
+    // to a live pointer. WebKit takes that pointer's capture straight back,
+    // and the `lostpointercapture` that follows used to cancel the drag one
+    // event after it began — leaving the sheet inert for the rest of the pull
+    // while the handle still worked. Every browser that keeps the two id
+    // spaces apart hides this, which is why it only showed up on device.
+    it('survives a lostpointercapture for the finger driving it', () => {
+      const {hook} = setup({snapHeights: () => [200]});
+      const el = midDetentScroller(hook, 600); // parked at the content end
+      act(() => {
+        touch(el, 'touchstart', 500, 7);
+        touch(el, 'touchmove', 450, 7); // promotes at the armed bottom edge
+      });
+      expect(hook.result.current.isDragging).toBe(true);
+      act(() => {
+        hook.result.current.bodyProps.onLostPointerCapture(
+          pointerEvent(450, 0, el, 7), // same id as the touch: iOS does this
+        );
+      });
+      expect(hook.result.current.isDragging).toBe(true);
+      act(() => {
+        touch(el, 'touchmove', 400, 7);
+      });
+      // 100px of pull past the touchstart, from the 200px detent.
+      expect(hook.result.current.dragOffset).toBe(100);
+    });
+
+    // `pointercancel` for that same finger arrives the moment WebKit claims
+    // the gesture. Ending the drag on it settles the sheet mid-pull.
+    it('does not end the touch drag on a pointercancel for that finger', () => {
+      const {hook} = setup({snapHeights: () => [200]});
+      const el = midDetentScroller(hook, 600);
+      act(() => {
+        touch(el, 'touchstart', 500, 7);
+        touch(el, 'touchmove', 450, 7);
+      });
+      act(() => {
+        hook.result.current.bodyProps.onPointerCancel(
+          pointerEvent(450, 0, el, 7),
+        );
+      });
+      expect(hook.result.current.isDragging).toBe(true);
+    });
+
     it('hands off when the content runs out under a moving finger', () => {
       const {hook} = setup({snapHeights: () => [200]});
       const el = midDetentScroller(hook, 300); // finger lands mid-content

package/src/BottomSheet/useSheetGestures.ts

@@ -19,14 +19,16 @@
  * the part the scrolling area gives up as layout height, and the remainder is
  * a transform. Gestures and snaps only ever move the transform, so they stay
  * on the compositor; layout height changes at rest, in one transition-free
- * render whose visible geometry is identical. The peek detent keeps the full
- * height and slides below the viewport instead of reflowing to a sliver.
+ * render whose visible geometry is identical. A peek detent — a stop that is
+ * only a sliver of the sheet — keeps the full height and slides below the
+ * viewport instead of reflowing to that sliver.
  *
- * Those are pixels, and the detents behind them are viewport fractions, so a
- * sheet at rest re-resolves its detent on `resize` / `orientationchange` and
- * re-anchors to the new geometry without animating. The detent it returns to
- * is tracked by index: the pixels stop meaning the same thing when the
- * viewport changes, the stop the user chose does not.
+ * Those are pixels, and the stops behind them are relative to the viewport, so
+ * a sheet at rest re-resolves its detent on `resize` / `orientationchange`,
+ * and whenever the host swaps the snap points, and re-anchors to the new
+ * geometry without animating. The detent it returns to is tracked by index:
+ * the pixels stop meaning the same thing when the viewport changes, the stop
+ * the user chose does not.
  *
  * On touch, the scrolling body hands the gesture to the sheet at a scroll
  * edge. Two shapes, because the browser only offers one of them a choice: a
@@ -66,11 +68,20 @@ import {
 import {useMediaQuery} from '../hooks';
 import {
   computeDetentOffsets,
-  isPeekOffset,
+  peekOffsetFor,
   resolveSettleOffset,
   scrimOpacityForOffset,
 } from './snapOffsets';
 
+/**
+ * The stops a sheet of a given height rests at: offsets from fully-open in px,
+ * ascending, plus which of them (if any) is the peek.
+ */
+interface SheetDetents {
+  offsets: number[];
+  peekOffset: number | null;
+}
+
 // A flick (fast throw) dismisses (down) or expands (up) regardless of where
 // it ends. Requires both a speed and a distance floor so a small nudge
 // doesn't trigger it.
@@ -82,6 +93,19 @@ const DISMISS_OVERSHOOT_RATIO = 0.4;
 // Within this many px of a detent, the live drag is magnetically eased toward
 // it so it "clicks" into place instead of hovering just off the mark.
 const MAGNET_RANGE = 40;
+// The touch path drives the sheet through the same machinery the pointer path
+// uses, by handing it a pointer-shaped object built from a `Touch`. On iOS
+// Safari that object is indistinguishable from the real thing: WebKit raises
+// PointerEvents for a finger under the SAME numeric id it puts in
+// `Touch.identifier`, so such a drag is keyed to a live pointer and the
+// handlers that guard a mouse drag fire against it. Mark the synthetic object
+// so they can tell the two apart.
+type SyntheticTouchPointer = ReactPointerEvent & {syntheticTouch?: true};
+
+function isSyntheticTouch(event: ReactPointerEvent): boolean {
+  return (event as SyntheticTouchPointer).syntheticTouch === true;
+}
+
 // Rubber-band factor for dragging up past fully-open, capped at OVERSCROLL_MAX
 // (the sheet reserves that much bottom padding for the lift to reveal).
 const OVERSCROLL_RESISTANCE = 0.35;
@@ -192,6 +216,9 @@ export interface UseSheetGesturesOptions {
    * (rotation, a resized desktop window, collapsing browser chrome). The fully
    * open height is always the tallest detent. Omit for a single-height sheet
    * (a drag then only dismisses or springs back).
+   *
+   * Keep the identity stable: a new function is read as new stops, and
+   * re-anchors a resting sheet to them.
    */
   snapHeights?: () => number[];
   /** Notified when the settled visible detent height (px) changes. */
@@ -279,7 +306,7 @@ export interface UseSheetGesturesResult {
   /**
    * How much of `settledOffset` is expressed as layout height rather than as a
    * transform. Equals `settledOffset` at the resizing detents; 0 at fully open
-   * and at the peek, which keep the sheet's full height (see isPeekOffset).
+   * and at the peek, which keep the sheet's full height (see peekOffsetFor).
    */
   settledLayoutOffset: number;
 }
@@ -326,7 +353,7 @@ export function useSheetGestures({
   const [scrollPreservationInset, setScrollPreservationInset] = useState(0);
   // How much of the settled travel is expressed as layout height. Equal to
   // settledOffset for the resizing detents, and 0 at fully open and at the
-  // peek (see isPeekOffset), which keep the full height and use a transform.
+  // peek (see peekOffsetFor), which keep the full height and use a transform.
   const [settledLayoutOffset, setSettledLayoutOffset] = useState(0);
   const settledLayoutOffsetRef = useRef(0);
   // WHICH detent the sheet rests on, as an index into the resolved list. The
@@ -419,21 +446,30 @@ export function useSheetGestures({
   const isOpenRef = useRef(isOpen);
   isOpenRef.current = isOpen;
 
+  // The resolver is refreshed during render, not with the callbacks below: the
+  // layout effect that re-anchors on a change to it runs BEFORE passive
+  // effects, so a resolver parked in one would still be the previous set of
+  // stops by the time the re-anchor read it.
+  const snapHeightsRef = useRef(snapHeights);
+  snapHeightsRef.current = snapHeights;
+
   const onDismissRef = useRef(onDismiss);
   const canDismissRef = useRef(canDismiss);
   const onSnapRef = useRef(onSnap);
   const onScrimOpacityRef = useRef(onScrimOpacity);
-  const snapHeightsRef = useRef(snapHeights);
   useEffect(() => {
     onDismissRef.current = onDismiss;
     canDismissRef.current = canDismiss;
     onSnapRef.current = onSnap;
     onScrimOpacityRef.current = onScrimOpacity;
-    snapHeightsRef.current = snapHeights;
   });
 
   // Live drag bookkeeping (refs so pointermove doesn't churn renders).
   const dragStateRef = useRef<{
+    // Whether the touch path drives this drag. Such a drag holds no pointer
+    // capture and takes its events from `touchmove`, so every real-pointer
+    // handler has to leave it alone.
+    syntheticTouch: boolean;
     pointerId: number;
     startCoord: number;
     lastCoord: number;
@@ -545,20 +581,22 @@ export function useSheetGestures({
     return sheetElRef.current?.getBoundingClientRect().height ?? 0;
   }, []);
 
-  // Detent translate offsets (px) from the tallest detent, ascending. Exclude
-  // the border-box portion reserved below the viewport before comparing the
-  // candidate visible heights; otherwise every snap point lands that many px
-  // too low. Snap heights are resolved lazily so they track the viewport.
-  const detentOffsets = useCallback((height: number): number[] => {
+  // Detent translate offsets (px) from the tallest detent, ascending, plus the
+  // peek among them. Exclude the border-box portion reserved below the
+  // viewport before comparing the candidate visible heights; otherwise every
+  // snap point lands that many px too low. Snap heights are resolved lazily so
+  // they track the viewport.
+  const resolveDetents = useCallback((height: number): SheetDetents => {
     const visibleSheetHeight = visibleHeightForOffset(
       height,
       0,
       offscreenBlockEndInsetRef.current,
     );
-    return computeDetentOffsets(
+    const offsets = computeDetentOffsets(
       visibleSheetHeight,
       snapHeightsRef.current?.() ?? [],
     );
+    return {offsets, peekOffset: peekOffsetFor(offsets, visibleSheetHeight)};
   }, []);
 
   // The height the sheet WOULD have fully open, right now. While it rests at a
@@ -592,87 +630,105 @@ export function useSheetGestures({
   //
   // Re-resolve the SAME detent — by index, the one thing that survives the
   // units changing — against the new geometry, and re-anchor without
-  // animating: the viewport moved, not the user's finger, so there is no
+  // animating: the geometry moved, not the user's finger, so there is no
   // gesture to continue and nothing to ease.
-  useEffect(() => {
-    if (!isOpen || typeof window === 'undefined') {
+  const reanchorToSettledDetent = useCallback(() => {
+    // A closed sheet re-anchors on its way back open; a live drag re-measures
+    // on its own, and a settle in flight owns the layout until it lands.
+    if (
+      !isOpenRef.current ||
+      dragStateRef.current != null ||
+      settlingLayoutOffsetRef.current != null
+    ) {
+      return;
+    }
+    const height = measureFullyOpenHeight();
+    if (height <= 0) {
+      return;
+    }
+    const {offsets, peekOffset} = resolveDetents(height);
+    const index = Math.min(settledDetentIndexRef.current, offsets.length - 1);
+    const target = offsets[index];
+    const targetLayoutOffset = target === peekOffset ? 0 : target;
+    const baseLayoutOffset = settledLayoutOffsetRef.current;
+    if (
+      height === sheetHeightRef.current &&
+      Math.abs(target - activeOffsetRef.current) <= 0.5 &&
+      Math.abs(targetLayoutOffset - baseLayoutOffset) <= 0.5
+    ) {
       return;
     }
-    const handleViewportChange = () => {
-      // A live drag re-measures on its own, and a settle in flight owns the
-      // layout until it lands.
-      if (
-        dragStateRef.current != null ||
-        settlingLayoutOffsetRef.current != null
-      ) {
-        return;
-      }
-      const height = measureFullyOpenHeight();
-      if (height <= 0) {
-        return;
-      }
-      const offsets = detentOffsets(height);
-      const index = Math.min(settledDetentIndexRef.current, offsets.length - 1);
-      const target = offsets[index];
-      const targetLayoutOffset = isPeekOffset(target, offsets) ? 0 : target;
-      const baseLayoutOffset = settledLayoutOffsetRef.current;
-      if (
-        height === sheetHeightRef.current &&
-        Math.abs(target - activeOffsetRef.current) <= 0.5 &&
-        Math.abs(targetLayoutOffset - baseLayoutOffset) <= 0.5
-      ) {
-        return;
-      }
 
-      sheetHeightRef.current = height;
-      setSheetHeight(height);
-      settledDetentIndexRef.current = index;
-      prepareScrollAreaSettle(
-        baseLayoutOffset,
-        target,
-        targetLayoutOffset,
+    sheetHeightRef.current = height;
+    // Re-anchoring is a measurement: the geometry it reads is only knowable
+    // after layout, so the state it corrects can only be set from an effect
+    // (or, on the resize path, from the listener). Both writes below are
+    // guarded by the equality check above, so a re-anchor that finds nothing
+    // to change sets nothing.
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- corrects settled geometry from a measurement
+    setSheetHeight(height);
+    settledDetentIndexRef.current = index;
+    prepareScrollAreaSettle(
+      baseLayoutOffset,
+      target,
+      targetLayoutOffset,
+      target,
+      baseLayoutOffset,
+      naturalEndGapFor(bodyNodeRef.current),
+      false,
+    );
+    recordSettledLayoutOffset(targetLayoutOffset);
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- corrects settled geometry from a measurement
+    setSettledOffset(target);
+    onSnapRef.current?.(
+      visibleHeightForOffset(height, target, offscreenBlockEndInsetRef.current),
+    );
+    const maxOffset = offsets[offsets.length - 1];
+    const shortestDetentHeight = visibleHeightForOffset(
+      height,
+      maxOffset,
+      offscreenBlockEndInsetRef.current,
+    );
+    onScrimOpacityRef.current?.(
+      scrimOpacityForOffset(
         target,
-        baseLayoutOffset,
-        naturalEndGapFor(bodyNodeRef.current),
-        false,
-      );
-      recordSettledLayoutOffset(targetLayoutOffset);
-      setSettledOffset(target);
-      onSnapRef.current?.(
-        visibleHeightForOffset(
-          height,
-          target,
-          offscreenBlockEndInsetRef.current,
-        ),
-      );
-      const maxOffset = offsets[offsets.length - 1];
-      const shortestDetentHeight = visibleHeightForOffset(
-        height,
-        maxOffset,
-        offscreenBlockEndInsetRef.current,
-      );
-      onScrimOpacityRef.current?.(
-        scrimOpacityForOffset(
-          target,
-          offsets,
-          maxOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO,
-        ),
-      );
-    };
-    window.addEventListener('resize', handleViewportChange);
-    window.addEventListener('orientationchange', handleViewportChange);
-    return () => {
-      window.removeEventListener('resize', handleViewportChange);
-      window.removeEventListener('orientationchange', handleViewportChange);
-    };
+        offsets,
+        maxOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO,
+        peekOffset,
+      ),
+    );
   }, [
-    detentOffsets,
-    isOpen,
     measureFullyOpenHeight,
     prepareScrollAreaSettle,
     recordSettledLayoutOffset,
+    resolveDetents,
   ]);
 
+  useEffect(() => {
+    if (!isOpen || typeof window === 'undefined') {
+      return;
+    }
+    window.addEventListener('resize', reanchorToSettledDetent);
+    window.addEventListener('orientationchange', reanchorToSettledDetent);
+    return () => {
+      window.removeEventListener('resize', reanchorToSettledDetent);
+      window.removeEventListener('orientationchange', reanchorToSettledDetent);
+    };
+  }, [isOpen, reanchorToSettledDetent]);
+
+  // The other input to the same geometry: the snap points themselves. A host
+  // that swaps them while the sheet rests has moved the stops out from under
+  // it, exactly as a rotation does, so re-anchor the same way. Skipped on the
+  // first run — the sheet is already anchored to the detents it opened with.
+  const hasAnchoredSnapHeightsRef = useRef(false);
+  useLayoutEffect(() => {
+    if (!hasAnchoredSnapHeightsRef.current) {
+      hasAnchoredSnapHeightsRef.current = true;
+      return;
+    }
+    reanchorToSettledDetent();
+  }, [reanchorToSettledDetent, snapHeights]);
+
   const cancelDrag = useCallback(
     (target?: HTMLElement) => {
       const state = dragStateRef.current;
@@ -701,7 +757,7 @@ export function useSheetGestures({
       // An interrupted drag returns to its previous resting detent. Restore
       // the matching scrim opacity as well so the modal shell cannot remain
       // dimmed with its sheet translated out of view.
-      const offsets = detentOffsets(state.height);
+      const {offsets, peekOffset} = resolveDetents(state.height);
       const maxOffset = offsets[offsets.length - 1];
       const shortestDetentHeight = visibleHeightForOffset(
         state.height,
@@ -711,10 +767,15 @@ export function useSheetGestures({
       const dismissOffset =
         maxOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO;
       onScrimOpacityRef.current?.(
-        scrimOpacityForOffset(state.baseOffset, offsets, dismissOffset),
+        scrimOpacityForOffset(
+          state.baseOffset,
+          offsets,
+          dismissOffset,
+          peekOffset,
+        ),
       );
     },
-    [detentOffsets, prepareScrollAreaSettle],
+    [prepareScrollAreaSettle, resolveDetents],
   );
 
   useEffect(() => {
@@ -745,7 +806,7 @@ export function useSheetGestures({
       layoutOffset: number,
       naturalEndGap: number,
     ) => {
-      const offsets = detentOffsets(height);
+      const {offsets, peekOffset} = resolveDetents(height);
       const maxOffset = offsets[offsets.length - 1];
       const shortestDetentHeight = visibleHeightForOffset(
         height,
@@ -757,7 +818,7 @@ export function useSheetGestures({
       const settleAt = (target: number) => {
         // A peek keeps the full layout height and slides below the viewport;
         // every taller detent resizes the scrolling area to what it shows.
-        const targetLayoutOffset = isPeekOffset(target, offsets) ? 0 : target;
+        const targetLayoutOffset = target === peekOffset ? 0 : target;
         prepareScrollAreaSettle(
           baseLayoutOffset,
           target,
@@ -780,7 +841,7 @@ export function useSheetGestures({
         const dismissOffset =
           maxOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO;
         onScrimOpacityRef.current?.(
-          scrimOpacityForOffset(target, offsets, dismissOffset),
+          scrimOpacityForOffset(target, offsets, dismissOffset, peekOffset),
         );
         if (target !== baseOffset) {
           hapticTick();
@@ -849,13 +910,22 @@ export function useSheetGestures({
       const target = resolveSettleOffset(offset, offsets, dir, baseOffset);
       settleAt(target);
     },
-    [detentOffsets, prepareScrollAreaSettle, recordSettledLayoutOffset],
+    [prepareScrollAreaSettle, recordSettledLayoutOffset, resolveDetents],
   );
 
   const beginDrag = useCallback(
     (event: ReactPointerEvent, sheetHeight: number, startCoord?: number) => {
       const target = event.currentTarget as HTMLElement;
-      target.setPointerCapture?.(event.pointerId);
+      const syntheticTouch = isSyntheticTouch(event);
+      // Never capture for a touch drag. The id came from `Touch.identifier`,
+      // which on iOS names a live pointer: the capture succeeds, WebKit takes
+      // it straight back for its own gesture handling, and the
+      // `lostpointercapture` a millisecond later cancels the drag that just
+      // started. Touch drags need no capture — the listener is on the
+      // scroller itself.
+      if (!syntheticTouch) {
+        target.setPointerCapture?.(event.pointerId);
+      }
       // `startCoord` lets a body-overscroll drag anchor at the original
       // pointer-down position (not the promotion point), so the first frame's
       // delta reflects the full pull distance.
@@ -863,6 +933,7 @@ export function useSheetGestures({
       const naturalEndGap = naturalEndGapFor(bodyNodeRef.current);
       const baseLayoutOffset = settledLayoutOffsetRef.current;
       dragStateRef.current = {
+        syntheticTouch,
         pointerId: event.pointerId,
         startCoord: start,
         lastCoord: event.clientY,
@@ -917,6 +988,12 @@ export function useSheetGestures({
 
   const handleLostPointerCapture = useCallback(
     (event: ReactPointerEvent) => {
+      // A touch drag never took capture, so this is WebKit reclaiming its own
+      // pointer for the finger doing the dragging — not the drag losing its
+      // grip.
+      if (dragStateRef.current?.syntheticTouch) {
+        return;
+      }
       if (dragStateRef.current?.pointerId === event.pointerId) {
         cancelDrag();
       }
@@ -930,6 +1007,11 @@ export function useSheetGestures({
       if (!state || state.pointerId !== event.pointerId) {
         return;
       }
+      // Same finger, real pointer event: the touch path already drove this
+      // move. Let it own the drag rather than driving it twice.
+      if (state.syntheticTouch && !isSyntheticTouch(event)) {
+        return;
+      }
       const delta = event.clientY - state.startCoord;
       const dt = event.timeStamp - state.lastTime;
       if (dt > 0) {
@@ -937,7 +1019,7 @@ export function useSheetGestures({
         state.lastCoord = event.clientY;
         state.lastTime = event.timeStamp;
       }
-      const offsets = detentOffsets(state.height);
+      const {offsets, peekOffset} = resolveDetents(state.height);
 
       const raw = state.baseOffset + delta;
       const maxDetentOffset = offsets[offsets.length - 1];
@@ -979,10 +1061,10 @@ export function useSheetGestures({
       const dismissOffset =
         floorOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO;
       onScrimOpacityRef.current?.(
-        scrimOpacityForOffset(next, offsets, dismissOffset),
+        scrimOpacityForOffset(next, offsets, dismissOffset, peekOffset),
       );
     },
-    [detentOffsets, updateScrollPreservationInset],
+    [resolveDetents, updateScrollPreservationInset],
   );
 
   const endDrag = useCallback(
@@ -991,12 +1073,20 @@ export function useSheetGestures({
       if (!state || state.pointerId !== event.pointerId) {
         return;
       }
+      // `pointercancel` fires for the finger the moment WebKit claims the
+      // gesture; ending a touch drag on it settles the sheet mid-pull. The
+      // touchend handler is what finishes a touch drag.
+      if (state.syntheticTouch && !isSyntheticTouch(event)) {
+        return;
+      }
       const target = event.currentTarget as HTMLElement;
       const delta = event.clientY - state.startCoord;
       const offset = Math.max(0, state.baseOffset + delta);
       const dir = delta === 0 ? 0 : delta > 0 ? 1 : -1;
       dragStateRef.current = null;
-      target.releasePointerCapture?.(event.pointerId);
+      if (!state.syntheticTouch) {
+        target.releasePointerCapture?.(event.pointerId);
+      }
       setIsDragging(false);
       settleFromDrag(
         offset,
@@ -1067,6 +1157,11 @@ export function useSheetGestures({
   const handleBodyEnd = useCallback(
     (event: ReactPointerEvent) => {
       armedBodyRef.current = null;
+      // The pointerup/pointercancel for a finger already driving a touch drag
+      // arrives here carrying that drag's own id; touchend ends those.
+      if (dragStateRef.current?.syntheticTouch) {
+        return;
+      }
       if (dragStateRef.current) {
         endDrag(event);
       }
@@ -1118,6 +1213,7 @@ export function useSheetGestures({
   const bodyRef = useCallback((node: HTMLElement | null) => {
     const asPointer = (touch: Touch, target: HTMLElement) =>
       ({
+        syntheticTouch: true,
         pointerId: touch.identifier,
         clientY: touch.clientY,
         timeStamp: Date.now(),