@rific/scroll-view 0.8.3 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rific/scroll-view",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "description": "Blur styled scroll system for React Native. Floating headers/footers, keyboard awareness, and scroll-away chrome",
   "keywords": [
     "react-native",
@@ -65,8 +65,8 @@
     "@infinitetoken/jest-config": "^0.4.0",
     "@infinitetoken/tsconfig": "^0.5.0",
     "@reduxjs/toolkit": "^2.12.0",
-    "@rific/auto-paper": "^0.12.0",
-    "@rific/core": "^0.2.0",
+    "@rific/auto-paper": "^0.13.2",
+    "@rific/core": "^0.3.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/jest": "^30.0.0",
@@ -80,7 +80,7 @@
     "prettier": "^3.8.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "react-native": "^0.83.0",
+    "react-native": "^0.86.3",
     "react-native-gesture-handler": "^2.32.0",
     "react-native-keyboard-controller": "*",
     "react-native-paper": "^5.12.0",

package/src/CustomList.tsx

@@ -38,13 +38,13 @@ const CustomListInner = <P extends object>({ chipProps, chipThreshold, component
 
   const { chipHidden, chipStyle, containerStyle, contentInset, contentOffset, contentPadding, footerFixed, headerFixed } = useScrollList({ footerFixed: footerFixedProp, headerFixed: headerFixedProp, keyboardAware, pullSearchHeight, style })
   const { listGeneration, onListUnmount } = useContext(ScrollViewContext)
-  // -1 never matches a real generation (starts at 0, only increments) — the runOnUI call below
+  // -1 never matches a real generation (starts at 0, only increments) - the runOnUI call below
   // corrects it before any scroll event could observe the placeholder.
   const capturedGeneration = useSharedValue(-1)
   // Layout effects (not passive effects): React guarantees all layout-effect cleanups for fibers
   // removed in a commit run before any layout-effect setups for fibers added in that same commit,
   // but gives no such ordering guarantee for passive effects. On a key-forced remount, the outgoing
-  // instance's unmount and the incoming instance's mount land in the same commit — with passive
+  // instance's unmount and the incoming instance's mount land in the same commit - with passive
   // effects, the incoming instance's sync could run before the outgoing instance's bump, permanently
   // capturing a stale generation and silently disabling this instance's onScroll handling forever.
   // Correct ordering alone isn't sufficient, though: the onScroll worklet reads capturedGeneration
@@ -54,7 +54,7 @@ const CustomListInner = <P extends object>({ chipProps, chipThreshold, component
   // own serial queue, so it's guaranteed to run before any onScroll worklet invocation that could
   // only be queued after this component finishes mounting.
   //
-  // Web has no such thread split, though — see ScrollView.tsx's own doc comment on this same
+  // Web has no such thread split, though - see ScrollView.tsx's own doc comment on this same
   // pattern for why runOnUI's deferred-to-next-frame behavior there leaves a real gap, and why a
   // synchronous assignment is the correct fix rather than a workaround.
   useLayoutEffect(() => {

package/src/FlatList.tsx

@@ -30,9 +30,9 @@ export type FlatListProps<T> = Omit<RNFlatListProps<T>, 'onRefresh' | 'refreshin
 
 const FlatListInner = <T,>({ chipProps, chipThreshold, columnWrapperStyle, contentContainerStyle: externalContentContainerStyle, data, initialNumToRender = 20, keyExtractor, maxToRenderPerBatch = 50, numColumns, renderFilters, renderItem, footerFixed: footerFixedProp, gesture, headerFixed: headerFixedProp, horizontal, keyboardAware, ListHeaderComponent: externalListHeaderComponent, onChipPress, onMomentumScrollEnd: externalMomentumScrollEnd, onRefresh, onScrollBeginDrag: externalScrollBeginDrag, onScrollEndDrag: externalScrollEndDrag, pagingEnabled, pullSearchHeight, refreshing, removeClippedSubviews = false, showsHorizontalScrollIndicator, showsVerticalScrollIndicator, style, onContentSizeChange, ref: externalRef, windowSize = 100, ...props }: FlatListProps<T>) => {
   // Plain (non-Animated) FlatList: react-native-reanimated's Animated.FlatList does not reliably
-  // honor the initial `contentOffset` prop on a key-forced remount — the header/list can briefly
+  // honor the initial `contentOffset` prop on a key-forced remount - the header/list can briefly
   // render at the wrong position. A plain FlatList honors it correctly, so scroll position is driven
-  // by a regular JS onScroll callback (useScrollHandlerJS) instead of a Reanimated worklet — which
+  // by a regular JS onScroll callback (useScrollHandlerJS) instead of a Reanimated worklet - which
   // also avoids the "WorkletEventHandler" crash that a worklet handler triggers when attached to a
   // non-Animated component.
   const scrollView = useRef<RNFlatList<T>>(null)
@@ -42,10 +42,10 @@ const FlatListInner = <T,>({ chipProps, chipThreshold, columnWrapperStyle, conte
   // RN's own FlatList implements numColumns by chunking `data` into rows internally, but throws if
   // numColumns ever changes without the caller changing `key` to force a full remount. On iOS,
   // Fabric pools/recycles native ScrollView instances by component type across such a remount, and
-  // the recycled instance's onScroll can silently stop firing for the new React instance entirely —
+  // the recycled instance's onScroll can silently stop firing for the new React instance entirely -
   // a native event-routing issue, not something a JS-side retry loop can detect or correct. Doing
   // the row-chunking ourselves here and always passing numColumns={1} through to the underlying
-  // RNFlatList means numColumns never "changes" from RN's perspective — only `data`/`renderItem`
+  // RNFlatList means numColumns never "changes" from RN's perspective - only `data`/`renderItem`
   // change, which RNFlatList treats as an ordinary prop update with no remount at all, so callers
   // can toggle numColumns freely (e.g. switching a list to a grid) without ever hitting this class
   // of bug.

package/src/PullSearch.tsx

@@ -47,7 +47,7 @@ export const PullSearch = forwardRef<PullSearchHandle, PullSearchProps>(function
     (isHidden, wasHidden) => {
       if (isHidden && !wasHidden) runOnJS(blurInput)()
     },
-    // scrollPosition has to be listed too, not just read — see useStickyHeaders' useAnimatedReaction
+    // scrollPosition has to be listed too, not just read - see useStickyHeaders' useAnimatedReaction
     // for why: on web, without reanimated's Babel plugin active, an unlisted SharedValue mutation
     // never re-triggers this reaction (confirmed empirically elsewhere in this package).
     [barHeight, headerHeight, blurInput, scrollPosition]

package/src/ScrollView.tsx

@@ -32,13 +32,13 @@ const ScrollViewInner = ({ chipProps, chipThreshold, children, contentContainerS
 
   const { chipHidden, chipStyle, containerStyle, contentInset, contentOffset, contentPadding, footerFixed, headerFixed } = useScrollList({ footerFixed: footerFixedProp, headerFixed: headerFixedProp, isHorizontal, keyboardAware, pullSearchHeight, style })
   const { listGeneration, onListUnmount } = useContext(ScrollViewContext)
-  // -1 never matches a real generation (starts at 0, only increments) — the runOnUI call below
+  // -1 never matches a real generation (starts at 0, only increments) - the runOnUI call below
   // corrects it before any scroll event could observe the placeholder.
   const capturedGeneration = useSharedValue(-1)
   // Layout effects (not passive effects): React guarantees all layout-effect cleanups for fibers
   // removed in a commit run before any layout-effect setups for fibers added in that same commit,
   // but gives no such ordering guarantee for passive effects. On a key-forced remount, the outgoing
-  // instance's unmount and the incoming instance's mount land in the same commit — with passive
+  // instance's unmount and the incoming instance's mount land in the same commit - with passive
   // effects, the incoming instance's sync could run before the outgoing instance's bump, permanently
   // capturing a stale generation and silently disabling this instance's onScroll handling forever.
   // Correct ordering alone isn't sufficient, though: the onScroll worklet reads capturedGeneration
@@ -48,12 +48,12 @@ const ScrollViewInner = ({ chipProps, chipThreshold, children, contentContainerS
   // own serial queue, so it's guaranteed to run before any onScroll worklet invocation that could
   // only be queued after this component finishes mounting.
   //
-  // Web has no such thread split, though — react-native-worklets' own runOnUI there (see its
+  // Web has no such thread split, though - react-native-worklets' own runOnUI there (see its
   // threads.js) only enqueues the callback for the NEXT requestAnimationFrame, it doesn't run it
   // synchronously. That opens exactly the gap the native path exists to close: a scroll event
   // (including useScrollInit's own mount-time imperative scrollTo) landing before that deferred
   // frame sees capturedGeneration still at its -1 placeholder, fails the generation check below,
-  // and — since this effect only ever runs once per mount — never gets a second chance, silently
+  // and - since this effect only ever runs once per mount - never gets a second chance, silently
   // disabling scroll tracking (and therefore header/footer scroll-away) for this instance's entire
   // lifetime. Assigning directly is both simpler and provably correct on web: single-threaded JS
   // makes a synchronous write immediately visible to any read that follows it in program order, so

package/src/ScrollViewChromeContext.ts

@@ -0,0 +1,37 @@
+import { createContext } from 'react'
+import type { SharedValue } from 'react-native-reanimated'
+
+// Two contexts, deliberately split by who is allowed to see them:
+//
+// ScrollViewChromeHostContext is the claim machinery. ScrollViewProvider reads it to decide whether
+// it is "hosted" and then immediately re-provides `null` around its own children, so a nested
+// ScrollViewProvider (a picker or form modal rendered inside a screen) never sees the host and never
+// competes with its parent screen for it.
+//
+// ScrollViewChromeContext is the public, never-cleared face of the same host: the shared offset a
+// persistent bar animates from, plus pin/reveal controls. It has to survive the clearing above
+// because the components that use it (a search bar, a pager) sit *below* a ScrollViewProvider.
+export type ScrollViewChromeHost = {
+  activeId: string | null
+  claim: (id: string) => void
+  footprint: number
+  offset: SharedValue<number>
+  overhang: number
+  pinned: boolean
+  release: (id: string) => void
+  reveal: () => void
+  snapBack: boolean
+  useIsActive: () => boolean
+}
+
+export type ScrollViewChrome = {
+  addPin: () => void
+  footprint: number
+  offset: SharedValue<number>
+  overhang: number
+  removePin: () => void
+  reveal: () => void
+}
+
+export const ScrollViewChromeHostContext = createContext<ScrollViewChromeHost | null>(null)
+export const ScrollViewChromeContext = createContext<ScrollViewChrome | null>(null)

package/src/ScrollViewChromeProvider.tsx

@@ -0,0 +1,65 @@
+import { type ReactNode, useCallback, useEffect, useMemo, useState } from 'react'
+import { useSharedValue, withTiming } from 'react-native-reanimated'
+
+import { ScrollViewChromeContext, ScrollViewChromeHostContext } from './ScrollViewChromeContext'
+
+const REVEAL_DURATION = 200
+
+const alwaysActive = () => true
+
+export type ScrollViewChromeProviderProps = {
+  children: ReactNode
+  // Height of a persistent bottom bar's resting box (its row + safe-area inset), i.e. how far up from
+  // the screen bottom a hosted ScrollViewFooter has to sit to clear it. Passed in as a plain number
+  // rather than reported back by the bar, so every hosted screen has the right geometry on its very
+  // first render instead of one commit later.
+  footprint: number
+  // How far the bar pokes ABOVE its resting box (a FAB that dips out of it, say). Hosted footers pad
+  // their bottom by this instead of the safe-area inset, and the hide distance covers it.
+  overhang?: number
+  // Hosted footers reveal on a short scroll-up instead of only near the top. A bar that hides on
+  // scroll has to be reachable from anywhere in a list, so this is on by default - and there is no
+  // "hide but only reveal near the top" mode: `snapBack={false}` turns hiding off entirely, leaving
+  // the bar and hosted footers permanently revealed.
+  snapBack?: boolean
+  // A hook (not a plain function) returning whether the calling screen is the focused one, e.g.
+  // react-navigation's useIsFocused. Injected rather than imported so this package carries no
+  // navigation dependency. It has to be a stable reference: it is called as a hook on every render.
+  useIsActive?: () => boolean
+}
+
+// Mounted once above a navigator (a Tabs layout). Every ScrollViewProvider below it that is focused
+// claims it, and while it does, that screen's scroll handlers drive one shared `offset` that the
+// screen's own ScrollViewFooter AND the persistent bar both translate by - a single value read by
+// both, so the two move as one rigid stack instead of being two animations that have to be kept in
+// step.
+export const ScrollViewChromeProvider = ({ children, footprint, overhang = 0, snapBack = true, useIsActive = alwaysActive }: ScrollViewChromeProviderProps) => {
+  const offset = useSharedValue(0)
+  const [claims, setClaims] = useState<string[]>([])
+  const [pins, setPins] = useState(0)
+  const activeId = claims.length > 0 ? claims[claims.length - 1] : null
+  const pinned = pins > 0
+  const claim = useCallback((id: string) => setClaims((current) => [...current.filter((c) => c !== id), id]), [])
+  const release = useCallback((id: string) => setClaims((current) => current.filter((c) => c !== id)), [])
+  const addPin = useCallback(() => setPins((current) => current + 1), [])
+  const removePin = useCallback(() => setPins((current) => Math.max(0, current - 1)), [])
+  const reveal = useCallback(() => {
+    offset.value = withTiming(0, { duration: REVEAL_DURATION })
+  }, [offset])
+  // offset is per-host but the scroll state that produced it is per-screen, and nothing else ever
+  // zeroes it except a scroll event landing at the top of a list. Without this, popping back to a
+  // screen that was hidden when it lost focus, or focusing one with no scroll view at all, would
+  // leave the bar wherever the last screen parked it. Any change of who owns the host, or a pin
+  // engaging (which also turns the scroll handlers off, so nothing else would ever bring it back),
+  // starts from fully revealed.
+  useEffect(() => {
+    reveal()
+  }, [activeId, pinned, reveal])
+  const host = useMemo(() => ({ activeId, claim, footprint, offset, overhang, pinned, release, reveal, snapBack, useIsActive }), [activeId, claim, footprint, offset, overhang, pinned, release, reveal, snapBack, useIsActive])
+  const chrome = useMemo(() => ({ addPin, footprint, offset, overhang, removePin, reveal }), [addPin, footprint, offset, overhang, removePin, reveal])
+  return (
+    <ScrollViewChromeContext.Provider value={chrome}>
+      <ScrollViewChromeHostContext.Provider value={host}>{children}</ScrollViewChromeHostContext.Provider>
+    </ScrollViewChromeContext.Provider>
+  )
+}

package/src/ScrollViewContext.ts

@@ -3,6 +3,14 @@ import { SharedValue } from 'react-native-reanimated'
 
 export type ScrollViewContextType = {
   blur: boolean
+  // True when this provider is driven by a ScrollViewChromeProvider above the navigator (see
+  // ScrollViewChromeProvider). Hosted footers sit above the persistent bar, share its offset, and
+  // always snap back.
+  chromeHosted: boolean
+  chromeOverhang: number
+  // Whether this provider's scroll handlers may currently write footerOffset: always true unhosted,
+  // and only while this provider owns the host (and nothing has pinned it) when hosted.
+  chromeWritable: SharedValue<boolean>
   footerAboveKeyboard: boolean
   footerHeight: number | null
   footerHeightShared: SharedValue<number>
@@ -15,7 +23,7 @@ export type ScrollViewContextType = {
   // Plain (non-Reanimated) counter for JS-thread-only scroll handlers (FlatList's useScrollHandlerJS).
   // A SharedValue is deliberately NOT used here: mutating `.value` from inside a React commit-phase
   // callback (a layout effect) is not synchronously visible even to an immediate subsequent read in
-  // the same callback — Reanimated defers the actual flush — which silently broke the "did another
+  // the same callback - Reanimated defers the actual flush - which silently broke the "did another
   // list instance just unmount" check this counter exists for. A plain ref has no such batching.
   jsListGeneration: RefObject<number>
   listGeneration: SharedValue<number>
@@ -32,11 +40,18 @@ export type ScrollViewContextType = {
   setHeaderHeight: (h: number | null) => void
   setProgress: (p: number | null) => void
   setProgressing: (b: boolean) => void
+  // The farthest footerOffset can travel: how far the whole bottom stack has to slide to clear the
+  // screen. Unhosted this IS footerHeightShared (the same SharedValue), so unhosted snap-back
+  // clamps exactly as it always has.
+  stackHeightShared: SharedValue<number>
   tabBarHeight: number
 }
 
 export const ScrollViewContext = createContext<ScrollViewContextType>({
   blur: true,
+  chromeHosted: false,
+  chromeOverhang: 0,
+  chromeWritable: null as unknown as SharedValue<boolean>,
   footerAboveKeyboard: false,
   footerHeight: null,
   footerHeightShared: null as unknown as SharedValue<number>,
@@ -61,5 +76,6 @@ export const ScrollViewContext = createContext<ScrollViewContextType>({
   setProgressing: () => {},
   snapBackFooterShared: null as unknown as SharedValue<boolean>,
   snapBackHeaderShared: null as unknown as SharedValue<boolean>,
+  stackHeightShared: null as unknown as SharedValue<number>,
   tabBarHeight: 0
 })

package/src/ScrollViewFooter.tsx

@@ -1,6 +1,6 @@
 import { BlurView } from '@rific/auto-paper'
-import { type ReactNode, useContext, useEffect, useRef } from 'react'
-import { type LayoutChangeEvent, StyleSheet, View, type ViewStyle } from 'react-native'
+import { type ReactNode, useContext, useEffect, useLayoutEffect, useRef } from 'react'
+import { type LayoutChangeEvent, Platform, StyleSheet, View, type ViewStyle } from 'react-native'
 import Animated, { useAnimatedStyle } from 'react-native-reanimated'
 import { useSafeAreaInsets } from 'react-native-safe-area-context'
 
@@ -13,17 +13,17 @@ export type ScrollViewFooterProps = {
 }
 
 export const ScrollViewFooter = ({ children, style }: ScrollViewFooterProps) => {
-  const { blur, footerAboveKeyboard, footerHeight, footerFixed, footerOffset, headerHeightShared, pullSearchHeightShared, scrollPosition, setFooterHeight, snapBackFooterShared, tabBarHeight } = useContext(ScrollViewContext)
+  const { blur, chromeHosted, chromeOverhang, footerAboveKeyboard, footerHeight, footerFixed, footerOffset, headerHeightShared, pullSearchHeightShared, scrollPosition, setFooterHeight, snapBackFooterShared, stackHeightShared, tabBarHeight } = useContext(ScrollViewContext)
   const insets = useSafeAreaInsets()
   const keyboardHeight = useKeyboardInset()
-  // setFooterHeight's own identity changes on every real measurement (ScrollViewProvider's
-  // useCallback closes over `footerHeight` itself, so setting it recreates the callback). Depending
-  // on it directly here re-ran this effect on every measurement too — tearing down the PREVIOUS
-  // closure as a "cleanup" and calling ITS setFooterHeight(null) right after the real height had
-  // just been set, permanently clobbering it back to null with no further layout event left to
-  // recover it (the DOM node's true size never changed, so onLayout never fires again). Reading
-  // through a ref sidesteps that: the effect itself only ever runs once, on mount/unmount, so its
-  // cleanup fires exactly when it's meant to (a real unmount) rather than after every measurement.
+  // setFooterHeight used to change identity on every real measurement (ScrollViewProvider's
+  // useCallback closed over `footerHeight` itself). Depending on it directly here re-ran this
+  // effect on every measurement too - tearing down the PREVIOUS closure as a "cleanup" and calling
+  // ITS setFooterHeight(null) right after the real height had just been set, permanently clobbering
+  // it back to null with no further layout event left to recover it (the DOM node's true size never
+  // changed, so onLayout never fires again). The provider's setter is stable now, but the context
+  // type doesn't promise that, so this still reads through a ref: the effect itself only ever runs
+  // once, on mount/unmount, so its cleanup fires exactly when it's meant to (a real unmount).
   // The mirror below has to be effect-based too, not a bare render-time assignment: writing to the
   // ref during render is a React-render-purity violation (render can be discarded/replayed), so it's
   // done in its own no-deps effect, which still re-runs on every commit and keeps the ref current.
@@ -46,17 +46,23 @@ export const ScrollViewFooter = ({ children, style }: ScrollViewFooterProps) =>
   }
   // See ScrollViewHeader's translateStyle/blurStyle/progressStyle for why every SharedValue read
   // here (scrollPosition, headerHeightShared, pullSearchHeightShared, snapBackFooterShared,
-  // footerOffset) also has to be listed explicitly — on web, reanimated doesn't pick up their
+  // footerOffset) also has to be listed explicitly - on web, reanimated doesn't pick up their
   // mutations as reactive triggers unless they're in this array, unlike native.
   const footerStyle = useAnimatedStyle(() => {
+    // Hosted, the offset is the ONE value the persistent bar translates by too, so it is always
+    // read straight through - never short-circuited to 0 for footerFixed the way the unhosted path
+    // below is. Footer Lock reaches it by animating the shared offset back to 0 instead (see
+    // ChromeRegistrar), which keeps this footer and the bar equal on every frame, including the
+    // ones where one would otherwise jump and the other animate.
+    if (chromeHosted) return { transform: [{ translateY: Math.min(Math.max(footerOffset.value, 0), stackHeightShared.value) }] }
     if (footerFixed) return { transform: [{ translateY: 0 }] }
     if (snapBackFooterShared.value) return { transform: [{ translateY: footerOffset.value }] }
     const effective = scrollPosition.value + headerHeightShared.value - pullSearchHeightShared.value
     if (effective <= 0) return { transform: [{ translateY: 0 }] }
     return { transform: [{ translateY: Math.min(effective, footerHeight ?? 0) }] }
-  }, [footerHeight, footerFixed, headerHeightShared, pullSearchHeightShared, scrollPosition, snapBackFooterShared, footerOffset])
+  }, [chromeHosted, footerHeight, footerFixed, headerHeightShared, pullSearchHeightShared, scrollPosition, snapBackFooterShared, footerOffset, stackHeightShared])
   // Floating above the keyboard is done by GROWING this container (via paddingBottom) rather than
-  // translating it. Translating the whole bar left its bottom edge — and the BlurView filling it —
+  // translating it. Translating the whole bar left its bottom edge - and the BlurView filling it -
   // floating above the true screen bottom, exposing a gap of whatever sits behind (visible as a
   // strip above the keyboard, and worse at the keyboard's rounded top corners, which dip below its
   // reported height). Growing the container instead keeps its `bottom: 0` anchor untouched: the
@@ -64,25 +70,53 @@ export const ScrollViewFooter = ({ children, style }: ScrollViewFooterProps) =>
   // while the extra height pushes the row (this bar's actual content) up by keyboardHeight, same
   // as the old translateY did for it.
   const containerPaddingBottom = footerFixed && footerAboveKeyboard ? keyboardHeight : 0
+  // Web only, same as ScrollViewHeader's pre-paint measurement: react-native-web's onLayout lands
+  // well after the first paint (a ResizeObserver callback plus a setTimeout measure - over a second
+  // on a cold load), and until footerHeight is known this footer draws no backdrop (see the
+  // BlurView gate below) and the list reserves no room for it, so the row floated bare over the
+  // content and its bar only appeared once the measurement arrived. Measuring the row here, after
+  // the DOM is built but before the browser paints, makes the very first frame the final one. The
+  // container's own height is the row plus containerPaddingBottom, which is what onLayout reports,
+  // so that later onLayout is a no-op. A node with no layout box (hidden ancestor) reports 0 and
+  // is left to onLayout; a footer mounting while another's height is already known does too.
+  const rowRef = useRef<View>(null)
+  useLayoutEffect(() => {
+    if (Platform.OS !== 'web' || footerHeight) return
+    const height = (rowRef.current as unknown as { offsetHeight?: unknown } | null)?.offsetHeight
+    if (typeof height !== 'number' || height <= 0) return
+    setFooterHeight(height + containerPaddingBottom)
+    // Mount-only: after this, onLayout owns every later change.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
   // The safe-area bottom inset exists to clear the home indicator at the physical screen edge.
   // Once footerAboveKeyboard has floated this bar's content up above an open keyboard, it's no
-  // longer sitting at that edge — the keyboard itself now occupies that space — so the inset would
+  // longer sitting at that edge - the keyboard itself now occupies that space - so the inset would
   // just be dead space under the content (e.g. under a Save button) for no reason.
   //
   // This has to ramp continuously with keyboardHeight, not flip as a boolean once the keyboard
   // fully closes: containerPaddingBottom above already tracks keyboardHeight every frame, so a
   // step-function padding change here lands in the same frame keyboardHeight hits 0, growing this
-  // row by insets.bottom right as the container finishes shrinking back down — the content visually
+  // row by insets.bottom right as the container finishes shrinking back down - the content visually
   // overshoots to the physical bottom edge and then snaps back up. Ramping this padding by the same
   // keyboardHeight keeps the content's on-screen position moving continuously throughout: for
   // keyboardHeight >= insets.bottom the padding is 0 (unchanged from mid-close), and for the last
   // insets.bottom worth of keyboard travel, containerPaddingBottom's continued shrink and this
   // padding's growth cancel out exactly, so the content holds still at the safe-area line instead
   // of dropping past it and correcting back up.
-  const rowPaddingBottom = footerFixed && footerAboveKeyboard ? Math.max(insets.bottom - keyboardHeight, 0) : insets.bottom
+  //
+  // Hosted, the bar (which already includes the safe-area inset in its own footprint) sits below
+  // this footer, so the row's bottom padding is only what pokes above the bar (a FAB) - not the
+  // inset a second time.
+  const bottomPadding = chromeHosted ? chromeOverhang : insets.bottom
+  const rowPaddingBottom = footerFixed && footerAboveKeyboard ? Math.max(bottomPadding - keyboardHeight, 0) : bottomPadding
+  // A hosted, keyboard-floating footer would otherwise float a whole bar-height above the keyboard:
+  // containerPaddingBottom above already lifts it by keyboardHeight, on top of `bottom: footprint`.
+  // The bar it was clearing is behind the keyboard by then, so the footprint has to shrink away as
+  // the keyboard rises.
+  const footerBottom = chromeHosted && footerFixed && footerAboveKeyboard ? Math.max(tabBarHeight - keyboardHeight, 0) : tabBarHeight
   // A consumer's own `style.paddingBottom` (e.g. tightening the row's vertical rhythm to match a
   // header's actionMargin) is spread after rowPaddingBottom below, so it has to be added to it
-  // rather than assigned after it — plain style-array merge would otherwise let it silently
+  // rather than assigned after it - plain style-array merge would otherwise let it silently
   // replace the safe-area clearance instead of sitting on top of it, leaving the row's real
   // content (buttons, etc.) flush against the home indicator.
   const { paddingBottom: consumerPaddingBottom, ...restStyle } = style ?? {}
@@ -91,9 +125,11 @@ export const ScrollViewFooter = ({ children, style }: ScrollViewFooterProps) =>
     // tab bar (a fixture outside this package's header/footer concepts entirely, same as
     // useScrollList's content-inset reservation) sits below this at the true screen bottom, so this
     // bar has to clear it rather than rendering flush against 0 and overlapping/hiding behind it.
-    <Animated.View onLayout={handleLayout} pointerEvents='box-none' style={[styles.footer, { bottom: tabBarHeight, paddingBottom: containerPaddingBottom }, footerStyle]}>
+    <Animated.View onLayout={handleLayout} pointerEvents='box-none' style={[styles.footer, { bottom: footerBottom, paddingBottom: containerPaddingBottom }, footerStyle]}>
       {(footerHeight ?? 0) > 0 && <BlurView blur={blur} style={StyleSheet.absoluteFill} />}
-      <View style={[styles.row, restStyle, { paddingBottom: rowPaddingBottom + (typeof consumerPaddingBottom === 'number' ? consumerPaddingBottom : 0) }]}>{children}</View>
+      <View ref={rowRef} style={[styles.row, restStyle, { paddingBottom: rowPaddingBottom + (typeof consumerPaddingBottom === 'number' ? consumerPaddingBottom : 0) }]}>
+        {children}
+      </View>
     </Animated.View>
   )
 }

package/src/ScrollViewHeader.tsx

@@ -1,6 +1,6 @@
 import { BlurView } from '@rific/auto-paper'
-import { type ReactNode, useContext } from 'react'
-import { type LayoutChangeEvent, StyleSheet, Text, View, type ViewStyle } from 'react-native'
+import { type ReactNode, useContext, useLayoutEffect, useRef } from 'react'
+import { type LayoutChangeEvent, Platform, StyleSheet, Text, View, type ViewStyle } from 'react-native'
 import { Appbar, ProgressBar, Surface, useTheme } from 'react-native-paper'
 import Animated, { useAnimatedStyle, useSharedValue } from 'react-native-reanimated'
 import { useSafeAreaInsets } from 'react-native-safe-area-context'
@@ -12,12 +12,12 @@ export type ScrollViewHeaderProps = {
   actionSize?: number
   actionStyle?: ViewStyle
   // A plain callback renders the default Appbar.BackAction (themed onSurface, sized/positioned by
-  // actionSize/iconSize below) — the common case, unchanged from before. Passing a ReactNode
+  // actionSize/iconSize below) - the common case, unchanged from before. Passing a ReactNode
   // instead skips that default entirely and renders the given element in its place, same escape
   // hatch trailingAction already gave the other corner: a caller that wants its own color, icon,
   // or component altogether (a colored IconButton, say) isn't stuck fighting Appbar.BackAction's
   // own fixed color/no-customization API to get it. backActionAccessibilityLabel/iconSize below
-  // only apply to the default-rendered case — a custom element carries its own.
+  // only apply to the default-rendered case - a custom element carries its own.
   backAction?: (() => void) | ReactNode
   backActionAccessibilityLabel?: string
   backActionFixed?: boolean
@@ -56,7 +56,7 @@ export const ScrollViewHeader = ({ actionSize = 48, actionStyle, backAction, bac
   const top = topInset ? insets.top : 0
   // Tracks "has this header's own onLayout fired yet" as a SharedValue rather than deriving it from
   // headerHeight (a plain, React-state-backed number) so the worklets below never have to list a
-  // value that flips from null to a real measured number in their dependency arrays — see the
+  // value that flips from null to a real measured number in their dependency arrays - see the
   // comment on translateStyle/blurStyle/progressStyle for why that recreation was a real crash, not
   // just a perf concern.
   const measuredShared = useSharedValue(false)
@@ -68,24 +68,45 @@ export const ScrollViewHeader = ({ actionSize = 48, actionStyle, backAction, bac
     measuredShared.value = true
     if (headerHeight !== height) setHeaderHeight(height)
   }
+  // Web only: measure synchronously before the first paint instead of waiting for onLayout.
+  // react-native-web delivers onLayout from a ResizeObserver callback plus a setTimeout measure,
+  // which routinely lands after ScrollViewProvider's two-frame "no header, assume 0" fallback -
+  // so the first frames painted headerHeight === 0: header absolute with no backdrop, list with no
+  // top padding, its first rows (sort/filter chips) drawn up inside the header until the real
+  // height arrived. A layout effect runs after the DOM is built but before the browser paints, and
+  // a state update made here is applied synchronously before that paint too, so the very first
+  // frame on screen is already the final measured layout. `headerHeight` being 0 still runs this
+  // (a header mounting after the fallback fired); a node with no layout box (an ancestor hidden
+  // via display:none) reports 0 and is left to onLayout. offsetHeight is the same integer
+  // react-native-web's onLayout reports, so that later onLayout is a no-op rather than a re-set.
+  const contentRef = useRef<View>(null)
+  useLayoutEffect(() => {
+    if (Platform.OS !== 'web' || headerHeight) return
+    const height = (contentRef.current as unknown as { offsetHeight?: unknown } | null)?.offsetHeight
+    if (typeof height !== 'number' || height <= 0) return
+    measuredShared.value = true
+    setHeaderHeight(height)
+    // Mount-only: after this, onLayout owns every later change.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
   const actionMargin = 4
   const contentMinHeight = actionSize + 2 * actionMargin
   // Same natural height the header renders at in-flow before headerHeight is ever measured (see
   // useScrollList's containerStyle comment for that same "in-flow first, absolute once measured"
-  // pattern) — used as the blur backdrop's own height for that same pre-measurement window, so it
+  // pattern) - used as the blur backdrop's own height for that same pre-measurement window, so it
   // doesn't render as a flat, unblurred box for the ~60-80ms an onLayout round trip takes on web.
   const unmeasuredHeight = top + contentMinHeight
   // Every one of these worklets reads SharedValues only (scrollPosition, snapBackHeaderShared,
-  // headerOffset, pullSearchHeightShared, headerHeightShared, measuredShared) — deliberately NOT the
+  // headerOffset, pullSearchHeightShared, headerHeightShared, measuredShared) - deliberately NOT the
   // plain `headerHeight` context value, even though it holds the same number. `headerHeight` is a
   // React-state-backed `number | null` that changes identity on every measurement (starting at null,
   // then flipping to a real pixel value within a frame of mount); putting it in a useAnimatedStyle
   // dependency array forces Reanimated to tear down and recreate the worklet the moment that happens
-  // — which crashed outright ("[Worklets] Tried to synchronously call a Remote Function") on
+  // - which crashed outright ("[Worklets] Tried to synchronously call a Remote Function") on
   // react-native-worklets 0.10.1. SharedValues never change identity, only their `.value`, so they're
   // safe to depend on and don't retrigger this. They still have to be LISTED here despite that: on
   // web, without the Reanimated Babel plugin's automatic worklet dependency capture, a SharedValue's
-  // mutations aren't picked up as reactive unless its reference appears in this array — omitting one
+  // mutations aren't picked up as reactive unless its reference appears in this array - omitting one
   // silently freezes that value's contribution to the header/blur/progress-bar's scroll tracking at
   // whatever it was when the array last changed.
   const translateStyle = useAnimatedStyle(() => {
@@ -119,7 +140,7 @@ export const ScrollViewHeader = ({ actionSize = 48, actionStyle, backAction, bac
         {headerHeight !== 0 && <BlurView blur={blur} style={[styles.blurInner, { height: headerHeight ?? unmeasuredHeight }]} />}
       </Animated.View>
       <Animated.View onLayout={handleLayout} pointerEvents='box-none' style={[headerHeight === null ? styles.headerInit : styles.header, translateStyle]}>
-        <View style={[{ paddingTop: top }, style]}>
+        <View ref={contentRef} style={[{ paddingTop: top }, style]}>
           {children ?? (
             <View style={[styles.content, { minHeight: contentMinHeight }]}>
               <View style={styles.side} />