@tamagui/sheet 2.0.0 → 2.1.0

package/src/SheetImplementationCustom.tsx

@@ -26,6 +26,11 @@ import { getGestureHandlerState } from './gestureState'
 import { GestureSheetProvider } from './GestureSheetContext'
 import { resisted } from './helpers'
 import { getKeyboardOccludedHeight } from './keyboardAvoidance'
+import {
+  getStableLayoutViewportHeight,
+  getWebKeyboardHeight,
+  MIN_KEYBOARD_HEIGHT,
+} from './webViewport'
 import { SheetProvider } from './SheetContext'
 import type { SheetProps, SnapPointsMode } from './types'
 import { useGestureHandlerPan } from './useGestureHandlerPan'
@@ -57,6 +62,19 @@ let sheetHiddenStyleSheet: HTMLStyleElement | null = null
 // on web we are always relative to window, on to screen
 const relativeDimensionTo = isWeb ? 'window' : 'screen'
 
+// height of the viewport the sheet positions against. on web this MUST be the
+// stable layout viewport and NOT Dimensions.get('window') — react-native-web's
+// Dimensions tracks visualViewport, which shrinks by the soft keyboard. capping
+// frameSize / maxContentSize against that shrinking value corrupts the fit-mode
+// math (translateY = screenSize - frameSize), detaching the sheet's bottom from
+// the screen edge when the keyboard opens. NOTE: window.innerHeight is NOT
+// stable on real iOS Safari (it shrinks with the keyboard too), so we use the
+// self-correcting baseline from webViewport instead. see getStableLayoutViewportHeight.
+function getStableViewportHeight(): number {
+  if (isWeb && typeof window !== 'undefined') return getStableLayoutViewportHeight()
+  return Dimensions.get(relativeDimensionTo).height
+}
+
 export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
   function SheetImplementationCustom(props, forwardedRef) {
     const parentSheet = React.useContext(ParentSheetContext)
@@ -142,6 +160,19 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       setIsShowingInnerSheet(hasChild)
     }, [])
 
+    // keyboard state tracking — just tracks height/visibility, no position animation.
+    // Position animation is handled via keyboard-adjusted positions below,
+    // matching the react-native-actions-sheet pattern.
+    const {
+      keyboardHeight,
+      isKeyboardVisible,
+      dismissKeyboard,
+      pauseKeyboardHandler,
+      flushPendingHide,
+    } = useKeyboardControllerSheet({
+      enabled: Boolean(moveOnKeyboardChange),
+    })
+
     // FIX: Store stable frameSize to prevent recalculation during exit animation
     const stableFrameSize = React.useRef(frameSize)
 
@@ -152,31 +183,84 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       }
     }, [open, frameSize])
 
+    // WEB keyboard anchor freeze. on real iOS Safari opening the keyboard shrinks
+    // the visual viewport AND innerHeight AND the measured layout, which would
+    // re-derive screenSize/frameSize smaller, recompute the fit positions, and
+    // fly the frame up then back down ("goes back down after the keyboard opens").
+    // so we snapshot the pre-keyboard geometry — captured every render while the
+    // keyboard is CLOSED, which dodges the open-transition race where a shrunk
+    // onLayout lands before isKeyboardVisible flips — and use it for the anchor
+    // math while the keyboard is open. the sheet then stays put; only the scroll
+    // content shifts to clear the keyboard (keyboardOccludedHeight padding below
+    // + SheetScrollView's frozen height).
+    // this sheet is the kind the web keyboard anchor freeze is designed for — a
+    // fit-mode web sheet opted into keyboard handling. percent/constant sheets
+    // keep the live geometry (their height isn't pinned, so a frozen anchor
+    // would mismatch).
+    const isWebKbSheet = isWeb && hasFit && moveOnKeyboardChange
+
+    // whether we ever captured geometry while the keyboard was CLOSED. that's the
+    // authoritative baseline; until we have it, the autofocus-on-open seed below
+    // reconstructs one from keyboard-up measurements.
+    const hasCleanKbBaseline = React.useRef(false)
+    // the autofocus-on-open seed has settled on a stable frame height (the
+    // unclipped content stopped growing). until then we keep the seed phase open.
+    const seedSettled = React.useRef(false)
+    const stableKbGeom = React.useRef({ frame: 0, screen: 0 })
+    if ((!isWeb || !isKeyboardVisible) && frameSize > 0 && screenSize > 0) {
+      // keyboard-free render — the authoritative baseline. mutate in place: the
+      // ref is only ever read field-by-field, never identity-compared, so this
+      // avoids a per-render allocation.
+      stableKbGeom.current.frame = frameSize
+      stableKbGeom.current.screen = screenSize
+      hasCleanKbBaseline.current = true
+    } else if (
+      isWebKbSheet &&
+      isKeyboardVisible &&
+      !hasCleanKbBaseline.current &&
+      screenSize > 0
+    ) {
+      // AUTOFOCUS-ON-OPEN seed. when the input autofocuses as the sheet animates
+      // in, the keyboard rises BEFORE any keyboard-free layout lands, so the
+      // branch above never runs (frameSize/screenSize were 0 the whole time the
+      // keyboard was up) and freezeForKb stays false, collapsing the sheet to the
+      // shrunk consumer maxHeight. instead, reconstruct the baseline from the
+      // keyboard-up render: screen = the stable layout viewport
+      // (keyboard-independent). the frame is grown by the seeding layout path
+      // below: while seeding, the tail padding is suppressed and the scroll view
+      // is unclipped (via keyboardStableFrameHeight = stable screen), so the frame
+      // converges on its pure pre-keyboard content height across a couple layout
+      // passes. a real keyboard-free render later replaces it with the exact value
+      // (branch above).
+      stableKbGeom.current.screen = Math.max(stableKbGeom.current.screen, screenSize)
+    }
+    // are we still reconstructing the baseline from a keyboard-up render? true
+    // until either a clean baseline lands or the seeded frame settles.
+    const seedingKbBaseline =
+      isWebKbSheet &&
+      isKeyboardVisible &&
+      !hasCleanKbBaseline.current &&
+      !seedSettled.current
+    const freezeForKb =
+      isWebKbSheet && isKeyboardVisible && stableKbGeom.current.frame > 0
+    const effScreenSize = freezeForKb ? stableKbGeom.current.screen : screenSize
+
     // use stableFrameSize when closing to prevent position jumps during exit animation
     // but when opening, always use the current frameSize so positions update correctly
-    const effectiveFrameSize = open ? frameSize : stableFrameSize.current || frameSize
+    const effectiveFrameSize = freezeForKb
+      ? stableKbGeom.current.frame
+      : open
+        ? frameSize
+        : stableFrameSize.current || frameSize
 
     const positions = React.useMemo(
       () =>
         snapPoints.map((point) =>
-          getYPositions(snapPointsMode, point, screenSize, effectiveFrameSize)
+          getYPositions(snapPointsMode, point, effScreenSize, effectiveFrameSize)
         ),
-      [screenSize, effectiveFrameSize, snapPoints, snapPointsMode]
+      [effScreenSize, effectiveFrameSize, snapPoints, snapPointsMode]
     )
 
-    // keyboard state tracking — just tracks height/visibility, no position animation.
-    // Position animation is handled via keyboard-adjusted positions below,
-    // matching the react-native-actions-sheet pattern.
-    const {
-      keyboardHeight,
-      isKeyboardVisible,
-      dismissKeyboard,
-      pauseKeyboardHandler,
-      flushPendingHide,
-    } = useKeyboardControllerSheet({
-      enabled: !isWeb && Boolean(moveOnKeyboardChange),
-    })
-
     const [isDragging, setIsDragging_] = React.useState(false)
 
     // synchronous dragging ref — set BEFORE async state commits.
@@ -198,28 +282,32 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       [pauseKeyboardHandler, flushPendingHide]
     )
 
-    // keyboard-adjusted positions: shift snap points up by keyboard height
-    // when keyboard is visible. This drives both gesture snap calculation
-    // and animation targets — keyboard never dismissed during drag.
-    // Capped at safe area top inset so the sheet never goes above the notch/status bar
-    // (matching the react-native-actions-sheet pattern).
+    // keyboard-adjusted snap positions.
+    //
+    // WEB: the sheet stays ANCHORED at the bottom and keeps its full pre-keyboard
+    // height — it does NOT shift up or resize. Shifting/resizing with the
+    // translateY model detaches the bottom from the screen edge or teleports it.
+    // Instead the frame's anchor geometry is frozen (effScreenSize/effectiveFrameSize
+    // above) and its height is pinned (keyboardStableFrameHeight -> SheetScrollView);
+    // the scroll content is padded by keyboardOccludedHeight and the browser
+    // scroll-into-view lifts the focused input above the keyboard. So
+    // activePositions === positions on web.
     //
-    // IMPORTANT: frozen during drag to prevent gesture handler recreation.
-    // When user drags, TextInput may blur → keyboard dismisses → positions would revert,
-    // causing the gesture useMemo to recreate and cancel the active drag.
-    // The post-drag reconciliation effect handles animating to correct position after drag ends.
+    // NATIVE: shift snap points up by keyboard height (the native keyboard is
+    // opaque and pushes content), capped at the safe-area top inset.
+    //
+    // IMPORTANT: frozen during drag to prevent gesture handler recreation —
+    // when a TextInput blurs mid-drag the keyboard state would otherwise revert
+    // and recreate the gesture useMemo, cancelling the active drag.
     const activePositionsRef = React.useRef(positions)
     const activePositions = React.useMemo(() => {
-      // during drag, return frozen positions to prevent gesture handler recreation.
-      // check both state (for re-render trigger) and ref (for synchronous check
-      // when keyboard hide event fires before isDragging state commits)
       if (isDragging || isDraggingRef.current) return activePositionsRef.current
 
       let result: number[]
-      if (!isKeyboardVisible || keyboardHeight <= 0) {
+      if (isWeb || !isKeyboardVisible || keyboardHeight <= 0) {
         result = positions
       } else {
-        const safeAreaTop = isWeb ? 0 : getSafeAreaTopInset()
+        const safeAreaTop = getSafeAreaTopInset()
         result = positions.map((p) => {
           // don't adjust the off-screen/close position (from dismissOnSnapToBottom's 0% snap)
           // — it must stay at screenSize so the user can drag between real snap points
@@ -232,13 +320,39 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       return result
     }, [positions, isKeyboardVisible, keyboardHeight, screenSize, isDragging])
 
-    const keyboardOccludedHeight = getKeyboardOccludedHeight({
-      frameSize,
-      isKeyboardVisible: !isWeb && isKeyboardVisible,
-      keyboardHeight,
-      screenSize,
-      sheetY: position >= 0 ? activePositions[position] : undefined,
-    })
+    const keyboardOccludedHeight = seedingKbBaseline
+      ? // while seeding, suppress the keyboard tail padding so the frame measures
+        // its PURE pre-keyboard content height (the padding would otherwise inflate
+        // it toward the full screen). re-enabled once the baseline is captured.
+        0
+      : getKeyboardOccludedHeight({
+          frameSize: effectiveFrameSize,
+          isKeyboardVisible,
+          keyboardHeight,
+          screenSize: effScreenSize,
+          sheetY: position >= 0 ? activePositions[position] : undefined,
+        })
+
+    // the authoritative pre-keyboard frame height to pin the scroll view to while
+    // the keyboard is open (web). stableKbGeom.frame is captured every render the
+    // keyboard is closed, so it survives the open transition; SheetScrollView
+    // gates application on its own live keyboard check.
+    //
+    // AUTOFOCUS-ON-OPEN seed: while still reconstructing the baseline (seeding,
+    // not yet settled) we use the STABLE SCREEN SIZE — a safe upper bound (a fit
+    // frame never exceeds the screen) that is > 0, so SheetScrollView's height
+    // override engages and UNCLIPS the scroll view from the shrunk consumer
+    // maxHeight. with the tail padding suppressed (above) the content then lays
+    // out to its pure intrinsic height, which the seeding layout grows the frame
+    // baseline toward across a couple passes. once settled (or once a real
+    // keyboard-free baseline lands) we pin that exact frame height.
+    const keyboardStableFrameHeight = !isWebKbSheet
+      ? 0
+      : seedingKbBaseline
+        ? stableKbGeom.current.screen || screenSize
+        : stableKbGeom.current.frame > 0
+          ? stableKbGeom.current.frame
+          : 0
 
     const { useAnimatedNumber, useAnimatedNumberStyle, useAnimatedNumberReaction } =
       animationDriver
@@ -325,7 +439,11 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
     const animateTo = useEvent((position: number, animationOverride?: any) => {
       if (frameSize === 0) return
 
-      let toValue = isHidden || position === -1 ? screenSize : activePositions[position]
+      // use effScreenSize (the frozen anchor space the positions were built in) for
+      // the off-screen/close target too, so a close while the keyboard is still up
+      // animates fully out instead of to a mismatched live screenSize.
+      let toValue =
+        isHidden || position === -1 ? effScreenSize : activePositions[position]
 
       if (at.current === toValue) return
 
@@ -417,6 +535,16 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
         return
       }
 
+      // never fight an active drag: the gesture owns the animated position. on
+      // web the AnimatedView's onLayout re-fires with sub-pixel jitter as the
+      // frame translates (frameSize 499.99996 <-> 500.00003), and since frameSize
+      // is a dep of this effect that would re-run it mid-pull and snap the sheet
+      // back to its resting snap point. read the live ref so drag-end (which the
+      // reconcile-after-drag effect handles) isn't gated by stale deps.
+      if (isDraggingRef.current) {
+        return
+      }
+
       if (!frameSize || !screenSize || isHidden || (hasntMeasured && !open)) {
         return
       }
@@ -454,7 +582,11 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       if (!frameSize) return
       if (isShowingInnerSheet) return
 
-      const minY = positions[0]
+      // use keyboard-adjusted positions (matches the RNGH path): when the
+      // keyboard is open the sheet sits at activePositions[0], so clamping drags
+      // against the un-adjusted positions[0] would rubber-band the sheet down to
+      // near the bottom on any drag.
+      const minY = activePositions[0]
       scrollBridge.paneMinY = minY
       let startY = at.current
 
@@ -497,8 +629,8 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
         let closestPoint = 0
         let dist = Number.POSITIVE_INFINITY
 
-        for (let i = 0; i < positions.length; i++) {
-          const position = positions[i]
+        for (let i = 0; i < activePositions.length; i++) {
+          const position = activePositions[i]
           const curDist = end > position ? end - position : position - end
           if (curDist < dist) {
             dist = curDist
@@ -530,6 +662,16 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
             return true
           }
 
+          // touch is on the ScrollView node — the web scroll-view gesture hook
+          // owns it and drives drag/release through scrollBridge directly (it
+          // re-baselines via scrollBridge.startPanDrag on each pan handoff). if
+          // we also granted here, RNW's PanResponder would set the animated
+          // position from a second, differently-based offset every move and the
+          // sheet would jitter/jump. defer entirely to the hook.
+          if (scrollBridge.scrollNodeTouched) {
+            return false
+          }
+
           if (scrollBridge.hasScrollableContent === true) {
             if (scrollBridge.scrollLock) {
               return false
@@ -575,6 +717,17 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
 
       let isExternalDrag = false
 
+      // re-baseline a pan drag to the current animated position. the web
+      // scroll-view hook calls this on every transition INTO pan ownership
+      // (including handoffs back from scroll), so its panDragOffset — which it
+      // resets to 0 at each pan entry — is measured from where the sheet
+      // actually is now, not from where the gesture first grabbed it. without
+      // this the sheet would jump to a stale origin on a scroll→pan handoff.
+      scrollBridge.startPanDrag = () => {
+        isExternalDrag = true
+        grant()
+      }
+
       scrollBridge.drag = (dy) => {
         if (!isExternalDrag) {
           isExternalDrag = true
@@ -616,10 +769,22 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
         onPanResponderTerminate: finish,
         onPanResponderRelease: finish,
       })
-    }, [disableDrag, isShowingInnerSheet, animateTo, frameSize, positions, setPosition])
+    }, [
+      disableDrag,
+      isShowingInnerSheet,
+      animateTo,
+      frameSize,
+      activePositions,
+      setPosition,
+    ])
 
-    // animate to keyboard-adjusted position when keyboard state changes
+    // animate to keyboard-adjusted position when keyboard state changes.
+    // WEB skips this: the sheet stays anchored at its frozen position/height
+    // (activePositions don't change with the keyboard, and the anchor geometry is
+    // frozen), so there's nothing to re-animate. Running a timing animation here
+    // would only introduce movement where the sheet should hold perfectly still.
     React.useEffect(() => {
+      if (isWeb) return
       if (isDragging || isHidden || !open || disableAnimation) return
       if (!frameSize || !screenSize) return
       // use timing animation to match iOS keyboard animation (~250ms)
@@ -647,6 +812,11 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
     React.useEffect(() => {
       if (!open && isKeyboardVisible) {
         dismissKeyboard()
+        // if the sheet was closed mid-drag the keyboard-hide handler was paused
+        // and a hide could be left pending — clear it so isKeyboardVisible can't
+        // stick true after the sheet is gone. (no-op for a normal close.)
+        pauseKeyboardHandler.current = false
+        flushPendingHide()
       }
     }, [open])
 
@@ -671,31 +841,102 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       pauseKeyboardHandler,
     })
 
+    // ignore any layout measured while the soft keyboard is up (web +
+    // moveOnKeyboardChange): the visual viewport (which RN's web layout follows)
+    // shrinks, so the height would be the collapsed sheet — keeping it would
+    // recompute the fit anchor and fly the frame. a LIVE DOM check, NOT the
+    // isKeyboardVisible React state, is required: the state lags the resize, so
+    // the first shrunk onLayout lands before the flag flips. holding the measured
+    // sizes keeps the sheet anchored; the scroll content shifts to clear the kb.
+    const ignoreLayoutForKeyboard = useEvent(
+      () => isWeb && moveOnKeyboardChange && getWebKeyboardHeight() >= MIN_KEYBOARD_HEIGHT
+    )
+
+    // AUTOFOCUS-ON-OPEN seed gates. normally a layout measured while the keyboard
+    // is up is dropped (it's the shrunk/collapsed sheet). but if the keyboard rose
+    // before ANY keyboard-free baseline was captured (the autofocus race),
+    // dropping every measurement leaves frameSize/screenSize stuck at 0 forever
+    // and the freeze never engages.
+    //
+    // frame: while seeding (not settled) the scroll view is unclipped and the
+    // tail padding suppressed, so the frame measures toward its pure pre-keyboard
+    // content height. the first keyboard-up pass is still clipped at the consumer
+    // maxHeight; the override only unclips it the following pass, so the frame
+    // grows. we take the MAX and mark the seed SETTLED once it stops growing
+    // (handled in handleAnimationViewLayout) — then later keyboard-up layouts are
+    // dropped again so the re-enabled tail padding can't inflate the frame.
+    const shouldSeedKbFrame = useEvent(
+      () =>
+        isWebKbSheet &&
+        !hasCleanKbBaseline.current &&
+        !seedSettled.current &&
+        ignoreLayoutForKeyboard()
+    )
+    // screen (= maxContentSize): keep reconstructing from the stable viewport for
+    // the whole keyboard-up-without-clean-baseline window.
+    const shouldSeedKbScreen = useEvent(
+      () => isWebKbSheet && !hasCleanKbBaseline.current && ignoreLayoutForKeyboard()
+    )
+
     const handleAnimationViewLayout = useEvent((e: LayoutChangeEvent) => {
       // don't update frameSize during exit animation to prevent position jumps
       if (!open && stableFrameSize.current !== 0) {
         return
       }
 
+      const seeding = shouldSeedKbFrame()
+      if (!seeding && ignoreLayoutForKeyboard()) return
+
       // avoid bugs where it grows forever for whatever reason
       // For inline mode (non-modal), don't cap at window height - use actual layout
       const layoutHeight = e.nativeEvent?.layout.height
-      const next = modal
-        ? Math.min(layoutHeight, Dimensions.get(relativeDimensionTo).height)
-        : layoutHeight
+      // while seeding, the keyboardStableFrameHeight fallback has unclipped the
+      // scroll view (capped at the stable screen) and the tail padding is
+      // suppressed, so this measures the pure pre-keyboard content height — cap it
+      // at the stable viewport like modal does.
+      const next =
+        modal || seeding
+          ? Math.min(layoutHeight, getStableViewportHeight())
+          : layoutHeight
       if (!next) return
-      setFrameSize(next)
+      // round: web onLayout reports sub-pixel heights (e.g. 499.99996) that jitter
+      // frame to frame as the view transforms; the raw float would re-fire every
+      // effect that depends on frameSize on each drag move.
+      const rounded = Math.round(next)
+      // seeding the frame: grow the baseline toward the unclipped content height.
+      // the first keyboard-up pass is clipped; the scroll-view override unclips it
+      // the next pass so it grows. once a pass doesn't exceed the running max the
+      // content has settled — mark the seed done so the next render exits the seed
+      // phase (freezeForKb pins this height, tail padding re-enables for scroll).
+      if (seeding) {
+        if (rounded > stableKbGeom.current.frame) {
+          stableKbGeom.current.frame = rounded
+        } else if (stableKbGeom.current.frame > 0) {
+          seedSettled.current = true
+        }
+      }
+      setFrameSize(rounded)
     })
 
-    const handleMaxContentViewLayout = React.useCallback((e: LayoutChangeEvent) => {
-      // avoid bugs where it grows forever for whatever reason
-      const next = Math.min(
-        e.nativeEvent?.layout.height,
-        Dimensions.get(relativeDimensionTo).height
-      )
-      if (!next) return
-      setMaxContentSize(next)
-    }, [])
+    const handleMaxContentViewLayout = React.useCallback(
+      (e: LayoutChangeEvent) => {
+        // same keyboard guard so screenSize (= maxContentSize) stays the full
+        // pre-keyboard viewport — except while seeding the baseline (see above),
+        // where we use the stable layout viewport directly so screenSize lands at
+        // the full pre-keyboard height instead of the shrunk visual viewport.
+        if (shouldSeedKbScreen()) {
+          setMaxContentSize(Math.round(getStableViewportHeight()))
+          return
+        }
+        if (ignoreLayoutForKeyboard()) return
+        // avoid bugs where it grows forever for whatever reason
+        const next = Math.min(e.nativeEvent?.layout.height, getStableViewportHeight())
+        if (!next) return
+        // round to avoid sub-pixel churn re-firing size-dependent effects
+        setMaxContentSize(Math.round(next))
+      },
+      [ignoreLayoutForKeyboard, shouldSeedKbScreen]
+    )
 
     const getAnimatedNumberStyle = React.useCallback(
       (val: number) => {
@@ -745,6 +986,9 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
           <SheetProvider
             {...providerProps}
             keyboardOccludedHeight={keyboardOccludedHeight}
+            isKeyboardVisible={isKeyboardVisible}
+            keyboardStableFrameHeight={keyboardStableFrameHeight}
+            isKeyboardSeeding={seedingKbBaseline}
             setHasScrollView={setHasScrollView}
           >
             <GestureSheetProvider

package/src/SheetScrollView.tsx

@@ -10,6 +10,7 @@ import { getGestureHandlerState, isGestureHandlerEnabled } from './gestureState'
 import { useSheetContext } from './SheetContext'
 import type { SheetScopedProps } from './types'
 import { useSheetScrollViewGestures } from './useSheetScrollViewGestures'
+import { getWebKeyboardHeight, MIN_KEYBOARD_HEIGHT } from './webViewport'
 
 const SHEET_SCROLL_VIEW_NAME = 'SheetScrollView'
 
@@ -31,6 +32,14 @@ export const SheetScrollView = React.forwardRef<
     const gestureContext = useGestureSheetContext()
     const { scrollBridge, setHasScrollView, hasFit, screenSize } = context
     const keyboardOccludedHeight = Math.max(0, context.keyboardOccludedHeight || 0)
+    // OR a LIVE DOM check: context.isKeyboardVisible (React state) lags the
+    // viewport resize, so on the open-transition render this component can re-run
+    // with the shrunk consumer maxHeight BEFORE the context flag flips. reading
+    // the keyboard height straight from visualViewport closes that race so the
+    // height freeze engages on the same render that would otherwise collapse it.
+    const isKeyboardVisible =
+      context.isKeyboardVisible === true ||
+      (isWeb && getWebKeyboardHeight() >= MIN_KEYBOARD_HEIGHT)
     const [scrollEnabled] = useControllableState({
       prop: scrollEnabledProp,
       defaultProp: true,
@@ -40,25 +49,47 @@ export const SheetScrollView = React.forwardRef<
     const [hasScrollableContent, setHasScrollableContent] = useState(true)
     const parentHeight = useRef(0)
     const contentHeight = useRef(0)
+    // the sheet's authoritative pre-keyboard frame height (see SheetImpl). a
+    // scroll-view-local high-water mark used to live here, but it was unreliable
+    // (the ref could read 0 if the view remounted on focus / never laid out while
+    // closed), so the height now comes from the sheet, which doesn't remount.
+    const frozenFrameHeight = Math.max(0, context.keyboardStableFrameHeight || 0)
 
     // with snapPointsMode="fit", Frame is content-sized (flex: 0, flex-basis: auto, height: undefined).
     // a flex: 1 child can't grow inside a content-sized parent, so the ScrollView (and the Frame
     // around it) collapse to 0 height. instead, let the ScrollView size to its content and cap it
     // at the available viewport (screenSize / maxContentSize) so scrolling kicks in for tall content.
-    // when the keyboard forces the sheet against the top safe area, preserve the measured viewport
-    // height while adding scrollable tail padding so content can move above the keyboard.
-    const keyboardFrozenHeight =
-      hasFit && keyboardOccludedHeight > 0 && parentHeight.current
-        ? parentHeight.current
-        : undefined
     const fitSizingStyle = hasFit
       ? {
           flex: undefined as undefined,
-          height: keyboardFrozenHeight,
+          height: undefined as undefined,
           maxHeight: screenSize || undefined,
         }
       : { flex: 1 }
 
+    // AUTOFOCUS-ON-OPEN seed (web): the sheet is still reconstructing its
+    // pre-keyboard frame baseline and needs THIS scroll view to size to its
+    // content so it can measure the true content height. so we apply the stable
+    // screen only as a maxHeight cap (UNCLIP from the shrunk consumer maxHeight)
+    // and leave height undefined so it stays content-sized.
+    const isKeyboardSeeding = context.isKeyboardSeeding === true
+
+    // when the keyboard is open the sheet stays ANCHORED at the bottom and keeps
+    // its full pre-keyboard height — the keyboard overlays its lower part and the
+    // keyboardOccludedHeight tail padding (added to the scroll content below) +
+    // browser scroll-into-view lift the focused input above the keyboard. so we
+    // pin the height to the sheet's authoritative frozenFrameHeight, overriding
+    // any consumer maxHeight (on web that's often tied to useWindowDimensions,
+    // which SHRINKS when the keyboard opens and would otherwise collapse the
+    // sheet). holding the height constant means nothing animates on keyboard
+    // open/close — no jump/teleport. applied AFTER {...props} so it wins.
+    const keyboardFrozenOverride =
+      hasFit && isKeyboardVisible && frozenFrameHeight > 0
+        ? isKeyboardSeeding
+          ? { maxHeight: frozenFrameHeight }
+          : { height: frozenFrameHeight, maxHeight: frozenFrameHeight }
+        : null
+
     const panGestureRef = gestureContext?.panGestureRef
     const { ScrollView: RNGHScrollView } = getGestureHandlerState()
     const useRNGHScrollView = isGestureHandlerEnabled() && RNGHScrollView && panGestureRef
@@ -102,6 +133,12 @@ export const SheetScrollView = React.forwardRef<
       }
     }
 
+    // track the fit height for the scrollable-content check. the keyboard-freeze
+    // height is supplied by the sheet (frozenFrameHeight), not derived here.
+    const recordFitHeight = (height: number) => {
+      parentHeight.current = height
+    }
+
     useEffect(() => {
       scrollBridge.hasScrollableContent = hasScrollableContent
     }, [hasScrollableContent])
@@ -148,7 +185,7 @@ export const SheetScrollView = React.forwardRef<
           scrollEnabled={scrollEnabled}
           simultaneousHandlers={[panGestureRef]}
           onLayout={(e: any) => {
-            parentHeight.current = Math.ceil(e.nativeEvent.layout.height)
+            recordFitHeight(Math.ceil(e.nativeEvent.layout.height))
             updateScrollable()
           }}
           onScroll={(e: any) => {
@@ -186,6 +223,7 @@ export const SheetScrollView = React.forwardRef<
           keyboardShouldPersistTaps="always"
           keyboardDismissMode="none"
           {...props}
+          {...keyboardFrozenOverride}
         >
           {contentWrapper}
         </RNGHComponent>
@@ -196,7 +234,7 @@ export const SheetScrollView = React.forwardRef<
     return (
       <ScrollView
         onLayout={(e) => {
-          parentHeight.current = Math.ceil(e.nativeEvent.layout.height)
+          recordFitHeight(Math.ceil(e.nativeEvent.layout.height))
           updateScrollable()
         }}
         ref={composeRefs(scrollRef as any, ref)}
@@ -213,6 +251,7 @@ export const SheetScrollView = React.forwardRef<
         contentContainerStyle={{ minHeight: '100%' }}
         {...gestureProps}
         {...props}
+        {...keyboardFrozenOverride}
       >
         {contentWrapper}
       </ScrollView>

package/src/nativeSheet.tsx

@@ -62,6 +62,9 @@ export function setupNativeSheet(
           <SheetProvider
             setHasScrollView={emptyFn}
             keyboardOccludedHeight={0}
+            isKeyboardVisible={false}
+            keyboardStableFrameHeight={0}
+            isKeyboardSeeding={false}
             {...providerProps}
             onlyShowFrame
           >

package/src/types.tsx

@@ -75,7 +75,8 @@ export type SheetProps = ScopedProps<
     zIndex?: number
     portalProps?: PortalProps
     /**
-     * Native-only flag that will make the sheet move up when the mobile keyboard opens so the focused input remains visible
+     * Makes the sheet move up when the mobile keyboard opens so the focused input remains visible.
+     * Works on native (via keyboard events) and on mobile web (via the VisualViewport API).
      */
     moveOnKeyboardChange?: boolean
     containerComponent?: React.ComponentType<any>
@@ -131,6 +132,15 @@ export type ScrollBridge = {
   isAtTop?: boolean
   // snap sheet to a specific position (for handoff UP)
   snapToPosition?: (positionIndex: number) => void
+  // re-baseline the pan drag origin to the current animated position. the web
+  // scroll-view hook calls this on each transition into pan ownership so a
+  // scroll→pan handoff resumes from where the sheet is, not a stale origin.
+  startPanDrag?: () => void
+  // web only: true while a touch is active on the ScrollView node. The web
+  // scroll-view gesture hook owns drag detection for those touches (it calls
+  // drag/release on this bridge), so the PanResponder must NOT also grant for
+  // them — otherwise two systems drive the animated position and it jitters.
+  scrollNodeTouched?: boolean
 }
 
 // keyboard controller sheet types