@hanzogui/sheet 7.3.0 → 8.0.0

package/src/useGestureHandlerPan.tsx

@@ -1,10 +1,13 @@
-import { useCallback, useMemo, useRef, type RefObject } from 'react'
+import { isWeb } from '@hanzogui/constants'
+import { useCallback, useEffect, useMemo, useRef, type RefObject } from 'react'
 import { getGestureHandlerState, isGestureHandlerEnabled } from './gestureState'
-import type { ScrollBridge } from './types'
+import { getSheetReleasePosition } from './keyboardAvoidance'
+import type { ScrollBridge, SnapPointsMode } from './types'
 
 // threshold in pixels for considering sheet "at top" position
 // allows for small measurement variations
 const AT_TOP_THRESHOLD = 5
+const SCROLL_HANDOFF_THRESHOLD = 160
 
 interface GesturePanConfig {
   positions: number[]
@@ -18,6 +21,9 @@ interface GesturePanConfig {
   resisted: (val: number, minY: number) => number
   disableDrag?: boolean
   isShowingInnerSheet?: boolean
+  dismissOnSnapToBottom?: boolean
+  snapPointsMode?: SnapPointsMode
+  isKeyboardVisible?: boolean
   // set the animated position directly (for smooth dragging)
   setAnimatedPosition: (val: number) => void
   // ref to scroll gesture for simultaneousWithExternalGesture
@@ -69,6 +75,16 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
 
   const gestureHandlerEnabled = isGestureHandlerEnabled()
   const panGestureRef = useRef<any>(null)
+  const releaseConfigRef = useRef({
+    dismissOnSnapToBottom: config.dismissOnSnapToBottom === true,
+    snapPointsMode: config.snapPointsMode ?? 'percent',
+    isKeyboardVisible: config.isKeyboardVisible === true,
+  })
+  releaseConfigRef.current = {
+    dismissOnSnapToBottom: config.dismissOnSnapToBottom === true,
+    snapPointsMode: config.snapPointsMode ?? 'percent',
+    isKeyboardVisible: config.isKeyboardVisible === true,
+  }
 
   // use refs for values that need to persist across gesture lifecycle
   // (useMemo closure variables get reset when gesture is recreated)
@@ -86,20 +102,48 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
     // causing positions to revert. Frozen positions ensure stable snap calculation.
     frozenPositions: [] as number[],
     frozenMinY: 0,
+    frozenIsKeyboardVisible: false,
     // whether pan gesture actually started (vs just a tap in onBegin)
     panStarted: false,
+    startedBelowTop: false,
+    upwardDragAfterTop: 0,
+    scrollUnlockedAfterTop: false,
+    keepScrollLockedAfterEnd: false,
   })
+  const unlockScrollTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    return () => {
+      if (unlockScrollTimer.current) {
+        clearTimeout(unlockScrollTimer.current)
+        unlockScrollTimer.current = null
+      }
+    }
+  }, [])
 
   const onStart = useCallback(() => {
     stopSpring()
   }, [stopSpring])
 
   const onEnd = useCallback(
-    (closestPoint: number, animationOverride?: any) => {
+    (closestPoint: number, animationOverride?: any, keepScrollLocked = false) => {
+      if (unlockScrollTimer.current) {
+        clearTimeout(unlockScrollTimer.current)
+        unlockScrollTimer.current = null
+      }
       setIsDragging(false)
       scrollBridge.setParentDragging(false)
-      // re-enable scroll when gesture ends
-      scrollBridge.setScrollEnabled?.(true)
+      scrollBridge.lockScrollAtTop = false
+      if (keepScrollLocked) {
+        scrollBridge.setScrollEnabled?.(false, 0)
+        unlockScrollTimer.current = setTimeout(() => {
+          unlockScrollTimer.current = null
+          scrollBridge.setScrollEnabled?.(true)
+        }, 160)
+      } else {
+        // re-enable scroll when gesture ends
+        scrollBridge.setScrollEnabled?.(true)
+      }
       setPosition(closestPoint)
       animateTo(closestPoint, animationOverride)
     },
@@ -122,7 +166,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
 
     // simultaneousHandlers pattern from react-native-actions-sheet
     // both gestures run simultaneously, we use blockPan to decide who handles
-    // console.warn('[RNGH-Pan] CREATING gesture, minY:', minY, 'frameSize:', frameSize)
     const gesture = Gesture.Pan()
       .withRef(panGestureRef)
       // NO manualActivation - let both gestures run via simultaneousHandlers
@@ -148,7 +191,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         const pos = getCurrentPosition()
         const atTop = pos <= minY + AT_TOP_THRESHOLD
         const currentScrollY = scrollBridge.y
-        // console.warn('[RNGH-Pan] onBegin', { pos, minY, atTop, currentScrollY })
         gs.startY = pos
         gs.lastPanTranslationY = 0
         gs.accumulatedOffset = 0
@@ -158,6 +200,16 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         // doesn't change snap targets mid-gesture
         gs.frozenPositions = [...positions]
         gs.frozenMinY = minY
+        gs.frozenIsKeyboardVisible = releaseConfigRef.current.isKeyboardVisible
+        gs.startedBelowTop = !atTop
+        gs.upwardDragAfterTop = 0
+        gs.scrollUnlockedAfterTop = false
+        gs.keepScrollLockedAfterEnd = false
+        scrollBridge.lockScrollAtTop = false
+        if (unlockScrollTimer.current) {
+          clearTimeout(unlockScrollTimer.current)
+          unlockScrollTimer.current = null
+        }
 
         // if sheet not at top, DISABLE SCROLL immediately and lock to 0
         // this prevents scroll from firing before pan takes over
@@ -171,7 +223,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         gs.panStarted = true
         setIsDragging(true)
 
-        // console.warn('[RNGH-Pan] onStart', { startY: gs.startY, minY })
         scrollBridge.initialPosition = gs.startY
         onStart()
       })
@@ -195,8 +246,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         const isCurrentlyAtTop = currentPos <= minY + AT_TOP_THRESHOLD
         const nodeIsScrolling = scrollY > 0
 
-        // console.warn('[RNGH-Pan] onChange', { translationY: translationY.toFixed(1), deltaY: deltaY.toFixed(1), currentPos: currentPos.toFixed(1), minY, isCurrentlyAtTop, isSwipingDown, scrollY, scrollEngaged: gs.scrollEngaged })
-
         // decision matrix (from react-native-actions-sheet pattern)
         // each frame, decide who handles the movement based on current state
         //
@@ -229,7 +278,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
             } else if (gs.scrollEngaged && hasScrollableContent) {
               // scroll WAS > 0 but now is 0 -> handoff from scroll to pan
               // pan takes over to drag sheet down
-              // console.warn('[RNGH-Pan] *** HANDOFF FROM SCROLL TO PAN ***')
               panHandles = true
             } else {
               // scroll never engaged OR content not scrollable, just drag sheet down
@@ -240,8 +288,18 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
             // if there's scrollable content, let scroll handle so user can scroll into content
             // resistance only applies when there's NO scrollable content
             if (hasScrollableContent) {
-              // content is scrollable - let scroll handle (user wants to scroll down into content)
-              panHandles = false
+              if (gs.startedBelowTop && !gs.scrollUnlockedAfterTop) {
+                gs.upwardDragAfterTop += Math.max(0, -deltaY)
+                if (gs.upwardDragAfterTop >= SCROLL_HANDOFF_THRESHOLD) {
+                  gs.scrollUnlockedAfterTop = true
+                  panHandles = false
+                } else {
+                  panHandles = true
+                }
+              } else {
+                // content is scrollable - let scroll handle (user wants to scroll down into content)
+                panHandles = false
+              }
             } else {
               // no scrollable content -> pan handles for resistance effect
               panHandles = true
@@ -249,9 +307,8 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
           }
         }
 
-        // console.warn('[RNGH-Pan] decision', { panHandles, isCurrentlyAtTop, isSwipingDown, nodeIsScrolling, scrollEngaged: gs.scrollEngaged, hasScrollableContent, currentPos: currentPos.toFixed(1), minY })
-
         if (panHandles) {
+          scrollBridge.lockScrollAtTop = gs.startedBelowTop && !gs.scrollUnlockedAfterTop
           // pan handles - disable scroll and move sheet
           // when swiping down at top after scroll was engaged: lock at current scroll position
           //   (handoff from scroll to pan — preserve scroll offset)
@@ -269,19 +326,22 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
           setAnimatedPosition(newPosition)
           scrollBridge.setParentDragging(newPosition > minY)
         } else {
+          scrollBridge.lockScrollAtTop = false
           // scroll handles - enable scroll so it can move freely
           scrollBridge.setScrollEnabled?.(true)
+          scrollBridge.setParentDragging(false)
           // don't accumulate offset when scroll is handling
         }
       })
       .onEnd((event: { velocityY: number }) => {
         const { velocityY } = event
         const currentPos = gs.startY + gs.accumulatedOffset
-
-        // console.warn('[RNGH-Pan] onEnd', { velocityY, currentPos, accumulatedOffset: gs.accumulatedOffset, scrollY: scrollBridge.y })
+        const keepScrollLockedAfterEnd = gs.startedBelowTop && !gs.scrollUnlockedAfterTop
 
         // clear scroll lock
-        scrollBridge.scrollLockY = undefined
+        scrollBridge.lockScrollAtTop = false
+        scrollBridge.scrollLockY = keepScrollLockedAfterEnd ? 0 : undefined
+        gs.keepScrollLockedAfterEnd = keepScrollLockedAfterEnd
 
         // use frozen positions from gesture start — keyboard may have dismissed
         // during drag (input blur), reverting activePositions. Frozen positions
@@ -294,7 +354,7 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
 
         // if sheet is at top and scroll is engaged, just stay at top
         if (currentPos <= snapMinY + AT_TOP_THRESHOLD && scrollBridge.y > 0) {
-          onEnd(0)
+          onEnd(0, undefined, keepScrollLockedAfterEnd)
           return
         }
 
@@ -302,24 +362,24 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         const velocity = velocityY / 1000
         const projectedEnd = currentPos + frameSize * velocity * 0.2
 
-        let closestPoint = 0
-        let minDist = Number.POSITIVE_INFINITY
-
-        for (let i = 0; i < snapPositions.length; i++) {
-          const pos = snapPositions[i]
-          const dist = Math.abs(projectedEnd - pos)
-          if (dist < minDist) {
-            minDist = dist
-            closestPoint = i
-          }
-        }
-
-        onEnd(closestPoint)
+        const releaseConfig = releaseConfigRef.current
+        const closestPoint = getSheetReleasePosition({
+          positions: snapPositions,
+          projectedEnd,
+          currentPosition: currentPos,
+          frameSize,
+          dismissOnSnapToBottom: releaseConfig.dismissOnSnapToBottom,
+          snapPointsMode: releaseConfig.snapPointsMode,
+          isKeyboardVisible: gs.frozenIsKeyboardVisible,
+          isWeb,
+        })
+
+        onEnd(closestPoint, undefined, keepScrollLockedAfterEnd)
       })
       .onFinalize(() => {
-        // console.warn('[RNGH-Pan] onFinalize', { panStarted: gs.panStarted })
         // clear scroll lock on finalize too (safety)
-        scrollBridge.scrollLockY = undefined
+        scrollBridge.lockScrollAtTop = false
+        scrollBridge.scrollLockY = gs.keepScrollLockedAfterEnd ? 0 : undefined
         if (gs.panStarted) {
           // real pan gesture — reset isDragging (also un-pauses keyboard handler + flushes)
           setIsDragging(false)
@@ -336,7 +396,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
     // if we have a scroll gesture ref, make pan simultaneous with it
     // this allows both gestures to run and we decide in onChange who handles it
     if (scrollGestureRef?.current) {
-      // console.warn('[RNGH-Pan] adding simultaneousWithExternalGesture for scroll')
       return gesture.simultaneousWithExternalGesture(scrollGestureRef.current)
     }
 

package/src/useKeyboardControllerSheet.ts

@@ -1,26 +1,143 @@
 /**
- * Web stub for keyboard controller sheet hook.
- * Returns no-op values since keyboard-controller is native-only.
+ * Web implementation of the keyboard controller sheet hook.
+ *
+ * Mobile browsers don't expose a keyboard API, but they do resize the
+ * VisualViewport when the soft keyboard opens. We use the viewport shrink
+ * (`clientHeight - visualViewport.height`) to detect the keyboard, then feed the
+ * bottom layout inset (`clientHeight - (offsetTop + height)`) into
+ * SheetImplementationCustom. The bottom inset accounts for iOS Safari panning
+ * the visual viewport during focus, so the sheet doesn't over-lift.
+ *
+ * Without this, a bottom sheet on mobile web stays pinned behind the keyboard:
+ * react-native-web's Dimensions tracks the (shrinking) VisualViewport, so any
+ * content sized off window dimensions collapses while the sheet's bottom stays
+ * occluded. See SheetImplementationCustom's activePositions / keyboardOccludedHeight.
  */
 
-import { useRef } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { isWeb } from '@hanzogui/constants'
 import type {
   KeyboardControllerSheetOptions,
   KeyboardControllerSheetResult,
 } from './types'
-
-const noop = () => {}
+import {
+  getWebKeyboardBottomInset,
+  getWebKeyboardResizeHeight,
+  isEditableElement,
+  MIN_KEYBOARD_HEIGHT,
+} from './webViewport'
 
 export function useKeyboardControllerSheet(
-  _options: KeyboardControllerSheetOptions
+  options: KeyboardControllerSheetOptions
 ): KeyboardControllerSheetResult {
+  const { enabled } = options
+
+  // initialize from the CURRENT viewport, not blindly from 0/false. when the
+  // sheet opens with the soft keyboard already up (e.g. it was raised by a field
+  // on the page behind, or by an autofocus whose keyboard wins the race against
+  // the first layout), a false initial value makes the sheet's very first render
+  // believe the keyboard is down — it captures a keyboard-free baseline from a
+  // keyboard-shrunk layout and the anchor/seed machinery has to recover. reading
+  // the viewport synchronously here removes that first-render race: the sheet
+  // knows the keyboard is up on render 1 and takes the seed path deterministically.
+  const [keyboardHeight, setKeyboardHeight] = useState(() =>
+    isWeb && enabled && typeof window !== 'undefined' && window.visualViewport
+      ? (() => {
+          const resizeHeight = getWebKeyboardResizeHeight()
+          return resizeHeight >= MIN_KEYBOARD_HEIGHT &&
+            isEditableElement(document.activeElement)
+            ? getWebKeyboardBottomInset()
+            : 0
+        })()
+      : 0
+  )
+  const [isKeyboardVisible, setIsKeyboardVisible] = useState(() => keyboardHeight > 0)
+
+  // action-sheet pattern: pause keyboard hide events during drag so the sheet
+  // position doesn't revert mid-gesture when a TextInput blurs.
   const pauseKeyboardHandler = useRef(false)
+  const pendingHide = useRef(false)
+  // live mirror of isKeyboardVisible so the listener can read it without
+  // re-subscribing on every toggle.
+  const isVisibleRef = useRef(false)
+  isVisibleRef.current = isKeyboardVisible
+
+  const dismissKeyboard = useCallback(() => {
+    if (typeof document === 'undefined') return
+    const active = document.activeElement as HTMLElement | null
+    if (isEditableElement(active)) {
+      active?.blur?.()
+    }
+  }, [])
+
+  const flushPendingHide = useCallback(() => {
+    if (pendingHide.current) {
+      pendingHide.current = false
+      setIsKeyboardVisible(false)
+      setKeyboardHeight(0)
+    }
+  }, [])
+
+  useEffect(() => {
+    if (!isWeb || !enabled) return
+    if (typeof window === 'undefined') return
+    const vv = window.visualViewport
+    if (!vv) return
+
+    const update = () => {
+      const resizeHeight = getWebKeyboardResizeHeight()
+      const height = getWebKeyboardBottomInset()
+      const tall = resizeHeight >= MIN_KEYBOARD_HEIGHT
+      // require an editable element focused to *show* — this rules out URL-bar
+      // collapse and other viewport changes that aren't a keyboard. but stay
+      // visible while the viewport remains shrunk even if focus momentarily
+      // moves to a non-editable element (e.g. tapping between two inputs fires
+      // focusout→focusin), so the sheet doesn't flicker mid-transition.
+      const editableFocused = isEditableElement(document.activeElement)
+      const visible = tall && (editableFocused || isVisibleRef.current)
+
+      if (!visible) {
+        // suppress hide during an active drag so positions stay frozen; the
+        // drag-end flush reconciles the real state.
+        if (pauseKeyboardHandler.current && isVisibleRef.current) {
+          pendingHide.current = true
+          return
+        }
+        setIsKeyboardVisible(false)
+        setKeyboardHeight(0)
+        return
+      }
+
+      pendingHide.current = false
+      setIsKeyboardVisible(true)
+      setKeyboardHeight((prev) => (prev === height ? prev : height))
+    }
+
+    // resize tracks keyboard open/close. scroll tracks iOS Safari's focus pan:
+    // visualViewport.offsetTop can change after the height has settled, and the
+    // sheet cap must move in that same layout coordinate space.
+    vv.addEventListener('resize', update)
+    vv.addEventListener('scroll', update)
+    // focus changes flip editable state without necessarily resizing the viewport
+    window.addEventListener('focusin', update)
+    window.addEventListener('focusout', update)
+
+    update()
+
+    return () => {
+      vv.removeEventListener('resize', update)
+      vv.removeEventListener('scroll', update)
+      window.removeEventListener('focusin', update)
+      window.removeEventListener('focusout', update)
+    }
+  }, [enabled])
+
   return {
     keyboardControllerEnabled: false,
-    keyboardHeight: 0,
-    isKeyboardVisible: false,
-    dismissKeyboard: noop,
+    keyboardHeight,
+    isKeyboardVisible,
+    dismissKeyboard,
     pauseKeyboardHandler,
-    flushPendingHide: noop,
+    flushPendingHide,
   }
 }

package/src/useSafeAreaInsets.native.ts

@@ -0,0 +1,29 @@
+import * as React from 'react'
+import { SafeAreaInsetsContext as RNSafeAreaInsetsContext } from 'react-native-safe-area-context'
+
+import type { SafeAreaInsets } from './useSafeAreaInsets'
+
+// the real react-native-safe-area-context insets context, re-typed to the local
+// shape so consumers don't depend on the package's types. exported so the Sheet
+// can re-propagate it across the portal.
+export const SafeAreaInsetsContext =
+  RNSafeAreaInsetsContext as unknown as React.Context<SafeAreaInsets | null>
+
+/**
+ * Live safe-area insets (notch / status bar / home indicator) read from the
+ * context the app's SafeAreaProvider provides.
+ *
+ * Read this in a component BODY that renders inside the provider. The Sheet does
+ * exactly that — only its modal CONTENT is teleported out through the portal, so
+ * the body still sees the real insets. This is the one read that works in real
+ * native bundles:
+ *  - `getSafeArea()` (the @hanzogui/native abstraction) is frequently NOT enabled
+ *    against the instance a component reads, so it returns 0.
+ *  - a dynamic `require('react-native-safe-area-context')` throws "Unknown named
+ *    module" in metro/rolldown bundles where the package isn't in the importing
+ *    module's graph.
+ * A static import + context read avoids both.
+ */
+export function useSafeAreaInsets(): SafeAreaInsets | null {
+  return React.useContext(SafeAreaInsetsContext)
+}

package/src/useSafeAreaInsets.ts

@@ -0,0 +1,19 @@
+import * as React from 'react'
+
+export interface SafeAreaInsets {
+  top: number
+  right: number
+  bottom: number
+  left: number
+}
+
+// web uses CSS env(safe-area-inset-*) for safe areas, so there is no native
+// safe-area context to read here — the keyboard-avoidance path uses the visual
+// viewport offset instead. this stub keeps the import resolvable on web (where
+// react-native-safe-area-context isn't a dependency) and is the canonical type
+// source for both platform variants.
+export const SafeAreaInsetsContext = React.createContext<SafeAreaInsets | null>(null)
+
+export function useSafeAreaInsets(): SafeAreaInsets | null {
+  return null
+}

package/src/useSheetProviderProps.tsx

@@ -8,6 +8,17 @@ import type { ScrollBridge, SheetProps } from './types'
 import type { SheetOpenState } from './useSheetOpenState'
 
 export type SheetContextValue = ReturnType<typeof useSheetProviderProps> & {
+  keyboardOccludedHeight: number
+  // whether the soft keyboard is currently open. distinct from
+  // keyboardOccludedHeight (which is 0 once the sheet fits above the keyboard):
+  // the fit-mode height freeze must persist for the whole time the keyboard is
+  // open, not just while occluded, or it releases and the sheet collapses.
+  isKeyboardVisible: boolean
+  // the sheet's pre-keyboard frame height (web). SheetScrollView pins its height
+  // to this while the keyboard is open so the frame translates at full size
+  // instead of collapsing to a consumer maxHeight that shrank with the viewport.
+  // 0 when not applicable.
+  keyboardStableFrameHeight: number
   setHasScrollView: (val: boolean) => void
 }
 
@@ -133,7 +144,7 @@ export function useSheetProviderProps(
     throw new Error(
       process.env.NODE_ENV === 'production'
         ? `❌ 008`
-        : 'Must set animations in gui.config.ts'
+        : 'Must set animations in hanzogui.config.ts'
     )
   }
 

package/src/useSheetScrollViewGestures.native.ts

@@ -131,6 +131,10 @@ export function useSheetScrollViewGestures({
     } else {
       panHandles = !hasScrollableContent
       if (!panHandles) {
+        s.handoffOccurred = false
+        s.handoffDragOffset = 0
+        s.scrollEngaged = currentScrollY > 0
+        s.prevScrollY = currentScrollY
         s.isScrolling = true
         scrollBridge.scrollLock = true
         setScrollEnabled(true)

package/src/useSheetScrollViewGestures.ts

@@ -8,6 +8,7 @@ interface GestureState {
   startY: number
   lastY: number
   owner: GestureOwner
+  hadPanOwner: boolean
   panDragOffset: number
   dys: number[]
   scrollYAtGestureStart: number
@@ -19,21 +20,29 @@ interface UseSheetScrollViewGesturesProps {
   hasScrollableContent: boolean
   scrollEnabled: boolean
   setScrollEnabled: (enabled: boolean, lockTo?: number) => void
+  onManualScroll?: (node: HTMLElement, y: number) => void
 }
 
 export function useSheetScrollViewGestures({
   scrollRef,
   scrollBridge,
   hasScrollableContent,
+  onManualScroll,
 }: UseSheetScrollViewGesturesProps) {
   const state = useRef<GestureState>({
     startY: 0,
     lastY: 0,
     owner: 'none',
+    hadPanOwner: false,
     panDragOffset: 0,
     dys: [],
     scrollYAtGestureStart: 0,
   })
+  const onManualScrollRef = useRef(onManualScroll)
+
+  useEffect(() => {
+    onManualScrollRef.current = onManualScroll
+  }, [onManualScroll])
 
   useEffect(() => {
     if (!scrollRef.current) return
@@ -59,6 +68,13 @@ export function useSheetScrollViewGestures({
       node.style.overflowY = originalOverflow
     }
 
+    const setScrollTop = (nextScrollY: number) => {
+      if (node.scrollTop === nextScrollY) return
+
+      node.scrollTop = nextScrollY
+      onManualScrollRef.current?.(node, nextScrollY)
+    }
+
     const handleTouchStart = (e: TouchEvent) => {
       const touch = e.touches[0]
       if (!touch) return
@@ -69,12 +85,17 @@ export function useSheetScrollViewGestures({
         startY: touch.pageY,
         lastY: touch.pageY,
         owner: 'none',
+        hadPanOwner: false,
         panDragOffset: 0,
         dys: [],
         scrollYAtGestureStart: currentScrollY,
       }
 
       scrollBridge.scrollStartY = touch.pageY
+      // claim this touch for the scroll-view gesture hook so the PanResponder
+      // (which also negotiates this touch via RNW's responder system) defers
+      // and doesn't double-drive the sheet position. cleared on touchend.
+      scrollBridge.scrollNodeTouched = true
     }
 
     const handleTouchMove = (e: TouchEvent) => {
@@ -90,7 +111,8 @@ export function useSheetScrollViewGestures({
 
       const isDraggingDown = dy > 0
       const currentScrollY = node.scrollTop
-      const isPaneAtTop = scrollBridge.paneY <= scrollBridge.paneMinY + 5
+      const isPaneAtTop =
+        scrollBridge.isAtTop ?? scrollBridge.paneY <= scrollBridge.paneMinY + 5
 
       scrollBridge.y = currentScrollY
 
@@ -113,14 +135,23 @@ export function useSheetScrollViewGestures({
       // handle transitions
       if (newOwner !== s.owner) {
         if (newOwner === 'pan') {
+          s.hadPanOwner = true
           s.panDragOffset = 0
           s.dys = []
+          // re-baseline the pan origin to the sheet's CURRENT position so the
+          // offset (reset to 0 here) maps to where it actually is — required for
+          // a correct scroll→pan handoff now that the PanResponder defers to us.
+          scrollBridge.startPanDrag?.()
           scrollBridge.setParentDragging(true)
           disableScroll()
         } else {
           scrollBridge.setParentDragging(false)
           scrollBridge.scrollLock = false
-          enableScroll()
+          if (s.hadPanOwner) {
+            disableScroll()
+          } else {
+            enableScroll()
+          }
         }
         s.owner = newOwner
       }
@@ -133,14 +164,21 @@ export function useSheetScrollViewGestures({
 
         s.dys.push(dy)
         if (s.dys.length > 100) s.dys = s.dys.slice(-10)
-      } else if (s.owner === 'scroll') {
-        // programmatic scroll for synthetic events
+      } else if (s.owner === 'scroll' && (!e.isTrusted || s.hadPanOwner)) {
+        // synthetic events don't trigger native overflow scroll, so tests need us
+        // to move scrollTop directly. real mixed gestures need the same direct
+        // path after pan ownership: ios safari may not resume native scrolling
+        // mid-touch after an earlier prevented touchmove. pure real scrolls still
+        // use native scrolling; mixed pan↔scroll gestures keep overflow hidden
+        // and are driven here until touchend.
+        if (e.cancelable) e.preventDefault()
         const scrollDelta = -dy
         const maxScrollY = node.scrollHeight - node.clientHeight
         const newScrollY = Math.max(0, Math.min(maxScrollY, currentScrollY + scrollDelta))
         if (newScrollY !== currentScrollY) {
-          node.scrollTop = newScrollY
+          setScrollTop(newScrollY)
           scrollBridge.y = newScrollY
+          if (newScrollY > 0) scrollBridge.scrollStartY = -1
         }
       }
     }
@@ -159,12 +197,21 @@ export function useSheetScrollViewGestures({
         }
 
         scrollBridge.release({ dragAt: s.panDragOffset, vy })
+      } else if (s.owner === 'scroll') {
+        // gesture ended while scrolling. a pan→scroll handoff only happens once
+        // the pane reached the top, so commit the top snap (index 0) and clear
+        // the dragging state HERE, on touchend — never mid-gesture (that would
+        // fight the live gesture). this replaces the PanResponder's release,
+        // which used to fire on touchend before it deferred to this hook.
+        scrollBridge.snapToPosition?.(0)
       }
 
       enableScroll()
       s.owner = 'none'
+      s.hadPanOwner = false
       s.panDragOffset = 0
       s.dys = []
+      scrollBridge.scrollNodeTouched = false
     }
 
     node.addEventListener('touchstart', handleTouchStart, {