@rific/scroll-view 0.8.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rific/scroll-view",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Blur styled scroll system for React Native. Floating headers/footers, keyboard awareness, and scroll-away chrome",
   "keywords": [
     "react-native",
@@ -92,15 +92,14 @@
   },
   "peerDependencies": {
     "@rific/auto-paper": ">=0.10.0",
-    "@rific/core": "^0.2.0",
+    "@rific/core": ">=0.1.1",
     "react": ">=19.0.0",
     "react-native": ">=0.83.0",
     "react-native-gesture-handler": ">=2.0.0 <3.0.0",
     "react-native-keyboard-controller": ">=1.0.0",
     "react-native-paper": ">=5.0.0",
     "react-native-reanimated": ">=4.0.0",
-    "react-native-safe-area-context": ">=5.0.0",
-    "react-native-worklets": "0.10.x"
+    "react-native-safe-area-context": ">=5.0.0"
   },
   "publishConfig": {
     "access": "public"

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>
@@ -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.
@@ -49,12 +49,18 @@ export const ScrollViewFooter = ({ children, style }: ScrollViewFooterProps) =>
   // 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 —
   // floating above the true screen bottom, exposing a gap of whatever sits behind (visible as a
@@ -64,6 +70,24 @@ 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
@@ -79,7 +103,17 @@ export const ScrollViewFooter = ({ children, style }: ScrollViewFooterProps) =>
   // 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
@@ -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'
@@ -68,6 +68,27 @@ 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
@@ -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} />

package/src/ScrollViewProvider.tsx

@@ -1,13 +1,20 @@
 import { useBlur } from '@rific/auto-paper'
-import { type ReactNode, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react'
+import { type ReactNode, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
 import { Dimensions, Platform } from 'react-native'
 import { useSharedValue } from 'react-native-reanimated'
 
+import { CHROME_SLACK } from './internal/chrome'
+import { ChromeRegistrar } from './internal/ChromeRegistrar'
+import { ScrollViewChromeHostContext } from './ScrollViewChromeContext'
 import { ScrollViewContext } from './ScrollViewContext'
 import { ScrollViewSettingsContext } from './ScrollViewSettingsContext'
 
 export type ScrollViewProviderProps = {
   blur?: boolean
+  // Opt out of an enclosing ScrollViewChromeProvider. A screen inside a hosted navigator joins the
+  // host by default; a nested provider that is NOT a screen (a picker or form modal — Paper's Portal
+  // can re-parent those above the clearing this provider does for its own children) has to say so.
+  chrome?: boolean
   children: ReactNode
   fixed?: boolean
   footerAboveKeyboard?: boolean
@@ -19,8 +26,14 @@ export type ScrollViewProviderProps = {
   tabBarHeight?: number
 }
 
-export const ScrollViewProvider = ({ blur, children, fixed = false, footerAboveKeyboard = false, footerFixed, headerFixed, snapBack, snapBackFooter, snapBackHeader, tabBarHeight = 0 }: ScrollViewProviderProps) => {
+export const ScrollViewProvider = ({ blur, chrome, children, fixed = false, footerAboveKeyboard = false, footerFixed, headerFixed, snapBack, snapBackFooter, snapBackHeader, tabBarHeight = 0 }: ScrollViewProviderProps) => {
   const { settings } = useContext(ScrollViewSettingsContext)
+  const enclosingHost = useContext(ScrollViewChromeHostContext)
+  const chromeHost = chrome === false ? null : enclosingHost
+  const chromeHosted = chromeHost !== null
+  const chromeFootprint = chromeHost?.footprint ?? 0
+  const chromeOverhang = chromeHost?.overhang ?? 0
+  const chromeSnapBack = chromeHost?.snapBack ?? false
   const effectiveBlur = useBlur(blur)
   const effectiveSnapBack = snapBack ?? settings.snapBack
   const effectiveSnapBackHeader = snapBackHeader ?? settings.snapBackHeader
@@ -35,30 +48,76 @@ export const ScrollViewProvider = ({ blur, children, fixed = false, footerAboveK
   const headerHeightShared = useSharedValue(0)
   const footerHeightShared = useSharedValue(0)
   const headerOffset = useSharedValue(0)
-  const footerOffset = useSharedValue(0)
+  const ownFooterOffset = useSharedValue(0)
+  const ownStackHeight = useSharedValue(0)
+  // A hosted provider writes the host's ONE offset instead of its own, so the persistent bar and this
+  // screen's footer read literally the same SharedValue. Starts unwritable when hosted: the
+  // registrar flips it once this screen actually owns the host, so a mounted-but-unfocused screen
+  // (Tabs and Stacks keep visited screens mounted) can never fight the focused one for it.
+  const footerOffset = chromeHost ? chromeHost.offset : ownFooterOffset
+  const chromeWritable = useSharedValue(!chromeHosted)
+  // Only the registrar ever writes this while hosted. If a provider stops being hosted while it stays
+  // mounted (chrome flipping to false, the host unmounting), the registrar goes away with it and
+  // would leave the last value behind — possibly false, which would silently switch off this
+  // provider's own snap-back footer for good.
+  useEffect(() => {
+    if (!chromeHosted) chromeWritable.value = true
+  }, [chromeHosted, chromeWritable])
+  const revealChrome = chromeHost?.reveal
+  // Unhosted, the hide distance is simply the footer's own height — the SAME SharedValue, not a
+  // copy, so nothing about existing snap-back behavior changes. Hosted, the whole stack (screen
+  // footer + bar + whatever pokes above the bar) has to clear the screen, and the footer's own
+  // measured height already includes the overhang as its bottom padding.
+  const stackHeightShared = chromeHosted ? ownStackHeight : footerHeightShared
   const pullSearchHeightShared = useSharedValue(0)
   const snapBackHeaderShared = useSharedValue(false)
   const snapBackFooterShared = useSharedValue(false)
   useEffect(() => {
     snapBackHeaderShared.value = effectiveSnapBackHeader ?? effectiveSnapBack
-    snapBackFooterShared.value = effectiveSnapBackFooter ?? effectiveSnapBack
-  }, [effectiveSnapBack, effectiveSnapBackFooter, effectiveSnapBackHeader, snapBackFooterShared, snapBackHeaderShared])
-  const setHeaderHeight = useCallback(
-    (h: number | null) => {
-      // react-native-screens' web shim hides an inactive screen via display:none on an
-      // ancestor instead of unmounting it, so the header's ResizeObserver-backed onLayout
-      // keeps firing while hidden and reports a spurious 0 (no layout box), then again once
-      // revealed. Never let a spurious 0 clobber a real height — only a true remount
-      // (headerHeight reset to null) should ever legitimately shrink it back to 0.
-      if (h === 0 && headerHeight) return
-      setHeaderHeightState(h)
-      headerHeightShared.value = h ?? 0
-    },
-    [headerHeight, headerHeightShared]
-  )
+    // Forced on for a hosted footer only: a bar that hides on scroll must be revealable from
+    // anywhere in a list, which the non-snap footer (visible only near the top) is not. The header's
+    // own snap-back is deliberately left to its own setting.
+    snapBackFooterShared.value = chromeHosted ? chromeSnapBack : (effectiveSnapBackFooter ?? effectiveSnapBack)
+  }, [chromeHosted, chromeSnapBack, effectiveSnapBack, effectiveSnapBackFooter, effectiveSnapBackHeader, snapBackFooterShared, snapBackHeaderShared])
+  useEffect(() => {
+    if (!chromeHosted) return
+    ownStackHeight.value = chromeFootprint + Math.max(footerHeight ?? 0, chromeOverhang) + CHROME_SLACK
+  }, [chromeFootprint, chromeHosted, chromeOverhang, footerHeight, ownStackHeight])
+  // The last height each setter below accepted, written synchronously on every call. The 0-guards
+  // read these rather than the rendered headerHeight/footerHeight, because a caller can hold a
+  // setter from before the previous call committed: on web the header's first onLayout and the
+  // fallback below routinely land ~2ms apart in the same frame, and the fallback's closure still
+  // saw headerHeight === null, so its 0 passed the guard and overwrote the real height. The header's
+  // size never changed after that, so onLayout never fired again and the list kept 0 top padding
+  // under the header for good.
+  const headerHeightRef = useRef<number | null>(null)
+  const footerHeightRef = useRef<number | null>(null)
+  const setHeaderHeight = useCallback((h: number | null) => {
+    // react-native-screens' web shim hides an inactive screen via display:none on an
+    // ancestor instead of unmounting it, so the header's ResizeObserver-backed onLayout
+    // keeps firing while hidden and reports a spurious 0 (no layout box), then again once
+    // revealed. Never let a spurious 0 clobber a real height — only a true remount
+    // (headerHeight reset to null) should ever legitimately shrink it back to 0.
+    if (h === 0 && headerHeightRef.current) return
+    headerHeightRef.current = h
+    setHeaderHeightState(h)
+  }, [])
+  // Mirrored into the SharedValue in the same commit as the state, never ahead of it. Writing it
+  // straight from onLayout let the header's translate worklet see the new height while the list
+  // still had no top padding and scrollPosition hadn't been moved to its resting -headerHeight
+  // (useScrollInit does that in its own layout effect on this commit) — so for the whole re-render
+  // (~50ms on web) the header computed translateY = -headerHeight and slid off-screen, a visible
+  // flash of a header-less screen with the list's first rows at the very top.
+  useLayoutEffect(() => {
+    headerHeightShared.value = headerHeight ?? 0
+  }, [headerHeight, headerHeightShared])
   const onListUnmount = useCallback(() => {
     listGeneration.value += 1
-  }, [listGeneration])
+    // The owning screen's list going away is the last scroll source for the shared offset: a screen
+    // that swaps its list for non-scrolling content (a spinner, an empty state) while the stack is
+    // hidden would otherwise keep the app's primary navigation hidden with nothing left to bring it back.
+    if (revealChrome && chromeWritable.value) revealChrome()
+  }, [chromeWritable, listGeneration, revealChrome])
   const onJsListUnmount = useCallback(() => {
     jsListGeneration.current += 1
   }, [])
@@ -97,15 +156,29 @@ export const ScrollViewProvider = ({ blur, children, fixed = false, footerAboveK
       // still on screen (e.g. a wizard cycling through several <ScrollViewFooter> instances).
       // Never let that clobber a known height — only an explicit null (genuinely no footer
       // mounted) may reset it.
-      if (h === 0 && footerHeight) return
+      if (h === 0 && footerHeightRef.current) return
+      footerHeightRef.current = h
       setFooterHeightState(h)
       footerHeightShared.value = h ?? 0
     },
-    [footerHeight, footerHeightShared]
+    [footerHeightShared]
   )
   const scrollHeight = useMemo(() => Dimensions.get('window').height - (headerHeight ?? 0) - (footerHeight ?? 0), [headerHeight, footerHeight])
   const effectiveHeaderFixed = fixed || (headerFixed ?? settings.headerFixed)
   const effectiveFooterFixed = fixed || (footerFixed ?? settings.footerFixed)
-  const value = useMemo(() => ({ blur: effectiveBlur, footerAboveKeyboard, footerHeight, footerHeightShared, footerFixed: effectiveFooterFixed, footerOffset, headerHeight, headerHeightShared, headerFixed: effectiveHeaderFixed, headerOffset, jsListGeneration, listGeneration, onJsListUnmount, onListUnmount, progress, pullSearchHeightShared, progressing, scrollHeight, scrollPosition, setFooterHeight, setHeaderHeight, setProgress, setProgressing, snapBackFooterShared, snapBackHeaderShared, tabBarHeight }), [effectiveBlur, footerAboveKeyboard, effectiveFooterFixed, effectiveHeaderFixed, footerHeight, footerHeightShared, footerOffset, headerHeight, headerHeightShared, headerOffset, jsListGeneration, listGeneration, onJsListUnmount, onListUnmount, progress, pullSearchHeightShared, progressing, scrollHeight, scrollPosition, setFooterHeight, setHeaderHeight, snapBackFooterShared, snapBackHeaderShared, tabBarHeight])
-  return <ScrollViewContext.Provider value={value}>{children}</ScrollViewContext.Provider>
+  // Hosted, the persistent bar's footprint replaces the consumer's static tabBarHeight guess: it is
+  // the same "reserve this much at the bottom" number, just now known exactly.
+  const effectiveTabBarHeight = chromeHosted ? chromeFootprint : tabBarHeight
+  const value = useMemo(
+    () => ({ blur: effectiveBlur, chromeHosted, chromeOverhang, chromeWritable, footerAboveKeyboard, footerHeight, footerHeightShared, footerFixed: effectiveFooterFixed, footerOffset, headerHeight, headerHeightShared, headerFixed: effectiveHeaderFixed, headerOffset, jsListGeneration, listGeneration, onJsListUnmount, onListUnmount, progress, pullSearchHeightShared, progressing, scrollHeight, scrollPosition, setFooterHeight, setHeaderHeight, setProgress, setProgressing, snapBackFooterShared, snapBackHeaderShared, stackHeightShared, tabBarHeight: effectiveTabBarHeight }),
+    [effectiveBlur, chromeHosted, chromeOverhang, chromeWritable, footerAboveKeyboard, effectiveFooterFixed, effectiveHeaderFixed, footerHeight, footerHeightShared, footerOffset, headerHeight, headerHeightShared, headerOffset, jsListGeneration, listGeneration, onJsListUnmount, onListUnmount, progress, pullSearchHeightShared, progressing, scrollHeight, scrollPosition, setFooterHeight, setHeaderHeight, snapBackFooterShared, snapBackHeaderShared, stackHeightShared, effectiveTabBarHeight]
+  )
+  return (
+    <ScrollViewContext.Provider value={value}>
+      <ScrollViewChromeHostContext.Provider value={null}>
+        {children}
+        {chromeHost ? <ChromeRegistrar footerFixed={effectiveFooterFixed} host={chromeHost} writable={chromeWritable} /> : null}
+      </ScrollViewChromeHostContext.Provider>
+    </ScrollViewContext.Provider>
+  )
 }

package/src/index.ts

@@ -8,6 +8,8 @@ export { PullSearch } from './PullSearch'
 export { scrollViewActions, scrollViewReducer } from './redux/scrollViewSlice'
 export type { ScrollViewProps } from './ScrollView'
 export { ScrollView } from './ScrollView'
+export type { ScrollViewChromeProviderProps } from './ScrollViewChromeProvider'
+export { ScrollViewChromeProvider } from './ScrollViewChromeProvider'
 export type { ScrollViewContextType } from './ScrollViewContext'
 export { ScrollViewContext } from './ScrollViewContext'
 export type { ScrollViewFooterProps } from './ScrollViewFooter'
@@ -24,4 +26,5 @@ export type { SectionListProps } from './SectionList'
 export { SectionList } from './SectionList'
 export { useKeyboardInset } from './useKeyboardInset'
 export { useScrollView } from './useScrollView'
+export { useScrollViewChromePin, useScrollViewChromeReveal, useScrollViewChromeStyle } from './useScrollViewChrome'
 export { useScrollViewSettings } from './useScrollViewSettings'

package/src/internal/ChromeRegistrar.tsx

@@ -0,0 +1,37 @@
+import { useEffect, useId } from 'react'
+import type { SharedValue } from 'react-native-reanimated'
+
+import type { ScrollViewChromeHost } from '../ScrollViewChromeContext'
+
+type ChromeRegistrarProps = {
+  footerFixed: boolean
+  host: ScrollViewChromeHost
+  writable: SharedValue<boolean>
+}
+
+// Rendered by a hosted ScrollViewProvider as a sibling of its children. It is a component rather
+// than a hook call inside the provider because host.useIsActive is itself a hook, and a provider
+// only sometimes has a host — mounting this only when hosted keeps the hook order stable.
+//
+// While its screen is active it claims the host; the provider's scroll handlers only write the
+// shared offset (`writable`) while this provider is the claim's owner and nothing has pinned the
+// bar. Footer Lock turning on while the stack is hidden reveals it, since the handlers stop writing
+// the moment it does and nothing else would ever bring it back.
+export const ChromeRegistrar = ({ footerFixed, host, writable }: ChromeRegistrarProps) => {
+  const id = useId()
+  const active = host.useIsActive()
+  const { activeId, claim, pinned, release, reveal } = host
+  useEffect(() => {
+    if (!active) return undefined
+    claim(id)
+    return () => release(id)
+  }, [active, claim, id, release])
+  const owner = activeId === id
+  useEffect(() => {
+    writable.value = owner && !pinned
+  }, [owner, pinned, writable])
+  useEffect(() => {
+    if (owner && footerFixed) reveal()
+  }, [footerFixed, owner, reveal])
+  return null
+}

package/src/internal/chrome.ts

@@ -0,0 +1,19 @@
+import { usesContentInset } from './insetMode'
+
+// Extra distance past the geometrically-required hide distance, so a soft shadow (a FAB's) that
+// bleeds past the bar's box doesn't leave a sliver at the screen edge once fully hidden.
+export const CHROME_SLACK = 2
+
+// How far a list can actually be scrolled from its resting position. In inset mode the resting
+// position sits at -headerHeight and raw contentOffset spans [-headerHeight, maxScroll]; in padding
+// mode the header is part of the content and raw spans [0, maxScroll].
+export const chromeTravel = (maxScroll: number, headerHeight: number) => {
+  'worklet'
+  return usesContentInset ? maxScroll + headerHeight : maxScroll
+}
+
+// Where a half-hidden stack should come to rest once scrolling stops: whichever end is nearer.
+export const chromeSettleTarget = (offset: number, stackHeight: number) => {
+  'worklet'
+  return offset > stackHeight / 2 ? stackHeight : 0
+}