@tamagui/sheet 2.0.0 → 2.1.0-1780182832733

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tamagui/sheet",
-  "version": "2.0.0",
+  "version": "2.1.0-1780182832733",
   "license": "MIT",
   "source": "src/index.ts",
   "type": "module",
@@ -56,27 +56,27 @@
     "clean": "tamagui-build clean"
   },
   "dependencies": {
-    "@tamagui/adapt": "2.0.0",
-    "@tamagui/animate-presence": "2.0.0",
-    "@tamagui/animations-react-native": "2.0.0",
-    "@tamagui/compose-refs": "2.0.0",
-    "@tamagui/constants": "2.0.0",
-    "@tamagui/core": "2.0.0",
-    "@tamagui/create-context": "2.0.0",
-    "@tamagui/helpers": "2.0.0",
-    "@tamagui/native": "2.0.0",
-    "@tamagui/portal": "2.0.0",
-    "@tamagui/remove-scroll": "2.0.0",
-    "@tamagui/scroll-view": "2.0.0",
-    "@tamagui/stacks": "2.0.0",
-    "@tamagui/use-constant": "2.0.0",
-    "@tamagui/use-controllable-state": "2.0.0",
-    "@tamagui/use-did-finish-ssr": "2.0.0",
-    "@tamagui/use-keyboard-visible": "2.0.0",
-    "@tamagui/z-index-stack": "2.0.0"
+    "@tamagui/adapt": "2.1.0-1780182832733",
+    "@tamagui/animate-presence": "2.1.0-1780182832733",
+    "@tamagui/animations-react-native": "2.1.0-1780182832733",
+    "@tamagui/compose-refs": "2.1.0-1780182832733",
+    "@tamagui/constants": "2.1.0-1780182832733",
+    "@tamagui/core": "2.1.0-1780182832733",
+    "@tamagui/create-context": "2.1.0-1780182832733",
+    "@tamagui/helpers": "2.1.0-1780182832733",
+    "@tamagui/native": "2.1.0-1780182832733",
+    "@tamagui/portal": "2.1.0-1780182832733",
+    "@tamagui/remove-scroll": "2.1.0-1780182832733",
+    "@tamagui/scroll-view": "2.1.0-1780182832733",
+    "@tamagui/stacks": "2.1.0-1780182832733",
+    "@tamagui/use-constant": "2.1.0-1780182832733",
+    "@tamagui/use-controllable-state": "2.1.0-1780182832733",
+    "@tamagui/use-did-finish-ssr": "2.1.0-1780182832733",
+    "@tamagui/use-keyboard-visible": "2.1.0-1780182832733",
+    "@tamagui/z-index-stack": "2.1.0-1780182832733"
   },
   "devDependencies": {
-    "@tamagui/build": "2.0.0",
+    "@tamagui/build": "2.1.0-1780182832733",
     "react": ">=19",
     "react-native": "0.83.2",
     "react-native-gesture-handler": "~2.30.0"

package/src/SheetImplementationCustom.tsx

@@ -26,6 +26,12 @@ import { getGestureHandlerState } from './gestureState'
 import { GestureSheetProvider } from './GestureSheetContext'
 import { resisted } from './helpers'
 import { getKeyboardOccludedHeight } from './keyboardAvoidance'
+import {
+  getMaxViewportHeight,
+  getStableLayoutViewportHeight,
+  getWebKeyboardHeight,
+  MIN_KEYBOARD_HEIGHT,
+} from './webViewport'
 import { SheetProvider } from './SheetContext'
 import type { SheetProps, SnapPointsMode } from './types'
 import { useGestureHandlerPan } from './useGestureHandlerPan'
@@ -57,6 +63,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 +161,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 +184,42 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       }
     }, [open, frameSize])
 
-    // use stableFrameSize when closing to prevent position jumps during exit animation
-    // but when opening, always use the current frameSize so positions update correctly
+    // 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
+
+    // the space the snap positions are built against. WEB: the stable layout
+    // viewport (document.documentElement.clientHeight), which the soft keyboard
+    // never shrinks (unlike the measured screenSize / visualViewport). NATIVE:
+    // the measured screenSize. positions are then shifted UP by keyboardHeight
+    // when the keyboard opens (activePositions, below) — the whole device-height
+    // frame slides up so its content clears the keyboard, capped at the safe area.
+    const effScreenSize = isWebKbSheet ? getStableViewportHeight() : screenSize
+
+    // use stableFrameSize when closing to prevent position jumps during the exit
+    // animation; while open use the live frameSize.
     const effectiveFrameSize = 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 +241,30 @@ 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 — the keyboard is an overlay, so the frame neither shifts nor resizes.
+    // Avoidance is handled below the frame: a bottom spacer (keyboardOccludedHeight
+    // = keyboardHeight) extends the scroll content so the lower content (e.g. the
+    // footer) can scroll up clear of the keyboard, and SheetScrollView scrolls the
+    // focused input above it. So activePositions === positions on web (no shift).
+    //
+    // 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 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.
+    // 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) {
         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,14 +277,27 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       return result
     }, [positions, isKeyboardVisible, keyboardHeight, screenSize, isDragging])
 
+    // bottom spacer for a sheet TALLER than the visible band: once the frame has
+    // shifted up as far as the safe-area cap allows, its lowest content can still
+    // sit behind the keyboard. the spacer = exactly that occluded height, so the
+    // footer can scroll up clear of the keyboard. when the sheet fits above the
+    // keyboard this returns 0 (no spacer, no over-scroll). same logic web + native.
     const keyboardOccludedHeight = getKeyboardOccludedHeight({
-      frameSize,
-      isKeyboardVisible: !isWeb && isKeyboardVisible,
+      frameSize: effectiveFrameSize,
+      isKeyboardVisible,
       keyboardHeight,
-      screenSize,
+      screenSize: effScreenSize,
       sheetY: position >= 0 ? activePositions[position] : undefined,
     })
 
+    // pin the scroll view to the held (pre-keyboard) frame height while the
+    // keyboard is up on web. on older iOS the consumer's window-derived maxHeight
+    // shrinks with the keyboard, which would clip the scroll view (and the frame)
+    // smaller; this override keeps it at the full height so the frame only
+    // translates up, never resizes. 0 = no override (use the consumer maxHeight).
+    const keyboardStableFrameHeight =
+      isWebKbSheet && isKeyboardVisible && frameSize > 0 ? frameSize : 0
+
     const { useAnimatedNumber, useAnimatedNumberStyle, useAnimatedNumberReaction } =
       animationDriver
     const AnimatedView = (animationDriver.View ?? TamaguiView) as typeof Animated.View
@@ -325,7 +383,19 @@ 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.
+      //
+      // web: clear the maximum the viewport can ever reveal, not just the current
+      // layout viewport. iOS Safari retracts its chrome on scroll and exposes area
+      // below the current viewport, so a sheet parked at effScreenSize would peek
+      // back in as the page scrolls. getMaxViewportHeight floors the target past
+      // anything Safari can expose.
+      const closeTarget = isWeb
+        ? Math.max(effScreenSize, getMaxViewportHeight())
+        : effScreenSize
+      let toValue = isHidden || position === -1 ? closeTarget : activePositions[position]
 
       if (at.current === toValue) return
 
@@ -417,6 +487,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
       }
@@ -443,6 +523,10 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
           scrollBridge.setScrollEnabled?.(false)
         }
       }
+      // NOTE: effScreenSize/effectiveFrameSize are intentionally NOT deps. With the
+      // spacer approach the frame's position target is frozen across keyboard
+      // open/close (same stable baseline), so it must NOT re-animate — keyboard
+      // avoidance is the bottom spacer + scroll, not a frame move.
     }, [hasntMeasured, disableAnimation, isHidden, frameSize, screenSize, open, position])
 
     const disableDrag = props.disableDrag ?? controller?.disableDrag
@@ -454,7 +538,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 +585,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 +618,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 +673,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,13 +725,25 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
         onPanResponderTerminate: finish,
         onPanResponderRelease: finish,
       })
-    }, [disableDrag, isShowingInnerSheet, animateTo, frameSize, positions, setPosition])
-
-    // animate to keyboard-adjusted position when keyboard state changes
+    }, [
+      disableDrag,
+      isShowingInnerSheet,
+      animateTo,
+      frameSize,
+      activePositions,
+      setPosition,
+    ])
+
+    // animate to the keyboard-adjusted position when the keyboard state changes.
+    // both web and native shift the whole frame UP by the keyboard height (capped
+    // at the top safe area, in activePositions) so the content keeps its position
+    // relative to the visible area — it was resting on the device bottom, now it
+    // rests on the keyboard top. the frame is device-height, so sliding it up never
+    // reveals a gap below the content.
     React.useEffect(() => {
       if (isDragging || isHidden || !open || disableAnimation) return
       if (!frameSize || !screenSize) return
-      // use timing animation to match iOS keyboard animation (~250ms)
+      // timing animation matches the iOS keyboard animation (~250ms)
       animateTo(position, { type: 'timing', duration: 250 })
     }, [isKeyboardVisible, keyboardHeight])
 
@@ -647,6 +768,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 +797,57 @@ 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
+    )
+
     const handleAnimationViewLayout = useEvent((e: LayoutChangeEvent) => {
       // don't update frameSize during exit animation to prevent position jumps
       if (!open && stableFrameSize.current !== 0) {
         return
       }
 
+      const layoutHeight = e.nativeEvent?.layout.height
+      // drop a layout measured while the keyboard is up: on older iOS the web
+      // viewport shrinks and the frame would resize. keep the pre-keyboard frame
+      // height so the frame just TRANSLATES up (activePositions) without resizing.
+      // exception: if we have no frame height yet (sheet opened with the keyboard
+      // already up), accept it so the sheet can appear at all.
+      if (ignoreLayoutForKeyboard() && frameSize > 0) 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)
+        ? 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.
+      setFrameSize(Math.round(next))
     })
 
-    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) => {
+        // keep maxContentSize at the full pre-keyboard viewport: drop layouts
+        // measured while the keyboard is up (the shrunk viewport), unless we have
+        // none yet (keyboard-already-up open).
+        if (ignoreLayoutForKeyboard() && screenSize > 0) 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, screenSize]
+    )
 
     const getAnimatedNumberStyle = React.useCallback(
       (val: number) => {
@@ -745,6 +897,8 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
           <SheetProvider
             {...providerProps}
             keyboardOccludedHeight={keyboardOccludedHeight}
+            isKeyboardVisible={isKeyboardVisible}
+            keyboardStableFrameHeight={keyboardStableFrameHeight}
             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,35 @@ 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 }
 
+    // when the keyboard is open, pin the scroll view to the sheet's pre-keyboard
+    // frame height (frozenFrameHeight), overriding any consumer maxHeight. on web
+    // that maxHeight is often tied to useWindowDimensions, which SHRINKS when the
+    // keyboard opens and would otherwise collapse the sheet. holding the height
+    // constant means the frame only TRANSLATES up (no resize, no jump). applied
+    // AFTER {...props} so it wins.
+    const keyboardFrozenOverride =
+      hasFit && isKeyboardVisible && frozenFrameHeight > 0
+        ? { height: frozenFrameHeight, maxHeight: frozenFrameHeight }
+        : null
+
     const panGestureRef = gestureContext?.panGestureRef
     const { ScrollView: RNGHScrollView } = getGestureHandlerState()
     const useRNGHScrollView = isGestureHandlerEnabled() && RNGHScrollView && panGestureRef
@@ -102,6 +121,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 +173,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 +211,7 @@ export const SheetScrollView = React.forwardRef<
           keyboardShouldPersistTaps="always"
           keyboardDismissMode="none"
           {...props}
+          {...keyboardFrozenOverride}
         >
           {contentWrapper}
         </RNGHComponent>
@@ -196,7 +222,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 +239,7 @@ export const SheetScrollView = React.forwardRef<
         contentContainerStyle={{ minHeight: '100%' }}
         {...gestureProps}
         {...props}
+        {...keyboardFrozenOverride}
       >
         {contentWrapper}
       </ScrollView>

package/src/createSheet.tsx

@@ -1,5 +1,5 @@
 import { useComposedRefs } from '@tamagui/compose-refs'
-import { useIsomorphicLayoutEffect } from '@tamagui/constants'
+import { isWeb, useIsomorphicLayoutEffect } from '@tamagui/constants'
 import type {
   GetProps,
   ViewProps,
@@ -25,6 +25,7 @@ import { SheetScrollView } from './SheetScrollView'
 import type { SheetProps, SheetScopedProps } from './types'
 import { useSheetController } from './useSheetController'
 import { useSheetOffscreenSize } from './useSheetOffscreenSize'
+import { getMaxViewportHeight } from './webViewport'
 
 type SharedSheetProps = {
   open?: boolean
@@ -136,9 +137,9 @@ export function createSheet<
 
   type ExtraFrameProps = {
     /**
-     * By default the sheet adds a view below its bottom that extends down another 50%,
-     * this is useful if your Sheet has a spring animation that bounces "past" the top when
-     * opening, preventing it from showing the content underneath.
+     * by default the sheet adds a view below its bottom that extends past the
+     * largest visible viewport height. this covers spring overshoot when opening
+     * so page content never shows through below the sheet.
      */
     disableHideBottomOverflow?: boolean
 
@@ -225,14 +226,25 @@ export function createSheet<
             <Frame
               {...props}
               componentName="SheetCover"
+              data-sheet-cover=""
               children={null}
               // Don't inherit testID - this is a visual helper element
               testID={undefined}
               id={undefined}
               position="absolute"
-              bottom="-100%"
+              // anchor the cover's top at the sheet's bottom edge (top: 100% of the
+              // container), then extend it downward. on web extend it past the
+              // largest viewport safari can reveal as its chrome retracts, so the
+              // sheet background covers the bottom instead of revealing the page.
+              // native keeps frameSize.
+              top="100%"
               zIndex={-1}
-              height={context.frameSize}
+              height={
+                isWeb
+                  ? Math.max(context.frameSize, getMaxViewportHeight())
+                  : context.frameSize
+              }
+              maxHeight={isWeb ? 'none' : undefined}
               left={0}
               right={0}
               borderWidth={0}

package/src/nativeSheet.tsx

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